1. 为什么“SpringBootMybatis整合”这个动作本身就值得单独写一篇入门很多人点开“SpringBootMybatis整合入门”这类标题时心里想的是“不就是加个依赖、配个数据源、写个Mapper接口十分钟搞定。”我试过——在某个模拟项目X里用官方文档照着敲确实十分钟跑通了第一个查询。但三天后当需要加事务控制时Transactional加了没反应一周后联表查询返回字段全为 null两周后日志里开始疯狂刷Could not obtain JDBC Connection……最后发现问题既不在 Mybatis 的 XML 里也不在 SpringBoot 的application.yml中而是在整合层那几行看似无害的自动配置逻辑里。这恰恰是“整合”二字最常被低估的地方它不是两个框架的物理拼接而是两套生命周期管理、对象创建机制、代理策略和事务传播规则的深度耦合。SpringBoot 的SpringBootApplication自动扫描会接管 Mybatis 的SqlSessionFactory创建但默认配置只覆盖了 70% 的常见场景Mybatis 的MapperScannerConfigurer在 Spring 容器启动时注入 Mapper 接口代理可一旦你引入了多数据源或自定义拦截器这个代理链就会悄然断裂。更关键的是新手常把“能查出数据”等同于“整合成功”。但真实业务中一个未显式声明的MapperScan路径错误会导致部分 Mapper 接口根本没被 Spring 管理运行时抛NoSuchBeanDefinitionException一个漏掉的mybatis.configuration.map-underscore-to-camel-casetrue配置会让所有数据库下划线字段映射失败却不会报错只默默返回 null 值——这种静默失败比直接崩溃更难排查。所以这篇“入门一”不讲怎么写第一个 Controller也不堆砌 Maven 依赖坐标。我们先回到最原始的起点搞清楚 SpringBoot 是如何“认出” Mybatis 的Mybatis 又是如何“交出控制权”给 Spring 容器的。这个认知边界决定了你是把整合当成黑盒调用还是把它当作可调试、可定制、可诊断的系统工程。后面所有事务失效、SQL 日志不打印、动态 SQL 报错的问题根源几乎都埋在这里。提示本文所有配置和代码均基于 SpringBoot 3.2.x Mybatis 3.5.x最新稳定组合不兼容 SpringBoot 2.x 的旧式mybatis-spring-boot-starter配置方式。如果你还在用spring-boot-starter-mybatis注意包名差异请立刻停手——那是已被废弃的旧版 starter。2. Starter 机制的本质不是“帮你写代码”而是“帮你接管控制权”很多教程一上来就让加依赖dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version3.0.3/version /dependency然后说“好了Mybatis 就集成进来了。”这就像告诉你“把钥匙插进锁孔门就开了”却从不解释锁芯内部的弹子排列、弹簧张力、以及为什么同一把钥匙能开不同厂家的门。mybatis-spring-boot-starter的核心价值从来不是“提供 Mybatis 功能”而是提供一套 SpringBoot 兼容的自动装配契约。它内部包含一个MybatisAutoConfiguration类这个类才是真正的“整合开关”。我们来看它的关键逻辑2.1 条件装配SpringBoot 的“准入门槛”MybatisAutoConfiguration类顶部有这样一段注解ConditionalOnClass({ SqlSessionFactory.class, SqlSessionFactoryBean.class }) ConditionalOnBean(DataSource.class) EnableConfigurationProperties(MybatisProperties.class)这三行代码定义了 Mybatis 自动配置生效的全部前提条件ConditionalOnClass要求 classpath 下必须存在SqlSessionFactory和SqlSessionFactoryBean类。这意味着如果你只加了mybatis核心包org.mybatis:mybatis而没加mybatis-spring提供SqlSessionFactoryBean自动配置压根不会触发——你会得到一个“依赖加了但完全没反应”的诡异状态。ConditionalOnBean(DataSource.class)强制要求容器中已存在DataSourceBean。这是最关键的隐性依赖。SpringBoot 的DataSource自动配置由DataSourceAutoConfiguration提供必须先于 Mybatis 配置执行。如果application.yml里数据库配置写错比如spring.datasource.url拼写成spring.datasource.urllDataSourceBean 创建失败Mybatis 的自动配置就会被跳过且不会报任何与 Mybatis 相关的错误只会提示Failed to configure a DataSource——新手往往在此处卡住数小时反复检查 Mybatis 配置却忽略了源头的 DataSource。2.2 属性绑定MybatisProperties是什么EnableConfigurationProperties(MybatisProperties.class)这行代码将application.yml中以mybatis.开头的所有配置项自动绑定到MybatisProperties这个 POJO 对象上。这个类的结构直接决定了你能通过配置文件控制哪些行为。例如application.yml配置项MybatisProperties字段实际影响mybatis.config-locationclasspath:mybatis-config.xmlprivate Resource configLocation;指向 Mybatis 全局配置文件若不指定则使用默认最小化配置mybatis.mapper-locationsclasspath:mapper/*.xmlprivate Resource[] mapperLocations;必须显式配置否则 Mybatis 找不到 XML 映射文件Mapper 接口无法加载mybatis.type-aliases-packagecom.example.domainprivate String typeAliasesPackage;为实体类设置别名避免在 XML 中写全限定名这里有个极易踩的坑mapper-locations默认值是null而不是classpath*:/mapper/**/*.xml。这意味着如果你不手动配置这一项哪怕 XML 文件放在src/main/resources/mapper/下Mybatis 也完全感知不到——它不会主动扫描资源路径。很多教程只教“加依赖”却漏掉这行致命配置导致新人写出完美 XML 和 Mapper 接口却始终报Invalid bound statement (not found)。2.3 核心 Bean 的创建顺序谁先谁后决定一切MybatisAutoConfiguration内部定义了多个Bean方法它们的执行顺序严格遵循 Spring 的依赖注入规则。最关键的三个 Bean 是sqlSessionFactory(DataSource dataSource, MybatisProperties properties)这是 Mybatis 的心脏。它接收 Spring 管理的DataSource并根据MybatisProperties构建SqlSessionFactoryBean。注意此方法参数明确依赖DataSource因此 Spring 必须先创建好DataSourceBean才能调用此方法。sqlSessionTemplate(SqlSessionFactory sqlSessionFactory)这是 Spring 对 MybatisSqlSession的封装。它确保每次数据库操作都使用 Spring 管理的、线程安全的SqlSession从而支持事务。没有这个 BeanTransactional就是摆设。mapperScannerConfigurer()这个 Bean 的作用是扫描指定包路径下的所有Mapper接口并为每个接口生成一个 Spring 管理的代理 Bean。它依赖sqlSessionFactory因此必须在SqlSessionFactory创建之后才执行。这个依赖链条DataSource → SqlSessionFactory → SqlSessionTemplate → MapperScannerConfigurer就是整个整合的骨架。任何一个环节中断比如DataSource创建失败、SqlSessionFactory构建时抛异常后续 Bean 就无法生成最终表现为“Mapper 接口无法注入”或“事务不生效”。注意MapperScannerConfigurer的扫描路径必须与你的Mapper接口所在包完全匹配。例如若接口在com.example.mapper.UserMapper则MapperScan(com.example.mapper)必须精确到com.example.mapper不能写成com.example或com.example.mapper.*后者语法错误。路径错误不会报错只会静默跳过扫描——这是最隐蔽的失败模式之一。3. 从零开始搭建不依赖任何模板亲手构建可调试的整合骨架现在我们抛弃所有“一键生成”的脚手架用最原始的方式一步步搭出一个自带诊断能力的整合环境。目标很明确让第一个查询不仅“能跑”更要“能看、能调、能改”。3.1 最小化依赖清单只留必要项新建 SpringBoot 项目推荐使用 Spring Initializr选择 Spring Web Lombok不要勾选 Mybatis然后手动添加以下依赖!-- Mybatis 核心 -- dependency groupIdorg.mybatis/groupId artifactIdmybatis/artifactId version3.5.14/version /dependency !-- Spring 与 Mybatis 的桥接 -- dependency groupIdorg.mybatis/groupId artifactIdmybatis-spring/artifactId version3.0.3/version /dependency !-- Mybatis Spring Boot Starter真正起自动配置作用 -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version3.0.3/version /dependency !-- 数据库驱动以 H2 内存库为例便于快速验证 -- dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency为什么不用spring-boot-starter-jdbc因为mybatis-spring-boot-starter已经传递依赖了spring-jdbc再加一层反而可能引发版本冲突。H2 数据库的选择是为了彻底规避网络、权限、连接池等外部干扰把问题域聚焦在“整合逻辑”本身。3.2 数据库与实体用最简模型验证映射创建一个内存数据库初始化脚本src/main/resources/schema-h2.sqlCREATE TABLE user ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_name VARCHAR(50) NOT NULL, email VARCHAR(100), created_time DATETIME DEFAULT CURRENT_TIMESTAMP ); INSERT INTO user(user_name, email) VALUES (张三, zhangsanexample.com);对应 Java 实体类User.javaData Builder NoArgsConstructor AllArgsConstructor public class User { private Long id; private String userName; // 注意Java 字段是驼峰数据库是下划线 private String email; private LocalDateTime createdTime; }这里刻意使用user_name数据库与userNameJava的命名差异就是为了验证后续的驼峰映射是否生效。如果映射失败userName字段将永远为 null。3.3 配置文件每一行都是可控开关application.yml内容如下逐行解释其不可省略性# 1. 数据源配置这是整个链条的起点 spring: datasource: url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY-1;DB_CLOSE_ON_EXITFALSE driver-class-name: org.h2.Driver username: sa password: # 2. Mybatis 核心配置显式声明拒绝黑盒 mybatis: # 必须指定 XML 映射文件位置否则 Mapper 不加载 mapper-locations: classpath:mapper/*.xml # 必须开启驼峰映射否则 userName 无法从 user_name 映射 configuration: map-underscore-to-camel-case: true # 可选但强烈建议开启 SQL 日志这是调试的第一道光 configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 3. H2 控制台方便随时查看数据库状态 spring: h2: console: enabled: true path: /h2-console特别强调map-underscore-to-camel-case: true这一行。很多教程把它放在“高级配置”章节但它其实是最基础的生存配置。没有它Mybatis 默认使用ObjectWrapper进行属性匹配而ObjectWrapper对字段名是严格区分大小写的——userName和user_name在它眼里是两个完全无关的字符串。3.4 Mapper 接口与 XML分离但共生的双生体创建UserMapper.javaMapper public interface UserMapper { Select(SELECT * FROM user WHERE id #{id}) User selectById(Long id); // 这个方法将使用 XML 实现用于演示混合使用 User selectByEmail(String email); }创建src/main/resources/mapper/UserMapper.xml?xml version1.0 encodingUTF-8? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespacecom.example.mapper.UserMapper resultMap idUserResultMap typecom.example.domain.User id propertyid columnid/ result propertyuserName columnuser_name/ result propertyemail columnemail/ result propertycreatedTime columncreated_time/ /resultMap select idselectByEmail resultMapUserResultMap SELECT * FROM user WHERE email #{email} /select /mapper注意namespace必须与接口全限定名完全一致id必须与接口方法名完全一致。XML 中的resultMap是为了展示即使开启了驼峰映射对于复杂类型或特殊字段如created_time→createdTime显式声明column和property仍是最佳实践它比依赖全局配置更可靠、更易读。3.5 启动类与测试用最朴素的方式验证Application.java保持最简SpringBootApplication MapperScan(com.example.mapper) // 显式声明扫描路径比 Mapper 更健壮 public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }写一个最简单的测试类UserMapperTest.javaSpringBootTest class UserMapperTest { Autowired private UserMapper userMapper; Test void testSelectById() { User user userMapper.selectById(1L); System.out.println(Query by ID: user); // 观察控制台输出 assertNotNull(user); assertEquals(张三, user.getUserName()); // 验证驼峰映射 } Test void testSelectByEmail() { User user userMapper.selectByEmail(zhangsanexample.com); System.out.println(Query by Email: user); assertNotNull(user); assertEquals(张三, user.getUserName()); } }运行测试。此时你应该在控制台看到清晰的 SQL 日志 Preparing: SELECT * FROM user WHERE id ? Parameters: 1(Long) Columns: ID, USER_NAME, EMAIL, CREATED_TIME Row: 1, 张三, zhangsanexample.com, 2024-05-20 10:30:45.0 Total: 1如果看到Parameters: null或Row: 1, null, ...说明映射失败如果看到Invalid bound statement (not found)说明mapper-locations配置错误或 XML 文件路径不对如果测试直接报NoSuchBeanDefinitionException说明MapperScan路径与实际包名不匹配。提示在开发阶段务必开启StdOutImpl日志。它比 Logback 日志更底层、更直接能第一时间暴露 SQL 准备、参数绑定、结果集解析的全过程。等项目稳定后再切换到 SLF4J 实现。4. 整合层的“暗流”那些配置项背后的真实世界影响当你以为mybatis.mapper-locations只是一个路径字符串时它其实在幕后触发了一整套资源定位、解析、注册的流程。理解这些“暗流”才能在出问题时精准定位到故障点而不是盲目重启或重写配置。4.1mapper-locations的资源解析机制MybatisProperties中的mapperLocations字段类型是Resource[]这意味着它接受 Spring 的ResourceLoader支持的所有路径格式路径写法解析方式适用场景风险提示classpath:mapper/*.xml从 classpath 根路径查找mapper/目录下所有.xml文件最常用推荐若resources目录未被正确标记为 Resources Root文件将找不到classpath*:mapper/**/*.xml使用ClassPathResource的通配符递归扫描多模块项目Mapper 分布在不同 jar 包中性能稍差启动时需遍历所有 jarfile:/opt/config/mapper/*.xml从服务器文件系统绝对路径加载生产环境热更新 Mapper极不推荐安全风险高路径硬编码跨平台问题关键点在于classpath:前缀是 Spring 的约定不是 Mybatis 的。Mybatis 本身不理解classpath:它只接收Resource对象。MybatisAutoConfiguration在创建SqlSessionFactoryBean时会调用ResourcePatternResolver将字符串路径转换为Resource数组。如果路径写错比如classpath:/mapper/*.xml多了一个/ResourcePatternResolver会静默返回空数组导致SqlSessionFactoryBean.setMapperLocations()接收空数组最终没有任何 Mapper 被注册。4.2configuration与configuration-properties的分工mybatis.configuration下的配置项如map-underscore-to-camel-case会直接注入到 Mybatis 的org.apache.ibatis.session.Configuration对象中。而mybatis.configuration-properties则用于加载一个外部的.properties文件其键值对会被注入到Configuration的variables属性中供 XML 中的${}占位符使用。例如你可以创建mybatis-config.propertiesdatabase.typeh2然后在application.yml中mybatis: configuration-properties: classpath:mybatis-config.properties并在 XML 中使用select idselectByType resultTypeUser SELECT * FROM user WHERE database_type ${database.type} /select这种分离设计的意义在于configuration控制 Mybatis 的运行时行为如缓存策略、延迟加载而configuration-properties控制 SQL 的文本内容如表名前缀、分页方言。混淆二者会导致配置无效。4.3MapperScan的扫描原理与性能陷阱MapperScan注解最终会被MapperScannerRegistrar处理。它本质上是一个ImportBeanDefinitionRegistrar在 Spring 容器刷新的早期阶段ConfigurationClassPostProcessor之后扫描指定包路径下的所有接口并为每个接口注册一个MapperFactoryBean。MapperFactoryBean是一个FactoryBean它负责创建 Mapper 接口的代理对象。这个代理对象的核心是MapperProxy它实现了 JDK 动态代理拦截所有接口方法调用并将其转发给SqlSession。这里有一个隐藏的性能陷阱MapperScan的basePackages如果设置得过于宽泛如MapperScan(com.example)Spring 会扫描com.example下所有子包包括com.example.controller、com.example.service即使这些包里根本没有 Mapper 接口。扫描过程涉及大量 I/O读取.class文件和反射检查是否为接口在大型项目中可能导致启动时间增加数百毫秒。最佳实践是精确到 Mapper 接口所在的最小子包。例如所有 Mapper 都在com.example.infrastructure.mapper那就写MapperScan(com.example.infrastructure.mapper)而不是向上提一级。4.4 多数据源场景下的整合裂痕单数据源时MybatisAutoConfiguration的默认逻辑足够健壮。但一旦引入第二个数据源如主库 从库自动配置就会失效。因为MybatisAutoConfiguration的ConditionalOnBean(DataSource.class)只会匹配到第一个被创建的DataSourceBean通常是主数据源而忽略其他数据源。此时你必须手动配置第二个SqlSessionFactory和MapperScannerConfigurer。例如为从库创建SlaveSqlSessionFactoryConfiguration public class MybatisSlaveConfig { Bean Primary // 主数据源的 SqlSessionFactory public SqlSessionFactory masterSqlSessionFactory(Qualifier(masterDataSource) DataSource dataSource) throws Exception { SqlSessionFactoryBean factoryBean new SqlSessionFactoryBean(); factoryBean.setDataSource(dataSource); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources(classpath:mapper/master/*.xml)); return factoryBean.getObject(); } Bean public SqlSessionFactory slaveSqlSessionFactory(Qualifier(slaveDataSource) DataSource dataSource) throws Exception { SqlSessionFactoryBean factoryBean new SqlSessionFactoryBean(); factoryBean.setDataSource(dataSource); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources(classpath:mapper/slave/*.xml)); return factoryBean.getObject(); } }这个过程暴露了自动配置的边界它只为单一、标准的数据源场景服务。任何偏离多数据源、读写分离、分库分表都必须退回到手动配置模式。这也是为什么“入门”必须先理解自动配置的原理——只有知道它在哪条线上画了界你才知道自己该在哪条线外动手。注意Primary注解用于标识默认的SqlSessionFactory。当MapperScan未指定sqlSessionFactoryRef时它会使用Primary标记的SqlSessionFactory。为从库 Mapper 指定专属工厂需在MapperScan中显式引用MapperScan(basePackages com.example.mapper.slave, sqlSessionFactoryRef slaveSqlSessionFactory)。5. 调试与诊断当“整合成功”变成“整合可疑”时如何像侦探一样工作整合完成后的第一周往往是问题集中爆发期。此时你需要的不是重装依赖而是一套系统化的诊断流程。下面是我从某跨平台系统项目中总结出的“四步排障法”专治各种“能编译、能启动、但查不出数据”的疑难杂症。5.1 第一步确认 Spring 容器是否真的加载了 Mapper Bean这是最基础、也最容易被忽略的一步。很多问题的根源是 Mapper 接口根本没被 Spring 管理。操作在ApplicationRunner中注入ApplicationContext打印所有 Mapper 类型的 Bean 名称Component public class MapperChecker implements ApplicationRunner { Override public void run(ApplicationArguments args) throws Exception { String[] beanNames applicationContext.getBeanNamesForType(UserMapper.class); System.out.println(Found UserMapper beans: Arrays.toString(beanNames)); // 正常输出应为Found UserMapper beans: [userMapper] // 如果为空数组则说明 MapperScan 失败 } }如果输出为空立即检查MapperScan的包路径是否与UserMapper实际路径一致UserMapper接口上是否误加了Repository或其他 Spring 注解Mapper和MapperScan是互斥的不能同时用pom.xml中是否意外引入了mybatis-spring的旧版本如 1.x与 SpringBoot 3.x 不兼容5.2 第二步验证 SqlSessionFactory 是否正常创建SqlSessionFactory是 Mybatis 的核心工厂它创建失败一切皆空。操作在application.yml中临时开启 Mybatis 的 DEBUG 日志logging: level: org.mybatis.spring.SqlSessionFactoryBean: DEBUG org.springframework.beans.factory.support.DefaultListableBeanFactory: DEBUG启动应用观察日志中是否有类似Creating shared instance of singleton bean sqlSessionFactory ... Returning cached instance of singleton bean dataSource ... SqlSessionFactoryBean sqlSessionFactory initialized successfully.如果看到Creating shared instance...但没有initialized successfully说明SqlSessionFactoryBean的afterPropertiesSet()方法抛出了异常。此时异常堆栈通常会指向DataSource初始化失败、XML 文件解析错误如 DTD 地址不可达、或typeAliasesPackage指向的包不存在。5.3 第三步检查 SQL 日志是否真实输出这是判断“整合是否生效”的黄金标准。如果控制台看不到任何 Preparing日志说明请求根本没走到 Mybatis 层。操作确保mybatis.configuration.log-impl配置正确并在测试方法中加入断点观察UserMapper的代理对象类型Test void debugMapperProxy() { System.out.println(Mapper type: userMapper.getClass().getName()); // 正常输出应为Mapper type: com.sun.proxy.$ProxyXX // 如果是 com.example.mapper.UserMapper说明它没被代理即未被 Spring 管理 }如果userMapper是接口类型而非代理类说明MapperScannerConfigurer未生效回到第一步。5.4 第四步逐层剥离定位静默失败点当以上三步都“看起来正常”但业务逻辑仍返回 null 时问题往往出在映射层。此时采用“最小化还原法”写一个最简 SQLSELECT id, user_name FROM user WHERE id 1排除复杂字段干扰。用Select直接写死 SQL绕过 XML确认是 XML 解析问题还是映射问题。检查resultMap的type必须是实体类的全限定名不能是简单类名。启用 Mybatis 的useGeneratedKeys对于插入操作确保主键回填正常这是事务和缓存的基础。我曾在某图像处理Demo项目中遇到一个经典案例User实体类用了 Lombok 的Data但Data默认不为LocalDateTime字段生成EqualsAndHashCode导致 Mybatis 的二级缓存因hashCode不一致而失效同一个 ID 查询两次第二次返回 null。最终通过开启mybatis.configuration.cache-enabledfalse临时关闭缓存确认了问题根源。最后分享一个小技巧在application.yml中添加debug: trueSpringBoot 会输出所有自动配置的报告其中包含MybatisAutoConfiguration的matched匹配成功或excluded被排除状态。这是判断自动配置是否触发的终极依据比任何日志都权威。