Spring Boot Restful

一、概念术语

Rest(Representational State Transfer)译为“表现层状态转化”,用以实现一个功能强、性能好、适宜通信的软件和网络间的通信架构。

RESTful架构,是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。用于替代传统的RPC和SOAP。

1.1 理解RESTful

要理解RESTful架构,需要理解Representational State Transfer这个词组到底是什么意思,它的每一个词都有些什么涵义。

下面我们结合REST原则,围绕资源展开讨论,从资源的定义、获取、表述、关联、状态变迁等角度,列举一些关键概念并加以解释。

  • 资源与URI
  • 统一资源接口
  • 资源的表述
  • 资源的链接
  • 状态的转移

1.2 资源与URI

REST全称是表述性状态转移,那究竟指的是什么的表述? 其实指的就是资源。任何事物,只要有被引用到的必要,它就是一个资源。资源可以是实体(例如手机号码),也可以只是一个抽象概念(例如价值) 。下面是一些资源的例子:

  • 某用户的手机号码
  • 某用户的个人信息
  • 最多用户订购的GPRS套餐
  • 两个产品之间的依赖关系
  • 某用户可以办理的优惠套餐
  • 某手机号码的潜在价值

1.3 安全

执行HTTP的动作时不会修改资源。

1.4 幂等

无论HTTP请求多少次结果都一样。

1.5 HTTP方法

动作 安全/幂等 用途
GET Y/Y 获取资源
POST N/N 创建资源
PUT N/Y 更新资源
DELETE N/Y 删除资源
PATCH N/Y 更新局部资源
HEAD Y/Y 获取与GET一样的HTTP头信息,但没有响应体
OPTIONS Y/Y 获取资源支持的HTTP方法列表
TRACE Y/Y 让服务器返回其收到的HTTP头

PATCH 与 PUT 的区别
PUT 主要是和 GET 相对,目的是执行大规模的替换(replace)操作。
PATCH 的目的是对资源数据打补丁或局部更新(少数变化了的部分)。PATCH 不是HTTP标准方法,要考虑客户端是否支持。

1.6 超媒体(HATEOAS)

超媒体作为应用状态引擎(Hypermedia as the Engine of Application State,HATEOAS)是一种创建自描述API的方式。API所返回的资源中会包含相关资源的链接,客户端只需要了解最少的 API URL 信息就能导航整个 API。

二、设计原则

2.1 如何实现Restful设计

识别资源

  • 找到领域名词(能用CRUD操作的名词)
  • 将资源组织为集合(即集合资源)
  • 将资源合并为符合资源
  • 计算或处理函数
  • 选择合适的资源粒度

2.2 构建更好的URI

  • 使用域及子域对资源进行合理的分组或划分
  • 在URI的路径部分使用斜杠分隔符(/)来表示资源之间的层次关系
  • 在URI的路径部分使用(,)和(;)来表示非层次元素
  • 使用连字符(-)和下划线(_)来改善路径中名称的可读性
  • 在URI的查询部分使用与符号(&)来分隔参数
  • 在URI中避免出现文件扩展名(例如.php、.aspx 和.jsp)

2.3 URI与HTTP方法的组合

URI HTTP方法 含义
/orders/ GET 获取全部订单信息
/orders/ POST 添加新的订单信息
/orders/{id} GET 获取特定订单信息
/orders/{id} PUT 修改特定订单信息
/orders/{id} DELETE 删除特定咖啡信息

2.4 认识HTTP状态码

image.png

2xx:表示成功
3xx:与跳转、缓存、重定向相关
4xx:客户端错误
5xx:服务端错误

2.5 错误示范

统一资源接口要求使用标准的HTTP方法对资源进行操作,所以URI只应该来表示资源的名称,而不应该包括资源的操作。

GET    /getUser/1
POST   /createUser
PUT    /updateUser/1
DELETE /deleteUser/1

2.6 设计实践

1、API在URI里边带上版本号

http://api.example.com/1.0/foo
http://api.example.com/1.2/foo
http://api.example.com/2.0/foo

2、分层结构

http://api.example.com/sensor/temparature/room1
http://api.example.com/sensor/temparature/room2
http://api.example.com/sensor/humid/room1
http://api.example.com/sensor/humid/room2

参考资料

1、理解RESTful架构
2、RESTful 架构详解

评论

暂无评论