Spring Boot 3.3.X与MyBatis-Plus整合开发实战指南-代码聚汇网

Spring Boot 3.3.X与MyBatis-Plus整合开发实战指南

Pinxian Li·2026-08-26·阅读 27 GEO检测（免费）

Spring Boot 3.3.XMyBatis-PlusJava企业开发

|难度：普通|阅读约 24 分钟

1. 为什么选择Spring Boot 3.3.X与MyBatis-Plus组合

在Java企业级应用开发领域，Spring Boot 3.3.X与MyBatis-Plus的组合已经成为当前最热门的技术选型方案之一。这套技术栈的火爆并非偶然——Spring Boot 3.3.X作为Spring框架的最新稳定版本，在性能优化、原生镜像支持等方面带来了显著提升；而MyBatis-Plus作为MyBatis的增强工具，极大简化了数据库操作代码的编写。

我最近在一个电商后台系统的开发中采用了这套组合，实测下来单表CRUD操作代码量减少了70%以上，开发效率提升明显。特别是在处理复杂分页查询时，MyBatis-Plus的分页插件与Spring Boot 3.3.X的无缝集成，让原本需要手动编写的大量样板代码变得简洁优雅。

这套组合特别适合以下场景：

需要快速开发的企业级应用
对数据库操作有较高要求的项目
希望减少SQL编写但又需要灵活控制SQL的团队
需要与Spring生态其他组件（如Security、Cloud等）集成的系统

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与项目初始化

2.1 开发环境要求

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

JDK 17或更高版本（Spring Boot 3.x强制要求）
Maven 3.6.3+或Gradle 7.x
IDE推荐IntelliJ IDEA或Spring Tools Suite
MySQL 8.0+或其他兼容数据库

注意：Spring Boot 3.x不再支持JDK 8，这是与2.x版本的一个重要区别。我在迁移项目时就曾因为JDK版本问题浪费了半天时间排查启动失败的原因。

2.2 创建Spring Boot项目

使用Spring Initializr创建项目时，需要选择以下依赖：

Spring Web
Lombok（可选但强烈推荐）
MySQL Driver
MyBatis Framework

这里有个容易踩的坑：官方Initializr提供的MyBatis依赖是基础版，我们需要手动添加MyBatis-Plus的依赖。正确的pom.xml配置应该是：

xml复制<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>最新版本</version>
</dependency>

我建议使用MyBatis-Plus与Spring Boot版本匹配的最新稳定版，可以在MyBatis-Plus官网查看版本兼容性矩阵。

3. 核心配置详解

3.1 数据库连接配置

在application.yml中配置数据库连接是第一步，但有几个关键细节需要注意：

yaml复制spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/your_db?useSSL=false&serverTimezone=UTC&characterEncoding=utf8
    username: root
    password: yourpassword
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5

特别提醒：

MySQL 8+必须使用cj驱动
时区(serverTimezone)设置很重要，否则可能遇到时间类型转换问题
字符集(characterEncoding)建议显式指定为utf8或utf8mb4

3.2 MyBatis-Plus配置类

创建一个配置类来启用MyBatis-Plus的特性：

java复制@Configuration
@MapperScan("com.yourpackage.mapper")
public class MybatisPlusConfig {
    
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 分页插件
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        // 乐观锁插件
        interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
        return interceptor;
    }
}

这个配置类做了三件重要的事情：

通过@MapperScan指定Mapper接口的扫描路径
配置分页插件（支持MySQL方言）
启用乐观锁功能（需要实体类有@Version注解）

4. 实体与Mapper开发实践

4.1 实体类注解详解

MyBatis-Plus通过注解极大简化了实体类的定义。以下是一个完整的用户实体类示例：

java复制@Data
@TableName("sys_user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long id;
    
    private String username;
    
    private String password;
    
    @TableField("nick_name")
    private String nickname;
    
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
    
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
    
    @Version
    private Integer version;
    
    @TableLogic
    private Integer deleted;
}

关键注解说明：

@TableName：指定表名，省略时默认使用类名
@TableId：主键注解，IdType.AUTO表示数据库自增
@TableField：字段映射，可指定填充策略（自动填充create/update时间）
@Version：乐观锁版本号字段
@TableLogic：逻辑删除标记字段

4.2 Mapper接口与Service开发

MyBatis-Plus的BaseMapper提供了大量开箱即用的方法：

java复制public interface UserMapper extends BaseMapper<User> {
    // 自定义方法
    List<User> selectByUsername(@Param("username") String username);
}

对应的XML映射文件可以这样写：

xml复制<select id="selectByUsername" resultType="com.yourpackage.entity.User">
    SELECT * FROM sys_user WHERE username = #{username}
</select>

Service层可以继承ServiceImpl获得CRUD能力：

java复制@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
    // 自定义业务方法
    public List<User> findActiveUsers() {
        return lambdaQuery().eq(User::getDeleted, 0).list();
    }
}

这里使用了LambdaQueryWrapper，这是MyBatis-Plus 3.x引入的类型安全查询方式，避免了字段名的硬编码。

5. 高级特性与实战技巧

5.1 分页查询最佳实践

MyBatis-Plus的分页功能非常强大，但使用时需要注意几个要点：

java复制// 分页查询示例
Page<User> page = new Page<>(1, 10); // 当前页，每页数量
Page<User> result = userMapper.selectPage(page, 
    Wrappers.<User>lambdaQuery()
        .like(User::getUsername, "admin")
        .orderByAsc(User::getId)
);

// 获取分页数据
List<User> records = result.getRecords();
long total = result.getTotal();

实际项目中，我通常会封装一个统一的分页查询工具类，处理以下常见需求：

前端分页参数自动转换
排序字段安全处理（防止SQL注入）
空数据集优化处理

5.2 动态表名与租户隔离

在多租户系统中，动态表名是常见需求。MyBatis-Plus提供了动态表名处理器：

java复制public class MyTableNameHandler implements TableNameHandler {
    @Override
    public String dynamicTableName(String sql, String tableName) {
        // 从线程上下文中获取租户ID
        String tenantId = TenantContext.getCurrentTenant();
        return tenantId + "_" + tableName;
    }
}

然后在配置类中添加：

java复制interceptor.addInnerInterceptor(new DynamicTableNameInnerInterceptor(new MyTableNameHandler()));

对于需要临时取消租户隔离的场景（如全局统计），可以使用MyBatis-Plus的注解：

java复制@InterceptorIgnore(tenantLine = "true")
List<User> selectAllTenants();

5.3 字段级加密实现

数据安全越来越受重视，MyBatis-Plus配合Spring Boot可以实现透明的字段加密：

实现TypeHandler处理加密解密：

java复制public class EncryptTypeHandler extends BaseTypeHandler<String> {
    private final Encryptor encryptor = new AESEncryptor();
    
    @Override
    public void setNonNullParameter(...) {
        // 加密后存入数据库
        ps.setString(i, encryptor.encrypt(parameter));
    }
    
    @Override
    public String getNullableResult(...) {
        // 从数据库解密
        return encryptor.decrypt(rs.getString(columnName));
    }
}

在实体类字段上指定TypeHandler：

java复制@TableField(typeHandler = EncryptTypeHandler.class)
private String mobile;

这样在存取mobile字段时会自动加解密，业务代码无需关心具体实现。

6. 常见问题排查与性能优化

6.1 整合过程中的典型问题

SQL注入警告：MyBatis-Plus的LambdaQueryWrapper是类型安全的，但如果你使用字符串形式的Wrapper，需要特别注意：

java复制// 不安全的写法
QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.eq("username", param); // 如果param是用户输入，可能有风险

// 安全的Lambda写法
LambdaQueryWrapper<User> wrapper = Wrappers.lambdaQuery();
wrapper.eq(User::getUsername, param);

分页不生效：检查是否漏掉了配置MybatisPlusInterceptor，或者Page参数没有放在第一个参数位置。
乐观锁冲突：更新失败时检查是否实体类有@Version字段，并且更新前先查询最新版本。

6.2 性能优化建议

批量操作：使用MyBatis-Plus的saveBatch方法比循环单条insert快5-10倍：

java复制userService.saveBatch(userList, 1000); // 每批1000条

SQL打印与监控：开发环境可以开启SQL日志：

yaml复制mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

生产环境建议使用p6spy等工具监控SQL性能。

二级缓存：对于读多写少的场景，可以启用MyBatis二级缓存：

java复制@CacheNamespace
public interface UserMapper extends BaseMapper<User> {
    // ...
}

但要注意缓存一致性问题，更新操作需要清空缓存。

7. 测试与验证策略

7.1 单元测试配置

Spring Boot Test与MyBatis-Plus结合使用时，测试类应该这样配置：

java复制@SpringBootTest
@Transactional
@Rollback
class UserMapperTest {
    @Autowired
    private UserMapper userMapper;
    
    @Test
    void testInsert() {
        User user = new User();
        user.setUsername("test");
        int rows = userMapper.insert(user);
        assertEquals(1, rows);
        assertNotNull(user.getId());
    }
}

关键点：

@Transactional和@Rollback确保测试不会污染数据库
测试CRUD操作时验证返回的影响行数
自增ID应该在插入后自动回填到实体

7.2 集成测试技巧

对于复杂查询，我通常会采用以下测试策略：

使用Testcontainers启动真实MySQL容器
用Flyway或Liquibase初始化测试数据
验证查询结果和分页信息

java复制@Testcontainers
@SpringBootTest
class UserServiceIT {
    @Container
    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0");
    
    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", mysql::getJdbcUrl);
        registry.add("spring.datasource.username", mysql::getUsername);
        registry.add("spring.datasource.password", mysql::getPassword);
    }
    
    @Test
    void testComplexQuery() {
        // 测试复杂业务查询
    }
}

这种测试虽然运行较慢，但能最大程度模拟生产环境。

8. 生产环境部署注意事项

8.1 健康检查与监控

Spring Boot Actuator可以暴露MyBatis-Plus的健康信息：

yaml复制management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  health:
    db:
      enabled: true

访问/actuator/health可以查看数据库连接状态。

8.2 多数据源配置

大型项目往往需要多数据源，MyBatis-Plus对此有良好支持：

配置多个数据源：

java复制@Bean
@ConfigurationProperties("spring.datasource.master")
public DataSource masterDataSource() {
    return DataSourceBuilder.create().build();
}

@Bean
@ConfigurationProperties("spring.datasource.slave")
public DataSource slaveDataSource() {
    return DataSourceBuilder.create().build();
}

使用@DS注解切换数据源：

java复制@Service
@DS("slave") // 默认使用从库
public class UserServiceImpl implements UserService {
    
    @DS("master") // 写操作切到主库
    public void saveUser(User user) {
        // ...
    }
}

8.3 灰度发布策略

当升级MyBatis-Plus或Spring Boot版本时，建议采用以下策略：

先在测试环境验证所有CRUD操作
使用A/B测试逐步切流
监控SQL执行时间和错误率
准备好回滚方案

我在实际项目中就曾遇到过MyBatis-Plus小版本升级导致分页查询行为变化的情况，良好的发布策略可以最小化影响。