尊敬的 Spring 社区，我们很荣幸地宣布 Spring HATEOAS 1.0 的第一个里程碑版本。Spring HATEOAS 已经开发了将近七年。它最初是 Spring MVC 的一个小扩展，后来成为 Spring Data REST 的基础，并一直作为 Spring MVC 应用程序中基于超媒体 API 的基本构建块。

我们从社区收到了许多关于更高级功能的建议，最终决定是时候将这些功能集成到库中了。此外，我们在实际使用该库的过程中积累了大量的经验，认为应该借此机会将这些经验教训反映在 1.0 版本中。

以下是概要

• 整体重构包设计和领域模型语言。

• 升级到 Java 8 和 Spring Framework 5.1 作为基础。

• 通过 Affordances API 提供高级超媒体支持（HAL-FORMS、Collection+JSON、UBER）。

• 超媒体支持 SPI，用于插入自定义媒体类型实现。

• Spring WebFlux 的 LinkBuilder 实现。

• 完全重写的参考文档。

让我们详细看看其中一些功能。

包和类型的重构

在发布 1.0 之前，我们借此机会重新评估了包结构以及我们在领域类型中公开的术语。与 0.x 版本相比，这导致了一些重大变化。

最根本的变化是 Spring HATEOAS 不再创建资源。这是 Spring MVC/Spring WebFlux 做的事情。我们创建了与供应商无关的超媒体表示。因此，我们重命名了这些核心类型

• ResourceSupport 现在是 RepresentationModel

• Resource<T> 现在是 EntityModel<T>

• Resources<T> 现在是 CollectionModel<T>

• PagedResources<T> 现在是 PagedModel<T>

作为副作用，ResourceAssembler 现在是 RepresentationModelAssembler，其方法现在是 toModel(…​) 和 toCollection(…​)。整个代码库中都有类似的变更来反映这种变化。

许多 API 都围绕着 List<Link> 的概念展开，包括 RepresentationModel.getLinks()。我们现在返回的是 Links 而不是 Java List，Links 已得到显著增强，以便更容易地组合、提取和合并链接。核心抽象 LinkBuilder、EntityLinks、RelProvider、LinkDiscoverer 已分别分组到 server 和 client 包中。

听起来很令人头疼？别担心，我们已为您准备好。我们编写了一个脚本，它将尽最大努力将您的大部分代码迁移到新的类型和 import 语句。它可能无法覆盖所有内容，但应该能极大地简化迁移。

Spring WebFlux 支持

此版本中最关键的功能之一是对 Spring WebFlux 和响应式编程的支持。这包括

• 响应式构建链接。

• 向 WebFlux 端点提供超媒体。

• 支持 WebFlux 的 WebClient 来消费超媒体。

Spring HATEOAS 带有 WebFluxLinkBuilder，因此您可以响应式地构建链接。它会自动获取服务器托管的基础 URI，并将其与端点的路径合并。

示例 1. 响应式创建链接和 affordances

import static org.springframework.hateoas.server.reactive.WebFluxLinkBuilder.*;

@GetMapping("/employees")
public Mono<CollectionModel<EntityModel<Employee>>> all() {

  var controller = methodOn(WebFluxEmployeeController.class);

  return Flux.fromIterable(EMPLOYEES.keySet())
    .flatMap(id -> findOne(id))
    .collectList()
    .flatMap(resources -> linkTo(controller.all()).withSelfRel() (1)
      .andAffordance(controller.newEmployee(null)) (2)
      .andAffordance(controller.search(null, null))
      .toMono() (3)
      .map(selfLink -> new CollectionModel<>(resources, selfLink)));
}

1. 链接到具有 Reactor 类型的 WebFlux 端点。

2. 以领域友好的方式添加 affordances（更多信息见下文）。

3. 返回一个 Mono，以便您可以进行任何额外的 Reactor 操作。

假设此控制器托管在 http://example.com，则预计将提供包含指向 http://example.com/employees 链接的超媒体文档。

除了响应式构建链接之外，您的 WebFlux 端点现在将在您返回基于 RepresentationModel 的类型时渲染超媒体，无论它是否被包裹在 Reactor 类型中。

Affordances

在过去两年中，我们一直在开发 Affordances。我们从 Escalon 的 @dschulten 和 HDIV Security 的 @anderruiz 团队那里获得了宝贵的输入，了解如何收集元数据以渲染比已经支持的 HAL 更详细地描述资源交互的高级媒体类型。您在上面的 WebFlux 端点中看到了该元数据收集 API 的片段。

通过将相关操作链接在一起，可以生成感知 affordance 的媒体类型，例如 HAL-FORMS（如下所示）

示例 2. 从 Affordance API 生成的 HAL-FORMS 示例输出

{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "role" : "ring bearer",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/employees/1"
    }
  },
  "_templates" : {
    "default" : {
      "title" : null,
      "method" : "put",
      "contentType" : "",
      "properties" : [ {
        "name" : "firstName",
        "required" : true
      }, {
        "name" : "lastName",
        "required" : true
      }, {
        "name" : "role",
        "required" : true
      } ]
    },
    "partiallyUpdateEmployee" : {
      "title" : null,
      "method" : "patch",
      "contentType" : "",
      "properties" : [ {
        "name" : "firstName",
        "required" : false
      }, {
        "name" : "lastName",
        "required" : false
      }, {
        "name" : "role",
        "required" : false
      } ]
    }
  }
}

这种感知 affordance 的媒体类型提供了更新此资源所需的所有信息。

新的媒体类型

说到 HAL-FORMs，我们添加了*几种*新的媒体类型

• HAL-FORMS

• Collection+JSON

• UBER

但为何止步于此？虽然我们计划支持其他媒体类型，但这不应该阻止您创建自己的媒体类型。我们引入了一个新的 SPI，允许您编写您自己的自定义媒体类型，并将其注册到 Spring HATEOAS 中，以便您可以将其与 Spring MVC、RestTemplate bean、Spring WebFlux 和 WebClient bean 一起使用。

更新和增强的文档

不知道您是否注意到，Spring 团队一直在升级其所有文档。我们也一样！我们也开始清理和重写内容，所以务必去看看。我们将在接下来的里程碑版本中做更多调整。有什么遗漏吗？请告诉我们！有超过80 个已关闭的 issue，一定要查看一下。并告诉我们您的想法！

Spring Data REST

谈论 Spring HATEOAS 就不能不提 Spring Data REST。

Spring Data REST 的最新快照版本正在接收和适应 Spring HATEOAS 带来的所有这些变化。总体计划是让 Spring Data 发布列车 Moore 升级到 Spring HATEOAS 1.0。这意味着诸如 affordances 和新的媒体类型将成为 Spring Data REST 的一部分。

Spring Framework 5.1 支持

Spring HATEOAS 1.0 现在基于 Spring Framework 5.1。这意味着像 Forwarded 头部处理等事情都委托给 Spring Framework 管理。如果您的应用程序前面的代理服务器正在发送正确的头部，而您的 Spring HATEOAS 支持的 API 突然没有重写 URI，您需要配置头部处理。

如果您使用 Spring Boot，只需这样做

server.use-forward-headers=true

如果您不使用 Spring Boot，那么您必须配置类似这样的东西

@Bean
public FilterRegistrationBean<ForwardedHeaderFilter> forwardedHeaderFilter() {

  var filter = new FilterRegistrationBean<>();
  filter.setFilter(new ForwardedFilter());

  return filter;
}

有关更多详情，请查看Spring Framework 的 Forwarded 头部过滤器。

请查看下面的项目链接。

链接：项目主页 | GitHub | Issues

作为一个里程碑版本，您可以在https://repo.spring.io/libs-milestone找到这些制品。