Skip to content

Persistent State:带版本、期限与隐私边界的客户端恢复 ​

持久化层保存的是某一时刻、某一 Schema 版本的可恢复快照,而不是自动同步的权威事实。恢复路径必须依次完成读取、解析、版本识别、迁移、校验和过期判断,任一步失败都应回退到安全默认值。

前置知识与能力边界 ​

本文处理 Web Storage、IndexedDB 与前端快照恢复;服务端数据库、离线优先同步协议另行讨论。

1. 定义、所有权与数据流 ​

Persistent State 是跨页面重载或会话保留的客户端状态。持久化不是给所有 state 加 localStorage;它需要明确存储介质、序列化格式、版本迁移、过期、并发和隐私边界。

mermaid
flowchart LR
    A0["内存状态"] --> A1
    A1["白名单投影"] --> A2
    A2["序列化与版本"] --> A3
    A3["存储介质"] --> A4
    A4["校验迁移"] --> A5
    A5["恢复内存"]

Persistent State 是经白名单投影、版本化和运行时校验后可跨重载恢复的客户端快照。存储介质只是最后一步,迁移、期限、冲突和隐私决定它能否安全恢复。

2. 关键机制 ​

2.1 介质选择 ​

localStorage 同步且小型,IndexedDB 异步并适合结构化大数据,cookie 随请求发送。

若边界缺失,大对象频繁写 localStorage 阻塞主线程。

验证:性能记录写入耗时和配额错误。

2.2 白名单 ​

只投影恢复必要字段,不序列化整个 store。

若边界缺失,令牌、错误对象和临时 UI 被保存。

验证:扫描存储内容和字段清单。

2.3 schemaVersion ​

每个持久化文档含版本,迁移函数逐级转换。

若边界缺失,发布后旧数据使应用崩溃。

验证:用各历史 fixture 启动。

2.4 运行时校验 ​

JSON.parse 只保证语法,不保证形状和取值。

若边界缺失,类型断言接受损坏数据。

验证:畸形 fixture 回退默认。

2.5 过期 ​

expiresAt 按业务期限失效,使用绝对时间并考虑时钟偏差。

若边界缺失,永久草稿使用过期规则。

验证:虚拟时钟测试边界。

2.6 原子性 ​

写临时记录后切换指针,或利用 IndexedDB transaction。

若边界缺失,写一半留下不可解析文档。

验证:中断写入后恢复旧快照。

2.7 多标签页 ​

storage/BroadcastChannel 通知变化,需定义冲突策略。

若边界缺失,两个标签页最后写覆盖草稿。

验证:版本号或更新时间冲突提示。

2.8 序列化 ​

Date、Map、BigInt、File、函数不能靠普通 JSON 无损恢复。

若边界缺失,恢复后 Date 变字符串导致比较错误。

验证:往返测试每个字段类型。

2.9 加密边界 ​

客户端加密密钥若同在页面,不能抵抗 XSS;不要持久化高敏秘密。

若边界缺失,把 base64 当加密。

验证:威胁模型审查攻击者能力。

2.10 清理 ​

登出、租户切换、过期和版本废弃都触发删除。

若边界缺失,共享设备暴露前一用户数据。

验证:端到端测试登出后存储为空。

3. 持久化文档而不是直接存 Store ​

文档至少包含 schemaVersion、savedAt、可选 ownerId 和 value。写入前从内存状态投影允许字段;读取先 JSON 解析,再做运行时 schema 校验,然后逐版本迁移。任何一步失败都回退安全默认并删除或隔离坏记录。TypeScript 类型断言不会验证磁盘中的旧 JSON。

4. 保存、恢复和失效顺序 ​

  1. 启动先确定当前用户与租户命名空间,禁止读取前一主体的 key。

  2. 读取文档并限制尺寸,解析、校验版本和 expiresAt。

  3. 迁移函数逐级执行且保持纯净,迁移失败不写回半成品。

  4. 恢复内存后才建立跨标签订阅,避免初始化消息覆盖本地快照。

  5. 登出、过期、未知版本和租户切换都清理记录与广播状态。

5. 应用案例一:编辑器草稿 ​

  1. 编辑器只投影 title、body、baseRevision,排除 File、AbortController 和上传 URL。

  2. 空闲防抖保存到 IndexedDB transaction,保存状态有 pending/saved/failed。

  3. 恢复时请求服务端 revision;相同则应用草稿,不同进入冲突界面。

  4. 注入配额错误,编辑继续留在内存并显示未保存。

  5. 关闭写入中页面后,重新打开只能得到完整旧文档或完整新文档。

结果:同版本可直接恢复,不同版本进入冲突选择。

失败分支:配额满时继续编辑并显示未保存状态,不能反复同步阻塞。

6. 应用案例二:界面偏好 ​

  1. 主题保存 system/light/dark 枚举而不是计算颜色。

  2. v1 的 compact:boolean 迁移为 v2 density 枚举。

  3. BroadcastChannel 消息带 revision 和 sourceTab,接收方不回播同一版本。

  4. 两个标签并发修改时按产品规则提示或比较 revision,不能默认为最后写胜。

  5. 未知主题值回退 system,并从 DOM class 白名单生成样式。

结果:重载前后稳定,跨标签页同步偏好。

失败分支:未知枚举回退 system,不把非法字符串注入 className。

7. TypeScript 核心实现 ​

下面代码把编码、版本、迁移和过期策略封装成持久化协议。具体存储介质留在适配器中,以便用内存实现测试旧版本、损坏内容和容量错误。

tsx
type PreferenceDoc = {
  schemaVersion: 2;
  savedAt: number;
  value: { theme: "system" | "light" | "dark"; density: "compact" | "comfortable" };
};

export function readPreferences(storage: Storage, now: number): PreferenceDoc["value"] {
  const fallback = { theme: "system", density: "comfortable" } as const;
  const raw = storage.getItem("preferences");
  if (!raw) return fallback;
  try {
    const doc: unknown = JSON.parse(raw);
    if (!doc || typeof doc !== "object") return fallback;
    const d = doc as Partial<PreferenceDoc>;
    if (d.schemaVersion !== 2 || !d.value || typeof d.savedAt !== "number") return fallback;
    if (now - d.savedAt > 180 * 24 * 60 * 60 * 1000) return fallback;
    return d.value;
  } catch {
    return fallback;
  }
}

从存储读取的数据不再受编译期类型保证,必须先解析、校验版本再迁移。测试要覆盖非法 JSON、未知版本、跨标签页写入和迁移中断,失败时安全回退而非带病使用。

8. 方案选择 ​

方案适用条件成本与限制
内存只需当前页面重载丢失但最安全简单
localStorage小型、低频、同步偏好阻塞、字符串、配额和 XSS 可读
IndexedDB较大结构化数据与事务异步 API、迁移和清理更复杂

只有刷新后仍有价值、可安全落盘且有明确过期规则的状态才应持久化。敏感凭据、可重新查询的远端缓存和瞬时交互状态不应因使用方便而进入 localStorage。

9. 调试与失败注入 ​

现象检查修正
启动白屏JSON.parse 或字段访问未捕获校验并回退
升级后值错缺少版本迁移历史 fixture 测试
输入卡顿每键同步写 localStorage防抖或 IndexedDB
共享设备泄密登出未清理按用户命名空间并删除
两标签覆盖无冲突协议revision 比较和提示
配额错误循环写失败仍高频重试降级内存并通知
时间字段比较错Date 被序列化为字符串显式 epoch 或 codec
XSS 读到 token高敏数据被持久化使用 HttpOnly 会话并最小化存储

先读取原始存储值和版本号,再逐步运行解码、迁移、校验与过期判断,最后检查多标签页事件是否覆盖了更新版本。失败信号是启动崩溃、日期变字符串、旧字段静默丢失或敏感值可被脚本读取;用损坏夹具、迁移矩阵和安全扫描验证。

10. 性能、安全与运维边界 ​

  • 任何持久化 schema 都需版本、校验、迁移和安全默认。
  • 写入捕获 QuotaExceededError 和不可用存储环境。
  • 登录用户数据按用户和租户隔离命名空间。
  • 登出清理存储、缓存和跨标签广播状态。
  • 敏感令牌优先使用服务端会话与 HttpOnly cookie。
  • 大数据使用 IndexedDB transaction 并做失败恢复。
  • 后台标签页同步设置冲突和回环保护。
  • 记录迁移失败率和配额错误,不记录正文内容。

生产验证至少记录一次正常路径和一次故障路径;对“Persistent State”的结论必须能关联到日志、Profile、网络记录或自动化测试。

11. 与其他架构模块集成 ​

  • Global State 只把白名单切片交给持久化适配器。
  • Form State 的 dirty 草稿需要 revision 冲突处理。
  • URL 显式值优先于本地偏好默认。
  • Server State 缓存持久化要尊重用户隔离和 stale 规则。

集成时 store 仍是运行期所有者,持久化层只保存带版本的快照并在启动时恢复一次。服务端会话和查询缓存分别维护自己的真实性,不能用本地快照越过鉴权或覆盖新鲜远端数据。

12. 综合练习 ​

实现版本化草稿存储,覆盖 v1→v2 迁移、过期、配额失败、双标签冲突和登出清理。

验收标准 ​

  • [ ] v1、v2、损坏和未来版本 fixture 均有结果。
  • [ ] 配额失败不阻塞编辑且不无限重试。
  • [ ] 双标签消息无回环并有冲突策略。
  • [ ] 登出清理用户与租户命名空间。
  • [ ] 存储扫描不含令牌、密码和文件句柄。

13. 存储故障矩阵 ​

故障恢复行为证据
JSON 被截断捕获解析错误并回退默认损坏 fixture 不白屏
schemaVersion 过新保留或隔离记录,不用旧代码猜字段降级版本启动测试
expiresAt 已过删除并重新初始化虚拟时钟边界测试
QuotaExceededError降级内存,停止高频重试写入次数与用户提示
storage 被浏览器禁用能力检测后继续运行隐私模式测试
两标签同 revision进入冲突策略并发自动化记录

客户端可读取的加密密钥也能被同源 XSS 使用,因此加密 localStorage 不能把访问令牌变成安全会话。高敏凭证优先由服务端会话和 HttpOnly cookie 管理。

14. IndexedDB 事务与升级 ​

IndexedDB 的 schema 变化在 versionchange 事务中执行。升级回调不能等待任意网络请求;对象仓库与索引修改必须在升级事务存活期间完成。其他标签页持有旧连接会阻塞升级,因此应用应监听 versionchange 并关闭旧连接,同时向用户提示刷新。

草稿正文和元数据需要原子提交时放在同一 transaction。若正文成功而 revision 失败,恢复时无法判断草稿对应哪个服务端版本。测试在第二次 put 前主动 abort,重新读取应仍得到旧的完整文档。

大文档不要每个键击完整 JSON 序列化。记录一次 100KB、1MB 草稿的序列化和写入耗时,在空闲窗口防抖保存;页面隐藏时尝试最后一次短写,但不能承诺浏览器一定完成。UI 用最后成功 savedAt 表示保存证据,而不是在调用 put 时立即显示“已保存”。

15. 恢复结果的可观察状态 ​

恢复不是同步布尔值。界面至少区分 loading、none、restored、conflict 和 failed:没有草稿可以直接开始;恢复成功显示保存时间;冲突让用户比较;读取失败允许忽略坏记录。

恢复期间禁止把空初始表单自动保存回存储,否则会在异步读取完成前覆盖旧草稿。先完成读取和迁移,再启用保存订阅。测试把读取延迟 500ms,确认期间没有 write 调用。

来源 ​

从前端走向软件产品工程的长期路线图。