快速上手

相关源文件

本页面内容基于以下源文件生成：

• spring-boot-starter/mybatis-plus-boot-starter/build.gradle
• spring-boot-starter/mybatis-plus-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
• spring-boot-starter/mybatis-plus-boot-starter/src/test/resources/application.yml
• mybatis-plus/src/test/java/com/baomidou/mybatisplus/test/BaseDbTest.java
• mybatis-plus/src/test/java/com/baomidou/mybatisplus/test/PageTest.java
• mybatis-plus/src/test/java/com/baomidou/mybatisplus/test/OgnlTest.java
• mybatis-plus-core/src/test/java/com/baomidou/mybatisplus/test/User.java
• mybatis-plus-core/src/test/java/com/baomidou/mybatisplus/test/Role.java
• mybatis-plus/src/test/java/com/baomidou/mybatisplus/test/DbTypeTest.java
• mybatis-plus/src/test/java/com/baomidou/mybatisplus/test/MybatisTest.java

MyBatis-Plus 是 MyBatis 的增强工具，在 MyBatis 的基础上只做增强不做改变，为简化开发、提高效率而生。本文档将引导开发者快速完成环境搭建、基础配置和功能验证。

环境要求

MyBatis-Plus 3.0 版本基于 Spring Boot 构建，以下是运行和测试所需的核心环境：

可选依赖（用于模板引擎支持）：

• MyBatis-Thymeleaf（build.gradle:12）
• MyBatis-Velocity（build.gradle:13）
• MyBatis-Freemarker（build.gradle:14）

Spring Boot 集成

依赖配置

在 Gradle 项目中引入 MyBatis-Plus Spring Boot Starter，该 Starter 会自动传递核心依赖：

groovy
1dependencies {
2    // 核心依赖（包含 mybatis-plus、mybatis-spring、自动配置模块）
3    implementation 'com.baomidou:mybatis-plus-boot-starter:3.0.0'
4    
5    // 数据库驱动（以 H2 为例）
6    runtimeOnly 'com.h2database:h2'
7    
8    // Spring Boot JDBC 支持（Starter 已自动传递）
9    // implementation 'org.springframework.boot:spring-boot-starter-jdbc'
10}

完整的 Starter 依赖结构参见 build.gradle:1-21，其中包含：

• mybatis-plus 核心模块
• mybatis-spring Spring 集成
• mybatis-plus-spring-boot-autoconfigure 自动配置
• spring-boot-starter-jdbc JDBC 支持

自动配置机制

Spring Boot Starter 通过 AutoConfiguration.imports 文件注册自动配置类，无需手动配置 SqlSessionFactory：

properties
1# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
2com.baomidou.mybatisplus.autoconfigure.MybatisPlusInnerInterceptorAutoConfiguration
3com.baomidou.mybatisplus.autoconfigure.IdentifierGeneratorAutoConfiguration
4com.baomidou.mybatisplus.autoconfigure.MybatisPlusLanguageDriverAutoConfiguration
5com.baomidou.mybatisplus.autoconfigure.MybatisPlusAutoConfiguration
6com.baomidou.mybatisplus.autoconfigure.DdlAutoConfiguration

完整配置列表参见 AutoConfiguration.imports:1-5。这些配置类会自动完成：

• MyBatis SqlSessionFactory 初始化
• 分页插件等拦截器注册
• 主键生成器配置
• 多语言驱动支持（Thymeleaf/Velocity/Freemarker）

基础配置

数据源配置

在 application.yml 中配置数据源，以下为 H2 内存数据库的标准配置示例：

yaml
1spring:
2  datasource:
3    driver-class-name: org.h2.Driver
4    url: jdbc:h2:mem:test;MODE=mysql;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
5    username: sa

此配置来自 application.yml:1-5，关键参数说明：

• MODE=mysql：H2 使用 MySQL 兼容模式
• DB_CLOSE_DELAY=-1：保持内存数据库在连接关闭后不销毁
• DB_CLOSE_ON_EXIT=FALSE：JVM 退出时不自动关闭数据库

原生 Java 配置（非 Spring Boot）

对于非 Spring Boot 环境，可参考测试基类中的数据源初始化方式：

java
1private DataSource dataSource() {
2    SimpleDriverDataSource dataSource = new SimpleDriverDataSource();
3    dataSource.setDriver(new Driver());
4    dataSource.setUrl("jdbc:h2:mem:test;MODE=mysql;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE");
5    dataSource.setUsername("sa");
6    dataSource.setPassword("");
7    return dataSource;
8}

完整实现参见 BaseDbTest.java:92-99。

实体类定义

基础实体类

使用 MyBatis-Plus 注解定义实体类与数据库表的映射关系：

java
1@TableName("sys_user")
2@Data
3public class User {
4    private Integer id;
5    
6    @TableField("username")
7    private String name;
8    
9    private Integer roleId;
10}

此示例来自 User.java:1-17，核心注解说明：

• @TableName("sys_user")：指定对应的数据库表名
• @TableField("username")：当字段名与列名不一致时进行映射

多表关联实体

对于关联表场景，实体类定义方式类似：

java
1@TableName("sys_role")
2@Data
3public class Role {
4    private Integer id;
5    
6    @TableField("role_name")
7    private String name;
8    
9    private Integer userId;
10}

完整代码参见 Role.java:1-13。

最短可运行路径

推荐路径：Spring Boot 测试

最快验证 MyBatis-Plus 功能的方式是运行 Spring Boot 集成测试：

bash
1# 1. 克隆仓库
2git clone https://github.com/baomidou/mybatis-plus.git
3cd mybatis-plus
4
5# 2. 切换到 3.0 分支
6git checkout 3.0
7
8# 3. 运行 Spring Boot Starter 测试
9./gradlew :spring-boot-starter:mybatis-plus-boot-starter:test

预期输出（需要确认）：

> Task :spring-boot-starter:mybatis-plus-boot-starter:test
BUILD SUCCESSFUL
Test Summary: X tests passed

原生测试路径

不依赖 Spring Boot 容器，直接使用 MyBatis 原生 API 进行测试：

bash
1# 运行核心模块测试
2./gradlew :mybatis-plus:test --tests "com.baomidou.mybatisplus.test.*"

测试基类 BaseDbTest 封装了完整的初始化流程（BaseDbTest.java:1-50），包括：

1. 创建 H2 内存数据源
2. 执行建表 SQL（tableSql()）
3. 初始化测试数据（tableDataSql()）
4. 构建 SqlSessionFactory
5. 注册 Mapper 接口

运行验证

分页功能验证

分页是 MyBatis-Plus 的核心特性之一，可通过 PageTest 验证：

bash
1./gradlew :mybatis-plus:test --tests "com.baomidou.mybatisplus.test.PageTest"

测试代码展示了分页对象的创建与属性访问（PageTest.java:1-80）：

java
1// 创建分页对象：第 2 页，每页 10 条，总记录 100 条
2Page<?> page = new Page<>(2, 10, 100, false);
3
4// 设置排序
5page.setOrders(Collections.singletonList(OrderItem.asc("test")));
6
7// 验证属性
8Assertions.assertEquals(2, page.getCurrent());   // 当前页
9Assertions.assertEquals(100, page.getTotal());   // 总记录数
10Assertions.assertEquals(10, page.getSize());     // 每页大小

JSON 序列化验证

分页对象支持多种 JSON 框架的序列化/反序列化（PageTest.java:127-149）：

java
1private <T extends IPage<?>> List&lt;T&gt; toConvert(T source, Class&lt;T&gt; tClass) {
2    return List.of(
3        objectMapper.readValue(objectMapper.writeValueAsString(source), tClass),  // Jackson
4        gson.fromJson(gson.toJson(source), tClass),                                // Gson
5        JSON.parseObject(JSON.toJSONString(source), tClass),                       // Fastjson
6        JSONB.parseObject(JSONB.toBytes(source), tClass, JSONReader.Feature.FieldBased)  // Fastjson2
7    );
8}

OGNL 表达式验证

MyBatis 动态 SQL 中使用的 OGNL 表达式可通过 OgnlTest 验证（OgnlTest.java:1-50）：

java
1// Map 属性访问
2Map<String, Object> propertiesMap = new HashMap<>();
3propertiesMap.put("color", "yellow");
4Assertions.assertEquals("yellow", OgnlCache.getValue("color", propertiesMap));
5
6// 嵌套属性访问
7Bean bean = new Bean();
8bean.setProperties(propertiesMap);
9Assertions.assertEquals("yellow", OgnlCache.getValue("properties.color", bean));

常见问题与排错

问题 1：自动配置未生效

症状：启动时报错 SqlSessionFactory 未找到或 Mapper 注入失败。

排查步骤：

1. 确认依赖中包含 mybatis-plus-boot-starter
2. 检查 @MapperScan 注解是否配置：

   java
   1@MapperScan("com.example.mapper")
   2@SpringBootApplication
   3public class Application { ... }

3. 验证 AutoConfiguration.imports 文件是否在 classpath 中（AutoConfiguration.imports:1-5）

问题 2：H2 数据库连接失败

症状：测试时报 Table not found 或连接异常。

解决方案： 确保 H2 URL 包含 DB_CLOSE_DELAY=-1 参数（BaseDbTest.java:95）：

yaml
1url: jdbc:h2:mem:test;MODE=mysql;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE

问题 3：分页总数不正确

症状：Page.getTotal() 返回 0 或与预期不符。

排查方向：

1. 确认分页插件已注册（通过 MybatisPlusInnerInterceptorAutoConfiguration 自动配置）
2. 检查是否设置了 searchCount(false)（PageTest.java:87）
3. 验证 SQL 是否正确执行 COUNT 查询

问题 4：实体类字段映射失败

症状：查询结果中部分字段为 null。

解决方案： 使用 @TableField 注解显式指定列名（User.java:13-14）：

java
1@TableField("username")
2private String name;  // Java 字段名与数据库列名不同

下一步建议

完成快速上手后，建议按以下路径深入学习：

1. 核心功能：了解 CRUD 接口、条件构造器（Wrapper）的使用方法
2. 插件机制：配置分页插件、乐观锁插件、SQL 性能分析插件
3. 代码生成：使用 MyBatis-Plus Generator 自动生成实体、Mapper、Service 代码
4. 多租户架构：通过 TenantLineInnerInterceptor 实现多租户数据隔离
5. 动态表名：使用 DynamicTableNameInnerInterceptor 处理分表场景

详细配置选项和高级用法请参考项目官方文档或源码中的测试用例，测试基类 BaseDbTest（BaseDbTest.java:1-162）提供了完整的初始化模式参考。