REST

文章目录

• REST简介
• REST风格的架构
• 使用“api”作为上下文
• 增加一个版本标识
• 标识资源
• 确定HTTP Method
• 确定HTTP Status

REST简介

REST，即Representational State Transfer的缩写，翻译为“表现层状态转化”，如果一个架构符合REST原则，则称其为RESTful架构。

• 资源（Resources）
  REST的名称“表现层状态转化”，表现层指的是“资源”的“表现层”。

所谓“资源”，就是网络上的一个实体，或者说是网络上的一个具体信息，它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实体。可以用一个具体的URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以。
因此URL就成了每个资源的地址或第一无二的标识符。

• 表现层

“资源”是一种信息实体，可以有多种外在表现形式。将“资源”具体呈现出来的形式称之为“表现层”。比如，文本可以用txt格式表现，也可用HTML格式、XML格式、JSON格式等。

URI只代表资源的实体，不代表它的形式。它的具体表现形式应该在HTTP请求的头信息中用Accept和Content-Type字段指定。

• 状态转化
  访问一个网站。就代表了客户端和服务器的一个互动过程，这个过程中，势必涉及和状态的变化。

HTTP协议是一个无状态互联网通信协议，这意味着所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生“状态转化”。而这种转化是建立在表现层之上的，所以就是“表现层状态转化”。

URI：统一资源标识符
URL：统一资源定位符

REST风格的架构

包括了REST架构中如何标识资源，如何标识操作接口以及操作的版本，如何标识操作的结果等，如：

• 使用“api”作为web上下文；
• 增加版本标识；
• 标识资源；
• REST中的HTTP Method；
• REST中的HTTP Status；

使用“api”作为上下文

建议使用“api”作为上下文，如：

http://localhost/api
http://api.xxx.com

增加一个版本标识

http://localhost/api/v1.1

标识资源

将资源名称放到URL中，如果资源有层级关系，则放入层级关系：

http://localhost:/api/v1.1/user
//如果用户属于系统管理，则：
http://localhost:/api/v1.1/system/user

确定HTTP Method

在REST中，HTTP Method通常对应以下含义：

• POST：代表增加资源；
• PUT：代表更改资源，客户端提供完整的资源属性；
• GET：代表查询资源；
• PATCH：更新资源，客户端提供仅需要更改的资源属性；
• DELETE：删除资源；
• OPTIONS：用于获取URI所支持的方法，响应信息会在HTTP头中包含一个名为“Alllow”的头，值是所支持的方法，如“GET”、“POST”。

在业务系统中，删除往往不是指物理删除，而是逻辑删除，资源通常仍在数据库中，只是状态设置为删除状态。

确定HTTP Status

服务器向客户端返回HTTP Status以表示操作是否成功，常用的如下：

• 200，OK，用户请求成功，如查询数据成功返回。
• 400，错误的请求，如URI匹配上的Controller，但是方法参数匹配错误，就会抛出错误。
• 404NOT Found，用户发出的请求针对的资源不存在。通常是Controller没有匹配上URI，或者匹配上了Controller方法，但渲染的视图不存在。
• 405，用来访问本页面的HTTP Method不被允许，比如通过HTTP GET方式访问了一个@PostMapping的Controller方法。
• 406，表示无法使用请求的内容来响应请求的资源，如请求后缀以html结尾，但同时请求的HTTP头中又包含了Accept:application/json。
• 500，服务器内部错误，无法完成请求，通常是Controller抛出的错误。