kv4cj 版本演进全解:从 V1.0.0 到 V1.0.3 的功能清单与 Cangjie 适配历程
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 做二次开发或功能扩展时最值得复用的查证路径。