★ FEATURED ARTICLE 我最近一直在折腾 Flutter for OpenHarmony 的适配开发做了一个看书管理记录类的小工具用来维护我的阅读进度、笔记和书单状态。功能本身不复杂真正让我花了不少心思的反而是最容易被忽略的模块——数据备份。原因很简单阅读记录这类数据丢了真的会让人心态崩掉。你想想一本六百页的书读了三个月笔记、页码、状态全在里面App 一重装就全没了那感觉跟书被撕了差不多。这篇文章就把我在 Flutter for OpenHarmony 上做数据备份的完整思路、代码实现和踩坑过程整理出来。无论你是想给自研小工具加备份功能还是正准备把 Flutter 项目往 OpenHarmony 上迁移这部分内容都可以直接参考。1. 内容整体设计与思路拆解1.1 为什么选择 JSON 快照方案而不是直接拷贝数据库刚开始做备份功能的时候我的第一反应是“直接备份 SQLite 数据库文件不就行了”。这个方案看起来最省事数据库文件在哪把文件复制一份出来就行恢复的时候再覆盖回去。但真的放到 Flutter for OpenHarmony 这个场景里我仔细一推演发现这条路有几道坎数据库文件是二进制格式用户拿到备份文件后没法自己查看里面是什么出了问题也没法人工排查透明度太低。万一以后我改了数据库表结构老备份文件的兼容性就会出问题。轻则无法导入重则导入后数据错乱。SQLite 文件在备份那一刻可能处于写入中间状态直接拷贝存在数据不一致的风险。阅读记录类的数据量其实非常小完全没必要搬出数据库级备份这种“重武器”。所以我最终选了 JSON 快照方案。思路很直白把 App 里的核心业务数据序列化成 JSON 字符串写入一个带时间戳的.json文件。恢复的时候读取这个文件解析并校验通过后再导入。整个流程完全是可控的出了问题还能打开文件自己看。1.2 备份包的结构设计备份文件本身我设计成了一种带版本号的自描述格式。参考了常见的经验我把备份内容分成两层meta 层存放备份元信息比如备份版本号、App 版本、导出时间、备份内置的数据库结构版本。data 层存放实际的业务数据包含书目信息、阅读记录、笔记、书单状态等。结构草稿大概是这个样子{ backupVersion: 1, dbVersion: 3, exportedAt: 2025-06-15 21:30:00, data: { books: [], readingRecords: [], notes: [], tags: [] } }这样设计有个好处以后数据结构升级时我可以根据 backupVersion 写多个导入兼容分支。旧备份还能继续用而不是直接变成一堆废文件。1.3 备份文件命名与存放文件名我用的是book_backup_yyyyMMdd_HHmmss.json。全英文文件名加时间戳的格式在跨设备传输时最稳不会因为系统或编码问题导致乱码。存放位置我分了两个层次默认备份写入应用沙箱下的backup目录App 打开后会有“分享备份文件”的功能用户可以手动把文件发送到云盘、电脑或者其他 App 保存。为什么不在导出时直接写到公共下载目录因为在 OpenHarmony 上应用往公共目录比如 Download写文件涉及权限和媒体库授权这在适配早期版本的时候坑非常深后面我会详细说。2. 核心细节解析与实操要点2.1 数据模型的序列化设计既然选了 JSON 快照方案第一步就是让业务模型能干净地序列化和反序列化。我项目里的数据模型主要有三个分别对应书、阅读记录和笔记。class BookInfo { final String id; final String title; final String author; final int totalPages; final int currentPage; final String status; // reading / finished / wantToRead final DateTime createdAt; BookInfo({ required this.id, required this.title, required this.author, required this.totalPages, required this.currentPage, required this.status, required this.createdAt, }); BookInfo.fromJson(MapString, dynamic json) : id json[id] as String, title json[title] as String, author json[author] as String? ?? , totalPages json[totalPages] as int? ?? 0, currentPage json[currentPage] as int? ?? 0, status json[status] as String? ?? wantToRead, createdAt DateTime.parse(json[createdAt] as String); MapString, dynamic toJson() { id: id, title: title, author: author, totalPages: totalPages, currentPage: currentPage, status: status, createdAt: createdAt.toIso8601String(), }; }写这个类的时候有两个细节值得注意。第一个是DateTime的序列化强烈建议用toIso8601String()。如果你用toString()输出的字符串里会带着系统时区信息在不同的设备上解析时容易出现时差偏移看起来像是数据变了其实是时区问题在捣乱。第二个是字段的兼容性。我写fromJson的时候对可选字段全部用了空安全兜底比如json[author] as String? ?? 。为什么要这样因为旧版本备份里可能没有这个字段直接强转会在导入时抛错。宁可丢掉一个展示字段也不能让整个导入流程挂掉。2.2 备份目录的获取——这个适配坑让我记忆深刻在传统 Flutter 开发里获取应用文档目录一般用path_provider的getApplicationDocumentsDirectory()。但在 OpenHarmony 的 Flutter 适配环境中这套 API 的行为不完全一致。我实测下来部分设备上getApplicationDocumentsDirectory()返回的目录并不是真正持久化的文档目录而是缓存目录。这就意味着App 被清理缓存后你的备份文件就没了这在备份功能里是不可接受的。我现在采用的稳妥做法是自己构造备份目录用getApplicationSupportDirectory()这个在适配里基本正常作为根目录然后拼一个book_backup子目录。FutureDirectory getBackupDirectory() async { final supportDir await getApplicationSupportDirectory(); final backupDir Directory(${supportDir.path}/book_backup); if (!await backupDir.exists()) { await backupDir.create(recursive: true); } return backupDir; }注意在适配初期一定要检查你拿到的路径真正指向哪个目录。最保险的办法是在代码里临时打印路径用文件管理器看真实位置。别相信文档要信实测结果。2.3 为什么备份文件不直接写公共下载目录有一个需求场景是用户点一下“导出备份”文件直接出现在设备下载目录里。这个听起来很美好但在 OpenHarmony 上直接写公共目录会遇到权限问题。早期 Android 上有存储权限申请OpenHarmony 的公共目录写入同样需要申请媒体读写权限。这个权限申请流程在 Flutter 插件生态里还没有统一的适配方案而且即便申请成功不同系统版本的表现也不一致。我最终选择了“沙箱写入 分享导出”的组合方案。这个方案实测稳定得多而且用户体验并不差App 内提供备份文件列表每条记录上有“分享”按钮通过系统分享能力把文件发送出去就行。不用申请额外权限也绕开了公共目录的限制。3. 实操过程与核心环节实现3.1 备份管理器的整体结构我写了一个BackupManager单例类来统一管理备份的导出和导入核心逻辑全部集中在这里UI 层只管调用和展示结果。class BackupManager { BackupManager._(); static final BackupManager instance BackupManager._(); final ListBookInfo _books []; ListReadingRecord _records []; ListNote _notes []; FutureString exportBackup() async { final backupDir await getBackupDirectory(); final fileName book_backup_${_timestamp()}.json; final file File(${backupDir.path}/$fileName); final backupPackage { backupVersion: 1, dbVersion: 3, exportedAt: DateTime.now().toIso8601String(), data: { books: _books.map((e) e.toJson()).toList(), readingRecords: _records.map((e) e.toJson()).toList(), notes: _notes.map((e) e.toJson()).toList(), }, }; final jsonStr jsonEncode(backupPackage); await file.writeAsString(jsonStr, flush: true); return file.path; } String _timestamp() { final now DateTime.now(); final y now.year.toString().padLeft(4, 0); final m now.month.toString().padLeft(2, 0); final d now.day.toString().padLeft(2, 0); final h now.hour.toString().padLeft(2, 0); final min now.minute.toString().padLeft(2, 0); final s now.second.toString().padLeft(2, 0); return $y$m${d}_$h$min$s; } }写这个类的时候我特意用了flush: true参数确保数据真正落盘而不是停留在内存缓冲里。对备份文件来说写了一半就返回成功是最可怕的事情。3.2 导出流程的稳健化处理单纯调用writeAsString还不够稳。我经过实际测试后给导出流程增加了一步临时文件机制先把 JSON 内容写入一个backup_tmp.json临时文件。写入完成后检查文件大小如果大于某个合理的最小值比如 10 字节说明内容写进去了。再把临时文件重命名为正式文件。为什么要多这一步因为如果 App 在写入过程中被系统杀死、断电或者崩溃临时文件最多变成残留文件而正式备份区不会留下“半截”文件。用户恢复时拿到的要么是完整文件要么根本没这个文件不会出现导入到一半发现数据不对的尴尬局面。分享文件的逻辑用的是share_plus插件的 OpenHarmony 适配版本。这里提醒一句在 pubspec.yaml 里依赖 share_plus 时要确认你用的版本在 OpenHarmony 上有对应的平台实现。如果引入了不兼容的版本编译期不一定报错但运行时会直接 MissingPluginException。解决办法是关注社区里由开发者适配维护的 forks 或专用版本。3.3 导入流程的细节设计导入和导出看起来是对称的但细节上要复杂得多因为它面对的是“用户拿过来什么文件都可能”的场景。我的导入流程分了五个步骤读取文件拿到字符串内容。尝试jsonDecode失败则直接提示“文件格式错误”中止流程。检查backupVersion字段判断当前版本是否支持导入。解析data层并逐条构造BookInfo、ReadingRecord、Note对象。全部解析成功后弹确认框让用户选择“覆盖”还是“合并”确认后才真正写库。关键点是不要把确认框放在解析之前。用户还没看到这个文件能不能用你就先问他“确定要恢复吗”等他确认后才发现文件是坏的这个交互流程就很蠢。先做完所有校验再让用户做决定才是合理的顺序。合并策略我实现得很简单按 ID 去重如果导入的书已存在就用导入的数据覆盖不存在则新增。如果你需要保留两边的“新记录”可以改成按updatedAt时间戳比新旧旧的让位给新的。这个需求在多设备同步场景里很常见。3.4 UI 层的接入与用户反馈备份功能的 UI 我做得比较轻。设置页有一个“数据备份”入口点进去能看到备份列表、创建时间和文件大小每个文件右侧有一个分享按钮和一个删除按钮。页面顶部有两个大按钮立即备份和从备份恢复。从备份恢复的交互是这样设计的用户点击后进入文件选择器选中备份文件后App 会先解析校验。此时显示一个加载中状态因为解析是在异步线程里跑的大文件可能会卡一小会儿。解析成功后弹出包含备份时间和文件里书目数量的确认卡片用户确认后执行导入最后 Toast 提示成功或失败。Futurevoid onRestorePressed(BuildContext context) async { final result await FilePicker.platform.pickFiles( type: FileType.custom, allowedExtensions: [json], ); if (result null || result.files.isEmpty) return; final path result.files.single.path; try { final package await BackupManager.instance.importBackup(path); if (!mounted) return; showDialog( context: context, builder: (ctx) AlertDialog( title: const Text(确认恢复), content: Text( 备份时间${package.exportedAt}\n 包含书目${package.books.length} 本\n 包含笔记${package.notes.length} 条, style: const TextStyle(height: 1.6), ), actions: [ TextButton(onPressed: () Navigator.pop(ctx), child: const Text(取消)), TextButton( onPressed: () async { await BackupManager.instance.applyPackage(package); if (ctx.mounted) Navigator.pop(ctx); }, child: const Text(确认恢复), ), ], ), ); } catch (e) { ScaffoldMessenger.of(context).showSnackBar( SnackBar(content: Text(备份文件解析失败$e)), ); } }这里的文件选择器用的也是社区适配的版本在 OpenHarmony 设备上能拉起系统文件选择界面选中的文件会以临时路径提供。有一点要注意有时候返回的 path 指向的是临时缓存文件App 必须立刻读取并解析不能只保存这个路径等以后用因为临时文件随时可能被系统清掉。4. 常见问题与排查技巧实录开发过程中我踩过不少坑挑几个典型的分享出来这些在文档里真的找不到答案。4.1 备份文件在工作目录里找不到一开始我用getApplicationDocumentsDirectory()拿路径导出的文件测试时也显示成功但打开文件管理器怎么都找不到。排查了很久才发现问题出在 Flutter for OpenHarmony 的适配实现上这个 API 返回的路径和 Android 上的含义不一致文件被写进了缓存类目录。解决办法就是我前面说的改用getApplicationSupportDirectory()再拼子目录或者干脆自己用沙箱路径拼接。检查文件是否真的写进去了可以用文件管理器看路径也可以在代码里读回文件大小来验证。4.2 分享备份文件时找不到可用的 App在 OpenHarmony 上测试share_plus的分享功能时我遇到过调起分享面板但里面没有目标 App 的情况或者在某些设备上直接抛异常。这个问题的根源是系统分享通道的适配还在完善中。我的排查思路是看异常日志中是否有 MissingPluginException如果是优先确认插件版本如果分享面板能起来但列表为空那多半是设备上没有注册相关分享渠道换一台设备即可确认。给用户的备选方案就是文件管理器路径提示分享失败时在弹窗里把备份文件的完整沙箱路径展示出来引导用户用第三方文件管理器进入该目录手动拷贝文件。4.3 备份文件里的中文内容乱码这个问题是在电脑上打开备份文件时发现的。中文字段显示成了乱码但 App 内导入是正常的。原因是写入编码不统一部分版本默认不是 UTF-8。解决方式是在写入时显式指定 UTF-8 编码await file.writeAsString(jsonStr, flush: true, encoding: utf8);读取时同样指定final content await file.readAsString(encoding: utf8);后来我做了一个防御性处理导入时先按 UTF-8 读如果内容里有替换符或解析异常就尝试 GBK 编码再读一次。这样即使旧版本生成的备份文件用的是非 UTF-8 编码也能被兼容识别。4.4 大文件备份导致界面卡顿理论上看书管理的数据量很小但如果用户的笔记里贴了大段引用文本或者图片路径信息备份文件也可能达到几 MB。直接用主线程 jsonEncode 和写文件UI 会卡住一小会儿体现为掉帧或短暂白屏。解决思路很简单把备份的完整流程放到Isolate.run()里执行UI 层只显示 loading 状态。如果不想引入复杂的 isolate 管理也可以用Future(() async { ... })把耗时的部分包进去至少不阻塞主线程。实测下来一个包含 200 本书、800 条笔记的备份文件在普通设备上生成时间大约 200-300ms。虽然不算长但放到 isolate 里执行后体验明显更顺滑值得做。4.5 导入时误选损坏文件导致崩溃这是我最担心的情况。用户可能在网上随便下载一个 json 文件或者从聊天记录里转发一个本身就是坏的文件导入时如果没有防护App 很可能直接崩溃。我的防御策略分三层第一层是 jsonDecode 的 try-catch 包裹解析失败直接返回错误不往下走。第二层是格式校验。解析成功后先检查 backupVersion 是否存在再检查 data 是否为 Map 类型。这些都不满足就不继续。第三层是逐条数据构造时的容错。单条记录字段缺失时用空安全兜底让能恢复的数据先恢复个别异常记录跳过并汇总到提示信息里告诉用户。最后在导入前我会自动把当前数据先打一个临时备份。这样即使导入结果不理想用户也有后悔药。实测下来这个自动备份的成本极低但帮助非常大。4.6 备份后重装 App 文件访问不到了如果用户重装了 App应用沙箱里的备份文件会跟着销毁这是沙箱机制的必然行为。这也是我为什么在 App 里默认做了一步备份成功后自动弹出分享面板引导用户把文件存到外部存储或云盘。受限于权限问题App 无法直接写入公共目录但通过分享能力可以做到等价效果。我在备份列表里特意加了一个“未分享”的提示标签提醒用户该份备份只存在于设备本地建议尽快分享保存。这个设计虽然不起眼但对数据安全感提升很明显。写在最后折腾完这套备份实现我最大的体会是备份功能看起来只是一读一写真正做起来全是细节。文件写哪、怎么命名、编码用什么、解析怎么容错、导入要不要确认每一个环节都可能埋坑。尤其是 Flutter for OpenHarmony 这个适配环境很多 API 的行为和传统 Flutter 平台并不完全一致文档覆盖也不够细致更需要自己实测验证。如果你也在做类似的跨平台适配项目建议把备份功能优先级往前提一提而不是在最后补。数据安全这件事用户嘴上不说但一旦丢一次数据基本就不会再打开你的 App 了。这个方案后续还可以扩展的方向一个是备份文件压缩加密加入密码保护后再分享出去另一个是增加定期备份提醒比如每次退出 App 时检查上次备份时间超过一周就提醒一次。这两个功能加到现有架构上都很顺接口设计不用动只加逻辑层就行。
阅读完成 · 觉得有帮助？
