Polar 前端实践：localStorage 数据版本化与最小化存储指南

Polar 前端实践：localStorage 数据版本化与最小化存储指南

【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar

本指南围绕 Polar 仓库前端工程规范中的client-localstorage-schema规则展开，讲解如何为 localStorage 键添加版本前缀、只存 UI 真正需要的字段、用 try-catch 包裹所有读写，并结合仓库源码（useLocalStorage.ts、useChartRange.ts、useDismissed.ts、appealCaseUnread.ts、CookieConsent.tsx、GeneralSettings.tsx）展示真实落地写法。读完你将掌握：如何设计带版本号的存储键、如何做 schema 迁移、如何用校验器拦截脏数据，以及如何安全处理隐私/无痕/配额等异常场景。

为什么 localStorage 数据必须版本化与最小化

localStorage 是前端持久化 UI 状态最直接的手段，但它有三个天然缺陷，正是本规则要解决的：

1. 无 schema 契约：localStorage 里存的是纯字符串，任何一次代码变更都可能让旧数据变得不可解析或字段缺失。没有版本号，你无法知道"这份数据是哪个版本的代码写的"。
2. 容量有限：每个源（origin）大约 5MB，而服务器返回的对象往往有 20+ 个字段。把整个响应对象塞进去，既浪费配额，也让序列化/反序列化变慢。
3. 隐私风险：localStorage 是明文存储，把 token、PII（个人身份信息）、内部标志位写进去，等于把敏感数据留在用户磁盘上。

规则的 impact 等级为MEDIUM，其影响面明确为两层：prevents schema conflicts（防止 schema 冲突）与reduces storage size（降低存储体积）。它属于规则库中"Client-Side Data Fetching（客户端数据获取）"章节下的规范（见 规则目录 与 章节元数据）。

带版本前缀的键：让 schema 演进可控

规则给出的核心做法是在键名上直接嵌入版本号，形如userConfig:v2。这样做的好处是：

• 冲突可归因：同一逻辑数据的不同版本并存（userConfig:v1、userConfig:v2），互不覆盖；
• 迁移可编程：旧版本键还在，可以写一次性迁移函数读取并转换；
• 废弃可清理：迁移完成后删掉旧键，不给用户磁盘留垃圾。

下面把规则中的示例补全为一份可直接落地的模块（含注释与边界处理）：

const VERSION = 'v2' // 只存 UI 真正消费的字段 function saveConfig(config: { theme: string; language: string }) { try { localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config)) } catch { // 无痕/隐私模式、配额超限、存储被禁用时都会抛异常 } } function loadConfig() { try { const data = localStorage.getItem(`userConfig:${VERSION}`) return data ? JSON.parse(data) : null } catch { return null // 解析失败一律回退，不向调用方抛错 } } // v1 -> v2 迁移：读取旧数据、转换字段、写入新键、删除旧键 function migrate() { try { const v1 = localStorage.getItem('userConfig:v1') if (v1) { const old = JSON.parse(v1) saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang, }) localStorage.removeItem('userConfig:v1') } } catch { // 迁移失败不应阻断主流程 } }

在 Polar 仓库中，这种"键名前缀 + 作用域"的命名方式被广泛采用，例如：

• 申诉未读计数使用polar:appeal-case-seen:${organizationId}，以组织 ID 做参数化作用域（appealCaseUnread.ts）；
• 图表时间范围使用overview_chart_range:${orgId}（useChartRange.ts）；
• 一次性关闭提示使用dismissed:前缀统一命名空间（useDismissed.ts）。

只存 UI 需要的字段：从服务端响应中裁剪

规则强调"User object has 20+ fields, only store what UI needs"。在 Polar 中的实践同样如此：从完整用户对象中只抽取偏好字段写入存储，而不是整个对象 JSON 化：

// User 对象有 20+ 个字段，UI 只用到 theme 和 notifications function cachePrefs(user: FullUser) { try { localStorage.setItem( 'prefs:v1', JSON.stringify({ theme: user.preferences.theme, notifications: user.preferences.notifications, }), ) } catch { // 静默失败，不影响 UI 主流程 } }

裁剪的依据是"按需读取"：只保留渲染路径真正读取的字段，其余（token、邮箱、内部标志、大数组）一律不落盘。这既压缩了配额占用，也把意外泄露敏感字段的概率降到最低。

try-catch 包裹一切：getItem 与 setItem 都会抛异常

规则特别强调：getItem()和setItem()在无痕/隐私浏览（Safari、Firefox）、配额超限、存储被禁用时都会抛异常，因此所有读写必须包 try-catch。

Polar 的跨端存储封装（clients/apps/app/hooks/storage.ts）在 Web 分支里就做了这样的兜底：

export async function setStorageItemAsync(key: string, value: string | null) { if (Platform.OS === 'web') { try { if (value === null) { localStorage.removeItem(key) } else { localStorage.setItem(key, value) } } catch (e) { console.error('Local storage is unavailable:', e) } } else { // 原生端走 expo-secure-store } }

注意其中两个细节：

• 删除也走 try-catch：removeItem在部分环境下同样可能失败；
• 失败可观测：记录console.error，便于开发期排查，而不是彻底吞掉。

Polar 的工程化封装：useLocalStorage Hook

规则停留在"反例/正例"层面，而 Polar 将它落成了一个可复用的 React Hook（useLocalStorage.ts）。这个 Hook 把本规则的全部要点内化，并额外解决了 React 场景下的同步问题：

• SSR 安全：服务端渲染时window不存在，读取直接返回defaultValue（readFromStorage中的typeof window === 'undefined'分支），避免 hydration 崩溃；
• 跨标签页同步：订阅浏览器原生storage事件（其他标签页写入时本标签页刷新）；
• 同标签页同步：由于原生storage事件不会在当前标签页触发，Hook 定义了自定义事件polar:local-storage-changed，写入后手动dispatchEvent，让同一标签页内多个 Hook 实例保持一致；
• 引用稳定：用模块级 Map 缓存"原始字符串 -> 解析结果"，当底层字符串未变化时返回同一个对象引用，避免useSyncExternalStore因每次JSON.parse产生新对象而无限循环；
• 校验器兜底：通过validate选项对解析结果做类型守卫，不合法数据回退到defaultValue；
• 写入失败静默降级：setItem抛异常时忽略，但仍派发事件让订阅者重新读取，保持 UI 与存储一致。

实际调用方一：图表时间范围（useChartRange）

useChartRange.ts 展示了校验器 + 自定义序列化的完整用法：

const VALID_RANGES = new Set<ChartRange>( Object.keys(CHART_RANGES) as ChartRange[], ) const DEFAULT_RANGE: ChartRange = '30d' const storageKey = (orgId: string) => `overview_chart_range:${orgId}` const isValidRange = (value: unknown): value is ChartRange => typeof value === 'string' && VALID_RANGES.has(value as ChartRange) // 旧版本直接存裸字符串（'30d'、'12m'…），用恒等序列化保持兼容 const serialize = (value: ChartRange): string => value const deserialize = (raw: string): ChartRange => raw as ChartRange export const useChartRange = (orgId: string) => { const [range, setRange] = useLocalStorage<ChartRange>( storageKey(orgId), DEFAULT_RANGE, { validate: isValidRange, serialize, deserialize }, ) // ... }

它同时示范了两条本规则的关键工程技巧：

1. 老数据兼容：历史上键里存的是裸字符串而非 JSON，因此用恒等serialize/deserialize保持旧值可读，避免一次破坏性迁移；
2. 脏数据拦截：isValidRange作为类型守卫，凡是枚举集合VALID_RANGES之外的字符串都会被拒绝并回退到30d默认值——这正是"版本化 + 校验"处理 schema 冲突的落地形态。

实际调用方二：一次性关闭状态（useDismissed）

useDismissed.ts 是"最小化字段"的极致案例：布尔值只存'true'/'false'两个字符，并用dismissed:前缀隔离命名空间，避免调用方短标识互相冲突。

迁移与清理：版本化数据的老化回收

版本化带来的额外义务是及时清理旧键。规则中的migrate()三步走（读旧 → 写新 → 删旧）在 Polar 中有对应实践：useChartRange为了兼容历史裸字符串键，选择了恒等序列化而非重写迁移；而像useDismissed这种每次都是全新命名空间的场景，天然不会积累旧版本数据。

工程上的建议是：

• 升级 schema 时，保留一个版本的旧键迁移窗口，不要立刻删除，给灰度发布留退路；
• 迁移代码要幂等（重复执行结果一致），因为migrate()可能在多个标签页同时跑；
• 迁移完成后删除旧键，避免永久占用配额。

隐私与合规：把敏感数据挡在 localStorage 之外

规则的 Benefits 明确提到"prevents storing tokens/PII/internal flags"。在 Polar 的 Cookie 场景里，可以看到对"该存什么"的刻意控制：

• CookieConsent.tsx 只把cookie_consent（'yes'/'no'）这种非敏感的用户偏好写入 localStorage，且读取时先做typeof localStorage === 'undefined'守卫；
• 当用户选择拒绝时，PostHog 的持久化被切换为'memory'，即分析数据不落盘，从源头避免隐私数据被持久化（见setPersistence的调用）。

这与"最小化存储"原则一脉相承：能不存就不存，必须存就只存 UI 需要的最小集合，敏感数据一律走服务端或安全存储。在 Polar 移动端（clients/apps/app/hooks/storage.ts），原生平台甚至不使用 localStorage，而是走expo-secure-store（Keychain），进一步印证了"敏感数据不进 localStorage"这一准则。

总结：一条可直接套用的检查清单

遵循这套规范，你得到的不仅是"能跑"的 localStorage 代码，而是一套可演进、可迁移、可降级、不泄密的客户端持久化方案——这也正是 Polar 前端规则库把它列为 MEDIUM 影响级最佳实践的原因。

【免费下载链接】polarPolar — A billing platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/po/polar