简介这份资源是面向Java后端开发者与初学者的Spring Boot 3整合MyBatisPlus实战示例工程针对企业级Web应用中数据访问层配置繁琐、CRUD模板代码重复等痛点提供一套可直接运行的整合方案。压缩包共24个文件约85KB包含7个Java源码、7个class编译文件、2个yaml配置、1个properties、1个pom.xml及mvnw构建脚本等覆盖依赖管理、数据源配置、Mapper接口、实体注解与Service、Controller分层结构目录组织清晰便于对照学习。目前已有1435人学习下载说明该整合方案在开发者社区中具有较高的参考价值。读者可从中获取Spring Boot 3与MyBatisPlus协同工作的完整工程骨架理解BaseMapper通用CRUD、条件构造器与自动填充等核心用法并可直接基于该结构扩展业务模块减少重复搭建环境的时间成本。1. Spring Boot 3 整合 MyBatis-Plus从 JDK 17 到分页插件跑通很多人第一次在 Spring Boot 3 里配 MyBatis-Plus都会卡在同一个地方依赖能下、项目能起但一调 Mapper 就报Invalid bound statement或者分页查出来总数永远是 0。这不是代码写错了而是 Spring Boot 3 把底层依赖整体抬到了 JDK 17 和 Jakarta EE 9而 MyBatis-Plus 的 starter 如果版本没跟上扫描和自动装配就会静默失效。这套组合在后台管理系统、数据中台、内部工具里出现频率极高几乎每个 Java 后端都会碰到。下面按我实际装环境的顺序把 JDK、Maven、依赖、配置、分页和排错一次讲清照着走能少熬两个晚上。2. 环境准备JDK 17、Maven 与 Spring Boot 3 的版本对齐2.1 为什么必须是 JDK 17 起步Spring Boot 3 的最低要求是 JDK 17这不是建议是硬门槛。用 JDK 8 或 11 编译spring-boot-starter-web里的jakarta.servlet包根本加载不了启动直接抛NoClassDefFoundError。我一般用 Temurin 17 或 21LTS 版本稳定IDE 里把编译级别和运行级别都设成 17。# 检查当前 JDK 版本必须 17 java -version # 输出示例openjdk version 17.0.9 2023-10-17 # 如果系统有多个 JDK用 JAVA_HOME 显式指定 export JAVA_HOME/usr/lib/jvm/temurin-17-jdk export PATH$JAVA_HOME/bin:$PATHjava -version看的是运行时javac -version看的是编译器两个都要确认。Maven 编译时用的是JAVA_HOME指向的 JDK如果 IDE 里配了别的会出现命令行能编译、IDE 报错的玄学问题。2.2 Maven 版本与镜像配置Maven 用 3.8 以上即可3.9 更稳。关键是settings.xml里配好镜像否则拉 Spring Boot 3 的依赖会慢到怀疑人生。!-- ~/.m2/settings.xml 片段 -- mirrors mirror idaliyun-central/id mirrorOfcentral/mirrorOf namealiyun central/name urlhttps://maven.aliyun.com/repository/central/url /mirror /mirrorsmirrorOf写central表示只代理中央仓库不要写*否则连公司私服也会被劫持。配完后执行mvn help:effective-settings确认镜像生效。2.3 版本对照表别让 starter 版本打架Spring Boot 3 和 MyBatis-Plus 的版本必须成对选下面是我验证过能跑通的组合组件推荐版本说明JDK17 / 21LTS21 性能更好Spring Boot3.2.x3.0/3.1 也可3.2 最稳MyBatis-Plus3.5.5必须用mybatis-plus-spring-boot3-starterMySQL 驱动8.0.33用com.mysql.cj.jdbc.DriverLombok1.18.30低版本在 JDK 21 下会编译失败最容易翻车的是 starter 名字Spring Boot 3 要用mybatis-plus-spring-boot3-starter不是老的mybatis-plus-boot-starter。用错了不会报错只会扫描不到 Mapper。3. 依赖引入与 application.yml 配置落地3.1 pom.xml 里到底写哪几个依赖父工程锁定 Spring Boot 版本子模块只引 starter不要手动指定 MyBatis-Plus 的版本号交给 BOM 管理。parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent dependencies !-- Web 基础Spring Boot 3 自带 jakarta 命名空间 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- 关键Spring Boot 3 专用 starter别用错 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-spring-boot3-starter/artifactId version3.5.5/version /dependency !-- MySQL 驱动scope 用 runtime -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependenciesmybatis-plus-spring-boot3-starter内部已经带了mybatis-spring和mybatis不要再单独引mybatis-spring-boot-starter两个一起引会导致自动配置冲突启动时报BeanDefinitionOverrideException。3.2 application.yml 的最小可用配置spring: datasource: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://127.0.0.1:3306/demo_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/ShanghaiuseSSLfalse username: root password: your_password mybatis-plus: # Mapper XML 位置多个路径用逗号分隔 mapper-locations: classpath*:/mapper/**/*.xml # 实体类别名包XML 里可直接写类名 type-aliases-package: com.example.demo.entity configuration: # 下划线转驼峰数据库 user_name - 实体 userName map-underscore-to-camel-case: true # 开发期打印 SQL上线关掉 log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: # 主键自增实体不写 TableId 也能识别 id-type: automapper-locations里的classpath*:带星号表示扫描所有 jar 和目录下的匹配文件漏了星号在多模块项目里只能扫到当前模块。serverTimezone必须写不写 MySQL 8 会报时区错误。3.3 启动类加 MapperScanSpringBootApplication MapperScan(com.example.demo.mapper) // 扫描 Mapper 接口 public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }MapperScan的包路径要精确到 mapper 接口所在包不要写com.example.demo这种大范围否则会把 Service 也当 Mapper 扫描启动报No statement found。如果每个 Mapper 上都加了Mapper可以省略这个注解但多模块下我建议统一用MapperScan省得漏。4. 分页插件与代码生成器两个最容易配错的模块4.1 分页插件必须手动注册MyBatis-Plus 3.5.x 的分页插件不会自动生效必须写配置类。不注册的话Page查询返回全部数据total为 0这是最高频的坑。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 分页插件指定数据库类型 interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL)); // 乐观锁插件按需加 interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor()); return interceptor; } }DbType.MYSQL要和你实际数据库一致写成DbType.OTHER分页 SQL 会拼错。多个内部拦截器有顺序要求分页插件放最后加否则可能被其他拦截器改写 SQL 导致分页失效。4.2 分页查询的写法与验证// Service 层 public IPageUser pageQuery(int pageNum, int pageSize) { PageUser page new Page(pageNum, pageSize); // 第二个参数是查询条件null 表示查全部 return userMapper.selectPage(page, null); }Page的pageNum从 1 开始不是 0。传 0 会返回空列表但不报错很容易误判成没数据。验证时看控制台打印的 SQL 有没有LIMIT有LIMIT且total正确说明插件生效。4.3 代码生成器在 Spring Boot 3 下的调整MyBatis-Plus 的代码生成器依赖freemarker和velocitySpring Boot 3 下要单独引且模板引擎版本要新。FastAutoGenerator.create(url, username, password) .globalConfig(builder - builder .author(dev) .outputDir(System.getProperty(user.dir) /src/main/java) .disableOpenDir()) // 生成后不自动打开目录 .packageConfig(builder - builder .parent(com.example.demo) .entity(entity) .mapper(mapper) .service(service)) .strategyConfig(builder - builder .addInclude(user, order) // 指定表名 .entityBuilder().enableLombok()) .execute();outputDir用user.dir相对路径别写死绝对路径换机器就废。addInclude不写会生成全库所有表生产库上跑一次能生成几百个文件。5. 避坑排查整合后启动报错的五条血泪记录5.1 现象Invalid bound statement (not found)原因Mapper 接口和 XML 没对上。要么mapper-locations路径写错要么 XML 的namespace不是接口全限定名要么 XML 放在src/main/java下没配资源过滤。解决先看target/classes/mapper下有没有 XML 文件没有就是资源没打包。在pom.xml的build里加resources resource directorysrc/main/java/directory includes include**/*.xml/include /includes /resource /resources5.2 现象分页 total 为 0数据却查出来了原因分页插件没注册或者注册了但DbType写错。还有一种情况是自定义 SQL 里用了UNION分页插件生成的 count 语句不兼容。解决确认MybatisPlusInterceptor被 Spring 扫描到自定义复杂 SQL 手动写 count 查询用page.setTotal()设置。5.3 现象启动报 jakarta.servlet 相关 ClassNotFound原因引了老的javax.servlet依赖或者某个第三方库还在用 javax。解决mvn dependency:tree | grep javax.servlet找出冲突源排除掉。Spring Boot 3 下所有 servlet 相关依赖都必须是 jakarta 版本。5.4 现象Lombok 编译报错提示找不到符号原因Lombok 版本低于 1.18.30在 JDK 21 下注解处理器不工作。解决升级 Lombok 到 1.18.30并在maven-compiler-plugin里显式配置注解处理器路径。5.5 现象多模块下子模块 Mapper 扫描不到原因MapperScan只写在启动类所在模块子模块的 Mapper 包不在扫描范围。解决MapperScan写多个包路径或者用MapperScan(basePackages {com.example.module1.mapper, com.example.module2.mapper})。6. 装完怎么验证三条命令确认整合真的跑通环境装完别急着写业务先跑一遍验证。我一般按下面三步走任何一步不过就回去查对应配置。第一步启动应用看日志。控制台出现MyBatis-Plus的 banner 和Started DemoApplication才算启动成功。如果看到No MyBatis mapper was found的警告说明MapperScan路径不对。第二步调一个分页接口看控制台 SQL。正常应该打印两条一条SELECT COUNT(*)一条带LIMIT的查询。只有一条带LIMIT的说明分页插件没生效。# 用 curl 验证分页接口 curl http://127.0.0.1:8080/user/page?pageNum1pageSize10 # 期望返回{records:[...],total:100,size:10,current:1}total是真实总数records长度等于pageSizecurrent等于传入的pageNum三个都对才算过。第三步验证 XML 自定义 SQL。写一个带resultMap的查询确认字段映射正确。如果返回对象字段全是 null检查map-underscore-to-camel-case是否开启以及 XML 里resultType写的是不是全限定名。验证项通过标准失败先查应用启动无 Mapper 警告MapperScan 路径分页查询有 COUNT 和 LIMIT分页插件注册XML 查询字段有值mapper-locations主键回填insert 后 id 有值id-type 配置从那以后我每次搭 Spring Boot 3 加 MyBatis-Plus 的环境都强制先跑这三步再写业务代码省得写到一半发现分页是坏的、字段映射是错的回头返工更费时间。希望帮到你。本文还有配套的精品资源点击获取