初识Spring HATEOAS

REST 这个词想必大家都并不陌生。

REST 架构

REST 是 Representational state transfer 的缩写，翻译过来的意思是表达性状态转换。REST 是一种架构风格，它包含了一个分布式超文本系统中对于组件、连接器和数据的约束。其关键在于所定义的架构上的各种约束。只有满足这些约束，才能称之为符合 REST 架构风格。REST 的约束包括：

•   客户端-服务器结构。通过一个统一的接口来分开客户端和服务器，使得两者可以独立开发和演化。客户端的实现可以简化，而服务器可以更容易的满足可伸缩性的要求。
• 无状态。在不同的客户端请求之间，服务器并不保存客户端相关的上下文状态信息。任何客户端发出的每个请求都包含了服务器处理该请求所需的全部信息。
• 可缓存。客户端可以缓存服务器返回的响应结果。服务器可以定义响应结果的缓存设置。
• 分层的系统。在分层的系统中，可能有中间服务器来处理安全策略和缓存等相关问题，以提高系统的可伸缩性。客户端并不需要了解中间的这些层次的细节。
• 按需代码（可选）。服务器可以通过传输可执行代码的方式来扩展或自定义客户端的行为。这是一个可选的约束。
• 统一接口。该约束是 REST 服务的基础，是客户端和服务器之间的桥梁。该约束又包含下面 4 个子约束。
  • 资源标识符。每个资源都有各自的标识符。客户端在请求时需要指定该标识符。在 REST 服务中，该标识符通常是 URI。客户端所获取的是资源的表达（representation），通常使用 XML 或 JSON 格式。
  • 通过资源的表达来操纵资源。客户端根据所得到的资源的表达中包含的信息来了解如何操纵资源，比如对资源进行修改或删除。
  • 自描述的消息。每条消息都包含足够的信息来描述如何处理该消息。
  • 超媒体作为应用状态的引擎（HATEOAS）。客户端通过服务器提供的超媒体内容中动态提供的动作来进行状态转换。这也是本文所要介绍的内容。

HATEOAS 约束

HATEOAS（Hypermedia as the engine of application state）是 REST 架构风格中最复杂的约束，也是构建成熟 REST 服务的核心。

在介绍 HATEOAS 之前，先介绍一下 Richardson 提出的 REST 成熟度模型。该模型把 REST 服务按照成熟度划分成 4 个层次：

• 第一个层次（Level 0）的 Web 服务只是使用 HTTP 作为传输方式，实际上只是远程方法调用（RPC）的一种具体形式。SOAP 和 XML-RPC 都属于此类。
• 第二个层次（Level 1）的 Web 服务引入了资源的概念。每个资源有对应的标识符和表达。
• 第三个层次（Level 2）的 Web 服务使用不同的 HTTP 方法来进行不同的操作，并且使用 HTTP 状态码来表示不同的结果。如 HTTP GET 方法来获取资源，HTTP DELETE 方法来删除资源。
• 第四个层次（Level 3）的 Web 服务使用 HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。

从上述 REST 成熟度模型中可以看到，使用 HATEOAS 的 REST 服务是成熟度最高的，也是推荐的做法。对于不使用 HATEOAS 的 REST 服务，客户端和服务器的实现之间是紧密耦合的。

Spring HATEOAS

如果 Web 应用基于 Spring 框架开发，那么可以直接使用 Spring 框架的子项目 HATEOAS 来开发满足 HATEOAS 约束的 Web 服务。Spring框架为我们提供了一个极其简单的HATEOAS实现。

本文使用的是Spring boot 1.5.9.RELEASE。

引入Spring HATEOAS模块。

	 org.springframework.boot
	spring-boot-starter-hateoas

创建资源类。

public class Greeting extends ResourceSupport  {
	 private String content;

//	    @JsonCreator
//	    public Greeting(@JsonProperty("content") String content) {
//	        this.content = content;
//	        add(new Link("http://localhost:8080/lists/1"));
//	        add(new Link("http://localhost:8080/lists/1/items", "items"));
//	    }
	 
	 
	    public Greeting(String content) {
	        this.content = content;
	    }
	    
	    

	    public String getContent() {
	        return content;
	    }
}

注意：资源类Greeting中不可以有id成员变量，因为其集成的父类ResourceSupport中有一个getId()方法。

创建控制器类。

import static org.springframework.hateoas.mvc.ControllerLinkBuilder.*;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.hateoas.EntityLinks;
import org.springframework.hateoas.ExposesResourceFor;
import org.springframework.hateoas.Link;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.byit.backstage.entity.Greeting;

@RestController
@ExposesResourceFor(Greeting.class)
@RequestMapping(path = "/lists")
public class GreetingController {
	
	private static final String TEMPLATE = "Hello, %s!";

	@Autowired
	private EntityLinks entityLinks;
	
    @RequestMapping("/greeting")
    public HttpEntity greeting(@RequestParam(value = "name", required = false, defaultValue = "World") String name) {

        Greeting greeting = new Greeting(String.format(TEMPLATE, name));
        greeting.add(linkTo(methodOn(GreetingController.class).greeting(name)).withSelfRel());
        greeting.add(new Link("http://localhost:8080/lists/1"));
        greeting.add(new Link("http://localhost:8080/lists/1/items", "items"));
        greeting.add(new Link("www.baidu.com"));
        return new ResponseEntity<>(greeting, HttpStatus.OK);
    }
    @RequestMapping("/{id}")
    public HttpEntity lists(@RequestParam(value = "name", required = false, defaultValue = "World") String name, @PathVariable(value = "id") String id) {
    	
    	Greeting greeting = new Greeting(String.format(TEMPLATE, name));
//    	greeting.add(linkTo(methodOn(GreetingController.class).greeting(name)).withSelfRel());
//    	greeting.add(linkTo(GreetingController.class).slash(id).withSelfRel());
//    	greeting.add(new Link("http://localhost:8080/lists/1/items", "items"));
    	
    	
    	greeting.add(entityLinks.linkForSingleResource(Greeting.class, 1).withSelfRel());
    	
    	return new ResponseEntity<>(greeting, HttpStatus.OK);
    }
}

Spring  boot配置类。

@SpringBootApplication
@EnableEntityLinks
public class Application_8501 {

	public static void main(String[] args) {
		SpringApplication.run(Application_8501.class, args);

	}

}

打开浏览器，在地址栏输入URL。

http://localhost:8501/lists/greeting?name=wangziyan

查看结果。

{

  "content" : "Hello, wangziyan!",

  "_links" : {

    "self" : [ {

      "href" : "http://localhost:8501/lists/greeting?name=wangziyan"

    }, {

      "href" : "http://localhost:8080/lists/1"

    }, {

      "href" : "www.baidu.com"

    } ],

    "items" : {

      "href" : "http://localhost:8080/lists/1/items"

    }

  }

}

是不是很简单~

参考文档：

http://spring.io/guides/gs/rest-hateoas/

https://www.ibm.com/developerworks/cn/java/j-lo-SpringHATEOAS/index.html?ca=drs-&utm_source=tuicool&utm_medium=referral