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连接工具等方面，进行评审和测试。