# 接口设计说明书模板 > 来源:`05.开发部-模板文档-接口设计说明书.docx`,已转 Markdown,示例由 XML 改为 JSON(老系统对接仍可用 XML)。 ## 一、文件要求 - 文件名:`接口设计说明书-{项目}-v{版本}.md` - 存放:`docs/02-设计/` - 一个接口一节,编号唯一,可被需求文档反向引用 ## 二、文档骨架 ```markdown # {项目} 接口设计说明书 ## 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 错误码表 ``` ## 三、单个接口的格式 ```markdown ### 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) | | #### 返回示例 ```json { "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**——旧模板没强调这条,实际项目里吃过亏。