接口设计规范有哪些要求？最全的API 接口设计规范，值得收藏！

本文关于接口设计规范有哪些要求？最全的API 接口设计规范，值得收藏！

述

这篇文章分享 API 接口设计规范，目的是提供给研发人员做参考。

规范是死的，人是活的，希望自己定的规范，不要被打脸。

路由命名规范

请求方式

请求参数

Query

url?后面的参数，存放请求接口的参数数据。

Header

请求头，存放公共参数、requestId、token、加密字段等。

Body

Body 体，存放请求接口的参数数据。

公共参数

APP 端请求

WEB 端请求

调用方需向服务方申请 appKey（请求时使用） 和 secretKey（加密时使用）。

安全规范

敏感参数加密处理

登录密码、支付密码，需加密后传输，建议使用非对称加密。

其他规范

参数命名规范 建议使用驼峰命名，首字母小写。

requestId 建议携带唯一标示追踪问题。

返回参数

若有分页数据返回的，格式如下：

安全规范

敏感数据脱敏处理

用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏，部分数据加 * 号处理。

其他规范

属性名命名时，建议使用驼峰命名，首字母小写。

属性值为空时，严格按类型返回默认值。

金额类型/时间日期类型的属性值，如果仅用来显示，建议后端返回可以显示的字符串。

业务逻辑的状态码和对应的文案，建议后端两者都返回。

调用方不需要的属性，不要返回。

签名设计

签名验证没有确定的规范，自己制定就行，可以选择使用 对称加密、非对称加密、单向散列加密 等，分享下原来写的签名验证，供参考。

Go 签名验证

PHP 签名验证

日志平台设计

日志平台有利于故障定位和日志统计分析。

日志平台的搭建可以使用的是 ELK 组件，使用 Logstash 进行收集日志文件，使用 Elasticsearch 引擎进行搜索分析，最终在 Kibana 平台展示出来。

幂等性设计

我们无法保证接口的每一次调用都是有返回结果的，要考虑到出现网络异常的情况。

举个例子，订单创建时，我们需要去减库存，这时接口发生了超时，调用方进行了重试，这时是否会多扣一次库存？

解决这类问题有 2 种方案：

一、服务方提供相应的查询接口，调用方在请求超时后进行查询，如果查到了，表示请求处理成功了，没查到就走失败流程。

二、调用方只管重试，服务方保证一次和多次的请求结果是一样的。

对于第二种方案，就需要服务方的接口支持幂等性。

大致设计思路是这样的：

调用接口前，先获取一个全局唯一的令牌（Token）

调用接口时，将 Token 放到 Header 头中

解析 Header 头，验证是否为有效 Token，无效直接返回失败

完成业务逻辑后，将业务结果与 Token 进行关联存储，设置失效时间

重试时不要重新获取 Token，用要上次的 Token

小结

限流设计、熔断设计、降级设计，这些就不多说了，因为大部分都用不到，当用上了基本上也都在网关中加这些功能。

上述就是小编为大家整理的接口设计规范有哪些要求？最全的API 接口设计规范相关内容。

国内(北京、上海、广州、深圳、成都、重庆、杭州、西安、武汉、苏州、郑州、南京、天津、长沙、东莞、宁波、佛山、合肥、青岛)Eolinker软件分析、比较及推荐。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。