SpringBoot+MybatisPlus整合实战：自动装配、分页失效与版本选型

做Java后端这些年，SpringBoot结合Mybatisplus这套组合几乎成了我日常用得最顺手、也推荐给新人最多的技术栈。每次和同事聊起，总有人问“为什么大家都在用Mybatisplus”“分页插件配了但不生效”“SpringBoot版本太高了启动直接报错”之类的问题。与其零散地回答，不如把这几年整合SpringBoot与Mybatisplus的完整经验整理成一篇文章，从自动装配原理到版本选型，从分页插件到实体类一键生成建表DDL，再到各种翻车现场和排查方法，一次性讲透。这篇文章适合正在准备毕设的学生、刚转SpringBoot的后端开发，以及在公司维护老项目的朋友，花十分钟看完，应该能省掉不少调试时间。

1. 整合前要想清楚的事：为什么是Mybatisplus

1.1 持久层开发到底难在哪

很多人刚开始用MyBatis时会觉得“明明很简单，为啥写起来这么费劲”。一张表的增删改查，要先建Mapper接口，再去XML里写四个标签，就算有MyBatis Generator帮忙生成代码，一旦表结构调整，又要重新生成。更别提分页，原生MyBatis自带的分页依赖PageHelper，翻车姿势千奇百怪：分页插件拦截不了自定义SQL、count查询优化不了、嵌套结果映射时分页总数不对。这些痛点几乎每个Java项目都踩过一遍。

Mybatisplus（下称MP）站在MyBatis的肩膀上，把单表CRUD直接提到了框架层面。只要Mapper接口继承BaseMapper<T>，增删改查、批量插入、分页查询、逻辑删除、自动填充这些能力自动就有。不用写XML，不用手动拼接SQL，甚至字段到列的映射、下划线转驼峰这些琐事也被接管了。它的核心价值不是让你少写几行代码，而是让“不具备特殊性的单表操作”不再占用你的注意力，把精力留给真正的业务查询和复杂逻辑。我见过不少项目引入MP之后，Mapper目录下的XML文件减少了八成以上，新人上手成本也明显降低。

1.2 SpringBoot自动装配与MP的衔接逻辑

整合SpringBoot和MP，本质上是让SpringBoot的自动装配机制接管MyBatis的初始化流程。SpringBoot在classpath下扫描到mybatis-plus-boot-starter之后，会触发MybatisPlusAutoConfiguration。这个自动配置类会创建SqlSessionFactory，并注入MP自己扩展的拦截器链。关键点在于，MP替换掉的是默认的MyBatis配置，所以原生的mybatis-spring-boot-starter不需要再重复引入，否则可能出现SqlSessionFactoryBean冲突之类的问题。

在实际项目中，@MapperScan注解负责把Mapper接口交给Spring管理。很多人在这一步翻车，是因为扫描路径写错，或者Mapper接口没有继承BaseMapper。MP的BaseMapper泛型必须指向真实的实体类，比如BaseMapper<User>，这一步写错会导致条件构造器里的lambda无法解析字段，启动时可能不报错，一运行就抛出各种异常。

2. 版本选型：SpringBoot版本太高怎么破

2.1 版本不匹配的典型翻车现场

搜索热词里“springboot版本太高”出现得很频繁，这确实是这几年最常见的问题。SpringBoot从2.x升级到3.x之后，底层的javax命名空间全部迁移到了jakarta，同时最低要求JDK17。老的mybatis-plus-boot-starter如果直接搬到SpringBoot3项目里，通常启动就报ClassNotFoundException，第一个找不到的就是javax.servlet相关的类。

另一个隐蔽问题是MyBatis的参数解析和JSqlParser组件兼容性。MP的分页和条件构造器依赖JSqlParser解析SQL，而不同版本的MP对应不同大版本的JSqlParser。比如3.4.x和3.5.x的JSqlParser差异就不小，如果一个项目强行把SpringBoot3和旧版MP搭配，分页插件在解析SQL时可能直接抛异常，而且报错信息晦涩难懂，搜都搜不到。

解决这个问题没有捷径，核心原则就一条：SpringBoot3项目用官方提供的mybatis-plus-spring-boot3-starter，SpringBoot2项目继续用mybatis-plus-boot-starter。千万别贪图方便把旧坐标复制过来就完事。对于还没建项目的朋友，我建议直接用目前使用量最大的组合：JDK17 + SpringBoot 3.2.x + mybatis-plus-spring-boot3-starter 3.5.x，这套组合既能体验到SpringBoot的新特性，也不会踩javax迁移的坑。

2.2 最小化依赖与基础配置

依赖声明是整个整合里最简单也最容易出错的部分。以SpringBoot 2.7为例，我们只需要加入mybatis-plus-boot-starter和MySQL驱动，不需要再单独引mybatis。Lombok不是必须的，但配合@Data使用实体类会清爽很多，项目里基本都会带上。

xml复制<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.5</version>
</dependency>
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <scope>runtime</scope>
</dependency>

如果是SpringBoot3，把第一个坐标换成mybatis-plus-spring-boot3-starter即可。数据源配置关注几个点：数据库URL中serverTimezone建议显式指定Asia/Shanghai，否则服务器和本机时区不一致时，日期时间字段可能出现8小时偏差；useSSL建议设成false，避免本地测试时证书告警刷屏。MP的配置我一般放在mybatis-plus节点下，核心是map-underscore-to-camel-case真值，MP默认就是true，但原生MyBatis默认是false，如果你之前写过原生MyBatis，很容易栽在这个差异上。

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: assign_id
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

id-type这项特别多说一句。assign_id是MP内部生成的雪花ID，适用于分布式环境下主键由应用生成的场景；如果你的表主键是数据库自增，一定要把它改成auto，否则插入数据时MP会强行塞一个雪花ID给主键字段，数据库自增完全失去意义。我就见过同事因为这个问题，主键值乱七八糟，排查了很久才意识到。

3. 分页、建表与字段维护：高频功能的细节拆解

3.1 分页插件失效的六个真实原因

“mybatisplus分页失效”这个热词几乎每周都有人搜，说明这不是个别现象。MP在3.4.0之后统一了拦截器入口，分页能力必须通过MybatisPlusInterceptor注册PaginationInnerInterceptor来实现。很多人引了依赖、写了Service，但漏了Interceptor注册，Page对象返回后total一直是0，或者数据全量返回，看起来就像分页没生效。

我给出一份我自己项目里一直用的分页配置，放到任意@Configuration类里即可：

java复制@Configuration
public class MybatisPlusConfig {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

除了漏注册，分页失效通常还有这几类原因。第一，DbType写错，比如MySQL库却配了DbType.ORACLE，分页SQL语法直接不对，报错或者查不出数据。第二，自定义Mapper方法的参数列表里，Page对象必须放在能被MP识别的位置，并且查询方法要接收IPage返回值。第三，手写SQL里自己拼了LIMIT，分页插件再追加limit，SQL直接语法错误。第四，多数据源场景下，拦截器只注入到其中一个数据源，另一个数据源的分页自然没效果。第五，用了老版本MP的旧式PaginationInterceptor配置模板，和当前版本冲突，这种情况我建议直接删除旧Bean，统一使用MybatisPlusInterceptor。

排查时可以按这个顺序来：先确认Spring容器里有MybatisPlusInterceptor这个Bean，再确认拦截器的DbType和实际数据库一致，再检查Mapper方法是否把IPage作为参数传入，最后看看日志里打印出来的SQL有没有LIMIT。这四个层级检查完，绝大多数分页问题都能定位。

3.2 根据Java实体类一键生成建表DDL

“根据java实体类生成创建表的sql语句”是个非常实际的诉求。很多团队没有专职DBA，表的维护靠开发手动写DDL，写着写着就和实体类对不上，少个字段、类型不匹配、注释缺失，上线时才发现问题。MP本身不提供自动建表功能，但我们可以利用它的TableInfoHelper，在应用启动或测试阶段解析实体类上注解，生成对应的CREATE TABLE语句。

思路其实不复杂：实体类上的@TableName标注了表名，@TableId标注了主键列，@TableField标注了每个字段对应的列名，TableInfoHelper会把它们解析成内部的TableInfo对象。我们要做的就是把TableInfo里的字段信息重新组织成DDL字符串。字段注释需要额外处理，因为MP的@TableField没有comment属性，我习惯自定义一个@ColumnComment注解，配合起来使用。

java复制@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ColumnComment {
    String value() default "";
}

生成器核心代码大致是这个样子。它遍历TableInfo的字段列表，根据Java类型映射到MySQL类型，再拼接主键、表注释和引擎配置：

java复制public class DdlGenerator {

    public static String buildCreateTableSql(Class<?> entityClass) {
        TableInfo tableInfo = TableInfoHelper.getTableInfo(entityClass);
        if (tableInfo == null) {
            throw new IllegalArgumentException("无法解析实体类: " + entityClass.getName());
        }
        StringBuilder sql = new StringBuilder();
        sql.append("CREATE TABLE IF NOT EXISTS `").append(tableInfo.getTableName()).append("` (\n");

        sql.append("  `").append(tableInfo.getKeyColumn())
           .append("` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',\n");

        for (TableFieldInfo fieldInfo : tableInfo.getFieldList()) {
            String column = fieldInfo.getColumn();
            String javaType = fieldInfo.getPropertyType().getSimpleName();
            String columnType = mysqlType(javaType);
            ColumnComment comment = fieldInfo.getField().getAnnotation(ColumnComment.class);
            String commentStr = comment == null ? "" : comment.value();
            sql.append("  `").append(column).append("` ").append(columnType)
               .append(" DEFAULT NULL COMMENT '").append(commentStr).append("',\n");
        }

        // 去掉最后一个逗号，拼主键
        sql.setLength(sql.length() - 2);
        sql.append("\n  PRIMARY KEY (`").append(tableInfo.getKeyColumn()).append("`)\n");
        sql.append(") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='")
           .append(tableInfo.getComment()).append("';");
        return sql.toString();
    }

    private static String mysqlType(String javaType) {
        switch (javaType) {
            case "String": return "VARCHAR(128)";
            case "Integer": return "INT";
            case "Long": return "BIGINT";
            case "BigDecimal": return "DECIMAL(18,2)";
            case "LocalDateTime": return "DATETIME";
            case "Boolean": return "TINYINT(1)";
            default: return "VARCHAR(255)";
        }
    }
}

在测试类里跑一下，控制台输出建表SQL，复制到数据库执行即可。更进一步，可以做一个ApplicationRunner，在应用启动时先检查表是否存在，不存在就自动执行这段SQL，这对本地开发和小项目非常友好，省去手动同步表结构的麻烦。但必须提醒一点：这个方案适合个人项目、学习项目或者两三个人的小团队，一旦项目上了规模，多环境多人协作，还是老老实实用Flyway这类数据库版本管理工具，否则一个字段升级就可能让所有环境的数据定义二次漂移。

3.3 自动填充、逻辑删除与乐观锁的联动细节

自动填充用来处理createTime、updateTime这类字段非常省心。实现MetaObjectHandler后，插入时自动写下创建时间，更新时自动写修改时间，业务代码不碰这两个字段。这里有个典型的翻车点：stricttInsertFill里的字段名必须和实体类的走蛇,如果实体类用了createTime，处理器里写的就是createTime，一旦拼错，MP会选择静默不填充，数据落库后时间字段是null。同时，实体类对应字段需要加上@TableField(fill = FieldFill.INSERT)或INSERT_UPDATE，否则MP不会触发填充逻辑。

逻辑删除也是高频功能。@TableLogic标注的字段，在查询时MP会自动追加deleted=0，在删除时自动转为UPDATE语句，避免物理删除。但这会引入一个很隐蔽的问题：如果业务表上有唯一索引，比如用户表的用户名唯一，逻辑删除后该记录还留在表里，下次再注册同一个用户名，唯一索引直接冲突。解决方案是让唯一索引包含逻辑删除字段，比如(username, deleted)组成联合唯一索引，这样deleted=0只有一条有效记录，deleted=1的垃圾记录可以有多条，重新注册不受影响。

乐观锁用于并发更新的场景，@Version字段配合OptimisticLockerInnerInterceptor使用。它的原理是执行UPDATE时自动带上WHERE version=旧值，同时SET version=旧值+1。要注意，只有走MP的updateById或者update(entity, wrapper)时才会触发乐观锁，如果写了自定义SQL，MP加不了version条件，你就得自己处理，不然并发就失控了。常见实现里version字段建议用Long或Integer，避免用时间戳，因为高并发下时间戳的粒度可能不够。

4. 完整实操：从零搭一个用户管理模块

4.1 搭建工程和编写配置

空谈原理不如直接上手。我以用户管理为例，展示一个完整的整合过程。先到start.spring.io生成一个基础工程，SpringBoot版本建议直接选2.7.x，引入Web、MySQL驱动和Lombok，再加MP的starter依赖。工程生成后，把application.yml替换成上文的配置，重点检查数据源URL和MP的全局配置。

实体类提前规划好：主键id、用户名、昵称、创建时间、更新时间、逻辑删除标记、版本号。主键用AssignedId雪花ID，还是数据库自增，取决于你团队是否使用分布式主键方案。我习惯于公司内部的常规业务表用数据库自增，跨库合并或分库分表业务才用雪花。实体类这样写：

java复制@Data
@TableName(value = "sys_user", comment = "用户表")
public class User {

    @TableId(type = IdType.AUTO)
    private Long id;

    private String username;

    private String nickname;

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

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

    @TableLogic
    private Integer deleted;

    @Version
    private Long version;
}

启动类上记得加@MapperScan，扫描路径指向Mapper接口所在包：

java复制@SpringBootApplication
@MapperScan("com.example.demo.mapper")
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Mapper接口什么都不用写，继承BaseMapper即可：

java复制public interface UserMapper extends BaseMapper<User> {
}

4.2 实体类、Mapper、Service、Controller全链路

Service层我习惯结合MP的IService接口写。IService内置了page方法、saveBatch批量保存方法、lambda链式查询等，配合ServiceImpl实现类，几乎不用写一行SQL。

java复制public interface UserService extends IService<User> {
}

@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
}

Controller里写一个分页查询接口，接收当前页、每页条数和用户名关键字。这里用LambdaQueryWrapper，字段引用全部走lambda方法，编译期就能发现字段名拼写错误。使用like方法时，第一个参数是条件布尔值，只有条件成立时才会拼接SQL，这个写法比手动判断是否为空要干净。

java复制@RestController
@RequestMapping("/user")
public class UserController {

    @Resource
    private UserService userService;

    @GetMapping("/page")
    public IPage<User> page(@RequestParam(defaultValue = "1") long current,
                            @RequestParam(defaultValue = "10") long size,
                            @RequestParam(required = false) String username) {
        LambdaQueryWrapper<User> wrapper = Wrappers.lambdaQuery();
        wrapper.like(StringUtils.hasText(username), User::getUsername, username)
               .orderByDesc(User::getCreateTime);
        return userService.page(new Page<>(current, size), wrapper);
    }
}

分页接口返回的IPage对象里有records、total、current、pages四个关键属性，前端要的总数和当前页数据都能直接拿到。如果你要自己封装返回结构，从IPage里取数据塞到自定义VO即可，不建议直接把IPage暴露给前端，因为内部字段名可能和前端约定不一致，也不方便统一处理错误码。

这里再强调一个编程习惯：查询条件拼接时，尽量用LambdaQueryWrapper，而不是普通的QueryWrapper。后者用字符串写字段名，一旦实体类里改了字段名，编译期没问题，运行时直接SQL异常。用lambda写法，IDE重构自动跟着变，安全性高一个档次。

4.3 两个容易被忽略的批量写入优化

批量插入是MP的亮点之一，但它默认的批量方式和很多人想象的批处理不太一样。ServiceImpl里的saveBatch，底层是按每批1000条循环执行JDBC的executeBatch，MySQL默认情况下并不会把连续的单条INSERT语句合并成真正的批量SQL，性能提升有限。解决方法是给数据源URL追加一个参数rewriteBatchedStatements=true，让MySQL驱动把多条INSERT语句重写成一条多值INSERT，写入效率会有非常明显的提升。我在本地测试过，同样五千条数据，加这个参数后耗时能减少一大半。

另一个容易被忽略的是事务边界。批量操作或涉及多张表的写操作，一定要在Service方法上加@Transactional。有一个自坑的经典场景：同类的A方法调用B方法，B上有@Transactional，但A方法没有，调用发生时事务根本不生效，因为Spring事务走的是代理机制，同类内部调用跳过了代理。解决方法是把B方法放到另一个Service类，或者通过注入自身代理调用来保证事务边界正确。

5. 实战问题排查与踩坑记录

5.1 高频问题速查表

放在最前，这十来个问题是我在实际项目里或者帮同事排查时遇到频率最高的。每个问题背后都对应着某一段真实翻车经历，能查表解决就不用在搜索引擎里反复试错。

5.2 多模块与部署场景的几个提醒

很多项目是Gradle多模块结构，或者把entity、mapper、service拆分成多个子模块。这种架构下，使用MP有个容易忽略的点：实体类和Mapper分散在不同模块时，@MapperScan的扫描路径要精确到实际Mapper接口所在包，如果把整个父包都扫了，很可能把不相关的Bean也扫进来，导致容器初始化异常。如果是多个SpringBoot应用共享一套底层Mapper模块，我更建议把实体类和Mapper打包成独立Library模块，每个应用按需引用，避免一套代码被多份扫描，否则字段改动后各应用只更新一部分，线上就会出现诡异的数据错乱。

另一个常见场景是部署到宝塔Docker环境，容器里的应用连宿主机MySQL，容易在URL的IP地址、端口映射、时区上踩坑。容器内部访问宿主机的MySQL地址不能写localhost，要写宿主机在Docker网络中的IP或特殊域名，时区最好直接在容器启动参数里指定，否则日志时间和数据库时间可能对不上。不过这类问题不属于MP范畴，核心原则是先在宿主机手动跑一次打通的连接，再进容器排查网络和时区，效率会高很多。

5.3 防坑的三个经验习惯

第一，实体类字段不要用基本类型，全部用包装类型。Integer可以区分“0”和“null”，Long可以明确主键是否被赋值，Boolean判断逻辑删除状态时不会出现NPE。MP在做更新策略时，字段为null默认不参与SET，基本类型字段很难表达“未设置”这个语义，容易误更新。

第二，MP的逻辑删除和数据库层的外键、唯一索引存在天然矛盾。逻辑删除后数据还在，外键约束会阻止关联表插入或删除，唯一索引会让你无法重建同名的记录。用MP前，先想清楚哪些表需要逻辑删除，哪些表宁可物理删，别图省事全局开启，后面牵一发动全身。

第三，条件构造器虽然强大，但别把它写成两千行的上帝方法。当一个Wrapper里堆了七八个and、多个exists嵌套子查询时，SQL已经复杂到没人能看懂，这时候应该去XML里手写SQL，并把通用片段抽出来复用。MP的定位是消除简单CRUD的重复劳动，不是让你把复杂报表逻辑塞进Java代码里。

最后分享一个我自己的使用习惯：新建项目时，我总会把MP的版本锁定在一个已知稳定的版本上，而不是每次跟着最新版升级。升级前先读官方的升级日志，重点看JSqlParser、拦截器API、依赖坐标三个地方有没有破坏性变更，然后在测试环境跑一遍全量单元测试。这个习惯帮我避开过好几次升级带来的分页失效和自动填充异常的问题。现在做项目已经离不开MP了，但越是熟悉它，越要小心那些“看起来正常”的接口，比如Boolean字段默认参与更新、自定义SQL不自动套逻辑删除这类隐性行为，读一遍源码或官方文档，心里有底，才不会在线上栽跟头。