Spring Boot 3.3与Mybatis-Plus整合实战与问题解决

1. Spring Boot 3.3.X与Mybatis-Plus整合实战指南

最近在升级Spring Boot到3.3.2版本时，遇到了Mybatis-Plus整合的坑点。特别是当你想同时使用Mybatis-Plus的自动CRUD方法和自定义SQL时，配置不当很容易出现"Invalid bound statement"问题。本文将完整记录我的踩坑过程和最终解决方案。

2. 环境准备与基础配置

2.1 版本选择与依赖管理

首先明确版本组合：

• Spring Boot: 3.3.2
• Mybatis-Plus: 3.5.7

关键依赖配置（pom.xml）：

xml复制<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.7</version>
</dependency>

重要提示：必须使用mybatis-plus-spring-boot3-starter而非传统的starter，这是专为Spring Boot 3+设计的适配版本。我最初尝试的3.5.1版本组合会导致基础CRUD方法失效。

2.2 数据库连接配置

application.properties关键配置：

properties复制# 数据源配置
spring.datasource.url=jdbc:mysql://localhost:3306/dormitory?allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai&useSSL=false
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# Mybatis-Plus配置
mybatis-plus.mapper-locations=classpath:/mapper/*.xml
mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl
logging.level.com.dormitory.dormitory_backend.mapper=DEBUG

3. 核心组件实现

3.1 实体类设计

使用Mybatis-Plus注解规范实体类：

java复制@Data
@TableName("t_attendance")
public class Attendance {
    @TableId(type = IdType.AUTO)
    private Integer id;
    
    @TableField("user_account")
    private String userAccount;
    
    private String reason;
}

注解说明：

• @TableName：指定对应表名
• @TableId：标记主键，type=AUTO表示自增
• @TableField：字段映射（可省略字段名相同的）

3.2 Mapper层实现

基础接口继承BaseMapper：

java复制@Mapper
public interface AttendanceMapper extends BaseMapper<Attendance> {
    // 自定义方法
    int insertAttendance(Attendance attendance);
    int deleteAttendance(Integer id);
}

XML映射文件要点：

xml复制<mapper namespace="com.dormitory.dormitory_backend.mapper.AttendanceMapper">
    <insert id="insertAttendance">
        INSERT INTO t_attendance(user_account,reason) 
        VALUES(#{userAccount},#{reason})
    </insert>
    
    <delete id="deleteAttendance">
        DELETE FROM t_attendance WHERE id = #{id}
    </delete>
</mapper>

3.3 Service层实现

混合使用自动CRUD和自定义方法：

java复制@Service
public class AttendanceServiceImpl implements AttendanceService {
    @Autowired
    private AttendanceMapper mapper;

    // 使用自定义方法
    public int addAttendance(Attendance att) {
        return mapper.insertAttendance(att);
    }
    
    // 使用Mybatis-Plus自带方法
    public int deleteAttendance(Integer id) {
        return mapper.deleteById(id);
    }
}

4. 常见问题解决方案

4.1 Invalid bound statement错误排查

遇到"Invalid bound statement (not found)"时的检查清单：

1. Mapper扫描配置

   • 启动类添加@MapperScan("包路径.mapper")
   • 确保路径与实际Mapper接口包一致

2. XML文件位置

   • 检查mybatis-plus.mapper-locations配置
   • XML文件应放在resources/mapper/目录下

3. 命名空间匹配

   xml复制<!-- 必须与Mapper接口全限定名一致 -->
   <mapper namespace="com.example.mapper.UserMapper">
   

4. 方法签名一致性

   • XML中的id必须与接口方法名一致
   • 参数类型/返回值类型需匹配

4.2 分页插件配置

如需分页功能，添加配置类：

java复制@Configuration
public class MybatisConfig {
    @Bean
    public MybatisPlusInterceptor paginationInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor());
        return interceptor;
    }
}

使用示例：

java复制Page<Attendance> page = new Page<>(1, 10);
Page<Attendance> result = attendanceMapper.selectPage(page, null);

5. 开发调试技巧

5.1 SQL日志打印配置

application.properties添加：

properties复制# 显示执行的SQL及参数
mybatis-plus.configuration.log-impl=org.apache.ibatis.logging.stdout.StdOutImpl
logging.level.com.yourpackage.mapper=DEBUG

5.2 快速生成代码

使用Mybatis-Plus代码生成器：

java复制FastAutoGenerator.create(dataSourceConfig)
    .globalConfig(builder -> builder.outputDir("src/main/java"))
    .packageConfig(builder -> builder.parent("com.example"))
    .strategyConfig(builder -> builder.addInclude("t_attendance"))
    .execute();

5.3 接口测试验证

使用Swagger UI进行接口测试：

1. 添加依赖：

xml复制<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

2. 访问http://localhost:8080/swagger-ui.html

6. 性能优化建议

1. 二级缓存配置

   xml复制<cache eviction="LRU" flushInterval="60000"/>
   

2. 批量操作

   java复制// 批量插入
   boolean success = attendanceService.saveBatch(list);
   

3. 逻辑删除
   实体类添加：

   java复制@TableLogic
   private Integer deleted;
   

7. 升级注意事项

从Spring Boot 2.x迁移到3.x时需注意：

1. JDK最低要求17+
2. Mybatis-Plus必须使用boot3专用starter
3. 部分API有变动，需检查兼容性

通过以上配置，我成功在Spring Boot 3.3.2中整合了Mybatis-Plus 3.5.7，实现了自动CRUD与自定义SQL的混合使用。关键点在于使用正确的starter依赖和简洁的配置方式，避免过度复杂的配置类。