第1章：本地持久化方案全景 — 方案分类、技术演进与选型核心矛盾
1.1 边界与定义
本地持久化指在终端设备本地（非网络附加存储）完成数据保存与读取的技术组合。其核心边界是：应用沙盒内部、无网络依赖、终端用户独占。典型覆盖范围包括用户偏好、离线缓存、结构化业务数据、日志记录及资源包文件。与远程持久化的本质区别在于信任模型与延迟模型——本地持久化假定存储介质在信任域内且访问延迟通常在毫秒级。
1.2 方案分类与技术对比
根据数据结构模型与查询能力两个维度，主流方案可划分为四大类别：
| 类别 | 代表方案 | 数据结构 | 事务/ACID | 查询能力 | 典型场景 |
|---|---|---|---|---|---|
| 关系型嵌入式 | SQLite / Realm | 关系型表 | 强 (ACID, WAL) | 高 (SQL) | 结构化数据、复杂查询、多表关联 |
| 键值型 | LMDB / LevelDB | 键值对 | 事务性（部分） | 低 (点查/范围扫描) | 缓存、会话状态、配置 |
| 文档型 | Firebase本地 / UnQLite | JSON / BSON | 最终一致性 | 中 (文档内嵌查询) | 非结构化数据、NoSQL 风格 |
| 文件序列化型 | Protobuf / NSCoder | 二进制 / 平面文件 | 无 | 无 | 简单对象保存、游戏资源包 |
选型第一定律：数据查询复杂度决定方案路线。需跨表 Join 时强制选择关系型；仅 key→value 读写时优先选择键值型，避免引入 SQL 引擎带来的计算开销。
1.3 技术演进路线
本地持久化经历了三代范式迁移，当前正进入第四代声明式阶段：
- 1.0 平面文件时代：NSUserDefaults / SharedPreferences，XML/plist 格式，全量加载，无事务。
- 2.0 嵌入式引擎时代：SQLite 成为事实标准，提供完整 ACID 事务、SQL 查询与 WAL 并发模式。
- 3.0 ORM 时代：Room / CoreData 提供类型安全 DAO、自动迁移、响应式观察。
- 4.0 声明式时代：SwiftData / DataStore 利用编译期宏与编译器优化，将持久化逻辑融入数据模型声明。
1.4 全分层架构与数据流
典型本地持久化方案包含四层抽象，上层依赖下层接口，构成完整的数据写入与读取链路。
数据流路径： View → ViewModel → Repository → DAO → ORM → Engine → OS Abstraction → Storage。
控制流核心：写入事务在引擎层完成解析与锁竞争，操作系统抽象层负责页缓存与回写策略，硬件层通过 FTL（闪存转换层）处理磨损均衡与垃圾回收。
1.5 组件职责与信任链路
每一层在其边界内拥有自治权，跨层调用必须遵守信任契约：
- Repository： 统一数据出入口，协调本地与远端数据同步，对上层暴露单一数据源。
- DAO / ORM： 将数据模型映射为引擎层操作语句（SQL 或 KV 命令），维护缓存与对象关系。
- 引擎层： 提供事务原子性、隔离性、持久化保证，管理锁与日志（WAL / UNDO）。
- 操作系统抽象层： 屏蔽文件系统差异，提供零拷贝 I/O（mmap）或缓冲 I/O 选择。
信任链路断裂风险：当应用层绕过 ORM 直接使用原生引擎 API 执行写入时，ORM 内部的缓存与状态可能会与引擎层数据不一致，导致脏读无法被上层观察。跨进程写入时若缺少文件锁协调，极易触发损坏（如 SQLite 的
SQLITE_BUSY 或 SQLITE_CORRUPT）。1.6 选型核心矛盾与风险评估
架构师在选定本地持久化方案时，通常需要面对以下三组不可兼得的矛盾：
矛盾一：写入吞吐量 vs. 事务完整性
LMDB（键值型）在裸写入性能上可达 SQLite 的 3–5 倍（~200K ops/s vs ~40K ops/s），但代价是放弃 SQL 查询能力与多表关联支持。写入密集型场景（如埋点日志、实时传感器数据）建议优先评估键值引擎。
矛盾二：结构化复杂度 vs. 灵活性
SQLite 完全遵循 ACID，适合强一致性需求，但 Schema 变更需要显式迁移（ALTER TABLE），在快速迭代中成为负担。文档型方案允许动态 Schema，却难以保证数据完整性。
LMDB（键值型）在裸写入性能上可达 SQLite 的 3–5 倍（~200K ops/s vs ~40K ops/s），但代价是放弃 SQL 查询能力与多表关联支持。写入密集型场景（如埋点日志、实时传感器数据）建议优先评估键值引擎。
矛盾二：结构化复杂度 vs. 灵活性
SQLite 完全遵循 ACID，适合强一致性需求，但 Schema 变更需要显式迁移（ALTER TABLE），在快速迭代中成为负担。文档型方案允许动态 Schema，却难以保证数据完整性。
风险点清单：
- 损坏风险： 异常断电时 B-tree 结构可能损坏，SQLite 的
PRAGMA integrity_check可做恢复，但键值引擎（LevelDB）的 SSTable 不可变机制天然抗损坏。 - 大事务阻塞： 单次写入超过 1MB 的事务可能导致 WAL 文件急剧膨胀，触发 checkpoint 时阻塞全部读取请求（SQLite 的
WAL模式在 checkpoint 时表现更优）。 - 跨版本迁移： ORM 自动迁移在大型表（>100 万行）上执行
ALTER TABLE耗时可达秒级，必须设计灰度回退策略。
1.7 落地步骤与验收标准
五步落地法：
- 定义数据模型与访问模式： 统计写入频率、读取模式（点查 / 范围扫描 / 聚合查询）、最大数据规模。
- 根据结构化分数选型： 若查询涉及跨表 Join 或聚合函数 → 关系型；若仅 key→value 或范围扫描 → 键值型；若动态 Schema → 文档型。
- 确定并发与同步策略： 选择 WAL 日志模式、设置重试超时（
busy_timeout = 5000）、配置读未提交隔离级别。 - 实现迁移与回滚路径： 为 ORM 的自动迁移编写正向/逆向回调函数，确保灰度期间新旧版本兼容。
- 压力测试与基准建立： 在目标硬件上测量写入吞吐量（QPS）、p95 读取延迟、事务提交耗时。
验收标准：
定量指标示例（以 Android SQLite Room 为例）：
写入测试：1000 条批量插入，平均耗时 < 200ms
点查测试：随机按主键查询，p95 延迟 < 10ms
范围查询：扫描 100 条记录，总耗时 < 30ms
事务提交：单次事务（10 条写入）提交耗时 < 5ms
迁移测试：100 万行表执行 ADD COLUMN，总耗时 < 1s定性验收： 所有数据库操作在 UI 线程 16ms 刷新周期外完成，主线程无法直接持有数据库写锁；异常断电后启动 integrity_check 无损坏记录。