Spring Boot控制器返回含接口的复杂对象时的异常解决

问题核心原因 #

出现HttpMessageNotWritableException的根本原因是JSON序列化器（默认是Jackson）无法处理接口类型的属性——接口本身没有具体字段和实例信息，序列化时无法确定要输出的结构，进而触发异常；后续的IllegalStateException: Cannot call sendError() after the response has been committed是异常处理的连锁问题，核心还是接口属性的序列化失败。

解决方案（无需额外添加HttpMessageConverter，优先用Jackson注解或配置） #

下面是几种针对不同场景的有效解决方法：

1. 给接口添加类型识别注解（多实现类场景）

如果ReportHeader有多个实现类，在接口上通过@JsonTypeInfo和@JsonSubTypes标记实现类的映射关系，让Jackson能识别具体类型：

import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;

@JsonTypeInfo(
    use = JsonTypeInfo.Id.NAME,
    include = JsonTypeInfo.As.PROPERTY,
    property = "headerType" // 序列化时会添加该字段标记实现类类型
)
@JsonSubTypes({
    @JsonSubTypes.Type(value = PdfReportHeader.class, name = "pdf"),
    @JsonSubTypes.Type(value = ExcelReportHeader.class, name = "excel")
})
public interface ReportHeader {
    // 接口方法定义
}

这样序列化ReportHolder时，会自动在reportHeader属性中加入headerType字段，Jackson就能正确解析具体实现类的结构。

2. 指定属性的序列化类型（单实现类场景）

如果ReportHeader只有一个实现类，直接在ReportHolder的属性上用@JsonSerialize指定具体实现类即可：

import com.fasterxml.jackson.databind.annotation.JsonSerialize;

public class ReportHolder {
    // 指定用ConcreteReportHeader的规则序列化reportHeader属性
    @JsonSerialize(as = ConcreteReportHeader.class)
    private ReportHeader reportHeader;
    
    // 其他属性、getter/setter方法
}

3. 全局配置Jackson映射规则（全局生效场景）

如果需要让整个应用默认将ReportHeader映射到某个实现类，可以通过配置类自定义Jackson的ObjectMapper：

import com.fasterxml.jackson.databind.AbstractTypeResolver;
import com.fasterxml.jackson.databind.SimpleAbstractTypeResolver;
import com.fasterxml.jackson.databind.module.SimpleModule;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.util.List;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        Jackson2ObjectMapperBuilder builder = new Jackson2ObjectMapperBuilder();
        // 注册自定义模块，指定接口与实现类的映射
        builder.modulesToInstall(new SimpleModule() {
            @Override
            public void setupModule(SetupContext context) {
                AbstractTypeResolver resolver = new SimpleAbstractTypeResolver()
                        .addMapping(ReportHeader.class, ConcreteReportHeader.class);
                context.addAbstractTypeResolver(resolver);
            }
        });
        converters.add(new MappingJackson2HttpMessageConverter(builder.build()));
    }
}

这种方式会让所有ReportHeader类型的属性都默认用指定的实现类序列化。

总结 #

不需要额外添加新的HttpMessageConverter，通过Jackson的注解配置或全局ObjectMapper调整，就能解决接口属性的序列化问题，从根源上消除HttpMessageNotWritableException及后续连锁异常。

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