告别繁琐SQL！Spring Boot 3.2 + MybatisPlus 3.5.x 配置与常用注解避坑指南

Spring Boot 3.2 + MyBatis-Plus 3.5.x 实战避坑手册：从配置陷阱到注解玄学

当你在深夜调试MyBatis-Plus时，是否经历过这样的绝望瞬间——明明按照教程一步步操作，启动时却报出Invalid bound statement？或是发现@TableField注解像被施了隐身咒般毫无反应？本文将带你直击这些"灵异现象"背后的真相，用外科手术式精准拆解配置与注解的每个技术细节。

1. 那些年我们踩过的配置坑

1.1 配置文件：YAML的温柔陷阱

在Spring Boot 3.2中，application.yml的缩进就像Python的缩进一样致命。来看个典型错误示例：

mybatis-plus: mapper-locations: classpath*:/mapper/**/*.xml type-aliases-package: com.example.entity # 这里缩进错误！

这个配置会导致TypeAliases扫描完全失效。正确的姿势应该是：

mybatis-plus: mapper-locations: classpath*:/mapper/**/*.xml type-aliases-package: com.example.entity # 保持同级缩进

关键配置项对照表：

提示：在MyBatis-Plus 3.5.x中，开启驼峰映射需要额外添加：

mybatis-plus: configuration: map-underscore-to-camel-case: true

1.2 多数据源下的死亡缠绕

当项目需要连接多个数据库时，常见的连环坑包括：

1. Primary注解遗漏：

@Configuration public class DataSourceConfig { @Bean @Primary // 这个注解绝对不能少！ public DataSource firstDataSource() {...} @Bean public DataSource secondDataSource() {...} }

2. Mapper扫描范围重叠：

@MapperScan(basePackages = "com.dao.mysql", sqlSessionTemplateRef = "mysqlTemplate") public class MysqlConfig {} @MapperScan(basePackages = "com.dao.postgres", sqlSessionTemplateRef = "postgresTemplate") public class PostgresConfig {}

如果两个包路径存在包含关系，就会引发BeanDefinitionOverrideException。建议采用严格的包名隔离：

com.dao.mysql com.dao.postgresql

2. 注解背后的黑暗魔法

2.1 @TableName：你以为的简单其实不简单

这个看似简单的注解藏着三个致命陷阱：

场景一：表名前缀统一配置

@TableName("user") // 当全局配置了表前缀时，实际表名会是"t_user" public class User {}

解决方案：

@TableName(value = "user", keepGlobalPrefix = false) // 显式禁用全局前缀

场景二：动态表名切换

public class User { @TableField(exist = false) private String tableSuffix; public String getDynamicTableName() { return "user_" + tableSuffix; } }

需要在配置类中注册动态表名处理器：

public class MybatisPlusConfig { @Bean public DynamicTableNameParser dynamicTableNameParser() { return (sql, metaObject) -> { Object tableSuffix = metaObject.getValue("tableSuffix"); return tableSuffix != null ? "user_" + tableSuffix : "user"; }; } }

2.2 @TableId：主键类型的修罗场

主键类型配置错误会导致各种诡异问题：

// 雪花ID配置（MySQL的BIGINT） @TableId(type = IdType.ASSIGN_ID) private Long id; // 自增主键（需要数据库设置AUTO_INCREMENT） @TableId(type = IdType.AUTO) private Integer id; // 全局ID生成器（需实现IdentifierGenerator接口） @TableId(type = IdType.ASSIGN_UUID) private String id;

常见踩坑点：

• 数据库字段是BIGINT但实体类用Integer
• 忘记在application.yml配置id-type: ASSIGN_ID
• 混用AUTO和ASSIGN_ID策略

2.3 @TableField：映射的七十二变

这个注解的复杂程度远超想象：

Case 1：字段填充策略

@TableField(fill = FieldFill.INSERT) private LocalDateTime createTime; @TableField(fill = FieldFill.INSERT_UPDATE) private LocalDateTime updateTime;

需要实现元对象处理器：

@Component public class MyMetaObjectHandler implements MetaObjectHandler { @Override public void insertFill(MetaObject metaObject) { this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now()); } @Override public void updateFill(MetaObject metaObject) { this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now()); } }

Case 2：非表字段的三种处理方式

// 方式1：静态忽略 @TableField(exist = false) private String tempValue; // 方式2：动态忽略（通过Wrapper） queryWrapper.select(Student.class, info -> !info.getColumn().equals("temp_value")); // 方式3：条件判断 @TableField(condition = SqlCondition.LIKE) private String name;

3. 高阶玩家的性能调优

3.1 SQL注入器：自定义魔法

实现一个逻辑删除增强器：

public class MyLogicSqlInjector extends DefaultSqlInjector { @Override public List<AbstractMethod> getMethodList(Class<?> mapperClass) { List<AbstractMethod> methodList = super.getMethodList(mapperClass); methodList.add(new DeleteAll()); // 添加自定义方法 return methodList; } } public class DeleteAll extends AbstractMethod { @Override public MappedStatement injectMappedStatement(...) { String sql = "delete from " + tableInfo.getTableName(); SqlSource sqlSource = languageDriver.createSqlSource(...); return this.addDeleteMappedStatement(mapperClass, "deleteAll", sqlSource); } }

注册到Spring容器：

@Bean public MyLogicSqlInjector myLogicSqlInjector() { return new MyLogicSqlInjector(); }

3.2 分页插件性能优化

默认分页在百万级数据时会出现性能问题：

@Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor(); // 优化版分页插件 PaginationInnerInterceptor paginationInterceptor = new PaginationInnerInterceptor(DbType.MYSQL); paginationInterceptor.setOptimizeJoin(true); // 优化联表查询 paginationInterceptor.setMaxLimit(1000L); // 单页最大1000条 interceptor.addInnerInterceptor(paginationInterceptor); return interceptor; }

性能对比数据：

4. 调试技巧：从灵异到科学

4.1 日志配置的黄金组合

在application.yml中添加：

logging: level: com.baomidou.mybatisplus: DEBUG org.springframework.jdbc.datasource: TRACE

配合MyBatis-Plus原生日志：

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

4.2 元数据检查工具

在测试类中添加诊断方法：

@Test void showMetaData() { TableInfoHelper.getTableInfos().forEach(tableInfo -> { System.out.println("=== Table: " + tableInfo.getTableName() + " ==="); tableInfo.getFieldList().forEach(field -> { System.out.println(field.getProperty() + " -> " + field.getColumn()); }); }); }

输出示例：

=== Table: user === id -> user_id name -> user_name createTime -> create_time

4.3 异常速查手册