SpringBoot - RESTful接口命名及参数路径编写规范

╰+攻爆jí腚メ 2023-10-08 15:46 39阅读 0赞

#### 什么是REST? ####

REST（Representational State Transfer ），有中文翻译为"具象状态传输"（也有：“代表性状态传输”）。是由 Roy Thomas Fielding博士在2000年就读加州大学欧文分校期间在学术论文中提出的一个术语。他首次系统全面地阐述了REST的架构风格和设计思想，这篇论文是WEB发展史上一篇非常重要的技术文献，他也为WEB架构的设计与评判奠定了理论基础。他在论文中提到：“我这篇文章的写做目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，获得一个功能强、性能好、适宜通讯的架构。REST指的是一组架构约束条件和原则。” 若是一个架构符合REST的约束条件和原则，咱们就称它为RESTful架构。

如果想理解RESTful的架构风格，理解REST，首先要理解REST这个单词的组成：

*  资源（Resources）：REST的名称是"表现层状态转化"，其实是资源(Resources)的"表现层状态转化"。这里所谓的"资源"，其实就是网络上存储的一个具体信息或数据，它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的数据。我们可以用一个URI（统一资源标识符）指向这些资源，每种资源都对应一个特定的URI。要获取这个资源，通过访问它对应的URI就可以了，因此该URI就代表了每一个资源的地址或独一无二的识别符号。
 *  表述性（REpresentational）：“资源"是一种信息实体，它可以有多种外在的表现形式，我们把"资源"具体呈现出来的形式，叫做它的"表现层”(Representation)。REST 资源实际上可以用各种形式来进行表现，比如文本可以用TXT格式、HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现，我们可以使用最适合资源的任意形式。
 *  状态（State）：当使用REST时，我们更关注资源的状态而不是对资源采取的行为。
 *  转义（Transfer）：REST涉及到转移资源数据，它以某种表述性形式从一个应用转移到另一个应用。

#### 什么是RESTful？ ####

RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式或JSON格式进行定义。RESTFUL适用于移动互联网厂商作为业务接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源。

#### 用一句话总结 ####

REST是设计原则和约束条件；RESTFUL是设计风格和开发方式。

#### 接口设计原则 ####

接口单一且明确，在明确接口职责的条件下，尽量做到接口单一，即一个接口只做一件事，而非两件以上。

#### 接口协议规范 ####

在设计接口时，应明确接口协议，根据具体情况可以采用HTTP、HTTPS或者FTP协议。

*  FTP协议(File Transfer Protocol，简称FTP)，是一套标准的文件传输协议主要用于传输文件；
 *  HTTP协议，适用一般对安全性要求比较低或没要求的业务情景；
 *  HTTPS=HTTP+SSL,适用于对安全性要求较高的业务情景；

#### 接口动词说明 ####

对于资源的具体操作类型，由HTTP动词表示，前五个为常用的HTTP动词，后面两个是不常用的动词（括号里是对应的SQL命令）。

1.  GET（SELECT）：用于检索，从服务中取出一项或多项资源；
2.  POST（CREATE）：用于创建，通过服务新建一个资源。
3.  PUT（UPDATE）：用于更新，通过服务更新已有资源，客户端提供改变后的完整资源对象，而非实体的部分属性；
4.  PATCH（UPDATE）：用于更新，通过服务更新已有资源，客户端仅提供实体改变的部分属性；
5.  DELETE（DELETE）：用于删除，通过服务删除已有资源；
6.  HEAD：获取资源的元数据；
7.  OPTIONS：获取哪些属性是客户端可以改变的资源信息。

#### 路径命名规范 ####

[JAVA基础 - URI、URL和URN的区别][JAVA_ - URI_URL_URN]

命名规范：URL采用小写字母，数字，部分特殊符号（非制表符）组成  
URL的前半部分，按照分级分段的方式：/项目名/模块名/API版本/方法，如：/mallx/mallx-spu/api/v1/list  
项目名和模块名：不采用大小写混合的驼峰命名方式，尽量采用全小写单词，如果需要连接多个单词，则采用连接符“-”连接单词，即采用脊柱命名，如：mallx-spu。  
参数命名：采用驼峰命名，如：  
http://localhost:8719/metric?identity=XXX&startTime=XXXX&endTime=XXXX&maxLines=XXXX

#### 参数路径规范 ####

[SpringBoot - @RequestMapping/@GetMapping/@PostMapping/@PutMapping/@DeleteMapping注解使用详解][SpringBoot - _RequestMapping_GetMapping_PostMapping_PutMapping_DeleteMapping]  
[SpringBoot - @PathVariable/@RequestParam/@RequestBody注解使用详解][SpringBoot - _PathVariable_RequestParam_RequestBody]

平级关系：参数之间不存在从属关系的就是平级关系，如：/mallx/mallx-spu/api/v1/list?page=1&size=20&state=1  
从属关系：参数之间存在从属关系的，如获取某个用户的某个收货地址，则参数采用路径命名，如：/mallx/mallx-user/api/v1/user/\{id\}/address/\{id\}

[JAVA_ - URI_URL_URN]: https://blog.csdn.net/goodjava2007/article/details/125406586?spm=1001.2014.3001.5502
[SpringBoot - _RequestMapping_GetMapping_PostMapping_PutMapping_DeleteMapping]: https://blog.csdn.net/goodjava2007/article/details/125421921?spm=1001.2014.3001.5501
[SpringBoot - _PathVariable_RequestParam_RequestBody]: https://blog.csdn.net/goodjava2007/article/details/125424441?spm=1001.2014.3001.5501