kv4cj 版本演进全解:从 V1.0.0 到 V1.0.3 的功能清单与 Cangjie 适配历程

原创2026-10-14 22:44:041,876 阅读
文章标签:KV存储缓存

kv4cj 版本演进全解:从 V1.0.0 到 V1.0.3 的功能清单与 Cangjie 适配历程

kv4cj 是腾讯 MMKV 在 Cangjie(仓颉)语言上的键值存储封装库,底层基于 mmap 内存映射实现高性能 key-value 持久化。本文以仓库 CHANGELOG.md 为主线,逐版本解读 kv4cj 从 V1.0.0 到 V1.0.3 的演进脉络与能力清单,并结合 src 源码、doc/feature_api.md API 文档、native 封装层与测试用例,还原每个功能模块的接口形态与底层实现路径。读完本文,你将掌握 kv4cj 已交付的全部能力边界、各 Cangjie 编译器版本的适配关系,以及如何在仓库中定位任意功能的源码实现。

版本演进总览

CHANGELOG 以极简的方式记录了 kv4cj 的四个发布版本,其核心叙事是跟随 Cangjie 编译器的版本迭代而持续适配:

版本 适配的 Cangjie 编译器 变更要点
V1.0.0 — 首次发布,交付完整的 key-value 存取、清理删除、内存信息、加密、备份恢复、日志等能力清单
V1.0.1 cangjie-0.58.3 适配编译器版本更新
V1.0.2 cangjie-0.60.5 适配编译器版本更新
V1.0.3 cangjie-1.0.0 适配编译器版本更新,为当前仓库最新版本

从 cjpm.toml 可以看到当前发布态的工程配置:cjc-version = "1.0.0" 与 version = "1.0.3",恰好与 CHANGELOG 中"V1.0.3 适配 cangjie-1.0.0"一一对应。也就是说,V1.0.1 到 V1.0.3 属于典型的编译器跟随型发布——功能面保持稳定,重点在于让 kv4cj 在 Cangjie 工具链的每次迭代后仍能正常编译链接运行。

V1.0.0 则是功能交付的里程碑版本,CHANGELOG 用一份结构化清单列出了全部能力,下文将逐项展开,并对照 doc/feature_api.md 与源码逐一印证。

V1.0.0 能力清单一:存取 key-value 值

CHANGELOG 首先列出的是核心读写能力——"存储 XXX 类型的 key-value 值 / 读取 XXX 类型的 key-value 值"。对照 doc/feature_api.md 第 3 节,kv4cj 支持以下 8 种数据类型,均提供成对的 set / get 接口:

类型 写入接口 读取接口 读取默认值
Bool set(key, value: Bool) getBool(key, defaultValue! = false) false
Int32 set(key, value: Int32) getInt32(key, defaultValue! = 0) 0
UInt32 set(key, value: UInt32) getUInt32(key, defaultValue! = 0) 0
Int64 set(key, value: Int64) getInt64(key, defaultValue! = 0) 0
UInt64 set(key, value: UInt64) getUInt64(key, defaultValue! = 0) 0
Float32 set(key, value: Float32) getFloat32(key, defaultValue! = 0.0) 0.0
Float64 set(key, value: Float64) getFloat64(key, defaultValue! = 0.0) 0.0
String set(key, value: String) getString(key, defaultValue! = "") ""
Array<Byte> set(key, value: Array\<Byte\>) getBytes(key, defaultValue! = Array\<Byte\>()) 空数组
HashSet<String> set(key, value: HashSet\<String\>) getStringSet(key, defaultValue! = HashSet\<String\>()) 空集合

值得注意的设计细节:

  • 默认值通过 defaultValue! 具名参数提供,调用时可以省略,读取不存在的 key 时返回默认值而不是抛异常,这与 MMKV 的语义保持一致。
  • set 返回 Bool,当 key 为空等非法情况下返回 false;get 系列在 key 为空或不存在时回落到默认值。
  • 底层通过 FFI 调用 native 层完成序列化。以 src/native.cj 为例,setBool_c、setInt32_t_c、setString_c、setBytes_c、setStringSet_c 与对应的 get*_c 系列逐一绑定;Cangjie 层的 set/get 封装位于 src/mmkv.cj。

实际使用示例(取自 test/DOC/testExample4.cj):

import kv4cj.*

main() {
    MMKV.initializeMMKV("rootdir")
    var kv = MMKV.mmkvWithID("MyID")
    kv.set("bool", true)
    var value = kv.getBool("bool")

    kv.set("int32", 0x11223344)
    var iValue = kv.getInt32("int32")

    kv.set("string", "Hello from mmkv")
    var str = kv.getString("string")

    return 0
}

编译命令(README 中的标准链接参数):

cjc --import-path build -Lbuild/kv4cj -Llib -lcore -lkv4cj_mmkv -lmymmkv testExample4.cj -o main

V1.0.0 能力清单二:清理、删除与关闭操作

CHANGELOG 罗列了生命周期管理的全部操作,这与 doc/feature_api.md 第 4 节以及 src/mmkv.cj 的封装一一对应:

CHANGELOG 描述 接口 说明
根据键值删除值,多个操作 removeValuesForKeys(arrKeys: Array<String>) 批量删除,native 层 mmkv_cpp/native-mmkv.cpp 的 removeValuesForKeys_c 将其转换为 vector<string> 后调用 kv->removeValuesForKeys(keys)
根据键值删除值,单个操作 removeValueForKey(key: String) 单个删除
删除所有 key-value 对 clearAll() 删除后 MMKV 文件大小不会立即减小
裁剪内存块 trim() 大量删除后回收磁盘占用;native 层注释明确指出"clearAll 具有与 trim 相似的效果"
关闭实例 close() 实例在不久的将来不再需要时调用,之后对实例的任何调用属于未定义行为
同步内容到硬盘 sync() / async() 以内存映射文件方式将修改同步到硬盘
清理内存缓存 clearMemoryCache() 面临内存警告时调用,后续调用会重新从文件加载所有 key-value
销毁 mmkv MMKV.onExit() 静态方法,应用终止时调用

其中 sync / async 在 native 层共用同一个入口 sync_c(kv, sync: Bool)(见 mmkv_cpp/native-mmkv.cpp),通过布尔参数区分同步刷盘与异步刷盘两种 SyncFlag。

删除语义验证可以参照 LLT 测试 test/LLT/test_removeValueForKey.cj 与 test/DOC/testRemove.cj:先 set 再 removeValueForKey,随后 getString 不应再取回原值。此外 test/LLT/test_clearAll.cj、test/LLT/test_trim.cj、test/LLT/test_close.cj、test/LLT/test_clearMemoryCache.cj、test/LLT/test_sync.cj、test/LLT/test_onExit.cj 分别覆盖了本小节每个接口的行为。

V1.0.0 能力清单三:获取内存相关信息

CHANGELOG 将内存信息拆为两组,分别对应静态信息与实例级信息。

平台级静态信息

  • 获取内存分页大小:MMKV.pageSize(): Int64。native 层实现为 pageSize_c(),直接返回 DEFAULT_MMAP_SIZE。从运行日志可见典型 x86_64 Linux 下分页大小为 4096,与 MMKV 日志中 "page size 4096" 一致,也是 MMKV 默认 mmap 文件大小。

实例级信息接口

CHANGELOG 描述 接口 语义
键值的实际大小 getValueSize(key, actualSize: Bool): UInt64 actualSize = true 返回值的实际长度,false 返回值的实际存储消耗
判断是否存在这个 key-value containsKey(key: String): Bool 是否存在该 key
返回 key-value 的数量 count(): UInt64 键值对个数
获取总共的内存大小(文件大小) totalSize(): UInt64 底层文件大小,向磁盘块大小对齐
获取实际使用大小 actualSize(): UInt64 实际使用大小
获取所有的 key allKeys(): HashSet\<String\> 返回全部 key 的集合
获取 m_mmapID mmapID(): String 实例 ID

这些接口在 src/native.cj 中均有对应 FFI 声明(getValueSize_c、containsKey_c、count_c、totalSize_c、actualSize_c、allKeys_c、mmapID_c),封装位于 src/mmkv.cj。功能示例可参考 test/DOC/testMemory.cj:写入多个不同类型的值后,通过 allKeys() 与期望集合比对验证;LLT 侧则有 test/LLT/test_actualSize.cj、test/LLT/test_allKeys.cj、test/LLT/test_containsKey.cj、test/LLT/test_count.cj、test/LLT/test_getValueSize.cj、test/LLT/test_totalSize.cj、test/LLT/test_mmapID.cj 逐项覆盖。

V1.0.0 能力清单四:根路径、文件有效性检测与初始化

CHANGELOG 单列的两项能力,加上初始化相关的配套接口(在 README.md 与 doc/feature_api.md 中定义),共同构成 kv4cj 的"生命周期起点"。

  • 获取 mmkv 根路径:MMKV.getRootDir(): String,返回初始化时设定的根目录。示例 test/DOC/testRootdir.cj 在 initializeMMKV("rootdir") 后直接断言返回值等于 "rootdir"。
  • 检测 MMKV 文件是否有效:MMKV.isFileValid(mmapID) 及带 rootPath 的重载版本。注意约束:不要用它来检查实例是否存在,对从未创建过的文件返回值是未定义的。示例 test/DOC/testCheckFile.cj 先写入 100 个 key-value,验证文件有效后删除对应的 .crc 校验文件,再验证 isFileValid 返回 false——直观演示了 CRC 校验文件在文件有效性判定中的作用。
  • 初始化接口:MMKV.initializeMMKV(rootDir),以及在指定 logLevel、MMKVHandler 下的多个重载,必须在获取任何 MMKV 实例之前调用,否则抛出 src/util.cj 中定义的 MMKVException(错误信息示例为 "You should Call MMKV.initializeMMKV() first.")。
  • 实例创建:MMKV.defaultMMKV() 创建全局默认实例(对应文件 mmkv.default),MMKV.mmkvWithID(mmapID) 创建独立实例;两者均支持 MMKVMode(单进程 MMKV_SINGLE_PROCESS = 0x1 为默认、多进程 MMKV_MULTI_PROCESS = 0x2)与 cryptKey 参数组合,见 doc/feature_api.md 第 2 节。示例代码位于 test/DOC/testExample1.cj、test/DOC/testExample2.cj、test/DOC/testExample3.cj,LLT 测试见 test/LLT/test_init.cj 目录下的 initialize/defaultMMKV/mmkvWithID 系列。

V1.0.0 能力清单五:native 内存缓冲操作

CHANGELOG 单独列出的"开辟内存空间 / 地址从整型转换为 CPointer 型 / 释放内存空间 / 按 key 获取值并写到 ptr 内存"四项,对应 doc/feature_api.md 第 11 节的 NativeBuffer 能力:

/* native memory 封装,必须手动执行 destoryBuffer 销毁 */
public struct NativeBuffer {
    public var pointer: CPointer<Unit> = CPointer<Unit>() // native memory 指针
    public var size: Int32 = 0                            // native memory 大小
}

配套的三个实例方法:

接口 语义
creatBuffer(size: UIntNative): NativeBuffer 申请一段 native 内存(对应 CHANGELOG"开辟内存空间")
writeValueToBuffer(key: String, buffer: NativeBuffer): Int32 按 key 取值写入 ptr 内存,返回写入大小;内存不够直接返回 -1
destoryBuffer(buffer: NativeBuffer): Unit 释放内存,必须手动调用以避免内存泄漏

使用约束:writeValueToBuffer 与 destoryBuffer 的 buffer 参数必须是 creatBuffer 的返回值,传入其他值会产生不可预知的问题。NativeBuffer.pointer 即"地址从整型转换为 CPointer 型"的载体,native 层由 writeValueToBuffer_c(mmkv_cpp/native-mmkv.cpp)转发到 kv->writeValueToBuffer(strkey, ptr, size)。完整示例见 test/DOC/testNativeBuffer.cj 与 test/LLT/test_writeValueToBuffer.cj,运行输出显示 32 字节字符串写入与回读一致。

V1.0.0 能力清单六:加密 key-value

加密是 kv4cj 的重要能力,CHANGELOG 的三条记录对应 doc/feature_api.md 第 12 节的三个接口:

CHANGELOG 描述 接口 语义
获取加密密钥 cryptKey(): String 返回当前实例的加密密钥
重置加密密钥,并用新密钥重置 mmkv 实例 reKey(cryptKey: String): Bool 修改加密密钥并重写整个实例内容
重置加密密钥,不修改 mmkv 实例中已保存内容 checkReSetCryptKey(cryptKey: String): Unit 检测密钥是否被其他进程改过,若被改则以新密钥重新读取

关键约束:cryptKey 最大长度为 16 字节字符串,超过 16 字节则截取前 16 字节(doc/feature_api.md 前置条件,并在 defaultMMKV / mmkvWithID 的参数注释中重复声明)。

测试 test/DOC/testCryptkey.cj 展示了两个典型场景:对无密钥实例调用 checkReSetCryptKey("rekeyrekey") 触发 "setting new aes key",随后 cryptKey() 返回新密钥;对以 "checkKeyXXXX" 创建密钥的实例调用 checkReSetCryptKey("") 则触发 "reset aes key"。LLT 侧对应 test/LLT/test_cryptKey.cj、test/LLT/test_reKey.cj、test/LLT/test_checkReSetCryptKey.cj。

V1.0.0 能力清单七:上锁解锁与进程变更检测

CHANGELOG 在 V1.0.0 中规划了实例的并发控制能力:

  • 锁定 / 解锁 / 尝试锁定 MMKV 实例:对应 native 层的 lock_c、unlock_c、tryLock_c(见 mmkv_cpp/native-mmkv.cpp),分别转发到 MMKV 的 lock()、unlock()、try_lock();tryLock 在获取失败时返回 false 而不会阻塞。FFI 声明位于 src/native.cj,native 单测可见 test/LLT-native/native-mmkv-ut.cpp。
  • 手动检查进程更改 mmkv 实例:对应 native 层 checkContentChanged_c,转发到 kv->checkContentChanged(),用于多进程场景下手动确认其他进程是否修改了共享实例内容。

需要说明的是:从 src/mmkv.cj 当前源码结构看,上述两项能力的 native 绑定已就绪,但公开的 Cangjie API 封装暂未在 mmkv.cj 中直接暴露,CHANGELOG 记录的是 V1.0.0 交付清单中的规划能力。多进程内容变更的通知路径则已完整落地:通过 MMKVHandler.onMMKVContentChange 回调(见下文 log 处理小节)在任意 get/set 调用后触发。

V1.0.0 能力清单八:备份和恢复 mmkv 实例

CHANGELOG 列出的四项备份恢复能力,对应 doc/feature_api.md 第 8 节与 src/mmkv.cj 中的静态方法:

接口 返回值 语义
backupOneToDirectory(mmapID, dstDir) Bool 从根目录备份一个实例到 dstDir
backupOneToDirectory(mmapID, dstDir, rootPath) Bool 从自定义根目录 rootPath 备份一个实例
restoreOneFromDirectory(mmapID, srcDir) Bool 从 srcDir 恢复一个实例到根目录
restoreOneFromDirectory(mmapID, srcDir, rootPath) Bool 从 srcDir 恢复一个实例到自定义根目录
backupAllToDirectory(dstDir) / (dstDir, rootPath) UInt64 备份所有实例,返回成功个数
restoreAllFromDirectory(srcDir) / (srcDir, rootPath) UInt64 恢复所有实例,返回成功个数

native 层实现位于 mmkv_cpp/native-mmkv.cpp 的 backupOne / restoreOne / backupAll / restoreAll:srcDir / dstDir 为空时分别回落为根目录,随后调用 MMKV::backupOneToDirectory、MMKV::restoreOneFromDirectory 等静态接口。运行日志显示备份实际执行的是主文件与 .crc 校验文件的双文件复制(先经 /tmp/MMKV.xxxx 临时文件再落到目标目录)。

集成示例 test/DOC/testBackupAndRestore.cj 演示了完整流程:备份 test/Encrypt 实例到备份目录 → 恢复 → 读取校验(getInt32("set1") 应为 -444);随后创建 test1、test2 两个实例执行 backupAllToDirectory / restoreAllFromDirectory,断言返回个数为 3(含此前实例)。LLT 覆盖见 test/LLT/test_backupAndRestore.cj。

V1.0.0 能力清单九:log 打印处理

CHANGELOG 的 log 处理三条记录,对应 doc/feature_api.md 第 9 节与 src/mmkv_handler.cj:

  • 设置 log 打印等级:MMKV.setLogLevel(level: MMKVLogLevel)。等级常量定义在 src/mmkv_handler.cj:MMKVLogDebug = 0(release 构建不可用)、MMKVLogInfo = 1(默认等级)、MMKVLogWarning = 2、MMKVLogError = 3、MMKVLogNone = 4(禁用全部日志)。native 层 setLogLevel_c 直接转发到 MMKV::setLogLevel。
  • 注册 / 注销 MMKV 日志函数:MMKV.registerHandler(handler: MMKVHandler) / MMKV.unregiserHandler()。

MMKVHandler 是 @C 结构体,包含四个回调(全部默认空函数指针):

回调字段 触发时机
mmkvLog: LogHandler 每条日志输出,签名 (level, file, line, function, message) -> Unit
onMMKVCRCCheckFail: ErrorHandler CRC32 校验失败,返回 OnErrorRecover = 1(尽力恢复)或 OnErrorDiscard = 0(默认,丢弃数据)
onMMKVFileLengthError: ErrorHandler 文件长度不匹配,同样返回恢复策略
onMMKVContentChange: ContentChangeHandler 进程间内容变更通知,在任意 get/set 或 checkContentChanged 调用后触发

native 层 setCallbackHandler(mmkv_cpp/native-mmkv.cpp)会根据回调是否注册,动态挂接 MMKV::registerLogHandler、registerErrorHandler、registerContentChangeHandler 或对应的注销方法。示例 test/DOC/testLog.cj 演示了注册自定义日志回调(输出带 r- 前缀的日志行)、注册错误恢复策略与内容变更回调,随后注册 unregiserHandler() 观察日志回到默认 <a href="https://link.gitcode.com/i/7afa16c5d6f25f4e4f9c90e435baa554" target="_blank">I] 前缀格式。LLT 覆盖见 [test/LLT/test_setLogLevel.cj 与 test/LLT/test_handler.cj。

从 CHANGELOG 看仓库工程结构

围绕 CHANGELOG 的功能清单,仓库的工程组织方式如下(完整目录见 README.md):

  • src/mmkv.cj:全部公开 API 的 Cangjie 封装(初始化、读写、清理、内存信息、加密、备份恢复、日志、NativeBuffer 等);
  • src/mmkv_handler.cj:日志等级、恢复策略、错误类型常量与 MMKVHandler 回调结构体;
  • src/util.cj:MMKVException 异常类型;
  • src/native.cj:foreign 块集中声明所有 native FFI 绑定(*_c 函数);
  • mmkv_cpp:native 接口封装层,native-mmkv.cpp 将 Cangjie 调用桥接到底层 MMKV C++ 库(含 Makefile / configure 构建);
  • doc/feature_api.md:API 手册,CHANGELOG 每个功能条目都能在此找到签名、参数与示例;
  • test:DOC(文档示例)、HLT(功能级测试,按 mmkv_*_001.cj 命名)、LLT(接口级测试,按 test_*.cj 命名)、LLT-native(native 层 C++ 单测)四类测试。

构建脚本 build_linux.sh 的流程也印证了版本演进:先检查 lib/libcore.so(由 MMKV 编译产物放入根目录 lib 文件夹),再进入 mmkv_cpp 执行 ./configure && make 生成 libmymmkv.so,最后 cjpm build -V 构建 kv4cj 动态库并拷贝到 target/release/kv4cj/。Windows 侧对应 build_win.bat。同时仓库还提供了 build_aarch64.sh 与 build_ohos.sh,后者对应 cjpm.toml 中的 aarch64-linux-ohos 目标配置(OpenHarmony 交叉编译选项),可见 kv4cj 面向多架构、多平台的适配意图。

结语

CHANGELOG 虽然只有寥寥数行,却精确勾勒出 kv4cj 的交付全貌:V1.0.0 一次性落地了从 key-value 读写、生命周期管理、内存信息、加密、备份恢复到日志回调的完整能力矩阵,V1.0.1 至 V1.0.3 则紧随 Cangjie 编译器从 0.58.3、0.60.5 到 1.0.0 的演进完成适配。借助 doc/feature_api.md、src 源码与 test 测试三层佐证,开发者可以在任一功能条目上快速定位到"接口签名 → Cangjie 封装 → FFI 绑定 → native 实现 → 测试用例"的完整链路,这也是后续基于 kv4cj 做二次开发或功能扩展时最值得复用的查证路径。

登录后查看全文
kv4cj