当前位置：首页 > news >正文

Spring Boot项目里RestTemplate遇到text/html响应报错？手把手教你自定义HttpMessageConverter搞定它

news 2026/4/22 11:41:25

Spring Boot项目中RestTemplate处理text/html响应的实战指南

1. 当RestTemplate遇上非标准响应

作为一名长期使用Spring Boot进行后端开发的工程师，我经常遇到需要调用第三方API的情况。最近在对接一个老旧的系统时，遇到了一个令人头疼的问题：对方返回的明明是JSON数据，但Content-Type却标记为text/html。这导致RestTemplate直接抛出了UnknownContentTypeException异常，项目组为此浪费了大半天时间排查问题。

这种情况在实际开发中并不罕见。很多遗留系统或者不规范实现的API服务，常常会返回与内容不匹配的Content-Type。特别是当服务端发生错误时，有些框架会默认以text/html格式返回错误信息，即使内容实际上是JSON结构。

提示：Content-Type是HTTP协议中非常重要的头部字段，它告诉客户端如何解析响应体内容。常见的类型包括application/json、text/xml、text/plain等。

RestTemplate默认配置的HttpMessageConverter只处理标准的JSON响应（application/json），对于text/html类型的响应会直接拒绝处理。这虽然符合规范，但在实际业务场景中却可能造成不便。

2. 深入理解HttpMessageConverter机制

2.1 RestTemplate的消息转换原理

Spring的RestTemplate依赖于HttpMessageConverter来处理请求和响应。当收到服务器响应时，它会按照以下步骤工作：

检查响应头的Content-Type值
遍历已注册的HttpMessageConverter列表
找到第一个能处理该Content-Type和目标类型的转换器
使用该转换器将响应体转换为Java对象

默认情况下，RestTemplate会注册以下常用的转换器：

MappingJackson2HttpMessageConverter（处理application/json）
StringHttpMessageConverter（处理text/plain）
ByteArrayHttpMessageConverter
其他基于JAXB或XML的转换器

2.2 为什么text/html会报错

查看MappingJackson2HttpMessageConverter的源码，我们可以看到它的构造函数：

public MappingJackson2HttpMessageConverter(ObjectMapper objectMapper) { super(objectMapper, MediaType.APPLICATION_JSON, new MediaType("application", "*+json")); }

这个转换器明确声明它只支持两种媒体类型：

application/json
application/*+json

当遇到text/html时，由于没有匹配的转换器，RestTemplate就会抛出异常。

3. 自定义RestTemplate配置方案

3.1 基础解决方案：扩展支持的媒体类型

最简单的解决方案是创建一个新的MappingJackson2HttpMessageConverter实例，并扩展它支持的媒体类型：

@Bean public RestTemplate restTemplate() { RestTemplate restTemplate = new RestTemplate(); // 获取现有的转换器列表 List<HttpMessageConverter<?>> converters = new ArrayList<>(restTemplate.getMessageConverters()); // 创建自定义的JSON转换器 MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter(); converter.setSupportedMediaTypes(Arrays.asList( MediaType.APPLICATION_JSON, MediaType.TEXT_HTML, MediaType.TEXT_PLAIN )); // 添加到转换器列表 converters.add(converter); restTemplate.setMessageConverters(converters); return restTemplate; }

这种方法简单直接，但也有几个潜在问题：

会保留原有的MappingJackson2HttpMessageConverter，可能导致重复处理
转换器顺序可能影响处理结果
全局修改可能影响其他不需要这种处理的场景

3.2 更优雅的方案：替换默认转换器

更推荐的做法是找到并替换默认的JSON转换器：

@Bean public RestTemplate restTemplate() { RestTemplate restTemplate = new RestTemplate(); restTemplate.getMessageConverters().stream() .filter(c -> c instanceof MappingJackson2HttpMessageConverter) .findFirst() .ifPresent(converter -> { ((MappingJackson2HttpMessageConverter)converter) .setSupportedMediaTypes(Arrays.asList( MediaType.APPLICATION_JSON, MediaType.TEXT_HTML, MediaType.TEXT_PLAIN )); }); return restTemplate; }

这种方法的好处是：

只修改现有的转换器，不增加新的实例
保持转换器列表的简洁性
不会影响其他类型的处理

3.3 高级配置：使用RestTemplateBuilder

在Spring Boot中，更现代的方式是使用RestTemplateBuilder：

@Bean public RestTemplate restTemplate(RestTemplateBuilder builder) { return builder .additionalMessageConverters( new MappingJackson2HttpMessageConverter() {{ setSupportedMediaTypes(Arrays.asList( MediaType.APPLICATION_JSON, MediaType.TEXT_HTML, MediaType.TEXT_PLAIN )); }}) .build(); }

RestTemplateBuilder提供了更流畅的API和更好的默认配置，是Spring Boot推荐的方式。

4. 处理非标准API的最佳实践

4.1 防御性编程策略

在实际项目中，处理不规范的API时，建议采取以下防御性措施：

内容嗅探：即使Content-Type不正确，也可以尝试解析内容
错误处理：为不同的错误情况提供友好的错误信息
日志记录：详细记录请求和响应，便于调试
重试机制：对临时性错误实现自动重试

4.2 性能与兼容性考量

扩展RestTemplate的功能时，需要考虑以下因素：

考虑因素	说明	建议
转换器顺序	先匹配的转换器会被使用	将最常用的转换器放在前面
内存占用	每个转换器都有开销	避免重复添加相同类型的转换器
线程安全	RestTemplate本身是线程安全的	确保自定义转换器也是线程安全的
异常处理	不同的转换器可能抛出不同的异常	统一异常处理逻辑

4.3 替代方案：WebClient

对于新项目，可以考虑使用Spring 5引入的WebClient作为RestTemplate的替代品：

WebClient.builder() .codecs(configurer -> { configurer.defaultCodecs() .jackson2JsonDecoder(new Jackson2JsonDecoder() {{ setSupportedMediaTypes(Arrays.asList( MediaType.APPLICATION_JSON, MediaType.TEXT_HTML, MediaType.TEXT_PLAIN )); }}); }) .build();

WebClient提供了更现代的API和更好的非阻塞IO支持，特别是在微服务架构中表现更优。