# 关于框架的设计说明

## 目录说明：

##### `/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 - 表示服务端出问题。
- 将错误码控制在适当的数目内，客户端比较容易处理和判断，开发也比较容易进行错误码映射

## 项目的运行

```shell script
# 项目目录下执行
# 编译
make
# 查看版本
./cmd/<执行文件> version
# 启动api服务
./cmd/<执行文件> run --profile=./configs/test.yml
```