react-native-mmkv 集成 React Query：用 createAsyncStoragePersister 将查询缓存持久化到 MMKV

【免费下载链接】react-native-mmkv⚡️ The fastest key/value storage for React Native. ~30x faster than AsyncStorage!项目地址https://gitcode.com/gh_mirrors/re/react-native-mmkv点击查看免费下载react-queryTanStack Query默认把请求缓存保存在内存中应用重启后缓存即失效。本文讲解如何在 React Native 项目中把 react-query 的持久化层从 AsyncStorage 无缝切换到 react-native-mmkv——一个基于 C 原生实现、完全同步调用的高性能键值存储库让查询缓存以字符串形式落盘实现重启不丢缓存、离线秒开页面。读完本文你将掌握query-async-storage-persister与 MMKV 的桥接写法、PersistQueryClientProvider的接入方式以及 MMKV 实例的配置细节与底层行为。一、为什么把 react-query 缓存持久化到 MMKVreact-query 提供了createAsyncStoragePersister插件用于把查询缓存Query Cache写入一个符合AsyncStorage接口的存储介质。默认情况下它面向react-native-async-storage/async-storage但该接口只需三个方法setItem、getItem、removeItem。MMKV 的优势在于完全同步storage.set(key, value)、storage.getString(key)等都是同步返回没有 Promise、没有 Bridge读写是直接的 JS ↔ C 调用符合读取一次缓存的高频场景类型丰富支持string | boolean | number | ArrayBuffer四种取值天然适合以字符串存储的 JSON 序列化缓存原生性能底层是腾讯开源的 MMKV C 实现读写性能远高于跨线程桥接的 AsyncStorage仓库主页标注~30x faster than AsyncStorage该数据来自 StorageBenchmark 基准项目仅为社区参考。因此把 react-query 的持久化目标从 AsyncStorage 换成 MMKV既保持了createAsyncStoragePersister的使用方式不变又能获得同步、快速的落盘体验。二、前置条件安装依赖本文方案需要两个层面的依赖react-native-mmkv 本身本仓库的安装方式npm install react-native-mmkv react-native-nitro-modules cd ios pod install若使用 Expo则npx expo install react-native-mmkv react-native-nitro-modules npx expo prebuildreact-query 的持久化插件下文核心步骤。注意react-native-mmkv V4 基于 Nitro Modules 架构安装时需保证react-native-nitro-modules已正确链接从 V3 升级请参考 V4 升级指南。三、核心步骤一安装 react-query 持久化包执行以下命令安装 TanStack Query 的持久化辅助包yarn add tanstack/query-async-storage-persister tanstack/react-query-persist-client两个包的分工tanstack/query-async-storage-persister提供createAsyncStoragePersister(...)把符合 AsyncStorage 接口的存储对象包装成 react-query 可用的Persistertanstack/react-query-persist-client提供PersistQueryClientProvider根组件负责在应用启动时恢复缓存、运行时持续持久化。四、核心步骤二编写 MMKV 适配器clientStoragecreateAsyncStoragePersister需要一个实现setItem / getItem / removeItem的存储对象。由于 MMKV 本身是同步 API这个适配器写起来非常直接import { createAsyncStoragePersister } from tanstack/query-async-storage-persister import { createMMKV } from react-native-mmkv const storage createMMKV() const clientStorage { setItem: (key, value) { storage.set(key, value); }, getItem: (key) { const value storage.getString(key); return value undefined ? null : value; }, removeItem: (key) { storage.remove(key); }, }; export const clientPersister createAsyncStoragePersister({ storage: clientStorage });代码中的几个关键细节createMMKV()的默认行为无参调用会创建一个 ID 为mmkv.default的默认实例见 createMMKV.ts 与 MMKVFactory.nitro.ts 的default mmkv.default。建议将storage与clientPersister在模块顶层导出全应用复用同一个实例而不是每次渲染都新建。getItem必须把undefined转成nullMMKV 的getString在键不存在时返回undefined接口签名见 MMKV.nitro.ts而 AsyncStorage 接口约定键不存在返回null。value undefined ? null : value正是为了满足这一契约避免 persister 把undefined误当作合法值处理。返回值类型react-query 持久化的缓存内容是 JSON 序列化后的字符串storage.set(key, value)写入的正是字符串类型set方法同时支持boolean | number | ArrayBuffer但此处无需使用。从源码看MMKV 的set / getString / remove均为同步方法因此适配器无需async/await也无需返回 Promise——这比基于 AsyncStorage 的异步适配器更简单直接。五、核心步骤三用 PersistQueryClientProvider 接入根组件创建好clientPersister后在根组件如App.tsx中用PersistQueryClientProvider替换普通的QueryClientProviderimport { PersistQueryClientProvider } from tanstack/react-query-persist-client const App () { return ( PersistQueryClientProvider persistOptions{{ persister: clientPersister }} {...} /PersistQueryClientProvider ); };persistOptions.persister即上一步导出的clientPersister。这样应用每次启动时PersistQueryClientProvider会先从 MMKV 中读取上一次保存的缓存走clientStorage.getItem恢复为可用的 Query Cache未过期的查询无需重新请求即可立即渲染运行时查询状态的任何变化都会经clientStorage.setItem / removeItem写回 MMKV。提示persistOptions还支持maxAge缓存最大存活时间、buster缓存失效标识等可选参数可按 TanStack Query 官方文档的createAsyncStoragePersister说明按需配置。六、源码级深入MMKV 实例的配置与行为6.1 可配置项ConfigurationcreateMMKV(configuration?)接受完整的配置对象相关类型定义见 MMKVFactory.nitro.ts配置项类型默认值说明idstringmmkv.default实例 ID多实例场景必须使用不同 IDpathstringundefined存储根目录默认$(Documents)/mmkv/iOS 上配置了 AppGroup 且未指定 path 时自动使用 AppGroup 目录encryptionKeystringundefined加密密钥AES-128 最长 16 字节AES-256 最长 32 字节encryptionTypeAES-128 \| AES-256AES-128加密算法modesingle-process \| multi-processsingle-process多进程模式App Clip、扩展、后台服务等readOnlybooleanfalse只读模式只允许读set会抛错compareBeforeSetbooleanfalse写入前先比较新旧值相等则跳过文件写入作为可选性能优化recoveryStrategydiscard-on-error \| recover-on-errorundefined存储出现 CRC/长度错误时的恢复策略针对 react-query 持久化场景常见进阶写法// 多用户场景按用户隔离查询缓存 export const queryStorage createMMKV({ id: query-cache-${userId} }) // 敏感查询缓存加密落盘 export const secureStorage createMMKV({ id: secure-query-cache, encryptionKey: my-encryption-key!, encryptionType: AES-256, })6.2 底层方法签名适配器用到的三个方法在 MMKV.nitro.ts 中定义如下set(key: string, value: boolean | string | number | ArrayBuffer): voidL44-L44——空 key 会抛错getString(key: string): string | undefinedL56-L56——键不存在返回undefined这正是适配器需要转null的原因remove(key: string): booleanL77-L77——键被删除返回true否则返回false。此外 MMKV 实例还提供getBoolean / getNumber / getBuffer / contains / getAllKeys / clearAll / trim等方法以及addOnValueChangedListener值变更监听能力可在需要同步多实例缓存时使用。6.3 平台与测试环境行为Web 平台仓库提供独立的 Web 实现createMMKV.web.ts底层基于 localStorage 的读写适配器写法保持一致测试环境在 Jest 等测试环境中createMMKV会返回内存 Mock 实例见 createMockMMKV.ts其getString对缺失键同样返回undefined、set对空 key 抛错行为与真实实现对齐因此你的clientStorage适配器可以直接在单测中验证例如断言写入后可读回、缺失键返回 null。七、实践建议与注意事项始终导出并复用实例在模块顶层创建storage与clientPersister并导出避免每次渲染新建 MMKV 实例导致重复打开文件句柄。getItem的null转换不可省略直接返回storage.getString(key)的undefined会导致 persister 行为异常务必按文档写法处理。持久化内容为字符串react-query 缓存以 JSON 字符串形式存取storage.set(key, value)不会做类型推断直接写入即可如需额外存布尔/数字型业务数据MMKV 也原生支持。多实例隔离需要按用户或按模块隔离查询缓存时使用不同的id创建多个实例并在适配器中分别引用。敏感数据可加密若查询缓存包含 token、个人信息等可配置encryptionKeyencryptionType: AES-256密钥长度须符合算法要求。清除缓存需要登出清缓存时可调用storage.clearAll()清空该实例全部键值或storage.remove(key)定向删除某个缓存条目。八、同系列方案对比横向参考本仓库 docs 目录下还提供了其他状态管理库的 MMKV 适配模板可对照参考Zustand persist-middleware 适配同样实现setItem / getItem / removeItem三方法getItem使用value ?? null的写法MMKV 返回undefined时经空值合并得到nullRedux-persist 适配由于 redux-persist 接口是异步的适配器将同步调用包装进Promise.resolve(...)返回Jotai、MobX、Recoil、TinyBase 等适配思路一致均是把各库的存储接口映射到 MMKV 的同步 API 上。可以看到React Query 的适配器之所以无需 Promise 包装正是因为createAsyncStoragePersister直接接受同步风格的 AsyncStorage 兼容对象这也是三者中写法最简洁的一个。九、小结通过三个步骤即可完成 react-query 查询缓存向 MMKV 的迁移安装tanstack/query-async-storage-persister与tanstack/react-query-persist-client用createMMKV()set / getString / remove实现clientStorage并牢记getItem的undefined → null转换再经createAsyncStoragePersister生成clientPersister在根组件用PersistQueryClientProvider包裹应用并传入persistOptions.persister。结合仓库源码createMMKV.ts、MMKV.nitro.ts、MMKVFactory.nitro.ts可以看到这一方案充分利用了 MMKV 同步、快速、类型丰富的特性让 react-query 的缓存持久化获得原生级的读写性能且适配代码量极小、易于测试与维护。赞分享【免费下载链接】react-native-mmkv⚡️ The fastest key/value storage for React Native. ~30x faster than AsyncStorage!项目地址https://gitcode.com/gh_mirrors/re/react-native-mmkv点击查看免费下载相关推荐react-native-mmkv 与 Recoil 集成用 atomEffect 实现 atom 状态持久化react native mmkv 与 Recoil 集成用 atomEffect 实现 atom 状态持久化 Recoil 的 atom 状态默认只存在于内react-native-mmkv 的 redux-persist 存储封装用 MMKV 同步持久化 Redux 状态react native mmkv 的 redux persist 存储封装用 MMKV 同步持久化 Redux 状态 本文基于仓库文档 docs/WRAPP用 instantdb/react-native-mmkv 为 Instant 的 React Native 应用接入 MMKV 本地存储用 instantdb/react native mmkv 为 Instant 的 React Native 应用接入 MMKV 本地存储 本指南以 clie后端数据库上一篇如何为 FunASR 的 Paraformer 输出时间戳带时间戳语音识别指南下一篇知识蒸馏在现代AI中的5大应用场景Awesome Knowledge Distillation实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考