来源:
05.开发部-模板文档-接口设计说明书.docx,已转 Markdown,示例由 XML 改为 JSON(老系统对接仍可用 XML)。
接口设计说明书-{项目}-v{版本}.mddocs/02-设计/# {项目} 接口设计说明书
## 0 文档信息
| 项 | 内容 |
|---|---|
| 版本 | v1.0 |
| 编写 | |
| 复核 | |
| 关联需求 | 需求说明书 v1.0 |
## 1 接口概述
### 1.1 系统概述
业务功能、技术架构、OS 与版本、应用服务器、数据库版本、组件版本
### 1.2 接口技术
通信方式(HTTP/WebService/MQ)、数据封装格式(JSON/XML)、鉴权方式
### 1.3 字符编码
UTF-8(老系统可能用 GBK,必须写明)
### 1.4 接口列表
| 编号 | 接口名称 | 方法 | 功能描述 | 调用方 | 提供方 |
## 2 接口详述
### 2.1 {接口名称}({编号})
(按第三节格式逐个展开)
## 3 附录
### 3.1 接口编号规则
### 3.2 基本数据类型
### 3.3 错误码表
### I-001 用户信息查询
**请求地址**:`POST /api/v1/user/query`
**通信方式**:HTTP + JSON
**鉴权**:请求头 `Authorization: Bearer {token}`
**超时**:连接 3s,读取 10s
**幂等性**:查询类,天然幂等
**频次限制**:单账号 60 次/分钟
#### 请求参数
| 参数名 | 代码 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| 用户ID | userId | string(32) | 否 | 与手机号二选一 |
| 手机号 | mobile | string(11) | 否 | 与用户ID二选一 |
| 是否含已禁用 | includeDisabled | boolean | 否 | 默认 false |
#### 请求示例
```json
{
"userId": "U20261112001",
"includeDisabled": false
}
| 参数名 | 代码 | 类型 | 说明 |
|---|---|---|---|
| 结果码 | code | int | 0 成功,非 0 见错误码表 |
| 描述 | msg | string(100) | 失败时返回原因 |
| 用户信息 | data | object | 见下表 |
| 用户状态 | data.status | int | 1 启用 / 0 禁用 |
| 所属组织 | data.orgId | string(32) |
{
"code": 0,
"msg": "success",
"data": { "userId": "U20261112001", "status": 1, "orgId": "ORG-001" }
}
| 错误码 | 含义 | 调用方处理 |
|---|---|---|
| 40001 | 参数缺失 | 修正后重试 |
| 40002 | 用户不存在 | 提示,不重试 |
| 50001 | 下游超时 | 指数退避重试 3 次 |
| 50002 | 下游异常 | 记录并告警,不重试 |
## 四、必填项检查
| 项 | 为什么必须写 |
|---|---|
| 鉴权方式 | 不写对方不知道怎么调 |
| 超时时间 | 不写会互相等死 |
| 幂等性 | 决定对方能不能重试 |
| 频次限制 | 决定对方要不要排队 |
| 错误码全表 | 只写 0 和 1,失败时没法定位 |
| 字段类型与长度 | 不写对方按 int 建表,上线就溢出 |
**最常见的三个坑**:
1. **只写成功路径**,没有错误码和异常说明 → 联调时全靠猜
2. **字段只有中文名没有代码** → 大小写、下划线对不上
3. **没写幂等性** → 对方超时重试,产生重复数据
## 五、编号规则
沿用旧模板的 8 位编号:
0702 0001 └┬┘ └─┬─┘ │ └── 系统内接口序号(项目组维护) └──────── 系统业务范围 + 系统序号(接口管理员统一分配) ```
| 系统码 | 说明 |
|---|---|
| 0702 | 打印 |
| 0703 | 短信 |
| 0704 | 用户管理 |
新项目按公司接口管理员分配的前缀来,不要自行编造。
| 类型 | 说明 |
|---|---|
| int(n) | 整数,n 为位数,不定长可省略 |
| float(n,m) | 浮点,n 总位数,m 小数位 |
| char | 单字符 |
| string(n) | 字符串,n 为字符数 |
| object | 对象 |
| datetime | yyyy-MM-dd HH:mm:ss,时区须注明 |
| decimal(n,m) | 金额专用,禁止用 float |
金额一律 decimal,禁止 float/double——旧模板没强调这条,实际项目里吃过亏。