JSON-Schema校验是保障localStorage数据类型安全的最可靠方式：先定义严格可复用schema，再封装带AJV校验的读取函数，支持版本升级迁移，并通过开发/构建/运行时三重保障实现可观测性。
直接用 json-schema 对 localstorage 读取的原始字符串做校验，是保证缓存数据“类型安全”的最可靠方式——它不依赖运行时断言或手动 type-check，而是用声明式规则在解析前就拦截非法结构。
第一步：为业务数据定义严格、可复用的 JSON Schema
不要把 schema 写死在组件里。例如你存储的是用户偏好设置：
{
"type": "object",
"properties": {
"theme": { "type": "string", "enum": ["light", "dark", "auto"] },
"fontSize": { "type": "number", "minimum": 12, "maximum": 24 },
"notifications": { "type": "boolean" }
},
"required": ["theme", "fontSize", "notifications"],
"additionalProperties": false
}
保存为 schema/userPrefs.json，并确保字段名、类型、约束（如 enum、min/max、required）与当前 TypeScript 接口完全对齐。推荐用工具如 ts-json-schema-generator 从 TS 类型自动生成，避免手写偏差。
第二步：封装带校验的 localStorage 读取函数
每次读取都走校验流程，失败则清除无效缓存并返回默认值：
- 先用
localStorage.getItem(key)获取原始字符串 - 尝试
JSON.parse()；若抛错，说明不是合法 JSON → 视为损坏，清空并返回默认 - 用校验引擎（如 AJV）校验解析后的 JS 对象是否符合 schema
- 校验失败 → 清空该 key，返回默认值（如
{ theme: 'light', fontSize: 16, notifications: true }）
示例逻辑（使用 AJV）：
立即学习“前端免费学习笔记（深入）”；
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
import Ajv from 'ajv';
const ajv = new Ajv({ strict: true });
const validate = ajv.compile(userPrefsSchema);
function safeGetUserPrefs(): UserPrefs {
const raw = localStorage.getItem('userPrefs');
if (!raw) return defaultPrefs;
try {
const parsed = JSON.parse(raw);
if (validate(parsed)) return parsed;
} catch (e) {
// JSON parse error or validation failure
}
localStorage.removeItem('userPrefs');
return defaultPrefs;
}
第三步：在版本升级时主动触发 schema 迁移或清理
前端发版后，如果 schema 发生不兼容变更（如字段重命名、类型收紧），旧缓存大概率校验失败，自动降级到默认值即可。但若需平滑迁移（如把 fontSize 从 string 改为 number），可在校验失败后加一层迁移逻辑：
- 检测旧结构特征（如
typeof parsed.fontSize === 'string'） - 执行转换（
fontSize: Number(parsed.fontSize) || 16） - 用新 schema 校验转换后结果，成功则写回 localStorage
迁移逻辑应轻量、幂等，并配日志便于监控迁移成功率。
第四步：开发期与构建期双重保障
仅靠运行时校验还不够：
-
开发时：在 Vite/Webpack 启动时用
json-schema-ref-parser验证所有 schema 文件语法有效 -
构建时：用
ajv-cli或自定义脚本检查 schema 是否能成功编译，防止引入无效规则 - 上线后：上报校验失败事件（key 名 + 错误原因），用于识别高频损坏场景或灰度问题
这样就把“缓存是否可用”从隐式假设，变成了显式、可观测、可修复的工程环节。
