Software Architecture

REST and Spring HATEOAS

回顾

height:400px


spring-petclinic/spring-framework-petclinic

问题一









展示层页面与计算逻辑混杂

问题二










用户接口并不标准

RESTful Petclinic

height:400px


https://github.com/spring-petclinic/spring-petclinic-rest

REST架构风格

Architectural Styles and the Design of Network-based Software Architectures

- Roy Thomas Fielding, 2000

Roy Thomas Fielding: HTTP协议（1.0版和1.1版）的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席

REST


Representational State Transfer      表现层状态转化

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

全称应为： Resource Representational State Transfer，资源表现层状态转化。

REST

  • REST指的是一组架构约束条件和原则
    • 为设计一个功能强、性能好、适宜通信的Web应用
    • 如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构
  • 核心概念
    • 资源（Resources）
    • 表现层（Representation）
    • 状态转化（State Transfer）

资源

网络上的一个实体，或者说是网络上的一个具体信息，任何事物，只要有被引用到的必要，它就是一个资源。

  • 一段文本，一张图片，一首歌曲
  • 数据库中的一行数据
  • 一个手机号码，某用户的个人信息
  • 一种服务

资源标识

要让一个资源可以被识别，需要有个唯一标识，在Web中这个唯一标识就是URI(Uniform Resource Identifier)

  • http://www.ex.com/software/releases/latest.tar.gz
  • http://www.ex.com/map/roads/USA/CA/17_mile_drive
  • http://www.ex.com/search/cs578
  • http://www.ex.com/sales/2012/Q1
  • http://www.ex.com/relationships/Alice;Bob

URI设计原则

  • 易读
    • http://www.oschina.net/news/38119/oschina-translate-reward-plan
  • 表达资源的层级关系
    • https://github.com/git/git/commit/e3ae056f87e1d675913d08/orders/2012/10
  • 表示资源的同级关系
    • /git/block-sha1/sha1.h/compare/e3af72cda056f87e;bd63e61bdf38eb264
  • 表达资源的过滤
    • https://github.com/git/git/pulls?state=closed

统一资源接口

  • RESTFul架构应该遵循统一接口原则，统一接口包含了一组受限的预定义的操作，不论什么样的资源，都是通过使用相同的接口进行资源的访问。接口应该使用标准的HTTP方法如GET，PUT和POST，并遵循这些方法的语义。
  • 如果按照HTTP方法的语义来暴露资源，那么接口将会拥有安全性和幂等性的特性
    • GET和HEAD请求是安全的， 无论请求多少次，都不改变服务器状态
    • GET、HEAD、PUT和DELETE请求是幂等的，无论对资源操作多少次， 结果总是一样的，后面的请求并不会产生比第一次更多的影响

GET

获取表示，变更时获取表示（缓存）。安全且幂等。

200（OK） - 表示已在响应中发出
204（无内容） - 资源有空表示
301（Moved Permanently） - 资源的URI已被更新
303（See Other） - 其他（如，负载均衡）
304（not modified）- 资源未更改（缓存）
400 （bad request）- 指代坏请求（如，参数错误）
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务端当前无法处理请求

POST

使用服务端管理的（自动产生）的实例号创建资源，或创建子资源，部分更新资源，如果没有被修改，则不过更新资源（乐观锁）。不安全且不幂等。

200（OK）- 如果现有资源已被更改
201（created）- 如果新资源被创建
202（accepted）- 已接受处理请求但尚未完成（异步处理）
301（Moved Permanently）- 资源的URI被更新
303（See Other）- 其他（如，负载均衡）
400（bad request）- 指代坏请求
404 （not found）- 资源不存在

POST

使用服务端管理的（自动产生）的实例号创建资源，或创建子资源，部分更新资源，如果没有被修改，则不过更新资源（乐观锁）。不安全且不幂等。

406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前无法处理请

PUT

用客户端管理的实例号创建一个资源，通过替换的方式更新资源，如果未被修改，则更新资源（乐观锁）。不安全但幂等。

200 （OK）- 如果已存在资源被更改
201 （created）- 如果新资源被创建
301（Moved Permanently）- 资源的URI已更改
303 （See Other）- 其他（如，负载均衡）
400 （bad request）- 指代坏请求
404 （not found）- 资源不存在

PUT

用客户端管理的实例号创建一个资源，通过替换的方式更新资源，如果未被修改，则更新资源（乐观锁）。不安全但幂等。

406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前无法处理请求

DELETE

删除资源。不安全但幂等。

200 （OK）- 资源已被删除
301 （Moved Permanently）- 资源的URI已更改
303 （See Other）- 其他，如负载均衡
400 （bad request）- 指代坏请求
404 （not found）- 资源不存在
409 （conflict）- 通用冲突
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务端当前无法处理请求

指导意义

统一资源接口要求使用标准的HTTP方法对资源进行操作，所以URI只应该来表示资源的名称，而不应该包括资源的操作。 通俗来说，URI不应该使用动作来描述。例如，

  • POST /getUser?id=1 => GET /User/1
  • GET /newUser => POST /User
  • GET /updateUser => PUT /User/1
  • GET /deleteUser?id=2 => DELETE /User/2

表现（Representation）／表述／表征

“资源”是一种信息实体，它可以有多种外在表现形式。我们把“资源”具体呈现出来的形式，叫做它的“表现层”（Representation）

  • 文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式
  • 图片可以用JPG格式表现，也可以用PNG格式表现

资源表述

  • URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的“.html”后缀名是不必要的，因为这个后缀名表示格式，属于“表现层”范畴，而URI应该只代表“资源”的位置。
  • 资源的表述包括数据和描述数据的元数据，例如，HTTP头“Content-Type” 就是这样一个元数据属性
  • 客户端可以通过Accept头请求一种特定格式的表述，服务端则通过Content-Type告诉客户端资源的表述形式

资源表述










同一资源 http://api.github.com/orgs/github 的不同表述

资源表述

不支持的表述

height:300px

资源链接

  • 当你浏览Web网页时，从一个连接跳到一个页面，再从另一个连接跳到另外一个页面，就是利用了超媒体的概念: 把一个个把资源链接起来
  • 同样，我们在表述格式里边加入链接来引导客户端

在Link头告诉客户端怎么访问下一页和最后一页的记录；在响应体里用url来链接项目所有者和项目地址

资源链接

创建订单后通过链接引导客户端如何去付款

height:300px

状态转移（State Transfer）

  • 状态应该区分应用状态和资源状态，客户端负责维护应用状态，而服务端维护资源状态。
  • 客户端与服务端的交互必须是无状态的，并在每一次请求中包含处理该请求所需的一切信息。
  • 服务端不需要在请求间保留应用状态，只有在接受到实际请求的时候，服务端才会关注应用状态。
  • 这种无状态通信原则，使得服务端和中介能够理解独立的请求和响应。 在多次请求中，同一客户端也不再需要依赖于同一服务器，方便实现高可扩展和高可用性的服务端。

状态转移



客户端应用状态在服务端提供的超媒体的指引下发生变迁。 服务端通过超媒体告诉客户端当前状态有哪些后续状态可以进入。

一个完整的故事

例如我订阅了一个人的博客，想要获取他发表的所有文章（这里“他发表的所有文章”就是一个资源Resource）。于是我就向他的服务发出请求，说“我要获取你发表的所有文章，最好是atom格式的”，这时候服务器向你返回了atom格式的文章列表第一页（这里“atom格式的文章列表”就是表征Representation）。

一个完整的故事-2

你看到了第一页的页尾，想要看第二页，这时候有趣的事情就来了。如果服务器记录了应用的状态（stateful），那么你只要向服务询问“我要看下一页”，那么服务器自然就会返回第二页。类似的，如果你当前在第二页，想服务器请求“我要看下一页”，那就会得到第三页。

一个完整的故事-3

但是REST的服务器恰恰是无状态的（stateless），服务器并没有保持你当前处于第几页，也就无法响应“下一页”这种具有状态性质的请求。因此客户端需要去维护当前应用的状态（application state），也就是“如何获取下一页资源”。

一个完整的故事-4

当然，“下一页资源”的业务逻辑必然是由服务端来提供。服务器在文章列表的atom表征中加入一个URI超链接（hyper link），指向下一页文章列表对应的资源。客户端就可以使用统一接口（Uniform Interface）的方式，从这个URI中获取到他想要的下一页文章列表资源。

一个完整的故事-5

上面的“能够进入下一页”就是应用的状态（State）。服务器把“能够进入下一页”这个状态以atom表征形式传输（Transfer）给客户端就是表征状态传输（REpresentational State Transfer）这个概念。

Tutorial

Building REST services with Spring

https://spring.io/guides/tutorials/rest/

Demo

https://www.bilibili.com/video/BV1GE411G7hu?p=4

spring-projects/spring-hateoas-examples
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>