最佳实践

汇总API接口设计的一些常见的最佳实践

安全与升级

1.版本管理

无论是小程序，还是app，还是Web网站，都需要版本升级，而提前设计好版本，可以避免因为升级导致旧的服务无法正常工作。
需要要保证在升级的时候，新旧版本的服务都能正常提供服务。

2.授权认证

大部分接口都是需要授权认证的，因此要对接口的授权认证进行判断，这样可以过滤掉大部分的非法访问。
可以通过token校验实现

3.签名校验

• sign生成算法
• 接口有效时间限制，可以根据timestamp判断

接口设计规范

4.统一返回数据格式

• 统一返回正常值
• 统一返回错误/异常

5.统一设计分页

统一分页返回
– 减少资源的返回
– 减少服务器的开销

6.幂等设计

防重和幂等设计其实是有区别的，防重主要为了避免产生重复数据，把重复请求拦截下来即可。而幂等设计除了拦截已经处理的请求，还要求每次相同的请求都返回一样的效果。

• token令牌
• 分布式锁

7.接口限流

限流策略、以及粒度

• 流量网关限流
• 业务网关限流

8.参数校验

9.批量接口，需要限制限制请求记录条数

接口需要做条数判断

10.数据脱敏

• 请求：部分敏感接口，可以对接口请求数据进行加密
  对用户比较重要的数据，如银行卡号、身份证号、手机号、保险号，等数据，请求前可以用base64进行加密。
• 返回：数据脱敏
  对返回结果包含敏感数据的接口，数据进行脱敏：银行卡号、身份证号、手机号等。如：
  用户手机号：139****7895
  身份证号：****19****3345353****

11.请求日志 API Log设计

• 可以在网关层做请求日志的收集，记录：traceId,requestId,request parameter,request body ,response result,error code,error message ..等信息
• 做成可视化，提供一个UI显示和查询工具，可以给内部和外部使用

12.异步处理

耗时接口可以改为异步处理
常见的方式是可以发送MQ消息，异步化处理。

13.压力测试

可以用JMeter等工具做压力测试

14.完整的接口文档

• 内部：swagger等开源方案
• 外部：自建、sphinx(python)、gitbook等

（完）