三方库适配征文 · 第二批 · 上游 square/okhttp parent-5.5.1适配代码https://atomgit.com/oh-tpc/okhttp摘要本文是「Kotlin Multiplatform for OpenHarmony 实战」系列第 37 篇聚焦 OkHttp 在鸿蒙ArkTS侧的语义复刻。OkHttp 的核心价值在于拦截器链而 ArkTS 没有suspend无法直接照搬 Kotlin 的同步挂起链。本文给出解法回调式异步链——请求沿链向下传递回调响应沿链向上complete/fail送达与同步链的return Response逐行对应。文章依次说明适配分层语义层 引擎层、RealAsyncChain的链末端出口设计、ohos.net.http桥接的三个关键细节ARRAY_BUFFER、会话createHttp/destroy、超时守卫定时器并附环境搭建版本表、踩坑记录与 FAQ。读完可掌握一套可迁移到任意「链式处理」库的 ArkTS 网络适配骨架。目录一、OkHttp 是什么二、适配路线三、环境搭建指引四、核心设计同步链在回调世界的等价物五、引擎层桥接要点六、踩坑记录七、FAQ八、总结一、OkHttp 是什么OkHttp 是 JVM 生态使用量最大的 HTTP 客户端47k stars连接池、HTTP/2 多路复用、拦截器链、透明 GZIP、响应缓存、WebSocket 与同步/异步调用。KMP 生态大量库以其为默认网络层。二、适配路线OkHttpKotlin鸿蒙语义层鸿蒙引擎层Request/RequestBody/FormBodyRequest/RequestBody/FormBody—Response/ResponseBodyResponse/ResponseBody—Interceptor.intercept(chain)Interceptor同步AsyncInterceptor异步BridgeAsyncInterceptorRealInterceptorChainRealInterceptorChain/RealAsyncChain—Call.execute()/enqueue()Call接口异步优先execute 引导用异步OkHttpClient(interceptors)OkHttpClientinstallEngine/addInterceptor—HttpLoggingInterceptor—AsyncLoggingInterceptorRetryAndFollowUpInterceptor—AsyncRetryInterceptorCallServerInterceptor—ohos.net.http桥接整体适配分层如下应用层OkHttpClient语义层Request / Response / Call语义层Interceptor 同步链 AsyncInterceptor 异步链引擎层BridgeAsyncInterceptorohos.net.http 真实网络请求三、环境搭建指引复现本文代码前请先对齐以下工具链版本。版本不一致是 KMP 鸿蒙适配最常见的「跑不起来」原因。组件版本说明DevEco StudioDevEco Studio 26HarmonyOS 6.0 SDK 配套版本本文全部验证基于 DevEco Studio 26工程模板与 hvigor 配置以该版本为准HarmonyOS SDKAPI 20HarmonyOS 6.0ohos.net.http等系统能力随 SDK 提供Kotlin2.1.xKMP 工程与kotlinx-coroutines版本需与之匹配Kotlin Multiplatform 插件2.1.x与 Kotlin 同版本Gradle 中kotlin(multiplatform)版本号Gradle8.9需支持 Kotlin 2.1 与 JDK 17JDK17DevEco Studio 26 内置 JDK 17建议直接使用Node.js18.x 及以上hvigor 构建依赖搭建步骤安装DevEco Studio 26首次启动时按向导下载 HarmonyOS 6.0API 20SDK。用 DevEco Studio 新建一个 Empty Ability 工程确认hvigor与 SDK 版本正常编译。在工程根目录引入 KMP 模块build.gradle.kts中声明kotlin(multiplatform) version 2.1.x并配置ohosArm64/ohosX64目标。将本文的okhttp适配模块作为commonMainohosMain源码集接入同步 Gradle 后即可编译。真机或模拟器运行验收页先测正常请求再测不可达地址的超时与取消分支。开发情况如下官方参考链接DevEco Studio 下载与版本说明https://developer.huawei.com/consumer/cn/deveco-studio/HarmonyOS 开发者文档ArkTS /ohos.net.httphttps://developer.huawei.com/consumer/cn/doc/Kotlin Multiplatform 官方文档https://kotlinlang.org/docs/multiplatform.html本文适配代码仓库https://atomgit.com/wdracky/kmp-ohos-adapters/tree/main/okhttp提示若使用其他 DevEco Studio 版本请以对应版本的 SDK 与 hvigor 为准本文的桥接代码只依赖ohos.net.http的稳定接口跨版本差异主要集中在工程配置而非业务代码。三、核心设计同步链在回调世界的等价物OkHttp 的精髓是拦截器链每个拦截器拿到 Request处理后交给下一个终端拦截器真正发请求。Kotlin 里这是协程挂起函数ArkTS 没有 suspend——解法是回调式异步链// 中间拦截器把新回调向下传递chain.proceedAsync(req,(resp:Response){this.logs.push(-- resp.code);chain.complete(resp);},(err:Error){this.logs.push(-- ERR);chain.fail(err);});// 末端拦截器网络完成后向上送达chain.complete(response);// 或 chain.fail(error)回调沿链向下、响应沿链向上——与同步链的「return Response」逐行对应只是方向变成了回调。语义层同时保留同步链测试用双链并存是 ArkTS 网络适配的通用模式。拦截器链的请求下行与响应上行时序如下ohos.net.http终端拦截器桥接拦截器重试拦截器应用拦截器调用方ohos.net.http终端拦截器桥接拦截器重试拦截器应用拦截器调用方proceedAsync(req, cb)proceedAsync(req, cb)proceedAsync(req, cb)proceedAsync(req, cb)createHttp().request()Response / Errorcomplete(resp) / fail(err)complete(resp) / fail(err)complete(resp) / fail(err)complete(resp) / fail(err)四、引擎层桥接要点consthttpRequest:http.HttpRequest{method:toOhosMethod(request.method),// HttpMethod → http.RequestMethodheader:this.buildHeader(request),// Map → RecordexpectDataType:http.HttpDataType.ARRAY_BUFFER,// 二进制安全readTimeout:this.readTimeoutMs,connectTimeout:this.connectTimeoutMs};if(request.body!null){httpRequest.extraDatarequest.body.toBytes();// RequestBody → extraData}三个细节expectDataType: ARRAY_BUFFER与 ktor 引擎策略一致避免字符串编码损耗每次createHttp()新会话、回调里destroy()readTimeout 500ms守卫定时器兜底防会话挂起。引擎层桥接的请求生命周期如下成功失败RequesttoOhosMethod / buildHeadercreateHttp() 新会话request() 发起请求结果类型ARRAY_BUFFER 转 ResponseBodyError 转 fail 回调destroy() 释放会话complete / fail 向上送达五、踩坑记录链末端的回调出口最初把 onResponse/onFailure 挂在 Bridge 上导致「谁注册出口」不清重构为 RealAsyncChain 持有整链出口末端经complete/fail送达职责清晰。取消语义CancelToken 命中后回调静默okhttp 的 canceled 分支不回调 onFailure——验收页不可达地址测超时、正常请求测取消。重试的边界只对 5xx 与网络异常重试4xx 不重试对应 RetryAndFollowUpInterceptor 的语义重试计数单独暴露供断言。七、FAQQ1DevEco Studio 26 与旧版本工程能直接互开吗不建议。DevEco Studio 26 对应 HarmonyOS 6.0API 20hvigor 与 SDK 版本跨度较大旧工程建议新建后迁移源码而不是直接升级打开。Q2编译报ohos.net.http找不到检查module.json5是否声明了网络权限ohos.permission.INTERNET以及 SDK 是否为 API 20权限缺失时请求会在运行时失败而非编译期报错。Q3为什么execute()也走异步ArkTS 没有阻塞式网络 API同步语义只能由异步实现「伪装」。语义层保留同步链仅为测试与兼容生产路径请统一用enqueue()。Q4回调里拿不到响应日志也没有优先排查链末端出口是否注册在RealAsyncChain上若出口挂在 Bridge 上取消或异常分支会静默丢弃回调。Q5超时时间设了却不生效ohos.net.http的readTimeout在部分场景下不会主动中断会话因此额外加了readTimeout 500ms的守卫定时器兜底。Q6重试次数怎么断言AsyncRetryInterceptor单独暴露重试计数测试中直接读取该计数即可不必依赖日志字符串匹配。Q7这套结构能复用到其他库吗可以。凡是「链式处理 终端执行」的模型图片加载管道、加解密管道、埋点管道都能套用同一套回调链骨架。八、总结OkHttp 的适配价值不在「发一个 GET」那ohos.net.http一行就够了而在拦截器链的完整语义应用拦截器→重试→桥接→终端的分层、回调世界的等价变换、取消与超时的精确语义。回顾全文可以提炼出三条可复用的经验语义层与引擎层分离。语义层只描述「链怎么走、回调怎么传」引擎层只负责「怎么把 Request 变成一次真实网络调用」。两层解耦后换引擎ohos.net.http→ 其他实现不影响上层拦截器。同步链与异步链双轨并存。生产路径走AsyncInterceptor回调链同步链保留给测试与兼容场景二者共享同一套Request/Response模型避免语义漂移。边界语义要显式化。取消后回调静默、只对 5xx 与网络异常重试、超时用守卫定时器兜底——这些「不显眼」的边界恰恰是适配质量的分水岭也是验收用例该覆盖的地方。这套结构可以直接迁移到任何「链式处理 终端执行」的库图片加载管道、加解密管道、埋点管道。下一篇将继续沿 KMP 鸿蒙适配路线拆解另一个高频三方库的语义复刻。OkHttp 的适配价值不在「发一个 GET」那 ohos.net.http 一行就够了而在拦截器链的完整语义应用拦截器→重试→桥接→终端的分层、回调世界的等价变换、取消与超时的精确语义。这套结构可以直接迁移到任何「链式处理」的库图片加载管道、加解密管道。欢迎加入 KMPCMP 鸿蒙社区https://atomgit.com/CPF-KMP-CMP
三方库适配征文 · 第二批 · 上游 square/okhttp parent-5.5.1适配代码https://atomgit.com/oh-tpc/okhttp摘要本文是「Kotlin Multiplatform for OpenHarmony 实战」系列第 37 篇聚焦 OkHttp 在鸿蒙ArkTS侧的语义复刻。OkHttp 的核心价值在于拦截器链而 ArkTS 没有suspend无法直接照搬 Kotlin 的同步挂起链。本文给出解法回调式异步链——请求沿链向下传递回调响应沿链向上complete/fail送达与同步链的return Response逐行对应。文章依次说明适配分层语义层 引擎层、RealAsyncChain的链末端出口设计、ohos.net.http桥接的三个关键细节ARRAY_BUFFER、会话createHttp/destroy、超时守卫定时器并附环境搭建版本表、踩坑记录与 FAQ。读完可掌握一套可迁移到任意「链式处理」库的 ArkTS 网络适配骨架。目录一、OkHttp 是什么二、适配路线三、环境搭建指引四、核心设计同步链在回调世界的等价物五、引擎层桥接要点六、踩坑记录七、FAQ八、总结一、OkHttp 是什么OkHttp 是 JVM 生态使用量最大的 HTTP 客户端47k stars连接池、HTTP/2 多路复用、拦截器链、透明 GZIP、响应缓存、WebSocket 与同步/异步调用。KMP 生态大量库以其为默认网络层。二、适配路线OkHttpKotlin鸿蒙语义层鸿蒙引擎层Request/RequestBody/FormBodyRequest/RequestBody/FormBody—Response/ResponseBodyResponse/ResponseBody—Interceptor.intercept(chain)Interceptor同步AsyncInterceptor异步BridgeAsyncInterceptorRealInterceptorChainRealInterceptorChain/RealAsyncChain—Call.execute()/enqueue()Call接口异步优先execute 引导用异步OkHttpClient(interceptors)OkHttpClientinstallEngine/addInterceptor—HttpLoggingInterceptor—AsyncLoggingInterceptorRetryAndFollowUpInterceptor—AsyncRetryInterceptorCallServerInterceptor—ohos.net.http桥接整体适配分层如下应用层OkHttpClient语义层Request / Response / Call语义层Interceptor 同步链 AsyncInterceptor 异步链引擎层BridgeAsyncInterceptorohos.net.http 真实网络请求三、环境搭建指引复现本文代码前请先对齐以下工具链版本。版本不一致是 KMP 鸿蒙适配最常见的「跑不起来」原因。组件版本说明DevEco StudioDevEco Studio 26HarmonyOS 6.0 SDK 配套版本本文全部验证基于 DevEco Studio 26工程模板与 hvigor 配置以该版本为准HarmonyOS SDKAPI 20HarmonyOS 6.0ohos.net.http等系统能力随 SDK 提供Kotlin2.1.xKMP 工程与kotlinx-coroutines版本需与之匹配Kotlin Multiplatform 插件2.1.x与 Kotlin 同版本Gradle 中kotlin(multiplatform)版本号Gradle8.9需支持 Kotlin 2.1 与 JDK 17JDK17DevEco Studio 26 内置 JDK 17建议直接使用Node.js18.x 及以上hvigor 构建依赖搭建步骤安装DevEco Studio 26首次启动时按向导下载 HarmonyOS 6.0API 20SDK。用 DevEco Studio 新建一个 Empty Ability 工程确认hvigor与 SDK 版本正常编译。在工程根目录引入 KMP 模块build.gradle.kts中声明kotlin(multiplatform) version 2.1.x并配置ohosArm64/ohosX64目标。将本文的okhttp适配模块作为commonMainohosMain源码集接入同步 Gradle 后即可编译。真机或模拟器运行验收页先测正常请求再测不可达地址的超时与取消分支。开发情况如下官方参考链接DevEco Studio 下载与版本说明https://developer.huawei.com/consumer/cn/deveco-studio/HarmonyOS 开发者文档ArkTS /ohos.net.httphttps://developer.huawei.com/consumer/cn/doc/Kotlin Multiplatform 官方文档https://kotlinlang.org/docs/multiplatform.html本文适配代码仓库https://atomgit.com/wdracky/kmp-ohos-adapters/tree/main/okhttp提示若使用其他 DevEco Studio 版本请以对应版本的 SDK 与 hvigor 为准本文的桥接代码只依赖ohos.net.http的稳定接口跨版本差异主要集中在工程配置而非业务代码。三、核心设计同步链在回调世界的等价物OkHttp 的精髓是拦截器链每个拦截器拿到 Request处理后交给下一个终端拦截器真正发请求。Kotlin 里这是协程挂起函数ArkTS 没有 suspend——解法是回调式异步链// 中间拦截器把新回调向下传递chain.proceedAsync(req,(resp:Response){this.logs.push(-- resp.code);chain.complete(resp);},(err:Error){this.logs.push(-- ERR);chain.fail(err);});// 末端拦截器网络完成后向上送达chain.complete(response);// 或 chain.fail(error)回调沿链向下、响应沿链向上——与同步链的「return Response」逐行对应只是方向变成了回调。语义层同时保留同步链测试用双链并存是 ArkTS 网络适配的通用模式。拦截器链的请求下行与响应上行时序如下ohos.net.http终端拦截器桥接拦截器重试拦截器应用拦截器调用方ohos.net.http终端拦截器桥接拦截器重试拦截器应用拦截器调用方proceedAsync(req, cb)proceedAsync(req, cb)proceedAsync(req, cb)proceedAsync(req, cb)createHttp().request()Response / Errorcomplete(resp) / fail(err)complete(resp) / fail(err)complete(resp) / fail(err)complete(resp) / fail(err)四、引擎层桥接要点consthttpRequest:http.HttpRequest{method:toOhosMethod(request.method),// HttpMethod → http.RequestMethodheader:this.buildHeader(request),// Map → RecordexpectDataType:http.HttpDataType.ARRAY_BUFFER,// 二进制安全readTimeout:this.readTimeoutMs,connectTimeout:this.connectTimeoutMs};if(request.body!null){httpRequest.extraDatarequest.body.toBytes();// RequestBody → extraData}三个细节expectDataType: ARRAY_BUFFER与 ktor 引擎策略一致避免字符串编码损耗每次createHttp()新会话、回调里destroy()readTimeout 500ms守卫定时器兜底防会话挂起。引擎层桥接的请求生命周期如下成功失败RequesttoOhosMethod / buildHeadercreateHttp() 新会话request() 发起请求结果类型ARRAY_BUFFER 转 ResponseBodyError 转 fail 回调destroy() 释放会话complete / fail 向上送达五、踩坑记录链末端的回调出口最初把 onResponse/onFailure 挂在 Bridge 上导致「谁注册出口」不清重构为 RealAsyncChain 持有整链出口末端经complete/fail送达职责清晰。取消语义CancelToken 命中后回调静默okhttp 的 canceled 分支不回调 onFailure——验收页不可达地址测超时、正常请求测取消。重试的边界只对 5xx 与网络异常重试4xx 不重试对应 RetryAndFollowUpInterceptor 的语义重试计数单独暴露供断言。七、FAQQ1DevEco Studio 26 与旧版本工程能直接互开吗不建议。DevEco Studio 26 对应 HarmonyOS 6.0API 20hvigor 与 SDK 版本跨度较大旧工程建议新建后迁移源码而不是直接升级打开。Q2编译报ohos.net.http找不到检查module.json5是否声明了网络权限ohos.permission.INTERNET以及 SDK 是否为 API 20权限缺失时请求会在运行时失败而非编译期报错。Q3为什么execute()也走异步ArkTS 没有阻塞式网络 API同步语义只能由异步实现「伪装」。语义层保留同步链仅为测试与兼容生产路径请统一用enqueue()。Q4回调里拿不到响应日志也没有优先排查链末端出口是否注册在RealAsyncChain上若出口挂在 Bridge 上取消或异常分支会静默丢弃回调。Q5超时时间设了却不生效ohos.net.http的readTimeout在部分场景下不会主动中断会话因此额外加了readTimeout 500ms的守卫定时器兜底。Q6重试次数怎么断言AsyncRetryInterceptor单独暴露重试计数测试中直接读取该计数即可不必依赖日志字符串匹配。Q7这套结构能复用到其他库吗可以。凡是「链式处理 终端执行」的模型图片加载管道、加解密管道、埋点管道都能套用同一套回调链骨架。八、总结OkHttp 的适配价值不在「发一个 GET」那ohos.net.http一行就够了而在拦截器链的完整语义应用拦截器→重试→桥接→终端的分层、回调世界的等价变换、取消与超时的精确语义。回顾全文可以提炼出三条可复用的经验语义层与引擎层分离。语义层只描述「链怎么走、回调怎么传」引擎层只负责「怎么把 Request 变成一次真实网络调用」。两层解耦后换引擎ohos.net.http→ 其他实现不影响上层拦截器。同步链与异步链双轨并存。生产路径走AsyncInterceptor回调链同步链保留给测试与兼容场景二者共享同一套Request/Response模型避免语义漂移。边界语义要显式化。取消后回调静默、只对 5xx 与网络异常重试、超时用守卫定时器兜底——这些「不显眼」的边界恰恰是适配质量的分水岭也是验收用例该覆盖的地方。这套结构可以直接迁移到任何「链式处理 终端执行」的库图片加载管道、加解密管道、埋点管道。下一篇将继续沿 KMP 鸿蒙适配路线拆解另一个高频三方库的语义复刻。OkHttp 的适配价值不在「发一个 GET」那 ohos.net.http 一行就够了而在拦截器链的完整语义应用拦截器→重试→桥接→终端的分层、回调世界的等价变换、取消与超时的精确语义。这套结构可以直接迁移到任何「链式处理」的库图片加载管道、加解密管道。欢迎加入 KMPCMP 鸿蒙社区https://atomgit.com/CPF-KMP-CMP
