API 接口设计规范

标签：展示   dev   ble   创建   save   账号   非对称   后端   默认值   

概述

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

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

路由命名规范

请求方式

请求参数

Query

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

Header

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

Body

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

公共参数

APP 端请求

WEB 端请求

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

安全规范

敏感参数加密处理

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

其他规范

• 参数命名规范 建议使用驼峰命名，首字母小写。
• requestId 建议携带唯一标示追踪问题。

返回参数

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

{
    "code": 1,
    "showMsg": "success",
    "errorMsg": "",
    "data": {
        "list": [],
        "pagination": {
            "total": 100,
            "currentPage": 1,
            "prePageCount": 10
        }
    }
}

安全规范

敏感数据脱敏处理

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

其他规范

• 属性名命名时，建议使用驼峰命名，首字母小写。
• 属性值为空时，严格按类型返回默认值。
• 金额类型/时间日期类型的属性值，如果仅用来显示，建议后端返回可以显示的字符串。
• 业务逻辑的状态码和对应的文案，建议后端两者都返回。
• 调用方不需要的属性，不要返回。

签名设计

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

• Go 签名验证
• PHP 签名验证

日志平台设计

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

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

幂等性设计

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

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

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

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

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

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

大致设计思路是这样的：

1. 调用接口前，先获取一个全局唯一的令牌（Token）
2. 调用接口时，将 Token 放到 Header 头中
3. 解析 Header 头，验证是否为有效 Token，无效直接返回失败
4. 完成业务逻辑后，将业务结果与 Token 进行关联存储，设置失效时间
5. 重试时不要重新获取 Token，用要上次的 Token

小结

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

暂时就想到这么多，规范这东西不是一成不变的，发现有不妥的及时调整吧。

推荐阅读

• 一线技术管理者究竟在管什么事？
• 一个人被提拔，不仅仅是能力，而是信任

API 接口设计规范

标签：展示   dev   ble   创建   save   账号   非对称   后端   默认值   

原文地址：https://www.cnblogs.com/xinliangcoder/p/12327088.html