| 规范点 | 说明 | 推荐方式 | 等级 |
|---|---|---|---|
| 文档唯一性 | 文档出处来源（人员和设备）必须统一，建议文档服务器，统一发布人。 | 重要 | |
| 接口环境 | 要明确给出各个环境的调用地址。 | 重要 | |
| 接口文档版本 | 必须有版本编号，名称+版本，版本必须能区分历史版本。 RPC facade版本号不能使用SNAPSHOT版本结尾。 |
非常重要 | |
| 接口兼容 | 必须说明是否兼容历史版本，如不兼容，必须特别说明或提供平滑迁移方案。 | 兼容 | 非常重要 |
| 安全设计 | 必须符合安全部门要求规范。对外接口必须已HTTPS请求提供，需要使用国家授权的发证机构进行证书签发，用来进行签名和重要信息加密。严禁私发证书，严禁商户私钥证书落地（必须商户通过浏览器申请后自行导出） | 非常重要 | |
| 接口调用范围 | 明确接口是给谁调用的（IP白名单），可接受的范围区间（同交换机、同机房、跨专线和机房等）。 | 重要 | |
| 接口设计 | 接口尽量建议一个接口做一件事。 不建议将一些关键字段开放参数来传递表明接口不同业务（特别是组合字段）。 不建议使用类型的默认值作为字段的业务说明。
|
非常重要 | |
| 接口接入支持开发语言 | Java、Python、PHP等。 |
|
重要 |
| 同步接口协议 | 对外（https）对内（http/https/RPC）。 | 重要 | |
| 异步接口协议 | json 或 Java序列化。 json采用小写+“_”来表示key命名，最好指定解析json的包和版本。 |
json fastjson |
非常重要 |
| 接口编码 | UTF-8、GBK、或其他特殊指定编码。 | UTF-8 | 非常重要 |
| 接口响应时间（MS） | 95%以上的平均响应时间为多少毫秒，最大响应时间为多少毫秒，平均响应时间为多少毫秒。 | 重要 | |
| 接口最大吞吐量（TPS） | 接口每秒请求事务数。 | 重要 | |
| 接口超时时间 | 内部100MS之内，外部5秒之内，根据实际情况调整。 | 非常重要 | |
| 接口重试次数 | 接口允许在指定超时时间内重试次数。 一般重试次数为接口平均响应时间3-5次（具体按业务情况）。 |
非常重要 | |
| 接口限流策略 | http协议必须提供限制失败影响状态码和响应页面，RPC必须指定返回错误异常类型。 | 重要 | |
| 接口输入参数限制 | 必须指明那些参数需要客户端验证（客户端不验证的，一般是服务端验证经常变更的），哪些服务端会验证。 输入参数中应包含接口请求时间和全局流水号。 字符、数字，最大最小建议使用闭区间，最大输入字段以业务为准（切记不要全量开放数据库字段限制，以后扩展就非常困难）。 日期明确指定格式。 枚举必须提供字典表。 |
非常重要 | |
| 接口返回参数限制 | 返回结果必须有终态说明（提供逻辑表，表明业务F、S），不能有模糊区间。 枚举必须提供字典表。 字符、数字，必须提供大小，建议使用闭区间。 日期明确指定格式。 RPC对象返回结果代码中严重使用extends对象，防止变动影响范围无法控制。 返回值中尽量不要返回可选字段（可有可无的）。 Mock返回必须要特殊注明。 |
非常重要 | |
| 代码示例 | 接口调用方必须提供代码示例。 http可以采用swagger。 RPC需要提供主流client语言支持，如java，其他语言如不支持，需要提供解决方法。 |
非常重要 |
3. 文档示例
接口名称：XXX名称
版本：V1.0.1
接口用途：XXX
调用场景：支付XXX
是否申请白名单：是/否
签名方式：SHA256
协议：HTTP/HTTPS/RPC
支持接入语言：Java
编码：UTF-8
吞吐量：300 TPS
平均超时时间：50MS
建议重试次数：50MS/1次，3次
限流策略：300 TPS以上，强制返回XXXException，需要客户端代码处理。或 HTTP 状态码6XX，限流返回页面http://XXX，文字说明。
特殊说明：XXX
同步接口输入
| 名称 | 字段 | 类型 | 说明 | 客户端必须验证 |
|---|---|---|---|---|
同步接口返回
| 名称 | 字段 | 类型 | 说明 |
|---|---|---|---|
异步队列名称
XXX
异步返回
JSON
返回逻辑表
| 字段逻辑 | 终态 | 说明 |
|---|---|---|
字典表
| 枚举列表 | 值 | 说明 |
|---|---|---|
示例代码
Json：示例
其他：代码示例（各种语言示例）
客户端SDK提供示例。
4. 接口开发注意点
2、 服务端验证（验证顺序要考虑：如开户接口，应该先验证基础参数，非空字段长度等；再验证数据库访问，如商户是否存在；最后验证外面请求，实名认证等。避免非法数据对数据库和远程调用造成开销）
3、 事务标签，@Transactional下的代码应该行数最小，不包含数据准备、逻辑计算，尽量避免远程调用，慢查询。（将数据准备、逻辑计算排除在事务标签之外，外部请求更不能放在事务中，考虑二阶段事务和事务补偿）
4、 慢SQL（解决方式：正确SQL写法、执行计划 、索引、缓存、冗余字段、表分区、归档、分库分表等等）
5、 严禁循环内SQL执行， 连接池尽量还是要设置的少并且合理，一般5-15个左右，就能承载300-400个并发的，再上去宁愿加实例，也不太建议另外开大连接换取高并发，大连接在请求有尖值的时候，大量回收不可预估。
