Spring整合MyBatis：從DataSource到Mapper掃描的完整配置指南

Spring管理DataSource、SqlSessionFactory、Mapper介面掃描，MyBatis負責SQL映射與執行。本文提供基於XML配置與Spring Boot自動配置兩種模式的完整步驟，助你快速落地DAO層開發。

模式一：傳統XML配置（Spring 5.x / 非Boot專案）

1. 依賴坐標

<dependencies>
    <dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.5.13</version></dependency>
    <dependency><groupId>org.mybatis</groupId><artifactId>mybatis-spring</artifactId><version>2.0.7</version></dependency>
    <dependency><groupId>org.springframework</groupId><artifactId>spring-jdbc</artifactId><version>5.3.27</version></dependency>
    <dependency><groupId>com.zaxxer</groupId><artifactId>HikariCP</artifactId><version>5.0.1</version></dependency>
    <dependency><groupId>mysql</groupId><artifactId>mysql-connector-java</artifactId><version>8.0.33</version></dependency>
</dependencies>

2. applicationContext.xml 核心Bean定義

<!-- 1. 資料來源（HikariCP） -->
<bean id="dataSource" class="com.zaxxer.hikari.HikariDataSource">
    <property name="jdbcUrl" value="jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=Asia/Taipei"/>
    <property name="username" value="app_user"/>
    <property name="password" value="${db.password}"/>
    <property name="maximumPoolSize" value="20"/>
</bean>

<!-- 2. SqlSessionFactory -->
<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource"/>
    <property name="mapperLocations" value="classpath*:mapper/**/*.xml"/>
    <property name="typeAliasesPackage" value="com.example.model"/>
    <property name="configurationProperties">
        <props>
            <prop key="mapUnderscoreToCamelCase">true</prop>
            <prop key="cacheEnabled">true</prop>
        </props>
    </property>
</bean>

<!-- 3. Mapper掃描器（自動將介面代理為Spring Bean） -->
<bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
    <property name="basePackage" value="com.example.dao"/>
    <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
</bean>

<!-- 4. 事務管理 -->
<bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
    <property name="dataSource" ref="dataSource"/>
</bean>
<tx:annotation-driven transaction-manager="transactionManager"/>

3. DAO介面與Mapper XML

// com.example.dao.UserDao.java
public interface UserDao {
    User selectById(Long id);
    int insert(User user);
    int update(User user);
    int deleteById(Long id);
}

<!-- resources/mapper/UserDao.xml -->
<mapper namespace="com.example.dao.UserDao">
    <resultMap id="userMap" type="com.example.model.User">
        <id property="id" column="id"/>
        <result property="username" column="username"/>
        <result property="email" column="email"/>
    </resultMap>

    <select id="selectById" resultMap="userMap">
        SELECT id, username, email FROM users WHERE id = #{id}
    </select>

    <insert id="insert" useGeneratedKeys="true" keyProperty="id">
        INSERT INTO users(username, email) VALUES(#{username}, #{email})
    </insert>

    <update id="update">
        UPDATE users SET username=#{username}, email=#{email} WHERE id=#{id}
    </update>

    <delete id="deleteById">
        DELETE FROM users WHERE id=#{id}
    </delete>
</mapper>

模式二：Spring Boot 3.x 自動配置（零XML，強烈推薦）

1. 依賴

<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

2. application.yml

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=Asia/Taipei
    username: app_user
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: 20

mybatis:
  mapper-locations: classpath*:mapper/**/*.xml
  type-aliases-package: com.example.model
  configuration:
    map-underscore-to-camel-case: true
    cache-enabled: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 開發期輸出SQL

3. Mapper介面加註解即可（無需MapperScannerConfigurer）

@Mapper // 或在啟動類加 @MapperScan("com.example.dao")
public interface UserDao { ... }

常見坑排查

• Mapper介面未被代理：缺少@Mapper或@MapperScan，或包路徑錯誤。
• XML未被載入：mapper-locations路徑不匹配，或XML未放入resources目錄導致打包遺漏。
• 欄位駝峰映射失效：確認mapUnderscoreToCamelCase=true且資料庫欄位為user_name、實體屬性為userName。
• 事務不生效：@Transactional加在private方法、同類內部呼叫、未掃描到切面包。

掌握以上配置，即可在Spring專案中流暢使用MyBatis進行增刪改查開發。