SpringMVC 整合 MyBatis 實戰避坑指南：從依賴衝突、Mapper 掃描、編碼亂碼到 JSON 輸出全鏈路解決

前言：SSM 整合看似標準，實則坑點密集，本文記錄實戰中遇到的 8 大類問題及解決方案

SpringMVC + MyBatis (SSM) 是經典技術棧，但整合過程中依賴版本衝突、配置缺失、編碼不一、資源文件未打包等問題層出不窮。本文梳理 web.xml 版本、BeanCreationException、Mapper 綁定失敗、請求亂碼、參數綁定、Maven 編碼、JSON 輸出、依賴分析 八大類高頻問題，附帶排查思路與最佳實踐配置。

一、 web.xml Servlet 版本導致 listener-class 報紅

問題

<web-app version="3.0" ...> <!-- 3.0 版本不提倡 listener-class 配置 -->
    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>
</web-app>

解決

• 改用 version="2.5" 兼容舊寫法。
• 或升級 Tomcat 7+ 並改用 ServletContainerInitializer (Spring 3.1+ 支持無 web.xml 啟動)。
• 實測：後續調試正常後改回 3.0 也不報錯，IDE 靜態檢查誤報。

二、 BeanCreationException：缺少 spring-aspects 等核心依賴

錯誤堆棧

Caused by: java.lang.NoClassDefFoundError: org/aspectj/weaver/reflect/ReflectionWorld$ReflectionWorldException

排查

mvn dependency:tree

解決：統一版本屬性 + 顯式引入

<properties>
    <spring.version>4.2.4.RELEASE</spring.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
    <dependency><groupId>org.springframework</groupId><artifactId>spring-core</artifactId><version>${spring.version}</version></dependency>
    <dependency><groupId>org.springframework</groupId><artifactId>spring-orm</artifactId><version>${spring.version}</version></dependency>
    <dependency><groupId>org.springframework</groupId><artifactId>spring-aspects</artifactId><version>${spring.version}</version></dependency>
    <dependency><groupId>org.springframework</groupId><artifactId>spring-test</artifactId><version>${spring.version}</version></dependency>
    <dependency><groupId>org.springframework</groupId><artifactId>spring-jdbc</artifactId><version>${spring.version}</version></dependency>
    <!-- 其他依賴 -->
</dependencies>

三、 MyBatis Mapper 綁定失敗：BindingException: Invalid bound statement

根因

Maven 默認不打包 src/main/java 下的 *.xml，導致 target/classes 缺少 UserMapper.xml。

方案一：配置 resources 打包 (推薦)

<build>
    <resources>
        <resource>
            <directory>src/main/java</directory>
            <includes><include>**/*.xml</include></includes>
        </resource>
        <resource>
            <directory>src/main/resources</directory>
        </resource>
    </resources>
</build>

方案二：Mapper XML 移至 resources 目錄 (規範做法)

src/main/resources/mapper/UserMapper.xml  (與包結構對應)

對應 Mapper 接口包路徑，MyBatis 掃描更直觀。

四、 請求參數亂碼：POST/GET 雙管齊下

4.1 POST 亂碼：CharacterEncodingFilter (必須在 filter 鏈最前)

<filter>
    <filter-name>CharacterEncodingFilter</filter-name>
    <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
    <init-param><param-name>encoding</param-name><param-value>UTF-8</param-value></init-param>
    <init-param><param-name>forceEncoding</param-name><param-value>true</param-value></init-param>
</filter>
<filter-mapping>
    <filter-name>CharacterEncodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

4.2 GET 亂碼：Tomcat URIEncoding + 手動轉碼

• server.xml：<Connector port="8080" URIEncoding="UTF-8" />
• 代碼兜底：new String(request.getParameter("name").getBytes("ISO-8859-1"), "UTF-8")

五、 請求參數類型轉換：自定義 Converter

日期字符串 → Date 等非基本類型需註冊 Formatter/Converter 到 FormattingConversionService。

六、 Maven 平台編碼警告

[WARNING] Using platform encoding (GBK actually) to copy filtered resources

解決

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

七、 JSON 輸出 415/無轉換器錯誤：缺少 jackson-databind

錯誤

HttpMediaTypeNotSupportedException: Content type 'application/json;charset=UTF-8' not supported
No converter found for return value of type: class com.xxx.ItemsCustom

根因

SpringMVC 默認消息轉換器需 jackson-databind，舊版 jackson-mapper-asl 不夠。

解決

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.7.2</version>
</dependency>

配合 <mvc:annotation-driven> 自動註冊 MappingJackson2HttpMessageConverter。

八、 依賴分析：mvn dependency:analyze 輸出解讀

Used undeclared dependencies: spring-context, spring-web, spring-beans (實際由 spring-webmvc 傳遞)
Unused declared dependencies: spring-orm, spring-aspects, spring-test, spring-jdbc, mysql, mybatis-spring, log4j...

說明

• Used undeclared：被傳遞依賴隱式使用，無需顯式聲明。
• Unused declared：顯式聲明但未直接使用 (可能間接被其他依賴需要)。
• 策略：核心功能依賴顯式聲明 (如 spring-orm 用於 MyBatis 整合)，工具類依賴 (test) 標記 <scope>test</scope>，定期 mvn dependency:analyze 清理。

九、 待深究的 IDE 警告 (不影響運行)

1. contextConfigLocation 用 WEB-INF/classes/... 報紅，改 classpath:... 不紅，但運行均正常 (路徑解析時機不同)。
2. <list> 標籤在 conversionService 注入 converters 時 IDE 報紅，去掉也能運行 (Spring 容器自動處理集合合並)。

結語

SSM 整合的核心難點在於 依賴版本鎖定、資源文件打包、編碼統一、消息轉換器配置 四大塊。建立標準化 pom.xml 模板、web.xml 模板、spring-mvc.xml 模板，新項目直接複製微調，能避開 90% 的坑。遇到異常先看堆棧定位 NoClassDefFoundError/BindingException，再對照依賴樹與打包產物排查，系統性解決而非盲目嘗試。