编译器JIT编译语言运行时高性能计算内存管理【免费下载链接】graalGraalVM compiles applications into native executables that start instantly, scale fast, and use fewer compute resources 项目地址https://gitcode.com/gh_mirrors/gr/graal点击查看免费下载本指南面向使用 Gradle 构建 GraalVM Native Image 的开发者系统讲解因反射reflection、资源resources、序列化serialization与 JNI 缺失可达性元数据Reachability Metadata而导致的构建与运行失败问题。你将掌握一套完整的排查工作流如何开启严格元数据检查与告警、如何用 Tracing Agent 自动收集元数据、如何手工编写reachability-metadata.json补充遗漏项并最终通过nativeCompile/nativeTest验证修复结果。为什么 Native Image 需要可达性元数据JVM 的动态特性反射、JNI、动态代理、资源加载等在 HotSpot 上之所以工作正常是因为运行期所有 class 文件与资源都可按需加载但这一便利也带来了内存占用与启动时间的代价。而native-image构建器在构建期执行静态分析遵循封闭世界假设closed-world assumption只把静态分析判定为可达的元素打入二进制以换取小体积与快速启动。问题在于动态访问的元素是否可达取决于只有运行期才知道的数据静态分析无法覆盖。因此native-image要求开发者提供可达性元数据显式声明哪些类、方法、字段、资源需要被包含。元数据不全时二进制要么构建失败要么运行期抛出形如MissingReflectionRegistrationError的缺失注册错误。关于元数据的完整原理与 JSON 格式总参考可阅读官方 Reachability Metadata 文档本指南聚焦 Gradle 项目中的落地排查流程。第一步开启检测暴露缺失元数据在动手补元数据之前首先要让问题看得见。在 Gradle 构建脚本中对所有二进制启用严格元数据模式与运行期告警模式graalvmNative { binaries.all { buildArgs.add(--exact-reachability-metadata) runtimeArgs.add(-XX:MissingRegistrationReportingModeWarn) } }其中--exact-reachability-metadata构建期参数开启精确可达性元数据模式。该模式下凡未注册元数据的动态访问二进制会以java.lang.Error的子类型快速失败fail fast并精确指出缺失的元素覆盖反射、资源、JNI 与序列化四类访问。-XX:MissingRegistrationReportingModeWarn运行期参数把缺失注册从抛异常崩溃降级为打印告警便于在不中断运行的前提下一次收集全部问题点。源码视角这两个参数从哪来这两个选项在 Native Image 核心中有明确实现。构建期选项定义于 SubstrateOptions.java 附近其详细语义写在 ExactReachabilityMetadataHelp.txt 中要点如下不带参数使用时命令行的所有类都会触发缺失注册错误该形式只允许出现在命令行或模块路径module-path上 jar 内的native-image.properties中不允许出现在类路径class-path的 properties 里。带包名参数--exact-reachability-metadatacom.example.mypackage时仅指定包内的类触发严格检查适用于修复第三方库问题命令行上使用带参数形式不受上述位置限制。还有配套的--exact-reachability-metadata-path class-search path用于把整个 class-path / module-path 条目目录或 jar内的所有类都注册为严格检查对象该选项只能出现在命令行。帮助文本明确提示--exact-reachability-metadata将在未来版本的 Native Image 中成为默认行为因此尽早采用可以避免后续升级 GraalVM 时大面积破坏。运行期选项-XX:MissingRegistrationReportingMode同样是 Native Image 的运行时选项见 SubstrateOptions.java。其四种取值的行为在 MissingRegistrationUtils.java 的report(...)中实现模式行为Warn打印缺失注册告警与相关栈帧跳过 JDK 与 GraalVM 内部帧聚焦应用代码程序继续运行Throw直接抛出缺失注册的ErrorExit打印错误与栈跟踪后调用System.exit退出退出码对应ExitStatus.MISSING_METADATAExitTest抛出ExitException适合测试框架捕获并判定失败按错误类型定位缺失的元数据即使没有开启严格模式运行期错误类型本身也能直接指示该补哪类元数据。下表来自配套技能参考文档 reachability-metadata.mdsubstratevm 技能是排查的第一步运行期错误根因修复位置NoClassDefFoundError类未被打入二进制反射元数据中注册该类型MissingReflectionRegistrationError对未注册类/方法/字段的反射访问反射元数据NoSuchMethodException方法未注册供反射调用反射元数据方法小节NoSuchFieldException字段未注册供反射访问反射元数据字段小节MissingJNIRegistrationErrorJNI 查找未注册的类型/成员JNI 元数据MissingForeignRegistrationErrorFFM downcall/upcall 缺少注册描述符Foreign 小节进阶见 GraalVM 文档MissingResourceException资源包未包含资源元数据bundles 小节快速诊断命令——用告警模式运行应用不崩溃即可看到所有缺失注册java -XX:MissingRegistrationReportingModeWarn -jar your-app.jar若测试代码中存在catch (Throwable t)吞掉缺失注册错误的情况改用Exit模式强制暴露java -XX:MissingRegistrationReportingModeExit -jar your-app.jar构建期则可直接启用严格元数据模式native-image --exact-reachability-metadata ... # 或仅对指定包启用 native-image --exact-reachability-metadatacom.example.mypackage ...第二步运行 Tracing Agent 自动收集元数据定位到缺失项后优先使用 GraalVM 的Tracing Agent自动收集。Agent 在普通 JVM 上运行应用时跟踪所有动态特性访问类查找、方法/字段访问、资源加载、JNI 调用等并在应用退出时把元数据写成 JSON 配置文件。其实现位于 NativeImageAgent.java支持条件元数据写入ConditionalConfigurationWriter与调用方过滤userCodeFilter等能力。在 Gradle 项目中通过 Native Build Tools 插件的generateMetadata任务一键完成./gradlew generateMetadata -Pcoordinateslibrary-coordinates -PagentAllowedPackagescondition-packages参数含义可概括为-Pcoordinateslibrary-coordinates提供库的 Maven 坐标如com.example:my-lib决定元数据按META-INF/native-image/groupId/artifactId/的目录层级输出便于发布为库时随 jar 分发-PagentAllowedPackagescondition-packages限定 Agent 生成条件元数据时考虑的应用包让收集结果聚焦于你的业务代码而非全部第三方依赖。Agent 只观察实际执行过的代码路径因此建议用尽可能全面的输入多次运行应用以提高覆盖率。官方自动元数据收集文档还提供了命令行形式的 Agent 用法例如$JAVA_HOME/bin/java -agentlib:native-image-agentconfig-output-dir/path/to/config-dir/ ...以及追加式合并、周期性写入config-write-period-secs、config-write-initial-delay-secs等选项供需要更细粒度控制收集时机的场景使用。第三步手工补充元数据reachability-metadata.json当 Agent 收集结果不完整例如某些路径未被测试覆盖或你维护的库希望精确控制暴露面时手工补充是必要的兜底手段。文件位置与命名约定Native Image 会自动扫描类路径下META-INF/native-image/目录含任意子目录中所有名为reachability-metadata.json的文件并合并纳入构建。标准布局为src/main/resources/ └── META-INF/ └── native-image/ └── groupId/ └── artifactId/ └── reachability-metadata.json本指南对应的 Gradle 场景建议放在独立子目录中便于区分来源META-INF/native-image/project-groupId/manual-metadata/reachability-metadata.json文件顶层是一个对象每个键对应一类元数据值为条目数组{ reflection: [], resources: [] }替代方案当 JSON 不足以表达时向Class.forName(Foo)、getMethod(...)等 API 传入常量参数native-image 会在构建期自动求值并注册无需 JSON使用-H:Preserveclasspath-selector保留整个包/模块/类路径条目详见 BuildOptions 中 Preserve 相关文档。反射元数据reflection注册类型修复NoClassDefFoundError、MissingReflectionRegistrationError使Class.forName(com.example.MyClass)可命中{ reflection: [ { type: com.example.MyClass } ] }注册指定方法修复Method.invoke()/Constructor.newInstance()上的NoSuchMethodException{ type: com.example.MyClass, methods: [ { name: myMethod, parameterTypes: [java.lang.String, int] }, { name: init, parameterTypes: [] } ] }构造器统一使用init作为方法名parameterTypes为空数组表示无参构造器。注册全部方法精度低、二进制更大慎用{ type: com.example.MyClass, allDeclaredMethods: true, allPublicMethods: true, allDeclaredConstructors: true, allPublicConstructors: true }allDeclared*类型自身声明的成员/构造器allPublic*所有 public 成员/构造器包含从父类型继承的。注册字段修复Field.get()/Field.set()上的NoSuchFieldException{ type: com.example.MyClass, fields: [ { name: myField }, { name: anotherField } ] }或全部字段{ type: com.example.MyClass, allDeclaredFields: true, allPublicFields: true }动态代理Proxy.newProxyInstance(...)创建的类type换为接口列表对象接口顺序必须与调用时传入的顺序一致{ type: { proxy: [com.example.IFoo, com.example.IBar] } }Unsafe 分配Unsafe.allocateInstance(MyClass.class){ type: com.example.MyClass, unsafeAllocated: true }类型条目完整字段参考以下字段可任意组合均被 Native Image 支持完整字段表另见 ReachabilityMetadata.md 的字段参考{ condition: { typeReached: com.example.TriggerClass }, type: com.example.MyClass, fields: [{ name: fieldName }], methods: [{ name: methodName, parameterTypes: [java.lang.String] }], allDeclaredConstructors: true, allPublicConstructors: true, allDeclaredMethods: true, allPublicMethods: true, allDeclaredFields: true, allPublicFields: true, unsafeAllocated: true, serializable: true }JNI 元数据jni / jniAccessible当原生 C/C 代码通过 JNI 回调 Java 时使用修复MissingJNIRegistrationError{ reflection: [ { type: com.example.MyClass, jniAccessible: true } ] }同时开放字段与方法{ type: com.example.MyClass, jniAccessible: true, fields: [{ name: value }], methods: [ { name: callback, parameterTypes: [int] } ], allDeclaredConstructors: true }JNI 元数据同样支持allDeclared*/allPublic*便捷标志。多数 JNI 库对 Java 异常处理并不友好官方建议始终以--exact-reachability-metadata配合-XX:MissingRegistrationReportingModeWarn观察缺失项。资源元数据resources嵌入资源修复getResourceAsStream返回 null使用 glob 模式{ resources: [ { glob: config/app.properties }, { glob: templates/** }, { glob: **/Resource*.txt } ] }Glob 规则*匹配单个路径层级内的任意字符**跨多个层级匹配不允许结尾斜杠、空层级或***。更多示例{ glob: config/app.properties } // 精确文件 { glob: **/**.json } // 任意位置的所有 JSON { glob: static/images/*.png } // 单目录下所有 PNG注意Class.getResourceAsStream(plan.txt)这类使用类字面量与字符串字面量的调用会被 native-image 自动检测无需写 JSON。指定模块的资源{ resources: [ { module: library.module, glob: resource-file.txt } ] }资源包Resource Bundles修复ResourceBundle.getBundle(...)抛出的MissingResourceException{ resources: [ { bundle: com.example.Messages }, { bundle: com.example.Errors } ] }指定模块的 bundle{ resources: [ { module: app.module, bundle: com.example.Messages } ] }Bundle 会包含镜像内嵌的所有 locale。如需控制 locale 集合减小体积或全量包含体积显著增大native-image -Duser.countryUS -Duser.languageen -H:IncludeLocalesfr,de # 或包含全部 locale会显著增加镜像体积 native-image -H:IncludeAllLocales序列化元数据serialization修复ObjectInputStream.readObject()时的InvalidClassException、StreamCorruptedException或ClassNotFoundException。JSON 方式{ reflection: [ { type: com.example.MySerializableClass, serializable: true } ] }代码方式自动检测使用常量模式的ObjectInputFilter时 native-image 可自动识别var filter ObjectInputFilter.Config.createFilter(com.example.MyClass;!*;); objectInputStream.setObjectInputFilter(filter);代理序列化{ reflection: [ { type: { proxy: [com.example.IFoo] }, serializable: true } ] }条件元数据条目condition / typeReached为避免把可能永不执行的代码路径的元数据也塞进二进制官方强烈建议为条目加上条件{ condition: { typeReached: com.example.FeatureModule }, type: com.example.OptionalClass, allDeclaredMethods: true }语义要点详见 ReachabilityMetadata.md 条件条目章节带typeReached条件的元数据条目仅当指定类型在运行期被触达后才生效触达之前对相应元素的动态访问行为如同该条目不存在会抛出缺失注册错误一个类型被触达的时刻是其类初始化例程开始之前或其任一子类型被触达时数组类型永远不会被视为触达不能用作条件条件条目在构建期只要满足静态可达性就会被包含进镜像占用体积但只有在运行期条件成立时才真正可用对第三方库元数据应尽量使用条件以控制二进制体积。关于typeReached判定边界的 Java 示例可参考官方条件元数据文档中的ConditionType代码演示。完整示例reachability-metadata.json综合以上各类元数据的可运行样例同样源自技能参考文档{ reflection: [ { condition: { typeReached: com.example.App }, type: com.example.MyClass, fields: [ { name: myField } ], methods: [ { name: myMethod, parameterTypes: [java.lang.String] }, { name: init, parameterTypes: [] } ], allDeclaredConstructors: true, allPublicConstructors: true, allDeclaredFields: true, allPublicFields: true, allDeclaredMethods: true, allPublicMethods: true, unsafeAllocated: true, serializable: true }, { type: { proxy: [com.example.IFoo, com.example.IBar] } }, { type: com.example.JniClass, jniAccessible: true, fields: [{ name: nativeHandle }], allDeclaredMethods: true } ], resources: [ { glob: config/** }, { module: app.module, glob: static/index.html }, { bundle: com.example.Messages } ] }如需按 schema 校验文件合法性仓库提供了 reachability-metadata-schema-v1.2.0.json 以及更早版本的 schema位于 assets 目录可依据所用 GraalVM 版本选用对应 schema 进行 JSON Schema 校验。第四步重新构建并验证补充完元数据后重新构建并运行测试./gradlew nativeCompile ./gradlew nativeTest建议的验证顺序构建阶段确认--exact-reachability-metadata不再报缺失注册运行期先以-XX:MissingRegistrationReportingModeWarn启动核对告警列表是否清零测试阶段切换为-XX:MissingRegistrationReportingModeExit或ExitTest确保被catch (Throwable t)吞掉的缺失注册也能被暴露从而保证元数据完整若只修复了部分包可将--exact-reachability-metadatapackage逐步扩展到更多包最终实现全量严格模式。小结Gradle 场景下的可达性元数据排障可归纳为四步闭环开启严格模式暴露问题 → 按错误类型定位缺失元数据类别 → 用 Tracing Agent 自动收集并手工补充reachability-metadata.json→ 重建并验证。核心工具是构建期参数--exact-reachability-metadata与运行期参数-XX:MissingRegistrationReportingModeWarn/Exit/Throw/ExitTest元数据文件遵循META-INF/native-image/groupId/artifactId/reachability-metadata.json约定。由于--exact-reachability-metadata未来将成为 Native Image 的默认行为尽早把项目迁移到显式、完整、带条件的元数据体系可以显著降低后续 GraalVM 升级时的回归风险。更多细节可继续查阅 Reachability Metadata 完整文档、自动元数据收集文档以及技能参考 reachability-metadata.md。赞分享编译器JIT编译语言运行时高性能计算内存管理【免费下载链接】graalGraalVM compiles applications into native executables that start instantly, scale fast, and use fewer compute resources 项目地址https://gitcode.com/gh_mirrors/gr/graal点击查看免费下载相关推荐GraalVM Native Image 中的 Foreign Function and Memory APIDowncall、Upcall 与 reachability-metadata 配置实战GraalVM Native Image 中的 Foreign Function and Memory APIDowncall、Upcall 与 reacha编译器JIT编译语言运行时高性能计算内存管理使用 Tracing Agent 自动收集 GraalVM Native Image 可达性元数据使用 Tracing Agent 自动收集 GraalVM Native Image 可达性元数据 本指南围绕 GraalVM Native Image 的 T编译器JIT编译语言运行时高性能计算内存管理Argilla FeedbackDataset 元数据Metadata实战指南从属性配置到记录过滤排序Argilla FeedbackDataset 元数据Metadata实战指南从属性配置到记录过滤排序 元数据是 Argilla 数据标注协作平台中连接「数据标注人工智能NLPMLOpsRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GraalVM Native Image 可达性元数据（Reachability Metadata）排查与配置实战：Gradle 构建篇
编译器JIT编译语言运行时高性能计算内存管理【免费下载链接】graalGraalVM compiles applications into native executables that start instantly, scale fast, and use fewer compute resources 项目地址https://gitcode.com/gh_mirrors/gr/graal点击查看免费下载本指南面向使用 Gradle 构建 GraalVM Native Image 的开发者系统讲解因反射reflection、资源resources、序列化serialization与 JNI 缺失可达性元数据Reachability Metadata而导致的构建与运行失败问题。你将掌握一套完整的排查工作流如何开启严格元数据检查与告警、如何用 Tracing Agent 自动收集元数据、如何手工编写reachability-metadata.json补充遗漏项并最终通过nativeCompile/nativeTest验证修复结果。为什么 Native Image 需要可达性元数据JVM 的动态特性反射、JNI、动态代理、资源加载等在 HotSpot 上之所以工作正常是因为运行期所有 class 文件与资源都可按需加载但这一便利也带来了内存占用与启动时间的代价。而native-image构建器在构建期执行静态分析遵循封闭世界假设closed-world assumption只把静态分析判定为可达的元素打入二进制以换取小体积与快速启动。问题在于动态访问的元素是否可达取决于只有运行期才知道的数据静态分析无法覆盖。因此native-image要求开发者提供可达性元数据显式声明哪些类、方法、字段、资源需要被包含。元数据不全时二进制要么构建失败要么运行期抛出形如MissingReflectionRegistrationError的缺失注册错误。关于元数据的完整原理与 JSON 格式总参考可阅读官方 Reachability Metadata 文档本指南聚焦 Gradle 项目中的落地排查流程。第一步开启检测暴露缺失元数据在动手补元数据之前首先要让问题看得见。在 Gradle 构建脚本中对所有二进制启用严格元数据模式与运行期告警模式graalvmNative { binaries.all { buildArgs.add(--exact-reachability-metadata) runtimeArgs.add(-XX:MissingRegistrationReportingModeWarn) } }其中--exact-reachability-metadata构建期参数开启精确可达性元数据模式。该模式下凡未注册元数据的动态访问二进制会以java.lang.Error的子类型快速失败fail fast并精确指出缺失的元素覆盖反射、资源、JNI 与序列化四类访问。-XX:MissingRegistrationReportingModeWarn运行期参数把缺失注册从抛异常崩溃降级为打印告警便于在不中断运行的前提下一次收集全部问题点。源码视角这两个参数从哪来这两个选项在 Native Image 核心中有明确实现。构建期选项定义于 SubstrateOptions.java 附近其详细语义写在 ExactReachabilityMetadataHelp.txt 中要点如下不带参数使用时命令行的所有类都会触发缺失注册错误该形式只允许出现在命令行或模块路径module-path上 jar 内的native-image.properties中不允许出现在类路径class-path的 properties 里。带包名参数--exact-reachability-metadatacom.example.mypackage时仅指定包内的类触发严格检查适用于修复第三方库问题命令行上使用带参数形式不受上述位置限制。还有配套的--exact-reachability-metadata-path class-search path用于把整个 class-path / module-path 条目目录或 jar内的所有类都注册为严格检查对象该选项只能出现在命令行。帮助文本明确提示--exact-reachability-metadata将在未来版本的 Native Image 中成为默认行为因此尽早采用可以避免后续升级 GraalVM 时大面积破坏。运行期选项-XX:MissingRegistrationReportingMode同样是 Native Image 的运行时选项见 SubstrateOptions.java。其四种取值的行为在 MissingRegistrationUtils.java 的report(...)中实现模式行为Warn打印缺失注册告警与相关栈帧跳过 JDK 与 GraalVM 内部帧聚焦应用代码程序继续运行Throw直接抛出缺失注册的ErrorExit打印错误与栈跟踪后调用System.exit退出退出码对应ExitStatus.MISSING_METADATAExitTest抛出ExitException适合测试框架捕获并判定失败按错误类型定位缺失的元数据即使没有开启严格模式运行期错误类型本身也能直接指示该补哪类元数据。下表来自配套技能参考文档 reachability-metadata.mdsubstratevm 技能是排查的第一步运行期错误根因修复位置NoClassDefFoundError类未被打入二进制反射元数据中注册该类型MissingReflectionRegistrationError对未注册类/方法/字段的反射访问反射元数据NoSuchMethodException方法未注册供反射调用反射元数据方法小节NoSuchFieldException字段未注册供反射访问反射元数据字段小节MissingJNIRegistrationErrorJNI 查找未注册的类型/成员JNI 元数据MissingForeignRegistrationErrorFFM downcall/upcall 缺少注册描述符Foreign 小节进阶见 GraalVM 文档MissingResourceException资源包未包含资源元数据bundles 小节快速诊断命令——用告警模式运行应用不崩溃即可看到所有缺失注册java -XX:MissingRegistrationReportingModeWarn -jar your-app.jar若测试代码中存在catch (Throwable t)吞掉缺失注册错误的情况改用Exit模式强制暴露java -XX:MissingRegistrationReportingModeExit -jar your-app.jar构建期则可直接启用严格元数据模式native-image --exact-reachability-metadata ... # 或仅对指定包启用 native-image --exact-reachability-metadatacom.example.mypackage ...第二步运行 Tracing Agent 自动收集元数据定位到缺失项后优先使用 GraalVM 的Tracing Agent自动收集。Agent 在普通 JVM 上运行应用时跟踪所有动态特性访问类查找、方法/字段访问、资源加载、JNI 调用等并在应用退出时把元数据写成 JSON 配置文件。其实现位于 NativeImageAgent.java支持条件元数据写入ConditionalConfigurationWriter与调用方过滤userCodeFilter等能力。在 Gradle 项目中通过 Native Build Tools 插件的generateMetadata任务一键完成./gradlew generateMetadata -Pcoordinateslibrary-coordinates -PagentAllowedPackagescondition-packages参数含义可概括为-Pcoordinateslibrary-coordinates提供库的 Maven 坐标如com.example:my-lib决定元数据按META-INF/native-image/groupId/artifactId/的目录层级输出便于发布为库时随 jar 分发-PagentAllowedPackagescondition-packages限定 Agent 生成条件元数据时考虑的应用包让收集结果聚焦于你的业务代码而非全部第三方依赖。Agent 只观察实际执行过的代码路径因此建议用尽可能全面的输入多次运行应用以提高覆盖率。官方自动元数据收集文档还提供了命令行形式的 Agent 用法例如$JAVA_HOME/bin/java -agentlib:native-image-agentconfig-output-dir/path/to/config-dir/ ...以及追加式合并、周期性写入config-write-period-secs、config-write-initial-delay-secs等选项供需要更细粒度控制收集时机的场景使用。第三步手工补充元数据reachability-metadata.json当 Agent 收集结果不完整例如某些路径未被测试覆盖或你维护的库希望精确控制暴露面时手工补充是必要的兜底手段。文件位置与命名约定Native Image 会自动扫描类路径下META-INF/native-image/目录含任意子目录中所有名为reachability-metadata.json的文件并合并纳入构建。标准布局为src/main/resources/ └── META-INF/ └── native-image/ └── groupId/ └── artifactId/ └── reachability-metadata.json本指南对应的 Gradle 场景建议放在独立子目录中便于区分来源META-INF/native-image/project-groupId/manual-metadata/reachability-metadata.json文件顶层是一个对象每个键对应一类元数据值为条目数组{ reflection: [], resources: [] }替代方案当 JSON 不足以表达时向Class.forName(Foo)、getMethod(...)等 API 传入常量参数native-image 会在构建期自动求值并注册无需 JSON使用-H:Preserveclasspath-selector保留整个包/模块/类路径条目详见 BuildOptions 中 Preserve 相关文档。反射元数据reflection注册类型修复NoClassDefFoundError、MissingReflectionRegistrationError使Class.forName(com.example.MyClass)可命中{ reflection: [ { type: com.example.MyClass } ] }注册指定方法修复Method.invoke()/Constructor.newInstance()上的NoSuchMethodException{ type: com.example.MyClass, methods: [ { name: myMethod, parameterTypes: [java.lang.String, int] }, { name: init, parameterTypes: [] } ] }构造器统一使用init作为方法名parameterTypes为空数组表示无参构造器。注册全部方法精度低、二进制更大慎用{ type: com.example.MyClass, allDeclaredMethods: true, allPublicMethods: true, allDeclaredConstructors: true, allPublicConstructors: true }allDeclared*类型自身声明的成员/构造器allPublic*所有 public 成员/构造器包含从父类型继承的。注册字段修复Field.get()/Field.set()上的NoSuchFieldException{ type: com.example.MyClass, fields: [ { name: myField }, { name: anotherField } ] }或全部字段{ type: com.example.MyClass, allDeclaredFields: true, allPublicFields: true }动态代理Proxy.newProxyInstance(...)创建的类type换为接口列表对象接口顺序必须与调用时传入的顺序一致{ type: { proxy: [com.example.IFoo, com.example.IBar] } }Unsafe 分配Unsafe.allocateInstance(MyClass.class){ type: com.example.MyClass, unsafeAllocated: true }类型条目完整字段参考以下字段可任意组合均被 Native Image 支持完整字段表另见 ReachabilityMetadata.md 的字段参考{ condition: { typeReached: com.example.TriggerClass }, type: com.example.MyClass, fields: [{ name: fieldName }], methods: [{ name: methodName, parameterTypes: [java.lang.String] }], allDeclaredConstructors: true, allPublicConstructors: true, allDeclaredMethods: true, allPublicMethods: true, allDeclaredFields: true, allPublicFields: true, unsafeAllocated: true, serializable: true }JNI 元数据jni / jniAccessible当原生 C/C 代码通过 JNI 回调 Java 时使用修复MissingJNIRegistrationError{ reflection: [ { type: com.example.MyClass, jniAccessible: true } ] }同时开放字段与方法{ type: com.example.MyClass, jniAccessible: true, fields: [{ name: value }], methods: [ { name: callback, parameterTypes: [int] } ], allDeclaredConstructors: true }JNI 元数据同样支持allDeclared*/allPublic*便捷标志。多数 JNI 库对 Java 异常处理并不友好官方建议始终以--exact-reachability-metadata配合-XX:MissingRegistrationReportingModeWarn观察缺失项。资源元数据resources嵌入资源修复getResourceAsStream返回 null使用 glob 模式{ resources: [ { glob: config/app.properties }, { glob: templates/** }, { glob: **/Resource*.txt } ] }Glob 规则*匹配单个路径层级内的任意字符**跨多个层级匹配不允许结尾斜杠、空层级或***。更多示例{ glob: config/app.properties } // 精确文件 { glob: **/**.json } // 任意位置的所有 JSON { glob: static/images/*.png } // 单目录下所有 PNG注意Class.getResourceAsStream(plan.txt)这类使用类字面量与字符串字面量的调用会被 native-image 自动检测无需写 JSON。指定模块的资源{ resources: [ { module: library.module, glob: resource-file.txt } ] }资源包Resource Bundles修复ResourceBundle.getBundle(...)抛出的MissingResourceException{ resources: [ { bundle: com.example.Messages }, { bundle: com.example.Errors } ] }指定模块的 bundle{ resources: [ { module: app.module, bundle: com.example.Messages } ] }Bundle 会包含镜像内嵌的所有 locale。如需控制 locale 集合减小体积或全量包含体积显著增大native-image -Duser.countryUS -Duser.languageen -H:IncludeLocalesfr,de # 或包含全部 locale会显著增加镜像体积 native-image -H:IncludeAllLocales序列化元数据serialization修复ObjectInputStream.readObject()时的InvalidClassException、StreamCorruptedException或ClassNotFoundException。JSON 方式{ reflection: [ { type: com.example.MySerializableClass, serializable: true } ] }代码方式自动检测使用常量模式的ObjectInputFilter时 native-image 可自动识别var filter ObjectInputFilter.Config.createFilter(com.example.MyClass;!*;); objectInputStream.setObjectInputFilter(filter);代理序列化{ reflection: [ { type: { proxy: [com.example.IFoo] }, serializable: true } ] }条件元数据条目condition / typeReached为避免把可能永不执行的代码路径的元数据也塞进二进制官方强烈建议为条目加上条件{ condition: { typeReached: com.example.FeatureModule }, type: com.example.OptionalClass, allDeclaredMethods: true }语义要点详见 ReachabilityMetadata.md 条件条目章节带typeReached条件的元数据条目仅当指定类型在运行期被触达后才生效触达之前对相应元素的动态访问行为如同该条目不存在会抛出缺失注册错误一个类型被触达的时刻是其类初始化例程开始之前或其任一子类型被触达时数组类型永远不会被视为触达不能用作条件条件条目在构建期只要满足静态可达性就会被包含进镜像占用体积但只有在运行期条件成立时才真正可用对第三方库元数据应尽量使用条件以控制二进制体积。关于typeReached判定边界的 Java 示例可参考官方条件元数据文档中的ConditionType代码演示。完整示例reachability-metadata.json综合以上各类元数据的可运行样例同样源自技能参考文档{ reflection: [ { condition: { typeReached: com.example.App }, type: com.example.MyClass, fields: [ { name: myField } ], methods: [ { name: myMethod, parameterTypes: [java.lang.String] }, { name: init, parameterTypes: [] } ], allDeclaredConstructors: true, allPublicConstructors: true, allDeclaredFields: true, allPublicFields: true, allDeclaredMethods: true, allPublicMethods: true, unsafeAllocated: true, serializable: true }, { type: { proxy: [com.example.IFoo, com.example.IBar] } }, { type: com.example.JniClass, jniAccessible: true, fields: [{ name: nativeHandle }], allDeclaredMethods: true } ], resources: [ { glob: config/** }, { module: app.module, glob: static/index.html }, { bundle: com.example.Messages } ] }如需按 schema 校验文件合法性仓库提供了 reachability-metadata-schema-v1.2.0.json 以及更早版本的 schema位于 assets 目录可依据所用 GraalVM 版本选用对应 schema 进行 JSON Schema 校验。第四步重新构建并验证补充完元数据后重新构建并运行测试./gradlew nativeCompile ./gradlew nativeTest建议的验证顺序构建阶段确认--exact-reachability-metadata不再报缺失注册运行期先以-XX:MissingRegistrationReportingModeWarn启动核对告警列表是否清零测试阶段切换为-XX:MissingRegistrationReportingModeExit或ExitTest确保被catch (Throwable t)吞掉的缺失注册也能被暴露从而保证元数据完整若只修复了部分包可将--exact-reachability-metadatapackage逐步扩展到更多包最终实现全量严格模式。小结Gradle 场景下的可达性元数据排障可归纳为四步闭环开启严格模式暴露问题 → 按错误类型定位缺失元数据类别 → 用 Tracing Agent 自动收集并手工补充reachability-metadata.json→ 重建并验证。核心工具是构建期参数--exact-reachability-metadata与运行期参数-XX:MissingRegistrationReportingModeWarn/Exit/Throw/ExitTest元数据文件遵循META-INF/native-image/groupId/artifactId/reachability-metadata.json约定。由于--exact-reachability-metadata未来将成为 Native Image 的默认行为尽早把项目迁移到显式、完整、带条件的元数据体系可以显著降低后续 GraalVM 升级时的回归风险。更多细节可继续查阅 Reachability Metadata 完整文档、自动元数据收集文档以及技能参考 reachability-metadata.md。赞分享编译器JIT编译语言运行时高性能计算内存管理【免费下载链接】graalGraalVM compiles applications into native executables that start instantly, scale fast, and use fewer compute resources 项目地址https://gitcode.com/gh_mirrors/gr/graal点击查看免费下载相关推荐GraalVM Native Image 中的 Foreign Function and Memory APIDowncall、Upcall 与 reachability-metadata 配置实战GraalVM Native Image 中的 Foreign Function and Memory APIDowncall、Upcall 与 reacha编译器JIT编译语言运行时高性能计算内存管理使用 Tracing Agent 自动收集 GraalVM Native Image 可达性元数据使用 Tracing Agent 自动收集 GraalVM Native Image 可达性元数据 本指南围绕 GraalVM Native Image 的 T编译器JIT编译语言运行时高性能计算内存管理Argilla FeedbackDataset 元数据Metadata实战指南从属性配置到记录过滤排序Argilla FeedbackDataset 元数据Metadata实战指南从属性配置到记录过滤排序 元数据是 Argilla 数据标注协作平台中连接「数据标注人工智能NLPMLOpsRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考