接口设计规范

基本规范

公共参数

公共参数是每个接口都要携带的参数，描述每个接口的基本信息，用于统计或其他用途，放在 header 或 url 参数中。例如：

响应数据

为了方便给客户端响应，响应数据会包含三个属性，状态码（code）, 信息描述（message）, 响应数据（data）。客户端根据状态码及信息描述可快速知道接口，如果状态码返回成功，再开始处理数据。

array 类型数据。通过 list 字段，保证 data 的 Object 结构。

分页类型数据。返回总条数，用于判断是否可以加载更多。

// object类型数据
{
    "code":1,
    "msg":"成功",
    "data":{}}// array类型数据。{
    "code":1,
    "msg":"成功",
    "data":{
        "list":[]
    }}// 分页类型数据。{
    "code":1,
    "msg":"成功",
    "data":{
        "list":[]
        "total":"10"
    }
}

列表类数据接口，无论是否要求分页，最好支持分页，pageSize=Integer.Max 即可。

响应结果定义及常用方法：

public class R implements Serializable {

    private static final long serialVersionUID = 793034041048451317L;

    private int code;
    private String message;
    private Object data = null;

    public int getCode() {
        return code;
    }
    public void setCode(int code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }
    public void setMessage(String message) {
        this.message = message;
    }

    public Object getData() {
        return data;
    }

    /**
     * 放入响应枚举
     */
    public R fillCode(CodeEnum codeEnum){
        this.setCode(codeEnum.getCode());
        this.setMessage(codeEnum.getMessage());
        return this;
    }

    /**
     * 放入响应码及信息
     */
    public R fillCode(int code, String message){
        this.setCode(code);
        this.setMessage(message);
        return this;
    }

    /**
     * 处理成功，放入自定义业务数据集合
     */
    public R fillData(Object data) {
        this.setCode(CodeEnum.SUCCESS.getCode());
        this.setMessage(CodeEnum.SUCCESS.getMessage());
        this.data = data;
        return this;
    }
}

采用 http 的状态码进行数据封装，例如 200 表示请求成功，4xx 表示客户端错误，5xx 表示服务器内部发生错误。状态码设计参考如下：

状态码枚举类：

public enum CodeEnum {

    // 根据业务需求进行添加
    SUCCESS(200,"处理成功"),
    ERROR_PATH(404,"请求地址错误"),
    ERROR_SERVER(505,"服务器内部发生错误");
    
    private int code;
    private String message;
    
    CodeEnum(int code, String message) {
        this.code = code;
        this.message = message;
    }

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }}

正常响应

响应状态码 2xx

• 200：常规请求

• 201：创建成功

重定向响应

响应状态码 3xx

• 301：永久重定向

• 302：暂时重定向

客户端异常

响应状态码 4xx

• 403：请求无权限

• 404：请求路径不存在

• 405：请求方法不存在

服务器异常

响应状态码 5xx

• 500：服务器异常

字段类型规范

统一使用 String 类型。某些情况，统一使用 String 可以防止解析失败，减少类型转化操作。

Boolean 类型，1 是 0 否。客户端处理时，非 1 都是 false。

上传 / 下载

上传 / 下载，参数增加文件 md5，用于完整性校验（传输过程可能丢失数据）。

避免精度丢失

缩小单位保存数据，如：钱以分为单位、距离以米为单位。

调用接口的先决条件 - token

获取 token 一般会涉及到几个参数appid，appkey，timestamp，nonce，sign。我们通过以上几个参数来获取调用系统的凭证。

appid和appkey可以直接通过平台线上申请，也可以线下直接颁发。appid是全局唯一的，每个appid将对应一个客户，appkey需要高度保密。

timestamp是时间戳，使用系统当前的 unix 时间戳。时间戳的目的就是为了减轻 DOS 的 GJ。防止请求被拦截后一直尝试请求接口。服务器端设置时间戳阀值，如果请求时间戳和服务器时间超过阀值，则响应失败。

nonce是随机值。随机值主要是为了增加sign的多变性，也可以保护接口的幂等性，相邻的两次请求nonce不允许重复，如果重复则认为是重复提交，响应失败。

sign是参数签名，将appkey，timestamp，nonce拼接起来进行 md5 加密（当然使用其他方式进行不可逆加密也没问题）。

token，使用参数appid，timestamp，nonce，sign来获取 token，作为系统调用的唯一凭证。token可以设置一次有效（这样安全性更高），也可以设置时效性，这里推荐设置时效性。如果一次有效的话这个接口的请求频率可能会很高。token推荐加到请求头上，这样可以跟业务参数完全区分开来。

使用 POST 作为接口请求方式

一般调用接口最常用的两种方式就是 GET 和 POST。两者的区别也很明显，GET 请求会将参数暴露在浏览器 URL 中，而且对长度也有限制。为了更高的安全性，所有接口都采用 POST 方式请求。

GET

• 安全且幂等

• 获取表示

• 变更时获取表示（缓存）

  适合查询类的接口使用

POST

• 不安全且不幂等

• 使用服务端管理的（自动产生）的实例号创建资源

• 创建子资源

• 部分更新资源

• 如果没有被修改，则不过更新资源（乐观锁）

  适合数据提交类的接口使用

PUT

• 不安全但幂等

• 用客户端管理的实例号创建一个资源

• 通过替换的方式更新资源

• 如果未被修改，则更新资源（乐观锁）

  适合更新数据的接口使用

DELETE

• 不安全但幂等

• 删除资源

  适合删除数据的接口使用

客户端 IP 白名单

ip 白名单是指将接口的访问权限对部分 ip 进行开放。这样就能避免其他 ip 进行访问 ***，设置 ip 白名单比较麻烦的一点就是当你的客户端进行迁移后，就需要重新联系服务提供者添加新的 ip 白名单。设置 ip 白名单的方式很多，除了传统的防火墙之外，spring cloud alibaba 提供的组件 sentinel 也支持白名单设置。为了降低 api 的复杂度，推荐使用防火墙规则进行白名单设置。

单个接口针对 ip 限流

限流是为了更好的维护系统稳定性。使用 redis 进行接口调用次数统计，ip + 接口地址作为 key，访问次数作为 value，每次请求 value+1，设置过期时长来限制接口的调用频率。

记录接口请求日志

使用 aop 全局记录请求日志，快速定位异常请求位置，排查问题原因。

敏感数据脱敏

在接口调用过程中，可能会涉及到订单号等敏感数据，这类数据通常需要脱敏处理，最常用的方式就是加密。加密方式使用安全性比较高的RSA非对称加密。非对称加密算法有两个密钥，这两个密钥完全不同但又完全匹配。只有使用匹配的一对公钥和私钥，才能完成对明文的加密和解密过程。

瘦客户端

客户端尽量不处理逻辑

客户端不处理金额

客户端参数校验规则可以通过接口返回，同时提供默认规则，接口不通则使用默认规则。

如何设计接口的幂等性

幂等问题的解决有很多思路，这里讲一种比较严谨的。提供一个生成随机数的接口，随机数全局唯一。调用接口的时候带入随机数。第一次调用，业务处理成功后，将随机数作为 key，操作结果作为 value，存入 redis，同时设置过期时长。第二次调用，查询 redis，如果 key 存在，则证明是重复提交，直接返回错误。

insert

1. 全局唯一的 id
2. 先查询一下然后再决定是插入还是更新
3. 创建一个去重表（redis）
   4.token -> redis

update

1. 多版本控制
2. 数据库乐观锁 / 悲观锁
3. 使用状态码 status=0

分布式 ID 生成器

不能使用数据库本身的自增功能来产生主键值，原因是生产环境为分片部署的。会导致有重复的 id 值
使用 snowflake （雪花）算法（twitter 出品）生成唯一的主键值

• 41bit 的时间戳可以支持该算法使用到 2082 年

• 10bit 的工作机器 id 可以支持 1024 台机器

• 序列号支持 1 毫秒产生 4096 个自增序列 id

• 整体上按照时间自增排序

• 整个分布式系统内不会产生 ID 碰撞

• 每秒能够产生 26 万 ID 左右