环境配置

本章节将介绍如何搭建 MyBatis 开发环境，包括 Maven 依赖配置、数据库准备和第一个 MyBatis 程序。

前置要求

在开始之前，请确保你的开发环境满足以下要求：

工具	版本要求	说明
JDK	8+	MyBatis 3.5+ 需要 Java 8 及以上
Maven	3.6+	项目构建和依赖管理
MySQL	5.7+ / 8.0+	本教程使用 MySQL 作为示例数据库
IDE	-	推荐 IntelliJ IDEA

Maven 依赖配置

基础依赖

在 pom.xml 中添加以下依赖：

<dependencies>
    <!-- MyBatis 核心依赖 -->
    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.5.15</version>
    </dependency>
    
    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <version>8.3.0</version>
    </dependency>
    
    <!-- Lombok（可选，简化代码） -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.30</version>
        <scope>provided</scope>
    </dependency>
    
    <!-- 单元测试 -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>

构建配置

为了确保 XML 映射文件能正确打包，需要配置资源过滤：

<build>
    <resources>
        <resource>
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.xml</include>
                <include>**/*.properties</include>
            </includes>
        </resource>
        <resource>
            <directory>src/main/resources</directory>
        </resource>
    </resources>
</build>

数据库准备

创建数据库和表

-- 创建数据库
CREATE DATABASE IF NOT EXISTS mybatis_demo 
    DEFAULT CHARACTER SET utf8mb4 
    DEFAULT COLLATE utf8mb4_unicode_ci;

USE mybatis_demo;

-- 创建用户表
CREATE TABLE `user` (
    `id` BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
    `username` VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名',
    `password` VARCHAR(100) NOT NULL COMMENT '密码',
    `email` VARCHAR(100) COMMENT '邮箱',
    `phone` VARCHAR(20) COMMENT '手机号',
    `status` TINYINT DEFAULT 1 COMMENT '状态：0-禁用，1-启用',
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

-- 插入测试数据
INSERT INTO `user` (`username`, `password`, `email`, `phone`) VALUES
    ('zhangsan', '123456', '[email protected]', '13800138001'),
    ('lisi', '123456', '[email protected]', '13800138002'),
    ('wangwu', '123456', '[email protected]', '13800138003');

-- 创建订单表（用于关联查询示例）
CREATE TABLE `orders` (
    `id` BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '订单ID',
    `user_id` BIGINT NOT NULL COMMENT '用户ID',
    `order_no` VARCHAR(50) NOT NULL UNIQUE COMMENT '订单号',
    `amount` DECIMAL(10, 2) NOT NULL COMMENT '订单金额',
    `status` TINYINT DEFAULT 0 COMMENT '状态：0-待支付，1-已支付，2-已发货，3-已完成',
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单表';

-- 插入订单测试数据
INSERT INTO `orders` (`user_id`, `order_no`, `amount`, `status`) VALUES
    (1, 'ORD20240101001', 299.00, 1),
    (1, 'ORD20240101002', 599.00, 2),
    (2, 'ORD20240101003', 199.00, 0);

项目结构

创建标准的 Maven 项目结构：

mybatis-demo/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/mybatis/
│   │   │       ├── entity/          # 实体类
│   │   │       │   └── User.java
│   │   │       ├── mapper/          # Mapper 接口
│   │   │       │   └── UserMapper.java
│   │   │       └── util/            # 工具类
│   │   │           └── SqlSessionUtil.java
│   │   └── resources/
│   │       ├── com/example/mybatis/mapper/  # XML 映射文件
│   │       │   └── UserMapper.xml
│   │       └── mybatis-config.xml           # MyBatis 配置文件
│   └── test/
│       └── java/
│           └── com/example/mybatis/
│               └── UserMapperTest.java
└── pom.xml

核心配置文件

mybatis-config.xml

在 src/main/resources 目录下创建 MyBatis 核心配置文件：

<?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>
    <!-- 环境配置 -->
    <environments default="development">
        <environment id="development">
            <!-- 事务管理器 -->
            <transactionManager type="JDBC"/>
            <!-- 数据源配置 -->
            <dataSource type="POOLED">
                <property name="driver" value="com.mysql.cj.jdbc.Driver"/>
                <property name="url" value="jdbc:mysql://localhost:3306/mybatis_demo?useSSL=false&amp;serverTimezone=Asia/Shanghai&amp;characterEncoding=utf8"/>
                <property name="username" value="root"/>
                <property name="password" value="your_password"/>
            </dataSource>
        </environment>
    </environments>
    
    <!-- 映射器配置 -->
    <mappers>
        <mapper resource="com/example/mybatis/mapper/UserMapper.xml"/>
    </mappers>
</configuration>

配置文件说明

元素	说明
environments	环境配置，可以配置多个环境（开发、测试、生产）
transactionManager	事务管理器，JDBC 表示使用 JDBC 的事务管理
dataSource	数据源配置，POOLED 表示使用连接池
mappers	映射器配置，指定 SQL 映射文件的位置

实体类

创建与数据库表对应的实体类：

package com.example.mybatis.entity;

import lombok.Data;
import java.time.LocalDateTime;

@Data
public class User {
    private Long id;
    private String username;
    private String password;
    private String email;
    private String phone;
    private Integer status;
    private LocalDateTime createTime;
    private LocalDateTime updateTime;
}

如果不使用 Lombok，需要手动添加 getter/setter 和构造方法：

package com.example.mybatis.entity;

import java.time.LocalDateTime;

public class User {
    private Long id;
    private String username;
    private String password;
    private String email;
    private String phone;
    private Integer status;
    private LocalDateTime createTime;
    private LocalDateTime updateTime;

    // 无参构造器
    public User() {}

    // 全参构造器
    public User(Long id, String username, String password, String email, 
                String phone, Integer status, LocalDateTime createTime, LocalDateTime updateTime) {
        this.id = id;
        this.username = username;
        this.password = password;
        this.email = email;
        this.phone = phone;
        this.status = status;
        this.createTime = createTime;
        this.updateTime = updateTime;
    }

    // Getter 和 Setter 方法
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    // ... 其他 getter/setter 省略
}

SqlSession 工具类

创建一个工具类来获取 SqlSession：

package com.example.mybatis.util;

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.IOException;
import java.io.InputStream;

public class SqlSessionUtil {
    
    private static final SqlSessionFactory sqlSessionFactory;
    
    static {
        try {
            // 加载配置文件
            InputStream inputStream = Resources.getResourceAsStream("mybatis-config.xml");
            // 创建 SqlSessionFactory
            sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);
        } catch (IOException e) {
            throw new RuntimeException("MyBatis 配置文件加载失败", e);
        }
    }
    
    /**
     * 获取 SqlSession
     */
    public static SqlSession getSqlSession() {
        return sqlSessionFactory.openSession();
    }
    
    /**
     * 获取 SqlSession（自动提交）
     */
    public static SqlSession getSqlSession(boolean autoCommit) {
        return sqlSessionFactory.openSession(autoCommit);
    }
}

Mapper 接口

创建 Mapper 接口定义数据访问方法：

package com.example.mybatis.mapper;

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

public interface UserMapper {
    
    /**
     * 根据ID查询用户
     */
    User selectById(Long id);
    
    /**
     * 查询所有用户
     */
    List<User> selectAll();
    
    /**
     * 根据用户名查询用户
     */
    User selectByUsername(String username);
    
    /**
     * 插入用户
     */
    int insert(User user);
    
    /**
     * 更新用户
     */
    int update(User user);
    
    /**
     * 删除用户
     */
    int deleteById(Long id);
}

XML 映射文件

创建对应的 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.mybatis.mapper.UserMapper">
    
    <!-- 结果映射 -->
    <resultMap id="BaseResultMap" type="com.example.mybatis.entity.User">
        <id column="id" property="id"/>
        <result column="username" property="username"/>
        <result column="password" property="password"/>
        <result column="email" property="email"/>
        <result column="phone" property="phone"/>
        <result column="status" property="status"/>
        <result column="create_time" property="createTime"/>
        <result column="update_time" property="updateTime"/>
    </resultMap>
    
    <!-- 基础字段 -->
    <sql id="Base_Column_List">
        id, username, password, email, phone, status, create_time, update_time
    </sql>
    
    <!-- 根据ID查询 -->
    <select id="selectById" resultMap="BaseResultMap">
        SELECT <include refid="Base_Column_List"/>
        FROM user
        WHERE id = #{id}
    </select>
    
    <!-- 查询所有 -->
    <select id="selectAll" resultMap="BaseResultMap">
        SELECT <include refid="Base_Column_List"/>
        FROM user
    </select>
    
    <!-- 根据用户名查询 -->
    <select id="selectByUsername" resultMap="BaseResultMap">
        SELECT <include refid="Base_Column_List"/>
        FROM user
        WHERE username = #{username}
    </select>
    
    <!-- 插入用户 -->
    <insert id="insert" parameterType="com.example.mybatis.entity.User" 
            useGeneratedKeys="true" keyProperty="id">
        INSERT INTO user (username, password, email, phone, status)
        VALUES (#{username}, #{password}, #{email}, #{phone}, #{status})
    </insert>
    
    <!-- 更新用户 -->
    <update id="update" parameterType="com.example.mybatis.entity.User">
        UPDATE user
        SET username = #{username},
            email = #{email},
            phone = #{phone},
            status = #{status}
        WHERE id = #{id}
    </update>
    
    <!-- 删除用户 -->
    <delete id="deleteById">
        DELETE FROM user WHERE id = #{id}
    </delete>
</mapper>

第一个 MyBatis 程序

测试类

编写测试类验证 MyBatis 是否正常工作：

package com.example.mybatis;

import com.example.mybatis.entity.User;
import com.example.mybatis.mapper.UserMapper;
import com.example.mybatis.util.SqlSessionUtil;
import org.apache.ibatis.session.SqlSession;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import java.util.List;

import static org.junit.jupiter.api.Assertions.*;

class UserMapperTest {
    
    private SqlSession sqlSession;
    private UserMapper userMapper;
    
    @BeforeEach
    void setUp() {
        sqlSession = SqlSessionUtil.getSqlSession();
        userMapper = sqlSession.getMapper(UserMapper.class);
    }
    
    @AfterEach
    void tearDown() {
        if (sqlSession != null) {
            sqlSession.close();
        }
    }
    
    @Test
    void testSelectById() {
        User user = userMapper.selectById(1L);
        assertNotNull(user);
        assertEquals("zhangsan", user.getUsername());
        System.out.println("查询结果: " + user);
    }
    
    @Test
    void testSelectAll() {
        List<User> users = userMapper.selectAll();
        assertNotNull(users);
        assertTrue(users.size() > 0);
        users.forEach(System.out::println);
    }
    
    @Test
    void testInsert() {
        User user = new User();
        user.setUsername("testuser");
        user.setPassword("123456");
        user.setEmail("[email protected]");
        user.setPhone("13900139000");
        user.setStatus(1);
        
        int result = userMapper.insert(user);
        assertEquals(1, result);
        assertNotNull(user.getId()); // 主键回填
        System.out.println("插入成功，ID: " + user.getId());
        
        // 回滚测试数据
        sqlSession.rollback();
    }
    
    @Test
    void testUpdate() {
        User user = userMapper.selectById(1L);
        user.setEmail("[email protected]");
        
        int result = userMapper.update(user);
        assertEquals(1, result);
        
        // 验证更新
        User updated = userMapper.selectById(1L);
        assertEquals("[email protected]", updated.getEmail());
        
        sqlSession.rollback();
    }
    
    @Test
    void testDelete() {
        // 先插入一条测试数据
        User user = new User();
        user.setUsername("todelete");
        user.setPassword("123456");
        userMapper.insert(user);
        sqlSession.commit();
        
        // 删除
        int result = userMapper.deleteById(user.getId());
        assertEquals(1, result);
        
        // 验证删除
        User deleted = userMapper.selectById(user.getId());
        assertNull(deleted);
    }
}

运行测试

在 IDE 中运行测试类，或者在命令行执行：

mvn test -Dtest=UserMapperTest

常见问题

1. 找不到映射文件

问题：运行时报错 BindingException: Invalid bound statement

解决方案：

• 确保 XML 文件路径与 Mapper 接口包路径一致
• 检查 pom.xml 中的资源配置是否正确
• 确保 XML 文件的 namespace 与接口全限定名一致

2. 连接数据库失败

问题：Communications link failure

解决方案：

• 检查 MySQL 服务是否启动
• 确认数据库连接信息是否正确
• 检查防火墙设置

3. 时区问题

问题：The server time zone value 'xxx' is unrecognized

解决方案：在连接 URL 中添加时区参数：

<property name="url" value="jdbc:mysql://localhost:3306/mybatis_demo?serverTimezone=Asia/Shanghai"/>

4. 字符编码问题

问题：中文乱码

解决方案：在连接 URL 中添加编码参数：

<property name="url" value="jdbc:mysql://localhost:3306/mybatis_demo?characterEncoding=utf8"/>

使用 properties 文件管理配置

为了更好地管理数据库配置，可以使用 properties 文件：

db.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

修改 mybatis-config.xml

<configuration>
    <!-- 引入属性文件 -->
    <properties resource="db.properties"/>
    
    <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>
        <mapper resource="com/example/mybatis/mapper/UserMapper.xml"/>
    </mappers>
</configuration>

小结

本章完成了 MyBatis 开发环境的搭建：

• 配置了 Maven 依赖
• 创建了数据库和测试表
• 编写了核心配置文件
• 创建了实体类、Mapper 接口和 XML 映射文件
• 完成了第一个 MyBatis 程序

下一章将详细介绍 MyBatis 的核心配置。