在构建 RESTful 服务时，很多团队习惯返回仅包含业务字段的 JSON 对象，客户端必须依赖外部文档才知道下一步该调用哪个地址。Spring Boot 通过 EnableHATEOAS 模块把超媒体控制（HATEOAS）能力集成进来，让响应自身携带相关操作链接，从而降低服务端与调用方的硬编码耦合。下面以一个订单查询场景为例，说明完整整合过程。
一、引入依赖与开启 EnableHATEOAS
要在 Spring Boot 中使用 HATEOAS，首先需要在构建文件中加入对应的 starter。以 Maven 为例，引入 spring-boot-starter-hateoas 后，Spring Boot 的自动配置会注册必要的消息转换器和链接构建器。这一步不需要手动编写 XML 或 Java 配置类，只要依赖存在且版本匹配，框架就会在启动阶段完成基础装配。
开启 EnableHATEOAS 的核心动作是使用注解。在应用主类或者任意被扫描的配置类上添加 @EnableHypermediaSupport 或直接使用 Spring Boot 提供的自动支持均可。较新版本的 spring-boot-starter-hateoas 已经默认开启，但如果需要指定超媒体格式（如 HAL、HAL-FORMS），则可通过注解显式声明类型。下面的代码展示了主类上的常见写法。
@SpringBootApplication
@EnableHypermediaSupport(type = HypermediaType.HAL)
public class OrderApplication {
public static void main(String[] args) {
SpringApplication.run(OrderApplication.class, args);
}
}
引入依赖后，项目中就可以使用 org.springframework.hateoas 包下的 RepresentationModel、Link 等类型。与传统 DTO 不同，这些类型允许在对象内部追加关系链接。需要注意的是，如果同时引入了其他消息转换器，要确保 HATEOAS 的转换器优先级正确，否则可能出现链接字段被忽略的情况。通常 Spring Boot 自动配置已经处理了顺序问题，但在自定义 WebMvcConfigurer 时要避免覆盖默认 HttpMessageConverter 列表。
二、定义带链接的资源模型与控制器返回
传统做法里，我们会写一个纯数据的 OrderDto，里面只有 id、amount 等字段。启用 HATEOAS 之后，应当让资源类继承 RepresentationModel，这样就能调用 add 方法附加 Link。Link 由 rel（关系名）和 href（地址）组成，客户端通过解析 rel 决定下一步动作，而不是直接拼接字符串 URL。
在控制器中，我们可以使用 EntityLinks 或 ControllerLinkBuilder 来生成指向其他接口的链接。例如订单详情接口可以附加一个指向支付接口的“pay”链接，只有当前订单状态允许支付时才添加。这种条件化链接让前端不用写复杂的状态判断逻辑，直接读取响应里的链接是否存在即可。下面示例展示资源类与控制器写法。
public class OrderModel extends RepresentationModel<OrderModel> {
private String orderId;
private Integer amount;
public OrderModel(String orderId, Integer amount) {
this.orderId = orderId;
this.amount = amount;
}
// getter 和 setter 省略
}
@RestController
@RequestMapping("/orders")
public class OrderController {
@GetMapping("/{id}")
public OrderModel getOrder(@PathVariable String id) {
OrderModel model = new OrderModel(id, 100);
model.add(Link.of("http://localhost:8080/orders/" + id + "/pay").withRel("pay"));
return model;
}
}
上述代码返回的 JSON 会包含一个 _links 节点，里面列出了 self 和 pay 关系。如果前端使用支持 HATEOAS 的客户端库，就能自动把 pay 链接绑定到按钮事件上。对比传统接口，当支付路径从 /orders/{id}/pay 调整为 /pay/{id} 时，只要服务端改了 Link 构造逻辑，前端无需发版。这就是超媒体驱动带来的演进优势。
在实际项目里，手动拼 URL 容易出错，推荐注入 EntityLinks 来构建。例如调用 entityLinks.linkToItemResource(OrderController.class, id).withRel("self")，框架会根据请求映射自动算出地址，避免硬编码主机名和端口。对于集群部署场景，还可以配合反向代理前缀配置，保证生成的链接对外部可见。
三、HAL 格式解析与常见整合误区
Spring Boot EnableHATEOAS 默认采用 HAL（Hypertext Application Language）作为媒体类型，响应里的链接统一放在 _links 对象中，关联资源用 _embedded 表示。理解 HAL 结构有助于排查前端解析异常。比如有的开发者以为链接会平铺在根对象，结果取不到数据，其实是因为 HAL 规范要求链接集中管理，从而降低字段冲突概率。
一个常见误区是认为加了 @EnableHypermediaSupport 就一定能生效，却忘了控制器返回的是普通 Map 或自己写的 POJO。HATEOAS 的链接注入依赖对象类型是 RepresentationModel 的子类，如果直接返回 HashMap，链接不会被序列化进去。此时要么改造返回类型为 ResourceSupport 体系，要么用 EntityModel.wrap 包装一层再返回。
@GetMapping("/v2/{id}")
public EntityModel<OrderDto> getOrderV2(@PathVariable String id) {
OrderDto dto = new OrderDto(id, 200);
EntityModel<OrderDto> model = EntityModel.of(dto);
model.add(Link.of("http://localhost:8080/orders/" + id).withSelfRel());
return model;
}
另一个容易被忽略的点是内容协商。如果客户端请求头里 Accept 不是 application/hal+json，Spring Boot 可能返回普通 JSON 而丢掉链接。因此在网关或前端封装的 HTTP 工具里，需要明确携带对应 Accept，或者在配置中将 HAL 设为默认返回格式。通过正确设置，EnableHATEOAS 才能真正发挥超媒体接口的弹性价值，让 API 随业务变化平滑升级。
Spring_BootEnableHATEOASHATEOAS修改时间：2026-08-17 07:34:31