Flutter on OpenHarmony 数据持久化实战：电子合同场景选型与踩坑

从第一次在模拟器上把Flutter应用跑进OpenHarmony，到真正把完整的电子合同签署App落地，最折磨人的其实不是UI适配，反而是那些看起来没什么技术含量的数据持久化。我最初想得很简单：数据库存一下合同内容，本地存一下PDF，不就完事了吗？真做起来才发现，在OpenHarmony上用Flutter做持久化，坑多且细，而且大部分文档不会直接告诉你答案。

这篇文章就围绕我在电子合同签署App里做数据持久化的完整过程展开，包括方案选型、数据模型设计、三套存储手段的落地细节、安全加固，以及大量实测踩坑后的排查经验。如果你也是用Flutter做OpenHarmony应用，或者正在为跨端持久化方案纠结，这篇文章应该能帮你少走不少弯路。

1. 项目背景与技术选型思路

1.1 电子合同App为什么离不开数据持久化

电子合同签署App和一般工具类应用还不一样，它有一个很核心的特点：状态敏感。合同从创建、填写、待签署、已签署到归档，每一个环节的数据都不能丢。你想想，用户花十分钟填完合同信息，结果App切换后台被系统杀掉，回来发现草稿没了，这种体验在合同场景下是绝对不可接受的。

合同类数据本身的形态也很复杂。除了业务字段（合同编号、标题、双方主体、金额、签署时间），还有关联文件（PDF合同正文）和签名图片（手写签名）。这些数据如果是纯网络侧存储，那确实后端兜底，但合同签署过程中经常有需要本地暂存、离线查看、签署中保活的场景——这也是我们项目里做数据持久化的直接动因。

具体来说，我在这个项目里需要解决这么几类持久化需求：

• 用户登录态、手写签名偏好、合同列表缓存等轻量数据
• 合同草稿、签署记录、签署流程状态等结构化数据
• 签署版PDF正文、电子签名图片等二进制大文件
• 合同关键字段的完整性校验信息，用于防篡改

这几类数据对存储手段的诉求完全不一样，所以不可能用一套方案打天下。

1.2 Flutter on OpenHarmony下的持久化可选方案

先说说Flutter for OpenHarmony这套移植框架的背景。OpenHarmony不是直接跑Flutter的原生引擎，而是通过适配层打通了Flutter的Platform Channel能力，让标准Flutter插件能在OpenHarmony上找到对应的实现。这意味着我们在Flutter生态里用惯了的那套插件体系，很大一部分是可以复用的——但又不是全部都能平迁。

我在选型时认真对比过这几种方案：

我的最终结论是：shared_preferences管配置和用户态，sqflite管合同和签署记录，文件系统管PDF和签名图。这套组合在Flutter生态里是成熟打法，迁移到OpenHarmony之后也基本能跑通。初期我也调研过引入其他重量级数据库方案，但考虑到OpenHarmony适配层的成熟度，还是先把这三件套吃透更实际。

2. 数据模型设计与存储方案确定

2.1 合同业务核心字段怎么拆

数据持久化不能上来直接写代码，先把模型想清楚。电子合同的核心对象是合同以及围绕合同的签署行为。我在设计数据库表结构时，最后落地的是三张主表加一张配置表：

合同主表存的是合同本身的静态信息，包括合同编号、标题、合同类型、甲方乙方主体名称、合同金额、状态、创建时间、更新时间，以及一个内容指纹字段。内容指纹非常关键，当初设计它的原因有两个：一是做合同数据的完整性校验，防止本地数据库被篡改或者同步过程中写坏；二是后续和服务器做增量同步时，通过指纹快速判断文件是否变化。

签署记录表重点记录每一次签署行为，包括关联合同ID、签署人、签署类型（同意/拒绝）、签名图片路径、签署时间、当时的设备标识。这张表是审计追踪的基础，也是合同出现纠纷时的重要证据链，所以我在设计时不允许物理删除，只做逻辑作废。

用户表和配置表就简单了，用户表存登录信息、身份标识和上次登录时间，配置表存一些用户偏好，比如签名笔迹样式、默认合同模板、是否开启离线模式等。

2.2 按数据形态分层存储的方案权衡

表结构确定后，下一步是关于存储位置和存储方式的决策。我把所有数据按形态分成三层，每一层用不同的技术实现：

第一层是长度为几个字节到几十KB的参数数据，比如用户Token、用户偏好、功能开关。这类数据用shared_preferences最合适。它的读写是以Key-Value方式进行的，开销极小，而且写入后缓存在内存里，读取速度非常快，适合高频读取场景。

第二层是结构化业务数据，也就是合同主表、签署记录这类数据。这层用sqflite落库，理由很明显：合同列表需要分页查询，签署记录需要按合同维度聚合，状态流转需要事务保证。这些能力不是KV存储能优雅搞定的。而且数据库有一个额外好处：可以给字段加约束，比如合同编号唯一性、状态字段的合法性校验，这在应用层做纯逻辑判断要繁琐得多。

第三层是PDF合同正文、签名图片等二进制大文件。文件单独落盘，数据库里只存文件路径。为什么不把PDF以BLOB直接塞进数据库？我实测过，几百KB的PDF存库性能还能接受，但合同PDF动辄几MB，再加上签名图片，数据库文件会膨胀得很厉害，备份和迁移都会变得无比痛苦。分开存的好处是：文件可以被单独清理、单独备份，数据库只是做索引和元数据管理。

方案定了之后，还有一个选型原则值得说：能用平台自带的就不要硬造轮子。OpenHarmony在这方面的适配思路和Android挺像，应用沙箱、偏好存储、关系型数据库这些底座能力都有，Flutter插件层做的其实是桥接，所以我优先选择插件生态里有对应移植或适配的方案，而不是自己去写Platform Channel。

3. 持久化实战：三套方案逐个落地

3.1 轻量数据存储：用户态与配置项怎么管

最开始动手的是shared_preferences这部分，因为逻辑最简单，先把它跑通能快速验证整条链路是否正常。

在Flutter for OpenHarmony环境下，shared_preferences要引用适配过的版本。实际使用中注意导入路径可能和标准Flutter不一样，但API层面基本保持一致。我的做法是在项目根目录建了一个storage/local_store.dart，统一封装所有轻量数据的读写，避免业务代码里到处散落Key字符串。

// storage/local_store.dart import 'package:shared_preferences/shared_preferences.dart'; class LocalStore { static const _tokenKey = 'login_token'; static const _userIdKey = 'user_id'; static const _signatureStyleKey = 'signature_style'; static Future<void> saveLoginInfo(String token, String userId) async { final prefs = await SharedPreferences.getInstance(); await prefs.setString(_tokenKey, token); await prefs.setString(_userIdKey, userId); } static Future<Map<String, String?>> getLoginInfo() async { final prefs = await SharedPreferences.getInstance(); return { 'token': prefs.getString(_tokenKey), 'userId': prefs.getString(_userIdKey), }; } static Future<void> clearLoginInfo() async { final prefs = await SharedPreferences.getInstance(); await prefs.remove(_tokenKey); await prefs.remove(_userIdKey); } }

封装的关键点在于：调用方永远不直接感知Key名，以后如果要改Key、加缓存层，只需改动这个文件，不用全局搜索替换。

不过这里我要特别提醒一个在OpenHarmony上的细节：SharedPreferences.getInstance()虽然名字叫getInstance，看起来是同步的，但它实际上有一个异步加载过程。代码写得没问题，但如果你在App冷启动时紧接着调用读取逻辑，可能遇到拿不到最新数据的情况。我当时就碰到过一次：登录成功写入Token，立即跳转页面后读取却为空。排查后发现是写入后没有等待完成就跳转了。所以记住一个原则：登录、登出这种关键状态写入，一定要await完整写完再执行后续动作。

3.2 结构化数据存储：sqflite落地合同与签署记录

重头戏是sqflite。我在标准Flutter项目里用sqflite用得很多，本以为迁移到OpenHarmony很简单，结果还是有一些差异需要注意。首先是插件的引入，其次是路径初始化，最后是数据库版本升级策略。

初始化数据库时，我的做法是在应用启动后异步建库，不阻塞主流程。电子合同App的主路径是登录和合同列表，这两个页面都需要数据库里的数据，所以初始化动作会在App启动早期就触发，但同时保留一个降级逻辑：如果数据库暂时不可用，先走网络拉数据，等数据库就绪后再落库。

// storage/db_helper.dart import 'package:sqflite/sqflite.dart'; import 'package:path/path.dart'; class DbHelper { static final DbHelper _instance = DbHelper._(); DbHelper._(); static const _dbName = 'contract_app.db'; static const _dbVersion = 3; Database? _db; Future<Database> get db async { if (_db != null) return _db!; _db = await _open(); return _db!; } Future<Database> _open() async { final dbPath = await getDatabasesPath(); final path = join(dbPath, _dbName); return openDatabase( path, version: _dbVersion, onCreate: _onCreate, onUpgrade: _onUpgrade, ); } Future<void> _onCreate(Database db, int version) async { await db.execute(''' CREATE TABLE contracts ( id INTEGER PRIMARY KEY AUTOINCREMENT, contract_no TEXT NOT NULL UNIQUE, title TEXT NOT NULL, party_a TEXT NOT NULL, party_b TEXT NOT NULL, amount REAL, status INTEGER NOT NULL DEFAULT 0, content_hash TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL ) '''); await db.execute(''' CREATE TABLE sign_records ( id INTEGER PRIMARY KEY AUTOINCREMENT, contract_id INTEGER NOT NULL, signer TEXT NOT NULL, sign_type INTEGER NOT NULL, sign_image_path TEXT, sign_time TEXT NOT NULL, device_id TEXT, is_deleted INTEGER NOT NULL DEFAULT 0, FOREIGN KEY (contract_id) REFERENCES contracts(id) ) '''); await db.execute(''' CREATE TABLE users ( id INTEGER PRIMARY KEY AUTOINCREMENT, user_uuid TEXT NOT NULL UNIQUE, display_name TEXT, last_login_at TEXT ) '''); } Future<void> _onUpgrade(Database db, int oldVersion, int newVersion) async { // 版本迁移逻辑 } }

这张建表语句我实际是迭代了三次才稳定的。第一次没有加content_hash字段，后来做防篡改校验时需要这个字段，就通过onUpgrade补了一个版本号升级。第二次发现合同编号唯一性必须在数据库层面约束，光靠应用层判断，在并发写入场景下会出现重复数据，所以加了UNIQUE约束。第三次把签署记录的逻辑删除标识加上了，因为审计类数据不适合物理删除。

事务处理是我特别依赖的特性。合同创建时不是只插一行合同记录就完事，有可能要先落一条签署流程记录；合同状态流转时，要同时更新合同状态和插入签署记录，这两个操作必须保证原子性，任何一个失败都要回滚，否则就会出现合同状态已经变了、但签署记录丢了的不一致状态。

// repository/contract_repository.dart class ContractRepository { final DbHelper _dbHelper = DbHelper.instance; Future<void> createContractWithFirstSign({ required Map<String, dynamic> contractData, required Map<String, dynamic> signRecordData, }) async { final db = await _dbHelper.db; await db.transaction((txn) async { final contractId = await txn.insert('contracts', contractData); await txn.insert('sign_records', { ...signRecordData, 'contract_id': contractId, }); }); } }

3.3 合同文件与签名图片：沙箱文件系统存储

文件存储是最后一层，也是最容易在OpenHarmony上踩坑的一层。在Android上，getApplicationDocumentsDirectory()拿到的路径和沙箱模型是稳定且统一的；但在OpenHarmony适配环境下，我遇到的第一个问题就是路径获取的时机和方式。

解决办法是直接用path_provider的API，但要注意确认拿到的路径确实在当前应用沙箱范围内。另外OpenHarmony的文件沙箱策略比Android更严格，不是所有目录都能随便访问，所以优先用官方API拿目录，不要自己去拼路径。

为了管理方便，我在文件存储层做了一个简单的目录规划：

// storage/file_storage.dart import 'dart:io'; import 'package:path_provider/path_provider.dart'; class FileStorage { static Future<String> get contractDir() async { final dir = await getApplicationDocumentsDirectory(); final contractDir = Directory('${dir.path}/contracts'); if (!await contractDir.exists()) { await contractDir.create(recursive: true); } return contractDir.path; } static Future<String> get signatureDir() async { final dir = await getApplicationDocumentsDirectory(); final signatureDir = Directory('${dir.path}/signatures'); if (!await signatureDir.exists()) { await signatureDir.create(recursive: true); } return signatureDir.path; } static Future<String> saveContractFile({ required String fileName, required List<int> bytes, }) async { final dir = await contractDir; final file = File('$dir/$fileName'); await file.writeAsBytes(bytes, flush: true); return file.path; } }

这里有一个非常关键的File写入选项：flush: true。如果不加这个参数，文件写入可能只停留在内核缓存的page cache里，App进程意外结束或者系统杀掉进程后，文件数据可能还没真正落到磁盘。我最初是踩过这个坑的：写签名图片成功、但用户马上锁屏杀进程后，签名图片变成了一张损坏图。排查来排查去，最后发现就是flush参数的问题。业务上签名图片是不可再生的，丢了就得让用户重新签，所以这种关键文件的写入，我全部用了flush等待落盘。

签名图片这种大文件的存储，还有一个细节：写文件时最好加一个download_id或者sign_timestamp到文件名里，避免同名文件互相覆盖。比如用sign_{contractNo}_{timestamp}.png做命名，排查问题时能直接从文件名看出是哪份合同、什么时候签的。

4. 数据安全与异常处理实践

4.1 合同数据完整性校验与基础加密

电子合同和法律效力强相关，所以数据完整性和不可篡改是我额外关注的点。合同一旦签署，任何字段的修改都应该是可被发现的。

我的做法是在合同落库时计算一次content_hash，用的是sha256。计算范围是合同的关键字段拼接后的字符串，包括合同编号、甲乙双方、金额、签署时间。后续每次读取合同详情时，重新计算一遍哈希并对数据库里存的对比，不一致就标记为“数据异常”，打断用户操作。

这个哈希方案不能防止高级攻击者直接改数据库内容后同步改哈希，但它的价值在于发现意外损坏和低级别篡改，同时作为服务器端校验的本地依据。如果和服务器有同步机制，服务端也用同一套计算逻辑再次校验，就能形成双层防线。对大多数电子合同App来说，这个强度已经够了。

Token这类敏感信息我没有明文存，简单处理是存一份加盐哈希，验证时通过比对哈希值判断。真正的安全机制还是要靠服务端Biometric或系统级KeyStore，但在本地持久化层面，至少不要明文暴露Token在SharedPreferences里。

4.2 存储异常时的降级与数据恢复

任何一个长期运行的应用，都不能假设存储层永远不出问题。我遇到过两种比较典型的故障：一种是数据库文件损坏导致openDatabase直接抛异常，另一种是沙箱目录被系统清理导致文件路径失效。

针对第一种情况，我做了启动时的数据库健康检查：openDatabase如果失败，就尝试删除损坏文件并重建库。同时把错误上报到日志系统，便于后续排查。注意删除数据库文件是个危险操作，一定要确认确实打不开、且本地没有未同步的数据时才做。所以我在代码里做了二次确认，读取备份文件是否存在、是否有未上传的合同记录，有的话先走网络恢复。

针对第二种情况，文件路径失效的问题，处理思路是：所有数据库里的文件路径字段，保存的是相对路径而不是绝对路径。绝对路径里带有沙箱根目录，如果系统清理后沙箱路径前缀变化，旧路径就彻底失效了。相对路径搭配应用启动时重新拼接根目录，兼容性会好很多。这也是我在一次应用升级后发现老用户合同附件打不开后总结的教训。

5. 常见问题排查与优化实录

5.1 数据库版本升级引发的字段丢失

第一次做数据库版本升级时我差点闹出事故。当时的场景是在已上线的版本上给contracts表加一个remark字段，我直接在onUpgrade里执行了ALTER TABLE contracts ADD COLUMN remark TEXT，测试也过了，但发布后一部分老用户升级后打开App直接崩溃。

查了半天发现，OpenHarmony上有一部分用户安装的旧版本数据库，表结构和我预想的不完全一样。原因是早先一个测试版本把表的schema写错了，后来虽然修正了建表语句，但老库已经按错误结构建出来了，升级语句再按正确结构去执行就冲突了。

从那以后，我的onUpgrade升级逻辑里加了一整套校验：先查PRAGMA table_info确认当前表结构，再决定要不要执行ALTER；执行完再校验字段确实存在。不依赖对旧版本的假设，每个版本升级都单独验证一次。这个方法虽然啰嗦，但胜在稳。

5.2 SharedPreferences在并发写入时的数据覆盖

SharedPreferences的大坑在于它是一个全局缓存的Key-Value仓库，而它的写入本质上是整文件覆盖。两个地方同时写入不同Key，理论上没问题；但如果一个写Key A，另一个写Key B，写A的线程先读了旧的全量数据，写B的线程后写，最后写A的线程把全量数据写回时，就可能把B刚写入的值覆盖掉。

我是在做“退出登录 + 切换账号”并发场景测试时发现这个问题的。你说巧不巧，两个异步任务分别写Token和用户ID，结果用户ID被旧值覆盖，导致本地登录态错乱。

加固措施是加了一个简单的串行写队列，所有写操作都通过队列排队执行，保证同一时刻只有一个写任务在跑。这个方案成本极低，但彻底解决了并发覆盖问题。另外，把多个相关字段的写入合并成一个批量提交，也能从根源上减少竞态窗口。

5.3 sqflite查询慢的性能调优要点

数据库在数据量超过两三万条合同记录后，列表查询开始有明显卡顿。最初没有做任何索引优化，每次列表查询都是全表扫描加排序，性能瓶颈很快暴露。

优化动作主要有三个：一是给contracts表的status和updated_at字段建立联合索引，让列表页的分页查询直接走索引；二是给sign_records表的contract_id建索引，因为签署记录列表按合同ID聚合是高频查询；三是分页查询使用标准化LIMIT/OFFSET，并限制一次最多加载20条记录，滚动加载时增量获取。

实测下来，最耗时的列表页从最初的800多毫秒降到了100毫秒以内，体感是质的飞跃。调优时我习惯先用EXPLAIN QUERY PLAN看查询执行计划，确认SQL确实走的是索引而不是全表扫描，避免索引建立了但SQL写法不匹配。

5.4 文件写入成功但数据丢失的排查过程

这是我在签名图片存储上踩过最诡异的一个问题。现象是：签名完成提示成功，图片预览也正常，但杀进程重启后，签名图上一次的状态丢了或者图片打不开。

排查过程很有意思。我先确认了文件写入路径没问题、权限没问题、文件也确实生成了。最后通过抓取系统日志发现，问题出在文件写入的同步时机上。Flutter的File.writeAsBytes默认不是同步落盘，数据写到OS缓存就算返回了。进程正常存活时，缓存会慢慢刷盘，你不会感觉到问题；但进程被强杀时，缓存数据直接丢了。

解决方案上面也已经提到，关键写入操作必须带flush: true参数。这也是文件存储实战中性价比最高的一个改动。另外，写完后做一次file.exists()和file.length()的校验，能尽早发现写入问题而不是等用户下次打开App时才发现。

6. 实战心得与后续扩展方向

整套数据持久化做下来，我最大的感受是：持久化方案本身不难选，难的是把细节做好。每一个存储手段的适配、每一个异常分支的处理、每一次版本升级的兼容，这些单看都是小问题，但它们组合起来，才是用户感知到的稳定性。

这里再分享几个我实测下来比较有用的经验。

第一个是关于测试覆盖。我给数据层写了独立的单元测试和集成测试。单元测试主要验证DAO层的CRUD逻辑，集成测试跑在模拟器上验证真实的存储链路。尤其是数据库升级的测试，我把每个历史版本的数据文件都保留了一份，在升级测试里逐个验证老库能顺利升级到新库，这个习惯帮我避开了一次因老版本schema不一致导致的升级崩溃。

第二个是关于初始化时机的把控。数据库初始化和本地文件目录创建应该在App启动早期完成，但不能阻塞主线程。我用的方式是启动后立刻异步执行初始化，同时在业务层做一个简单的“存储就绪”状态标志。业务请求如果早于就绪标志，就等待或者走网络侧策略，这比一上来就强依赖存储逻辑要稳健得多。

第三个是关于存储层的可替换性。我所有业务代码都不直接操作sqflite或者File API，而是通过仓储接口访问。这样做的直接好处是，后来OpenHarmony适配原生文件存储能力时，我只需要替换仓储实现类，业务侧几乎零改动。如果你现在也在做跨端项目，强烈建议从第一天就保持这个原则。

如果项目继续往下走，我会重点做两件事：一是把本地数据和远端存储的同步机制完善，当前是先落库后同步的策略，后续可以加增量同步和冲突检测；二是把合同文件加密存储做深入，当前只是基础哈希校验，后续可以考虑对PDF和签名图做真正的加密落盘，进一步提升安全性。

数据持久化这件事看着基础，做扎实了，整个App的稳定性上限会高很多。希望这篇实战记录对正在折腾Flutter on OpenHarmony的你有所帮助。