Spring MVC 4.x 返回 JSON 完整配置指南：@ResponseBody、MessageConverter 與版本差異

Spring MVC 4.0+ 實現 RESTful JSON 響應的標準化配置與避坑指南

Spring MVC 4.0 引入 MappingJackson2HttpMessageConverter（基於 Jackson 2.x），大幅簡化 JSON 序列化配置。本文提供基於 XML 的完整配置、Controller 寫法、前端 ExtJS 異步調用示例，並對比 4.0 以下版本（Jackson 1.x）的差異。

一、Maven 依賴 (Spring 4.2.3 為例)

<dependencies>
  <!-- Spring Web MVC -->
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>4.2.3.RELEASE</version>
  </dependency>
  <!-- Jackson 2.x -->
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.10</version>
  </dependency>
  <!-- Servlet API -->
  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

二、web.xml 配置 DispatcherServlet

<web-app version="2.5" xmlns="https://java.sun.com/xml/ns/javaee"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://java.sun.com/xml/ns/javaee https://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  <servlet>
    <servlet-name>SpringMVC</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>classpath:applicationContext.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <servlet-mapping>
    <servlet-name>SpringMVC</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>
</web-app>

三、Spring MVC 核心配置 (applicationContext.xml) —— 4.0+ 標準寫法

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="https://www.springframework.org/schema/beans"
       xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="https://www.springframework.org/schema/context"
       xmlns:mvc="https://www.springframework.org/schema/mvc"
       xsi:schemaLocation="
         https://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
         https://www.springframework.org/schema/context https://www.springframework.org/schema/context/spring-context.xsd
         https://www.springframework.org/schema/mvc https://www.springframework.org/schema/mvc/spring-mvc.xsd">

  <!-- 1. 掃描 Controller -->
  <context:component-scan base-package="cn.xugang.controller"/>

  <!-- 2. 關鍵：啟用註解驅動 + 內容協商管理器 -->
  <mvc:annotation-driven content-negotiation-manager="contentNegotiationManager"/>

  <!-- 3. 靜態資源處理 -->
  <mvc:default-servlet-handler/>

  <!-- 4. 內容協商管理器：禁用路徑擴展名/參數模式，僅依賴 Accept Header -->
  <bean id="contentNegotiationManager" class="org.springframework.web.accept.ContentNegotiationManagerFactoryBean">
    <property name="favorPathExtension" value="false"/>
    <property name="favorParameter" value="false"/>
    <property name="ignoreAcceptHeader" value="false"/>
    <property name="mediaTypes">
      <map>
        <entry key="json" value="application/json"/>
        <entry key="xml" value="application/xml"/>
      </map>
    </property>
  </bean>

  <!-- 5. Jackson 2 轉換器：支持 UTF-8 文本輸出 -->
  <bean id="jacksonConverter" class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter">
    <property name="supportedMediaTypes">
      <list>
        <value>application/json;charset=UTF-8</value>
        <value>text/html;charset=UTF-8</value> <!-- 兼容瀏覽器直接訪問 -->
      </list>
    </property>
  </bean>

  <!-- 6. 視圖解析器 (JSP) -->
  <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="prefix" value="/WEB-INF/jsp/"/>
    <property name="suffix" value=".jsp"/>
  </bean>
</beans>

四、Controller 實現

@Controller
@RequestMapping("/user")
public class UserController {

    @GetMapping(value = "/hello", produces = "application/json;charset=UTF-8")
    @ResponseBody
    public User hello() {
        User user = new User();
        user.setName("test");
        user.setAge(19);
        return user; // 自動序列化為 JSON
    }

    @GetMapping("/page")
    public String page() {
        return "hello"; // 視圖解析 -> /WEB-INF/jsp/hello.jsp
    }
}

五、實體類

public class User {
    private String name;
    private int age;
    // getter/setter
    // 建議加上 @JsonProperty 精確控制字段名
}

六、前端 ExtJS 異步請求

Ext.onReady(function() {
    Ext.define('User', {
        extend: 'Ext.data.Model',
        fields: ['name', 'age']
    });

    var store = Ext.create('Ext.data.Store', {
        model: 'User',
        proxy: {
            type: 'ajax',
            url: '/SpringMVC4/user/hello', // 根據部署上下文調整
            reader: { type: 'json' }
        }
    });

    store.load({
        callback: function(records, operation, success) {
            if (success) {
                var msgs = [];
                store.each(function(rec) {
                    msgs.push(rec.get('name') + ' ' + rec.get('age'));
                });
                Ext.Msg.alert('提示', msgs.join('
'));
            }
        }
    });
});

七、版本差異總結：Spring MVC 3.x (Jackson 1.x) 配置對比

3.x 遺留項目最小配置片段：

<bean class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter">
  <property name="supportedMediaTypes">
    <list><value>application/json;charset=UTF-8</value></list>
  </property>
</bean>
<bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
  <property name="messageConverters">
    <list><ref bean="jacksonConverter"/></list>
  </property>
</bean>

八、常見問題排查

1. 406 Not Acceptable：請求頭 Accept 無匹配 MediaType。檢查 produces 屬性、ContentNegotiationManager 配置、Jackson 依賴是否在 classpath。
2. 中文亂碼：確保 supportedMediaTypes 含 charset=UTF-8；Tomcat URIEncoding=UTF-8；數據庫連接 characterEncoding=utf8。
3. 循環引用：實體雙向關聯導致序列化死循環。使用 @JsonIgnore、@JsonManagedReference/@JsonBackReference 或 DTO 斷開循環。
4. 日期格式：全局配置 ObjectMapper：mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"))。

九、總結

Spring MVC 4.x+ 通過 <mvc:annotation-driven> + Jackson 2.x 實現零配置 JSON 序列化。核心要點：引入 jackson-databind、啟用註解驅動、Controller 方法加 @ResponseBody（或類上 @RestController）、設置 produces 指定媒體類型。升級舊項目時注意包名與轉換器類的變更。