【HarmonyOS 7新能力｜014】冷启网络预建链入门实战：从能力边界到最小可运行链路

应用冷启动时，首屏业务请求经常要依次经历目标解析、连接建立和安全协议准备。预建链的思路，是在业务已经能确定目标、但真实请求尚未产生时，提前准备可复用连接。不过，"预热连接"不等于"提前发送业务数据"，更不等于绕过用户授权或网络策略。

本文以"首屏确定会访问一个已知服务，用户进入后才请求真实内容"为场景，建立读取策略、校验白名单、启动预热、等待协议就绪、接收业务请求和复用或降级连接的应用侧链路。文中的 ArkTS 类型和状态机属于建议实现，不是华为官方 API；预建链接口、协议、权限和设备范围请以 HarmonyOS 7 / API 26 当前官方资料为准。本文没有完成真机时延、弱网、功耗或隐私验证。

一、先定义预热边界

预建链只准备建立连接所需的网络状态，不携带账号令牌、查询参数、正文或用户操作结果。若某个协议阶段不可避免地暴露目标信息，项目也要在网络与隐私设计中明确评估，而不能把"没有 HTTP 正文"理解成完全没有数据处理。

最小验收条件是：只对白名单目标预热；业务请求仍由正常授权和数据层创建；预热失败不阻塞首屏；目标或网络变化时不复用旧连接；页面退场可取消无用会话；日志不记录敏感地址参数和凭据。

二、目标策略必须是显式白名单

不能根据页面任意输入或跳转链接发起预热。应用内部先定义受控目标：

ts 复制代码

interface PreconnectTarget {
  targetId: string
  scheme: 'https'
  hostAlias: string
  port: number
  policyVersion: string
}

interface NetworkPolicy {
  version: string
  allowedTargetIds: string[]
}

hostAlias 是内部映射标识，不把用户输入直接当主机名。真实地址由受控配置解析，并遵循证书、域名和网络安全规范。

三、连接状态与业务状态分离

预热会话只描述连接是否可用，不保存业务响应：

ts 复制代码

type WarmupPhase = 'idle' | 'resolving' | 'connecting' |
  'ready' | 'failed' | 'expired' | 'cancelled'

interface WarmupSession {
  sessionId: string
  launchId: string
  targetId: string
  policyVersion: string
  phase: WarmupPhase
  createdAt: number
  revision: number
}

业务仓库可以询问是否存在匹配连接，但不能把 ready 当成请求成功。请求状态仍需独立处理加载、错误、空数据和重试。

四、预热前先校验当前条件

预热只有在目标确定、策略有效、网络允许且应用生命周期合适时才启动：

ts 复制代码

function targetAllowed(target: PreconnectTarget, policy: NetworkPolicy): boolean {
  return target.policyVersion === policy.version &&
    target.scheme === 'https' && target.port > 0 &&
    policy.allowedTargetIds.includes(target.targetId)
}

function canWarmup(phase: WarmupPhase): boolean {
  return phase === 'idle' || phase === 'failed' || phase === 'expired'
}

网络不可用或系统策略不允许时直接跳过，不能循环唤醒网络。是否适合蜂窝、漫游、省电或后台场景，必须按真实产品规则与官方能力确定。

五、完整链路始终保留正常建链

启动时读取网络策略并校验目标白名单，之后才创建预热会话。协议就绪后只登记可复用状态；等业务请求真正到来，再核对目标、策略、网络和会话版本。任何条件不匹配，都走正常按需建链。

网络不可用、目标变化或预热超时不应展示成首屏业务错误。预热属于优化路径，失败后清理状态即可；只有真实请求也失败时，页面才进入对应错误与重试状态。

六、复用必须满足完整匹配条件

只比较主机并不够，还应匹配启动会话、策略版本、协议要求、网络身份和有效期：

ts 复制代码

interface RequestContext {
  launchId: string
  targetId: string
  policyVersion: string
  networkId: string
  createdAt: number
}

interface WarmupContext extends WarmupSession {
  networkId?: string
  expiresAt?: number
}

function reusable(warm: WarmupContext, request: RequestContext, now: number): boolean {
  return warm.phase === 'ready' && warm.launchId === request.launchId &&
    warm.targetId === request.targetId && warm.policyVersion === request.policyVersion &&
    warm.networkId === request.networkId && warm.expiresAt !== undefined && now <= warm.expiresAt
}

任何字段不一致都放弃复用，而不是冒险修补。有效期数值需要通过平台行为和实测确定，本文不编造统一参数。

七、并发预热要合并而不是堆叠

同一目标在同一启动会话中只保留一个在途预热。重复调用返回共享结果；目标不同则受并发上限约束：

ts 复制代码

interface WarmupKey {
  launchId: string
  targetId: string
  policyVersion: string
}

function keyOf(value: WarmupKey): string {
  return `${value.launchId}:${value.targetId}:${value.policyVersion}`
}

不要同时预热所有可能服务，这会增加 DNS、连接、内存和功耗开销，挤占首屏真正关键的资源。只有概率高且价值明确的目标进入清单。

八、网络变化立即使旧状态失效

网络从无线切换到蜂窝、代理或 VPN 状态变化时，旧连接可能不再适用。会话接收网络变化事件后递增修订并标记过期，业务请求重新按需建链。

ts 复制代码

function invalidate(session: WarmupSession): WarmupSession {
  if (session.phase === 'cancelled' || session.phase === 'expired') return session
  return { ...session, phase: 'expired', revision: session.revision + 1 }
}

迟到的"连接成功"回调必须带原修订号，不能把已经过期的会话重新写成 ready。

九、四层结构隔离页面与网络

页面层负责首屏状态、业务意图和失败反馈；编排层维护启动阶段、预热会话与超时取消；网络策略层管理目标白名单、连接复用和网络变化；平台适配层封装解析、连接与生命周期能力。

页面不直接创建连接，适配层也不读取账号令牌。真实请求仍经由原有 Repository 或 Service 发出，预热模块只提供匹配连接状态。

十、超时与取消避免无效占用

页面退场、启动会话结束、目标改变或预热超过预算时取消会话。取消操作幂等，并阻止迟到结果进入可复用池。底层操作如果无法立即中断，完成后也只能释放，不能继续发送数据。

超时预算需依据真实网络和设备测试。过短会浪费预热机会，过长会持有无效资源；无论数值如何，真实业务请求都不能无限等待预热结果。

编排层应区分"用户已不需要"和"底层建立失败"。前者直接静默清理，后者只记录优化路径失败；两者都不应触发业务重试弹窗或改变首屏已有内容。

十一、观测指标必须区分收益与代价

至少记录预热尝试、就绪、命中复用、未命中原因、取消和正常建链结果，并按冷启动、网络类型和目标策略版本分组。指标只记录内部目标标识，不记录完整 URL、查询参数、令牌和响应正文。

收益不能只看一次请求变快，还要同时观察额外连接数、失败率、流量、CPU、内存和功耗。没有对照实验与真机数据时，只能说明链路已实现，不能宣称性能提升。

对照实验必须保持构建版本、数据状态、目标服务和操作脚本一致，并分别统计未启用预热与启用预热的分布。只挑选命中样本会高估收益，也会隐藏无效连接的成本。

十二、测试矩阵与落地清单

测试至少覆盖白名单目标、未知目标、无网络、网络切换、重复预热、预热超时、页面退场、目标变化、策略升级、业务请求早于就绪、连接失效和按需降级。每项断言业务请求次数、连接复用结果和资源清理。

集成验证还应覆盖证书失败、代理环境、省电场景、前后台切换与真实冷启动。本文未完成这些测试，不提供时延或命中率结论。

落地前确认官方接口范围；预热不携带业务数据；目标来自白名单；业务请求独立；复用条件完整；重复会话合并；网络变化使旧连接失效；超时可取消；日志最小化；失败始终能回到正常建链。

冷启网络预建链的核心，是把可安全提前的连接准备从真实请求中拆出来，而不是更早采集或发送用户数据。先守住目标、会话、网络和隐私边界，再结合 HarmonyOS 7 的实际能力进行真机测量，优化才有可信价值。

参考资料：

HarmonyOS 开发者能力介绍：https://developer.huawei.com/consumer/cn/features/
HarmonyOS 新特性发布说明：https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/os-new-feature-2600