【HarmonyOS 7新能力｜040】QUIC长连接工程封装：把接入逻辑放进可维护的分层结构

即时消息、协同编辑和实时状态都依赖长连接，但移动网络会频繁切换：设备离开 Wi-Fi、蜂窝信号抖动、应用进入后台，都可能让"看似在线"的连接已经无法交付消息。QUIC 提供的能力可以改善部分传输问题，但协议优势不会自动解决鉴权续期、消息幂等、断线补偿与生命周期管理。工程上必须把"连接存在"升级为"业务消息可可靠交付"。

说明：本文的 QuicTransportPort、SessionOrchestrator 是教学抽象，不对应 HarmonyOS SDK 的真实接口。QUIC 版本、平台能力、后台限制、网络权限与 API 签名，请以当前官方文档、目标 SDK 和服务端实现为准。

1. 分清传输连接与业务会话

传输层连接解决字节如何送达，业务会话还包含用户身份、房间、订阅范围、游标和权限。网络路径变化后，底层可能继续连接，但业务鉴权已经过期；反过来，连接重建后也可以恢复同一个业务会话。

ts 复制代码

export interface BusinessSession {
  sessionId: string
  principalId: string
  subscriptions: readonly string[]
  lastAckCursor: string
  authExpiresAt: number
  state: 'idle' | 'connecting' | 'active' | 'recovering' | 'closed'
}

将两者拆开后，页面只观察业务状态，不根据 socket 回调直接显示"在线"。

2. 四层架构稳定依赖关系

业务页面发送命令并消费领域事件；会话编排层管理状态机、鉴权和恢复；传输适配层封装 QUIC 连接、流与路径事件；消息与状态仓库保存待发送消息、确认游标和恢复快照。

ts 复制代码

export interface QuicTransportPort {
  connect(options: TransportOptions): Promise<TransportHandle>
  send(handle: TransportHandle, frame: Uint8Array): Promise<void>
  close(handle: TransportHandle, reason: string): Promise<void>
}

export interface MessageStore {
  enqueue(message: OutboundMessage): Promise<void>
  acknowledge(messageId: string): Promise<void>
  listPending(sessionId: string): Promise<OutboundMessage[]>
}

适配器不解释业务消息，仓库不持有平台连接对象，编排层通过端口协调二者。

3. 状态机比回调堆叠更可靠

连接流程至少包含建立、鉴权、活跃、迁移、恢复、离线和关闭。所有平台回调先转成领域事件，再由归约器决定新状态，避免多个回调同时修改页面变量。

ts 复制代码

export type SessionEvent =
  | { kind: 'CONNECT_REQUESTED'; at: number }
  | { kind: 'TRANSPORT_READY'; connectionId: string; at: number }
  | { kind: 'AUTH_ACCEPTED'; expiresAt: number; at: number }
  | { kind: 'PATH_CHANGED'; epoch: string; at: number }
  | { kind: 'CONNECTION_LOST'; reason: string; at: number }
  | { kind: 'CLOSE_REQUESTED'; at: number }

非法转换直接拒绝并记录，例如 closed 状态不能因迟到回调重新变为 active。

4. 鉴权绑定业务会话而非单条流

连接成功后应完成业务鉴权，绑定主体、会话和订阅范围。认证令牌只在安全服务中获取，并通过受控握手消息传递；页面与普通日志不接触令牌。

ts 复制代码

export interface AuthEnvelope {
  sessionId: string
  clientNonce: string
  requestedScopes: readonly string[]
  resumeCursor?: string
  protocolVersion: number
}

服务端返回确认后才进入活跃态。令牌即将过期时提前刷新，刷新失败进入受控恢复，而不是继续把消息写入失效会话。

5. QUIC长连接状态闭环

主流程依次建立传输、绑定鉴权、心跳保活、感知路径变化、恢复会话并补偿未确认消息。离线、超时或服务拒绝进入不同分支，不能统一无间隔重连。

ts 复制代码

export type RecoveryDecision =
  | { action: 'migrate'; pathEpoch: string }
  | { action: 'reconnect'; delayMs: number }
  | { action: 'waitForNetwork' }
  | { action: 'close'; reason: string }

决策函数依据网络状态、失败类型、重试次数和应用生命周期生成结果，便于单元测试。

6. 心跳用来验证业务活性

系统层连接存在不代表对端业务仍可响应。心跳帧带会话 ID、序列和当前确认游标，对端返回对应确认。频率根据前后台、网络类型和业务实时性调整。

ts 复制代码

export interface HeartbeatFrame {
  sessionId: string
  sequence: number
  lastAckCursor: string
  sentAt: number
}

function isHeartbeatExpired(sentAt: number, now: number, timeoutMs: number): boolean {
  return now - sentAt >= timeoutMs
}

具体间隔要遵循平台后台规则和实机功耗测试。不要用过密心跳掩盖状态机缺陷。

7. 网络切换优先迁移，失败再重连

Wi-Fi 与蜂窝切换时，编排器收到路径代次变化。若平台与连接状态允许，适配器尝试迁移；迁移成功保留业务会话和游标，失败才进入重连。

ts 复制代码

export interface PathSnapshot {
  epoch: string
  type: 'wifi' | 'cellular' | 'unknown'
  available: boolean
  changedAt: number
}

async function onPathChanged(path: PathSnapshot): Promise<void> {
  if (!path.available) return session.goOffline()
  const migrated = await transport.tryMigrate(path).catch(() => false)
  if (!migrated) await recovery.scheduleReconnect('MIGRATION_FAILED')
}

网络回调可能抖动，使用 epoch 去重，旧路径结果不得覆盖新路径状态。

8. 退避重连要区分错误类型

无网状态等待网络恢复；临时超时使用带随机扰动的指数退避；鉴权拒绝停止自动重连并刷新身份；协议不兼容直接关闭并提示升级。所有错误都重连会造成电量与服务端压力。

ts 复制代码

export function nextDelay(attempt: number, baseMs: number, capMs: number): number {
  const exponential = Math.min(capMs, baseMs * 2 ** attempt)
  const jitter = Math.floor(Math.random() * Math.max(1, exponential / 4))
  return exponential - jitter
}

重试计数在稳定活跃一段时间后再清零，避免连接刚恢复就断开时重新从最激进频率开始。

9. 消息交付依赖幂等与确认

长连接恢复时，客户端无法仅凭发送成功判断服务端是否处理。每条需要可靠交付的业务消息使用稳定 messageId，先写本地队列再发送，收到业务 ACK 后移除。

ts 复制代码

export interface OutboundMessage {
  messageId: string
  sessionId: string
  topic: string
  payloadRef: string
  createdAt: number
  attempts: number
}

服务端同样按 messageId 去重。对于天然可覆盖的状态消息，可以只保留最新版本；聊天、交易类消息则使用严格序列和业务规则。

10. 断线补偿从确认游标继续

恢复后客户端提交最后确认游标，服务端返回缺失区间。客户端按序应用并持久化新游标，重复事件由事件 ID 去重。若游标过期，则走全量快照同步，而不是猜测缺失内容。

ts 复制代码

export interface ResumeRequest {
  sessionId: string
  lastAckCursor: string
  clientEpoch: string
}

export interface ResumeResult {
  mode: 'delta' | 'snapshot'
  nextCursor: string
  eventRefs: readonly string[]
}

补偿完成前页面可显示"同步中"，不能提前宣称实时状态已恢复。

11. 生命周期、资源与隐私

应用进入后台后是否保持连接，取决于真实业务、平台规则和用户可感知场景。无持续需求时主动关闭，保存游标并在前台恢复；不得通过隐藏方式规避后台限制。

ts 复制代码

export interface SessionPolicy {
  keepAliveInBackground: boolean
  idleTimeoutMs: number
  maxPendingMessages: number
  payloadTtlMs: number
}

队列设置容量与 TTL，退出账号时清理会话、令牌引用和待发敏感消息。诊断日志只记录状态、错误码和耗时，不记录完整载荷与认证信息。

12. 验收清单与总结

测试覆盖 Wi-Fi/蜂窝切换、离线恢复、弱网抖动、心跳超时、鉴权过期、服务拒绝、重复消息、ACK 丢失、游标过期和前后台切换。确认无网时不忙重试、重连后消息不重复、补偿完成前状态不误报，并在目标设备上观察功耗、内存与长时间稳定性。

QUIC 能提供更灵活的传输基础，但长连接可靠性最终来自业务闭环：传输与会话分离、状态机统一、路径迁移优先、错误分类退避、消息幂等确认、游标补偿恢复。把这些责任放进清晰分层后，网络变化才不会扩散成页面层的随机故障。