架构

发布日期: 2022-06-10

文章字数: 1.7k

阅读时长: 6 分

阅读次数:

目录：

Restful概念

具体规范

2.1 格式规范

2.2 协议

2.3 域名

2.4 版本

2.5 名词应该使用复数

2.6 URL中不能使用动词

2.7 不符合CRUD的情况

2.8 用HTTP动词表示对资源的操作

2.9 HTTP状态码

2.10 其它

参考/来源：

https://mp.weixin.qq.com/s/cnAFVJJAd0pixHTXwg1KUQ

RESTful概念

在此之前，我们先聊聊什么是REST。REST实际上为Representational State Transfer的缩写，翻译为“表现层状态转化” 。如果一个架构符合REST 原则，就称它为RESTful架构。

Resource 资源

REST忽略了主语，全称应该是资源的表现层状态转移。所谓资源就是互联网上的各种资源，比如文本、图片、音频、视频等。在互联网上通过URI指定唯一的资源，所谓的’上网‘就是通过调用资源的URL来跟互联网上的一系列资源进行互动。

注：URI只代表资源的实体，严格地说，有些网址最后的.html后缀名是不必要的，因为这个后缀名表示格式，属于”表现层”范畴，而URI应该只代表”资源”的位置。
Representational 表象

资源可以有各种具体的表现形式，比如文本可以有xml格式，html格式，json格式，甚至是二进制格式，图片可以有PNG格式，JPEG格式等。资源的一个具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对”表现层”的描述。
State Transfer 状态转移

通过http动词来实现资源的状态转移，用GET来请求资源，用POST来新建资源，用PUT来更新资源，用DELETE来删除资源。

下面对比下传统URL请求和RESTful风格请求的区别：

描述	传统请求	方法	RESTful请求	方法
查询	/user/query?name=mrbird	GET	/user?name=mrbird	GET
详情	/user/getInfo?id=1	GET	/user/1	GET
创建	/user/create?name=mrbird	POST	/user	POST
修改	/user/update?name=mrbird&id=1	POST	/user/1	PUT
删除	/user/delete?id=1	GET	/user/1	DELETE

从上面这张表，我们大致可以总结下传统请求和RESTful请求的几个区别：

传统请求通过URL来描述行为，如create，delete等；RESTful请求通过URL来描述资源。
RESTful请求通过HTTP请求的方法来描述行为，比如DELETE，POST，PUT等，并且使用HTTP状态码来表示不同的结果。
RESTful请求通过JSON来交换数据。

RESTful只是一种风格，并不是一种强制性的标准。

Spring Boot中包含了一些注解，对应于HTTP协议中的方法：

@GetMapping对应HTTP中的GET方法；
@PostMapping对应HTTP中的POST方法；
@PutMapping对应HTTP中的PUT方法；
@DeleteMapping对应HTTP中的DELETE方法；
@PatchMapping对应HTTP中的PATCH方法。

具体规范

格式规范

根据RFC3986定义，URL是大小写敏感的。所以为了避免歧义，尽量使用小写字母。

RESTful API 应具备良好的可读性，当url中某一个片段（segment）由多个单词组成时，建议使用 - 来隔断单词，而不是使用 _。这主要是因为，浏览器中超链接显示的默认效果是文字并附带下划线，如果API以_隔断单词，二者会重叠，影响可读性。

/api/featured-post/     # GOOD
/api/featured_post/     # WRONG

协议

提供给用户的API，总是使用HTTPs协议。使用HTTPs协议还是HTTP协议本身和RESTful API并无关系，但是这对于提高网站的安全性很重要。

域名

API应该放在专有域名下，比如https://api.example.com/v1。也可以简单地把版本放在URL中，比如https://www.example.com/api/v1

版本

API的版本号应该放在URL中：

https://api.example.com/v1/

名词应该使用复数

所用的名词往往和数据库的表名对应，而数据库的表是一组记录的集合，因此URL中的名词即表示一组资源的集合，故URI中的名词要使用复数

https://api.example.com/v1/students
https://api.example.com/v1/schools
https://api.example.com/v1/employees

URL中不能使用动词

URI代表着一个资源，是一个实体，应该是名词，而不要把具体的动作放在URL中，对资源的操作应该通过HTTP的动词来实现。

不符合CRUD的情况

如果实在无法表示，也可使用动词，例如search没有对应的HTTP方法，可以在路径中使用search，更加直观

http://api.xxx.com/apiv3/search?timestamp=123213218&user_id=4192121&keyword=2134789。

再例如创建了博客网站，如果想要发布一个博客，可以使用POST /articles/{:id}/publish

用HTTP动词表示对资源的操作

使用HTTP协议里的动词来实现资源的获取、删除、添加等操作

GET：从服务器获取资源
POST：在服务器新建一个资源
PUT：在服务器更新资源（客户端提供改变后的完整资源）
PATCH：在服务器更新资源（客户端提供改变的属性）
DELETE：从服务器中删除资源

GET     https://api.example.com/v1/schools                  # 列出所有学校
POST    https://api.example.com/v1/schools                  # 新建一个学校
GET     https://api.example.com/v1/schools/ID               # 列出指定学校的信息
DELETE  https://api.example.com/v1/schools/ID               # 删除指定学校

GET     https://api.example.com/v1/schools/ID/students      # 列出指定学校的所有学生
DELETE  https://api.example.com/v1/schools/ID/students/ID   # 删除指定学校的指定学生