flutter-persistence

Flutter 持久化

根据数据形态、查询需求、持久性、敏感性、同步和迁移要求选择存储方式。

在选择 API 之前，检查 pubspec.yaml、SDK 约束、已解析的持久化包及其版本、生成的架构策略、现有存储所有者、支持的平台和测试。除非有证据表明需求超出其支持范围，否则应保留已采用的包。

按需选择

• 偏好设置仅用于少量设置，不用于关系型数据或关键领域数据。
• 文件适用于拥有明确原子性和清理机制的文档／二进制数据。
• 当查询、关系、事务、索引或迁移需求有此必要时，使用数据库。
• 少量机密信息应使用平台安全存储；不要把普通应用数据库当作机密保险库。
• 除非现有包无法满足具体需求，否则应予以保留。

建模所有权

定义数据真实来源、缓存新鲜度、写入顺序、冲突处理方式、离线变更、删除语义，以及从损坏或不兼容数据中恢复的方式。将存储模型置于仓库之后，避免架构细节泄漏到组件中。

按需加载参考资料

• 选择缓存键、新鲜度、失效、淘汰、过期数据提示或用户隔离策略时，阅读缓存策略。
• 本地数据和远程数据可能不一致、变更会在离线时排队、后台任务会运行，或需要协调冲突和删除时，阅读离线同步。
• 更改数据库架构、序列化的持久格式、迁移回调或不兼容数据恢复策略之前，阅读架构迁移与恢复。

HTTP 验证器和传输缓存请参考 flutter-networking；图像、组件、滚动或内存缓存性能请参考 flutter-performance。

迁移与安全

在定义迁移和恢复行为之前，将存储状态归类为持久用户数据、持久操作、可丢弃缓存或可重现的派生数据。为架构设置版本，并使用真实的旧版本产物测试每条受支持的升级路径。迁移失败时，绝不要自动销毁持久用户数据；只有明确其所有权和重建来源后，才可以重建可丢弃缓存。避免在日志或纯文本偏好设置中存储访问令牌、密码或敏感个人数据。

验证

针对该功能相关的首次运行、重新打开、升级、写入失败、并发访问、数据损坏、删除以及离线／在线转换进行测试。使用临时数据库或目录确保测试可重复。

来源

• Flutter 持久化指南
• Flutter 离线优先支持