好的实现不会依赖用户反复刷新碰运气，而会让每个阶段有明确输入、输出、超时和终态。 带 hash 的不可变资源适合 cache-first，HTML 需要较新并能离线回退，用户 API 与凭据通常不应进入 Cache Storage。
离线体验必须诚实区分本地可用、等待同步和服务端已确认。缓存版本、命令队列和冲突解决要一起设计，否则重新联网只会放大旧操作与新事实的冲突。
先定义系统契约
先从数据和协议能保证的事实出发，再决定界面承诺。下面的规则都应有明确所有者、边界值和兼容策略，不能只存在于某次代码评审的口头共识里。
- 路由表按 request destination 与 URL 分类，缓存响应前检查 ok、类型和大小；文章用 SWR，导航 network-first 带短超时，API 明确 bypass。
- 先定义正常、降级、取消和失败四类终态，再让界面、存储与指标消费同一状态。
- 上线参数必须有保守默认值、服务端上限和灰度开关，不能把浏览器传来的数字直接当作资源预算。
“Service Worker 缓存策略：Shell、文章和 API 不能一刀切”的交付标准是正常路径可用、异常路径收敛、资源有界，并且用户能理解系统为何采用当前状态。 这样得到的不是演示代码，而是能解释、能降级、能回滚的生产能力。
哪些情况会破坏契约
失败路径需要与成功路径共享同一套状态模型。只弹一个错误提示却不释放资源、不传播终态，下一次恢复就会继承脏状态。
- 对所有 GET cache-first 会永久保存旧 HTML 和敏感 API；缓存 404/521 响应又让故障恢复后用户继续离线错误。
- 刷新或网络切换同时触发两条恢复路径，重复副作用被误当成两次真实用户操作。
- 降级路径从未压测，主路径故障时所有流量同时进入更慢、更昂贵的后备方案。
如何逐条验证契约
发布闸门应包含确定性回归、随机时序探索和真实浏览器组合。发现一次失败后保存 seed 与状态轨迹，让它永久成为可重放用例。
- 对每类资源运行在线、慢网、断网、521、内容更新和缓存满，核对命中、过期、回退、敏感响应与总字节。
- 在操作中途断网、切换网络并恢复，核对两端状态、持久化记录和资源计数最终一致。
- 用故障注入验证告警先于用户投诉触发，并确认值班人员能从有限证据定位到具体阶段。
最终结果应同时满足正确性、可恢复性和可解释性。任何一项只能依赖刷新页面或工程师猜测，都说明协议闭环仍不完整。