外贸建网站免费模板,网站开发项目意义,seo网站推广软件,php wordpress apiAPI接口设计的18条规范
签名
目的#xff1a;防止数据被篡改
实现方法#xff1a;
接口请求方将请求参数、时间戳和密钥拼接成一个字符串使用MD5等hash算法生成签名sign在请求参数或请求头中增加sign参数#xff0c;传递给API接口API接口网关服务验证传递的sign值#…API接口设计的18条规范
签名
目的防止数据被篡改
实现方法
接口请求方将请求参数、时间戳和密钥拼接成一个字符串使用MD5等hash算法生成签名sign在请求参数或请求头中增加sign参数传递给API接口API接口网关服务验证传递的sign值与自己生成的sign值对比若相等则认为是有效请求
时间戳的作用防止同一次请求被反复利用增加密钥未破解的可能性每次请求设置合理的过期时间如15分钟。
加密
目的保护敏感数据如密码、银行卡号等
实现方法
使用AES对称加密算法在前端使用公钥加密用户密码在注册接口中使用密钥解密并做相关校验
加密方式的选择有很多如AES, RSA等等可以根据自己实际需要选择合适的加密方式。
IP白名单
目的防止恶意请求 实现方法
限制请求IP添加IP白名单在API网关服务上防止内部服务器被攻破需增加WAF (web防火墙软件如ModSecurity、OpenWAF等)
限流
目的限制单位时间内用户的请求数量防止API接口被频繁调用导致服务不可用。 实现方法
对请求IP、请求接口、请求用户做限流使用nginxredis,gateway ,sentinel 等技术实现限流功能
请求方式
目的根据实际业务选择合适的请求方式如restful风格或自定义风格等等怎么合适怎么来
具体方法
不建议让前端做主选择api请求方式之前遇到过不靠谱的前端非要求后端把一个删除接口从delete请求改成get接口争论几番后原来是他不太会用axios就给后端找事个人建议如果是非常简单的CRUD业务可以使用restful风格如 查询/分页接口用GET 添加/新增接口POST 修改/更新接口用PUT 删除接口用 DELETE遇到一些特殊的业务接口如发布按钮用POST请求带上时间戳和其他请求参数再比如 前端有一个下拉框接口下拉选择时要支持动态手输新增item 可以参考elementUI中的下拉框组件高级特性这个时候对后端就有高要求了要一个接口既支持返回arraylist ,也支持传入一个新item值当前端没传item值返回现有的arraylist,当前端输入了一个item值后端先添加这个item值到数据库再执行查询返回最新的arraylist给前端这个后端逻辑不难但是要注意得用POST接口实现来标识该接口所做的业务是非幂等的。
参数校验
目的拦截无效请求保护系统资源 实现方法
校验字段是否为空、字段类型、字段长度、枚举值等使用Hibernate Validator 等框架进行参数校验使用注解如 (NotNull NotBlank NotEmpty Size Max Min等)对字段进行限制。
请求头设计
目的将公共参数放入请求头中便于后端统一拦截处理
实现方法
前端登录成功后让前端把jwt放到请求头里后续再请求后端后端就可以知道请求的用户等信息一些重要的业务请求让前端在请求头里加上traceId便于后端做幂等处理一些重要的资源若没有规定的特殊的请求头不允许上传或下载一些对外开放的openApi 限定外部请求时必须加上规定的请求头来做权限验证和请求来源识别可以通过请求头中的user-agent来限定请求来源如禁止PC端访问只允许手机端访问
统一异常返回
目的 避免异常返回结构不统一便于接口维护 实现方法
法一–在SpringBoot中使用GlobalExceptionHandler处理全局异常法二–项目中有网关如SpringGateway时所有异常通过API网关捕获并转换成统一的异常结构返回
统一封装返回
目的以相同格式返回数据便于前端接收处理节省前端数据转换处理的代码
实现方法 构造一个如下2种格式的json返回封装
{
code: 20001, //业务返回码
success: true, //标识请求成功/失败
message: 查询数据成功, //返回的业务处理消息提示
timestamp : 1718506205 , //时间戳
result : [ ] //返回的数组数据,array内部还可以继续有obj
}{
code: 20001, //业务返回码
success: true, //标识请求成功/失败
message: 查询数据成功, //返回的业务处理消息提示
timestamp : 1718506205 , //时间戳
result : { //返回的对象数据,obj内部还可以继续有arrayage:28 , hobby:[reading,working]}
}请求日志
目的便于快速分析和定位问题 实现方法
使用过滤器、拦截器或AOP实现记录请求URL、参数、请求头、请求方式、响应数据、响应时间使用traceId 在整个请求日志中打标记可以参考我之前的文章 利用MDC实现日志打点 https://blog.csdn.net/ThinkPet/article/details/131056402也可以把日志转发到ELK中后续在Kibana平台可视化查看日志
幂等设计
目的防止多次请求产生错误数据 实现方法
使用数据库唯一索引或redis保存requestId和请求参数来保证幂等性如果使用了MQ组件要在发送的mq消息内容中自定义messageId 即业务消息id 并利用本地消息表来实现最终一致性
限制请求的数据量
目的避免接口超时问题 实现方法
限制查询接口请求查询的数据量如一次最多返回30条记录限制批量保存接口入参的数据量(如一次最多同时保存5条)超过限制直接提示用户
压测
目的了解各接口的QPS情况确保上线后的稳定性
实现方法
使用Jmeter 或wrk 等测试工具进行压力测试使用Prometheus ,Grafana等监控工具监控api接口在测试环境的QPS
批量操作
目的加快处理逻辑一定程度上可以降低api超时时间
实现案例
后端接口逻辑中同类型数据执行批量保存减少jdbc时间上传接口要支持多图上传删除接口要支持按ids删除1个或多个大数据场景下导入接口要支持单文件或多文件数据批量导入后台分批次多线程处理写入大数据场景下导出接口可以分批次多线程查询数据然后合并结果并导出excel文件
异步处理
目的同步转异步当前端一个接口要触发后端多个长逻辑时经过仔细分析考量后确认哪些逻辑可以转异步执行的然后进行异步处理提升复杂业务逻辑的接口性能。
实现方法
利用MQ组件一些实时性要求低的操作把操作数据发送到MQ然后让MQ消费者订阅后再执行操作处理。这样API接口发送MQ消息后立即返回成功消息会由MQ消费者异步处理完成。利用juc并发工具来对后端逻辑中的多个操作进行异步编排如下 CountDownLatch----允许一个或多个线程等待其他线程完成操作,它可以用来实现线程之间的等待和协调 CyclicBarrier----用于实现多个线程之间的屏障,它可以让一组线程等待直到所有线程都到达指定的屏障点 CompletableFuture----jdk8提供的强大的异步编排工具可以组合多个异步任务实现串行执行合并结果异常处理等操作。
单一职责
目的一个API接口尽量只做一个单一的业务操作。实际开发中可能因为赶时间、降低前端难度等原因经常要后端一个接口做多个复杂业务这实际是项目技术债务
设计思路
尽量开发前产品需求前后端人员有充足的会议讨论共同设计一个 简单易用同时方便前后端开发的产品。比如原型设计中多使用 步骤条穿梭框 等UI组件把复杂业务流程简单化而不是一味推给后端搞。建议原型设计多参考 AntDesignUI 和elementUI 提供的各种UI组件大厂不是平白无故开发这些组件的那都是为了实现各种需求搞的设计思路。不要搞方便了自己麻烦了别人的做法。有些时候UI的具体实现是 应该前端做es6的查询过滤排序等操作有的时候UI的实现中应该后端直接提供过滤、排序后的数据还有就是 不要让前端同学生成id数据虽然我知道前端领域有vue-uuid这种组件但是我认为id数据应该后端产生前端查询和使用。要根据UI原型和业务需求综合考量前后端的工作细节项。避免出现 方便了前端麻烦了后端或方便了后端麻烦了前端。
数据脱敏
目的数据部分加密后展示给前端用来保护姓名、手机号等隐私数据防止泄露隐私 实现方法
用星号替代部分内容如手机号132*****153用预设的文本做内容替代如 王先生/女士
完善的接口文档或API用例
目的减少沟通成本便于前后端对接API
具体方法 法一—使用swagger 或knife4j 实现在线API接口文档随服务启动而启动让前端同学自己去看去对接不过swagger 或knife4j 都对后端代码有侵入性如果项目没有太高性能要求可以使用这种方式。 法2----后端使用postman自测接口后导出postman的apijson文件给前端让前端把apijson文件导入自己的postman中然后前端根据postman测试用例自己开发前端axios请求逻辑但前提是后端在使用postman自测接口时完善的标记好字段含义字段示例值等描述信息
