企业官网建设流程全解析

OkHttp 原生镜像测试指南：在 GraalVM Native Image 中运行 JUnit 5 测试套件

【免费下载链接】okhttpA meticulous HTTP client for the JVM, Android, and GraalVM.项目地址: https://gitcode.com/gh_mirrors/okh/okhttp

OkHttp 项目将自身定位为面向 JVM、Android 与 GraalVM 的 HTTP 客户端，其中 GraalVM 原生镜像支持是重要的一环。native-image-tests模块（见 native-image-tests/README.md）的作用，正是把 OkHttp 的 JUnit 5 测试套件放进 GraalVM Native Image 中执行，用来验证 OkHttp 在 AOT（Ahead-of-Time）编译、关闭 JIT 与反射受限环境下的真实行为。读完本文，你将掌握如何用一条 Gradle 命令触发原生镜像测试、该模块测试了哪些关键能力（MockWebServer 回环请求、Public Suffix 资源加载、参数化测试），以及 OkHttp 为原生镜像做了哪些自动化配置。

一、模块定位：为什么要在原生镜像里跑测试

OkHttp 在 JVM 上依赖运行时反射、动态代理、SPI 加载等机制来选择 TLS 平台实现、加载 Public Suffix 数据库等资源。而 GraalVM Native Image 是静态分析驱动的：它通过"可达性分析"（reachability analysis）确定哪些类需要被编译进镜像，反射、资源、JNI 等动态特性必须在构建期显式注册，否则运行时会抛MissingResourceException、ClassNotFoundException或NoSuchMethodError。

因此，仅仅把 OkHttp 编译成原生镜像成功"能启动"是不够的，必须让测试套件本身也运行在镜像内，才能暴露诸如"资源未被打包""反射调用缺失""TLS 平台选择逻辑失效"这类问题。native-image-tests模块正是为此而生——它使用 GraalVM 官方 Gradle 插件（org.graalvm.buildtools.native，版本在 gradle/libs.versions.toml 中定义为graalvm-plugin = "1.1.10"，对应的 GraalVM 版本参考为graalvm = "25.0.4"）把 JUnit 5 测试编译成一个原生测试镜像，再在镜像内运行这些测试。

二、执行方式：一条命令触发原生镜像测试

原文档给出了唯一的执行入口：

./gradlew -PgraalBuild=true --info native-image-tests:nativeTest

这条命令包含三个关键要素：

1. -PgraalBuild=true：这是一个项目级 Gradle 属性开关。在 gradle.properties 中该属性的默认值为graalBuild=false（即常规构建不会引入该模块）；在 settings.gradle.kts 的第 42–44 行可以看到，只有graalBuild.toBoolean()为 true 时，:native-image-tests子项目才会被include进构建：

   if (graalBuild.toBoolean()) { include(":native-image-tests") }

   所以省略该开关或设为 false，该任务根本不存在，这一点与常规 JVM 测试（./gradlew :okhttp:test之类）有本质区别。

2. native-image-tests:nativeTest：nativeTest是 GraalVM 原生构建插件提供的测试任务——它先把测试类编译成原生镜像（而不是在 JVM 上跑），再执行镜像。--info用于输出详细的构建日志，方便观察镜像构建（native-image编译）过程与测试执行输出。

3. 运行前提：需要本机安装与插件兼容的 GraalVM JDK（配置了native-image组件）。由于原生镜像编译耗时较长，命令还可在插件配置中看到针对开发调试的加速参数（见下文第四节）。

三、测试内容：覆盖三类典型原生镜像风险点

模块的测试源码集中在 native-image-tests/src/test/kotlin/okhttp3/nativeimage，共三个测试类，恰好对应三类最典型的 GraalVM 兼容性问题。

3.1 SampleTest：MockWebServer 回环与真实外网请求

SampleTest.kt 包含三个用例：

class SampleTest { private val server = MockWebServer() private val client = OkHttpClient() @Test fun passingTest() { assertThat("hello").isEqualTo("hello") } @Test fun testMockWebServer() { server.enqueue(MockResponse(body = "abc")) server.start() client.newCall(Request(url = server.url("/"))).execute().use { assertThat(it.body.string()).isEqualTo("abc") } } @Test fun testExternalSite() { client.newCall(Request(url = "https://google.com/robots.txt".toHttpUrl())).execute().use { assertThat(it.code).isEqualTo(200) } } }

• passingTest是纯 JUnit 5 冒烟用例，验证测试框架本身在原生镜像内可用；
• testMockWebServer是本模块的核心价值用例：它在镜像内启动 mockwebserver3 的 MockWebServer，再用OkHttpClient发起真实 HTTP 回环请求并校验响应体。这验证了 OkHttp 的 HTTP/1.1 协议栈、连接池、socket I/O 在 AOT 编译后仍能正常工作；
• testExternalSite会访问外网（https://google.com/robots.txt）并断言返回 200，验证 HTTPS/TLS 握手在原生镜像中可用——注意该用例依赖外网可达性，离线环境会失败。

3.2 PublicSuffixDatabaseTest：资源文件必须被打进镜像

PublicSuffixDatabaseTest.kt 是一个针对性极强的回归测试：

@Test fun testResourcesLoaded() { val url = "https://api.twitter.com".toHttpUrl() assertThat(url.topPrivateDomain()).isEqualTo("twitter.com") }

HttpUrl.topPrivateDomain()的实现（见 HttpUrl.kt 第 776–781 行）会调用PublicSuffixDatabase.get().getEffectiveTldPlusOne(host)。而 Public Suffix 数据来源于资源文件okhttp3/internal/publicsuffix/PublicSuffixDatabase.list（JVM 端位于 okhttp/src/jvmMain/resources/okhttp3/internal/publicsuffix/PublicSuffixDatabase.list，约 9700 行；Android 端为 okhttp/src/androidMain/assets/PublicSuffixDatabase.list），由 ResourcePublicSuffixList.kt 通过FileSystem.Companion.RESOURCES加载。

在原生镜像中，资源文件默认不会被自动打包，需要显式配置。该用例就是守护"Public Suffix 资源必须随镜像分发"这一行为——如果资源缺失，topPrivateDomain()会抛出MissingResourceException而非返回"twitter.com"。而 OkHttp 通过自身的native-image.properties（见下文第五节）自动解决了该问题。

3.3 WithArgumentSourceTest：参数化测试在原生镜像中的兼容性

WithArgumentSourceTest.kt 针对的是 GraalVM 原生构建工具的一个已知问题（源码注释中标注了https://github.com/graalvm/native-build-tools/issues/745）：

class WithArgumentSourceTest { @ParameterizedTest @ArgumentsSource(FakeArgumentsProvider::class) fun passingTest(value: Int) { assertThat(value).isGreaterThan(0) } } internal class FakeArgumentsProvider : ArgumentsProvider { override fun provideArguments( parameters: ParameterDeclarations?, context: ExtensionContext?, ): Stream<out Arguments> = listOf(Arguments.of(1), Arguments.of(2)).stream() }

该测试通过自定义ArgumentsProvider执行 JUnit 5 参数化测试，强制把junit-jupiter-params相关类纳入镜像闭包（镜像构建时这些类需要保留），以此验证"使用@ArgumentsSource的参数化测试能在原生镜像内正常运行"。这是对测试框架与 GraalVM 反射配置之间兼容性的直接回归保护。

四、构建配置：graalvmNative块与依赖

模块的构建脚本 native-image-tests/build.gradle.kts 揭示了测试镜像的关键配置：

plugins { id("org.graalvm.buildtools.native") kotlin("jvm") id("okhttp.jvm-conventions") id("okhttp.quality-conventions") id("okhttp.testing-conventions") } dependencies { implementation(projects.okhttp) testImplementation(projects.mockwebserver3Junit5) testImplementation(libs.assertk) testRuntimeOnly(libs.junit.jupiter.engine) testImplementation(libs.kotlin.junit5) testImplementation(libs.junit.jupiter.params) } graalvmNative { testSupport = true binaries { named("test") { buildArgs.add("--strict-image-heap") // speed up development testing buildArgs.add("-Ob") } } }

值得注意的配置点：

• testSupport = true：这是让nativeTest任务生效的开关，它会让插件生成"可运行测试的原生测试镜像"；
• --strict-image-heap：启用严格镜像堆检查，在构建期就发现堆内的非法访问（比如把 Java 堆对象错误地放进了镜像堆），属于较严格的验证选项；
• -Ob：-Ob是 GraalVM 的快速构建模式（Quick Build），牺牲部分优化换取更快的编译速度，源码注释明确说明这是"加快开发期测试"；
• 依赖选择：测试只依赖okhttp核心模块与mockwebserver3-junit5，使用 assertk 断言、JUnit 5 引擎与junit-jupiter-params参数化支持；
• JVM 目标：模块将 Kotlin/Java 编译目标都固定为 JVM 17（JvmTarget.JVM_17）。

另外，构建脚本中还保留了一段被注释的sourceSets配置（引用了 okhttp-brotli、okhttp-dnsoverhttps、okhttp-logging-interceptor、okhttp-sse 的测试目录），说明该项目曾经尝试把更多子模块的测试纳入原生镜像执行，目前因上游问题（注释中标注了 issue 链接）暂时只保留native-image-tests自身的三个测试类。

五、OkHttp 侧的原生镜像支持：自动配置与平台裁剪

为了让上述测试（以及用户自己的原生镜像应用）能真正跑起来，OkHttp 在okhttp模块内做了两处原生镜像适配。

5.1 自动化配置：native-image.properties

OkHttp 把 GraalVM 原生镜像的构建参数打包在资源目录的native-image.properties中（JVM 源集为 okhttp/src/jvmMain/resources/META-INF/native-image/okhttp/okhttp/native-image.properties，另有同内容的镜像副本）：

Args = -H:+AddAllCharsets --enable-http --enable-https --features=okhttp3.internal.graal.OkHttpFeature

参数含义：

• -H:+AddAllCharsets：把 JVM 的全部字符集编入镜像，避免Charset缺失导致的编解码问题；
• --enable-http/--enable-https：显式启用 HTTP/HTTPS 协议支持，这是native-image工具默认裁剪掉的网络能力，必须显式开启 OkHttp 才能发起请求；
• --features=okhttp3.internal.graal.OkHttpFeature：注册 OkHttp 自带的镜像配置 Feature。

OkHttpFeature定义于 okhttp/src/jvmMain/kotlin/okhttp3/internal/graal/OkHttpFeature.kt，其 KDoc 明确说明"自动配置 OkHttp 的原生镜像支持，目前包含所有必要的资源"——这保证了PublicSuffixDatabase.list等资源会被打进镜像，正是 PublicSuffixDatabaseTest 能够通过的原因。

5.2 平台裁剪：GraalSvm.kt的@Delete/@Substitute

原生镜像中同时存在多个 TLS 提供者的平台检测逻辑是没有意义的，还可能引入不可达代码的构建告警。OkHttp 在 okhttp/src/jvmMain/kotlin/okhttp3/internal/graal/GraalSvm.kt 中使用 GraalVM SDK 的注解做了裁剪：

• 用@TargetClass(...)+@Delete删除BouncyCastlePlatform、ConscryptPlatform、Jdk8WithJettyBootPlatform、OpenJSSEPlatform四个平台类；
• 对Platform.Companion用@Substitute替换findPlatform()的实现，直接返回Jdk9Platform.buildIfSupported()!!，即原生镜像中只保留 JDK 自带的 TLS 平台。

对照 JVM 上完整的平台选择逻辑（见 PlatformRegistry.kt，它会按Security.getProviders()[0]依次尝试 Conscrypt、BouncyCastle、OpenJSSE、Jdk9、JettyBoot），可以清楚看到原生镜像场景刻意简化为"仅 JDK9 平台"。这也解释了 SampleTest 中 HTTPS 外网请求能够走通的底层前提。

六、与其他模块的关系与适用边界

• 只在 GraalVM 场景生效：:native-image-tests仅在-PgraalBuild=true时参与构建（settings.gradle.kts 第 42–44 行），默认的./gradlew test/./gradlew build不会触达该模块，因此不会拖慢常规 CI；
• 与 okcurl 的对照：仓库中另一个使用 GraalVM 原生构建插件的是 okcurl/build.gradle.kts（第 83 行apply(plugin = "org.graalvm.buildtools.native")），但那是为 CLI 工具生成可执行镜像，而native-image-tests生成的是测试镜像，两者的目的不同；
• 离线环境注意：testExternalSite用例需要外网可达，内网/离线执行nativeTest时该用例会失败；
• 版本前提：本文所述行为基于当前仓库的插件版本org.graalvm.buildtools.native1.1.10 与 GraalVM 25.0.4（见 gradle/libs.versions.toml），并且仓库根目录的 gradle.properties 启用了配置缓存与隔离项目（org.gradle.isolated-projects=true）等现代 Gradle 特性，执行命令时需使用仓库自带的 gradlew 包装器以匹配版本。

七、小结

native-image-tests模块用最小的成本验证了 OkHttp 在 GraalVM 原生镜像中的三项关键能力：HTTP 协议栈可用性（MockWebServer 回环 + 外网 HTTPS）、资源自动打包（Public Suffix 数据库）、测试框架兼容性（参数化测试）。其背后是 OkHttp 在okhttp模块中提供的native-image.properties自动配置与GraalSvm.kt平台裁剪双保险。对于任何想在 GraalVM 原生镜像中使用 OkHttp 的开发者，这条命令值得直接借鉴到自己的项目中：

./gradlew -PgraalBuild=true --info native-image-tests:nativeTest

【免费下载链接】okhttpA meticulous HTTP client for the JVM, Android, and GraalVM.项目地址: https://gitcode.com/gh_mirrors/okh/okhttp