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自测接口时,完善的标记好字段含义,字段示例值等描述信息

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/diannao/28658.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

数电逻辑门电路分析和Digital仿真

文章目录 1. 逻辑门电路 2. 非门(NOT Gate) 3. 与门(AND Gate) 4. 或门(OR Gate) 5. 与非门(NAND Gate) 6. 或非门(NOR Gate) 7. 异或门(XO…

pinocchio计算MPC控制状态方程AB矩阵

pinocchio计算MPC控制状态方程AB矩阵 Pinocchio是一个用于机器人动力学和运动学计算的库,广泛应用于机器人控制和仿真中。为了在MPC控制中使用Pinocchio计算状态方程的线性化矩阵 A 和 B,需要以下步骤: 1、初始化机器人模型和数据结构: 使用Pinocchio加载机器人模型。初始…

开源模型应用落地-LangChain高阶-LCEL-表达式语言(七)

一、前言 尽管现在的大语言模型已经非常强大,可以解决许多问题,但在处理复杂情况时,仍然需要进行多个步骤或整合不同的流程才能达到最终的目标。然而,现在可以利用langchain来使得模型的应用变得更加直接和简单。 LCEL是什么&…

每天五分钟深度学习框架pytorch:多维tensor向量在某一维度的拼接和分割

本文重点 在深度学习中,我们常常需要完成多个向量拼接,同时也要完成向量的分割,在pytorch中已经有封装好的库,我们可以直接调用完成这部分任务。 Cat拼接 c=torch.cat([a,b],dim=0)表示将a和b按0维度进行拼接,需要注意再非dim维度,两个矩阵的维度必须是一致的,不然会拼…

单调栈(续)、由斐波那契数列讲述矩阵快速降幂技巧

在这里先接上一篇文章单调栈,这里还有单调栈的一道题 题目一(单调栈续) 给定一个数组arr, 返回所有子数组最小值的累加和 就是一个数组,有很多的子数组,每个数组肯定有一个最小值,要把所有子…

Caffe、PyTorch、Scikit-learn、Spark MLlib 和 TensorFlowOnSpark 概述

在 AI 框架方面,有几种工具可用于图像分类、视觉和语音等任务。有些很受欢迎,如 PyTorch 和 Caffe,而另一些则更受限制。以下是四种流行的 AI 工具的亮点。 Caffee Caffee是贾扬青在加州大学伯克利分校(UC Berkeley)时开发的深度学习框架。该工具可用于图像分类、语音和…

MySQL中的复合查询与表的内外连接解析

在MySQL中,复合查询通常指的是涉及多个表或多个查询条件的查询。而表的内外连接(INNER JOIN、LEFT JOIN、RIGHT JOIN 和 FULL OUTER JOIN,但MySQL不直接支持FULL OUTER JOIN)则是复合查询中常用的连接技术,用于从多个表…

【websocket】怎么终止websocket断开重连

介绍 代码是用go语言实现的。go语言实现websocket,常用第三方库github.com/gorilla/websocket。 不过只要明白了思路,不管哪个语言实现起来都是一样的。 问题 在生产环境,websocket客户端一般都会实现断开重连的逻辑,如果直接…

胡说八道(24.6.12)——数字电子技术以及Modelsim

上回书说到数电中的最常用的表达式——逻辑表达式(由布尔代数组成)以及常用的两种图表——真值表(真值表表示的是所有的输入可能的线性组合以及输出)和卡诺图(卡诺图则是一种化简工具,排除冗余项,合并可合并项)。 今天,先来看看昨天说的基本逻…

DP:01背包问题

一、背包问题的概述 背包问题是⼀种组合优化的NP完全问题。 本质上是为了找出“带有限制条件的组合最优解” 1、根据物品的个数,分为如下几类: • 01背包问题:每个物品只有⼀个(重点掌握)• 完全背包问题&#xff1…

ffmpeg封装和解封装介绍-(10)综合完成视频重编码为h265,解封装解码编码再封装

主函数逐句解析: 由于代码太多我们只解析主函数,(其他封装函数见前面文章,同时用到了解码编码封装代码)。 初始化和参数处理 int main(int argc, char* argv[]) {/// 输入参数处理string useage "124_test_x…

【计算机网络】已解决:“‘ping‘ 不是内部或外部命令,也不是可运行的程序或批处理文件”报错

文章目录 一、问题分析背景二、可能出错的原因三、错误代码示例四、正确解决方法与示例五、注意事项 已解决“‘ping’ 不是内部或外部命令,也不是可运行的程序或批处理文件”报错 一、问题分析背景 在Windows操作系统中,ping 命令是一个常用的网络诊断…

线程池ThreadPoolExecutor使用指南

线程池ThreadPoolExecutor使用指南 🧐使用线程池的好处是什么? 统一管理,减少资源获取创建的开销,提高利用率。 🔧线程池的参数 ​ThreadPoolExecutor​ 3 个最重要的参数: ​corePoolSize​ : 任务队列…

docker login 报错: http: server gave HTTP response to HTTPS client

环境: 自建 Harbor、Docker 1. 问题分析 # 命令,这里用的是 IP,可以为域名 docker login -u test 172.16.51.182:31120 # 输入密码 Password:# 报错如下: Error response from daemon: Get "https://172.16.51.182:31120/…

HIVE及SparkSQL优化经验

简介 针对高耗跑批时间长的作业,在公司近3个月做过一个优化专项;优化成效:综合cpu、内存、跑批耗时减少均在65%以上; cpu和内存消耗指的是:vcoreseconds和memoryseconds 这里简单说下优化的一些思路,至于…

[Algorithm][贪心][增减字符串匹配][分发饼干][最优除法][跳跃游戏Ⅱ][跳跃游戏]详细讲解

目录 1.增减字符串匹配1.题目链接2.算法原理详解3.代码实现 2.分发饼干1.题目链接2.算法原理详解3.代码实现 3.最优除法1.题目链接2.算法原理详解3.代码实现 4.跳跃游戏 II1.题目链接2.算法原理详解3.代码实现 5.跳跃游戏1.题目链接2.算法原理详解3.代码实现 1.增减字符串匹配 …

图神经网络pytorch_geometric库之MessagePassing类

MessagePassing是图神经网络Python库pytorch_geometric(PyG)库里非常重要的一个基类,它可以用来创建消息传递图神经网络,pytorch_geometric里很多类比如图卷积层GCNConv和图注意力层GATConv都基于此类实现,我们也可以基于它来自定义图神经网络…

期末复习6--链表头插法(逆序)尾插法(顺序)---输出链表

头插法 #include <stdio.h> #include <stdlib.h>struct Node //定义结构体 {char data; //数据域struct Node * next; //指针域 };/* 请在这里填写答案 */void PrintList (struct Node * head) {struct Node * s;if(head NULL){printf("None&qu…

mybatisplus 笔记

int isDelete userRoleMapper.delete(new LambdaQueryWrapper<UserRole>().in(UserRole::getUserId, roleUserDTO.getUserId()).in(UserRole::getRoleId, roleUserDTO.getRoleId()));LambdaQueryWrapper<UserRole>: LambdaQueryWrapper 是 MyBatis Plus 提供的一个…

Apipost模拟HTTP客户端

模拟HTTP客户端的软件有很多&#xff0c;其中比较著名的就有API-FOX、POSTMAN。 相信很多小伙伴都使用POSTMAN。这篇博客主要介绍Apipost的原因是&#xff0c;Apipost无需下载&#xff0c;具有网页版。 APIFOX的站内下载&#xff1a; Api-Fox&#xff0c;类似于PostMan的软件…