反射配置与 AOT 编译

• Spring AOP 动态代理在 Native 中的限制
• Spring AOT 对代理的预生成
• 反射/代理配置的自动收集

Spring AOP 依赖动态代理（JDK 动态代理或 CGLIB），而 Native Image 的 AOT 编译无法在运行时动态生成代理类，因此需要 Spring AOT 在构建期预生成并注册代理类，同时把相关接口/类写入 proxy-config.json 与 reflect-config.json。Spring Framework 6 / Spring Boot 3 提供了 GraalVM AOT 支持（Spring AOT 引擎），会在构建期解析 @Bean、AOP 切面等，生成 native 需要的代理与反射元数据。处理时需确保 AOP 依赖的类、接口、切面被正确纳入配置，并避免在运行时动态创建代理实例。

兼容的关键是"把动态代理提前到构建期做"。Spring 的 AOT 引擎从 @Configuration 出发，静态化计算 Bean 定义与代理，配合 reachability metadata 满足 Native 的封闭世界假设。

• @ReflectionRegister 注解的作用
• 代理配置（proxy-config）
• 与配置文件的关系

@ReflectionRegister 是 GraalVM 提供的注解，用于在构建期声明某个类需要反射支持，可配合指定构造函数、方法、字段等，常通过构建特性（Feature）或注册机制使用。对于动态代理，GraalVM 通过 proxy-config.json（或 @ProxyRegister 相关注解）声明需要生成的代理接口组合。这些声明本质上是把"运行期动态行为"提前告知构建期，纳入可达性分析。相比手工 JSON，注解方式更贴近代码、便于维护。

注解与 JSON 配置是同一目标（声明反射/代理）的两种表达方式，注解更内聚于代码，适合需要精确控制的场景。构建期需确保这些注解被正确扫描。

• Tracing Agent 的启动参数
• 配置输出目录与命令
• 配置合并与迭代

使用 Tracing Agent 时，在应用启动命令中加入 -agentlib:native-image-agent=config-output-dir=<dir>，运行代表性测试场景，Agent 会采集反射、资源、代理、序列化等调用并输出 JSON 到指定目录。随后将生成的配置目录交给 native-image（通过 -H:ConfigurationFileDirectories 或放入 META-INF/native-image）用于构建。注意事项是：采集时必须覆盖所有真实使用路径（否则会遗漏配置），且配置会随代码演进过期，需在 CI 中周期性重建配置。

Agent 是"以运行促配置"的工程手段，关键是把采集覆盖度与 CI 集成做好，避免"配置快照"与代码脱节。

• Hibernate 的字节码增强（懒加载、代理）
• Native 中的反射与序列化依赖
• 配置与处理方案

Hibernate 依赖字节码增强（如 Entity 懒加载代理、属性增强）与反射、序列化，在 Native Image 中这些动态特性无法在运行时生成，因此需要构建期处理：包括在构建期注册 Hibernate 所需的反射/代理/序列化配置，使用 Hibernate 提供的 Native 支持（如 hibernate-search 或相关依赖），并确保实体类被纳入可达性分析。实践中常需配合 Tracing Agent 采集 Hibernate 的反射调用，并针对字节码增强（Hibernate 的 ByteBuddy 代理）做特殊处理，必要时关闭或调整增强策略。

Hibernate 是最复杂的 Native 适配对象之一，其 ORM 的反射、代理、序列化特性与 Native 的封闭世界假设冲突，需通过配置与框架支持逐项解决。

• Agent 捕获不到的场景
• 构建期初始化与 Lambda 的反射
• 补充手段（手动配置、注解、feature）

Tracing Agent 只在它运行期间被触发的代码路径上采集反射调用，因此以下场景可能捕获不到：一是构建期初始化阶段执行的类静态初始化中的反射（此时 Agent 尚未运行）；二是仅仅在 Lambda 内部或未被执行到的分支中的反射；三是第三方线程、后台任务、特定请求路径中未触发的反射；四是只在特定运行时条件（如配置开关）下才执行的反射。补充手段包括：编写手动配置、使用 @ReflectionRegister 或 Feature 在构建期注册、在 CI 中扩大测试覆盖以覆盖更多路径、合并多轮 Agent 输出。

Agent 的采集是"观察式"而非"穷举式"，其完整性依赖运行覆盖。理解捕获盲区才能设计有效的补充策略，避免生产环境才暴露配置缺失。

• JNI 在本机代码中的调用
• JNI 库的打包与加载
• 限制与注意事项

Native Image 支持 JNI，需要通过 JNI 配置（jni-config.json）声明需要从 native 代码回调的 Java 类、方法、字段，并确保 native 库（.so/.dll）能被打包进镜像或按路径加载。与 JVM 相比，Native 的 JNI 调用更受限：JNI 环境中可用的 Java 宿主能力有限，且必须预先注册可达的 Java 侧对象。此外，由于镜像已静态化，JNI 动态加载的库路径需与平台匹配，跨平台（如 glibc/musl）需重新构建。实践中应尽量用预编译的 native 库并遵循 GraalVM 的 JNI 文档。

JNI 打破了 Native 的封闭世界假设，需要显式声明回调边界。理解其限制可避免在 JNI 密集场景中踩坑。

• ResourceBundle 的资源加载
• 国际化资源在镜像中的打包
• 配置与限制

Native Image 中 ResourceBundle 的加载依赖资源文件被正确打包进镜像，并通过 resource-config.json 声明。默认情况下，构建期对 ResourceBundle 的解析可能被静态化，导致运行时根据 Locale 动态加载多个 locale 的 bundle 不可用。因此通常需要关闭 ResourceBundle 的构建期静态化（如 -H:-UseRuntimeResourceBundle 相关参数），并显式声明所有需要的 locale 资源，确保国际化资源在运行期可访问。限制是动态新增 locale 需要在构建期已知。

国际化的关键是"资源在运行期可动态按 Locale 加载"，这与 Native 的静态化倾向冲突，需显式配置并保持运行期初始化。

• 序列化所需的配置
• serialization-config.json
• 限制（类需构建期注册）

Native Image 对 Java 序列化的支持需要显式配置：通过 serialization-config.json 声明需要序列化/反序列化的类，因为序列化在运行时通过反射创建对象，AOT 无法推断。限制是：所有可能被序列化的类必须在构建期注册，否则运行时抛 ClassNotFoundException 或 InvalidClassException；动态传入任意类名序列化在 Native 中不可行。实践中需结合 Tracing Agent 或手动维护序列化类清单，并尽量使用受控的序列化方案（如 JSON）。

序列化在 Native 中属于"反射类"动态行为，必须预注册。这要求对序列化类面有完整认知，避免遗漏导致运行期异常。

• AOT 对反射/代理的限制
• reflect-config.json 的必要性
• Spring AOT 的自动收集机制

AOT 编译时无法追踪基于字符串的反射与运行时动态代理，因为这些行为在构建期不可见，因此必须通过 reflect-config.json（反射）与 proxy-config.json（代理）预声明，把它们纳入可达性闭包。Spring 通过 AOT 引擎在构建期解析 @Configuration、@Bean、条件注解等，静态分析 Bean 依赖并自动生成/收集所需的反射与代理元数据（写入 META-INF/native-image），从而把 Spring 的动态装配转换成静态可用的形式。这样运行期无需反射即可装配，也规避了动态代理的生成问题。

需要 reflect-config.json 的根本原因是"封闭世界假设"：AOT 只能看到静态可达且被声明的代码。Spring AOT 的价值正是把"装配过程"静态化，减少对反射的依赖。

• Jackson 的反射依赖
• ParameterNamesModule 与参数名保留
• Jandex 索引在 Quarkus 中的应用

Jackson 依赖反射读字段、调构造器、解析泛型，在 Native 中需通过 reflect-config.json 声明 JSON 相关类，并配合 Tracing Agent 采集。ParameterNamesModule 让 Jackson 使用构造器参数名（需编译时保留参数名 -parameters），从而无需无参构造器即可反序列化；Jandex 索引（类索引）在 Quarkus 等框架中用于在构建期扫描类角色与注解，辅助生成 Jackson 与反射配置。这些手段共同减少运行时反射，提升 Native 兼容性。

Jackson 的 Native 适配核心是"把反射与类型信息提前到构建期"。参数名与类索引是关键的元数据来源，配合 reflect-config 可完整覆盖 JSON 序列化场景。

• ServiceLoader 在 Native 中的限制
• 构建期预解析服务实现
• 配置与注意事项

ServiceLoader 通过 META-INF/services 在运行时发现服务实现，属于动态行为，Native 的 AOT 无法在运行时扫描。因此需在构建期预解析：通过配置（如 reflect-config 或 graalvm 的 service 配置）声明服务接口及其实现类，使它们在构建期被纳入可达性闭包。可通过 --enable-all-security-services 或 feature 自动收集。策略上要保证服务实现类在构建期可见且被注册，避免运行时返回空的服务列表。

ServiceLoader 的预解析是把"运行时扫描"变成"构建期注册"，确保服务实现被静态纳入。缺少注册会导致服务发现失败。

• Security Manager 在 Native 中的状态
• sun.misc.Unsafe 的可用性
• 禁用路径与替代方案

Security Manager 在 Java 中被弃用，Native Image 中也不支持运行时 Security Manager，因为它依赖运行时动态权限检查，与 AOT 假设冲突。sun.misc.Unsafe 的部分能力（如直接内存、CAS）在 Native 中受限，底层内存操作依赖 GraalVM 的支持，且部分 Unsafe 操作被禁用或需显式开启。建议用受控的替代 API（如 java.lang.invoke、VarHandle、Java 17+ 的受支持内存 API）替代。禁用路径通常指这些特性在 Native 中默认不可用或需通过配置开启。

Native 默认收敛了 JVM 的"逃生舱"能力（Security Manager、Unsafe），其目的在于安全与封闭世界。理解禁用路径有助于迁移依赖这些 API 的代码。

• 动态代理的生成机制
• proxy-config.json 配置
• 限制与注意事项

Native Image 中动态代理无法在运行时生成类，因此需通过 proxy-config.json 声明代理要实现的接口组合（接口列表），使构建期生成对应的代理类。配置时可列出代理需要的接口序列，运行时针对这些接口组合直接使用预生成的代理。限制是：代理的接口组合必须在构建期已知，无法在运行时任意组合；且代理所涉及的方法调用需被可达性分析覆盖。

动态代理配置的本质是"把接口组合提前枚举"。比反射更显式，因为代理类结构由接口组合决定，需完整声明所有可能用到的组合。

• Feature 的注册与实现
• resource-config 的配置
• 两者的关系

GraalVM 的 reachability metadata 可通过 Feature（构建特性）方式编程式注册：实现 org.graalvm.nativeimage.hosted.Feature 接口，在 beforeAnalysis 等回调中通过 RuntimeReflection、RuntimeResourceAccess 等注册类、方法、资源；也可通过 resource-config.json 声明需打包的资源。Feature 提供更灵活的编程式注入，适合按逻辑动态注册；resource-config 是声明式配置，适合静态资源清单。两者常配合使用，共同完善 reachability metadata。

Feature 是"代码级"的配置入口，resource-config 是"声明式"配置，分别满足动态与静态需求。理解二者有助于构建复杂应用的元数据。

• native-image-agent 的追踪模式
• 配置输出与合并
• 手动合并的注意事项

native-image-agent 以追踪模式运行，采集应用运行期的反射、资源、代理、序列化等调用，输出到指定目录（config-output-dir）。当多次运行或需要合并多份配置时，可使用 config-merge-dir 指定合并目录，Agent 会把多轮采集结果合并去重。手动合并则是把多份 JSON 手工整合，需注意去重与字段一致性。追踪+合并是生产环境生成完整配置的常用流程。

追踪模式解决"采集"，合并解决"完整性"。多轮采集覆盖不同场景后合并，可降低配置遗漏风险。

• Spring AOT 对 Bean 定义的静态化
• 条件注解的构建期评估
• 与运行时差异

Spring AOT 引擎在构建期解析 @Configuration 类，将 @Bean 方法、@Component、@Import 等装配信息静态化，生成注册到 ApplicationContext 的静态 Bean 定义，从而避免运行时反射扫描。条件注解（@Conditional、@Profile、@ConditionalOnProperty 等）在构建期根据构建时的环境/属性进行评估，选中可行的 Bean 定义。因此构建期与运行期的环境/属性需一致，否则条件注解的评估结果可能与运行时意图不符。Spring Boot 的 AOT 模式（spring-boot-starter）会生成静态初始化代码。

Spring AOT 的特点是把"运行期装配"前置到构建期，条件注解的评估结果在构建期固化。这要求构建环境与运行环境在关键属性上保持一致。

• AOT 生成的 proxy 与 lambda
• 序列化边界（哪些对象可序列化）
• 与 Native 的兼容

Spring AOT 在构建期会生成代理类与 lambda 相关的静态代码，其 native 化依赖这些代理/lambda 类被纳入可达性闭包并注册到 proxy/serialization 配置。序列化边界指：在 Native 中，只有被显式注册的类才能序列化，因此 AOT 生成的对象（如代理、lambda 相关对象）若需序列化，其类必须被声明。实践中，Spring 会尽量把 AOT 生成的对象限制在可序列化边界内，避免运行期序列化失败。

序列化边界强调"Native 中序列化须预注册"。AOT 生成的 proxy/lambda 对象需确保其类在序列化配置内，否则跨进程序列化会失败。

• 版本漂移的产生原因
• 配置过期带来的风险
• CI 校验与自动更新

版本漂移指应用代码演进（新增/删除/重命名类、方法、字段）后，已有的 reflect-config.json 等配置不再匹配，导致运行时反射调用失败。规避手段包括：在 CI 中定期用 Tracing Agent 重新采集配置并与现有配置做 diff，核对是否遗漏或多余；在测试阶段运行覆盖主要路径的应用，把采集结果作为配置基准；将配置生成纳入构建流水线，使配置与代码同步更新；同时可以加入"配置-代码一致性"校验步骤，防止过期配置进入生产构建。

版本漂移的本质是"配置是快照，代码在演进"。CI 校验+自动重新采集是把配置维护从"人工"变为"工程化"，是保障 Native 生产稳定性的关键。