您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

MyBatis 入門實戰：Maven 項目搭建、核心配置與 HelloWorld 完整流程

編輯：Java 相關知識

項目初始化

# 目錄結構
mybatis-helloworld/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/
    │   │   └── com/example/
    │   │       ├── entity/User.java
    │   │       ├── mapper/UserMapper.java
    │   │       └── MyBatisTest.java
    │   └── resources/
    │       ├── mybatis-config.xml
    │       ├── mapper/UserMapper.xml
    │       └── jdbc.properties
    └── test/
        └── java/

1. Maven 依賴 `pom.xml`

<project xmlns="https://maven.apache.org/POM/4.0.0"
         xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>mybatis-helloworld</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <mybatis.version>3.5.16</mybatis.version>
        <mysql.version>8.0.33</mysql.version>
    </properties>
    
    <dependencies>
        <!-- MyBatis 核心 -->
        <dependency>
            <groupId>org.mybatis</groupId>
            <artifactId>mybatis</artifactId>
            <version>${mybatis.version}</version>
        </dependency>
        <!-- MySQL 驅動 -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>${mysql.version}</version>
        </dependency>
        <!-- 單元測試 -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.10.2</version>
            <scope>test</scope>
        </dependency>
        <!-- 日誌 (SLF4J + Logback) -->
        <dependency>
            <groupId>ch.qos.logback</groupId>
            <artifactId>logback-classic</artifactId>
            <version>1.5.6</version>
        </dependency>
    </dependencies>
    
    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <includes><include>**/*.xml</include></includes>
            </resource>
        </resources>
    </build>
</project>

2. 數據庫準備

CREATE DATABASE mybatis_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE mybatis_demo;

CREATE TABLE t_user (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(50) NOT NULL UNIQUE,
    password VARCHAR(100) NOT NULL,
    email VARCHAR(100),
    age INT,
    address VARCHAR(200),
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

INSERT INTO t_user(username, password, email, age, address) 
VALUES ('zhangsan', '123456', 'zhangsan@example.com', 25, '北京市朝陽區');
INSERT INTO t_user(username, password, email, age, address) 
VALUES ('lisi', 'abcdef', 'lisi@example.com', 30, '上海市浦東新區');

3. 實體類 `User.java`

package com.example.entity;

import java.time.LocalDateTime;

public class User {
    private Long id;
    private String username;
    private String password;
    private String email;
    private Integer age;
    private String address;
    private LocalDateTime createTime;
    
    // 無參構造器、全參構造器、Getter/Setter、toString 省略...
}

4. 映射器接口 `UserMapper.java`

package com.example.mapper;

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

public interface UserMapper {
    User selectById(Long id);
    List selectAll();
    int insert(User user);
    int update(User user);
    int deleteById(Long id);
}

5. 映射器 XML `mapper/UserMapper.xml`

<?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.example.mapper.UserMapper">
    <resultMap id="userMap" type="com.example.entity.User">
        <id property="id" column="id"/>
        <result property="username" column="username"/>
        <result property="password" column="password"/>
        <result property="email" column="email"/>
        <result property="age" column="age"/>
        <result property="address" column="address"/>
        <result property="createTime" column="create_time"/>
    </resultMap>
    
    <sql id="columns">
        id, username, password, email, age, address, create_time
    </sql>
    
    <select id="selectById" resultMap="userMap">
        SELECT <include refid="columns"/> FROM t_user WHERE id = #{id}
    </select>
    
    <select id="selectAll" resultMap="userMap">
        SELECT <include refid="columns"/> FROM t_user
    </select>
    
    <insert id="insert" parameterType="User" useGeneratedKeys="true" keyProperty="id">
        INSERT INTO t_user(username, password, email, age, address) 
        VALUES(#{username}, #{password}, #{email}, #{age}, #{address})
    </insert>
    
    <update id="update" parameterType="User">
        UPDATE t_user SET 
        username=#{username}, password=#{password}, email=#{email}, 
        age=#{age}, address=#{address} 
        WHERE id=#{id}
    </update>
    
    <delete id="deleteById">
        DELETE FROM t_user WHERE id = #{id}
    </delete>
</mapper>

6. MyBatis 核心配置 `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>
    <properties resource="jdbc.properties"/>
    
    <settings>
        <setting name="cacheEnabled" value="true"/>
        <setting name="lazyLoadingEnabled" value="true"/>
        <setting name="mapUnderscoreToCamelCase" value="true"/>  -- 自動駝峰映射
        <setting name="defaultExecutorType" value="SIMPLE"/>
    </settings>
    
    <typeAliases>
        <package name="com.example.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>
    
    <mappers>
        <package name="com.example.mapper"/>
    </mappers>
</configuration>

7. JDBC 屬性 `jdbc.properties`

jdbc.driver=com.mysql.cj.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/mybatis_demo?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8
jdbc.username=root
jdbc.password=your_password

8. 測試類 `MyBatisTest.java`

package com.example;

import com.example.entity.User;
import com.example.mapper.UserMapper;
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 org.junit.jupiter.api.*;

import java.io.IOException;
import java.io.Reader;
import java.util.List;

@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
class MyBatisTest {
    private static SqlSessionFactory sqlSessionFactory;
    
    @BeforeAll
    static void initFactory() throws IOException {
        try (Reader reader = Resources.getResourceAsReader("mybatis-config.xml")) {
            sqlSessionFactory = new SqlSessionFactoryBuilder().build(reader);
        }
    }
    
    @Test
    @Order(1)
    void testSelectById() {
        try (SqlSession session = sqlSessionFactory.openSession()) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            User user = mapper.selectById(1L);
            Assertions.assertNotNull(user);
            Assertions.assertEquals("zhangsan", user.getUsername());
            System.out.println("查詢結果: " + user);
        }
    }
    
    @Test
    @Order(2)
    void testSelectAll() {
        try (SqlSession session = sqlSessionFactory.openSession()) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            List users = mapper.selectAll();
            Assertions.assertEquals(2, users.size());
            users.forEach(System.out::println);
        }
    }
    
    @Test
    @Order(3)
    void testInsert() {
        try (SqlSession session = sqlSessionFactory.openSession(true)) { // autoCommit
            UserMapper mapper = session.getMapper(UserMapper.class);
            User user = new User();
            user.setUsername("wangwu");
            user.setPassword("111111");
            user.setEmail("wangwu@example.com");
            user.setAge(28);
            user.setAddress("廣州市天河區");
            
            int rows = mapper.insert(user);
            Assertions.assertEquals(1, rows);
            Assertions.assertNotNull(user.getId()); // 回填自增 ID
            System.out.println("插入成功，生成 ID: " + user.getId());
        }
    }
    
    @Test
    @Order(4)
    void testUpdate() {
        try (SqlSession session = sqlSessionFactory.openSession(true)) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            User user = mapper.selectById(1L);
            user.setAge(26);
            user.setAddress("北京市海淀區");
            
            int rows = mapper.update(user);
            Assertions.assertEquals(1, rows);
            System.out.println("更新成功: " + user);
        }
    }
    
    @Test
    @Order(5)
    void testDelete() {
        try (SqlSession session = sqlSessionFactory.openSession(true)) {
            UserMapper mapper = session.getMapper(UserMapper.class);
            int rows = mapper.deleteById(2L);
            Assertions.assertEquals(1, rows);
            System.out.println("刪除成功，影響行數: " + rows);
        }
    }
}

9. 運行驗證

# 編譯測試
mvn test

# 預期輸出
查詢結果: User(id=1, username=zhangsan, ...)
User(id=1, username=zhangsan, ...)
User(id=2, username=lisi, ...)
插入成功，生成 ID: 3
更新成功: User(id=1, username=zhangsan, age=26, ...)
刪除成功，影響行數: 1

常見配置錯誤與修復

錯誤現象	原因	修復
`The content of element type "configuration" must match...`	XML 節點順序不符合 DTD 定義	按順序：properties → settings → typeAliases → typeHandlers → objectFactory → plugins → environments → mappers
`BindingException: Invalid bound statement`	namespace/id 拼寫錯誤	namespace = 接口全限定名，id = 方法名，大小寫敏感
字段為 null (如 email、age)	數據庫列名與屬性名不匹配 (下劃線 vs 駝峰)	開啟 `mapUnderscoreToCamelCase=true` 或用 resultMap 顯式映射
插入後 ID 為 0/null	缺 `useGeneratedKeys="true" keyProperty="id"`	在 <insert> 標籤添加自增主鍵回填配置
XML 文件未打包進 JAR	Maven 預設不包含 src/main/resources 下的 XML	pom.xml 添加 <resources> 配置包含 *.xml

進階提示

分頁插件：引入 com.github.pagehelper:pagehelper，一行代碼實現物理分頁
通用 Mapper：tk.mybatis:mapper-spring-boot-starter 封裝基礎 CRUD
Spring Boot 整合：org.mybatis.spring.boot:mybatis-spring-boot-starter，零配置啟動
代碼生成：org.mybatis.generator:mybatis-generator-maven-plugin 逆向生成實體/Mapper/XML

總結

MyBatis 入門核心路徑：POM 依賴 → 數據庫表 → 實體類 → Mapper 接口 → XML 映射 → 核心配置 → SqlSessionFactory → 測試驗證。掌握「resultMap 解決列名不匹配、useGeneratedKeys 回填主鍵、mapUnderscoreToCamelCase 自動駝峰、<sql> 復用片段、節點順序符合 DTD」五大關鍵點，即可快速構建穩健的持久層。建議新項目直接採用 Spring Boot + MyBatis-Plus/PageHelper 獲得開箱即用體驗。