合理的keyPath是IndexedDB高效运行的基础，它决定主键生成、索引使用、插入校验及升级稳定性，需匹配业务读写模式；须符合JS标识符规则，嵌套路径需数据稳定，结合索引协同优化查询。
设计合理的 keyPath 是 IndexedDB 高效运行的基础。它不只决定主键怎么生成，更直接影响查询是否能走索引、数据能否正确插入、以及后续升级是否稳定。关键不在“能不能用”，而在“是否匹配业务读写模式”。
明确 keyPath 的作用和限制
keyPath 是一个字符串路径（如 'id' 或 'user.profile.email'），用于从对象中提取主键值。它必须符合 JavaScript 标识符规则：不能含 @、&、空格、中划线等特殊字符；也不能以数字开头。例如 { "order-id": 123 } 中的 "order-id" 无法直接作 keyPath，需预处理为 orderId 或 order_id。
- 设了 keyPath 且未启用 autoIncrement → 插入时必须提供该字段，否则报错
- 设了 keyPath 且启用 autoIncrement → 若插入对象不含该字段，IndexedDB 自动补上递增值；若已存在，则以对象值为准（可能冲突）
- 不设 keyPath 但启用 autoIncrement → 主键由系统隐式分配（从 1 开始的整数），不存入对象本身，适合纯内部标识场景
按业务场景选 keyPath 类型
没有通用最优解，只有适配当前需求的合理选择：
-
需要业务可读性或全局唯一性（如订单号、UUID、手机号）→ 用字符串字段作 keyPath，关闭 autoIncrement。例如：
{ keyPath: 'orderId' }，插入前确保 orderId 已生成且唯一 -
仅需简单序号做本地标识（如草稿 ID、临时列表项）→ 用
{ keyPath: 'id', autoIncrement: true }，省心且避免重复逻辑 -
完全不想在数据里暴露 ID 字段（如日志记录、埋点事件）→ 省略 keyPath，只写
{ autoIncrement: true }，主键由 IndexedDB 隐式管理，数据对象保持“干净”
嵌套字段与复合结构要谨慎
支持点号路径（如 'address.city'），但前提是数据结构稳定。一旦后端返回字段缺失（如 address 为 null），取 keyPath 会失败，导致 add/put 报错。
立即学习“前端免费学习笔记（深入）”；
- 优先扁平化数据：入库前把 { user: { id: 1, name: 'A' } } 转成 { userId: 1, userName: 'A' }
- 必须用嵌套路径时，确保上游数据强约束，或在存储前做兜底校验（如
obj?.user?.id ?? generateId()） - 避免用数组索引路径（如 'items.0.name'），IndexedDB 不支持动态下标解析
配合索引提升查询效率
keyPath 决定主键，而索引（createIndex）决定非主键字段怎么查。二者协同才能发挥最大效能：
- 高频按用户查数据？建索引
createIndex('byUserId', 'userId')，别依赖主键扫描 - 常查“状态 + 时间”组合？建复合索引
createIndex('byStatusTime', ['status', 'createdAt'])，注意等值字段（status）在前 - 主键本身已是高频查询条件（如通过 ID 查单条）→ 不用额外建索引，get() 就是 O(1) 操作
不复杂但容易忽略：keyPath 和索引定义都在 onupgradeneeded 中一次性确定，后续无法修改。上线前务必结合真实查询日志和数据样本验证设计是否覆盖核心路径。
