在 OpenHarmony 上做便单类应用最难的部分往往不是界面而是数据怎么稳定地存下来、怎么组织、怎么管理。Flutter 负责 UI 层很顺手但持久化不能只靠内存里的 List必须落到本地数据库。这篇内容围绕“基于 Flutter × OpenHarmony 的便单服务类”这个项目把便单的持久化存储与管理实践完整拆开从选型、建表、桥接、CRUD、事务到回收站和备份一步步讲清楚适合正在折腾 Flutter 跨端适配 OpenHarmony 的开发者参考。1. 项目整体思路先搞明白便单场景为什么卡在存储上1.1 这个项目到底要解决什么问题便单应用可以理解成“便签 任务清单”的组合体核心操作对象是一张便单通常包含标题、正文、创建时间、提醒时间、所属分组、标签、置顶状态、删除状态等属性。用户每天会新建若干条便单会频繁修改标题、移动分组、搜索历史内容偶尔还会误删后从回收站找回来。这些行为看起来简单但落到技术实现上就变成了一连串必须认真对待的问题数据用什么结构保存写入和读取的性能怎么保证列表分页怎么处理删除是物理删除还是软删除数据升级时旧版本内容怎么兼容我最初做这个项目是需要在 OpenHarmony 设备上提供一套可离线使用的便单服务模块。UI 层选 Flutter是因为团队本身跨 Android、OpenHarmony 两端复用 UI 代码而 OpenHarmony 侧的原生能力用系统接口直接调。整个项目里最容易翻车的恰恰是存储层。你想用户在便签里敲了半天文字如果切换页面或者应用被杀掉之后内容丢了这个应用基本就没法用了。所以在动手写页面之前必须先定好持久化方案。这个项目适合谁参考呢一类是在 OpenHarmony 上做 Flutter 应用开发的工程师另一类是需要在端侧设计本地数据层的开发者。如果你只是写个 Demo用几个全局变量也够但只要涉及真实使用场景就必须理解持久化背后的数据模型、事务边界和升级策略。1.2 不同存储方案到底差在哪里在选择方案之前我先梳理了一遍可用的本地存储手段大致有四种方向方案常见实现适合场景主要问题轻量键值存储类似 SharedPreferences 的 KV 接口配置项、登录态、少量标记不适合存大量结构化便单读取时需要序列化整个集合文件存储将 JSON/文本写入本地文件小量草稿、导出备份缺少索引和事务查询和更新都很笨重关系型数据库SQLite 系列、系统自带 RDB结构化数据、复杂查询、事务需要建表、写 SQL、处理迁移分布式数据管理OpenHarmony 分布式 KV/DataShare多设备同步、靠近系统总线接入复杂度偏高网络异常时行为要设计好我建议优先考虑关系型数据库而不是直接把便单列表序列化成一个 JSON 塞进 KV。原因是便单的使用模式决定了它需要“局部更新”改一个标签、改一个标题如果每次都整包读写数据量到了几百上千条以后性能和可靠性都会明显下降。而且关系型数据库自带 WHERE、ORDER BY、LIKE、LIMIT这些原语几乎覆盖了便单管理的全部查询场景。对比下来我在项目里选择了 OpenHarmony 自带的 RDB关系型数据库模块配合 Flutter MethodChannel 做桥接。这个方案有几个好处数据管理逻辑在系统侧类型安全、有事务能力Flutter 侧只负责发送调令和接收结果避免在 Dart 层另搞一套 SQLite 兼容层后续如果要扩展到分布式同步底层可以继续接系统能力上层 Service 不用大改。提示千万别被“直接用文件存 JSON 更快”的说法带偏。真实场景下便单的写入频率并不低尤其还有“自动保存”这类功能关系型数据库的状态管理比文件覆盖可靠得多。1.3 为什么选择系统 RDB 而不是社区 SQLite 分支Flutter 生态里有很多 SQLite 插件但那是面向 Android/iOS 的。在 OpenHarmony 上跑 Flutter插件层不一定直接可用不少 SQLite 插件底层依赖系统原生的 SQLite 实现但 OpenHarmony 的 RDB 接口形态和 Android 不完全一样。与其花时间适配第三方插件不如直接用平台侧提供的能力封装一个窄接口Flutter 侧只关心业务方法签名即可。从工程角度看这种“窄桥接”的风险也更可控。MethodChannel 两边的方法、参数、返回值都是我们自定义的出了问题容易定位。数据库升级时原生侧可以直接执行 ALTER TABLE不需要关注 Flutter 侧怎么处理。2. 工程准备在 OpenHarmony 上跑 Flutter 的桥接坑2.1 环境与适配 SDK 的版本对齐这里有个容易踩的坑Flutter 官方 SDK 并不直接面向 OpenHarmony 输出产物需要用社区适配的 SDK 分支再配合 OpenHarmony 的 SDK 一起构建。不同版本的 Flutter 引擎对应不同的 API Level 和工具链版本不匹配往往会在运行期出现比较诡异的现象比如 MethodChannel 注册了但回调不到、页面构建正常但原生能力调用后无响应。我在搭建环境时建议把版本信息记录成一个表格放在工程根目录的 README 里方便自己和团队排查组件版本/说明Flutter SDK社区适配分支与目标 OpenHarmony 版本匹配OpenHarmony SDK对应 API Level安装配套 IDE 后确认Dart SDK随 Flutter 分支自带不单独指定构建工具使用配套 IDE 的构建链避免命令行手动跑偏IDE 环境安装好之后我习惯先在空项目里跑通一个最简通道再开始写业务代码。先创建一个默认 Flutter 工程再做一次“Dart 端调用原生侧返回当前版本号”的验证确保 Bridge 链路通。2.2 工程结构怎么摆项目不能让 Flutter 代码和原生代码搅在一起。我采用了典型的“Flutter App 原生宿主模块”结构lib/Flutter 业务代码下面分pages/页面、models/数据模型、services/存储服务与 API 封装、utils/工具。native/OpenHarmony 原生模块放 ArkTS 代码、资源文件以及数据库操作相关文件。合理使用 HAR 模块把 RDB 操作封装成一个独立模块方便多工程复用。这种结构的好处是后面如果要换底层数据库比如从本地 RDB 切到分布式存储只需要替换services/下面的实现页面层几乎不用动。2.3 MethodChannel 的初始化与命名规范MethodChannel 的通道名要全局唯一我统一用package/module/method的形式命名例如com.example.notestore/rdb。Dart 侧代码如下class NoteStoreService { static const MethodChannel _channel MethodChannel(com.example.notestore/rdb); Futureint insert(MapString, dynamic note) async { try { final int rowId await _channel.invokeMethod(insert, note); return rowId; } on PlatformException catch (e) { // 这里记录日志方便后续排查桥接问题 rethrow; } } }原生侧在注册通道时需要注意通道名和 Flutter 侧完全一致同时要处理主线程与数据库线程的关系。OpenHarmony 的 RDB 操作本身是异步的回调回来的结果再通过result返回给 Flutter不要在原生侧把耗时操作直接放在 UI 线程。注意MethodChannel 方法的result只能调用一次重复调用会直接报错。我在早期开发里就因为在回调里既调用了result.success又调用了result.error导致 Flutter 侧收到异常。现在所有原生侧方法入口先做参数校验再进入业务逻辑确保返回路径只有一条。3. 数据模型与表结构设计设计先行别急着写 SQL3.1 便单表字段设计建表之前先定义清楚字段我最终的便单表大致长这样字段名类型说明idINTEGER 自增主键本地主键方便索引和关联uuidTEXT 唯一全局 ID为将来分布式同步预留titleTEXT便单标题contentTEXT便单正文允许为空group_idINTEGER所属分组 ID默认 0 表示未分组tagsTEXT标签多个标签用逗号分隔is_pinnedINTEGER是否置顶0/1is_deletedINTEGER是否删除0/1回收站依赖这个字段remind_timeINTEGER提醒时间戳毫秒0 表示无提醒created_timeINTEGER创建时间戳毫秒updated_timeINTEGER更新时间戳毫秒id用自增整数主要是单机场景性能好uuid字段则用于未来多端同步避免设备间 ID 冲突。这两个字段都很关键少了uuid后续分布式能力扩展很被动少了is_deleted回收站就得额外建表或者物理删除恢复基本没戏。时间字段统一存毫秒时间戳不要存字符串这样排序、区间过滤都方便。在 Dart 层用DateTime解析时注意时区处理全部转成 UTC 存储展示时再按本地时区转换。3.2 分组与标签的关系建模分组很简单一张group表存分组名和排序值便单表通过group_id关联。标签我最终选择了“冗余字符串”方案在一张便单上直接存逗号分隔的标签文本。这是刻意做的取舍关联表便单-标签多对多表在规范化上更漂亮但对一个本地应用来说查询时需要多一次 JOIN而且用户标签数量通常不会很多简单方案带来的维护成本更低。检索时用LIKE %标签名%也能满足需要。如果你要强标签管理比如标签重命名时批量修改历史便单那就应该改用关联表否则重命名一个标签需要全表扫一遍。我在项目初期明确过需求标签不会频繁重命名所以选择了当前方案。3.3 索引与版本升级建索引的原则是优先给查询条件里的字段建索引。便单场景最常查询的是分组、排序、回收站状态所以重点建了这几个索引CREATE INDEX idx_notes_group ON notes(group_id); CREATE INDEX idx_notes_updated ON notes(updated_time DESC); CREATE INDEX idx_notes_deleted ON notes(is_deleted, updated_time DESC);数据库版本我直接定义为 1并在工程中预留了升级钩子// 伪代码升级时根据 oldVersion 执行不同的迁移 SQL onUpgrade(db, oldVersion, newVersion) { if (oldVersion 2) { ALTER TABLE notes ADD COLUMN remind_time INTEGER DEFAULT 0; } }版本号不要在代码里硬编码单独放在常量文件里。未来新增字段、调整索引都走固定的升级函数不要在启动时偷偷改表结构。4. 持久化核心实现建库、CRUD、事务与分页4.1 建立数据库与建表OpenHarmony 侧创建数据库我用系统 RDB 模块完成。简化后的核心逻辑长这样import relationalStore from ohos.data.relationalStore; const STORE_CONFIG: relationalStore.StoreConfig { name: note_app.db, securityLevel: relationalStore.SecurityLevel.S1, }; let store await relationalStore.getRdbStore(context, STORE_CONFIG); await store.executeSql( CREATE TABLE IF NOT EXISTS notes ( id INTEGER PRIMARY KEY AUTOINCREMENT, uuid TEXT NOT NULL, title TEXT NOT NULL DEFAULT , content TEXT, group_id INTEGER DEFAULT 0, tags TEXT DEFAULT , is_pinned INTEGER DEFAULT 0, is_deleted INTEGER DEFAULT 0, remind_time INTEGER DEFAULT 0, created_time INTEGER NOT NULL, updated_time INTEGER NOT NULL ) );securityLevel这里我选 S1普通级别因为便单数据不涉及高敏感信息如果业务上后续要加密可以再调高安全级别。注意created_time和updated_time设为 NOT NULL这样每次插入和更新时强制带上时间避免脏数据。4.2 便单插入与查询桥接原生侧插入方法核心是把 Flutter 传来的 Map 转成存储模块的 ValuesBucket然后调用系统的 insert 接口async insert(noteData) { let values new relationalStore.ValuesBucket(); values[uuid] noteData[uuid]; values[title] noteData[title]; values[content] noteData[content]; values[created_time] noteData[created_time]; values[updated_time] noteData[updated_time]; let rowId await store.insert(notes, values); return rowId; }Flutter 侧无论在哪个页面都通过NoteStoreService.insert()来写入不直接拼接 SQL统一走一层 Service。这层封装很有必要后面不管是加字段还是加缓存都在 Service 层处理。查询时原生侧用谓词构造条件。比如按“未删除 分组 时间倒序”查询一页let predicates new relationalStore.RdbPredicates(notes); predicates.equalTo(is_deleted, 0); if (groupId 0) { predicates.equalTo(group_id, groupId); } predicates.orderByDesc(updated_time); predicates.limitAs(pageSize); predicates.offsetAs(offset); let resultSet await store.query(predicates, [id, uuid, title, content, updated_time]);这套接口对 Flutter 端的开发者来说不需要理解具体格式只要约定好参数名和返回字段名就行。4.3 事务批量操作绝不能裸奔“批量删除”“批量移动到某个分组”“清空回收站”这类操作如果每条 SQL 单独提交中途一旦失败数据就只剩一半。RDB 提供事务接口我的做法是把所有需要在同一原子单元里完成的写操作包在事务里await store.beginTransaction(); try { for (let id of ids) { await store.delete(notes, predicates.equalTo(id, id)); } await store.commit(); } catch (err) { await store.rollBack(); throw err; }事务还可以用来保证某种逻辑上的“顺序”比如先把便单 A 批量设为删除状态再清空其标签这两步必须全部成功否则就会出现“已删除的便单还留在标签索引里”的脏情况。凡是有多步写操作都建议走事务。4.4 分页、排序与检索便单列表不能一次性全查出来几千条之后就会卡顿。我分页参数统一使用limit 20每页 20 条通过“拉到底部加载更多”的方式翻页。分页查询里最容易犯的错误是 offset 越来越大导致慢查询可以在设计阶段利用时间游标代替偏移量比如updated_time 上一次最后一条的时间避免深度分页。检索逻辑是便单应用的核心之一。用户输入一个关键词需要在标题和正文里同时匹配我使用谓词的多个条件组合类似let predicates new relationalStore.RdbPredicates(notes); predicates.equalTo(is_deleted, 0); predicates.beginWrap(); predicates.like(title, %${keyword}%); predicates.or().like(content, %${keyword}%); predicates.endWrap();这里要注意LIKE查询在数据量大时性能开销明显如果真要处理上万条便单建议引入全文索引或分词索引但在小规模场景下这条路径已经足够稳。5. 便单管理能力落地软删除、归档、备份与提醒5.1 回收站的软删除机制删除便单前我不直接DELETE而是把is_deleted置为 1并更新updated_time。这样便单还留在原表里查询列表时统一过滤is_deleted 0回收站列表则查is_deleted 1。恢复操作就是把标记改回 0。彻底清理则在回收站里单独提供“清空回收站”按钮真正执行批量物理删除。软删除的好处非常多误删恢复是基础需求而且可以保留操作痕迹后续做数据审计也很方便。心得软删除的代价是每条查询都要带上is_deleted条件因此索引里必须包含这个字段否则全表扫描会被放大。我在索引设计中已经单独建了复合索引实测在几千条数据量级下列表响应基本无感。5.2 归档与定期清理便单一类应用虽然不追求无限保留但也不能放任自流。我在存储层增加了“归档”概念超过 90 天未更新的便单自动进入归档状态不再出现在默认列表只在“归档”分组中查看。实现上可以新增一个archive字段也可以从updated_time推断。我选择用字段标记方便用户手动把某条便单归档。定期清理策略放在应用启动时执行一次超过 180 天、且不在收藏/置顶状态的已删除便单物理删除并输出日志。这可以防止回收站无限膨胀也不至于误删用户重要数据。备份功能我做了两步一是把整个便单表导出成 JSON 文件放在应用沙箱目录二是提供导入入口从 JSON 文件恢复。导出和导入表面看是文件操作其实是把数据库的id、uuid、created_time、updated_time完整保存下来UUID 的存在让导入时可以避免重复。5.3 提醒时间与状态管理提醒功能牵扯系统通知不只是存储问题。存储层需要保证提醒时间字段的可靠更新创建或修改便单时写入remind_time到点后系统触发通知应用响应用户“完成”后把这条便单状态置为已完成同时清掉remind_time。从持久化角度看提醒时间属于典型的“低频写 高频查”字段单独放在主表里就够不用另建提醒表。如果未来要做非常复杂的循环提醒可以独立建一张提醒规则表本次项目不涉及。5.4 分布式同步的扩展空间OpenHarmony 本身带有分布式数据管理能力可以在多设备之间同步数据。现在这套存储层虽然没有接入分布式但字段设计已经为它留好了口子全局uuid、毫秒时间戳、软删除标记这些是同步机制的基本前提。以后若要接分布式核心工作是写一个同步适配器把本地 RDB 的增量操作映射到分布式数据库的变更集而不是推翻重做。6. 常见问题与排查实录6.1 MethodChannel 方法找不到现象是 Flutter 调用后一直超时原生侧没有任何日志。排查下来多为两类原因通道名不一致或原生侧还没有完成registerMethodChannel的注册。我在原生方法顶部加了一个日志输出任何调用进来先打印方法名和参数这样可以快速确认问题在桥接还是业务逻辑。6.2 中文乱码与结果集字段解析异常这个坑在 JSON 序列化阶段。Flutter 侧收到的 Map 里面如果是Byte数组或者无符号整数解析时容易出现类型不匹配。我统一的规则是原生侧返回值全部转换为String或int不直接传递对象类型中文字符串在 ArkTS 端和 Dart 端默认都使用 UTF-8不会有问题但如果混用了字节流就会乱码。6.3 并发写导致的数据错乱同一时刻多个页面都可能触发写操作如果不加控制事务之间可能打乱顺序。我这里给写入方法加了一个简单的串行队列Dart 侧统一通过一个Future链来排队避免多个方法并发 invoke。6.4 数据库升级失败老版本数据库没有新版本字段升级时如果ALTER TABLE失败启动就会异常。我采取两个措施所有升级操作统一写在onUpgrade里每个步骤用 try/catch 包裹升级前先备份原始库文件到临时目录升级失败自动回滚并提示用户。问题现象可能原因解决办法通道调用超时通道名不一致/未注册核对通道名注册后打印日志中文乱码字节流与字符串混用统一 UTF-8 字符串传递数据丢更新并发无串行Dart 层串行队列升级后读崩缺少字段/索引未建onUpgrade 分步并备份列表卡顿缺索引/全量查询建复合索引分页查询这套便单持久化方案是我在 Flutter 与 OpenHarmony 组合模式下反复调整后稳定下来的版本。最大的体会是跨端开发里桥接层宁可多写一层薄的封装也比在业务层到处塞原生调用省心数据字段设计时多花半小时考虑升级和同步后面能省好几天的返工。如果你也在折腾类似的便单应用建议先从数据模型入手把字段和索引定扎实再谈界面美化。后续有机会我想把分布式同步真正接进来那又是另一个值得记录的话题了。