API接口设计规范

API 接口设计规范，目的是提供给研发人员做参考。规范是死的，人是活的，希望自己定的规范，不要被打脸。

一、路由命名规范

二、请求方式

三、请求参数

Query

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

Header

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

Body

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

四、公共参数

App 端请求

WEB 端请求

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

五、安全规范

• 敏感参数加密处理、 数据脱敏处理。
• 登录密码、支付密码，需加密后传输，建议使用 非对称加密。
• 用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏，部分数据加 * 号处理。

六、返回参数

七、签名设计

签名验证没有确定的规范，自己制定就行，可以选择使用 对称加密、 非对称加密、 单向散列加密等。

八、幂等性设计

我们无法保证接口的每一次调用都是有返回结果的，要考虑到出现网络异常的情况。
举个例子，订单创建时，我们需要去减库存，这时接口发生了超时，调用方进行了重试，这时是否会多扣一次库存？
解决这类问题有 2 种方案：
一、服务方提供相应的查询接口，调用方在请求超时后进行查询，如果查到了，表示请求处理成功了，没查到就走失败流程。
二、调用方只管重试，服务方保证一次和多次的请求结果是一样的。就需要服务方的接口支持幂等性。

大致设计思路是这样的：

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

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

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

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

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

九、其他规范

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

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