TimiServerAPI/http

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 统一包装返回

因此 .http 里的 返回参数 默认只描述业务 data 对象，不再重复赘述全局包装结构

全局返回包装、通用成功码、错误信息、常见分页壳子等内容统一维护在 ./object/common.md

如果接口使用 IgnoreGlobalReturn 跳过全局包装，必须在对应接口的 前置条件 或补充说明里明确写出“该接口不走全局返回包装”

文档真实性

1. 文档只记录服务端真实行为
2. 不写猜测
3. 不写“看代码”
4. 接口改了就同步更新 .http 和 ./object

变量复用

能复用的变量统一放在文件顶部，例如 @user_token、@userId

.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 表格，推荐结构如下

## User

| 字段 | 类型 | 说明 |
|---|---|---|
| name | String | 登录名，系统内唯一 |

## RoleCode

| 枚举 | 说明 |
|---|---|
| SYSTEM | 系统 |
| ADMIN | 管理员 |

对象说明规则

1. 一个对象一个标题，标题名必须和 .http 里引用的对象名一致
2. 字段说明只写真实存在且调用方需要关心的内容
3. 枚举单独列出，不要把枚举值混进普通字段表
4. 嵌套对象、列表元素对象也要有独立标题
5. 通用壳子对象统一写在 ./object/common.md

维护要求

1. 一个控制器通常对应一个 .http 文件
2. 新增接口时，同步补齐对应 .http
3. 新增或修改对象字段时，同步更新对应 ./object/*.md
4. 注释语言统一用中文
5. 示例请求优先保证可调试，其次才是看起来完整