Spring Boot 3迁移至Native Image时遇PersistentEntities代码生成异常

问题背景 #

我们有一个已上线的Spring Boot 3.1.0服务，计划在GCP中以Native Image方式运行。服务依赖Spring Cloud GCP 4.4.0（包含Datastore、Pub/Sub等组件），添加GraalVM构建工具插件后，无数据库依赖的小型服务可正常编译运行，但本服务在AOT编译阶段抛出如下异常：

Caused by: java.lang.IllegalArgumentException: Code generation does not support org.springframework.data.mapping.context.PersistentEntities

经排查该异常由GCP Datastore库间接依赖引发，尝试更换GCP依赖版本、升级Spring Data均未解决问题。

解决方案 #

1. 升级Spring Cloud GCP版本 #

切换到Spring Cloud GCP 4.5.0及以上版本（如4.5.1），该版本针对Spring Boot 3.1的AOT编译适配做了修复，解决了Datastore相关的PersistentEntities代码生成问题。修改build.gradle中的依赖平台：

implementation platform("com.google.cloud:spring-cloud-gcp-dependencies:4.5.1")

2. 显式声明Spring Data Commons依赖 #

确保Spring Data Commons版本与Spring Boot 3.1.0完全匹配（对应版本为3.1.0），避免依赖冲突导致AOT处理异常：

implementation group: 'org.springframework.data', name: 'spring-data-commons', version: '3.1.0'

3. 添加Native Image反射提示 #

如果升级版本后仍存在问题，为PersistentEntities添加反射访问提示，可通过两种方式实现：

• 方式一：创建反射配置文件
  在src/main/resources/META-INF/native-image/com.google.cloud/spring-cloud-gcp-data-datastore/reflect-config.json中添加：

  [
    {
      "name": "org.springframework.data.mapping.context.PersistentEntities",
      "allDeclaredConstructors": true,
      "allPublicConstructors": true,
      "allDeclaredMethods": true,
      "allPublicMethods": true,
      "allDeclaredFields": true,
      "allPublicFields": true
    }
  ]
  

• 方式二：使用Spring注解
  在项目配置类上添加@NativeHint：

  import org.springframework.aot.hint.annotation.NativeHint;
  import org.springframework.aot.hint.AccessBits;
  import org.springframework.context.annotation.Configuration;
  
  @Configuration
  @NativeHint(
      types = @org.springframework.aot.hint.annotation.TypeHint(
          type = org.springframework.data.mapping.context.PersistentEntities.class,
          access = AccessBits.ALL
      )
  )
  public class NativeImageConfiguration {
  }
  

4. 升级GraalVM Build Tools插件 #

将当前的org.graalvm.buildtools.native插件版本从0.9.20升级到最新稳定版（如0.10.0），新版本对Spring Boot 3.1的AOT编译支持更完善：

id 'org.graalvm.buildtools.native' version '0.10.0'

5. 排除不必要的自动配置（可选） #

如果服务未使用Datastore的全部功能，可以排除对应的自动配置类以减少AOT编译的复杂度：

@SpringBootApplication(exclude = {DatastoreDataAutoConfiguration.class})

注意：需确认服务确实不需要该自动配置的功能后再操作

验证步骤 #

修改完成后，执行以下命令重新编译Native Image：

./gradlew clean nativeCompile

或构建容器镜像：

./gradlew clean bootBuildImage

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