MyBatis 入門實戰 (一)：從 Maven 依賴到第一條 SQL 執行完整指南

項目結構預覽

mybatis-demo/
├── pom.xml
├── src/main/resources/
│   ├── mybatis.cfg.xml          # MyBatis 核心配置
│   ├── config.properties        # 數據庫連接屬性
│   └── com/mybatis/mapper/
│       └── UserMapper.xml       # SQL 映射文件
├── src/main/java/
│   ├── com.mybatis.entity.User  # 實體類
│   ├── com.mybatis.mapper.UserMapper  # Mapper 接口
│   ├── com.mybatis.tool.DBTools       # SqlSessionFactory 工具
│   └── com.mybatis.service.UserService # 業務測試

1. pom.xml 核心依賴

<dependencies>
    <!-- MyBatis 核心 -->
    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.5.13</version> <!-- 升級至穩定版 -->
    </dependency>
    <!-- MySQL 驅動 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId> <!-- 8.0+ 新坐標 -->
        <version>8.0.33</version>
    </dependency>
    <!-- 單元測試 -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

2. config.properties 數據庫配置

jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/mybatis_demo?useSSL=false&serverTimezone=UTC&characterEncoding=utf-8
jdbc.username=root
jdbc.password=123456

3. mybatis.cfg.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>
    <!-- 引入外屬性文件 -->
    <properties resource="config.properties"/>

    <!-- 類型別名：掃描 entity 包，類名即別名 -->
    <typeAliases>
        <package name="com.mybatis.entity"/>
    </typeAliases>

    <!-- 環境配置 -->
    <environments default="development">
        <environment id="development">
            <transactionManager type="JDBC"/> <!-- 事務管理器 -->
            <dataSource type="POOLED"> <!-- 連接池 -->
                <property name="driver" value="${jdbc.driver}"/>
                <property name="url" value="${jdbc.url}"/>
                <property name="username" value="${jdbc.username}"/>
                <property name="password" value="${jdbc.password}"/>
            </dataSource>
        </environment>
    </environments>

    <!-- 映射器掃描：自動關聯接口與 XML -->
    <mappers>
        <package name="com.mybatis.mapper"/>
    </mappers>
</configuration>

4. 實體類 User

package com.mybatis.entity;

public class User {
    private Integer id;
    private String username;
    private String password;
    private Double account;
    // 全參/無參構造器、getter/setter、toString 省略
}

5. Mapper 接口 UserMapper

package com.mybatis.mapper;

import com.mybatis.entity.User;
import java.util.List;

public interface UserMapper {
    int saveUser(User user);
    int updateUser(User user);
    int deleteUser(Integer id);
    User selectUserById(Integer id);
    List<User> selectAllUser();
}

6. UserMapper.xml SQL 映射（核心）

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.mybatis.mapper.UserMapper">

    <resultMap id="userMap" type="User">
        <id property="id" column="id"/>
        <result property="username" column="username"/>
        <result property="password" column="password"/>
        <result property="account" column="account"/>
    </resultMap>

    <insert id="saveUser" useGeneratedKeys="true" keyProperty="id" resultMap="userMap">
        INSERT INTO t_user (username, password, account)
        VALUES (#{username}, #{password}, #{account})
    </insert>

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

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

    <select id="selectUserById" resultMap="userMap">
        SELECT * FROM t_user WHERE id=#{id}
    </select>

    <select id="selectAllUser" resultMap="userMap">
        SELECT * FROM t_user
    </select>

</mapper>

7. DBTools：SqlSessionFactory 單例工具

package com.mybatis.tool;

import org.apache.ibatis.io.Resources;
import org.apache.ibatis.session.SqlSession;
import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.session.SqlSessionFactoryBuilder;
import java.io.Reader;

public class DBTools {
    private static SqlSessionFactory sessionFactory;

    static {
        try {
            Reader reader = Resources.getResourceAsReader("mybatis.cfg.xml");
            sessionFactory = new SqlSessionFactoryBuilder().build(reader);
        } catch (Exception e) {
            throw new ExceptionInInitializerError("MyBatis 初始化失敗", e);
        }
    }

    public static SqlSession getSession() {
        return sessionFactory.openSession(); // 手動提交模式
    }
}

8. UserService 測試類

package com.mybatis.service;

import com.mybatis.entity.User;
import com.mybatis.mapper.UserMapper;
import com.mybatis.tool.DBTools;
import org.apache.ibatis.session.SqlSession;

public class UserService {
    public void save(User user) {
        SqlSession session = DBTools.getSession();
        try {
            int count = session.getMapper(UserMapper.class).saveUser(user);
            session.commit(); // 手動提交！
            System.out.println("插入成功，ID=" + user.getId() + ", 影響行數=" + count);
        } catch (Exception e) {
            session.rollback();
            throw new RuntimeException(e);
        } finally {
            session.close();
        }
    }

    public static void main(String[] args) {
        User user = new User(null, "彬彬", "123456", 8.0);
        new UserService().save(user);
    }
}

9. 數據庫建表 SQL

CREATE TABLE t_user (
    id INT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL,
    password VARCHAR(50) NOT NULL,
    account DECIMAL(10,2)
);

關鍵避坑指南

1. namespace 必須 = Mapper 接口全限定名，否則綁定失敗。
2. resultMap 統一映射，避免列名與屬性名不一致（如下劃線 vs 駝峰）導致賦值失敗。可開啟 mapUnderscoreToCamelCase=true 自動轉換。
3. useGeneratedKeys + keyProperty 回寫自增 ID，插入後實體對象即可獲取 ID。
4. 無 Spring 托管時：必須手動 commit/rollback/close，否則數據不入庫/連接洩漏。
5. XML 文件放在 resources 目錄，Maven 打包才會輸出到 classpath，mapper 掃描才能找到。

下一步學習路線

• 動態 SQL：<where>, <if>, <foreach>, <choose>
• 關聯查詢：<resultMap> 中 <association> (一對一) / <collection> (一對多)
• 緩存機制：一級緩存、二級緩存、第三方緩存整合
• Spring 整合：MapperScannerConfigurer、事務管理、分頁插件