前后端接口设计规范

设计规范原则

1. 前端应只关注渲染逻辑，而不应该关注数据的处理逻辑。接口返回的数据应该是能够直接展示在界面上的。
2. 一个功能应避免多个接口嵌套调用获取数据，后台应该处理好一次性返回。
3. 响应格式应该是JSON，而且应避免多级JSON的出现；
4. 后端如果需要界面实时刷新数据，不应该要求前端定时器轮询，而要提供类似webSocket之类的功能。

根据这个原则，后端返回的数据应该是所见即所得的数据，而不应该是一层包一层的复杂的JSON，需要前端额外来处理很复杂的去重，排序、深浅拷贝，变形等处理。前端在渲染每一个div，每一个table的cell时，不用担心数据结构会频繁更改从而导致页面崩溃。

接口制定的全流程

前端请求一般是HTTP协议，这里以HTTP为例。

HTTP请求的协议类型

应使用下面罗列的HTTP方法（使用的SQL关键字）:

GET（SELECT）：从服务器取出资源，一项或多项。

POST（CREATE）：在服务器新建一个资源。

PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性），使用比较少

DELETE（DELETE）：从服务器删除资源。

下面是一些例子:

GET /schools：列出所有的学校列表

POST /school：新建一个学校

GET /school/{id}：获取某个指定学校的信息

PUT /school/{id}：更新某个指定学校的信息（提供该学校的全部信息，而不是让前端再通过别的接口获取）
PATCH /school/{id}：更新某个指定学校的信息（提供该学校的部分信息）

DELETE /school/{id}：删除某个学校
HTTP请求的参数定义

不同HTTP方法对应不同的参数传递方式，如下：

query指路径传参，body指requestBody请求体

  • GET：path & query
  • POST：path & body
  • PUT：path & query & body
  • PATCH：path & query & body
  • DELETE：path & query

注意：

  1. 未出现在上表中的位置不可放置参数，如GET方法不可在body中放置参数。
  2. 参数命名均遵循小驼峰命名法。
  3. path和query中传递的参数需确保长度可控，超过2000字符（因浏览器而异）的参数可导致请求失败。当请求无法保证参数长度可控，则不能将参数放在path或query中，必须使用支持body参数的HTTP方法，如POST。
  4. path和query中传递的参数需是基本类型，亦不可传递序列化之后的JSON对象！不然前端就要try/catch一下来parse了。
  5. body中的参数需是合法JSON对象或者formData，即使参数仅包含单字段或单数组，也需包含在对象中，如：
{name: string;
}
HTTP响应结果定义

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collections：返回资源对象的列表（数组）

{RetCode: 0,Message: 'ok',Action: 'collections',Data: [{Id: 1,name: 'collection1',...},...]
}

GET /collection/resource：返回单个资源对象

{RetCode: 0,Message: 'ok',Action: 'collectionResource',Data: {Id: 1,name: 'collection1',...}
}

POST /collection：返回新生成的资源对象

{RetCode: 0,Message: 'ok',Action: 'collection',Data: {Id: 1,name: 'collection1',...}
}

PUT /collection/resource：返回完整的资源对象， 返回结果同上。
PATCH /collection/resource：返回完整的资源对象，返回结果同上。
DELETE /collection/resource：返回一个空文档

{RetCode: 0,Message: 'ok',Action: 'collectionResource',Data: {}
}

注意：

  1. 所有返回数据需是合法JSON，尽量返回object或者array (二进制文件下载除外)。如果数据中包含类型为array的属性，当数据为空时，尽量返回空数组[]，避免返回null。
  2. 返回数据避免使用map的<‘key’, ‘value’>形式！如有相关格式的返回数据，请转换为array。
  3. 如果没有数据需要返回，或系统报错时，可统一返回固定字段：
  4. 返回值中应尽量避免包含无用信息，或者额外的数据结构，仅包含必要数据即可。必要数据指前端需要渲染的数据。
  5. 后端异常报错均以’500’状态码的形式返回，也可适当添加额外信息，非特殊情况无需在返回的数据体中返回HTTP code。
{RetCode: number; // 后端状态码Message: string; // 请求返回消息Action: string; // 请求的响应关键字Data: Object | Array; // 响应数据
}

URL规范

可参照下面的范例：

GET [http | https]://host:port/studio/api/组件名/v1/模块名/菜单名/接口名/:param

注意：

  1. 不用大写字母，建议用中杠 - 不用下杠 _. 比如邀请码写成invitation-code而不是invitation_code
  2. 使用名词表示资源集合，使用复数形式（为确保所有API URIs保持一致），不能使用动词；
  3. 每个资源都至少有一个标识它的URI，同时应该遵循一个可预测的层次结构来提高可理解性，从而提高可用性；
  4. 宾语必须是名词。网址中不能有动词，只能有名词，API中的名词也应该使用复数，宾语就是API的URL，是HTTP动词作用的对象。它应该是名词，不能是动词

正🌰 ：

GET /classes：列出所有班级
POST /classes：新建一个班级
GET /classes/{classId}：获取某个指定班级的信息
PUT /classes/{classId}：更新某个指定班级的信息（一般倾向整体更新）
PATCH /classes/{classId}：更新某个指定班级的信息（一般倾向部分更新）
DELETE /classes/{classId}：删除某个班级
GET /classes/{classId}/teachers：列出某个指定班级的所有老师的信息
GET /classes/{classId}/students：列出某个指定班级的所有学生的信息
DELETE classes/{classId}/teachers/{teacherId}：删除某个指定班级下的指定的老师的信息

反例：

/getAllclasses
/createNewclass
/deleteAllActiveclasses

复数还是单数URL问题： 既然 URL 是名词，那么应该使用复数，还是单数？这没有统一的规定，但是常见的操作是读取一个集合，比如GET /articles（读取所有文章），这里明显应该是复数，而获取单个可以用GET /article/2。 当然，你可以为了统一起见，都使用复数URL，比如GET /articles/2。

多级URL的处理：当查询资源信息较多时，往往会有多级参数出现在URL中，此处要分三种情况讨论：

查询信息指代当层唯一id，将查询信息放在path中，构建唯一的查询路径，如：

GET /authors/12/categories/2

查询信息属于对当层信息的状态过滤，将查询信息放在query中，如：

GET /articles?published=true

查询信息既包含当层id，也包含过滤信息，分别将id和过滤信息放在path和query中，如：

GET /authors/12/categories/2?published=true

HTTP状态码约束

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。HTTP 状态码就是一个三位数，分成五个类别。

1xx：相关信息

2xx：操作成功
3xx：重定向
4xx：客户端错误
5xx：服务器错误

状态码规范见W3C关于HTTP状态码定义

分页与搜索接口约束

分页接口广泛出现在数据量较大场景下的表格型交互。即使是渲染简单的列表元素，超过500项有可能导致前端卡顿，超过5000项以上（不同浏览器、电脑配置会影响这个数字）有可能导致前端崩溃。凡无法保证能限制接口返回数量在一个较小数量级（100以下）的接口都需要考虑支持后端分页；如果返回结果数量是不受控制的（如包含用户生成数据），则必须支持后端分页。
这里给出请求范例：
GET 接口

?page={page}&size={size}

POST 接口

// 格式1
{page: number;size: number;total: number; // 数据总量
}// 格式2
{Limit: number;Offset: numberTotal: number; // 数据总量
}
// 其中page为当前请求页，为从0开始的正整数；
// size为当前页大小，常用的值有10、20等，理论上需支持任意正整数。特殊的，若为-1，可以约定为查询全部
// Limit同size
// Offset为相对偏移量，为从0开始的正整数

需要注意的是，如果交互中出现过滤、排序功能，则相关功能必要时都需要后端支持。如果参数能保证不超过一定长度，则参数放在query里也是可以接受的。数组型参数可以以相关字段用逗号连接的形式传递，如：

?status=RUNNING,COMPLETE,ERROR

特殊类型处理

关于Boolean类型，JSON数据传输中使用true/false字段进行传递。
关于日期类型，JSON数据传输中一律使用长整形时间戳（Unix time）进行传递，具体日期显示格式由前端处理。

注意事项

任何形式的接口变更都会对前端产生影响，比如字段名称的修改，字段的增减，字段类型的修改，请求参数类型的变动等。原则上当接口对接完成后不应有任何形式的修改，如果一定要变更接口，需及时通知相应前端开发人员并重新对接。
表示同一含义的字段在同一套功能接口集合（增删改查）中应尽量保证相同。在接口设计中，对同一实体进行操作的接口应尽量保证在参数和返回值中，该实体的数据结构保持一致，尽量避免前端做数据对象转换的动作。

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

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

相关文章

hbase thrift2 jar包冲突导致启动失败问题排查记录

hbase thrift2 jar包冲突导致启动失败问题排查记录

1、启动命令 ${HBASE_HOME}/bin/hbase-daemon.sh start thrift2 2、异常情况 hbase-root-thrift2-hdfs-test07.yingzi.com.out异常日志&#xff1a; Exception in thread "main" java.lang.AbstractMethodError: org.apache.hadoop.metrics2.sink.timeline.Hadoo…
阅读更多...
3分钟在CentOS 7上离线安装Docker

3分钟在CentOS 7上离线安装Docker

在CentOS 7上离线安装Docker的详细步骤如下&#xff1a; 环境检查和准备 检查内核版本&#xff1a;Docker要求系统为64位且内核版本至少为3.10。使用命令uname -r查看内核版本。 检查CentOS版本&#xff1a;通过命令cat /etc/redhat-release查看版本信息。 更新yum包&#xff0…
阅读更多...
java中强引用、软引用、弱引用、虚引用的区别是什么？

java中强引用、软引用、弱引用、虚引用的区别是什么？

Java中的引用类型主要分为强引用、软引用、弱引用和虚引用&#xff0c;它们之间的区别主要体现在垃圾回收的行为上。 强引用&#xff08;Strong Reference&#xff09;&#xff1a;这是使用最普遍和默认的引用类型。如果一个对象具有强引用&#xff0c;那么垃圾回收器就永远不会…
阅读更多...
Nginx(十二) gzip gzip_static sendfile directio aio 组合使用测试(2)

Nginx(十二) gzip gzip_static sendfile directio aio 组合使用测试(2)

测试10&#xff1a;开启gzip、sendfile、aio、directio1m&#xff0c;关闭gzip_static&#xff0c;请求/index.js {"time_iso8601":"2023-11-30T17:20:5508:00","request_uri":"/index.js","status":"200","…
阅读更多...
【Java Web学习笔记】4 - DOM文档对象模型

【Java Web学习笔记】4 - DOM文档对象模型

项目代码 https://github.com/yinhai1114/JavaWeb_LearningCode/tree/main/javascript 零、在线文档 JavaScript HTML DOM 一、HTML DOM基本介绍 1. DOM全称是Document Object Model文档对象模型 文档<---映射--->对象 2.就是把文档中的标签&#xff0c;属性&#xf…
阅读更多...
WebSocket入门介绍及编程实战

WebSocket入门介绍及编程实战

HTTP的限制 全双工和半双工&#xff1a; 全双工&#xff1a;全双工&#xff08;Full Duplex&#xff09;是允许数据在两个方向上同时传输。 半双工&#xff1a;半双工&#xff08;Half Duplex&#xff09;是允许数据在两个方向上传输&#xff0c;但是同一个时间段内只允许一个…
阅读更多...
【2】基于多设计模式下的同步异步日志系统-设计模式

【2】基于多设计模式下的同步异步日志系统-设计模式

6. 相关技术知识补充 6.1 不定参函数 在初学C语⾔的时候&#xff0c;我们都⽤过printf函数进⾏打印。其中printf函数就是⼀个不定参函数&#xff0c;在函数内部可以根据格式化字符串中格式化字符分别获取不同的参数进⾏数据的格式化。 ⽽这种不定参函数在实际的使⽤中也⾮常…
阅读更多...
二十三种设计模式全面解析-解放组件间的通信束缚：深入探讨中介者模式的高级应用和进阶技巧

二十三种设计模式全面解析-解放组件间的通信束缚：深入探讨中介者模式的高级应用和进阶技巧

在软件开发中&#xff0c;组件之间的通信往往是不可避免的。然而&#xff0c;随着系统规模的增大和组件之间的相互依赖关系复杂化&#xff0c;直接的组件间通信往往会导致代码耦合度过高、可维护性下降等问题。为了解决这些问题&#xff0c;中介者模式应运而生。中介者模式通过…
阅读更多...
解决 引element-plus依赖时的core-js报错

解决 引element-plus依赖时的core-js报错

参考资料&#xff1a; https://blog.csdn.net/weixin_42164539/article/details/123388542 本人正在重构两年前搭建到一半的博客网站&#xff0c;相关依赖都很陈旧&#xff0c;用到了 npm-check-updates 检测项目可升级依赖&#xff1a; 补依赖过程始中报错 解决方案&#xf…
阅读更多...
linux 内核同步互斥技术之信号量

linux 内核同步互斥技术之信号量

信号量 信号量允许多个进程同时进入临界区&#xff0c;大多数情况下只允许一个进程进入临界区&#xff0c;把信号量的计数值设置为 1&#xff0c;即二值信号量&#xff0c;这种信号量称为互斥信号量。可允许多个锁持有者。 和自旋锁相比&#xff0c;信号量适合保护比较长的临界…
阅读更多...
Java-宋红康-（P133-P134)-多线程创建方式(Thread and Runnable)

Java-宋红康-（P133-P134)-多线程创建方式(Thread and Runnable)

b站视频 133-多线程-线程创建方式1&#xff1a;继承Thread类_哔哩哔哩_bilibili 目录 3.1 继承Thread 3.1.1 继承Thread类方式 3.1.2 线程的执行流程 3.1.3 线程内存图 3.1.4 run()方法和start()方法 3.1.5 线程名字的设置和获取 3.1.6 获取运行main方法线程的名字 3.…
阅读更多...
Linux进程间通信之共享内存

Linux进程间通信之共享内存

&#x1f4df;作者主页&#xff1a;慢热的陕西人 &#x1f334;专栏链接&#xff1a;Linux &#x1f4e3;欢迎各位大佬&#x1f44d;点赞&#x1f525;关注&#x1f693;收藏&#xff0c;&#x1f349;留言 本博客主要内容讲解共享内存原理和相关接口的介绍&#xff0c;以及一个…
阅读更多...
更换cmd下默认选择Python解释器

更换cmd下默认选择Python解释器

问题 我的电脑里有多个Python解释器&#xff0c;一个是自己下载的python37&#xff0c;版本是3.7.0&#xff0c;一个是anaconda的base环境&#xff0c;版本是3.7.4&#xff0c;还有虚拟环境里的python解释器。 最近发现&#xff0c;在cmd下输入python&#xff0c;使用的是anac…
阅读更多...
肺是人体的第一道防线，流感频发季节，最有效的养肺方法你得知道！

肺是人体的第一道防线，流感频发季节，最有效的养肺方法你得知道！

肺脏是人体的第一道防线&#xff0c;牵动着整个呼吸道的健康&#xff0c;一旦肺脏受损&#xff0c;易引发咳嗽、气喘甚至肺炎。在流感、呼吸道疾病高发的冬季&#xff0c;如何呵护肺脏&#xff0c;保持身体健康&#xff1f; 全民养肺&#xff0c;刻不容缓 养肺不仅仅是中老年朋…
阅读更多...
深入浅出之中央空调体系架构及楼宇自控系统

深入浅出之中央空调体系架构及楼宇自控系统

一、关于建筑节能 1、建筑能耗 在中国&#xff0c;建筑能耗占社会总能耗45.5%。来源&#xff1a;《中国建筑能耗研究报告&#xff08;2022&#xff09;》 2、空调、采暖、照明占比最高 建筑节能是指在保证、提高建筑舒适性和生活质量的条件下&#xff0c;在建筑物使用的全过…
阅读更多...
12.5 作业

12.5 作业

1&#xff0c; 以下是一个简单的比喻&#xff0c;将多态概念与生活中的实际情况相联系&#xff1a; 比喻&#xff1a;动物园的讲解员和动物表演 想象一下你去了一家动物园&#xff0c;看到了许多不同种类的动物&#xff0c;如狮子、大象、猴子等。现在&#xff0c;动物园里有…
阅读更多...
RocketMQTemplate 发送消息的高级用法

RocketMQTemplate 发送消息的高级用法

Apache RocketMQ 是一款强大的分布式消息中间件&#xff0c;与 Spring Boot 集成后&#xff0c;通过 RocketMQTemplate 可以实现在应用程序中方便地发送消息。在本文中&#xff0c;我们将深入探讨 RocketMQTemplate 的一些高级用法&#xff0c;以提供更灵活的消息发送和控制。 …
阅读更多...
7天快速学习计算机基础必考八股文day02：操作系统

7天快速学习计算机基础必考八股文day02：操作系统

day02操作系统目录一览图 请简述对进程的理解——操作系统的进程详解请简述同步与异步的区别——进程状态模型详解请简述进程和线程的区别——操作系统线程详解请简述什么是操作系统的内核态——用户态与内核态详解IO密集型任务部署需要注意什么——程序运行类型分析协程是什么…
阅读更多...
找鞍点(PTA)

找鞍点(PTA)

先找出每一行的max&#xff0c;然后在判断这个数是不是这一列的min #include <stdio.h> int main() { int i 0; int i1 0; int j1 0; int k 0; int j 0; int arr[6][6] { 0 }; int n 0; int i2 0; int max 0; int min…
阅读更多...
【Qt开发流程】之对象模型2：属性系统

【Qt开发流程】之对象模型2：属性系统

描述 Qt提供了一个复杂的属性系统&#xff0c;类似于一些编译器供应商提供的属性系统。然而&#xff0c;作为一个独立于编译器和平台的库&#xff0c;Qt不依赖于非标准的编译器特性&#xff0c;如__property或[property]。 Qt解决方案适用于Qt支持的所有平台上的任何标准c编译…
阅读更多...
最新文章

Copyright @ 2022~2023