kv4cj API参考手册：MMKV类全接口速查（附常用示例代码）

kv4cj API参考手册MMKV类全接口速查附常用示例代码【免费下载链接】kv4cj一个轻量级的键值存储库项目地址: https://gitcode.com/Cangjie-TPC/kv4cjkv4cj 是一个用仓颉语言Cangjie封装的高性能键值存储库核心就是对MMKV类的完整 API 封装初始化、创建实例、各类类型读写、删除清理、备份恢复、日志回调、加密存储。本文按功能分区梳理 MMKV 类全接口速查表并附上常用示例代码新手照着即可上手。⚡ 30秒快速上手创建第一个 kv4cj 键值存储只需三步初始化根目录 → 创建实例 → 读写键值import kv4cj.* main() { MMKV.initializeMMKV(rootdir) // 1. 初始化根目录 var kv MMKV.mmkvWithID(MyID) // 2. 创建实例 kv.set(greeting, Hello kv4cj) // 3. 写入 println(kv.getString(greeting)) // 读取 }上图展示了 kv4cj 的分层结构仓颉语言层src/mmkv.cj通过 src/native.cj 桥接 C 层 MMKV 内核完成键值存储的高性能读写。 kv4cj 全局常量与类型速查在 src/mmkv_handler.cj 中定义了日志等级等常用常量使用接口前建议先熟悉常量值说明MMKVLogDebug0调试级日志发布版不可用MMKVLogInfo1默认日志等级MMKVLogWarning2警告级日志MMKVLogError3错误级日志MMKVLogNone4关闭全部日志MMKV_SINGLE_PROCESS0x1单进程模式默认MMKV_MULTI_PROCESS0x2多进程模式OnErrorDiscard0出错时丢弃数据OnErrorRecover1出错时尽量恢复数据 MMKV 初始化与实例创建接口接口作用常见用法initializeMMKV(rootDir)设定根目录必须最先调用MMKV.initializeMMKV(rootdir)initializeMMKV(rootDir, logLevel)自定义日志等级见 src/mmkv.cjinitializeMMKV(rootDir, logLevel, handler)自定义日志等级回调见 src/mmkv.cjdefaultMMKV()获取全局默认实例见 src/mmkv.cjdefaultMMKV(mode, cryptKey)指定模式加密密钥的默认实例见 src/mmkv.cjmmkvWithID(mmapID)创建自定义 ID 实例见 src/mmkv.cjmmkvWithID(mmapID, mode, cryptKey, rootPath)全参数创建实例见 src/mmkv.cjgetRootDir()获取当前根目录见 src/mmkv.cj提示mmkvWithID提供 5 种重载ID / 模式 / 密钥 / 路径等组合按需选用。完整签名说明见 doc/feature_api.md。 MMKV 键值读写 set/get 全类型速查kv4cj 支持 8 种常见类型的读写set写入成功返回truekey 为空返回falseget系列在 key 不存在时返回默认值。定义见 src/mmkv.cj写入读取类型默认值set(key, true)getBool(key)Boolfalseset(key, 1)getInt32(key)Int320set(key, 1u)getUInt32(key)UInt320set(key, 1L)getInt64(key)Int640set(key, 1Lu)getUInt64(key)UInt640set(key, 1.0F)getFloat32(key)Float320.0set(key, 1.0)getFloat64(key)Float640.0set(key, s)getString(key)Stringset(key, arr)getBytes(key)Array空数组set(key, set)getStringSet(key)HashSet空集合常用读写示例来自 test/DOC/testExample4.cjkv.set(bool, true) var value kv.getBool(bool) kv.set(string, Hello from mmkv) var str kv.getString(string)️ 删除、清理与关闭接口接口作用备注removeValueForKey(key)删除单个 key见 src/mmkv.cjremoveValuesForKeys(arrKeys)批量删除多个 key见 src/mmkv.cjclearAll()清空全部键值文件体积不会缩小trim()回收删除后占用的磁盘空间大量删除后调用见 src/mmkv.cjclose()关闭实例不再需要时调用clearMemoryCache()释放内存缓存下次访问会从文件重新加载onExit()应用退出时销毁 MMKV静态方法注意clearAll()/ 删除键值后totalSize()不会减小在意磁盘占用时请调用trim()。 MMKV sync 与 async 同步到磁盘接口方式适用场景sync()同步落盘阻塞当前线程关键数据写入后立即保证持久化async()异步落盘不阻塞日常高频写入两者都通过内存映射把修改内容刷到硬盘实现见 src/mmkv.cj。 内存信息与统计接口速查接口返回值说明pageSize()Int64内存分页大小通常 4096containsKey(key)Bool判断 key 是否存在count()UInt64键值对总数totalSize()UInt64实例文件大小对齐磁盘块actualSize()UInt64实例实际使用大小getValueSize(key, actualSize)UInt64单个 key 值的大小消耗allKeys()HashSet获取所有 keymmapID()String获取实例 IDisFileValid(mmapID)Bool检测 MMKV 文件是否有效实现位于 src/mmkv.cj完整示例可参考 test/LLT/test_count.cj 与 test/LLT/test_allKeys.cj。⚠️isFileValid只用于校验文件有效性不要用它判断实例是否存在不存在的实例结果未知。 MMKV 备份与恢复接口用法支持按实例或全量备份/恢复全部为静态方法签名详见 doc/feature_api.md接口作用返回值backupOneToDirectory(mmapID, dstDir)备份单个实例BoolrestoreOneFromDirectory(mmapID, srcDir)恢复单个实例BoolbackupAllToDirectory(dstDir)备份全部实例成功个数restoreAllFromDirectory(srcDir)恢复全部实例成功个数备份恢复示例来自 test/DOC/testBackupAndRestore.cjvar backupDir /tmp/mmkv_backup MMKV.backupOneToDirectory(MyID, backupDir) MMKV.restoreOneFromDirectory(MyID, backupDir)每个接口均提供带rootPath的重载可指定自定义根路径实现见 src/mmkv.cj。 MMKV 日志等级设置与回调 Handler 注册通过 MMKVHandler 结构体注册回调可接管日志输出、CRC 校验失败、文件长度异常、多进程内容变更四类事件var handler MMKVHandler() handler.mmkvLog { level, file, line, function, message println(r-${level} ${file}:${line}:${function} ${message}) } handler.onMMKVCRCCheckFail { mmapID return OnErrorRecover } MMKV.registerHandler(handler)接口作用setLogLevel(level)单独调整日志等级registerHandler(handler)注册日志/异常/内容变更回调unregiserHandler()注销回调处理器完整示例见 test/DOC/testLog.cj接口实现见 src/mmkv.cj。 加密存储cryptKey / reKey / checkReSetCryptKey创建实例时传入cryptKey即可启用 AES 加密注意cryptKey 最长 16 字节超出部分被截断接口作用cryptKey()获取当前加密密钥reKey(cryptKey)重置密钥自动加解密已有数据checkReSetCryptKey(cryptKey)多进程场景下检查并同步新密钥实现见 src/mmkv.cj示例参考 test/DOC/testCryptkey.cj。⚙️ NativeBuffer高性能读取原生内存接口作用creatBuffer(size)创建 native 缓冲区writeValueToBuffer(key, buffer)按 key 读值并写入缓冲区返回写入大小destoryBuffer(buffer)必须手动销毁避免内存泄漏使用示例来自 test/DOC/testNativeBuffer.cjvar nbuff kv.creatBuffer(200) var size kv.writeValueToBuffer(set0, nbuff) kv.destoryBuffer(nbuff) // 用完必须销毁NativeBuffer结构体定义见 src/mmkv.cj。 MMKVException 异常捕获未初始化就创建实例、内存分配失败、模式参数非法等场景都会抛出 MMKVException推荐全局兜底try { var kv MMKV.mmkvWithID(test) } catch (e: MMKVException) { println(e) // MMKVException: You should Call MMKV.initializeMMKV() first. }常见异常触发点来自 src/mmkv.cj未先调用initializeMMKV()→ You should Call MMKV.initializeMMKV() first.实例创建失败native 返回 0→ Fail to create an MMKV instance日志等级或模式参数非法 → illegal value✅ 新手避坑清单先初始化再创建实例任何defaultMMKV/mmkvWithID调用前必须先initializeMMKVcryptKey 不超过 16 字节超长会被静默截断key 为空set返回falseget系列返回默认值删除后要trim()否则磁盘占用不减少NativeBuffer 用完必须destoryBufferisFileValid不能判断实例是否存在 相关文件与文档完整 API 文档含全部接口签名与示例doc/feature_api.mdMMKV 核心类实现src/mmkv.cj回调与常量定义src/mmkv_handler.cj异常类定义src/util.cj功能示例test/DOC/单元测试test/LLT/ 与 test/HLT/【免费下载链接】kv4cj一个轻量级的键值存储库项目地址: https://gitcode.com/Cangjie-TPC/kv4cj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考