API接口设计的18条规范

API接口设计的18条规范

签名

目的：防止数据被篡改

实现方法：

1. 接口请求方将请求参数、时间戳和密钥拼接成一个字符串
2. 使用MD5等hash算法生成签名sign
3. 在请求参数或请求头中增加sign参数，传递给API接口
4. API接口网关服务验证传递的sign值，与自己生成的sign值对比，若相等则认为是有效请求

时间戳的作用：防止同一次请求被反复利用，增加密钥未破解的可能性，每次请求设置合理的过期时间，如15分钟。

加密

目的：保护敏感数据，如密码、银行卡号等

实现方法：

1. 使用AES对称加密算法
2. 在前端使用公钥加密用户密码
3. 在注册接口中使用密钥解密并做相关校验

加密方式的选择有很多，如AES, RSA等等，可以根据自己实际需要选择合适的加密方式。

IP白名单

目的：防止恶意请求
实现方法：

1. 限制请求IP
2. 添加IP白名单在API网关服务上
3. 防止内部服务器被攻破，需增加WAF (web防火墙软件，如ModSecurity、OpenWAF等)

限流

目的：限制单位时间内用户的请求数量，防止API接口被频繁调用导致服务不可用。
实现方法：

1. 对请求IP、请求接口、请求用户做限流
2. 使用nginx，redis,gateway ,sentinel 等技术实现限流功能

请求方式

目的：根据实际业务，选择合适的请求方式，如restful风格或自定义风格等等，怎么合适怎么来

具体方法：

1. 不建议让前端做主选择api请求方式，（之前遇到过不靠谱的前端非要求后端把一个删除接口从delete请求改成get接口，争论几番后原来是他不太会用axios就给后端找事）
2. 个人建议，如果是非常简单的CRUD业务，可以使用restful风格，如 查询/分页接口用GET ，添加/新增接口POST ，修改/更新接口用PUT ，删除接口用 DELETE
3. 遇到一些特殊的业务接口，如发布按钮，用POST请求，带上时间戳和其他请求参数；
4. 再比如 前端有一个下拉框接口，下拉选择时要支持动态手输新增item （可以参考elementUI中的下拉框组件高级特性），这个时候对后端就有高要求了，要一个接口既支持返回arraylist ,也支持传入一个新item值，当前端没传item值，返回现有的arraylist,当前端输入了一个item值，后端先添加这个item值到数据库，再执行查询返回最新的arraylist给前端，这个后端逻辑不难，但是要注意得用POST接口实现，来标识该接口所做的业务是非幂等的。

参数校验

目的：拦截无效请求，保护系统资源
实现方法：

1. 校验字段是否为空、字段类型、字段长度、枚举值等
2. 使用Hibernate Validator 等框架进行参数校验，使用注解如 (@NotNull @NotBlank @NotEmpty @Size @Max @Min等)对字段进行限制。

请求头设计

目的：将公共参数放入请求头中，便于后端统一拦截处理

实现方法：

1. 前端登录成功后，让前端把jwt放到请求头里，后续再请求后端，后端就可以知道请求的用户等信息
2. 一些重要的业务请求，让前端在请求头里加上traceId，便于后端做幂等处理
3. 一些重要的资源，若没有规定的特殊的请求头，不允许上传或下载
4. 一些对外开放的openApi ，限定外部请求时必须加上规定的请求头来做权限验证和请求来源识别
5. 可以通过请求头中的user-agent来限定请求来源，如禁止PC端访问，只允许手机端访问

统一异常返回

目的： 避免异常返回结构不统一，便于接口维护
实现方法：

1. 法一–在SpringBoot中使用GlobalExceptionHandler处理全局异常
2. 法二–项目中有网关如SpringGateway时，所有异常通过API网关捕获并转换成统一的异常结构返回

统一封装返回

目的：以相同格式返回数据，便于前端接收处理，节省前端数据转换处理的代码

实现方法：
构造一个如下2种格式的json返回封装

{
"code": 20001,  //业务返回码
"success": true, //标识请求成功/失败
"message": "查询数据成功",  //返回的业务处理消息提示
"timestamp" : 1718506205 , //时间戳
"result" : [  ]  //返回的数组数据,array内部还可以继续有obj
}

{
"code": 20001,  //业务返回码
"success": true, //标识请求成功/失败
"message": "查询数据成功",  //返回的业务处理消息提示
"timestamp" : 1718506205 , //时间戳
"result" : {    //返回的对象数据,obj内部还可以继续有array"age":28 , "hobby":["reading","working"]} 
}

请求日志

目的：便于快速分析和定位问题
实现方法：

1. 使用过滤器、拦截器或AOP实现记录请求URL、参数、请求头、请求方式、响应数据、响应时间
2. 使用traceId 在整个请求日志中打标记，（可以参考我之前的文章 利用MDC实现日志打点 ）https://blog.csdn.net/ThinkPet/article/details/131056402
3. 也可以把日志转发到ELK中，后续在Kibana平台可视化查看日志

幂等设计

目的：防止多次请求产生错误数据
实现方法：

1. 使用数据库唯一索引或redis保存requestId和请求参数来保证幂等性
2. 如果使用了MQ组件，要在发送的mq消息内容中自定义messageId 即业务消息id ，并利用本地消息表来实现最终一致性

限制请求的数据量

目的：避免接口超时问题
实现方法：

1. 限制查询接口请求查询的数据量（如一次最多返回30条记录）
2. 限制批量保存接口入参的数据量(如一次最多同时保存5条)
3. 超过限制直接提示用户

压测

目的：了解各接口的QPS情况，确保上线后的稳定性

实现方法：

1. 使用Jmeter 或wrk 等测试工具进行压力测试
2. 使用Prometheus ,Grafana等监控工具，监控api接口在测试环境的QPS

批量操作

目的：加快处理逻辑，一定程度上可以降低api超时时间

实现案例：

1. 后端接口逻辑中，同类型数据执行批量保存，减少jdbc时间
2. 上传接口要支持多图上传
3. 删除接口要支持按ids删除1个或多个
4. 大数据场景下，导入接口要支持单文件或多文件数据批量导入，后台分批次多线程处理写入
5. 大数据场景下，导出接口可以分批次多线程查询数据，然后合并结果并导出excel文件

异步处理

目的：同步转异步，当前端一个接口要触发后端多个长逻辑时，经过仔细分析考量后，确认哪些逻辑可以转异步执行的，然后进行异步处理，提升复杂业务逻辑的接口性能。

实现方法：

1. 利用MQ组件，一些实时性要求低的操作，把操作数据发送到MQ，然后让MQ消费者订阅后再执行操作处理。这样API接口发送MQ消息后立即返回成功，消息会由MQ消费者异步处理完成。
2. 利用juc并发工具来对后端逻辑中的多个操作进行异步编排，如下
   CountDownLatch----允许一个或多个线程等待其他线程完成操作,它可以用来实现线程之间的等待和协调；
   CyclicBarrier----用于实现多个线程之间的屏障,它可以让一组线程等待，直到所有线程都到达指定的屏障点；
   CompletableFuture----jdk8提供的强大的异步编排工具，可以组合多个异步任务，实现串行执行，合并结果，异常处理等操作。

单一职责

目的：一个API接口尽量只做一个单一的业务操作。（实际开发中可能因为赶时间、降低前端难度等原因，经常要后端一个接口做多个复杂业务，这实际是项目技术债务）

设计思路：

1. 尽量开发前，产品需求前后端人员有充足的会议讨论，共同设计一个 简单易用同时方便前后端开发的产品。
2. 比如，原型设计中多使用 步骤条，穿梭框 等UI组件，把复杂业务流程简单化，而不是一味推给后端搞。建议原型设计多参考 AntDesignUI 和elementUI 提供的各种UI组件，大厂不是平白无故开发这些组件的，那都是为了实现各种需求，搞的设计思路。
3. 不要搞方便了自己，麻烦了别人的做法。有些时候，UI的具体实现是 应该前端做es6的查询过滤排序等操作；有的时候，UI的实现中应该后端直接提供过滤、排序后的数据；还有就是 不要让前端同学生成id数据，虽然我知道前端领域有vue-uuid这种组件，但是我认为id数据应该后端产生，前端查询和使用。
4. 要根据UI原型和业务需求，综合考量前后端的工作细节项。避免出现 方便了前端，麻烦了后端；或方便了后端，麻烦了前端。

数据脱敏

目的：数据部分加密后展示给前端，用来保护姓名、手机号等隐私数据，防止泄露隐私
实现方法：

1. 用星号替代部分内容，如手机号132*****153
2. 用预设的文本做内容替代，如 王先生/女士

完善的接口文档或API用例

目的：减少沟通成本，便于前后端对接API

具体方法：

1. 法一—使用swagger 或knife4j 实现在线API接口文档，随服务启动而启动，让前端同学自己去看去对接；不过swagger 或knife4j 都对后端代码有侵入性，如果项目没有太高性能要求，可以使用这种方式。

2. 法2----后端使用postman自测接口后，导出postman的apijson文件给前端，让前端把apijson文件导入自己的postman中，然后前端根据postman测试用例，自己开发前端axios请求逻辑；但前提是后端在使用postman自测接口时，完善的标记好字段含义，字段示例值等描述信息