基本规范

1.基本规范

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

相应数据
为了方便给客户端行营，相应数据会包含三个属性：状态码（dode），信息描述（message），相应数据（data），客户端根据状态码及消息描述可快速知道接口，如果状态码返回成功，再开始处理数据
array（数组）类型数据，通过list字段，保证data的Object结构
分页类型数据，返回总条数，用于判断是否可以加载更多
列表类数据接口，无论是否要求分页，最好支持分页，pageSize=interger.max 即可

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

字段类型规范
统一使用string类型，某些情况统一使用string可以防止解析失败，减少类型转化操作，
Boolean类型，1是0否，客户端处理时，非1都是false
status类型字段，从1+开始，区别Boolean的1和0 ，（“0”有两种含义1,Boolean类型的false，2,默认的status）
上传/下载
上传和下载，参数增加文件MD5，用于完整性校验（传输过程中可能丢失数据）
避免精度丢失
缩小单位保存数据，比如：钱以分为单位，距离以米为单位

2.调用接口的先决条件-Token

获取token一般会涉及到几个参数，appid，appkey，timestamp，nonce，sign。我们通过以上几个参数来获取调用系统的凭证
appid 和 appkey 可以通过平台线上申请，也可以线下值加发布，appid时全局唯一的，每个都对应一个用户，appkey需要高度保密
timestamp 是时间戳，使用系统当前的unix时间戳，时间戳的目的就是为了减轻DOS的GJ，防止请求被拦截后一直尝试请求接口，服务器端设置时间戳阈值，如果请求时间戳和服务器时间超过阈值，则相应失败
nonce 是随机值，随机值主要是为了增加 sign 的多变性，也可以保护接口的幂等性，相邻的两次请求，nonce不允许重复，如果重复则认为是重复提交，相应失败
sign 是参数签名，将appkey,timestamp,nonce.拼接起来进行MD5加密（当然使用其他方式进行不可逆加密也没问题）
token ，使用参数 appid，timestamp，nonce，sign来获取token，作为系统调用的唯一凭证，
token 可以设置一次有效（这样安全性更高），也可以设置时效性，这个推荐时效性，如果一次有效，这个接口的请求频率可能会更高，token 推荐加到请求头上，这样可以跟业务参数完全区分开来。

3.使用post请求

一般调用接口最常使用的两种方式就是get，和post，两者的区别也很明显，使用post有更好的安全性

4.客户端IP白名单

ip白名单是指将客户的访问权限对部分ip开放，这样就能避免其他ip进行访问，设置ip白名单比较麻烦的一点就是当你客户端进行迁移后，就需要重新联系服务提供者添加新的ip白名单，
设置方式也有很多种，除了传统的防火墙之外，还有其他的

5.单个接口针对ip限流

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

6. 记录接口请求日志

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

7. 敏感数据脱敏

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

8. 瘦客户端

客户端尽量不处理逻辑，不处理金额
客户端参数校验规则可以通过接口返回，同事提供默认规则，接口不通则使用默认规则

9. 拓展性

图片文案等，与校验规则类似，通过接口返回，并提供默认，
多个boolean，可以flag 替换
flag：7，//二进制，111，代表三个boolean字段，long flag=7

接口的幂等性

幂等性：不管你请求多少次，资源的状态是一样的
幂等性是指任意多次请求的执行结果和一次请求的执行结果所产生的影响相同，其实就是查询操作无论查询多少次都不会影响数据本身，因此查询操作本身就是幂等性的，但是新增操作，没执行一次数据库都会发生变化，所以他是分幂等性的

如何设计接口的幂等性

幂等问题的解决又很多思路，这里将一种比较严谨的，提供一个生成随机数的接口，随机数全局唯一，调用接口的时候带入随机数，第一次调用，业务处理成功后，将随机数作为key操作结果作为value，存入redis，同时设置过期时长，第二次调用，查询redis，如果key存在，则证明是重复提交，直接返回错误，
insert
全局唯一的id，先查询一下然后再决定是插入还是更新，创建一个去重表（redis），token->redis
update
多版本控制，数据库乐观锁/悲观锁，使用状态码 status=0

分布式ID生成器

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

相应状态码

采用http的状态码及逆行数据封装，例如200表示请求成功，4XX表示客户端错误，5XX表示服务器内部错误

接口规范

协议
API与和客户端用户的通信协议，总是使用https协议，以确保交互数据的传输安全
域名
应该尽量将API部署在专门域名下面，比如 https://api.xx.com
如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下面比如 https://www.xx.com/api
版本控制
https://api.xx.com/v{n}

应该将API的版本号放入URL
采用多版本并存，增量发布的方式
n 代表版本号，分为整型和浮点型，

整型：大功能的版本号例如 v1，v2
浮点型：补充功能版本，如 v1,2，v2.3

对于一个API或服务，应在生产中最多保留3个最详细的版本，

路径规则
路径又称终点，表示API的具体网址

在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能由名词，【所用的名词往往与数据库的表格名相应】
数据库中的表一般都是同种记录的几个，座椅API中的名词也应该使用复数

https://api.example.com/v1/products
https://api.example.com/v1/users
非 RESTful API的请求
实际业务开展中，可能会出现各种的API不是简单的restful规范实现的，需要一些API突破原有的规则，特别是一些移动互联网的api设计，需要一些特定的api来优化数据请求的交互
删除单个/删除多个，页面级API（）一次将页面用到的数据全部返回
一致性原理
前端需要那些字段，API接口应该返回那些字段，不多不少，
更新功能尽量做到，初次返回的原始数据参数，与提交更新的数据参数结构一致，
时间参数，尽量以一致格式的字符串传递
接口文档
尽量采用自动化接口文档，可以做到在线测试，同步更新
应该包含：接口地址，接口版本，接口模块分类

API接口规范