升级至Spring Boot 3.1.0后，无法初始化@Repository注解类

问题背景 #

我们将Spring从2.7.0版本升级至3.x，最初尝试升级到Spring 3.0.x，但因Spring的Bean初始化bug切换到3.1.0版本。已修复所有编译错误：将javax替换为jakarta、升级Spring Security配置等，但应用启动时在初始化阶段崩溃。

日志片段 #

[background-preinit] Version.<clinit>:21 - HV000001: Hibernate Validator 8.0.0.Final
[main] StartupInfoLogger.logStarting:51 - Starting ContentApplication using Java 17.0.2 with PID 3564
[main] SpringApplication.logStartupProfileInfo:639 - The following 1 profile is active: "local"
[main] RepositoryConfigurationDelegate.registerRepositoriesIn:138 - Bootstrapping Spring Data JPA repositories in DEFAULT mode.
[main] RepositoryConfigurationDelegate.registerRepositoriesIn:208 - Finished Spring Data repository scanning in 550 ms. Found 37 JPA repository interfaces.
[main] TomcatWebServer.initialize:108 - Tomcat initialized with port(s): 8080 (http)
[main] ServletWebServerApplicationContext.prepareWebApplicationContext:291 - Root WebApplicationContext: initialization completed in 5214 ms
[main] Version.logVersion:44 - HHH000412: Hibernate ORM core version 6.2.2.Final
[main] Environment.<clinit>:191 - HHH000406: Using bytecode reflection optimizer
[main] BytecodeProviderInitiator.buildBytecodeProvider:53 - HHH000021: Bytecode provider name : bytebuddy
[main] DialectFactoryImpl.logSelectedDialect:93 - HHH035001: Using dialect: org.hibernate.dialect.SQLServerDialect, version: 12.0
[main] QueryEnhancerFactory.<clinit>:47 - Hibernate is in classpath; If applicable, HQL parser will be used.
ANTLR Tool version 4.10.1 used for code generation does not match the current runtime version 4.9.3
ANTLR Runtime version 4.10.1 used for parser compilation does not match the current runtime version 4.9.3
[main] TomcatStarter.onStartup:60 - Error starting Tomcat context.

具体错误栈 #

Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'userRepository' defined in packagename.UserRepository defined in @EnableJpaRepositories declared on JpaRepositoriesRegistrar.EnableJpaRepositoriesConfiguration: null
Caused by: java.lang.ExceptionInInitializerError: null
    at org.springframework.data.jpa.repository.query.HqlQueryParser.parseQuery(HqlQueryParser.java:48)
    at org.springframework.data.jpa.repository.query.HqlQueryParser.parse(HqlQueryParser.java:63)
    at org.springframework.data.jpa.repository.query.JpaQueryParserSupport$ParseState.lambda$new$0(JpaQueryParserSupport.java:182)
--------------------------------------------------------------------------------------------------------------------------------------
Caused by: java.lang.UnsupportedOperationException: java.io.InvalidClassException: org.antlr.v4.runtime.atn.ATN; Could not deserialize ATN with version 4 (expected 3).
    at org.antlr.v4.runtime.atn.ATNDeserializer.deserialize(ATNDeserializer.java:187)
    at org.springframework.data.jpa.repository.query.HqlLexer.<clinit>(HqlLexer.java:1314)
    ... 222 common frames omitted
Caused by: java.io.InvalidClassException: org.antlr.v4.runtime.atn.ATN; Could not deserialize ATN with version 4 (expected 3).
    ... 224 common frames omitted   

问题根源 #

日志明确提示ANTLR工具版本4.10.1与运行时版本4.9.3不匹配，导致Spring Data JPA的HQL解析器在初始化时，无法反序列化ATN（增强型转换网络）结构——生成时用的是版本4的ATN，但运行时预期是版本3，最终触发InvalidClassException，进而导致userRepository Bean创建失败。

解决方案 #

1. 统一ANTLR版本 #

通过依赖管理强制将项目中的antlr4-runtime版本统一为4.10.1（与生成工具版本匹配）：

Maven配置（pom.xml）

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.antlr</groupId>
            <artifactId>antlr4-runtime</artifactId>
            <version>4.10.1</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle配置（build.gradle）

configurations.all {
    resolutionStrategy.force 'org.antlr:antlr4-runtime:4.10.1'
}

2. 清理并重新构建项目 #

执行清理和构建命令，确保新的依赖生效：

• Maven：mvn clean install
• Gradle：./gradlew clean build

3. 验证依赖树 #

可以通过以下命令检查ANTLR版本是否已统一：

• Maven：mvn dependency:tree | grep antlr
• Gradle：./gradlew dependencies | grep antlr

内容的提问来源于stack exchange，提问作者Cristian