HarmonyOS NEXT 6.1.1 RCP预建连接与蜂窝容灾实战：connectOnly及错误码1007900986处

鸿蒙专家

在构建高频网络通信的鸿蒙应用时，首包时延（RTT）往往是影响首屏渲染和交互流畅度的关键瓶颈。传统的 HTTP/HTTPS 请求在发送业务数据前必须经历 TCP 三次握手和 TLS 密钥协商（HTTPS 场景），这些底层建连开销在弱网或高并发场景下会显著拖慢请求速度。HarmonyOS NEXT 6.1.1（API 24）为 Remote Communication Kit (RCP) 带来了三项核心能力升级：预建网络连接（connectOnly）、全局共享会话复用（DefaultSession）以及蜂窝网络切换失败时的主动报错管控（throwErrorWhenEnableCellularFailed）。本文将从开发者视角解析这些特性的原理与实战用法，并提供可运行的代码片段。

一、预建连接（connectOnly）消除握手延迟
常规 HTTP 请求在收发首个业务字节前，需要完成 TCP 三次握手（1.5 个 RTT）和 TLS 密钥协商（1~2 个 RTT）。在高时延环境（高铁、电梯、地下车库）下，这些握手耗时可能长达数百毫秒。RCP 6.1.1 允许通过设置 Request 对象的 connectOnly 属性为 true，发起一次“零数据传输”的预建连接。该请求只完成底层 TCP 握手和 TLS 协商，之后立即结束，不携带任何应用层 Payload。后续发往相同域名且使用同一会话（Session）的真实请求可以直接复用这条已就绪的物理通道，实现首包零额外建连到达。

2. const request = new rcp.Request('https://example.com', 'GET');
3. request.connectOnly = true; // 声明此请求仅预建通道，不传输业务数据
4. const response = await session.fetch(request);

复制代码

需要注意的是，connectOnly 请求会强制建立一条全新连接，即使当前会话已存在可复用连接。因此它适合在业务闲时预热场景中提前调度，不应在常规请求中高频使用。C NDK 侧对应 HMS_Rcp_SetRequestConnectOnly 接口，同样要求通过 HMS_Rcp_Fetch 异步派发才能实现复用，同步调用 HMS_Rcp_FetchSync 不支持该机制。

二、默认会话（DefaultSession）实现全局连接池共享
旧版本 RCP 中每个组件或子业务独立创建 Session 会导致物理层隔离——即使访问相同域名，跨 Session 也无法复用 TCP 连接。API 24 推荐使用 rcp.getDefaultSession() 获取系统全局唯一的默认会话实例，它在内部指向同一个物理长连接池，支持跨页面、跨组件的连接复用。应用只需在核心 Service 或常驻后台中长期持有至少一个默认会话对象实例（不主动 close），即可让整个应用享受长连接多路复用的吞吐优势。

2. const defaultSession = rcp.getDefaultSession(); // ArkTS 获取全局默认会话
3. // C NDK 对应 HMS_Rcp_GetDefaultSession

复制代码

当应用中所有通过该接口获取的会话句柄都执行 close 后，系统才会释放全局池。因此，若需要持久化复用，切勿轻易释放默认会话的强引用。

三、蜂窝网络切换失败主动报错管控
某些安全敏感性业务（如支付、内网审计）需要强制将请求路径锁定在蜂窝网络（pathPreference: 'cellular'），以防止流量劫持。但若当前设备处于强 Wi-Fi 信号下，蜂窝数据因欠费、基站拥堵或硬件休眠等原因无法在 5~10 秒内激活，旧版本会静默超时或自动回退到 Wi-Fi，给合规审查留下隐患。
API 24 新增 throwErrorWhenEnableCellularFailed 属性，当设置为 true 且蜂窝激活失败时，系统直接抛出专属错误码 1007900986。上层业务可以精准捕获该错误，执行优雅的分流策略（如降级到 Wi-Fi 或备用网络），避免应用挂死。

2. const transferConfig: rcp.TransferConfiguration = {
3.   pathPreference: 'cellular', // 强制蜂窝路径
4.   throwErrorWhenEnableCellularFailed: true // 蜂窝启用失败时主动抛错
5. };
6. const request = new rcp.Request('https://example.com', 'GET');
7. request.configuration = { transfer: transferConfig };
8. try {
9.   const response = await session.fetch(request);
10. } catch (err) {
11.   if (err.code === 1007900986) {
12.     // 执行降级逻辑：切换到 Wi-Fi 或备用网络
13.   }
14. }

复制代码

使用该特性时，建议结合 TransferConfiguration 中的 timeout 字段（如 connectMs: 5000, transferMs: 8000）控制等待时长，防止长时间阻塞。

四、全栈实战：极速连通舱控制台核心逻辑
以下代码片段展示了在 ArkTS 组件中如何整合上述三个特性，构建一个交互式调试面板（完整页面基于 Column 布局，此处只提取关键网络执行器部分）。该面板允许开发者实时切换预建连接、默认会话、蜂窝偏好及报错开关，并捕获错误码 1007900986 执行容灾流转。

2. async executeNetworkRequest() {
3.   const startTime = Date.now();
4.   // 选择会话
5.   let session: rcp.Session;
6.   if (this.useDefaultSession) {
7.     session = rcp.getDefaultSession();
8.   } else {
9.     session = rcp.createSession();
10.   }
11.   // 组装传输配置
12.   const transferConfig: rcp.TransferConfiguration = {
13.     autoRedirect: true,
14.     timeout: { connectMs: 5000, transferMs: 8000 },
15.     pathPreference: this.pathPreferenceCellular ? 'cellular' : 'auto'
16.   };
17.   if (this.pathPreferenceCellular) {
18.     transferConfig.throwErrorWhenEnableCellularFailed = this.throwErrorWhenEnableCellularFailed;
19.   }
20.   // 创建请求并设置 connectOnly
21.   const request = new rcp.Request(this.targetUrl, 'GET');
22.   request.configuration = { transfer: transferConfig };
23.   request.connectOnly = this.connectOnly;
24.   try {
25.     const response = await session.fetch(request);
26.     const latency = Date.now() - startTime;
27.     this.lastLatencyMs = latency;
28.     // 连接复用判断：相同域名且非 connectOnly 模式
29.     if (!this.connectOnly && this.lastDomain === currentDomain) {
30.       this.connectionReuseCount++;
31.       this.connectionStatus = 'REUSED';
32.     }
33.     this.lastDomain = currentDomain;
34.   } catch (err) {
35.     if (err.code === 1007900986) {
36.       // 蜂窝容灾接管：自动切换网络偏好
37.     }
38.   }
39. }

复制代码

通过组合使用 connectOnly 预建连接、全局默认会话复用以及蜂窝激活失败的主动报错，开发者可以在 HarmonyOS NEXT 6.1.1 上显著降低首包时延，同时提升弱网环境下的通信可靠性。建议在关键业务入口（如首页加载、支付节点）提前触发预建连接，并在强制蜂窝路径的场景中开启 throwErrorWhenEnableCellularFailed，以规避静默挂死风险。