MyBatis 入門筆記 (上) - 從 iBatis 遷移到 MyBatis 核心配置與映射實戰

MyBatis 3.x 入門完全指南：環境搭建、核心配置、DAO 接口綁定、動態 SQL 基礎

MyBatis 是 iBatis 2.x 的升級版，提供了更強大的映射能力、註解支持、OGNL 表達式。本文記錄從零搭建 MyBatis 環境、核心配置文件解析、映射文件編寫、DAO 接口綁定機制的全過程。

一、MyBatis vs iBatis 核心升級點

二、環境搭建 (Maven)

<dependencies>
  <!-- MyBatis 核心 -->
  <dependency>
    <groupId>org.mybatis</groupId>
    <artifactId>mybatis</artifactId>
    <version>3.5.15</version>
  </dependency>
  <!-- MySQL 驅動 -->
  <dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
  </dependency>
  <!-- 測試用 JUnit -->
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.13.2</version>
    <scope>test</scope>
  </dependency>
</dependencies>

三、核心配置文件 mybatis-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
  "https://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
  <!-- 1. 屬性文件外置 -->
  <properties resource="db.properties"/>

  <!-- 2. 環境配置 (可多環境) -->
  <environments default="development">
    <environment id="development">
      <transactionManager type="JDBC"/>
      <dataSource type="POOLED">
        <property name="driver" value="${driver}"/>
        <property name="url" value="${url}"/>
        <property name="username" value="${username}"/>
        <property name="password" value="${password}"/>
      </dataSource>
    </environment>
  </environments>

  <!-- 3. 映射器註冊 (三種方式) -->
  <mappers>
    <!-- 方式 A: 相對類路徑 -->
    <mapper resource="mapper/UserMapper.xml"/>
    <!-- 方式 B: 接口全限定名 (需 mapper 文件同目錄同名) -->
    <mapper class="com.xxx.mapper.UserMapper"/>
    <!-- 方式 C: 包掃描 (推薦) -->
    <package name="com.xxx.mapper"/>
  </mappers>
</configuration>

四、映射文件 UserMapper.xml 與接口綁定

接口定義：

public interface UserMapper {
    User selectById(@Param("id") Long id);
    List<User> selectByCondition(@Param("user") User user);
    int insert(User user);
    int update(User user);
    int deleteById(Long id);
}

映射文件 (namespace = 接口全限定名)：

<mapper namespace="com.xxx.mapper.UserMapper">
  <resultMap id="userResult" type="com.xxx.entity.User">
    <id property="id" column="id"/>
    <result property="username" column="username"/>
    <result property="email" column="email"/>
    <result property="createTime" column="create_time"/>
  </resultMap>

  <select id="selectById" resultMap="userResult">
    SELECT id, username, email, create_time FROM t_user WHERE id = #{id}
  </select>

  <select id="selectByCondition" resultMap="userResult">
    SELECT * FROM t_user
    <where>
      <if test="user.username != null"> AND username LIKE CONCAT('%', #{user.username}, '%') </if>
      <if test="user.email != null"> AND email = #{user.email} </if>
    </where>
  </select>

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

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

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

五、關鍵機制解析

1. Namespace 綁定：namespace 必須精確等於接口全限定名，MyBatis 据此生成接口代理對象。
2. 方法名匹配：接口方法名 = <select|insert|update|delete> 的 id 屬性。
3. 參數綁定：單參數直接用 #{paramName}，多參數需 @Param 指定名稱，或封裝 POJO。
4. 結果映射：resultMap 解決列名與屬性名不一致 (駝峰/下劃線)，支援嵌套結果映射 (<association>/<collection>) 解決 N+1。
5. 動態 SQL：<where> 智能去除首個 AND/OR，<foreach> 批量插入/IN 查詢。

六、啟動測試

public class MyBatisTest {
    private SqlSessionFactory sqlSessionFactory;

    @Before
    public void init() throws IOException {
        String resource = "mybatis-config.xml";
        InputStream is = Resources.getResourceAsStream(resource);
        sqlSessionFactory = new SqlSessionFactoryBuilder().build(is);
    }

    @Test
    public void testSelectById() {
        try (SqlSession session = sqlSessionFactory.openSession()) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            User user = mapper.selectById(1L);
            System.out.println(user);
        }
    }
}

七、下篇預告

• 進階映射：一對一、一對多、多對多嵌套結果映射實戰。
• 動態 SQL 深度：<bind>/<script>/<trim> 進階技巧。
• 插件機制：分頁插件 (PageHelper) 原理與自定義插件開發。
• Spring 整合：MapperScannerConfigurer、事務管理、多数據源。

MyBatis 以「SQL 為中心」的設計哲學，給予開發者最大靈活性，配合接口綁定機制，實現了 DAO 層零實現類的極致簡潔。