KV存储缓存移动开发存储【免费下载链接】MMKVAn efficient, small mobile key-value storage framework developed by WeChat. Works on Android, iOS, macOS, Windows, POSIX, and OHOS.项目地址https://gitcode.com/gh_mirrors/mm/MMKV点击查看免费下载导读mmkv_platform_interface是 MMKV 官方 Flutter 插件flutter/mmkv所依赖的公共平台接口包它把 MMKV 的全部原生能力初始化、编解码、进程间同步、加密、备份恢复等抽象为统一的 Dart 接口让 Android、iOS、Linux、Windows、OHOS 等各平台实现遵循同一套契约。本文以 flutter/mmkv_platform_interface/README.md 为骨架结合 接口源码、FFI 辅助类 以及各平台真实实现完整讲解平台接口的架构、如何扩展自定义平台实现、接口包含的能力全集以及 Flutter 官方推荐的“非破坏性变更”演进策略帮助你理解并二次开发 MMKV 的 Flutter 绑定。一、平台接口是什么为什么 MMKV Flutter 插件需要它Flutter 插件生态中有一个成熟的架构约定主插件包与平台实现解耦中间通过一个独立的“平台接口platform interface”包对齐契约。mmkv_platform_interface就是这个契约层主包flutter/mmkv只面向业务开发者提供MMKV、NameSpace、MMKVHandler等易用 API平台接口包定义抽象的MMKVPluginPlatform声明了与底层原生 MMKV 一一对应的函数签名各平台包flutter/mmkv_ios、flutter/mmkv_android、flutter/mmkv_linux、flutter/mmkv_win32、flutter/mmkv_ohos继承该接口并给出各自的原生实现。正如 README 所述这一接口的作用是“允许平台特定实现与插件本身确保它们支持同一套接口”。从源码可以印证这种解耦的彻底程度——主插件包 mmkv.dart 中所有底层调用都不是直接调用具体平台代码而是先通过MMKVPluginPlatform.instance获取当前注册的实现再调用其暴露的函数例如_getMMKVWithID _mmkvPlatform.getMMKVWithIDFunc()也就是说业务层与平台层唯一的联系就是MMKVPluginPlatform.instance这个静态实例。二、核心抽象MMKVPluginPlatform 与 MMKVPluginPlatformFFI2.1 抽象基类 MMKVPluginPlatformMMKVPluginPlatform是所有 MMKV 平台插件实现必须继承的抽象基类其关键设计点如下持有静态实例static MMKVPluginPlatform? instance null平台包在注册时通过MMKVPluginPlatform.instance MyMMKVPluginPlatform()注入默认实现持有MMKVHandler? theHandler用于承载日志重定向、CRC 校验失败恢复策略、进程间变更通知等回调每个方法默认throw UnimplementedError()即“平台必须实现否则调用即抛错”提供getApplicationDocumentsPath()与getTemporaryPath()两个可覆写点默认基于path_provider实现因为“有些平台并未在 pub.dev 发布自己的 path_provider 包”见源码注释。2.2 FFI 辅助类 MMKVPluginPlatformFFI为了让 FFI 型平台实现免于重复编写底层查找逻辑仓库提供了 MMKVPluginPlatformFFIDynamicLibrary nativeLib()告诉框架去哪个动态库查找符号默认抛UnimplementedError由具体平台覆写String nativeFuncName(String name)提供一个“映射原生函数名”的机会用于避免符号冲突默认原样返回它基于dart:ffi的DynamicLibrary.lookupNativeFunction...().asFunction()模式为接口中绝大部分方法实现了符号查找逻辑例如getMMKVWithIDFunc()查找 C 函数getMMKVWithID、encodeBoolV2Func()查找encodeBool_v2等freePtrFunc()带有保护逻辑若原生库未导出freePtr早期版本不支持则回退到calloc.free见 CHANGELOG v2.2.3 “Protect from freePtr() not found”。因此一个典型的 FFI 平台实现只需要覆写nativeLib()以及按需覆写nativeFuncName()和initialize()即可获得整套 MMKV 能力的绑定。这也解释了为什么 README 建议自定义平台实现时去参考mmkv_ios或mmkv_android——它们都是继承MMKVPluginPlatformFFI的最小化示例。三、实战如何实现并注册一个新的 MMKV 平台实现README 给出的使用方法是本文的核心实操内容完整流程如下3.1 继承接口并实现平台行为import package:mmkv_platform_interface/mmkv_platform_interface.dart; class MyMMKVPluginPlatform extends MMKVPluginPlatform { // 在这里实现平台相关的具体行为 override FutureString initialize(String rootDir, {String? groupDir, int logLevel 1, ...}) async { // 调用原生 MMKV 初始化返回实际的 rootDir return rootDir; } // 其余方法encode/decode/reKey/...按需覆写 }如果是基于 FFI动态库符号的实现更推荐继承MMKVPluginPlatformFFI只需覆写动态库来源class MyMMKVPluginPlatform extends MMKVPluginPlatformFFI { override DynamicLibrary nativeLib() { return DynamicLibrary.open(libmmkv.so); } override String nativeFuncName(String name) { return my_prefix_$name; // 按需避免符号冲突 } }3.2 注册为默认实现在插件注册时设置默认平台实例void registerWith() { MMKVPluginPlatform.instance MyMMKVPluginPlatform(); }这一步是 README 强调的关键动作只有设置了instance主插件包flutter/mmkv中的MMKV.initialize()、MMKV(mmapID)等 API 才能真正工作因为 mmkv.dart 中final MMKVPluginPlatform _mmkvPlatform MMKVPluginPlatform.instance!;在库加载时就会读取该实例并抓取全部函数指针。3.3 参考官方示例实现README 明确指出可参考两个官方实现作为范本flutter/mmkv_ios/lib/mmkv_ios.dartMMKVPlatformIOS通过DynamicLibrary.process()获取宿主进程已加载的动态库并把所有原生函数名统一加上mmkv_前缀覆写nativeFuncName返回mmkv_$name初始化时调用mmkvInitializeflutter/mmkv_android/lib/mmkv_android.dartMMKVPlatformAndroid通过DynamicLibrary.open(libmmkv.so)加载 JNI 侧编出的共享库初始化时额外通过MethodChannel(mmkv)查询getSdkVersion、并用getTemporaryPath()获取缓存目录后调用mmkvInitialize_v2。此外仓库还提供了更多同构实现佐证这一模式的普适性flutter/mmkv_linux/lib/mmkv_linux.dart 加载libmmkv_linux_plugin.so调用mmkvInitializeflutter/mmkv_win32/lib/mmkv_win32.dart 加载mmkv_win32_plugin.dll初始化返回PointerUtf16Windows 宽字符路径flutter/mmkv_ohos/lib/mmkv_ohos.dart 则走MethodChannel(mmkv)的initializeMMKV调用并覆写了getApplicationDocumentsPath()/getTemporaryPath()两个 path_provider 缺口的场景对应了 2.1 节提到的“某些平台未发布 path_provider 包”的设计动机。四、接口能力全景从初始化到备份恢复虽然 README 未逐一列举但接口源码中约 70 个函数签名构成了 MMKV 完整的能力矩阵。按功能归类如下便于二次实现时对照4.1 初始化与实例管理接口方法对应原生能力initialize(rootDir, groupDir, logLevel, logHandler)全局初始化返回实际根目录如 iOS App Group 目录getMMKVWithIDFunc()按mmapID创建/获取实例含 mode、cryptKey、rootDir、expectedCapacity、namespace、aes256、过期、compare-before-set、恢复策略、itemSizeLimit 等参数getDefaultMMKVFunc()获取通用默认实例mmapIDFunc()查询实例的 IDmmkvCloseFunc()永久关闭底层原生实例removeStorageFunc()删除数据文件与.crc元文件checkExistFunc()/isFileValidFunc()检查实例存在性与文件有效性4.2 数据编解码含 V2 过期版本Bool、Int32、Int64、Double、Bytes 各有一套encode*/decode*其中*V2Func()变体额外接收expiredInSeconds参数用于单 key 级过期见 mmkv.dart 的 encodeBool/encodeInt32 等实现中expireDurationInSecond可选参数。此外还有valueSizeFunc()查询 key 值实际占用大小writeValueToNBFunc()写入预分配的原生缓冲区allKeysFunc()/containsKeyFunc()/countFunc()遍历与查询removeValueForKeyFunc()/removeValuesForKeysFunc()/clearAllFunc()删除能力。4.3 加密与安全reKeyFunc()/cryptKeyFunc()/checkReSetCryptKeyFunc()重设密钥、查询密钥、多进程场景下仅重置密钥不加密均支持 AES-256见 CHANGELOG v2.3.0业务侧约束cryptKey最多 16 字节见 mmkv.dart 中MMKV构造注释。4.4 进程间同步与回调注册registerErrorHandlerFunc()注册错误回调CRC 校验失败、文件长度错误对应MMKVRecoverStrategic恢复策略registerContentHandlerFunc()/registerContentLoadedHandlerFunc()注册进程间内容变更通知与加载完成通知checkContentChangedFunc()手动检查其他进程是否修改了内容isMultiProcessFunc()/isReadOnlyFunc()查询实例模式。4.5 备份恢复与其他工具backupOneFunc()/restoreOneFunc()/backupAllFunc()/restoreAllFunc()单实例与全量备份恢复CHANGELOG v2.2.0 起逐步引入importFromFunc()从另一个 MMKV 实例导入全部键值v2.2.1 新增enableAutoExpireFunc()/disableAutoExpireFunc()、enableCompareBeforeSetFunc()/disableCompareBeforeSetFunc()自动过期与写前比较开关trimFunc()/clearMemoryCacheFunc()/mmkvSyncFunc()文件瘦身、内存缓存清理、手动同步pageSizeFunc()/versionFunc()/groupPathFunc()系统信息查询groupPath仅 iOS 多进程 App Group 场景非 Darwin 平台返回 null见 mmkv.dartgetNameSpaceFunc()校验自定义根目录路径是否有效对应MMKV.nameSpace(path)memcpyFunc()/freePtrFunc()内存拷贝与指针释放Windows 场景尤为重要见 CHANGELOG v2.2.2。五、回调契约MMKVHandler、日志级别与恢复策略接口包还定义了业务方可覆写的回调模型这些类型也被主包export出去直接暴露给业务开发者5.1 MMKVLogLevel 与 MMKVRecoverStrategicenum MMKVLogLevel { Debug, Info, Warning, Error, None } enum MMKVRecoverStrategic { OnErrorDiscard, OnErrorRecover }MMKVLogLevel对应原生日志级别MMKV.initialize(logLevel: MMKVLogLevel.Info)默认 InfoMMKVRecoverStrategic.OnErrorDiscard为默认策略CRC 校验失败或文件长度错误时丢弃全部数据OnErrorRecover则尽可能恢复数据。5.2 MMKVHandler 回调集MMKVHandler定义了一组带默认行为的虚回调回调默认行为用途wantLogRedirect()false是否开启日志重定向mmkvLog(level, file, line, function, message)print 重定向日志自定义日志输出onMMKVCRCCheckFail(mmapID)OnErrorDiscardCRC 校验失败恢复策略onMMKVFileLengthError(mmapID)OnErrorDiscard文件长度错误恢复策略wantContentChangeNotification()false是否启用进程间变更通知onContentChangedByOuterProcess(mmapID)空实现其他进程修改内容时回调onMMKVContentLoadSuccessfully(mmapID)空实现文件加载成功回调v2.4.0 新增从 mmkv.dart 的初始化逻辑可以看到回调如何被桥接到原生若handler.wantLogRedirect()返回 true则通过Pointer.fromFunctionLogCallbackWrap(_logRedirect)注册日志回调_errorHandler将原生错误类型映射为_MMKVErrorTypeMMKVCRCCheckFail / MMKVFileLength并转调onMMKVCRCCheckFail/onMMKVFileLengthError内容变更与加载完成通知同样以原生回调方式注册。六、版本演进与破坏性变更策略README 特别强调“本包强烈倾向于非破坏性变更如给接口新增一个方法而不是破坏性变更”并引用了 Flutter 官方关于“为什么一个不那么干净的接口优于破坏性变更”的讨论flutter.dev/go/platform-interface-breaking-changes。这一策略在 CHANGELOG.md 中有清晰体现v1.0.02024-04-19初始发布后续功能几乎都以“新增方法”方式平滑演进v1.0.1 增加 path_provider 覆写点、v2.0.0/v2.1.0 才因getNameSpace()等引入刻意为之的 2.x 版本“Bump to setup a breaking change version”、v2.2.x 增加freePtr/importFrom、v2.3.0 支持 AES-256、v2.4.0 增加MMKVConfig与defaultMMKV(config)支持及onMMKVContentLoadSuccessfully即使需要变更也尽量通过新增方法或新增参数完成避免既有平台实现全部失效。对于维护自定义平台的开发者这意味着一套兼容原则向接口新增方法时应尽量为它提供默认实现或至少不删除旧方法升级平台接口版本时检查 CHANGELOG 中标注的 breaking change 版本如 v2.0.0、v2.1.0。七、在 Flutter 项目中使用与二次开发建议7.1 引入方式在pubspec.yaml中声明依赖即可接口包本身依赖flutter、ffi、path_provider见 pubspec.yamldependencies: mmkv_platform_interface: ^2.4.0业务侧通常不需要直接依赖该包——flutter/mmkv主包已export了MMKVHandler、MMKVLogLevel、MMKVRecoverStrategic等类型见 mmkv.dart 的 export 语句业务代码直接使用主包 API 即可。7.2 二次开发清单若你要为某个新平台或自有引擎接入 MMKV继承MMKVPluginPlatformFFI 场景继承MMKVPluginPlatformFFI逐项覆写 4.x 小节列出的函数覆写initialize()返回真实的 rootDir参考 Android/iOS/Linux/Windows/OHOS 五个官方实现注意 Windows 返回Utf16、OHOS 走 MethodChannel 的差异若目标平台没有 path_provider 支持覆写getApplicationDocumentsPath()/getTemporaryPath()在插件注册时执行MMKVPluginPlatform.instance YourPlatform();变更接口时遵循“非破坏性优先”原则并同步更新 CHANGELOG 与版本号。7.3 进一步阅读接口完整定义lib/mmkv_platform_interface.dartFFI 绑定辅助类lib/mmkv_platform_ffi.dart主插件消费方flutter/mmkv/lib/mmkv.dart版本演进记录flutter/mmkv_platform_interface/CHANGELOG.md示例实现Androidmmkv_android、iOSmmkv_ios、Linuxmmkv_linux、Windowsmmkv_win32、OHOSmmkv_ohos总结mmkv_platform_interface遵循 Flutter 官方插件架构的最佳实践用一套统一抽象把 MMKV 原生能力完整映射到 Dart 世界业务层只面对MMKVPluginPlatform.instance平台层只需继承接口或 FFI 辅助类并注册实例。本文覆盖了从抽象基类设计、FFI 辅助、五个官方平台实现、完整能力矩阵到回调契约与版本演进策略的全部要点无论是理解 MMKV Flutter 插件的工作原理还是为新的平台接入自定义实现都可以以此作为直接的代码与设计参考。赞分享KV存储缓存移动开发存储【免费下载链接】MMKVAn efficient, small mobile key-value storage framework developed by WeChat. Works on Android, iOS, macOS, Windows, POSIX, and OHOS.项目地址https://gitcode.com/gh_mirrors/mm/MMKV点击查看免费下载相关推荐webview_flutter_platform_interface 深入解析Flutter WebView 插件平台接口设计与自定义实现指南webview_flutter_platform_interface 深入解析Flutter WebView 插件平台接口设计与自定义实现指南 webview移动开发跨平台path_provider_platform_interface 深入解析Flutter 路径提供插件的统一平台接口设计path_provider_platform_interface 深入解析Flutter 路径提供插件的统一平台接口设计 path_provider_plat移动开发跨平台Flutter 官方插件平台接口解析shared_preferences_platform_interface 的设计与实现Flutter 官方插件平台接口解析shared_preferences_platform_interface 的设计与实现 导读 shared_prefer移动开发跨平台上一篇rqlite集群元数据备份确保配置信息安全下一篇基于 ONNX 的 DUC 语义分割模型实战ResNet101_DUC_HDC 的推理、验证与 INT8 量化指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考