1. MyBatis-Plus 项目集成指南
MyBatis-Plus 作为 MyBatis 的增强工具，在 Java 持久层开发中能显著提升效率。最近我在一个后台管理系统项目中完整实践了 MyBatis-Plus 的集成过程，这里将详细记录从依赖配置到实际使用的全流程。不同于简单的配置说明，我会重点分享在实际企业级项目中应用时的关键细节和避坑经验。
2. 项目环境准备
2.1 Maven 依赖管理
在父工程 pom.xml 中采用 BOM 方式管理依赖版本是个好习惯，这能确保所有子模块使用统一的 MyBatis-Plus 版本：
xml复制<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-bom</artifactId>
<version>3.5.15</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
提示：使用 BOM 管理后，子模块引入依赖时无需再指定版本号，这能有效避免版本冲突问题。当前 3.5.15 是较稳定的生产版本。
2.2 子模块依赖配置
根据项目技术栈选择对应的 starter。对于 Spring Boot 3.x 项目：
xml复制<dependencies>
<!-- 核心依赖 -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-spring-boot3-starter</artifactId>
</dependency>
<!-- 分页插件依赖（可选） -->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-jsqlparser</artifactId>
</dependency>
</dependencies>
注意：如果项目使用 Spring Boot 2.x，需要将 starter 改为
mybatis-plus-boot-starter。混用不同版本的 starter 会导致兼容性问题。
3. 核心配置详解
3.1 MyBatis-Plus 配置类
创建配置类统一管理 MyBatis-Plus 的扩展功能。以下是带详细注释的配置示例：
java复制@Configuration
@MapperScan("com.yourpackage.mapper") // 替换为你的Mapper接口所在包
public class MybatisPlusConfig {
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
// 分页插件配置（需要jsqlparser依赖）
PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor();
paginationInterceptor.setDbType(DbType.MYSQL); // 根据实际数据库类型配置
paginationInterceptor.setOverflow(true); // 超出总页数后回到第一页
paginationInterceptor.setMaxLimit(500L); // 单页分页条数限制
interceptor.addInnerInterceptor(paginationInterceptor);
// 可以继续添加其他插件
// interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
return interceptor;
}
}
3.2 多数据源配置技巧
在需要连接多个数据库的场景下，配置方式有所不同：
java复制@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
// 多数据源时不指定具体DbType
PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor();
paginationInterceptor.setOverflow(false); // 多数据源建议关闭overflow
interceptor.addInnerInterceptor(paginationInterceptor);
return interceptor;
}
经验：多数据源项目建议关闭 overflow 特性，不同数据库对超出页数的处理行为可能不一致。
4. 核心组件使用规范
4.1 Mapper 层开发
Mapper 接口需要继承 BaseMapper 并指定实体类：
java复制public interface UserMapper extends BaseMapper<User> {
// 可以继续添加自定义SQL方法
@Select("SELECT * FROM user WHERE age > #{age}")
List<User> selectByAge(@Param("age") Integer age);
}
注意：实体类需要添加 @TableName 注解指定表名（当表名与类名不一致时）：
java复制@TableName("sys_user")
public class User {
@TableId(type = IdType.AUTO)
private Long id;
// 其他字段...
}
4.2 Service 层开发
服务接口继承 IService：
java复制public interface UserService extends IService<User> {
// 自定义业务方法
List<User> getActiveUsers();
}
实现类继承 ServiceImpl：
java复制@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User>
implements UserService {
@Override
public List<User> getActiveUsers() {
// 可以使用baseMapper调用Mapper方法
return baseMapper.selectList(
new LambdaQueryWrapper<User>()
.eq(User::getStatus, 1)
);
}
}
5. 实际应用中的经验技巧
5.1 分页查询最佳实践
java复制// 构造分页参数（第1页，每页10条）
Page<User> page = new Page<>(1, 10);
// 构造查询条件
LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(User::getDepartmentId, 2)
.like(User::getName, "张");
// 执行分页查询
Page<User> result = userService.page(page, wrapper);
// 获取分页数据
List<User> records = result.getRecords();
long total = result.getTotal();
避坑指南：当使用 left join 等复杂SQL时，直接使用page方法可能导致分页不准确。此时建议：
- 在XML中手写count语句
- 或者使用自定义SQL+PageHelper
5.2 批量操作优化
java复制// 批量插入（实测比循环insert快10倍以上）
List<User> userList = new ArrayList<>();
// ...填充数据
boolean success = userService.saveBatch(userList, 1000); // 每批1000条
// 批量更新
boolean updateResult = userService.updateBatchById(userList);
5.3 逻辑删除配置
在 application.yml 中配置：
yaml复制mybatis-plus:
global-config:
db-config:
logic-delete-field: deleted # 逻辑删除字段名
logic-delete-value: 1 # 删除值
logic-not-delete-value: 0 # 未删除值
实体类字段添加注解：
java复制@TableLogic
private Integer deleted;
6. 常见问题排查
6.1 分页插件不生效
可能原因及解决方案：
-
配置顺序问题：确保分页插件是第一个被添加到拦截器链的
java复制// 错误示例：其他插件在前 interceptor.addInnerInterceptor(new BlockAttackInnerInterceptor()); interceptor.addInnerInterceptor(new PaginationInnerInterceptor()); // 不生效 // 正确顺序 interceptor.addInnerInterceptor(new PaginationInnerInterceptor()); // 先添加 interceptor.addInnerInterceptor(new BlockAttackInnerInterceptor()); -
依赖缺失：确认已引入 jsqlparser 依赖
-
SQL方言问题：复杂SQL可能需要手动指定count语句
6.2 字段映射异常
典型表现：
- 查询结果字段为null
- 插入时字段值未正确设置
解决方案：
- 检查实体类字段名与数据库列名是否匹配
- 使用 @TableField 注解显式指定映射：
java复制@TableField("user_name") private String name; - 开启下划线转驼峰配置：
yaml复制mybatis-plus: configuration: map-underscore-to-camel-case: true
6.3 事务不生效问题
确保：
- 主类添加 @EnableTransactionManagement
- Service方法添加 @Transactional
- 避免同类内方法调用（AOP代理失效）
7. 性能优化建议
-
SQL打印配置：
yaml复制mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl生产环境建议使用日志框架输出：
yaml复制logging: level: com.yourpackage.mapper: debug -
查询优化：
- 使用 selectMaps 避免不必要的字段查询
java复制List<Map<String, Object>> maps = userMapper.selectMaps( new QueryWrapper<User>().select("id", "name") );- 使用 LambdaQueryWrapper 避免硬编码字段名
-
二级缓存：在配置类添加：
java复制@Bean public MybatisPlusSqlInjector mybatisPlusSqlInjector() { return new MybatisPlusSqlInjector(); }然后在Mapper接口添加注解：
java复制@CacheNamespace public interface UserMapper extends BaseMapper<User> {}
在实际项目开发中，合理使用 MyBatis-Plus 的这些特性可以显著提升开发效率。特别是在需要快速迭代的业务系统中，它能减少约 60% 的常规CRUD代码量。不过也要注意避免过度依赖自动生成SQL，对于复杂查询还是推荐使用XML或注解方式明确SQL逻辑。