给新模块加了个 @MapperScan,启动崩了,最后发现跟 MapperScan 没关系

0 阅读6分钟

一个很普通的需求

我们项目加了一个新模块,叫 fenmi-job,用来放定时任务。任务要读写数据库,自然要接 Mapper。

我在模块里新建了一个 JobConfig,加上 @MapperScan:

@Configuration
@MapperScan("com.fenmi.job.mapper")
public class JobConfig {
}

本地跑,启动失败。控制台一片红:

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 之后问题直接消失。

<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 之后,有一次在别的服务里也偶尔见到过类似的报错,当时被当成了偶发问题忽略了。

所以我现在做事会多一个动作:遇到"我新加的东西出错"时,先问一句"这个错在我改动之前存在吗"。 验证方法很简单——把改动回滚,看错还在不在。如果还在,那跟我没关系,去找环境问题。

简单,但真的省时间。

版本修好之后,又来了第二个坑

改了版本,启动过了。我松了口气,然后运行任务,报:

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 是这么写的:

@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 挪到主启动类的扫描范围内。

package com.fenmi.admin.job;   // 挪到 admin 模块的包下

方案二:把 @MapperScan 直接写在主启动类上,一次性写全。

@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 客户端接口:

@FeignClient(name = "order-service")
public interface OrderClient {
    @GetMapping("/order/{id}")
    OrderVO get(@PathVariable Long id);
}

或者有普通的 Service 接口:

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 会帮你改。

@MapperScan(basePackageClasses = SysJobMapper.class)   // 重构安全

如果只有一个 Mapper,我更推荐这种。

3. @MapperScan 和 @Mapper 混用

@Mapper 是标注在单个接口上的,配合 @SpringBootApplication 所在包的自动扫描(MyBatis 的 AutoConfiguredMapperScannerRegistrar)。

@MapperScan 是批量扫描。

两个一起用不冲突,但会造成"有些 Mapper 靠 @Mapper 注册,有些靠 @MapperScan 注册"的混乱局面。以后有人的 Mapper 注不进去,你根本不知道是哪个机制该负责。

我们的规范是:统一用 @MapperScan,禁止在接口上加 @Mapper。 这样 Mapper 的注册只有一条路径,出问题好查。

最后

两个坑叠在一起的教训就是:报错信息指向的地方,不一定是问题发生的地方。

第一个坑,报错指向我新写的 Mapper,问题是全局依赖版本。 第二个坑,报错指向 Mapper 未注册,问题是包扫描范围。

如果我只是盯着报错的那一行代码改,永远改不出来。

现在我的排查套路是这样的:

  1. 先把报错信息里的关键词摘出来(比如 factoryBeanObjectType),搜一下它在框架里是什么。
  2. 问自己"这个错在我改动之前存在吗",想办法回滚验证。
  3. 看 Bean 的注册来源,而不是看代码。

第 3 条特别管用。Spring 的问题你光看代码是看不出来的,因为代码和实际装配结果之间隔着好几层条件判断。看一下 BeanDefinition 到底是谁注册的、什么类型,比读一百行代码强。