Spring MVC 返回 JSON 遇 406 錯誤？FastJson 配置全解析

Spring MVC 返回 JSON 遇 406 錯誤？FastJson 配置全解析

現象：Controller 方法加 @ResponseBody 返回對象，瀏覽器/前端報 **HTTP 406 Not Acceptable**，後端控制台無異常。根因：**Spring 默認消息轉換器無法匹配請求 Accept 頭**，或 **FastJson 轉換器未正確註冊/優先級不夠**。

一、406 錯誤核心機制

• 客戶端發送請求頭：Accept: application/json (或瀏覽器默認 text/html)
• Spring 遍歷 HttpMessageConverter 列表，尋找 canWrite(clazz, mediaType) 返回 true 的轉換器
• 若無匹配 → 拋 HttpMediaTypeNotAcceptableException → 返回 406

二、FastJson 完美配置方案 (Spring XML)

<mvc:annotation-driven>
    <mvc:message-converters register-defaults="true">
        <!-- FastJson 轉換器，置於首位提升優先級 -->
        <bean class="com.alibaba.fastjson.support.spring.FastJsonHttpMessageConverter">
            <property name="supportedMediaTypes">
                <list>
                    <value>application/json;charset=UTF-8</value>
                    <value>text/html;charset=UTF-8</value> <!-- 關鍵：兼容瀏覽器直接訪問 Accept=text/html -->
                </list>
            </property>
            <property name="features">
                <array>
                    <value>WriteMapNullValue</value>          <!-- 輸出 null 字段 -->
                    <value>WriteNullStringAsEmpty</value>     <!-- null 字串輸出 "" -->
                    <value>WriteNullListAsEmpty</value>       <!-- null 集合輸出 [] -->
                    <value>WriteNullNumberAsZero</value>      <!-- null 數字輸出 0 -->
                    <value>WriteNullBooleanAsFalse</value>    <!-- null 布爾輸出 false -->
                    <value>DisableCircularReferenceDetect</value> <!-- 禁用循環引用檢測 (提升性能，慎用) -->
                    <value>BrowserCompatible</value>           <!-- 瀏覽器兼容 (特殊字符轉義) -->
                </array>
            </property>
        </bean>
    </mvc:message-converters>
</mvc:annotation-driven>

三、Spring Boot 2.x / 3.x 自動配置時代的最佳實踐

Spring Boot 內置 HttpMessageConvertersAutoConfiguration，**無需 XML**，僅需引入依賴即可自動生效：

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.83</version> <!-- 或 2.x 版本 -->
</dependency>

若需自定義配置，創建配置類：

@Configuration
public class FastJsonConfig {
    @Bean
    public HttpMessageConverter<?> fastJsonHttpMessageConverter() {
        FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();
        FastJsonConfig config = new FastJsonConfig();
        config.setSerializerFeatures(
            SerializerFeature.WriteMapNullValue,
            SerializerFeature.WriteNullStringAsEmpty,
            SerializerFeature.WriteNullListAsEmpty,
            SerializerFeature.DisableCircularReferenceDetect,
            SerializerFeature.BrowserCompatible
        );
        config.setCharset(StandardCharsets.UTF_8);
        // 關鍵：支持 text/html 避免 406
        converter.setSupportedMediaTypes(Arrays.asList(
            MediaType.APPLICATION_JSON_UTF8,
            MediaType.TEXT_HTML
        ));
        converter.setFastJsonConfig(config);
        return converter;
    }
}

四、常見 406 根因排查清單

五、Jackson vs FastJson：如何選？

• Spring Boot 3+ / 新項目：首選 **Jackson** (默認內置、標準化、模塊化、GraalVM 原生支持)
• 舊項目維護 / 特殊性能場景：FastJson 1.2.83+ (安全修復版) 或 2.x
• 遷移建議：逐步替換 @JSONField → @JsonProperty、SerializerFeature → JsonSerialize、統一 DTO 層

六、總結

406 錯誤本質是 **內容協商失敗**。核心解法：**確保 FastJson 轉換器註冊、優先級最高、支持 `text/html` MediaType**。Spring Boot 時代只需引入依賴即自動生效，XML 時代需在 `` 顯式聲明並添加 `text/html` 支持。建議新項目標準化於 Jackson，避免雙轉換器共存帶來的不可預期行為。

1. 上一篇文章： 設計模式深度解析：簡單工廠 vs 工廠方法 vs 抽象工廠 進化史與實戰選型
2. 下一篇文章： FreeMarker 條件判斷指令 <#if> 完整使用指南與常見坑

Java 綜合教學

HBase WAL (Write Ahead Log) 深度解析：原子性保障、刷盤機制與源碼級調用鏈

WAL 在 HBase 寫入路徑中的定位 Client →

Java 23 種設計模式全解析：創建型、結構型、行為型完整指南（含六大原則與代碼範例）

前言 設計模式是軟體工程的基石，本文系統梳理 GoF 23

Java 集合框架全景圖譜：List/Set/Map 體系、Fail-Fast 機制與 CopyOnWrite 解決方案

集合框架核心結構 Java Collections Fram

Java Package 與 Import 完整指南：命名空間管理與類導入實戰

Java Package 與 Import 完整指南：命名空