前言
在进行 OpenHarmony 应用开发时，网络请求的响应速度直接决定了用户体验。如果用户每次切换页面都必须等待加载动画，应用体验会显得不佳。我们需要处理异步数据请求，并建立一套精密的机制来解决以下痛点：
- 自动缓存：第二次访问时应瞬间展示历史数据。
- 过期失效（Stale-while-revalidate）：在展示旧数据的同时，后台静默拉取新数据。
- 无限滚动：简单地处理分页与数据追加内容逻辑。
cached_query 是一个类似于 Web 端 React Query 的 Dart 状态管理库。它专注于数据获取与同步，让你的鸿蒙应用具备顶级的数据缓存表现。
一、核心缓存驱动机制
cached_query 在内存与数据源之间建立了一层'智能感知'缓存。
- 数据过期/缺失：返回新数据
- 发射流：触发 UI 更新
- Query Cache (内存存储)：中间层
- API Service (网络请求)：数据源
二、核心 API 实战
2.1 定义单一查询
import 'package:cached_query/cached_query.dart';
final userQuery = Query<Map<String, dynamic>, int>(
key: 'user_info', // 💡 唯一的缓存标识
queryFn: (userId) async {
// 模拟网络请求
await Future.delayed(Duration(seconds: 1));
return {'id': userId, 'name': '鸿蒙开发者'};
},
config: QueryConfig(
staleTime: Duration(minutes: 5), // 💡 5 分钟内不重新抓取
),
);
2.2 执行异步突变 (Mutation)
常用于更新、删除等会导致缓存失效的操作。
final updateMutation = Mutation<void, String>(
queryFn: (newName) => api.updateUser(newName),
onSuccess: (res, arg) {
// 💡 成功后通知缓存失效，自动触发重新抓取
CachedQuery.instance.invalidateQueries(key: 'user_info');
},
);
2.3 在 UI 中观测
QueryObserver<Map<String, dynamic>, int>(
query: userQuery,
arg: 123,
builder: (context, state) {
if (state.status == QueryStatus.loading) {
return CircularProgressIndicator();
}
return Text('用户名：${state.data?['name']}');
},
)
三、常见应用场景
3.1 鸿蒙新闻客户端列表
利用 InfiniteQuery 轻松实现'加载更多'逻辑。它会自动合并多个历史 Page 的数据，并记录每一个 Page 的滚动状态和游标（Cursor）。
3.2 离线优先的应用场景
结合 插件，可以将内存中的缓存异步序列化到鸿蒙系统的本地磁盘中。只要应用启动，即使在断网状态，也能立即看到上一次的全部内容。
