做资讯客户端做到第十二期终于轮到收藏这个高频又容易被低估的功能。前面几期把列表加载、详情页、搜索、分享串了一遍但一直有件事悬着用户看到值得留下的文章我们怎么帮他存住收藏看起来只是点亮一颗心实际牵扯的是一条完整的数据链路——收藏状态要在列表页、详情页、收藏页三处保持同步数据要经得起App重启、断网、乃至新闻源下架这几种不算罕见的情况。这篇就以OpenHarmony上运行的Flutter资讯App为背景把收藏功能和数据持久化从头实现一遍顺便聊聊我在这个过程中踩过的坑。先放个结论如果只是把newsId存下来收藏功能大概率会在离线场景翻车。文章会把重点放在两件事上——一是设计一个“快照式”收藏数据模型二是用文件存储方案把数据稳稳落到OpenHarmony的本地文件系统里。给出的接口和实现保持了清晰边界后面想换数据库、加云同步都不需要伤筋动骨。1. 收藏数据模型的设计思路为什么不能只存一个ID1.1 只存ID的三个隐患把收藏设计成“只存ID进收藏列表时再重新请求接口”逻辑上最省事第一版很容易这么做。但实际跑一段时间就会撞上三个明晃晃的坑。第一个是离线。用户在没网的时候打开收藏列表期望看到的是自己收藏过的文章而不是一屏加载失败的骨架图。资讯App本身就是强网络依赖的但收藏恰恰是用户主动保存的资产它不应该离了网络就变成一堆不可用的ID。第二个坑是内容下架。资讯源会定期清理过期内容你手里有newsId接口那边可能已经404了用户看到的就是一条标题都没有的死数据体验瞬间归零。第三个坑藏在性能里收藏列表如果有几十条每一条都发一个网络请求去补全信息且不说流量消耗光是滚动时的白屏和加载状态就够用户吐槽了。所以“快照式”收藏是刚需。用户在点击收藏的那一刻我们把新闻的标题、摘要、来源、封面、原文链接这一整套可展示的信息一起copy进本地库。收藏列表页完全不依赖网络直接从本地读打开即显示。1.2 存储介质选型对比存什么想清楚了接下来是存在哪。我先把目前能用的方案过一遍再告诉你我最后选了哪个。方案典型包适用场景OpenHarmony适配情况轻量键值对shared_preferences少量配置项、开关状态有适配分支但本质是整表读写不适合收藏这种列表数据本地文件JSONdart:io 手写百条到千条级别的结构化数据路径需要适配插件其余纯Dart层可用最稳嵌入式数据库sqflite / objectbox / hive千条以上、需要模糊查询或复杂索引适配进度不一入门成本偏高暂不推荐第一版用选文件存储的原因很直接收藏场景大多数用户最多也就存几百条新闻每条序列化后的JSON撑死2KB加起来不到1MB用纯Dart的文件读写完全扛得住。更重要的是OpenHarmony上的Flutter生态还没到所有原生插件都顺手的地步开发阶段先用最可控的方式把逻辑跑通比一开始就赌某个数据库的适配要靠谱得多。1.3 快照字段怎么设计字段设计我踩过一次教训。最开始只存了title、summary、imageUrl三个展示字段后来发现收藏列表里想显示“来源”和“收藏时间”结果老数据里根本没有只能做迁移兼容。所以字段宁可开头多留也别后期补。字段类型说明newsIdString新闻唯一ID去重和定位都靠它titleString标题快照列表页直接显示summaryString摘要快照imageUrlString封面图URL也可以存本地缓存路径sourceNameString来源名称linkUrlString原文链接collectedAtDateTime收藏时间按这个倒序排列一个很重要的设计原则newsId是唯一业务标识但排序字段用collectedAt两个都要存。千万别把列表顺序寄托在插入顺序上一旦后续要做批量导入、去重合并没有collectedAt的时间基准拆起来非常难受。2. 搭建收藏Repository把持久化隔离成一个黑盒2.1 先用接口把存储方式定下来我习惯在写任何存储代码之前先定义接口。这一步很关键它把“收藏功能怎么用”和“数据怎么存”彻底分开。UI层永远只跟接口对话不关心底层是文件、数据库还是云。abstract class FavoriteRepository { FutureListFavoriteNews loadAll(); Futurebool isFavorite(String newsId); Futurevoid add(FavoriteNews news); Futurevoid remove(String newsId); }为什么要留isFavorite这个看似多余的接口因为后面做启动恢复的时候要批量刷新详情页和列表页的收藏图标直接查集合比遍历列表高效得多。这就是接口设计的细节价值。接着定义快照数据类。注意DateTime的序列化统一用toIso8601String转成字符串存储避免跨平台的时间格式歧义class FavoriteNews { final String newsId; final String title; final String summary; final String imageUrl; final String sourceName; final String linkUrl; final DateTime collectedAt; const FavoriteNews({ required this.newsId, required this.title, required this.summary, required this.imageUrl, required this.sourceName, required this.linkUrl, required this.collectedAt, }); MapString, dynamic toJson() { newsId: newsId, title: title, summary: summary, imageUrl: imageUrl, sourceName: sourceName, linkUrl: linkUrl, collectedAt: collectedAt.toIso8601String(), }; factory FavoriteNews.fromJson(MapString, dynamic json) FavoriteNews( newsId: json[newsId] as String, title: json[title] as String? ?? , summary: json[summary] as String? ?? , imageUrl: json[imageUrl] as String? ?? , sourceName: json[sourceName] as String? ?? , linkUrl: json[linkUrl] as String? ?? , collectedAt: DateTime.parse(json[collectedAt] as String), ); }fromJson里对可能缺失的字段给了空串兜底这是做兼容的好习惯。旧版本没有sourceName的时候新代码读出来也不会崩溃。2.2 文件读写与内存缓存实现FileFavoriteRepository的时候我做了两个设计内存缓存优先写盘采用防抖合并。内存缓存是为了让UI层读取收藏列表时零等待。第一次启动从文件加载进内存后续所有查询都先走内存只有增删操作才触发落盘。这样收藏列表页的打开速度跟本地页面一样快。class FileFavoriteRepository implements FavoriteRepository { FileFavoriteRepository(this._file); final File _file; ListFavoriteNews? _cache; Timer? _debounce; override FutureListFavoriteNews loadAll() async { if (_cache ! null) return List.unmodifiable(_cache!); if (_file.existsSync()) { final content await _file.readAsString(encoding: utf8); final list (jsonDecode(content) as List) .map((e) FavoriteNews.fromJson(e as MapString, dynamic)) .toList(); _cache list; } else { _cache []; } return List.unmodifiable(_cache!); } override Futurevoid add(FavoriteNews news) async { final list await loadAll(); if (list.any((e) e.newsId news.newsId)) return; list.insert(0, news); _cache list; _scheduleSave(); } override Futurevoid remove(String newsId) async { final list await loadAll(); _cache list.where((e) e.newsId ! newsId).toList(); _scheduleSave(); } void _scheduleSave() { _debounce?.cancel(); _debounce Timer(const Duration(milliseconds: 300), _persist); } Futurevoid _persist() async { final list _cache ?? []; final json jsonEncode(list.map((e) e.toJson()).toList()); await _file.writeAsString(json, encoding: utf8, flush: true); } }重点看_persist里的flush: true。Dart的writeAsString默认不保证数据立刻物理落盘系统可能在断电或者进程被杀时丢数据。flush: true会强制把缓冲区刷到磁盘代价是性能稍降但收藏功能这种低频小数据量的场景可靠性优先这点性能损耗完全值得。2.3 原子写入与临时文件策略直接覆盖写一个JSON文件存在一个隐患如果App在写文件写到一半的时候被系统杀掉文件会变成截断的坏JSON下次启动直接解析失败。我的做法是先写临时文件再rename覆盖正式文件。Futurevoid _persist() async { final list _cache ?? []; final json jsonEncode(list.map((e) e.toJson()).toList()); final tmpFile File(${_file.path}.tmp); await tmpFile.writeAsString(json, encoding: utf8, flush: true); if (_file.existsSync()) { await _file.delete(); } await tmpFile.rename(_file.path); }rename替换在OpenHarmony这套类Linux文件系统上表现很稳定。先写临时文件再改名正式文件永远处于完整状态最多是“旧版本完整”或“新版本完整”不会出现半截文件。代价是同一时刻磁盘上会短暂存在两个文件但几百KB的量级完全不用担心。3. 收藏交互闭环收藏按钮、详情页与收藏列表的状态联动3.1 全局状态控制器文件层准备好了接下来解决UI层最棘手的问题收藏状态在多个页面之间保持一致。详情页点亮红心列表页要同步变红收藏页要立刻出现这条数据——它们是不能各自维护状态的。所以需要一个全局的FavoritesController继承ChangeNotifier由它持有内存中的收藏数据并在任何变化发生时通知所有监听者刷新class FavoritesController extends ChangeNotifier { FavoritesController(this._repository); final FavoriteRepository _repository; final SetString _favoriteIds {}; final ListFavoriteNews _items []; Futurevoid init() async { final all await _repository.loadAll(); _items.addAll(all); _favoriteIds.addAll(all.map((e) e.newsId)); notifyListeners(); } bool isFavorite(String newsId) _favoriteIds.contains(newsId); Futurevoid toggle(FavoriteNews news) async { if (_favoriteIds.contains(news.newsId)) { _favoriteIds.remove(news.newsId); _items.removeWhere((e) e.newsId news.newsId); await _repository.remove(news.newsId); } else { _favoriteIds.add(news.newsId); _items.insert(0, news); await _repository.add(news); } notifyListeners(); } }用SetString维护ID集合是为了让isFavorite查询走O(1)的hash查找。新闻列表滑动时每个item都要判断收藏状态如果遍历列表帧率马上绷不住。这里有一个取舍toggle里先更新内存再异步等待Repository落盘最后notifyListeners。为什么不先notify再等待因为如果先更新内存不notify用户点了红心结果图标没变体验会卡一下。反过来如果先notify再落盘用户在快速连续点击时内存状态是准的磁盘写入经过防抖合并最终也会一致。所以代码里落盘操作放在前面不会阻塞UI修改内存和通知放一起体验最跟手。3.2 收藏按钮组件有了全局Controller收藏按钮就纯粹是个“视图”了。我用ListenableBuilder监听Controller的变化按钮状态随数据源实时联动class FavoriteButton extends StatelessWidget { const FavoriteButton({super.key, required this.news}); final FavoriteNews news; override Widget build(BuildContext context) { final controller context.readFavoritesController(); return ListenableBuilder( listenable: controller, builder: (context, _) { final isFav controller.isFavorite(news.newsId); return IconButton( icon: Icon( isFav ? Icons.favorite : Icons.favorite_border, color: isFav ? Colors.redAccent : Colors.grey, ), onPressed: () controller.toggle(news), ); }, ); } }这个组件能直接用在列表页的每条item上也能放在详情页AppBar里复用性很好。用图标favorite和favorite_border切换比文字更能直观传达状态。如果以后想加动画在onPressed里包一个AnimatedSwitcher就行。根据我的经验IconButton默认的点击水波纹会跟列表滚动手势有冲突建议在按钮外层的GestureDetector配置behavior: HitTestBehavior.opaque确保点击区域不被列表的其他手势抢占。3.3 收藏列表页与空态处理收藏列表页是独立的页面启动时调用controller.init()确保内存数据已经加载然后直接用AnimatedBuilder监听数据变化收藏页和数据源天然同步class FavoritesPage extends StatelessWidget { const FavoritesPage({super.key}); override Widget build(BuildContext context) { final controller context.watchFavoritesController(); if (controller.items.isEmpty) { return const EmptyFavoritesView(); } return ListView.builder( itemCount: controller.items.length, itemBuilder: (context, index) { final news controller.items[index]; return NewsListTile(news: news, showFavoriteIcon: true); }, ); } }空态处理是收藏页最容易忽略的部分。用户第一次进来什么都没有光秃秃一个列表很难受。我做了个简单的空态视图一个灰色的心形图标加上“还没有收藏内容去资讯列表逛逛吧”的文案再放一个“去首页”按钮。别小看这个空态它在用户心智里是一个安全感信号——我知道这个功能存在只是暂时没有数据。3.4 重复点击和取消收藏的边界逻辑收藏功能最容易出bug的地方是边界情况快速双击导致同一数据重复插入在详情页取消收藏后返回列表页图标状态不对收藏列表里左滑删除结果详情页还显示红心。重复插入问题在Repository层已经做了防线——add方法开头有if (list.any((e) e.newsId news.newsId)) return;。这就是为什么上面我说newsId是唯一去重ID。UI层的快速双击第二次toggle进来时isFavorite已经为true走的是remove分支不会造成重复。跨页面一致性问题靠Controller解决。详情页和列表页都通过同一个Controller实例查询isFavorite任何页面调用了toggle其他页面在重建时自然能看到最新状态。前提是Controller必须是全局单例不能在页面Scope里重复创建。我在项目入口用了一个顶层变量保存实例并在main()里通过初始化注入方式传给首页保证整个App生命周期内只有一个Controller。4. OpenHarmony真机踩坑路径、编码与生命周期4.1 path_provider适配与沙箱路径差异在OpenHarmony上跑Flutter第一个坑就是路径获取。Flutter官方的path_provider插件在各平台走的是不同的原生接口OpenHarmony的Flutter适配层如果没把对应的MethodChannel实现注册进来getApplicationSupportDirectory()可能会抛异常或返回null。我的处理方式是把路径获取也包在Repository外面做一个可注入的路径提供器FutureFile _resolveFavoriteFile() async { final directory await getApplicationSupportDirectory(); return File(${directory.path}/favorites.json); }如果getApplicationSupportDirectory在你的适配环境不可用退一步用getApplicationDataDirectory再不行就在初始化时手动传入沙箱根目录自己拼接子路径。关键是不要在Repository内部直接依赖具体的插件而是启动时把File实例一次性注入。这样适配层怎么变都不影响业务代码。另外OpenHarmony的沙箱权限比传统Linux严格一些。调试时如果发现文件写入成功但重启后没了先怀疑路径不对打印directory.path看看是不是落到了临时目录。临时目录在进程被杀后会被系统清理乐观点说这是防抖合并的极端情况一旦正巧发生在冷启动前收藏就是有去无回。4.2 编码问题与容易误读的JSON转义写文件时Dart的File.writeAsString默认编码是UTF-8所以直接用中文标题基本不会有问题。真正暗藏玄机的是网络请求那边如果新闻列表接口返回的原始响应是其他编码比如旧系统常见的GBK直接用String.fromCharCodes去解码字节流中文会变成乱码乱码再进JSON收藏列表就全是“锟斤拷”。正确做法是用utf8.decode(bytes, allowMalformed: true)显式解码遇到无法识别的字节序列也不会整个抛异常。存下来之后再读取始终指定encoding: utf8两边对齐快照数据就稳了。另一个容易误读的是控制台输出。Dart的print打印含中文的JSON字符串时调试工具偶尔会把非ASCII字符显示成\uXXXX转义序列看起来像乱码其实文件里好好的。遇到这种情况先别紧张用编辑器直接打开JSON文件看一眼别被控制台表现骗了。4.3 热重载、启动恢复与坏文件兜底开发阶段最常用的热重载有个隐蔽问题热重载只重新构建页面State不会重跑main()。所以Controller的init()如果只在main里调用热重载后收藏列表页可能拿到空数据。我的做法是在FavoritesPage的initState里补一个幂等的ensureInitialized用标志位防止重复加载。这样热重载、页面跳转、冷启动三种路径下数据都会在真正需要的时候被加载。生产环境更要注意冷启动恢复顺序。资讯App首页加载很快用户可能还没进收藏页Controller的init还在跑。如果用户在init跑完前点击收藏某个item必须保证isFavorite查询不会因为集合为空而误判。所以Controller的构造函数里集合先置空只要UI层在toggle之前调用了await controller.init()就不会出现竞态。坏文件兜底是把可靠性做到位的关键一步。我在loadAll里对JSON解析做了try-catchoverride FutureListFavoriteNews loadAll() async { if (_cache ! null) return List.unmodifiable(_cache!); try { if (_file.existsSync()) { final content await _file.readAsString(encoding: utf8); final list (jsonDecode(content) as List) .map((e) FavoriteNews.fromJson(e as MapString, dynamic)) .toList(); _cache list; } else { _cache []; } } catch (e) { _cache []; } return List.unmodifiable(_cache!); }万一文件真损坏了至少App不会启动即崩溃收藏列表变成空列表也比整个页面白屏强。更稳妥的做法是留一个favorites.json.bak备份文件每次写入前先备份旧文件解析失败时自动从备份恢复。这个我在生产环境加过后面真遇到一次设备断电靠它救了数据。4.4 频繁I/O的性能红线收藏按钮的点击场景很极端——用户在列表页快速滑动疯狂点红心每一帧都可能触发一次数据修改。如果每次都同步读文件、写文件I/O线程马上成为瓶颈UI卡顿随之而来。这就是防抖合并存在的意义。300ms的时间窗口意味着用户在一瞬间点掉的10个收藏最终只触发一次落盘。这个窗口的时长选择不是拍脑袋太短合并效果差太长App被杀时可能丢失最近几秒的修改。300ms在“丢数据容忍度”和“I/O频率”之间比较平衡。另外一个性能红线是大图不要进JSON。收藏快照里如果存图片的Base64字符串一条数据可能膨胀到几百KB整个列表文件轻松破10MB读写都会变慢。正确姿势是存图片URL需要离线的场景可以单独做图片文件缓存把路径存进JSON。数据文件始终保持轻量收藏列表页的加载速度才会像本地页面。5. 后续扩展路径与最后一段心得5.1 从文件存储平滑迁移到数据库文件方案在收藏条数达到几千甚至上万条时全量读写的效率会开始退化。这时候迁移数据库顺理成章但不用推翻重来——Repository接口在这里的价值就体现出来了。只需要写一个新的DatabaseFavoriteRepository实现同一个接口在装配层把FileFavoriteRepository换掉Controller和UI层一行不用改。迁移时可以把老文件里的数据导入数据库然后删掉JSON文件。我习惯在迁移代码里留一个migrationVersion字段升级时判断版本决定是否执行导入逻辑避免用户升级后收藏消失。sqflite类型的关系型数据库适合做“按来源筛选”“按关键词搜索收藏”这类需求objectbox适合更复杂的关系模型。我的建议还是那句话第一版用文件存储把业务流程跑明白确确实实有性能需求了再迁移别为了“以后可能用得上”在起步阶段炫耀技术。5.2 分组收藏、云同步和离线下载的延伸收藏功能上线之后用户的需求会很快分化有人想给收藏打标签有人希望多设备同步有人想把收藏的文章离线下载完整版。这些都能在现有架构上延伸。分组和标签只需要在FavoriteNews里加一个ListString tags字段兼容旧的fromJson逻辑云同步可以做一个云端Repository装饰器本地Repository继续承担离线缓存离线下载则是在收藏动作触发时把文章正文缓存到本地文件顺手更新快照里的localContentPath。这些扩展都因为底层和UI解耦变得各管一摊互不干扰。5.3 一段实际调试后的体会在做收藏功能之前我一度以为这篇文章要讲的重点是“按钮动画怎么做”和“列表页怎么交互”。真正接进去才发现最花时间的反而是那些看不见的边界问题从文件读出来的数据字段缺失怎么办快速点击会不会重复重启App之后状态能不能对齐页面之间的红心能不能及时同步。我的实际体会是先把Repository边界划清楚数据模型定扎实后面的UI和扩展都会非常省心。具体到代码上恳切建议所有执行写操作的入口都走同一个_scheduleSave别贪图方便到处直接写文件——那样防抖和原子写就形同虚设了。最后分享一个调试小技巧给favorites.json文件路径打一个单独日志Tag每次启动打印文件条数和大小。开发阶段盯着这个日志看数据有没有落盘、有没有恢复成功一眼就知道比自己瞎翻文件系统快得多。