山海万灵 HarmonyOS 文化知识实战（08）：API 请求失败时的本地内容降级

网络失败最糟糕的体验不是“加载慢”而是用户已经进入图鉴详情却被一张空白页面打断。山海万灵将远端读取和本地内容拆为两个可替换实现请求失败时保留已知的神兽目录、出处和学习卡并在页面顶部明确标出本地模式与重试入口。先定义远端失败后的最小可用内容降级不是缓存一段提示文案。应用本地目录保留神兽、区域、展厅、学习卡和馆长导览所需字段因此详情页仍能展示应龙名称、原典条目、数字核验说明与知识卡。服务恢复后再回到 HTTP 数据源。async loadBootstrap(): PromiseShanhaiBootstrap { const home await this.apiClient.getJsonApiEnvelopeApiHomeBootstrap(/home/bootstrap) const beasts await this.listBeasts() const regions await this.listRegions() const halls await this.listHalls() return this.mapBootstrap(home.data, beasts, regions, halls) }HttpShanhaiRepository只在 HTTP 响应完整时返回 Bootstrap。请求抛出异常后控制权回到 Fallback Repository由本地实现返回同一份ShanhaiBootstrap形状。降级状态是页面状态的一部分ViewModel 不是只保留一个布尔网络标志而是把数据来源与提示文字放进加载状态。同步横幅依靠这个状态决定是展示在线同步、正在加载还是“本地模式 重试同步”。export interface ShanhaiAppLoadState { phase: LOADING | CONTENT | ERROR message: string isLocalFallback: boolean } const localState: ShanhaiAppLoadState { phase: CONTENT, message: mock-api 暂不可用发现记录已保存到本地内容。, isLocalFallback: true }失败时保留不保留为事实来源用户可执行动作图鉴目录、详情、出处、学习卡远端最新计数与服务端写入结果点击“重试同步”重新拉取当前神兽选择未返回的远端响应继续阅读或返回图鉴本地导览内容外部模型的实时生成结果等服务恢复后再次请求重试沿用同一加载入口重试不直接修改某张卡片而是重新执行数据装载命令。成功后状态回到在线内容再次失败时仍回到可阅读的本地状态避免在“错误”和“空内容”之间抖动。async retrySync(): Promisevoid { this.syncState { phase: LOADING, message: , isLocalFallback: false } try { await this.viewModel.reload() this.syncState this.viewModel.syncState() } catch (_) { this.syncState this.viewModel.syncState() } }在应龙详情页可观察到“本地模式”、失败原因和“重试同步”动作同时存在正文与来源面板没有消失。HTTP 请求生命周期可参考 HarmonyOS NetworkKit 文档。从重试到恢复的用户路径恢复服务后点击重试同步加载入口重新拉取 Bootstrap 并覆盖同步状态请求仍失败时图鉴、出处和已读内容继续可用。用户可以继续阅读也可以在合适时机重新连接而不是在失败页失去上下文。