【最佳实践】 - 接口规范

概述

本文介绍 接口规范 最佳实战.

一、基础规范

规范点	说明	推荐方式	等级
文档唯一性	文档出处来源（人员和设备）必须统一，建议文档服务器，统一发布人。		重要
接口环境	要明确给出各个环境的调用地址。		重要
接口文档版本	必须有版本编号，名称+版本，版本必须能区分历史版本。 Pegasus facade版本号不能使用SNAPSHOT版本结尾。		非常重要
接口兼容	必须说明是否兼容历史版本，如不兼容，必须特别说明或提供平滑迁移方案。	兼容	非常重要
安全设计	必须符合安全部门要求规范。对外接口必须已 HTTPS 请求提供，需要使用国家授权的发证机构进行证书签发， 用来进行签名和重要信息加密。严禁私发证书，严禁商户私钥证书落地（必须商户通过浏览器申请后自行导出）		非常重要
接口调用范围	明确接口是给谁调用的（IP白名单），可接受的范围区间（同交换机、同机房、跨专线和机房等）。		重要
接口设计	接口尽量建议一个接口做一件事。 不建议将一些关键字段开放参数来传递表明接口不同业务（特别是组合字段）。 不建议使用类型的默认值作为字段的业务说明。 - 字符类型空或null。 - 数字类型的0。		非常重要
支持语言	Java、Python、PHP等。		重要
同步接口协议	对外（https）对内（http/https/RPC）。		重要
异步接口协议	json 或 Java序列化。 json采用小写+“_”来表示key命名，最好指定解析json的包和版本。		非常重要
接口编码	UTF-8、GBK、或其他特殊指定编码。	UTF-8	非常重要
接口响应时间（MS）	95%以上的平均响应时间为多少毫秒，最大响应时间为多少毫秒，平均响应时间为多少毫秒。		非常重要
接口最大吞吐量（TPS）	接口每秒请求事务数。		重要
接口超时时间	内部100MS之内，外部5秒之内，根据实际情况调整。		非常重要
接口重试次数	接口允许在指定超时时间内重试次数。 一般重试次数为接口平均响应时间3-5次（具体按业务情况）。		非常重要
接口限流策略	http协议必须提供限制失败影响状态码和响应页面，RPC必须指定返回错误异常类型。		重要
接口输入参数限制	必须指明那些参数需要客户端验证（客户端不验证的，一般是服务端验证经常变更的），哪些服务端会验证。 输入参数中应包含接口请求时间和全局流水号。 字符、数字，最大最小建议使用闭区间，最大输入字段以业务为准（切记不要全量开放数据库字段限制，以后扩展就非常困难）。 日期明确指定格式。 枚举必须提供字典表。		非常重要
接口返回参数限制	返回结果必须有终态说明（提供逻辑表，表明业务F、S），不能有模糊区间。 枚举必须提供字典表。 字符、数字，必须提供大小，建议使用闭区间。 日期明确指定格式。 RPC对象返回结果代码中严重使用extends对象，防止变动影响范围无法控制。 返回值中尽量不要返回可选字段（可有可无的）。 Mock返回必须要特殊注明。		非常重要
代码示例	接口调用方必须提供代码示例。 http可以采用swagger。 RPC需要提供主流client语言支持，如java，其他语言如不支持，需要提供解决方法。		非常重要

二、文档示例

接口名称：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

同步接口输入

名称	字段	类型	说明	客户端必须验证
用户名	username	String	用户名	是

同步接口返回

名称	字段	类型	说明
名称	Result	User	用户信息

异步队列名称

XXX

异步返回

JSON

返回逻辑表

字段逻辑	终态	说明
是否线上	Y	Y: 是; N: 否

字典表

枚举列表	值	说明
commit	0	提交
registed	1	注册
running	2	上线
delete	3	删除

示例代码

Json：示例

其他：代码示例（各种语言示例）

客户端SDK提供示例

---

最佳实践

1. 客户端验证（基本验证，防止服务端过多通讯）
2. 服务端验证（验证顺序要考虑：如开户接口，应该先验证基础参数，非空字段长度等；再验证数据库访问，如商户是否存在；最后验证外面请求，实名认证等。避免非法数据对数据库和远程调用造成开销）
3. 事务标签，@Transactional下的代码应该行数最小，不包含数据准备、逻辑计算，尽量避免远程调用，慢查询。（将数据准备、逻辑计算排除在事务标签之外，外部请求更不能放在事务中，考虑二阶段事务和事务补偿）
4. 慢SQL（解决方式：正确SQL写法、执行计划、索引、缓存、冗余字段、表分区、归档、分库分表等等）
5. 严禁循环内SQL执行，连接池尽量还是要设置的少并且合理，一般5-15个左右，就能承载300-400个并发的，再上去宁愿加实例，也不太建议另外开大连接换取高并发，大连接在请求有尖值的时候，大量回收不可预估。

666 彩蛋

刚开始写博客, 希望大家支持, 如果有没疑问或不清楚的地方可以留言噢!

下周再见~