非Spring Boot环境下Spring MVC集成HATEOAS无法生成HAL-FORMS格式响应问题排查

你遇到的核心问题是非Spring Boot环境下，Spring HATEOAS的HAL-FORMS自动配置未生效，导致链接被序列化为数组形式而非HAL规范的_links对象。结合你的现有配置，以下是你遗漏的关键步骤和配置：

1. 修正@EnableHypermediaSupport的放置位置 #

你当前把@EnableHypermediaSupport加在了控制器类上，这是错误的——这个注解是全局配置注解，应该放在标注了@Configuration的Spring配置类上，用来启用超媒体支持的核心组件：

@Configuration
@EnableHypermediaSupport(type = EnableHypermediaSupport.HypermediaType.HAL_FORMS)
public class HypermediaConfig {
    // 其他超媒体相关配置放在这里
}

2. 手动注册HAL-FORMS相关的Jackson模块与消息转换器 #

非Spring Boot环境不会自动注册HAL序列化所需的Jackson模块，你需要手动配置MappingJackson2HttpMessageConverter，添加HalModule和HalFormsModule，同时指定支持的媒体类型：

@Bean
public MappingJackson2HttpMessageConverter halFormsJacksonHttpMessageConverter() {
    ObjectMapper objectMapper = new ObjectMapper();
    // 注册HAL和HAL-FORMS模块
    objectMapper.registerModule(new HalModule());
    objectMapper.registerModule(new HalFormsModule());
    // 禁用未知属性反序列化失败的校验，适配HAL扩展字段
    objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

    MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter(objectMapper);
    // 指定支持HAL-FORMS媒体类型
    converter.setSupportedMediaTypes(Collections.singletonList(MediaType.parseMediaType("application/prs.hal-forms+json")));
    return converter;
}

// 确保自定义转换器优先级高于默认转换器，优先处理HAL-FORMS响应
@Bean
public RequestMappingHandlerAdapter requestMappingHandlerAdapter() {
    RequestMappingHandlerAdapter adapter = new RequestMappingHandlerAdapter();
    adapter.getMessageConverters().add(0, halFormsJacksonHttpMessageConverter());
    return adapter;
}

3. 手动声明超媒体核心Bean #

Spring Boot会自动创建LinkRelationProvider、AffordanceModelFactory等核心Bean，但非Boot环境需要你手动注册：

@Bean
public LinkRelationProvider linkRelationProvider() {
    return new DefaultLinkRelationProvider();
}

@Bean
public AffordanceModelFactory affordanceModelFactory() {
    ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
    messageSource.setBasename("messages");
    return new SpringMvcAffordanceModelFactory(linkRelationProvider(), new MessageSourceAccessor(messageSource));
}

4. 验证依赖版本兼容性 #

确保你的spring-hateoas（1.4.1）与Spring MVC的版本兼容——1.4.x版本的Spring HATEOAS对应Spring Framework 5.3.x系列，如果你的Spring MVC版本过低，可能会出现序列化逻辑不兼容的问题。

5. 确认请求的媒体类型匹配 #

虽然你在控制器指定了produces = "application/prs.hal-forms+json"，但要确保请求的Accept头也包含该媒体类型，这样Spring才会选择对应的消息转换器处理响应，输出符合规范的HAL-FORMS格式。

完成以上配置后，你的EntityModel应该会被序列化为符合HAL-FORMS规范的格式，包含_links对象及对应的Affordance信息。

内容的提问来源于stack exchange，提问作者OrG