技术博客
首页 所有文章 标签 分类 关于
技术博客

目录

Spring-Boot-MyBatis-报-Invalid-bean-definition-如何排查解决

 收录于 实战源码 实战 Swift
   约 3134 字   预计阅读 7 分钟 
https://bing.ee123.net/img/rand?artid=151725172

Spring Boot + MyBatis 报 Invalid bean definition 如何排查解决

https://i-blog.csdnimg.cn/direct/46b078b160f94627aa5dc72b87b935b1.jpeg#pic_center

网罗开发 （小红书、快手、视频号同名）

  大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

前言

一段非常常见又让人头大的问题：Spring Boot 项目启动时报 Invalid bean definition with name 'userMapper' ... Invalid value type for attribute 'factoryBeanObjectType': java.lang.String。你已经把网上的各种注解检查过了，最后发现把 mybatis-spring-boot-starter 升级到 3.0.3 后问题消失——这是对的。下面把问题的本质、常见根因、排查流程和彻底可运行的 Demo（可直接跑）整理成一篇易读的技术博客，方便你理解和复用。

摘要

这个错误通常不是因为写错 @Mapper 注解或 Mapper 接口方法，而是运行时类路径上的 MyBatis / MyBatis Spring Boot Starter 与当前 Spring Boot 版本不兼容，导致 Spring 在处理 MapperFactoryBean 的 factoryBeanObjectType 属性时拿到了错误的类型（字符串），从而触发校验失败。解决办法主要是：对齐依赖版本（升级/降级 mybatis starter）或移除冲突的旧版本，并用 mvn dependency:tree 检查冲突。

为什么会发生

Spring 在处理 Mapper 接口时会为每个接口注册一个 MapperFactoryBean（或者某种 FactoryBean），Spring 会读取该 FactoryBean 的元信息（factoryBeanObjectType）来做 bean 定义校验。如果类路径中某个库版本不对，或 MapperFactoryBean 的实现不同（返回了字符串而非 Class<?>），Spring 会在启动阶段判断类型不符合而抛出异常。

常见导致这种问题的根源包括：

  • mybatis-spring-boot-starter 的版本与 Spring Boot 版本不匹配（例如 starter 包里对 Spring API 的使用方式与当前 Spring 版本期望不一致）。
  • 项目中同时存在多个不同版本的 MyBatis / MyBatis-Spring / mybatis-spring-boot-starter（jar 冲突）。
  • 误把 mapper 的实现类或注解写得奇怪，导致生成的 bean 元数据异常（不常见，相对概率小）。

你遇到的场景：把 mybatis-spring-boot-starter 从 3.0.0 改为 3.0.3（starter 内含 MyBatis 3.5.13）后问题解决，说明确实是版本兼容/bug 问题。

排查步骤

当你看到类似错误时，推荐按下面步骤排查，能快速定位问题：

  1. 查看完整异常栈，定位是哪个 Bean（userMapper）和哪个 class file。

  2. 执行 mvn dependency:tree，查找 mybatis / mybatis-spring / mybatis-spring-boot-starter 是否出现多个版本（特别是传递依赖冲突）。

    mvn dependency:tree | grep -i mybatis

  3. 检查 pom.xml 中是否显式或隐式引入了旧版 mybatis（通过其他 starter/库引入）。

  4. 尝试把 mybatis starter 升级到兼容版本（比如 3.0.3），或使用 Spring Boot 推荐的 starter 版本。

  5. 清理本地仓库并重建（有时候旧 jar 被缓存）：

    mvn -U clean package
mvn dependency:purge-local-repository -DmanualInclude="org.mybatis.spring.boot:mybatis-spring-boot-starter"

  6. 如果仍有问题，临时把 @Mapper 换成 @MapperScan + @Mapper 或者用 XML 配置试试，以确认是自动装配器的问题还是 Mapper 本身。

  7. 看是否有重复扫描：多个 @MapperScan 或者同时在 spring.factories 中被重复注册也会出问题。

可运行 Demo

基于 Spring Boot + MyBatis 注解方式，使用 H2 内存数据库，保证“开箱即跑”

下面是一个最小可运行的示例，确认环境是兼容的：Spring Boot（3.x 系列）+ mybatis-spring-boot-starter:3.0.3 + Java 17。

把下面目录结构放到一个 Maven 项目里即可运行。

demo-mybatis/
├─ pom.xml
├─ src/
   ├─ main/
      ├─ java/com/example/demo/
      │  ├─ DemoApplication.java
      │  ├─ mapper/UserMapper.java
      │  └─ model/User.java
      └─ resources/
         ├─ application.properties
         └─ schema.sql

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="
           http://maven.apache.org/POM/4.0.0
           https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.6</version>
    <relativePath/>
  </parent>

  <groupId>com.example</groupId>
  <artifactId>demo-mybatis</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <properties>
    <java.version>17</java.version>
  </properties>

  <dependencies>
    <!-- MyBatis Spring Boot Starter （注意版本） -->
    <dependency>
      <groupId>org.mybatis.spring.boot</groupId>
      <artifactId>mybatis-spring-boot-starter</artifactId>
      <version>3.0.3</version>
    </dependency>

    <!-- Spring Web（方便启动并观察） -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- H2 内存数据库，方便 demo -->
    <dependency>
      <groupId>com.h2database</groupId>
      <artifactId>h2</artifactId>
      <scope>runtime</scope>
    </dependency>

    <!-- 支持 JDBC -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-jdbc</artifactId>
    </dependency>

    <!-- 测试 -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

application.properties（src/main/resources/application.properties）

spring.datasource.url=jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;MODE=MYSQL
spring.datasource.username=sa
spring.datasource.password=
spring.datasource.driver-class-name=org.h2.Driver

# MyBatis 配置（若使用 XML mapper，可在这里配置 locations）
mybatis.mapper-locations=classpath*:mapper/*.xml
mybatis.type-aliases-package=com.example.demo.model

这里我们用注解方式的 Mapper，因此 mapper-locations 可以不用配置，但保留也没问题。

schema.sql（src/main/resources/schema.sql）

Spring Boot 会自动在运行时执行这个 SQL（H2 数据库），创建表。

CREATE TABLE users (
  id BIGINT PRIMARY KEY,
  name VARCHAR(100)
);

实体类 User.java（src/main/java/com/example/demo/model/User.java）

package com.example.demo.model;

public class User {
    private Long id;
    private String name;

    public User() {}
    public User(Long id, String name) { this.id = id; this.name = name; }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    @Override
    public String toString() {
        return "User{id=" + id + ", name='" + name + "'}";
    }
}

Mapper 接口 UserMapper.java（src/main/java/com/example/demo/mapper/UserMapper.java）

package com.example.demo.mapper;

import com.example.demo.model.User;
import org.apache.ibatis.annotations.Insert;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Select;

@Mapper
public interface UserMapper {

    @Insert("INSERT INTO users(id, name) VALUES(#{id}, #{name})")
    void insert(User user);

    @Select("SELECT id, name FROM users WHERE id = #{id}")
    User findById(Long id);
}

注意：使用 @Mapper 注解或在启动类上使用 @MapperScan("...mapper") 都可以。这里用了 @Mapper，简单明了。

启动类 DemoApplication.java（src/main/java/com/example/demo/DemoApplication.java）

package com.example.demo;

import com.example.demo.mapper.UserMapper;
import com.example.demo.model.User;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @Bean
    CommandLineRunner runner(UserMapper userMapper) {
        return args -> {
            System.out.println("Inserting a user...");
            userMapper.insert(new User(1L, "Alice"));
            User u = userMapper.findById(1L);
            System.out.println("Found user: " + u);
        };
    }
}

运行方式

  1. 把项目代码放好，执行：

    mvn -U clean package
mvn spring-boot:run

  2. 启动日志中你应该看到类似：

    Inserting a user...
Found user: User{id=1, name='Alice'}

如果能成功运行，说明 mybatis-spring-boot-starter:3.0.3 与 Spring Boot 3.1.6 + Java 17 是兼容的（demo 用 H2 避免外部数据库问题）。

其他可能的坑与补充建议

  • JAR 冲突：如果你有别的依赖（例如旧版 mybatis-spring、shaded 的 mybatis），请通过 mvn dependency:tree 找出并 exclusion 掉。

  • Mapper 被重复扫描：不要同时用 @Mapper 和 @MapperScan 再加上自动装配的扫描路径导致重复注册。

  • Spring 版本与 starter 版本不匹配：使用 Spring Boot 的 dependencyManagement 推荐版本，尽量不要手动随意指定各个库版本，除非你很确定兼容性。

  • IDE 的编译缓存：遇到奇怪的 Class/Bean 问题，建议 mvn clean、Invalidate Caches & Restart（IDEA），并再次打包运行。

  • 查看 Version.class 来源：如果怀疑加载了错误版本的 MyBatis，可以在启动代码中打印实现类的 jar 来源：

    System.out.println(org.apache.ibatis.session.SqlSessionFactory.class.getProtectionDomain().getCodeSource().getLocation());

    这样能直观看到哪个 jar 被加载。

总结

  • 错误 Invalid value type for attribute 'factoryBeanObjectType': java.lang.String 很大概率是依赖版本/兼容性问题导致 Spring 在解析 Mapper FactoryBean 时读到不符合预期的元数据格式。
  • 最常见、也最有效的解决办法是：把 mybatis-spring-boot-starter 升级到与 Spring Boot 兼容的版本（比如 3.0.3），或者清理掉冲突的旧版本。
  • 通过 mvn dependency:tree、打印 class 来源、清理缓存、对齐 starter 版本可以快速定位并解决问题。
  • 我在文章里给出一个可运行 Demo（Spring Boot + MyBatis 注解 + H2），可以拿来验证你的本地环境是否配置正确。
更新于 2025-09-15
 后端, Spring, Mybatis, Boot
返回 | 主页