framework.md 4.5 KB
关于框架的设计说明
目录说明：
/cmd
本项目的主干。不要在这个目录中放置太多代码。如果你认为代码可以导入并在其他项目中使用，那么它应该位于 /pkg
目录中。如果代码不是可重用的，或者你不希望其他人重用它，请将该代码放到 /internal
目录中。你会惊讶于别人会怎么做，所以要明确你的意图!
通常有一个小的 main 函数，从 /internal 和 /pkg 目录导入和调用代码，除此之外没有别的东西。
/configs
配置文件相关。
/doc
设计和用户文档。
/internal
私有应用程序和库代码。
应用程序共享的代码可以放在 /internal/pkg 目录下(例如 /internal/pkg/myprivlib)。
/pkg
外部应用程序可以使用的库代码。
/scripts
执行各种构建、安装、分析等操作的脚本。 这些脚本可以配合根级别的 Makefile 使用，以保持 Makefile 简单明了。
/test
额外的外部测试应用程序和测试数据。
/tools
这个项目的支持工具。这些工具可以从 /pkg 和 /internal 目录导入代码。
代码分层
业务代码主要分adapter层、application层、domain层、infra层
上层可以调用任意下层
adapter层主要作为接入层，可以是http接口也可以使用grpc
application层主要是业务逻辑
domain层主要用于长期开发过程的业务抽象，可以使用infra层，开发中应及时重构application层去合理复用domian层
infra层主要是dao层、相关调用服务封装、存储数据定义
code的定义
目前有的项目是采用固定返回200 http status code的方式，有其合理性。比如，HTTP Code 通常代表 HTTP Transport 层的状态信息。当我们收到 HTTP 请求，并返回时，HTTP Transport 层是成功的，所以从这个层面上来看，HTTP Status 固定为 200 也是合理的。 但是这个方式的缺点也很明显：对于每一次请求，我们都要去解析 HTTP Body，从中解析出错误码和错误信息。实际上，大部分情况下，我们对于成功的请求，要么直接转发，要么直接解析到某个结构体中；对于失败的请求，我们也希望能够更直接地感知到请求失败，特别是网关、监控等。
因此推荐使用http status code + 自定义业务码，业务码需要有一定规则，可以通过业务码判断出是哪类错误。 请求出错时，可以通过http status code直接感知到请求出错。 需要在请求出错时，返回详细的信息，通常包括 3 类信息：业务 Code 码、错误信息和参考文档链接（可选）。 返回的错误信息，需要是可以直接展示给用户的安全信息，也就是说不能包含敏感信息；同时也要有内部更详细的错误信息，方便 debug。 返回的数据格式应该是固定的、规范的。 错误信息要保持简洁，并且提供有用的信息。
自定义业务码说明：100101
- 10: 服务。
- 01: 某个服务下的某个模块。
- 01: 模块下的错误码序号，每个模块可以注册 100 个错误。
通过100101可以知道这个错误是什么服务什么模块下的错误。 如果每个模块的错误码超过 100 个，说明这个模块可能太大了，建议拆分；也可能是错误码设计得不合理，共享性差，需要重新设计。
可以看到 HTTP Code 有很多种，如果每个 Code 都做错误映射，会面临很多问题，在某些情况下不太好判断错误属于哪种http status code，到最后很可能会导致错误或者http status code不匹配，变成一种形式。而且，客户端也难以应对这么多的 HTTP 错误码。 所以，http status code不要太多，基本上只需要这 6 个 HTTP Code:
- 200 - 表示请求成功执行。
- 400 - 表示客户端出问题。
- 401 - 表示认证失败。
- 403 - 表示授权失败。
- 404 - 表示资源找不到，这里的资源可以是 URL 或者 RESTful 资源。
- 500 - 表示服务端出问题。
将错误码控制在适当的数目内，客户端比较容易处理和判断，开发也比较容易进行错误码映射
项目的运行
# 项目目录下执行
# 编译
make
# 查看版本
./cmd/<执行文件> version
# 启动api服务
./cmd/<执行文件> run --profile=./configs/test.yml