QUIC 长连接切网后看似在线却发不出消息：路径迁移、探活和 TCP 降级状态机

Wi-Fi 切到蜂窝后，连接对象仍显示 online，发送队列却一直不出；用户重开页面又恢复。仅用 socket 是否存在判断在线，会漏掉路径已经失效但连接尚未报错的半开状态。

验证边界：资料核对日期为 2026-09-26。本文以华为开发者官网当前可访问的 HarmonyOS 7（API 26）资料为能力边界，代码中的纯函数和状态转换在 Node.js 宿主环境做过断言。当前本机仍是 API 24 SDK，且没有连接 HDC 真机，所以不把宿主断言写成 API 26 编译或真机实测。涉及系统窗口、设备形态、GPU、网络、相机或 3D 重建的接口，正式交付前仍要在 API 26 SDK 与对应真机上补齐编译、日志、性能和异常路径证据。

先复现：不要一上来就改参数

先把触发条件写成可以重复执行的步骤，至少记录系统版本、设备形态、前后台状态和输入数据。一次正常截图不能证明问题已经解决；必须同时保留失败路径、恢复路径和最终状态。Wi-Fi 切到蜂窝后，连接对象仍显示 online，发送队列却一直不出；用户重开页面又恢复。仅用 socket 是否存在判断在线，会漏掉路径已经失效但连接尚未报错的半开状态。

根因与工程模型

连接状态至少区分 ACTIVE、PROBING、MIGRATING、FALLBACK 和 CLOSED。网络变化后先暂停有副作用请求，携带连接世代做路径探测；在截止时间内迁移成功就继续，否则切到 TCP 或重建连接。发送队列中的命令保留稳定 requestId，防止降级时重复执行。

把判断集中在纯函数中，页面只负责采集事实和渲染结果。这样既能在没有真机时验证核心状态转换，也能在接入 API 26 接口后用同一组事件序列回归。

type Link='ACTIVE'|'PROBING'|'MIGRATING'|'FALLBACK'|'CLOSED';
export function onNetworkChange(current:Link):Link {
  return current==='ACTIVE' ? 'PROBING' : current;
}
export function onProbe(ok:boolean,canMigrate:boolean):Link {
  if(ok && canMigrate) return 'MIGRATING';
  return 'FALLBACK';
}

案例一：稳定路径也要验证

Wi-Fi 断开但蜂窝可用。状态进入 PROBING，探测确认新路径可迁移后更新连接世代；旧路径的迟到确认因世代不匹配被忽略。

复现记录需要包含输入、关键状态迁移和最终输出。若实际接口回调顺序与预期不同，应先更新事件模型，而不是在页面里继续叠加延时。

案例二：异常与恢复路径

企业网络阻断 UDP，QUIC 探测连续超时。到达截止时间后进入 FALLBACK，复用同一 requestId 通过 TCP 发送；服务端按 requestId 返回已有结果而不重复写入。

异常路径验收不能停在“没有崩溃”。还要确认用户看见什么、是否可以继续、重复操作会不会产生副作用，以及恢复后状态是否与首次成功一致。

方案对比

观察项	容易出问题的做法	更可靠的做法
在线判断	连接对象存在就是在线	路径探测与截止时间
切网处理	继续向旧队列发送	暂停副作用请求并迁移世代
降级	失败后让用户重试	自动进入 TCP 或重建
幂等	换连接就生成新请求	业务 requestId 跨连接保持

更可靠的方案共同点是：状态有名字、输入有边界、失败可恢复、结果可读回。封装时把系统能力适配层、纯状态层和页面层分开，后续官方接口变化只替换适配层，不把业务判断散落到组件回调。

上线前检查表

• 网络变化会进入显式探测状态。
• 旧连接回调携带世代并可丢弃。
• 探测有截止时间而不是无限等待。
• 降级不改变业务 requestId。
• Wi-Fi、蜂窝和 UDP 受限网络都覆盖。

官方资料与适用范围

• 八月开发者月刊
• HarmonyOS 应用测试服务

官方资料负责说明能力范围，本文代码负责解释工程控制逻辑。由于本机尚未具备 API 26 SDK 与对应真机，正式项目必须补齐接口签名、权限、设备支持范围和真实性能证据后再交付。

结论

这个问题的关键不是再加一个 if，而是把系统信号转换成稳定、可测试、可恢复的业务状态。先复现、再建模、最后用两条不同路径验证，才能让新能力从演示效果变成可长期维护的工程能力。