2. 基本原理
本节涵盖了 Spring HATEOAS 的基础知识及其基本域抽象。
2.1. 链接
超媒体的基本思想是用超媒体元素来丰富资源的表示。 最简单的形式是链接。 它们指示客户端可以导航到特定资源。 相关资源的语义在所谓的链接关系中定义。 您可能已经在 HTML 文件的头上看到了这一点：
<link href="theme.css" rel="stylesheet" type="text/css" />如您所见，该链接指向资源theme.css，并指示它是一个样式表。
链接通常包含其他信息，例如资源指向的媒体类型将返回。
但是，链接的基本构建块是其引用和关系。
Spring HATEOAS 允许您通过其不可变的Linkvalue 类型。
它的构造函数同时采用超文本引用和链接关系，后者默认为 IANA 链接关系self.
在 Link relations 中阅读更多关于后者的信息。
Link link = Link.of("/something");
assertThat(link.getHref()).isEqualTo("/something");
assertThat(link.getRel()).isEqualTo(IanaLinkRelations.SELF);
link = Link.of("/something", "my-rel");
assertThat(link.getHref()).isEqualTo("/something");
assertThat(link.getRel()).isEqualTo(LinkRelation.of("my-rel"));Link公开 RFC-8288 中定义的其他属性。
你可以通过在Link实例。
有关如何创建指向 Spring MVC 和 Spring WebFlux 控制器的链接的更多信息，请参阅在 Spring MVC 中构建链接和在 Spring WebFlux 中构建链接。
2.2. URI 模板
对于 Spring HATEOASLink，超文本引用不仅可以是 URI，还可以是符合 RFC-6570 的 URI 模板。
URI 模板包含所谓的模板变量，并允许扩展这些参数。
这允许客户端将参数化模板转换为 URI，而无需了解最终 URI 的结构，它只需要知道变量的名称。
Link link = Link.of("/{segment}/something{?parameter}");
assertThat(link.isTemplated()).isTrue(); (1)
assertThat(link.getVariableNames()).contains("segment", "parameter"); (2)
Map<String, Object> values = new HashMap<>();
values.put("segment", "path");
values.put("parameter", 42);
assertThat(link.expand(values).getHref()) (3)
.isEqualTo("/path/something?parameter=42");| 1 | 这Linkinstance 表示它是模板化的，即它包含一个 URI 模板。 |
| 2 | 它公开模板中包含的参数。 |
| 3 | 它允许扩展参数。 |
可以手动构建 URI 模板，并在以后添加模板变量。
UriTemplate template = UriTemplate.of("/{segment}/something")
.with(new TemplateVariable("parameter", VariableType.REQUEST_PARAM);
assertThat(template.toString()).isEqualTo("/{segment}/something{?parameter}");2.3. 链接关系
为了指示目标资源与当前资源的关系，使用了所谓的链接关系。
Spring HATEOAS 提供了一个LinkRelation键入以轻松创建String-基于 IT 的实例。
2.3.1. IANA 链接关系
Internet Assigned Numbers Authority 包含一组预定义的链接关系。
它们可以通过以下方式引用IanaLinkRelations.
Link link = Link.of("/some-resource"), IanaLinkRelations.NEXT);
assertThat(link.getRel()).isEqualTo(LinkRelation.of("next"));
assertThat(IanaLinkRelation.isIanaRel(link.getRel())).isTrue();2.4. 表示模型
为了轻松创建超媒体丰富的表示形式，Spring HATEOAS 提供了一组具有RepresentationModel在他们的根源上。
它基本上是一个容器，用于Links，并提供了将它们添加到模型中的便捷方法。
这些模型稍后可以渲染为各种媒体类型格式，这些格式将定义超媒体元素在表示中的外观。
有关更多信息，请查看 媒体类型.
RepresentationModel类层次结构class RepresentationModel class EntityModel class CollectionModel class PagedModel EntityModel -|> RepresentationModel CollectionModel -|> RepresentationModel PagedModel -|> CollectionModel
使用RepresentationModel是创建它的子类以包含表示应该包含的所有属性，创建该类的实例，填充属性并使用链接丰富它。
class PersonModel extends RepresentationModel<PersonModel> {
String firstname, lastname;
}通用的自类型化是必要的，以便RepresentationModel.add(…)return 自身的实例。
模型类型现在可以像这样使用：
PersonModel model = new PersonModel();
model.firstname = "Dave";
model.lastname = "Matthews";
model.add(Link.of("https://myhost/people/42"));如果从 Spring MVC 或 WebFlux 控制器返回此类实例，并且客户端发送了Acceptheader 设置为application/hal+json，响应将如下所示：
{
"_links" : {
"self" : {
"href" : "https://myhost/people/42"
}
},
"firstname" : "Dave",
"lastname" : "Matthews"
}
2.4.1. Item 资源表示模型
对于由单个对象或概念支持的资源，方便EntityModeltype 存在。
你不必为每个概念创建自定义模型类型，只需重用已经存在的类型并将其实例包装到EntityModel.
EntityModel包装现有对象Person person = new Person("Dave", "Matthews");
EntityModel<Person> model = EntityModel.of(person);2.4.2. 集合资源表示模型
对于概念上是集合的资源，一个CollectionModel可用。
它的元素可以是简单对象或RepresentationModel实例。
CollectionModel包装现有对象的集合Collection<Person> people = Collections.singleton(new Person("Dave", "Matthews"));
CollectionModel<Person> model = CollectionModel.of(people);虽然EntityModel被约束为始终包含一个有效负载，因此允许对唯一实例上的类型排列进行推理，一个CollectionModel的基础集合可以为空。
由于 Java 的类型擦除，我们实际上无法检测到CollectionModel<Person> model = CollectionModel.empty()实际上是一个CollectionModel<Person>因为我们看到的只是运行时实例和一个空集合。
该缺失的类型信息可以通过在 construct 时通过CollectionModel.empty(Person.class)或者作为 fallback，以防底层集合可能为空：
Iterable<Person> people = repository.findAll();
var model = CollectionModel.of(people).withFallbackType(Person.class);