Spring Boot中HttpMediaTypeNotAcceptableException的解决方案

1. 问题现象与初步分析

最近在开发Spring Boot项目时，遇到了一个让人头疼的异常：org.springframework.web.HttpMediaTypeNotAcceptableException: No acceptable representation。这个错误发生在调用某个RESTful接口时，控制台打印的完整堆栈信息显示问题出在消息转换环节。

从异常堆栈可以清晰看到，错误发生在AbstractMessageConverterMethodProcessor.writeWithMessageConverters()方法中。Spring框架在处理返回值时，无法找到合适的消息转换器(MessageConverter)来将Java对象转换为客户端可接受的格式。有趣的是，根据问题描述，这个错误似乎与返回对象中的@JsonProperty("pageNum")注解有关。

提示：HttpMediaTypeNotAcceptableException通常表示服务器无法生成符合客户端Accept头要求的响应格式。在REST API开发中，这往往与内容协商(Content Negotiation)机制有关。

2. 深入理解内容协商机制

2.1 Spring MVC的内容协商流程

Spring MVC处理请求时，内容协商是一个关键环节。整个过程大致如下：

1. 客户端发送请求时，通过Accept头指定期望的响应格式（如application/json）
2. DispatcherServlet接收到请求后，委托给RequestMappingHandlerAdapter处理
3. HandlerMethodReturnValueHandlerComposite选择合适的返回值处理器
4. 对于@ResponseBody或@RestController方法，使用RequestResponseBodyMethodProcessor
5. 该处理器调用MessageConverter将Java对象转换为指定格式

当系统找不到能同时满足以下两个条件的MessageConverter时，就会抛出我们遇到的异常：

• 能够处理返回对象的类型
• 能够生成客户端接受的媒体类型

2.2 常见的MessageConverter及其作用

Spring Boot默认会注册以下常用的消息转换器：

3. 问题根源探究

3.1 @JsonProperty注解的影响

根据问题描述，异常与@JsonProperty("pageNum")注解有关。这个注解来自Jackson库，用于指定JSON属性名。当出现这种问题时，通常有以下几种可能：

1. 类路径上有多个JSON处理库（如同时存在Jackson和Gson），导致转换器冲突
2. 自定义的MessageConverter配置不当，覆盖了默认配置
3. 对象结构复杂，包含循环引用或非常规类型

3.2 典型场景复现

假设我们有一个返回分页数据的方法：

java复制@RestController
public class UserController {
    
    @GetMapping("/users")
    public PageInfo<User> getUsers() {
        // 返回包含@JsonProperty注解的对象
        return userService.getUsers();
    }
}

@Data
class PageInfo<T> {
    @JsonProperty("pageNum")
    private int pageNumber;
    
    private int pageSize;
    private List<T> list;
}

当客户端请求的Accept头与可用的MessageConverter不匹配时，就会出现问题。例如：

1. 客户端请求头：Accept: application/xml
2. 但只配置了JSON转换器
3. 或者客户端要求返回text/plain，但返回的是复杂对象

4. 解决方案与实施步骤

4.1 方案一：统一媒体类型

最直接的解决方案是确保客户端和服务端使用相同的媒体类型：

1. 客户端明确指定Accept头：

   bash复制curl -H "Accept: application/json" http://localhost:8080/users
   

2. 服务端强制指定produces：

   java复制@GetMapping(value = "/users", produces = "application/json")
   public PageInfo<User> getUsers() {
       // ...
   }
   

4.2 方案二：检查依赖冲突

在pom.xml中检查是否有多个JSON库：

xml复制<!-- 推荐只保留一个JSON库 -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.15.0</version>
</dependency>

<!-- 如果不需要Gson，应该移除 -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

4.3 方案三：自定义WebMvcConfigurer

如果需要更灵活的控制，可以自定义消息转换器：

java复制@Configuration
public class WebConfig implements WebMvcConfigurer {
    
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 移除不必要的转换器
        converters.removeIf(c -> c instanceof GsonHttpMessageConverter);
        
        // 添加自定义Jackson转换器
        MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
        converter.setSupportedMediaTypes(List.of(
            MediaType.APPLICATION_JSON,
            MediaType.TEXT_PLAIN // 支持text/plain
        ));
        converters.add(0, converter); // 优先使用
    }
}

5. 深度调试技巧

5.1 启用Spring调试日志

在application.properties中添加：

properties复制logging.level.org.springframework.web=DEBUG
logging.level.org.springframework.http=DEBUG

这样可以看到详细的内容协商过程：

code复制DEBUG - Checking if [application/json] is acceptable for [PageInfo]
DEBUG - No matching converter found for [PageInfo] to [application/json]

5.2 使用Postman测试

在Postman中测试时，注意：

1. Headers选项卡中明确设置Accept头
2. 查看Raw响应，观察实际的Content-Type
3. 检查响应体是否被正确转换

5.3 断点调试关键类

在以下类中设置断点可以深入理解处理流程：

1. AbstractMessageConverterMethodProcessor.writeWithMessageConverters()
2. RequestMappingHandlerAdapter.invokeHandlerMethod()
3. HandlerMethodReturnValueHandlerComposite.handleReturnValue()

6. 常见问题与解决方案

6.1 问题一：返回Map导致的异常

现象：返回Map对象时报同样的错误

原因：Map需要特殊处理，默认转换器可能不支持

解决方案：

java复制@GetMapping(value = "/map", produces = "application/json")
public Map<String, Object> getMap() {
    return Collections.singletonMap("key", "value");
}

6.2 问题二：循环引用问题

现象：对象间循环引用导致转换失败

解决方案：

java复制@Bean
public Jackson2ObjectMapperBuilder objectMapperBuilder() {
    return new Jackson2ObjectMapperBuilder()
        .failOnEmptyBeans(false)
        .serializationInclusion(JsonInclude.Include.NON_NULL)
        .featuresToDisable(SerializationFeature.FAIL_ON_EMPTY_BEANS);
}

6.3 问题三：日期格式不一致

现象：日期字段格式不符合预期

解决方案：

java复制@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
private LocalDateTime createTime;

7. 最佳实践总结

经过多次实践，我总结了以下经验：

1. 明确指定produces：每个@RestController方法都应该明确指定produces，避免依赖默认行为

2. 统一序列化库：项目中使用单一的JSON处理库（推荐Jackson）

3. 版本一致性：确保所有Jackson相关依赖版本一致（jackson-core, jackson-databind, jackson-annotations）

4. 测试覆盖：对API的多种Accept头情况进行测试，特别是：

   • application/json
   • application/xml
   • text/plain

5. 监控配置：定期检查自动配置报告，了解生效的MessageConverter：

   bash复制curl http://localhost:8080/actuator/beans | grep MessageConverter
   

在解决这个特定问题时，最关键的是理解Spring的内容协商机制。框架会按照以下顺序确定响应类型：

1. 首先检查URL路径扩展（如.json）
2. 然后检查请求参数（如?format=json）
3. 最后检查Accept头

如果这三个途径都无法确定可接受的响应类型，就会使用默认配置。因此，明确指定produces是最可靠的解决方案。