Controller接口设计规范

Controller接口设计规范

1. 签名
接口请求方将请求参数 + 时间戳 + 密钥拼接成一个字符串，然后通过md5等hash算法，生成一个前面sign
签名中为什么要加时间戳？
答：为了安全性考虑，防止同一次请求被反复利用，增加了密钥没破解的可能性，我们必须要对每次请求都设置一个合理的过期时间，比如：15分钟。

2. 加密
需要对数据进行非对称加密。

3. ip白名单
需求限制请求ip，增加ip白名单。

4. 限流
限流方法有三种：
对请求ip做限流：比如同一个ip，在一分钟内，对API接口总的请求次数，不能超过10000次。
对请求接口做限流：比如同一个ip，在一分钟内，对指定的API接口，请求次数不能超过2000次。
对请求用户做限流：比如同一个AK/SK用户，在一分钟内，对API接口总的请求次数，不能超过10000次。
我们在实际工作中，可以通过nginx，redis或者gateway实现限流的功能。

5. 参数校验
拦截一些无效的请求。
在Java中校验数据使用最多的是hiberate的Validator框架，它里面包含了@Null、@NotEmpty、@Size、@Max、@Min等注解。

6. 统一返回值
{
"code":0,
"message":null,
"data":[{"id":123,"name":"abc"}]
},

7. 统一封装异常
必要对API接口中的异常做统一处理，把异常转换成这样：
{
"code":500,
"message":"服务器内部错误",
"data":null
}
可以在gateway中对异常进行拦截，做统一封装，然后给第三方平台的是处理后没有敏感信息的错误信息。

8. 请求日志
需要把API接口的请求url、请求参数、请求头、请求方式、响应数据和响应时间等，记录到日志文件中。
最好有traceId，可以通过它串联整个请求的日志，过滤多余的日志。

9. 幂等设计
支持在极短的时间内，第三方平台用相同的参数请求API接口多次，第一次请求数据库会新增数据，但第二次请求以后就不会新增数据，但也会返回成功。
可以通过在数据库中增加唯一索引，或者在redis保存requestId和请求参来保证接口幂等性。

10. 限制记录条数
提供的批量接口，一定要限制请求的记录条数。
通常情况下，建议一次请求中的参数，最多支持传入500条记录。

11. 压测
在工作中可以用jmeter或者apache benc对API接口做压力测试。

12. 异步处理
直接异步处理的接口，第三方平台有两种方式获取到。
第一种方式是：我们回调第三方平台的接口，告知他们API接口的处理结果，很多支付接口就是这么玩的。
第二种方式是：第三方平台通过轮询调用我们另外一个查询状态的API接口，每隔一段时间查询一次状态，传入的参数是之前的那个API接口中的id集合。

13. 数据脱敏
返回的数据中，部分内容用星号代替。

14. 完整的接口文档
接口地址
请求方式，比如：post或get
请求参数和字段介绍
返回值和字段介绍
返回码和错误信息
加密或签名示例
完整的请求demo
额外的说明，比如：开通ip白名单。
统一字段的类型和长度，比如：id字段用Long类型，长度规定20。status字段用int类型，长度固定2等。
统一时间格式字段，比如：time用String类型，格式为：yyyy-MM-dd HH:mm:ss。

15.开发者对接SDK
我们在对接银行通道或微信、支付宝等三方支付平台时，会经常使用它们提供的SDK开发包。
提供一份开发者对接 SDK 可以帮助对方技术开发人员更快速、高效地开发应用程序，降低开发成本和对接难度，提高用户体验。
SDK包中，应包含下面几个package。
• 基础工具，加解密工具、数字签名工具、HttpUtil工具，等。
• 公共package，如 枚举、常量、自定义异常、配置。
• Model包，包含各种数据模型或实体类，用于表示和处理 SDK 所涉及的数据结构。
• 接口对接。完整的API对接代码。当然，也可以对通用逻辑进行抽象封装。
• test包，包含单元测试、集成测试等测试类。
代码中，应包含必要的javadoc，注明代码的用途，或可参考的内容。
应谨慎编写SDK中的代码，不可随意。SDK包 有可能被对接者直接引入到项目中，因此在代码质量、http连接工具等方面，进行评审和测试。