模板-接口设计.md 4.1 KB

接口设计说明书模板

来源:05.开发部-模板文档-接口设计说明书.docx,已转 Markdown,示例由 XML 改为 JSON(老系统对接仍可用 XML)。

一、文件要求

  • 文件名:接口设计说明书-{项目}-v{版本}.md
  • 存放:docs/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——旧模板没强调这条,实际项目里吃过亏。