postForEntity突报415 Unsupported Media Type的原因排查求助

问题背景 #

项目中使用postForEntity调用外部API时突然抛出415 UNSUPPORTED_MEDIA_TYPE错误，错误信息显示无法确定原因，请求体为空。改用exchange方法并显式设置MediaType.APPLICATION_JSON请求头后问题解决。外部API接口（使用@RequestBody接收JSON参数）未做任何变更，此前postForEntity可正常调用，需排查异常突发原因，重点确认是否与依赖变更有关。

原调用代码：

final ActionDto actionDto = new ActionDto().setRequestId(requestId);
final ResponseEntity<ActionResponseDto> response = restTemplate.postForEntity(url, actionDto, ActionResponseDto.class);

修复后代码：

final HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
val entity = new HttpEntity(actionDto, headers);
final ResponseEntity<ActionResponseDto> response =
        restTemplate.exchange(
                url,
                HttpMethod.POST,
                entity,
                ActionResponseDto.class);

外部API接口代码：

@PostMapping("/action/start")
@ResponseStatus(HttpStatus.OK)
@Operation(summary = "Start the action")
public ResponseEntity<ActionResponseDto> startAction(@RequestBody final ActionDto requestDto) {
    // ...业务逻辑
}

核心原因分析 #

415错误本质是请求的Content-Type不被服务端接受：服务端通过@RequestBody接收JSON格式参数，要求请求头Content-Type为application/json，但postForEntity发送请求时未正确设置该头，或使用了服务端不支持的Content-Type（如text/plain）。

postForEntity默认行为：当传入Java对象作为请求体时，RestTemplate会根据注册的HttpMessageConverter自动选择Content-Type。正常情况下，若项目中存在MappingJackson2HttpMessageConverter（处理JSON转换），会默认使用application/json。但该逻辑被破坏时，就会出现异常。

与依赖变更相关的可能诱因 #

1. Spring/Spring Boot版本升级 #

• 部分Spring Boot版本升级会调整RestTemplate的自动配置逻辑，比如修改HttpMessageConverter的注册顺序。例如，若StringHttpMessageConverter的优先级被调整为高于MappingJackson2HttpMessageConverter，RestTemplate会将Java对象转为字符串（调用toString()），并设置Content-Type为text/plain，触发服务端415错误。
• 部分版本可能移除了默认注册的MappingJackson2HttpMessageConverter，需手动配置。

2. Jackson依赖变更 #

• jackson-databind、jackson-core等核心依赖版本升级或降级，可能导致MappingJackson2HttpMessageConverter无法正常初始化，RestTemplate无法找到合适的JSON转换器。
• 引入了其他JSON处理库（如Gson、Fastjson），Spring自动注册了对应的HttpMessageConverter（如GsonHttpMessageConverter），若该转换器未正确设置Content-Type为application/json，或转换逻辑不符合服务端要求，也会触发错误。

3. 依赖冲突 #

• 新增或更新其他依赖时，间接引入了低版本或不兼容的Jackson相关jar包，导致MappingJackson2HttpMessageConverter加载失败。例如，某些第三方依赖可能内置了旧版本Jackson，与项目中的高版本Jackson冲突。

4. 自定义RestTemplate配置变更 #

• 若项目中存在自定义RestTemplate配置（如添加/移除HttpMessageConverter、调整转换器顺序），变更后可能导致JSON转换器未被注册或优先级过低，postForEntity无法自动选择JSON格式。

验证排查步骤 #

1. 检查依赖版本差异：对比项目正常运行时和出现异常后的pom.xml/build.gradle，重点查看Spring Boot、Jackson相关依赖的版本变化。
2. 调试RestTemplate转换器：在代码中打印restTemplate.getMessageConverters()，确认是否包含MappingJackson2HttpMessageConverter，以及其在列表中的顺序是否靠前。
3. 抓包/日志验证请求头：使用抓包工具或开启RestTemplate日志，查看postForEntity发送请求时的实际Content-Type，确认是否为application/json。

内容的提问来源于stack exchange，提问作者ale.soft