如何制定平台接口建设标准规范？
- 内容介绍
- 文章标签
- 相关推荐
本文共计2728个文字，预计阅读时间需要11分钟。
构建目标+平台接口设计规范：为接口开发、测试、使用规划一个框架，明确技术目标与需求，并要求提供详尽的接口文档说明，确保自有平台与第三方平台提供的数据及服务支持。
建设目标平台接口建设规范旨在为接口开发、测试、使用划定一个框架边界，明确技术目标与要求，并要求提供完备的接口文档说明，为自有平台与第三方平台提供数据及服务支持。
建设标准 接口规范 命名规范在标准的RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词。
根据观察大多数平台在接口设计当中，都无法完全按照此规范，这里我的建议是无论接口命名还是参数命名必须基于业务与理解需要进行合理设计，确保简洁务实、便于理解。
幂等性幂等性是指任意多次请求的执行结果和一次请求的执行结果所产生的影响相同。查询操作无论查询多少次都不会影响数据本身，因此查询操作本身就是幂等的。但是新增操作，每执行一次数据库就会发生变化，所以它是非幂等的。
关于幂等性的实现方式有很多种，比如前端禁用、参数传入唯一Key值或者先查询后操作等，这里不做详细概述。一般来说接口中新增操作、部分带条件的删除和修改操作都是要考虑幂等性的，这也是保证数据一致性和安全性的必要措施。
请求方式- • GET请求：查询数据
- • POST请求：新增数据
- • PUT请求：更新数据，调用者提供完整数据，要求幂等性
- • DELETE请求： 删除数据，要求幂等性
- • PATCH（UPDATE）请求：更新数据，调用者提供需改变数据
这里建议接口建设中最少支持GET、POST、DELETE三种请求方式，对应查询、新增/编辑、删除三大类操作。如存在PUT、DELETE请求方式的接口需要保证幂等性。
安全规范 传输加密- • HTTPS
条件允许情况下服务尽量启用HTTPS
- • 账号密码
登录认证时对账号密码进行加密，建议采用“ RSA ”非对称加密，非对称加密算法有两个密钥，这两个密钥完全不同但又完全匹配。只有使用匹配的一对公钥和私钥，才能完成对明文的加密和解密过程。
登录认证- • 认证方式
Bear Token api/v1。
以统一的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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
文档作为接口建设中的一个非常重要的指标必须予以足够的重视，如果接口本身的设计与开发需要考虑技术与业务的实际情况，那么文档的编制完全是团队素质的体现，所以说文档完备性也是衡量技术成熟型的一个重要标准。
无论是线上文档还是线下文档，内容务必完整详实，特别是要站在文档使用者的角度，对一些关键点进行说明，便于理解。
实时推送针对实时性较强的数据，建议通过队列方式分用户、分权限向调用方实时推送数据，建设数据推送服务。
总结接口设计的规范一方面既是软件系统工程化、标准化的体现，另一方面也是前人经验的总结汇总，必然会带着一定的主观性。而在实际接口设计开发当中，小的系统追求快速落地，可能无法完全匹配标准。大平台场景复杂，标准也相应比以上规范要更加繁多。所以各位见仁见智，根据实际情况综合考虑，技术层面力争做到严谨 ，务实， 精进。
希望本文对大家能有所帮助，其中如有不足与不正确的地方还望指正与海涵，十分感谢。
关注微信公众号，查看更多技术文章。
本文共计2728个文字，预计阅读时间需要11分钟。
构建目标+平台接口设计规范：为接口开发、测试、使用规划一个框架，明确技术目标与需求，并要求提供详尽的接口文档说明，确保自有平台与第三方平台提供的数据及服务支持。
建设目标平台接口建设规范旨在为接口开发、测试、使用划定一个框架边界，明确技术目标与要求，并要求提供完备的接口文档说明，为自有平台与第三方平台提供数据及服务支持。
建设标准 接口规范 命名规范在标准的RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词。
根据观察大多数平台在接口设计当中，都无法完全按照此规范，这里我的建议是无论接口命名还是参数命名必须基于业务与理解需要进行合理设计，确保简洁务实、便于理解。
幂等性幂等性是指任意多次请求的执行结果和一次请求的执行结果所产生的影响相同。查询操作无论查询多少次都不会影响数据本身，因此查询操作本身就是幂等的。但是新增操作，每执行一次数据库就会发生变化，所以它是非幂等的。
关于幂等性的实现方式有很多种，比如前端禁用、参数传入唯一Key值或者先查询后操作等，这里不做详细概述。一般来说接口中新增操作、部分带条件的删除和修改操作都是要考虑幂等性的，这也是保证数据一致性和安全性的必要措施。
请求方式- • GET请求：查询数据
- • POST请求：新增数据
- • PUT请求：更新数据，调用者提供完整数据，要求幂等性
- • DELETE请求： 删除数据，要求幂等性
- • PATCH（UPDATE）请求：更新数据，调用者提供需改变数据
这里建议接口建设中最少支持GET、POST、DELETE三种请求方式，对应查询、新增/编辑、删除三大类操作。如存在PUT、DELETE请求方式的接口需要保证幂等性。
安全规范 传输加密- • HTTPS
条件允许情况下服务尽量启用HTTPS
- • 账号密码
登录认证时对账号密码进行加密，建议采用“ RSA ”非对称加密，非对称加密算法有两个密钥，这两个密钥完全不同但又完全匹配。只有使用匹配的一对公钥和私钥，才能完成对明文的加密和解密过程。
登录认证- • 认证方式
Bear Token api/v1。
以统一的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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
文档作为接口建设中的一个非常重要的指标必须予以足够的重视，如果接口本身的设计与开发需要考虑技术与业务的实际情况，那么文档的编制完全是团队素质的体现，所以说文档完备性也是衡量技术成熟型的一个重要标准。
无论是线上文档还是线下文档，内容务必完整详实，特别是要站在文档使用者的角度，对一些关键点进行说明，便于理解。
实时推送针对实时性较强的数据，建议通过队列方式分用户、分权限向调用方实时推送数据，建设数据推送服务。
总结接口设计的规范一方面既是软件系统工程化、标准化的体现，另一方面也是前人经验的总结汇总，必然会带着一定的主观性。而在实际接口设计开发当中，小的系统追求快速落地，可能无法完全匹配标准。大平台场景复杂，标准也相应比以上规范要更加繁多。所以各位见仁见智，根据实际情况综合考虑，技术层面力争做到严谨 ，务实， 精进。
希望本文对大家能有所帮助，其中如有不足与不正确的地方还望指正与海涵，十分感谢。
关注微信公众号，查看更多技术文章。