您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 綜合教學

MyBatis 入門實戰：從環境搭建到 HelloWorld 完整流程 (含 Maven 依賴、配置文件、映射器、測試代碼)

編輯：Java 綜合教學

前言：MyBatis 是「半自動」ORM 榜樣，SQL 與代碼分離，靈活可控，本文手把手帶你跑通第一個 Demo

MyBatis (原 iBatis) 以 SQL 獨立配置、動態 SQL 強大、映射關係可見 著稱，是 Java 持久層主流選擇。本文基於 MyBatis 3.2.8 + MySQL + Eclipse，完整記錄 JAR 包準備、數據庫建表、項目結構、核心配置 (mybatis-config.xml)、映射文件 (UserMapper.xml)、實體類、測試代碼、日誌輸出 全流程，可直接複製運行。

一、環境準備

1.1 核心 JAR 包 (手動導入或 Maven)


mybatis-3.2.8.jar
mysql-connector-java-5.1.38-bin.jar
# 依賴包 (MyBatis 3.2.8 自帶或需補全)
asm-3.3.1.jar
cglib-2.2.2.jar
commons-logging-1.1.1.jar
javassist-3.17.1-GA.jar
log4j-1.2.17.jar
log4j-api-2.0.2.jar
log4j-core-2.0.2.jar
slf4j-api-1.7.5.jar
slf4j-log4j12-1.7.5.jar

Maven 坐標 (推薦)：


<dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.5.13</version></dependency>
<dependency><groupId>mysql</groupId><artifactId>mysql-connector-java</artifactId><version>8.0.33</version></dependency>
<dependency><groupId>org.slf4j</groupId><artifactId>slf4j-log4j12</artifactId><version>1.7.36</version></dependency>

1.2 數據庫建表


CREATE DATABASE book;
USE book;

CREATE TABLE `user` (
  `id` INT(10) NOT NULL AUTO_INCREMENT,
  `username` VARCHAR(20) NOT NULL,
  `password` VARCHAR(20) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

INSERT INTO `user` VALUES 
(1,'小華','xiaohua'),
(2,'柯南','666666'),
(3,'慕白','123456'),
(4,'小明','xiaoming12');

二、項目結構

src/
├── main/
│   ├── java/
│   │   └── ucas/
│   │       ├── book/
│   │       │   ├── pojo/User.java
│   │       │   └── test/TestUser.java
│   │       └── book/map/
│   │           ├── mybatis.xml
│   │           └── UserMapper.xml
│   └── resources/
│       └── log4j.properties

三、核心配置文件

3.1 log4j.properties (輸出 SQL 日誌)


log4j.rootLogger=DEBUG, CONSOLE
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.logger.java.sql.ResultSet=INFO
log4j.logger.org.apache=INFO
log4j.logger.java.sql.Connection=DEBUG
log4j.logger.java.sql.Statement=DEBUG
log4j.logger.java.sql.PreparedStatement=DEBUG

3.2 實體類 User.java


package ucas.book.pojo;

public class User {
    private int id;
    private String username;
    private String password;
    // Getter/Setter 省略
    @Override public String toString() { return "User{id=" + id + ", username='" + username + "'}"; }
}

3.3 MyBatis 總配置 mybatis.xml

3.4 映射文件 UserMapper.xml

四、測試代碼 TestUser.java


package ucas.book.test;

import ucas.book.pojo.User;
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 TestUser {
    public static void main(String[] args) throws Exception {
        String resource = "ucas/book/map/mybatis.xml";
        Reader reader = Resources.getResourceAsReader(resource);
        
        // 1. 構建 SqlSessionFactory (線程安全，應用級單例)
        SqlSessionFactory factory = new SqlSessionFactoryBuilder().build(reader);
        
        // 2. 開啟會話 (非線程安全，業務級)
        SqlSession session = factory.openSession();
        
        try {
            // 3. 執行查詢 (namespace.id)
            User user = session.selectOne("ucas.book.map.UserMapper.getUserById", 1);
            // 或使用映射器接口 (需定義接口)
            // UserMapper mapper = session.getMapper(UserMapper.class);
            // User user = mapper.getUserById(1);
            
            System.out.println("查詢結果: " + user);
        } finally {
            // 4. 關閉會話 (歸還連接)
            session.close();
        }
    }
}

五、運行結果與日誌分析

DEBUG [main] - Logging initialized using 'class org.apache.ibatis.logging.slf4j.Slf4jImpl' logger.
DEBUG [main] - PooledDataSource forcefully closed/removed all connections.
DEBUG [main] - Opening JDBC Connection
DEBUG [main] - Created connection 1893241234.
DEBUG [main] - Setting autocommit=false on Connection
DEBUG [main] - ==>  Preparing: SELECT * FROM user WHERE id = ?
DEBUG [main] - ==> Parameters: 1(Integer)
DEBUG [main] - <==      Total: 1
DEBUG [main] - Closing JDBC Connection
查詢結果: User{id=1, username='小華'}

關鍵日誌解讀

Preparing：SQL 預編譯，? 為佔位符。
Parameters：參數值及類型，#{id} 防注入。
Total：返回行數。
autocommit=false：JDBC 事務管理器默認關閉自動提交。

六、進階補充：Mapper 接口開發模式 (推薦)

6.1 定義接口 UserMapper.java


package ucas.book.map;

import ucas.book.pojo.User;

public interface UserMapper {
    User getUserById(int id);
}

6.2 映射文件 namespace 指向接口

...

6.3 測試代碼簡化


UserMapper mapper = session.getMapper(UserMapper.class);
User user = mapper.getUserById(1); // 類型安全，IDE 支持重構

七、常見坑點避雷

Mapper XML 未打包：Maven 需配置 <resources> 包含 **/*.xml，否則 BindingException: Invalid bound statement。
數據庫驅動版本不匹配：MySQL 8.0+ 驅動類 com.mysql.cj.jdbc.Driver，URL 需 useSSL=false&serverTimezone=UTC。
resultType 寫全限定名：用 typeAliases 定義別名簡化。
#{ } vs ${ }：默認用 #{ }，只有動態表名/列名用 ${ } 並嚴格白名單校驗。
SqlSession 線程不安全：請求級創建，用完即關，切勿作為字段共享。

結語

MyBatis 入門核心在於 配置文件三件套 (config/mapper/entity) + SqlSession 生命周期管理 + 安全參數綁定。跑通 HelloWorld 後，建議依次掌握：動態 SQL (if/choose/foreach/trim)、結果映射 (resultMap/association/collection)、緩存機制 (一級/二級)、插件攔截器 (分頁/租戶)、Spring 整合 (MapperScannerConfigurer/事務管理)，逐層深入，從「會用」到「懂原理」。