一个很普通的需求
我们项目加了一个新模块,叫 fenmi-job,用来放定时任务。任务要读写数据库,自然要接 Mapper。
我在模块里新建了一个 JobConfig,加上 @MapperScan:
java
@Configuration
@MapperScan("com.fenmi.job.mapper")
public class JobConfig {
}
本地跑,启动失败。控制台一片红:
ruby
org.springframework.beans.factory.BeanDefinitionStoreException:
Invalid bean definition with name 'sysJobMapper' defined in file
[/D:/workspace/fenmi-job/target/classes/com/fenmi/job/mapper/SysJobMapper.class]:
Invalid value type for attribute 'factoryBeanObjectType': java.lang.String
我第一反应:@MapperScan 路径写错了?
检查了一遍,com.fenmi.job.mapper 这个包确实存在,SysJobMapper 确实在里面。没毛病。
那是不是 @MapperScan 的位置不对------它得写在能被扫描到的配置类上?检查了,包路径没问题。
于是我开始了一轮"瞎改":
- 把
@MapperScan挪到启动类上------没用 - 把
@MapperScan删掉,改成每个 Mapper 接口上加@Mapper------还是同样的错 - 改成
@MapperScan(basePackages = {...}, sqlSessionFactoryRef = ...)------报错一样
改到后来我意识到一件事:报错的措辞很怪。
它说的是 Invalid value type for attribute 'factoryBeanObjectType': java.lang.String。
注意,它不是说"找不到 Mapper",也不是说"扫描路径无效"。它说的是------某个属性的值类型不对,期望的是别的类型,实际给的是 String。
这个词 factoryBeanObjectType 我有点印象,是 Spring 里 FactoryBean 的一个属性。既然是"类型不对",那大概率不是我的配置问题,而是某个组件返回的类型和框架期望的不一致。
顺着这个思路一查,破案了。
真正的根因:版本不兼容
factoryBeanObjectType 这个属性是 AbstractBeanDefinition 上的。在 Spring Framework 5.x 时代,它是个 String;Spring 6.0 之后,Spring 把它改成了 Class<?>。
而 MyBatis-Plus 的 MybatisMapperFactoryBean 在创建 BeanDefinition 的时候,会把这个属性设成 Mapper 接口的全限定名字符串。
老版本的 MyBatis-Plus 按 Spring 5 的约定返回 String,Spring 6 期望 Class,类型对不上,于是抛 BeanDefinitionStoreException。
我们项目的版本是:
spring-boot 3.2.x
mybatis-plus-boot-starter 3.5.2
3.5.2 这个版本还停留在 Spring 5 的适配期。升到 3.5.3.x 之后问题直接消失。
xml
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>3.5.5</version>
</dependency>
从 Spring Boot 3 升级上来的人,这个坑几乎踩一遍。 而且它的报错信息非常有误导性------它会指向你新加的那个 Mapper,让你以为是自己的配置写错了,实际上是整个项目的依赖版本没跟上。
但这个坑有个很值得反思的地方
我在排查的时候,浪费了很多时间在"我新加的这个模块"上。
因为我做了一个假设:"代码是我刚写的,问题一定在我刚写的东西里。"
这个假设在 90% 的情况下是对的,但这一次错了。新加模块这个动作,只是触发了问题------因为新模块是第一个用 MyBatis 的地方,如果不加这个模块,老代码跑得好好的,问题也不会暴露。
其实更早的时候是有信号的。我们升级 Spring Boot 3 之后,有一次在别的服务里也偶尔见到过类似的报错,当时被当成了偶发问题忽略了。
所以我现在做事会多一个动作:遇到"我新加的东西出错"时,先问一句"这个错在我改动之前存在吗"。 验证方法很简单------把改动回滚,看错还在不在。如果还在,那跟我没关系,去找环境问题。
简单,但真的省时间。
版本修好之后,又来了第二个坑
改了版本,启动过了。我松了口气,然后运行任务,报:
bash
Field sysJobMapper in com.fenmi.job.service.SysJobService required a bean
of type 'com.fenmi.job.mapper.SysJobMapper' that could not be found.
好家伙。启动过了,但 Mapper 没注册进去。
这次的根因确实在 @MapperScan 上了。
我们用的是多模块 + 多数据源 的结构,启动类在 fenmi-admin 模块,fenmi-job 是它依赖的一个子模块。
@MapperScan 我加在了 fenmi-job 里的 JobConfig 上。理论上没问题------JobConfig 也在 com.fenmi 包下,会被主启动类的 @SpringBootApplication 扫到。
但是,JobConfig 被扫到了,不代表 @MapperScan 生效了。因为 @MapperScan 是一个 @Import 注解,它要生效,承载它的类必须被当作配置类处理。
我的 JobConfig 是这么写的:
java
@Configuration
@MapperScan("com.fenmi.job.mapper")
public class JobConfig {
// 空的
}
这个写法本身没错。问题出在包路径上。
主启动类在 com.fenmi.admin 包下,@SpringBootApplication 默认只扫 com.fenmi.admin 及其子包。而 JobConfig 在 com.fenmi.job.config 下------压根没被扫到。
那为什么第一个坑里"启动崩"的时候,它又被处理了呢?
因为那时候 MyBatis-Plus 的自动配置在扫 Mapper(它有自己的扫描逻辑,扫的是 @MapperScan 声明的包,或者默认扫启动类所在包),所以 SysJobMapper 被创建了 BeanDefinition,只是定义有问题才报错。而修改版本之后,这个 Mapper 能正常创建了,@MapperScan 失效的问题才暴露出来。
修法有两个:
方案一:把 JobConfig 挪到主启动类的扫描范围内。
java
package com.fenmi.admin.job; // 挪到 admin 模块的包下
方案二:把 @MapperScan 直接写在主启动类上,一次性写全。
java
@SpringBootApplication
@MapperScan({
"com.fenmi.admin.mapper",
"com.fenmi.job.mapper",
"com.fenmi.business.mapper"
})
public class FenmiAdminApplication {
public static void main(String[] args) {
SpringApplication.run(FenmiAdminApplication.class, args);
}
}
我们最后选了方案二。理由很简单------Mapper 的扫描路径集中在一处,一眼能看全。 分散在各个模块的 @MapperScan 里,以后加模块很容易漏。
@MapperScan 还有几个容易踩的点
顺手把我在 @MapperScan 上踩过的其他坑也列一下。
1. 扫描包太宽,扫到了不该扫的接口
@MapperScan("com.fenmi") 这种写法很危险。它会把 com.fenmi 下所有接口都当成 Mapper 处理。
比如你有 Feign 客户端接口:
java
@FeignClient(name = "order-service")
public interface OrderClient {
@GetMapping("/order/{id}")
OrderVO get(@PathVariable Long id);
}
或者有普通的 Service 接口:
java
public interface OrderService {
void process(Long id);
}
这些接口被 MyBatis 当成 Mapper 处理后,会生成一堆诡异的 Mapped Statements collection does not contain value for ...,或者启动直接报方法找不到。
建议:Mapper 放在独立的 xxx.mapper 包下,@MapperScan 精确扫到这一层,别图省事扫父包。
2. basePackages 和 basePackageClasses 该选哪个
basePackages 是字符串,写错了编译器不报错,运行时才发现。 basePackageClasses 传的是类,重构的时候 IDE 会帮你改。
java
@MapperScan(basePackageClasses = SysJobMapper.class) // 重构安全
如果只有一个 Mapper,我更推荐这种。
3. @MapperScan 和 @Mapper 混用
@Mapper 是标注在单个接口上的,配合 @SpringBootApplication 所在包的自动扫描(MyBatis 的 AutoConfiguredMapperScannerRegistrar)。
@MapperScan 是批量扫描。
两个一起用不冲突 ,但会造成"有些 Mapper 靠 @Mapper 注册,有些靠 @MapperScan 注册"的混乱局面。以后有人的 Mapper 注不进去,你根本不知道是哪个机制该负责。
我们的规范是:统一用 @MapperScan,禁止在接口上加 @Mapper。 这样 Mapper 的注册只有一条路径,出问题好查。
最后
两个坑叠在一起的教训就是:报错信息指向的地方,不一定是问题发生的地方。
第一个坑,报错指向我新写的 Mapper,问题是全局依赖版本。 第二个坑,报错指向 Mapper 未注册,问题是包扫描范围。
如果我只是盯着报错的那一行代码改,永远改不出来。
现在我的排查套路是这样的:
- 先把报错信息里的关键词 摘出来(比如
factoryBeanObjectType),搜一下它在框架里是什么。 - 问自己"这个错在我改动之前存在吗",想办法回滚验证。
- 看 Bean 的注册来源,而不是看代码。
第 3 条特别管用。Spring 的问题你光看代码是看不出来的,因为代码和实际装配结果之间隔着好几层条件判断。看一下 BeanDefinition 到底是谁注册的、什么类型,比读一百行代码强。