164 lines
4.2 KiB
Markdown
164 lines
4.2 KiB
Markdown
# HTTP 调试与文档规范
|
|
|
|
本目录下的 `.http` 文件同时承担接口调试和接口文档职责，也要保证 AIAgent 能稳定读取
|
|
|
|
## 目录分工
|
|
|
|
### `.http`
|
|
|
|
`.http` 只描述接口级信息：
|
|
|
|
1. 接口中文名
|
|
2. 权限要求
|
|
3. 前置条件
|
|
4. 请求参数对应的对象说明
|
|
5. 返回参数对应的对象说明
|
|
|
|
`.http` 不重复展开对象字段明细，复杂字段、嵌套结构、枚举值统一写到 `./object` 下
|
|
|
|
### `./object`
|
|
|
|
`./object` 只描述对象级信息：
|
|
|
|
1. 字段名
|
|
2. 字段类型
|
|
3. 字段说明
|
|
4. 枚举值及含义
|
|
|
|
所有模块都可能复用的通用对象必须写在 `./object/common.md`
|
|
|
|
按业务领域拆分对象说明文件，例如：
|
|
|
|
1. `./object/common.md`
|
|
2. `./object/user.md`
|
|
3. `./object/role.md`
|
|
4. `./object/permission.md`
|
|
|
|
不要把同一个对象的字段说明散落到多个文件里
|
|
|
|
## 全局约定
|
|
|
|
### 返回包装
|
|
|
|
除使用 `IgnoreGlobalReturn` 跳过全局包装的方法外，接口默认都会经过
|
|
[GlobalReturnHandler](E:/IDEAProject/timi-spring/src/main/java/com/imyeyu/spring/util/GlobalReturnHandler.java)
|
|
统一包装返回
|
|
|
|
因此 `.http` 里的 `返回参数` 默认只描述业务 `data` 对象，不再重复赘述全局包装结构
|
|
|
|
全局返回包装、通用成功码、错误信息、常见分页壳子等内容统一维护在 `./object/common.md`
|
|
|
|
如果接口使用
|
|
[IgnoreGlobalReturn](E:/IDEAProject/timi-spring/src/main/java/com/imyeyu/spring/annotation/IgnoreGlobalReturn.java)
|
|
跳过全局包装，必须在对应接口的 `前置条件` 或补充说明里明确写出“该接口不走全局返回包装”
|
|
|
|
### 文档真实性
|
|
|
|
1. 文档只记录服务端真实行为
|
|
2. 不写猜测
|
|
3. 不写“看代码”
|
|
4. 接口改了就同步更新 `.http` 和 `./object`
|
|
|
|
### 变量复用
|
|
|
|
能复用的变量统一放在文件顶部，例如 `@user_token`、`@userId`
|
|
|
|
## `.http` 模板
|
|
|
|
每个接口块固定使用下面格式，不要擅自增删字段名：
|
|
|
|
```http
|
|
### <接口中文名>
|
|
### 权限：
|
|
### 前置条件：
|
|
### 请求参数：
|
|
### 返回参数：
|
|
|
|
POST {{baseUrl}}/path
|
|
Content-Type: application/json
|
|
Token: {{user_token}}
|
|
|
|
{}
|
|
```
|
|
|
|
## `.http` 填写要求
|
|
|
|
### 接口中文名
|
|
|
|
直接写接口用途，别写成控制器方法名
|
|
|
|
### 权限
|
|
|
|
1. 优先直接翻译控制器上的真实注解
|
|
2. 同时存在角色和权限时一起写，例如 `需要 ADMIN 角色 + USER_UPDATE 权限`
|
|
3. 只有 Token 要求时写 `需要有效 Token`
|
|
4. 无需登录时直接写 `无需登录`
|
|
|
|
### 前置条件
|
|
|
|
这里只写接口调用前必须知道的约束，例如：
|
|
|
|
1. 需要先登录并回填 `user_token`
|
|
2. 需要先创建用户再传入 `userId`
|
|
3. 重复调用可能因为唯一约束失败
|
|
4. 接口当前实现为空
|
|
5. 该接口不走全局返回包装
|
|
|
|
没有额外限制时写 `无`
|
|
|
|
### 请求参数
|
|
|
|
只写请求对象名和对象说明文件，不在 `.http` 内展开字段
|
|
|
|
推荐格式：
|
|
|
|
1. `无`
|
|
2. `UserCreateRequest，详见 ./object/user.md`
|
|
3. `Page<UserQuery>，详见 ./object/common.md 和 ./object/user.md`
|
|
|
|
### 返回参数
|
|
|
|
只写业务返回对象名和对象说明文件，不在 `.http` 内展开字段
|
|
|
|
推荐格式：
|
|
|
|
1. `无`
|
|
2. `User，详见 ./object/user.md`
|
|
3. `PageResult<User>，详见 ./object/common.md 和 ./object/user.md`
|
|
4. `二进制数据流，该接口不走全局返回包装`
|
|
|
|
## `./object` 编写要求
|
|
|
|
对象说明统一使用 Markdown 表格，推荐结构如下
|
|
|
|
```md
|
|
## User
|
|
|
|
| 字段 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| name | String | 登录名，系统内唯一 |
|
|
|
|
## RoleCode
|
|
|
|
| 枚举 | 说明 |
|
|
|---|---|
|
|
| SYSTEM | 系统 |
|
|
| ADMIN | 管理员 |
|
|
```
|
|
|
|
### 对象说明规则
|
|
|
|
1. 一个对象一个标题，标题名必须和 `.http` 里引用的对象名一致
|
|
2. 字段说明只写真实存在且调用方需要关心的内容
|
|
3. 枚举单独列出，不要把枚举值混进普通字段表
|
|
4. 嵌套对象、列表元素对象也要有独立标题
|
|
5. 通用壳子对象统一写在 `./object/common.md`
|
|
|
|
## 维护要求
|
|
|
|
1. 一个控制器通常对应一个 `.http` 文件
|
|
2. 新增接口时，同步补齐对应 `.http`
|
|
3. 新增或修改对象字段时，同步更新对应 `./object/*.md`
|
|
4. 注释语言统一用中文
|
|
5. 示例请求优先保证可调试，其次才是看起来完整
|