建设目标

平台接口建设规范旨在为接口开发、测试、使用划定一个框架边界，明确技术目标与要求，并要求提供完备的接口文档说明，为自有平台与第三方平台提供数据及服务支持。

建设标准

接口规范

命名规范

在标准的RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词。

根据观察大多数平台在接口设计当中，都无法完全按照此规范，这里我的建议是无论接口命名还是参数命名必须基于业务与理解需要进行合理设计，确保简洁务实、便于理解。

幂等性

幂等性是指任意多次请求的执行结果和一次请求的执行结果所产生的影响相同。查询操作无论查询多少次都不会影响数据本身，因此查询操作本身就是幂等的。但是新增操作，每执行一次数据库就会发生变化，所以它是非幂等的。

关于幂等性的实现方式有很多种，比如前端禁用、参数传入唯一Key值或者先查询后操作等，这里不做详细概述。一般来说接口中新增操作、部分带条件的删除和修改操作都是要考虑幂等性的，这也是保证数据一致性和安全性的必要措施。

请求方式

• • GET请求：查询数据
• • POST请求：新增数据
• • PUT请求：更新数据，调用者提供完整数据，要求幂等性
• • DELETE请求： 删除数据，要求幂等性
• • PATCH（UPDATE）请求：更新数据，调用者提供需改变数据

这里建议接口建设中最少支持GET、POST、DELETE三种请求方式，对应查询、新增/编辑、删除三大类操作。如存在PUT、DELETE请求方式的接口需要保证幂等性。

安全规范

传输加密

• • HTTPS

条件允许情况下服务尽量启用HTTPS

• • 账号密码

登录认证时对账号密码进行加密，建议采用“ RSA ”非对称加密，非对称加密算法有两个密钥，这两个密钥完全不同但又完全匹配。只有使用匹配的一对公钥和私钥，才能完成对明文的加密和解密过程。

登录认证

• • 认证方式

Bear Token https请求header里面放Authorization ，具备时效性；

• • 登录防护

连续登录失败一定次数应拒绝响应一段时间；

接口日志

• • 使用AOP全局记录请求日志，便于定位与追溯异常请求，排查问题原因。
• • 日志必须包含调用账号、调用接口、传入参数、调用时间等关键信息。返回数据可以只记录异常情况。
• • 日志异步存储，避免影响接口性能；

数据脱敏

• • 数据加密

在接口调用过程中，可能会涉及到位置、金额、个人信息等敏感数据，需对这类数据进行加密脱敏处理。 建议也采用 RSA ”非对称加密

• • 数据屏蔽

尽量不要在接口中返回不必要的数据，如ID、编号等敏感信息

黑白名单

• • 可针对IP对接口的访问权限进行限制。这样就能避免其他ip进行访问攻击；
• • 具备针对IP、账号的封禁功能；

IP限流

服务平台应实现基于IP的限流功能, 如每秒并发请求不高于1000次；

防重放

除登录接口外,其他请求除包含头部token外，应包含timestamp 时间戳,nonce 随机数、signature签名等三个参数；服务平台将token、timestamp、nonce三个参数进行字典序排序 ,将三个参数字符串拼接成一个字符串进行数字签名加密, 服务器将加密后的字符串与signature对比，标识该请求来源于特定用户。

这里建议针对业务敏感类接口，如涉及数据修改、设备操作等接口增加防重放机制，一方面既不提高常规接口调用的复杂性，另一方面对安全风险较大的接口进一步加固，保持业务与技术层面的平衡。

版本控制

如果涉及版本区分问题，可在接口中设计版本号标识

• • 一种方式是在URL中添加版本号，比如https://api/v1。
• • 另一种是将版本加到header中。

数据规范

统一响应数据格式

以统一的JSON格式返回数据

{
        "code": 200, //返回状态码;
        "msg": "成功",  //成功：无数据或成功信息;失败：失败信息
        "data": {}      //成功：数据实体失败：无数据
}

统一响应状态码

这里需要区分接口状态码与HTTP状态码的区别

接口状态码尽量设计的清晰统一，如用1或200代表接口调用成功，正常返回数据，其他视为调用异常，异常信息通过《附录状态表》 进行说明，一般情况下你只需要定义好平台接口返回状态码即可。

HTTP状态码则是代表服务器向用户返回的状态码和提示信息。含义如下：

• • 200 OK – [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
• • 201 CREATED – [POST/PUT/PATCH]：用户新建或修改数据成功。
• • 202 Accepted – [*]：表示一个请求已经进入后台排队（异步任务）
• • 204 NO CONTENT – [DELETE]：用户删除数据成功。
• • 400 INVALID REQUEST – [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
• • 401 Unauthorized – [*]：表示用户没有权限（令牌、用户名、密码错误）。
• • 403 Forbidden – [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
• • 404 NOT FOUND – [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
• • 406 Not Acceptable – [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
• • 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
• • 422 Unprocesable entity – [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
• • 500 INTERNAL SERVER ERROR – [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

接口文档

文档作为接口建设中的一个非常重要的指标必须予以足够的重视，如果接口本身的设计与开发需要考虑技术与业务的实际情况，那么文档的编制完全是团队素质的体现，所以说文档完备性也是衡量技术成熟型的一个重要标准。

无论是线上文档还是线下文档，内容务必完整详实，特别是要站在文档使用者的角度，对一些关键点进行说明，便于理解。

实时推送

针对实时性较强的数据，建议通过队列方式分用户、分权限向调用方实时推送数据，建设数据推送服务。

总结

接口设计的规范一方面既是软件系统工程化、标准化的体现，另一方面也是前人经验的总结汇总，必然会带着一定的主观性。而在实际接口设计开发当中，小的系统追求快速落地，可能无法完全匹配标准。大平台场景复杂，标准也相应比以上规范要更加繁多。所以各位见仁见智，根据实际情况综合考虑，技术层面力争做到严谨 ，务实， 精进。

希望本文对大家能有所帮助，其中如有不足与不正确的地方还望指正与海涵，十分感谢。

  关注微信公众号，查看更多技术文章。