炸锅了！HttpMediaTypeNotAcceptableException 血案背后，竟藏着 Spring MVC 最阴险的潜规则！

2025-07-10 02:37:21.456 ERROR 12345 --- [nio-8080-exec-5] o.s.web.servlet.handler.AbstractHandlerExceptionResolver : Resolved [org.springframework.web.HttpMediaTypeNotAcceptableException: Could not find acceptable representation]2025-07-10 02:37:22.103 WARN 12345 --- [nio-8080-exec-7] o.s.web.servlet.PageNotFound : No mapping for GET /error

// 前端请求（错误示例）fetch('/api/order', {  headers: {    'Accept': 'application/xml' // 只接受XML  }})// 后端接口@RestControllerpublic class OrderController {  @GetMapping("/api/order")  public OrderDTO getOrder() { // 返回JSON格式    return new OrderDTO(1L, "iPhone 15");  }}

<!-- 漏了这个依赖，JSON转换器就没法工作 --><dependency>  <groupId>com.fasterxml.jackson.core</groupId>  <artifactId>jackson-databind</artifactId>  <version>2.15.2</version></dependency>

// 错误示例：自定义转换器覆盖了默认配置@Configurationpublic class WebConfig implements WebMvcConfigurer {  @Override  public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {    // 只加了自定义转换器，没加默认的Jackson转换器    converters.add(new ProtobufHttpMessageConverter());  }}

@GetMapping("/api/order/{id}")public OrderDTO getOrder(@PathVariable Long id) {  OrderDO order = orderMapper.selectById(id);  return order == null ? null : convert(order); // 可能返回null}

@ControllerAdvicepublic class GlobalExceptionHandler {  @ExceptionHandler(BusinessException.class)  public String handleBusinessException(BusinessException e) {    // 错误：返回String（默认Content-Type: text/plain）    return e.getMessage();  }}

// 正确示例：明确支持JSON格式@GetMapping(value = "/api/order", produces = MediaType.APPLICATION_JSON_VALUE)public OrderDTO getOrder() {  return new OrderDTO(1L, "iPhone 15");}

// 前端请求优化fetch('/api/order', {  headers: {    'Accept': 'application/json, */*;q=0.9' // 放宽要求  }})

<!-- JSON转换器依赖 --><dependency>  <groupId>com.fasterxml.jackson.core</groupId>  <artifactId>jackson-databind</artifactId></dependency><!-- 如果需要XML支持，再加这个 --><dependency>  <groupId>com.fasterxml.jackson.dataformat</groupId>  <artifactId>jackson-dataformat-xml</artifactId></dependency>

@Configurationpublic class WebConfig implements WebMvcConfigurer {  @Override  public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {    // 关键：用extend而不是set，保留默认转换器    // 添加自定义转换器（比如protobuf）    converters.add(new ProtobufHttpMessageConverter());        // 可选：调整Jackson转换器的顺序（放到前面优先处理JSON）    for (int i = 0; i < converters.size(); i++) {      if (converters.get(i) instanceof MappingJackson2HttpMessageConverter) {        MappingJackson2HttpMessageConverter jacksonConverter = (MappingJackson2HttpMessageConverter) converters.remove(i);        converters.add(0, jacksonConverter); // 放到第一个        break;      }    }  }}

// 通用响应体@Datapublic class ApiResponse<T> {  private int code;  private String message;  private T data;  public static <T> ApiResponse<T> success(T data) {    ApiResponse<T> response = new ApiResponse<>();    response.code = 200;    response.message = "success";    response.data = data; // 允许data为null，但外层对象非null    return response;  }}// 接口改造@GetMapping("/api/order/{id}")public ApiResponse<OrderDTO> getOrder(@PathVariable Long id) {  OrderDO order = orderMapper.selectById(id);  return ApiResponse.success(order == null ? null : convert(order));}

spring:  jackson:    serialization-inclusion: ALWAYS # 总是包含null字段（默认就是ALWAYS）    default-property-inclusion: ALWAYS

@Beanpublic MappingJackson2HttpMessageConverter mappingJackson2HttpMessageConverter() {  MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();  ObjectMapper objectMapper = new ObjectMapper();  // 包含所有字段（包括null）  objectMapper.setSerializationInclusion(JsonInclude.Include.ALWAYS);  converter.setObjectMapper(objectMapper);  return converter;}

@ControllerAdvicepublic class GlobalExceptionHandler {  // 明确返回JSON格式  @ExceptionHandler(BusinessException.class)  @ResponseBody  @RequestMapping(produces = MediaType.APPLICATION_JSON_VALUE)  public ApiResponse<Void> handleBusinessException(BusinessException e) {    ApiResponse<Void> response = new ApiResponse<>();    response.code = e.getCode();    response.message = e.getMessage();    return response;  }  // 处理其他异常（比如404、500）  @ExceptionHandler(Exception.class)  @ResponseBody  @RequestMapping(produces = MediaType.APPLICATION_JSON_VALUE)  public ApiResponse<Void> handleException(Exception e) {    ApiResponse<Void> response = new ApiResponse<>();    response.code = 500;    response.message = "服务器内部错误";    return response;  }}

# 接口开发规范V1.0## 1. 响应格式- 统一使用ApiResponse<T>作为返回体- 成功：{"code":200,"message":"success","data":...}- 失败：{"code":xxx,"message":"错误信息","data":null}## 2. 注解要求- 类上必须加@RestController- 方法上必须加@GetMapping/@PostMapping等，并指定produces  示例：@GetMapping(value = "/api/xxx", produces = MediaType.APPLICATION_JSON_VALUE)## 3. 异常处理- 业务异常必须抛BusinessException，由全局处理器统一处理- 禁止在接口中捕获异常后返回String或其他非ApiResponse格式

@SpringBootTest@AutoConfigureMockMvcpublic class OrderControllerTest {  @Autowired  private MockMvc mockMvc;  // 测试Accept: application/json（正常场景）  @Test  public void testGetOrderWithJsonAccept() throws Exception {    mockMvc.perform(get("/api/order/1")            .header("Accept", "application/json"))            .andExpect(status().isOk())            .andExpect(content().contentType(MediaType.APPLICATION_JSON));  }  // 测试Accept: application/xml（应该返回406）  @Test  public void testGetOrderWithXmlAccept() throws Exception {    mockMvc.perform(get("/api/order/1")            .header("Accept", "application/xml"))            .andExpect(status().isNotAcceptable()); // 预期406  }  // 测试返回null的场景（应该返回JSON）  @Test  public void testGetNonExistOrder() throws Exception {    mockMvc.perform(get("/api/order/999")            .header("Accept", "application/json"))            .andExpect(status().isOk())            .andExpect(jsonPath("$.code").value(200))            .andExpect(jsonPath("$.data").doesNotExist()); // 假设不存在时data为null  }}

groups:- name: http_status_rules  rules:  - alert: Http406ErrorIncreased    expr: sum(rate(http_server_requests_seconds_count{status="406"}[5m])) > 0    for: 1m    labels:      severity: critical    annotations:      summary: "406错误数量增加"      description: "过去5分钟内出现{{ $value }}次406错误，可能是HttpMediaTypeNotAcceptableException导致"