BFM Pay

Appearance

附录 G: 网络故障矩阵 ​

定义各种网络故障场景的检测和处理策略

故障类型分类 ​

一级分类 ​

类型说明用户影响
完全离线无任何网络连接高
部分可达部分服务可用中
高延迟响应缓慢中
不稳定间歇性断连低-中
服务端故障服务器不可用高

故障检测 ​

检测方法 ​

方法用途频率
navigator.onLine基础离线检测实时事件
心跳请求服务可用性30s
请求超时监控延迟检测每次请求
错误率统计稳定性评估滑动窗口

检测指标 ​

NetworkHealth {
  isOnline: boolean        // 基础连接状态
  latency: number          // 平均延迟 (ms)
  errorRate: number        // 错误率 (%)
  lastSuccessTime: number  // 上次成功时间
  connectionType: string   // 连接类型 (wifi/4g/3g)
}

健康度评级 ​

评级条件状态
healthyerrorRate < 5% && latency < 1s正常
degradederrorRate < 20% && latency < 3s降级
poorerrorRate < 50% && latency < 10s较差
offlineerrorRate >= 50%

故障场景矩阵 ​

场景 1: 完全离线 ​

检测： navigator.onLine === false

功能处理方式UI 反馈
查看钱包使用缓存显示缓存时间
查看余额使用缓存"离线模式" 标签
发起转账离线签名"待发送" 状态
扫码正常可用无
设置正常可用无

恢复动作：

  1. 检测到网络恢复
  2. 刷新关键数据
  3. 处理待发送队列
  4. 移除离线提示

场景 2: 服务端不可用 (5xx) ​

检测： API 返回 500/502/503

功能处理方式UI 反馈
余额查询重试 → 缓存显示缓存 + 警告
交易历史重试 → 缓存显示缓存
广播交易重试 3 次显示进度
链配置使用本地无

重试策略：

第 1 次重试: 1s 后
第 2 次重试: 2s 后  
第 3 次重试: 4s 后
放弃并使用缓存/提示错误

场景 3: 节点不可用 ​

检测： RPC 请求超时或返回错误

功能处理方式UI 反馈
余额查询切换节点短暂加载
广播交易切换节点短暂延迟
Gas 估算切换节点短暂延迟

节点切换逻辑：

主节点请求
    │
    ├── 成功 ──► 返回结果
    │
    └── 失败
         │
         ▼
    尝试备用节点 1
         │
         ├── 成功 ──► 返回结果 + 标记主节点不健康
         │
         └── 失败 ──► 尝试备用节点 2 ──► ... ──► 全部失败
                                                    │
                                                    ▼
                                              返回错误

场景 4: 高延迟 (>3s) ​

检测： 请求响应时间 > 3s

功能处理方式UI 反馈
页面加载显示骨架屏加载指示器
余额刷新显示旧数据"加载中" 覆盖
交易广播等待进度指示

优化措施：

  • 并行请求改为串行
  • 降低轮询频率
  • 优先使用缓存

场景 5: 网络不稳定 (频繁断连) ​

检测： 5 分钟内断连 > 3 次

功能处理方式UI 反馈
数据同步增加重试"网络不稳定"
实时更新降级轮询更新频率降低
交易广播持久化重试队列状态显示

场景 6: 特定 API 故障 ​

检测： 单个 API 持续失败，其他正常

故障 API处理方式UI 反馈
余额 API缓存 + 标记显示缓存时间
历史 API缓存显示缓存数据
汇率 API缓存隐藏法币金额
链配置本地配置无

恢复策略 ​

自动恢复 ​

场景检测间隔恢复动作
网络恢复实时刷新数据 + 处理队列
服务恢复30s重试失败请求
节点恢复5min切回主节点

恢复后动作优先级 ​

1. [高] 广播待发送交易
2. [高] 刷新当前钱包余额
3. [中] 同步交易历史
4. [中] 更新其他钱包余额
5. [低] 更新链配置
6. [低] 预加载数据

恢复验证 ​

验证项方法
网络真正恢复发送测试请求
数据一致性对比缓存和最新
队列处理完成检查待发送队列

用户通知 ​

通知级别 ​

级别场景展示方式
全局横幅完全离线固定顶部
Toast临时故障自动消失
内联提示特定功能不可用功能旁边
无提示自动恢复的短暂故障静默处理

通知内容 ​

场景消息
离线"当前离线，显示的是缓存数据"
服务故障"服务暂时不可用，正在重试"
高延迟"网络较慢，请耐心等待"
恢复"网络已恢复"

监控指标 ​

需要监控的指标 ​

指标说明告警阈值
离线用户占比当前离线用户数/总用户> 10%
API 错误率失败请求/总请求> 5%
P95 延迟95% 请求的延迟> 3s
节点切换率切换次数/请求数> 20%

故障报告 ​

NetworkFaultReport {
  faultType: FaultType
  startTime: number
  endTime?: number
  affectedFeatures: string[]
  userActions: string[]
  recoveryMethod: string
}

测试场景 ​

必须测试的场景 ​

场景测试方法验证点
启动时离线断网后启动显示缓存
使用中断网拔网线/开飞行及时提示
慢速网络节流 3G不卡死
节点故障Mock 返回错误自动切换
恢复后同步断网→操作→恢复数据同步

自动化测试 ​

测试结构:
describe('Network Faults', () => {
  describe('Offline Mode', () => {
    it('shows cached balance when offline')
    it('queues transactions for later')
    it('syncs when back online')
  })
  
  describe('Node Failover', () => {
    it('switches to backup node')
    it('returns to primary when healthy')
  })
})

本章小结 ​

  • 完整覆盖各种网络故障场景
  • 每种故障都有明确的检测和处理方式
  • 自动恢复优先，必要时通知用户
  • 完善的监控和告警机制
  • 测试场景覆盖所有故障类型

Released under the MIT License.

Copyright © 2025 BioforestChain