解决 Spring Boot 中 LocalSessionFactoryBuilder 方法缺失问题
2025-03-19 04:51:21
Spring Boot 项目中 LocalSessionFactoryBuilder.addAttributeConverter 方法缺失问题解决
这篇博客文章帮你搞定 Spring Boot 项目启动时遇到的 org.springframework.orm.hibernate5.LocalSessionFactoryBuilder.addAttributeConverter method does not exists 错误。 我们会先看看问题出在哪里，然后给出几种可行的解决办法，还会提供代码和操作步骤，让你轻松应对。
一、 问题
Spring Boot 应用启动时，控制台报了类似下面的错误：
An attempt was made to call a method that does not exist. The attempt was made from the following location:
org.springframework.orm.hibernate5.LocalSessionFactoryBuilder.scanPackages(LocalSessionFactoryBuilder.java:365)
The following method did not exist:
'void org.springframework.orm.hibernate5.LocalSessionFactoryBuilder.addAttributeConverter(java.lang.Class)'
错误信息还指出了 LocalSessionFactoryBuilder 类是从哪里加载的，以及调用的方法所属的类和类层次结构。简单来说，就是程序试图调用一个不存在的方法。
二、 问题原因分析
这个问题通常是由于 Hibernate 和 Spring ORM 版本不兼容导致的。 更确切地说，Spring ORM 的版本中，LocalSessionFactoryBuilder类缺少被调用的 addAttributeConverter(java.lang.Class)方法，或者版本不对。
在pom.xml文件中可以看到，Spring Boot版本为3.4.2,Spring ORM 版本是 6.2.2， Hibernate Core 版本是 6.6.5.Final。
spring-boot-starter-parent 3.x.x 暗示可能使用jakarta相关的包，spring-orm包和hibernate包版本需要对应，可能是因为版本冲突，LocalSessionFactoryBuilder 试图去调用旧版本的addAttributeConverter`方法。
三、 解决方案
解决这个问题的关键在于确保 Spring ORM 和 Hibernate 版本协调一致。 下面列出几种可行的解决办法：
1. 统一 Spring Framework 和 Hibernate 版本
最简单的解决办法是确保整个项目使用统一的 Spring Framework 版本, 并与 Hibernate 版本对应。我们可以利用 Spring Boot 的依赖管理功能。
原理: Spring Boot 的 spring-boot-starter-parent 或 spring-boot-dependencies 已经帮你管理了一些常用库的版本。如果你不显式指定 spring-orm 的版本，Spring Boot 会自动选择一个合适的版本, 减少了冲突的可能性。
操作步骤：
- 修改
pom.xml： 移除spring-orm的显式版本声明。 - 删除显示声明hibernate依赖。
- 添加
spring-boot-starter-data-jpa依赖,并且去除<version>信息。 - maven强制刷新依赖。
<!-- 移除 -->
<!-- <dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-orm</artifactId>
<version>6.2.2</version>
</dependency> -->
<!-- 删除此项 -->
<dependency>
<groupId>jakarta.persistence</groupId>
<artifactId>jakarta.persistence-api</artifactId>
<version>3.2.0</version>
</dependency>
<!-- 添加 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
maven 刷新:
执行 mvn clean install -U。“-U” 强制更新snapshot。
或者在idea 等IDE 右键项目 -> Maven -> Reload project
Spring Boot 会选择兼容的版本。 这通常能解决大多数版本冲突问题。
2. 降级 Hibernate Core 版本 (不推荐,仅适用特定老项目)
如果你的项目因为某些原因必须使用老版本Hibernate,，可以尝试降级 Hibernate Core 的版本。
原理: 让Hibernate core 版本降级，和老版本的 Spring ORM 里的 LocalSessionFactoryBuilder 兼容。
注意：
- 请谨慎进行此操作。过时的Hibernate core 会导致新版本spring boot 部分功能不能用。
操作步骤：
- 查找兼容版本： 查找与你的 Spring ORM 版本（例如 6.2.2）兼容的 Hibernate Core 版本。可以通过查找旧版本文档找到版本匹配信息。
- 修改
pom.xml： 修改 Hibernate Core 的版本：- 添加hibernate-core依赖到pom，并且写版本到兼容版本。
- maven强制刷新依赖。
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<version>找到一个兼容版本号,比如 5.6.x.Final </version>
</dependency>
3. 使用 Spring Boot 管理 Hibernate 版本 (推荐)
可以让Spring boot 来管理 hibernate, 避免自己去寻找 hibernate 版本.
原理: 让 Spring Boot Data JPA 来帮你处理这些事情，减少配置，降低出错概率。
操作步骤：
- 移除显式的 Hibernate 依赖: 移除你添加的Hibernate依赖(类似上面方案的
<dependency>)。 - 使用
spring-boot-starter-data-jpa: 确保你的pom.xml包含了spring-boot-starter-data-jpa依赖：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
- maven强制刷新依赖.
spring-boot-starter-data-jpa 会自动引入合适的 Hibernate 版本，与 Spring Boot 和 Spring ORM 兼容。
4. 使用jakarta命名空间版本
检查你用到的所有库，是不是用了旧的javax命名空间，改成 jakarta 命名空间版本。
尤其当 spring boot 版本大于等于3时。
操作步骤
- 将全部
javax替换成jakarta。例如javax.persistence换成jakarta.persistence。 - maven强制刷新依赖.
选择合适的方案
- 一般情况: 优先选方法1 或者方法 3 (让 Spring Boot 来管理版本)。 简单、省事、不容易出错。
- 老项目，或者有特殊版本要求: 可以试试方法 2 (手动降级)，要小心。
- 使用了 jakarta相关的依赖: 可以尝试方法4.
不管用哪种方法，改完 pom.xml 后记得在IDE（如 IntelliJ IDEA 或 Eclipse）中刷新 Maven 依赖，或者执行 mvn clean install 来更新项目依赖。
搞定依赖问题， 应该就能正常启动你的 Spring Boot 应用了！ 如果你还有其他疑问，或者遇到了其他问题，可以在下方留言，我会尽力帮忙！
