KV 存储 on JasperSao的博客

KV 进化（二）：Snapshot 全量快照 + AOF 增量日志

Sun, 30 Aug 2026 00:00:00 +0800

这篇承接《KV 进化（一）：给 91kvstore 接上一条跳表》。上一阶段完成了第四种存储引擎的接入，这一阶段继续解决一个更实际的问题：服务退出以后，内存中的数据怎样留下来？

本文记录从 AOF 基础闭环，到全量快照，再到通过 AOF_OFFSET 连接二者的完整实现过程。

1. 确立实现模式

项目采用混合持久化模式：

全量快照：保存某一时刻完整的数据集。
AOF 增量日志：每次成功执行写命令后，记录这条命令。

AOF 的基础闭环为：

执行写命令
→ 写入 AOF
→ 服务重启
→ 读取 AOF
→ 重新执行历史命令
→ 恢复内存数据

加入全量快照以后，最终恢复流程变成：

加载全量快照
→ 获得快照对应的 AOF 偏移量
→ 从偏移量开始重放 AOF
→ 恢复出最新数据

2. 建立独立的持久化模块

持久化属于独立的辅助模块，不应该把所有文件操作都堆在 kvstore.c 中，因此新增：

include/persistence.h
src/persistence/aof.c
src/persistence/snapshot.c

其他模块通过：

#include "persistence.h"

使用持久化功能。

头文件中声明了 AOF 对外提供的接口：

int kvs_aof_open(const char *path);
int kvs_aof_append(char **tokens, int count);
int kvs_aof_close(void);
long long kvs_aof_get_offset(void);

为了实现重放，又增加了回调函数类型：

typedef int (*aof_replay_handler)(
 char *msg,
 int length,
 char *response
);

以及 AOF 重放接口：

int kvs_aof_replay(
 const char *path,
 long long offset,
 aof_replay_handler handler
);

快照模块对外提供：

int kvs_snapshot_save(const char *path);

long long kvs_snapshot_load(
 const char *path,
 aof_replay_handler handler
);

aof_replay_handler 是函数指针类型。重放函数读取到一条命令后，可以通过这个函数指针把命令交给 kvs_protocol() 执行。

3. 打开和关闭 AOF

AOF 文件使用一个模块内部的文件指针保存：

static FILE *aof_fp = NULL;

打开文件时使用追加模式：

aof_fp = fopen(path, "a");

"a" 表示 append，也就是从文件末尾追加内容，不会覆盖已有日志。

kvs_aof_open() 需要检查：

path 是否为 NULL
AOF 是否已经打开
fopen() 是否成功

约定返回值：

0 成功
-1 失败

关闭时使用：

int ret = fclose(aof_fp);
aof_fp = NULL;

即使 fclose() 失败，也要把 aof_fp 设置为 NULL。因为调用 fclose() 以后，不应该继续使用原来的文件指针。

4. 把命令追加到 AOF

协议层已经把命令切分到了 tokens 中。例如：

SET name Jasper

切分以后是：

tokens[0] = "SET"
tokens[1] = "name"
tokens[2] = "Jasper"
count = 3

kvs_aof_append() 首先检查：

AOF 文件是否已经打开
tokens 是否为 NULL
count 是否为 2 或 3
对应位置的 token 是否存在

之后使用 fprintf() 把 tokens 重新组合成一条完整命令：

fprintf(aof_fp, "%s %s\n",
 tokens[0], tokens[1]);

或者：

fprintf(aof_fp, "%s %s %s\n",
 tokens[0], tokens[1], tokens[2]);

因此 AOF 文件中的内容类似：

SET persist_key persist_value
MOD persist_key new_value
DEL persist_key

每条命令占一行，这样重放时才能确定不同命令之间的边界。

5. 从缓冲区同步到文件

fprintf() 返回值大于等于 0，只能说明格式化写入没有在这一层报告错误。数据可能仍然位于 C 标准库维护的用户态缓冲区中。

因此先调用：

fflush(aof_fp);

它会把 C 标准库缓冲区中的数据交给操作系统。

但是数据此时仍可能位于操作系统的页缓存中，所以继续调用：

fsync(fileno(aof_fp));

这里涉及两种文件表示：

FILE * C 标准库使用的文件流
fd 操作系统使用的整数文件描述符

fsync() 接收文件描述符，所以需要使用：

fileno(aof_fp)

把 FILE * 转换成对应的 fd。

于是一次追加的顺序是：

fprintf
→ fflush
→ fileno
→ fsync

其中任何一步失败，kvs_aof_append() 都返回 -1。

6. 判断哪些命令需要写入 AOF

AOF 只记录会改变数据的命令：

SET
DEL
MOD

查询命令不需要记录：

GET
EXIST

当前项目中，每个数据结构引擎的命令都按照五个一组排列：

SET GET DEL MOD EXIST

所以可以通过 cmd % 5 判断命令类型：

static int kvs_is_write_command(int cmd)
{
 if (cmd < KVS_CMD_START || cmd >= KVS_CMD_COUNT) {
 return 0;
 }

 switch (cmd % 5) {
 case 0:
 case 2:
 case 3:
 return 1;
 default:
 return 0;
 }
}

对应关系是：

0 → SET
1 → GET
2 → DEL
3 → MOD
4 → EXIST

7. 只有命令执行成功才记录

AOF 的写入位置是在业务命令执行完成、拿到 ret 之后。

原因是：如果命令执行失败，却仍然被写进 AOF，那么下次重启时可能恢复出一个与用户实际操作结果不一致的数据集。

当前判断为：

if (!aof_replaying &&
 ret == 0 &&
 kvs_is_write_command(cmd)) {

 int aof_ret = kvs_aof_append(tokens, count);

 if (aof_ret < 0) {
 fprintf(stderr, "failed to append AOF\n");
 exit(EXIT_FAILURE);
 }
}

三个条件分别表示：

!aof_replaying 当前不是重放阶段
ret == 0 业务命令执行成功
kvs_is_write_command(cmd) 当前是写命令

如果业务数据已经修改成功，但是 AOF 写入失败，服务选择立即退出。否则程序继续运行，就会出现：

内存中修改成功
→ AOF 中没有记录
→ 服务重启
→ 用户的数据丢失

8. AOF 重放

AOF 重放必须放在 KV 引擎初始化之后，因为历史命令最终要重新写进内存数据结构。

同时，重放必须发生在以追加模式打开 AOF 之前。

在只实现 AOF 的阶段，启动顺序是：

初始化 KV 引擎
→ 进入 AOF 重放状态
→ 读取并执行历史 AOF
→ 退出 AOF 重放状态
→ 以追加模式打开 AOF
→ 启动网络服务

aof_replaying 的含义是：

0 → 正常运行，可以记录新的写命令
1 → 正在恢复历史数据，不能写入 AOF

注意，它表示“正在重放”，不是“正在重写”。

它只能在函数外定义一次：

static int aof_replaying = 0;

如果在 kvs_filter_protocol() 内再次定义同名变量，就会发生变量遮蔽。这样主函数修改的是外层变量，而协议处理函数读取的是内部变量，二者不是同一个变量。

9. AOF 重放函数的实际过程

kvs_aof_replay() 使用只读模式打开 AOF：

FILE *fp = fopen(path, "r");

如果文件不存在，说明当前没有历史数据，可以直接返回成功：

if (errno == ENOENT) {
 return 0;
}

之后使用 getline() 每次读取一行：

while ((line_length = getline(&line, &capacity, fp)) != -1) {

假设读取到：

SET persist_key persist_value

之后，通过传入的回调函数执行它：

char response[1024] = {0};

int response_length = handler(
 line,
 (int)line_length,
 response
);

因为调用 kvs_aof_replay() 时传入的是：

kvs_protocol

所以这次调用实际相当于：

kvs_protocol(line, (int)line_length, response);

历史命令因此重新进入原来的协议层和业务层，不需要为重放重新写一套 SET、MOD、DEL 逻辑。

当返回值有效，并且响应为：

OK\r\n

说明这一条历史命令重放成功。否则重放失败，服务不继续启动。

10. AOF 基础闭环

AOF 阶段已经测试：

SET persist_key persist_value
MOD persist_key new_value

服务重启以后执行：

GET persist_key

能够得到：

new_value

同时，重放期间不会把历史命令再次追加到 AOF，所以文件不会随着每次重启产生重复日志。

至此，AOF 的基础闭环完成。但是如果 AOF 中存在大量历史命令，每次重启都从第一条开始执行，恢复时间会越来越长。所以接下来需要实现全量快照。

11. 开始实现全量快照

AOF 保存的是每一次成功执行的写命令，而全量快照保存的是某一个时刻内存中的完整数据集。

例如执行过：

SET name Jasper
MOD name Sao

AOF 中保存的是操作过程：

SET name Jasper
MOD name Sao

而快照只关心最终数据状态：

SET name Sao

因此，保存快照时不能简单复制 AOF。我们需要遍历当前内存中的数据，把每一个有效的 key-value 写进快照文件。

项目中存在多个 KV 引擎：

array
rbtree
hash
skiplist

每一种数据结构的遍历方式不同：

数组需要遍历每一个槽位。
红黑树需要按照节点关系递归遍历。
哈希表需要遍历桶以及桶中的链表。
跳表需要沿着最底层链表遍历。

但是持久化模块不应该知道这些数据结构的内部实现。

所以采用统一的设计：

引擎负责找到 key 和 value
→ 持久化模块负责把 key 和 value 写入文件

12. 定义统一的访问函数

在 kvstore.h 中定义访问函数类型：

typedef int (*kvs_visit_handler)(
 const char *key,
 const char *value,
 void *context
);

这个函数指针表示：

引擎每找到一组 key-value
→ 就调用一次 visitor
→ 把 key、value 和 context 交给 visitor

三个参数分别表示：

key 当前遍历到的键
value 当前遍历到的值
context 调用者额外传入的信息

每一个引擎分别提供自己的遍历函数：

int kvs_array_foreach(
 kvs_array_t *inst,
 kvs_visit_handler visitor,
 void *context
);

int kvs_rbtree_foreach(
 kvs_rbtree_t *inst,
 kvs_visit_handler visitor,
 void *context
);

int kvs_hash_foreach(
 kvs_hash_t *inst,
 kvs_visit_handler visitor,
 void *context
);

int kvs_skiplist_foreach(
 kvs_skiplist_t *inst,
 kvs_visit_handler visitor,
 void *context
);

虽然四个引擎内部的遍历方法不同，但是对外接口的形式相同。

13. foreach 的职责

以数组引擎为例：

int kvs_array_foreach(
 kvs_array_t *inst,
 kvs_visit_handler visitor,
 void *context)
{
 if (inst == NULL ||
 inst->table == NULL ||
 visitor == NULL) {
 return -1;
 }

 for (int i = 0; i < inst->total; i++) {
 if (inst->table[i].key == NULL ||
 inst->table[i].value == NULL) {
 continue;
 }

 int ret = visitor(
 inst->table[i].key,
 inst->table[i].value,
 context
 );

 if (ret < 0) {
 return -1;
 }
 }

 return 0;
}

每一次循环找到一组有效的 key-value，就调用一次：

visitor(key, value, context);

所以遍历函数本身没有耦合具体的文件写入逻辑。它只负责：

找到数据
→ 把数据交给 visitor

真正决定如何使用这些数据的是传进来的 visitor。

14. context 的意义

快照写入函数不只需要 key 和 value，它还需要知道：

应该写入哪个文件。
当前数据来自哪个引擎。
应该使用 SET、RSET、HSET 还是 SSET。

所以定义结构体：

typedef struct snapshot_write_context {
 FILE *fp;
 const char *command;
} snapshot_write_context_t;

这里：

fp 快照文件的文件指针
command 当前引擎对应的写命令

然后把这个结构体的地址作为 void *context 传入遍历函数：

snapshot_write_context_t ctx;

ctx.fp = fp;
ctx.command = "SET";

kvs_array_foreach(
 &global_array,
 snapshot_write_item,
 &ctx
);

此时 &ctx 被转换成了 void *。

进入 snapshot_write_item() 以后，再把它转换回来：

snapshot_write_context_t *ctx =
 (snapshot_write_context_t *)context;

所以 context 并不是“一个数”。它是一个通用指针，这里保存的是 ctx 这个结构体的地址。

15. 把一组 key-value 写进快照

真正负责写入文件的函数是：

static int snapshot_write_item(
 const char *key,
 const char *value,
 void *context)
{
 if (key == NULL ||
 value == NULL ||
 context == NULL) {
 return -1;
 }

 snapshot_write_context_t *ctx =
 (snapshot_write_context_t *)context;

 if (ctx->fp == NULL ||
 ctx->command == NULL) {
 return -1;
 }

 int written = fprintf(
 ctx->fp,
 "%s %s %s\n",
 ctx->command,
 key,
 value
 );

 if (written < 0) {
 return -1;
 }

 return 0;
}

例如数组引擎中存在：

name → Jasper
age → 20

调用两次 snapshot_write_item() 后，快照中会得到：

SET name Jasper
SET age 20

也就是说，每遍历到一个有效数据，就执行一次 snapshot_write_item()。

16. 为什么快照中只保存 SET 类型的命令

快照保存的是当前最终数据集，而不是数据变化的过程。

例如：

SET name Jasper
MOD name Sao
DEL age

最终只剩下：

name → Sao

所以快照只需要保存一条能够重新创建当前数据的命令：

SET name Sao

对于不同引擎，分别使用：

SET 数组引擎
RSET 红黑树引擎
HSET 哈希引擎
SSET 跳表引擎

快照不需要保存 MOD 和 DEL。因为已经被删除的数据不会出现在遍历结果中，而被修改的数据会直接以最终值保存。

17. 保存所有引擎的数据

在 snapshot.c 中访问四个全局引擎：

#if ENABLE_ARRAY
extern kvs_array_t global_array;
#endif

#if ENABLE_RBTREE
extern kvs_rbtree_t global_rbtree;
#endif

#if ENABLE_HASH
extern kvs_hash_t global_hash;
#endif

#if ENABLE_SKIPLIST
extern kvs_skiplist_t global_skiplist;
#endif

然后依次遍历已经启用的引擎：

#if ENABLE_ARRAY
if (result == 0) {
 ctx.command = "SET";

 if (kvs_array_foreach(
 &global_array,
 snapshot_write_item,
 &ctx) < 0) {
 result = -1;
 }
}
#endif

其他引擎对应的命令为：

红黑树 ctx.command = "RSET"
哈希表 ctx.command = "HSET"
跳表 ctx.command = "SSET"

result 用于记录整个快照保存过程是否成功：

0 到目前为止没有失败
-1 某一步已经失败

如果前一个引擎保存失败，后面的引擎就不再继续写。这样可以避免生成一个看起来正常、实际上缺少部分数据的快照。

18. 使用临时文件保存快照

不能直接使用：

fopen(path, "w");

覆盖原来的正式快照。因为如果写到一半时程序崩溃，旧快照已经被破坏，新快照又没有写完整。

所以先生成临时文件路径：

char temp_path[1024];

snprintf(
 temp_path,
 sizeof(temp_path),
 "%s.tmp",
 path
);

例如：

正式文件：snapshot.db
临时文件：snapshot.db.tmp

这里使用 snprintf()，是因为它可以接收缓冲区大小，避免写出的字符串超过 temp_path 的容量。

然后使用 "w" 模式打开临时文件：

FILE *fp = fopen(temp_path, "w");

"w" 表示重新写入。临时文件如果已经存在，原来的内容会被清空。

19. 把快照同步到磁盘

所有引擎遍历完成以后，依次执行：

fflush(fp)
→ fsync(fileno(fp))
→ fclose(fp)

含义与 AOF 相同：

fflush 把 C 标准库缓冲区交给操作系统
fsync 要求操作系统把内容同步到底层存储
fclose 关闭文件

如果任何一步失败：

unlink(temp_path);
return -1;

unlink(temp_path) 的意思是删除失败的临时文件，不是关闭文件。文件已经由 fclose() 负责关闭。

全部成功以后执行：

rename(temp_path, path);

这一步把：

snapshot.db.tmp

替换成：

snapshot.db

因此，快照保存过程是：

写临时文件
→ 确认完整写入
→ 同步到磁盘
→ 关闭临时文件
→ 用临时文件替换正式快照

这样可以尽量避免生成半份快照。

20. 增加 SAVE 命令

在持久化头文件中暴露快照保存接口：

int kvs_snapshot_save(const char *path);

协议层切分完 tokens 后，单独判断：

if (count == 1 && strcmp(tokens[0], "SAVE") == 0) {
 int save_result = kvs_snapshot_save("snapshot.db");

 if (save_result < 0) {
 return sprintf(response, "ERROR\r\n");
 }

 return sprintf(response, "OK\r\n");
}

用户发送：

SAVE

程序就会把当前四个引擎中的完整数据保存到 snapshot.db。

SAVE 本身不是修改 KV 数据的普通业务命令，所以不需要写进 AOF。

21. 快照与 AOF 的重复问题

如果快照已经保存了当前全部数据，而服务启动时又从 AOF 开头执行所有命令，就会出现重复恢复。

例如 AOF 中有：

SET name Jasper
MOD name Sao

快照中已经有：

SET name Sao

启动时先读取快照，内存里已经存在 name。如果又从 AOF 开头执行 SET name Jasper，就可能因为 key 已经存在而失败。

所以快照必须知道：

保存这份快照时，AOF 已经写到了哪个位置。

22. 获取 AOF 当前偏移量

在 AOF 模块中增加：

long long kvs_aof_get_offset(void);

实现过程：

long long kvs_aof_get_offset(void)
{
 if (aof_fp == NULL) {
 return -1;
 }

 off_t offset = ftello(aof_fp);

 if (offset == (off_t)-1) {
 return -1;
 }

 return (long long)offset;
}

off_t 是系统用来表示文件位置和文件大小的类型。

ftello() 返回当前文件位置，也就是 AOF 已经写了多少字节。

假设返回：

表示保存快照时，AOF 的前 189 个字节已经被这份快照包含。

23. 把 AOF 偏移量写进快照

保存快照之前先获取：

long long aof_offset = kvs_aof_get_offset();

然后把它写在快照第一行：

fprintf(fp, "AOF_OFFSET %lld\n", aof_offset);

最终快照类似：

AOF_OFFSET 189
SET persist_key new_value
SET snapshot_array value_array
RSET snapshot_rbtree value_rbtree
HSET snapshot_hash value_hash
SSET snapshot_skiplist value_skiplist

第一行是元数据，不是业务命令。后面的每一行才是用来恢复数据的命令。

24. 加载全量快照

在持久化头文件中增加：

long long kvs_snapshot_load(
 const char *path,
 aof_replay_handler handler
);

这个函数做两件事：

1. 读取并执行快照中的数据命令
2. 返回快照记录的 AOF_OFFSET

使用只读方式打开：

FILE *fp = fopen(path, "r");

如果快照文件不存在，说明以前没有保存过快照：

if (errno == ENOENT) {
 return 0;
}

返回 0 表示：

没有快照数据
→ AOF 应该从第 0 个字节开始重放

25. 读取快照中的偏移量

首先使用 getline() 读取第一行，然后解析：

long long aof_offset = -1;

int parsed = sscanf(
 line,
 "AOF_OFFSET %lld",
 &aof_offset
);

这里：

parsed 成功解析出的字段数量
aof_offset 真正保存偏移量的变量

如果第一行是：

AOF_OFFSET 189

那么：

parsed = 1
aof_offset = 189

如果没有成功读取一个偏移量，或者偏移量小于 0，就说明快照格式错误。

26. 逐行恢复快照数据

读取完第一行以后，继续使用 getline() 循环读取剩余内容：

while ((line_length = getline(&line, &capacity, fp)) != -1) {

getline() 每执行一次，就从文件当前位置读取一行。

读取完成以后，去掉末尾的换行符：

while (line_length > 0 &&
 (line[line_length - 1] == '\n' ||
 line[line_length - 1] == '\r')) {
 line[--line_length] = '\0';
}

然后准备一个响应缓冲区：

char response[1024] = {0};

把快照命令交给协议函数：

int response_length = handler(
 line,
 (int)line_length,
 response
);

因为传进来的 handler 是 kvs_protocol，所以实际效果相当于：

kvs_protocol(line, (int)line_length, response);

例如快照中的：

HSET snapshot_hash value_hash

会重新进入原来的协议解析和哈希引擎处理流程。

response 不会发送给网络客户端，它只用于检查这条恢复命令是否返回：

OK\r\n

所有快照命令恢复成功后，函数返回：

return aof_offset;

27. 让 AOF 从指定位置开始重放

AOF 重放函数的接口改成：

int kvs_aof_replay(
 const char *path,
 long long offset,
 aof_replay_handler handler
);

打开 AOF 后，先执行：

fseeko(fp, (off_t)offset, SEEK_SET);

三个参数表示：

fp 当前 AOF 文件
offset 要跳转到的字节位置
SEEK_SET 从文件开头计算位置

例如：

offset = 189

就表示跳过 AOF 前 189 个字节，只重放后面的增量命令。

这里并不是逐条判断哪些命令应该跳过，而是直接移动文件的读取位置。

28. 最终启动恢复顺序

最终启动过程变成：

初始化所有 KV 引擎
→ 进入恢复状态
→ 加载 snapshot.db
→ 得到 AOF_OFFSET
→ 从该偏移量开始重放 appendonly.aof
→ 退出恢复状态
→ 以追加模式打开 AOF
→ 启动网络服务

代码大致为：

init_kvengine();

aof_replaying = 1;

long long aof_offset = kvs_snapshot_load(
 "snapshot.db",
 kvs_protocol
);

if (aof_offset < 0) {
 aof_replaying = 0;
 fprintf(stderr, "failed to load snapshot\n");
 return -1;
}

int replay_ret = kvs_aof_replay(
 "appendonly.aof",
 aof_offset,
 kvs_protocol
);

aof_replaying = 0;

if (replay_ret < 0) {
 fprintf(stderr, "failed to replay AOF\n");
 return -1;
}

if (kvs_aof_open("appendonly.aof") < 0) {
 fprintf(stderr, "failed to open AOF\n");
 return -1;
}

这里的 aof_replaying 虽然叫做 AOF 重放状态，但是现在它实际上覆盖了整个数据恢复阶段：

加载快照期间 不允许写入 AOF
重放 AOF 期间 不允许写入 AOF

因为快照和 AOF 中的历史命令都会调用 kvs_protocol()。

如果没有这个标志，恢复出来的历史命令又会被当成新的写命令追加到 AOF。

29. 快照与 AOF 最终如何配合

可以把二者理解成：

snapshot.db 保存稳定的历史基础
appendonly.aof 保存快照之后发生的新变化

假设：

AOF 前 189 字节
→ 已经包含在 snapshot.db 中

AOF 第 189 字节以后
→ 是保存快照之后执行的新命令

恢复时：

snapshot.db
→ 恢复保存快照时的完整数据

AOF_OFFSET 之后的 AOF
→ 补上保存快照以后发生的变化

因此最后恢复出的内存状态是：

快照中的完整数据
+
快照之后的增量命令
=
服务退出前的最新数据

30. 最终验证

保存快照时的数据为：

SET persist_key new_value
SET snapshot_array value_array
RSET snapshot_rbtree value_rbtree
HSET snapshot_hash value_hash
SSET snapshot_skiplist value_skiplist

执行：

SAVE

快照记录：

AOF_OFFSET 189

保存完成以后，再执行：

SET after_snapshot from_aof

这条命令没有进入快照，只进入了 AOF 偏移量之后的增量部分。

服务重启以后，输出顺序为：

先执行快照中的五条命令
→ 再执行 SET after_snapshot from_aof
→ 最后开始监听端口

客户端执行：

GET after_snapshot

能够得到：

from_aof

这说明：

全量快照恢复成功
AOF 增量恢复成功
偏移量跳过成功
恢复期间没有重复写入 AOF

31. 当前完成的整体闭环

目前已经完成的混合持久化流程是：

正常运行
→ 成功的写命令立即追加到 AOF
→ 用户执行 SAVE
→ 遍历所有引擎
→ 保存当前完整数据集
→ 在快照中记录 AOF_OFFSET
→ 快照保存后继续记录新的 AOF
→ 服务退出或者崩溃
→ 下次启动先加载快照
→ 再重放 AOF_OFFSET 之后的日志
→ 恢复出最新内存数据
→ 开始对外提供服务

我的理解是：

AOF 负责尽量不丢掉每一次数据变化

快照负责保存某一时刻完整的数据集，
并缩短启动时需要处理的历史范围

AOF_OFFSET 负责把快照和 AOF 连接起来

aof_replaying 负责避免恢复过程再次产生日志

handler 负责让历史命令复用原来的业务处理流程

foreach 负责遍历不同引擎中的有效数据

visitor 负责处理遍历得到的每一组 key-value

context 负责向 visitor 传递文件指针和命令类型

至此，全量快照和 AOF 增量日志已经组成了一个完整的混合持久化闭环。

KV 进化（一）：给 91kvstore 接上一条跳表

Fri, 28 Aug 2026 00:00:00 +0800

这篇不打算深挖跳表算法，而是记录一个外部数据结构如何从“能够独立运行”，一步步变成 91kvstore 中真正可用的存储引擎。

目前这个 KV 存储引擎已经支持三种数据结构：

结构体数组
红黑树
哈希表

那么问题来了：能不能再加入一种新的存储引擎，并且让它像现有的三个引擎一样，通过统一接口和网络命令工作？

这次选择的是——跳表。

最终希望实现这样的效果：

SSET name Jasper
SGET name
SMOD name Sao
SEXIST name
SDEL name

表面上看，只是多写一个 kvs_skiplist.c；但真正有价值的部分并不是手搓跳表，而是研究如何把一个外部数据结构完整地融合进现有项目。

先对跳表有个大致印象

开始之前，我先看了一些简短的跳表介绍，比如这个视频：

B站：跳表相关介绍

现在并不打算深入研究跳表的每一个概率细节，只需要先形成几个基本认知：

跳表的底层仍然是一条有序链表；
它在普通链表上增加了多层索引；
查询时可以从高层快速跳过大量节点；
查找、插入、删除的平均时间复杂度是 O(log n)。

在工程中使用一种数据结构时，确实可以把它当成一个黑盒，但也不能完全不理解。至少要知道：

它需要什么样的输入；
它如何管理内存；
它能提供哪些操作；
它的节点和数据由谁创建、由谁释放。

理解到这个程度，就足够开始融合了。

写跳表之前，我先整理了项目

我多少有点目录洁癖。

原来的 .c、.o、可执行文件和头文件全部堆在项目根目录，看着实在难受。因此没有立刻开始写跳表，而是先参照常见开源项目的结构，把工程重新整理了一遍：

91kvstore/
├── .gitignore
├── .gitmodules
├── Makefile
│
├── clients/
│ ├── go-kvstore.go
│ ├── javakvstore.java
│ ├── js-kvstore.js
│ ├── py-kvstore.py
│ └── rust-kvstore.rs
│
├── include/
│ ├── kvstore.h
│ └── server.h
│
├── src/
│ ├── kvstore.c
│ ├── engines/
│ │ ├── kvs_array.c
│ │ ├── kvs_hash.c
│ │ ├── kvs_rbtree.c
│ │ └── kvs_skiplist.c
│ │
│ └── network/
│ ├── ntyco.c
│ ├── proactor.c
│ └── reactor.c
│
├── tests/
│ └── testcase.c
│
├── third_party/
│ └── NtyCo/ # Git 子模块
│
├── build/ # 编译产物，不提交
│ ├── kvstore.o
│ ├── reactor.o
│ ├── proactor.o
│ ├── ntyco.o
│ ├── kvs_array.o
│ ├── kvs_hash.o
│ ├── kvs_rbtree.o
│ └── kvs_skiplist.o
│
└── bin/ # 可执行文件，不提交
 ├── kvstore
 └── testcase

这样一来，各部分的职责就很直观：

include/ 放公共声明；
src/engines/ 放存储引擎；
src/network/ 放网络模型；
tests/ 放测试程序；
third_party/ 放第三方依赖；
build/ 和 bin/ 只保存编译产物。

规整多了，right？

第一步：把整数跳表改造成字符串 KV

找到的简易跳表实现只支持：

int key;
int value;

但 KV 存储引擎需要的是：

char *key;
char *value;

因此节点最终变成：

typedef struct kvs_skiplist_node {
 char *key;
 char *value;
 struct kvs_skiplist_node **forward;
} kvs_skiplist_node_t;

这里不只是把 int 改成 char * 那么简单。

整数可以直接比较：

node->key < key

字符串必须使用：

strcmp(node->key, key) < 0

同时，字符串不能只保存调用方传进来的地址。节点需要为 key 和 value 单独申请内存并复制内容，否则调用方的字符串失效后，跳表里保存的指针也会失效。

创建一个节点，大致需要依次完成：

为节点结构体申请内存；
为 key 申请内存；
复制 key；
为 value 申请内存；
复制 value；
为每层 forward 指针申请空间。

每一步都可能失败。

如果中途失败，就必须把前面已经申请成功的内存释放掉。否则节点虽然没有创建成功，却会留下内存泄漏。

这部分看起来啰嗦，但它实际上比跳表算法本身更接近真实的 C 工程开发。

第二步：补齐统一接口

原始代码只有插入、查询和展示，但项目中的每个存储引擎都需要提供七个接口：

kvs_skiplist_create
kvs_skiplist_destory
kvs_skiplist_set
kvs_skiplist_get
kvs_skiplist_del
kvs_skiplist_mod
kvs_skiplist_exist

其中比较复杂的是：

set：查找插入位置，并更新多层指针；
get：沿索引层逐级查找；
del：不仅要释放节点，还必须先从每一层中摘除节点。

mod 和 exist 相对简单，因为它们都可以复用内部查询函数：

static kvs_skiplist_node_t *
skiplist_search_node(kvs_skiplist_t *inst, const char *key);

exist 只需要判断查询结果是否为 NULL。

mod 则是在找到节点后，先申请并复制新的 value；成功之后再释放旧 value。这个顺序非常重要：

先申请新内存
 ↓
申请成功
 ↓
释放旧 value
 ↓
替换指针

如果先释放旧 value，再发现新内存申请失败，原来的数据也就丢了。

第三步：统一返回值

接口能工作还不够，它必须遵守现有引擎的返回规则。

最终统一为：

返回值	含义
`0`	操作成功，或者 key 存在
`1`	key 重复，或者 key 不存在
`-1`	参数或实例不合法
`-2`	内存申请失败

具体含义需要结合接口理解。

例如：

kvs_skiplist_set(...)

返回 1 表示 key 已经存在。

而：

kvs_skiplist_del(...)

返回 1 表示 key 不存在。

统一返回规则非常重要，因为协议层并不关心跳表内部发生了什么，它只根据返回值生成响应：

0 → OK
1 → EXIST 或 NO EXIST
< 0 → ERROR

第四步：别让测试变成纯苦力

最开始，每修改一个函数，就在 main() 中增加一堆 if/else，重新编译、运行、检查输出。

写到后面发现，大量测试代码无非是在做：

实际返回值是否等于预期返回值？

于是写了一个辅助函数：

static void check_test(int condition, const char *testName)
{
 if (condition) {
 printf("[PASS] %s\n", testName);
 } else {
 printf("[FAIL] %s\n", testName);
 }
}

测试就能简化为：

result = kvs_skiplist_set(
 skipList,
 "Dad",
 "Jasper"
);

check_test(
 result == 0,
 "set new key"
);

开发接口期间，可以先用 #if 0 屏蔽 main()，每完成一批接口只进行对象文件编译：

gcc -Iinclude \
 -c src/engines/kvs_skiplist.c \
 -o /tmp/kvs_skiplist.o

等全部接口完成后，再临时启用 main()，统一进行一次完整测试。

这样既能及时发现编译错误，也不用每改一个函数就维护一遍测试流程。

第五步：从“能运行”走向“融入项目”

底层接口通过测试，只能说明跳表自己能工作。接下来才是真正的工程融合。

首先，把公共内容移动到 include/kvstore.h：

最大层数定义；
跳表节点类型；
跳表实例类型；
七个公开接口声明。

而这些内部辅助函数仍然留在 .c 文件中，并使用 static 隐藏：

skiplist_create_node
skiplist_random_level
skiplist_search_node

这样外部模块只知道跳表“能做什么”，不需要知道它“具体怎么做”。

接着，把直接使用的：

malloc
free

替换为项目统一封装的：

kvs_malloc
kvs_free

再把：

build/kvs_skiplist.o

加入 Makefile，让跳表参与整个项目的编译与链接。

Makefile 的具体语法还需要继续学习，但目前已经能看懂它最核心的关系：

源文件
 ↓ 编译
对象文件
 ↓ 链接
可执行文件

第六步：创建全局跳表实例

服务器需要一个长期存在的跳表实例，保存所有客户端写入的数据。

因此在 kvs_skiplist.c 中定义：

kvs_skiplist_t global_skiplist;

在 kvstore.c 中声明：

extern kvs_skiplist_t global_skiplist;

这里的 extern 并不会创建第二个跳表，它只是告诉 kvstore.c：

这个变量在其他文件中已经定义，你可以直接使用它。

然后把跳表加入存储引擎生命周期：

kvs_skiplist_create(&global_skiplist);

服务器退出时：

kvs_skiplist_destory(&global_skiplist);

至此，跳表拥有了完整的生命过程：

定义 → 初始化 → 处理请求 → 销毁

第七步：命令协议融合

最后，也是最关键的一步，是让客户端真的能够使用跳表。

加入五条新命令：

SSET
SGET
SDEL
SMOD
SEXIST

项目并不存在一个“当前使用哪个 engine”的开关，而是通过命令前缀直接选择引擎：

SET → array
RSET → rbtree
HSET → hash
SSET → skiplist

例如客户端发送：

SSET Dad Jasper

服务器的处理过程是：

解析 SSET
 ↓
匹配 KVS_CMD_SSET
 ↓
进入 switch 对应分支
 ↓
调用 kvs_skiplist_set()
 ↓
根据返回值生成 OK / EXIST / ERROR

这一步完成后，跳表就不再是一个孤立的 .c 文件，而是真正成为了 KV 存储引擎的一员。

最后：用 testcase 做端到端测试

底层 main() 测试的是跳表接口，而 tests/testcase.c 测试的是完整链路：

测试客户端
 → TCP
 → 网络层
 → 协议解析
 → global_skiplist
 → 跳表接口
 → 协议响应

测试程序会自动发送：

SSET
SGET
SEXIST
SMOD
SDEL

然后将服务器的实际响应与预期结果比较：

相同 → PASS
不同 → FAILED

相比手动输入命令，这种测试不仅省事，还能在后续修改代码时快速确认：跳表功能有没有被意外破坏。

小结

这次表面上是在“增加一个跳表”，实际上完整经历了一个新模块接入现有项目的过程：

选择基础实现
 → 改造成字符串 KV
 → 补齐统一接口
 → 统一返回规则
 → 完成底层测试
 → 暴露公共声明
 → 接入内存管理
 → 接入 Makefile
 → 创建全局实例
 → 接入生命周期
 → 接入命令协议
 → 完成端到端测试

跳表算法当然重要，但这次更重要的收获是：

一个数据结构能独立运行，和它能成为项目中真正可用的一部分，是两件完全不同的事。

前者解决算法问题，后者解决接口、内存、构建、生命周期、协议和测试问题。

而后面这些，才是这次“KV 进化”真正有意思的地方。

KV 存储项目：Hash 接入、多语言客户端与 SkipList 扩展

Wed, 26 Aug 2026 00:00:00 +0800

阅读目标：在已有 Array、RBTree 和统一协议的基础上，重点复盘 Hash 如何真正成为一个可用的 KV 引擎；随后理解多语言客户端与服务端的边界，并按同一套接入模式继续扩展 SkipList。

本文不讲 Hash 数据结构算法本身，重点是 Hash 与现有 KV 项目的融合。

与前三篇的关系

本文承接以下三篇已有笔记：

《KV 存储项目网络层》已经讲过 Reactor、Proactor、NtyCo 和 msg_handler 回调。
《KV 存储项目：协议层与数组存储》已经讲过 TCP 消息边界、token 解析、协议响应和 Array 的五种操作。
《KV 存储项目：客户端测试、压力测试与多引擎扩展》已经讲过 Makefile 基础、测试用例、压力测试、宏开关、5+2 接口以及 RBTree 的接入模式。

因此本文不再重复网络收发、协议解析、Array/RBTree CRUD、通用测试方法和 5+2 的基础概念，只保留理解 Hash 接入所需的连接点。

1. 本阶段增加了什么

项目之前已经完成：

统一网络入口
 → 文本协议解析
 → Array 引擎
 → RBTree 引擎
 → 客户端测试和压力测试

本阶段增加三项能力：

1. 把 Hash 接入现有 KVEngine
2. 用 Go / Java / Node.js / Python / Rust 操作同一个 KV 服务
3. 按相同模式接入 SkipList，并为范围查询做准备

Hash 部分最值得掌握的不是“冲突链表怎样写”，而是：已经有一份 Hash 代码以后，还要修改项目的哪些位置，它才能从客户端真正访问到？

类型与接口声明
 → 编译和链接
 → 全局实例
 → create 初始化
 → 协议命令分发
 → set/get/del/mod/exist
 → 客户端测试
 → destroy 释放

任何一环缺失，Hash 都没有完整融入项目。

2. Hash 在项目中的位置

Hash 接入后，核心关系变成：

 kvs_protocol()
 │
 kvs_filter_protocol()
 │
 ┌─────────────────┼─────────────────┐
 │ │ │
 Array RBTree Hash
 普通命令前缀 R 命令前缀 H 命令前缀
 │ │ │
 global_array global_rbtree global_hash

网络层仍然只调用 kvs_protocol()，不需要为了 Hash 修改 Reactor、Proactor 或 NtyCo。

协议层也不需要知道桶、哈希下标和冲突链表，只负责把 Hash 命令映射到 kvs_hash_set/get/del/mod/exist。

这体现了已有分层设计带来的扩展性：新增存储引擎，主要修改核心层和构建层，不侵入网络层。

3. 第一个接入点：`kvstore.h`

3.1 增加编译开关

#define ENABLE_HASH 1

它应当像 ENABLE_ARRAY、ENABLE_RBTREE 一样，控制以下内容是否参与编译：

Hash 类型定义；
Hash 函数声明与实现；
global_hash；
Hash 协议分支；
Hash 的初始化与销毁。

宏开关的目的不是只隐藏一个结构体，而是完整地装上或拆下整个引擎。

3.2 Hash 实例在项目中的最小理解

typedef struct hashnode_s {
 char *key;
 char *value;
 struct hashnode_s *next;
} hashnode_t;

typedef struct hashtable_s {
 hashnode_t **nodes;
 int max_slots;
 int count;
} kvs_hash_t;

从 KV 项目角度只需知道：

global_hash
├── nodes 桶数组，每个元素是一条冲突链的头指针
├── max_slots 桶数量
└── count 当前键值对数量

nodes 是二级指针，因为它先表示桶数组，再由每个桶元素指向节点：

nodes[0] → node → node → NULL
nodes[1] → NULL
nodes[2] → node → NULL

发生 Hash 冲突时，相同桶下标的节点通过 next 串在一起。这里只把它作为理解资源释放和实例生命周期的前提，不展开 Hash 算法。

3.3 对外仍然使用已有的 5+2 形状

int kvs_hash_create(kvs_hash_t *hash);
void kvs_hash_destroy(kvs_hash_t *hash);
int kvs_hash_set(kvs_hash_t *hash, char *key, char *value);
char *kvs_hash_get(kvs_hash_t *hash, char *key);
int kvs_hash_del(kvs_hash_t *hash, char *key);
int kvs_hash_mod(kvs_hash_t *hash, char *key, char *value);
int kvs_hash_exist(kvs_hash_t *hash, char *key);

5+2 的设计价值和 RBTree 接入方式已在上一篇说明。这里的新增认识是：Hash 内部可以完全不同，但仍然服从项目已经形成的引擎契约。

4. 第二个接入点：Makefile

本阶段开始把每个 .c 文件单独编译成 .o。Hash 必须进入对象文件集合：

OBJS = kvstore.o reactor.o proactor.o kvs_array.o \
 ntyco.o kvs_rbtree.o kvs_hash.o

kvs_hash.o: kvs_hash.c kvstore.h
	$(CC) $(CPPFLAGS) $(CFLAGS) -c kvs_hash.c -o kvs_hash.o

kvstore: $(OBJS)
	$(CC) -o $@ $(OBJS) $(LDFLAGS) $(LDLIBS)

原笔记中的 OBJS 没有 kvs_hash.o。这意味着即使 kvs_hash.c 已经写好，最终的 kvstore 也没有编译、链接 Hash 实现。

建议把参数按职责拆开：

CC = gcc
CPPFLAGS = -I./NtyCo/core
CFLAGS = -Wall -Wextra -g
LDFLAGS = -L./NtyCo
LDLIBS = -luring -lntyco -lpthread -ldl

相对上一篇 Makefile 笔记，本阶段只需新增一个检查点：

每增加一个 KV 引擎，都要确认它的目标文件同时进入编译规则和最终的 OBJS 链接集合。

如果还要分别生成 kvstore、NtyCo 库和 testcase，可设为三个明确目标：

.PHONY: all ntyco clean

all: ntyco kvstore testcase

ntyco:
	$(MAKE) -C NtyCo

testcase 应有自己的对象文件和链接规则，不要与服务端的 main() 混在同一个目标中。

5. 第三个接入点：实例生命周期

5.1 定义全局实例

#if ENABLE_HASH
static kvs_hash_t global_hash;
#endif

它与已有的 global_array、global_rbtree 并列，是 Hash 引擎在当前进程中的状态容器。

5.2 网络服务启动前创建

#if ENABLE_HASH
if (kvs_hash_create(&global_hash) != 0) {
 /* 初始化失败，不能继续提供 Hash 命令 */
}
#endif

必须先创建引擎，再进入网络循环。否则客户端已经能够发来 HSET，协议层却会访问尚未初始化的桶数组。

5.3 网络服务停止后销毁

#if ENABLE_HASH
kvs_hash_destroy(&global_hash);
#endif

完整顺序为：

创建 Array / RBTree / Hash
 ↓
启动所选网络层
 ↓
处理客户端命令
 ↓
网络层退出
 ↓
销毁 Hash / RBTree / Array

如果网络启动函数永不返回，还需要设计退出信号和优雅关闭流程，否则 destroy 虽然写在 main() 中，正常运行时却永远不会执行。

6. 第四个接入点：协议命令

上一篇已经为 RBTree 增加 RSET/RGET/RDEL/RMOD/REXIST。教学阶段为了让多个引擎同时存在，可以继续采用同一规则：

Array	RBTree	Hash	语义
`SET`	`RSET`	`HSET`	新增键值对
`GET`	`RGET`	`HGET`	查询 value
`DEL`	`RDEL`	`HDEL`	删除键值对
`MOD`	`RMOD`	`HMOD`	修改已有 value
`EXIST`	`REXIST`	`HEXIST`	判断 key 是否存在

协议层识别到 HSET 后调用：

kvs_hash_set(&global_hash, tokens[1], tokens[2]);

其余命令同理。协议层负责将引擎内部返回值翻译成项目已有响应：

OK\r\n
EXIST\r\n
NO EXIST\r\n
具体 value\r\n
ERROR\r\n

需要保持的边界是：

协议层：参数数量、命令选择、响应文本
Hash 层：key/value 保存、查询、修改、删除、资源管理

协议层不能直接访问 global_hash.nodes，否则 Hash 内部实现一改，协议代码也必须跟着改，统一接口就失去了意义。

一条 `HSET` 的新增路径

前三篇已经讲过网络路径和 SET 完整路径，此处只看 Hash 分支的差异：

HSET Teacher King
 → 协议层识别 HSET
 → 检查 token 数量为 3
 → kvs_hash_set(&global_hash, "Teacher", "King")
 → 返回内部状态码
 → 协议层生成 OK / EXIST / ERROR

从网络层到 token 切分的部分与以前完全相同，不需要为 Hash 重写。

7. 当前 Hash 代码必须修正的工程问题

这些问题的重点是内存所有权和项目稳定性，而不是 Hash 算法。

7.1 创建后必须把桶数组清零

hash->nodes = kvs_malloc(sizeof(hashnode_t *) * hash->max_slots);
memset(hash->nodes, 0,
 sizeof(hashnode_t *) * hash->max_slots);

kvs_malloc 返回的内存默认包含不确定值。不清零时，第一次读取 hash->nodes[idx] 就可能取得随机地址。

7.2 下标计算应使用实例容量

当前各操作固定使用 MAX_TABLE_SIZE：

int idx = _hash(key, MAX_TABLE_SIZE);

应改为：

int idx = _hash(key, hash->max_slots);

否则 max_slots 字段形同虚设，将来改变容量或扩容时也会出错。

7.3 创建节点失败要逆序回滚

指针模式下，一个节点的申请顺序是：

node → key 副本 → value 副本

如果 value 申请失败，必须释放已经成功申请的 key 和 node。当前代码释放的是本来就为 NULL 的 kvalue，遗漏了前两块内存。

kvs_hash_set() 也要判断 _create_node() 是否返回 NULL，不能直接执行 new_node->next。

7.4 三条释放路径必须一致

开启 ENABLE_KEY_POINTER 后，一个节点拥有三块内存：

node
├── key
└── value

以下三条路径都必须依次释放 key、value、node：

删除桶的头节点；
删除桶内的普通节点；
销毁整张 Hash 表。

当前普通节点删除路径释放完整，但头节点删除和 destroy 只释放了 node，会发生内存泄漏。

7.5 MOD 要先申请，再替换

当前代码先 free(node->value)，然后申请新 value。如果申请失败，旧值已经丢失，节点中还留下悬空指针。

安全顺序是：

申请新 value
 → 复制成功
 → 保存 old_value
 → node->value = new_value
 → free(old_value)

这样内存申请失败时，旧值仍然有效。

7.6 其他接口一致性问题

kvs_hash_mod() 还要检查 value != NULL。
固定数组模式下，strncpy 后必须保证字符串以 \0 结束。
kvs_hash_count() 已实现，但头文件中缺少声明。
destory 应逐步统一为正确拼写 destroy。
kvs_hash_set() 的参数类型建议统一写成 kvs_hash_t *。
exist 的 0=存在、1=不存在 必须与 Array、RBTree 和协议响应保持一致。
销毁后应将 nodes=NULL、max_slots=0、count=0，降低误用风险。

8. 多语言支持：本阶段新增的认识

上一篇已经介绍过 TCP 客户端测试，第二篇也解释过消息边界，因此这里不再重复 socket 收发和粘包、拆包原理。

本阶段要建立的新认识是：

Go、Java、Node.js、Python 和 Rust 并不直接调用 C 的 Hash 函数；它们都是同一个文本协议的客户端。

语言	TCP 客户端 API	发出的内容
Go	`net.Dial`	UTF-8 协议文本
Java	`Socket`	UTF-8 协议文本
Node.js	`net.createConnection`	UTF-8 协议文本
Python	`socket.socket`	UTF-8 协议文本
Rust	`TcpStream`	UTF-8 协议文本

五种语言的差异只在 socket API，服务端看到的都应该是：

HSET Teacher King\r\n
HGET Teacher\r\n

因此“支持第三方语言”的核心不是编写五套服务端适配层，而是稳定以下契约：

服务器地址和端口；
UTF-8 编码；
请求结束标记；
命令名称和参数数量；
响应格式；
连接是单请求、长连接还是支持流水线；
超时与异常处理方式。

原示例中的 IP 地址有两组：172.16.145.132 和 192.168.243.131，实际测试时应统一为配置项。

用同一场景验证五种语言

不要让五份示例各自测试不同命令。它们应执行同一条状态链：

HSET lang:test C → OK
HGET lang:test → C
HMOD lang:test common → OK
HGET lang:test → common
HEXIST lang:test → EXIST
HDEL lang:test → OK
HGET lang:test → NO EXIST

这样验证的是“协议与 Hash 引擎对所有语言行为一致”，而不只是证明五种语言都能建立 TCP 连接。

正式测试还应给每个客户端加入：

send_all/write_all 语义，防止一次发送没有写完；
按 \r\n 或长度字段读取完整响应；
连接和读取超时；
非 UTF-8 或异常响应处理；
失败时返回非零退出码，便于自动化测试发现失败。

9. 课后扩展：把 SkipList 融入 KVEngine

通常称为 Skip List（跳表），不是 SkipTable。

这道动手题可以直接复用 Hash、RBTree 的接入模板：

1. kvstore.h 增加 ENABLE_SKIPLIST
2. 定义 kvs_skiplist_t
3. 声明 SkipList 的 5+2 接口
4. 新增 kvs_skiplist.c
5. Makefile 加入 kvs_skiplist.o
6. 核心层定义 global_skiplist
7. 启动时 create，退出时 destroy
8. 协议层增加 SSET/SGET/SDEL/SMOD/SEXIST
9. 复制已有状态链，编写 SkipList 端到端测试
10. 检查失败回滚、删除和销毁时的内存所有权

这能完成“把 SkipList 当作普通 KV 引擎接入”，但还没有发挥它的有序性。

9.1 范围查询需要扩展 5+2

原有 5+2 只表达单个 key 的操作，不能表达范围查询。可以增加：

int kvs_skiplist_range(
 kvs_skiplist_t *inst,
 const char *start_key,
 const char *end_key,
 kvs_pair_t *out,
 size_t capacity,
 size_t *count
);

协议层增加：

SRANGE user:100 user:200 LIMIT 50

设计范围接口时要明确：

起止 key 是否包含；
key 按字符串还是数值排序；
最大结果数量；
输出缓冲区由谁分配和释放；
大结果集如何分页；
遍历期间发生修改时怎样保证一致性。

Hash 适合精确点查，但没有顺序；SkipList 和 RBTree 保持 key 有序，更适合范围查询。

10. 面试题

10.1 KV 存储为什么常采用单线程执行命令？

首先修正问题前提：KV 存储不是必须使用单线程。

教学项目或某些内存 KV 的核心命令路径采用单线程，主要因为：

非阻塞 I/O 可以让一个事件循环管理大量连接；
内存 KV 的单次操作通常很短；
串行执行避免共享数据上的锁竞争；
不需要频繁进行线程上下文切换；
命令顺序和数据一致性更容易理解与调试。

它的限制也很明显：慢命令会阻塞后续请求，CPU 密集型任务无法充分利用多核，单实例吞吐最终受单核限制。

常见扩展方式是按 key 分片，每个分片由单线程串行执行，多个分片并行利用多核；也可以让网络 I/O、持久化、内存回收由不同线程负责。

结合当前项目回答时还要看所选网络模型：如果多个线程可能同时调用协议处理函数并访问同一个 global_hash，Hash 就需要互斥锁、分片锁或单写者队列。不能因为包含了 pthread.h，就认为数据已经线程安全。

10.2 范围查询应选择什么 KVEngine？

范围查询要求 key 有序：

引擎	范围查询特点
Hash	无序，适合点查，不适合直接做范围查询
SkipList	定位起点后沿底层链表扫描，适合本项目扩展
RBTree	中序遍历有序，也能实现范围查询
B/B+Tree	适合磁盘页和大规模范围扫描
LSM-Tree	适合高写入吞吐的持久化 KV

本项目的课后题应优先使用 SkipList，并在原有 5+2 之外增加 RANGE 接口。

10.3 频繁 malloc/free 时怎样管理 KV 内存？

当前项目已经通过 kvs_malloc/kvs_free 留出了统一入口。后续可以逐步演进：

在包装层统计分配次数、字节数、峰值和泄漏。
对固定大小的节点使用对象池或 slab。
对不同长度的 key/value 使用 size class 和空闲链表。
一次申请大块内存，再切成多个小对象复用。
多线程下使用线程本地缓存或分片内存池，降低锁竞争。
修改 value 时，如果旧缓冲区容量足够就复用；否则先申请新块，成功后再替换。
设置最大内存、淘汰策略并监控碎片率。

内存池解决的是性能和碎片问题，不能替代正确的所有权规则。无论使用系统分配器还是内存池，都必须明确：谁申请、谁持有、谁释放，以及失败时如何回滚。

11. 本阶段的实施顺序

统一 Hash 返回值与其他引擎的语义
 → 修正初始化、失败回滚、MOD 和三条释放路径
 → Makefile 加入 kvs_hash.o
 → 添加 global_hash 的 create/destroy
 → 协议层增加 HSET/HGET/HDEL/HMOD/HEXIST
 → 复用上一篇测试状态链验证 Hash
 → 五种语言运行完全相同的协议用例
 → 按相同模板接入 SkipList
 → 单独设计 RANGE 接口和测试
 → 压测后再决定分片、加锁和内存池方案

总结

本阶段相对于前三篇真正新增的主线是：

Hash 实现
 → 用统一接口包装
 → 进入 Makefile
 → 进入全局生命周期
 → 进入协议分发
 → 被同一测试链验证
 → 通过统一 TCP 协议服务五种语言

最重要的认识是：

项目扩展的重点不是孤立地增加一种数据结构，而是把它组织成符合现有接口、生命周期、协议和测试约定的 KV 引擎。

SkipList 的课后扩展也应遵循同一思路；只有范围查询属于新的业务能力，需要在原有 5+2 之外明确增加接口。

KV 存储项目：客户端测试、压力测试与多引擎扩展

Tue, 25 Aug 2026 00:00:00 +0800

阅读目标：沿着“建立可重复的测试—用压力测试暴露状态问题—在现有协议后接入第二种 KV 引擎”这条主线，回顾项目从数组存储继续向多引擎结构演进的过程。

本文承接 KV 存储项目网络层：统一接入 Reactor、Proactor 与协程和 KV 存储项目：协议层与数组存储。网络层的 Reactor、Proactor、ntyco，以及 kvs_protocol()、token 切分、数组五种操作等内容，前文已经完整讲过，这里只保留理解本阶段所需的连接点。

本文以学习笔记和当前代码为准，重点解释实现过程、测试现象与架构关系，不展开红黑树算法本身。

1. 这一阶段解决什么问题

前一阶段已经形成了一条可以工作的请求链路：

客户端发送文本命令
 ↓
网络层接收数据
 ↓
kvs_protocol() 切分 token
 ↓
kvs_filter_protocol() 识别命令
 ↓
数组引擎执行 SET / GET / DEL / MOD / EXIST
 ↓
协议层生成 OK / EXIST / NO EXIST / value
 ↓
网络层把响应发回客户端

项目能处理命令以后，下一步不只是继续添加代码，而是先回答三个问题：

已有功能能否被稳定、重复地验证？
测试次数增加后，内部状态是否仍然正确？
协议层能否在数组之外接入新的存储引擎？

所以本阶段的主线是：

Makefile 统一构建
 ↓
TCP 客户端实现自动化功能测试
 ↓
重复执行测试并粗测 QPS
 ↓
通过高次数测试定位数组状态问题
 ↓
保留原有数组引擎，接入红黑树引擎
 ↓
用同一组语义测试第二种引擎

这里体现了一种项目迭代思路：先观察当前代码已经处于什么形态，再决定下一项功能应该接入哪一层。

2. 用 Makefile 固定构建过程

随着源文件增加，手工重复输入完整的 gcc 命令会越来越不方便。最初可以直接把编译过程写进 all：

all:
	gcc -o kvstore kvstore.c reactor.c proactor.c kvs_array.c ntyco.c \
		-I ./NtyCo/core/ -L ./NtyCo/ -luring -lntyco

clean:
	rm -rf kvstore

这条命令由四部分组成：

部分	当前内容	作用
编译器	`gcc`	编译并链接 C 程序
target	`kvstore`	最终生成的程序
sources	`kvstore.c` 等	参加编译的源文件
flags	`-I`、`-L`、`-l`	指定头文件、库目录和链接库

把这些部分提取成变量后，Makefile 中各项职责更清楚：

CC=gcc
TARGET = kvstore
SRCS = kvstore.c reactor.c proactor.c kvs_array.c ntyco.c kvs_rbtree.c
INC = -I ./NtyCo/core/
LIBS = -L ./NtyCo/ -luring -lntyco

all:
	$(CC) -o $(TARGET) $(SRCS) $(INC) $(LIBS)

clean:
	rm -rf kvstore

当前阶段加入红黑树后，构建层面的变化很小：在 SRCS 中加入 kvs_rbtree.c。也就是说，存储引擎虽然增加了，但整个项目仍由同一个 target 统一构建。

2.1 NtyCo 是项目的外部依赖

INC 和 LIBS 都引用了 ./NtyCo/：

INC → ./NtyCo/core/ 中的头文件
LIBS → ./NtyCo/ 中的 libntyco

因此，Makefile 描述的是“依赖已经存在时怎样编译”。如果本地没有 NtyCo 目录，还要先完成依赖准备，也就是把对应代码下载到项目约定的位置，再进行编译。

这可以把构建理解成两个阶段：

准备第三方依赖
 ↓
编译当前项目

Makefile 的价值不只在于少输入一条命令，更重要的是把当前项目由哪些文件、头文件路径和库组成固定下来。

3. 客户端测试用例：把人工验证变成固定流程

测试客户端的基本流程很直接：

1. 建立 TCP 连接
2. 发送一条协议命令
3. 接收服务端响应
4. 将实际响应与预期响应比较
5. 一致则 PASS，不一致则 FAILED

测试代码把这五步拆成几个职责单一的函数：

函数	作用
`connect_tcpserver()`	创建 socket，并连接指定 IP 和端口
`send_msg()`	发送一条测试命令
`recv_msg()`	接收服务端返回值
`testcase()`	完成一次“发送—接收—比较”
`array_testcase()`	组织数组引擎的一组功能场景
`rbtree_testcase()`	组织红黑树引擎的一组功能场景

代码中的注释“一个函数只做一件事”在这里得到了体现：网络连接、一次断言和一组业务场景分别由不同函数承担。

3.1 一个测试用例包含什么

testcase() 接收四项信息：

void testcase(int connfd, char *msg, char *pattern, char *casename)

它们分别表示：

参数	含义	示例
`connfd`	已连接的 TCP socket	与 KV 服务端的连接
`msg`	发给服务端的命令	`SET Dad Jasper`
`pattern`	期望得到的响应	`OK\r\n`
`casename`	用于输出的测试名称	`SET-Dad`

测试执行过程可以压缩为：

msg ──send──> KV 服务端
 │
 └── response ──recv──> result
 │
 strcmp(result, pattern)
 │ │
 相同 不同
 │ │
 PASS FAILED

因此，测试用例并不需要知道数组或红黑树内部怎样保存数据。它只站在客户端角度检查协议行为，这正好覆盖了完整链路：

TCP 收发 + 协议解析 + 引擎操作 + 响应生成

4. 一组完整场景不只是“五条命令”

项目一共有五种基础操作：

SET / GET / DEL / MOD / EXIST

但“覆盖五个命令”不等于每个命令只执行一次。当前 array_testcase() 实际组织了九个连续步骤：

顺序	请求	预期响应	验证的状态
1	`SET Dad Jasper`	`OK`	新键可以写入
2	`GET Dad`	`Jasper`	写入后的值可以读出
3	`MOD Dad Sao`	`OK`	已存在的键可以修改
4	`GET Dad`	`Sao`	修改结果已经生效
5	`EXIST Dad`	`EXIST`	已存在的键能被识别
6	`DEL Dad`	`OK`	已存在的键可以删除
7	`GET Dad`	`NO EXIST`	删除后无法再读取
8	`MOD Dad Jasper`	`NO EXIST`	删除后无法再修改
9	`EXIST Dad`	`NO EXIST`	删除后状态确实不存在

这九步不是彼此独立的命令，而是一条状态变化链：

不存在
 │ SET
 ▼
Dad = Jasper
 │ MOD
 ▼
Dad = Sao
 │ DEL
 ▼
不存在

测试在每个关键状态后使用 GET 或 EXIST 进行确认。这样不仅验证命令返回了什么，还验证前一条命令是否真正改变了存储状态。

4.1 测试覆盖的两个方向

当前场景同时覆盖：

正向结果：写入成功、读取成功、修改成功、存在、删除成功；
反向结果：删除后读取、修改和判断存在均返回 NO EXIST。

“尽量覆盖项目所有结果，目标达到 90% 以上”可以理解为：不仅让每个函数运行一次，还要让函数中的主要结果分支都被执行到。对于协议层而言，要关注的结果包括：

OK
EXIST
NO EXIST
ERROR
具体 value

测试用例会贯穿后续项目：新增命令、新增引擎或调整内部结构以后，都可以重复运行同一套预期，确认原有行为仍然成立。这就是回归测试的作用。

5. 从功能测试扩展到压力测试

功能测试回答的是：

一组操作的结果是否正确？

压力测试进一步回答：

同一组操作重复很多次以后，结果是否仍然正确？大约能处理多少请求？

array_testcase_10w() 将九条命令循环执行：

int count = 10000;

for (i = 0; i < count; i++) {
 /* 每轮执行 9 条请求 */
}

所以请求总数为：

10000 轮 × 9 条/轮 = 90000 条请求

计时使用 gettimeofday()：

tv_begin：循环开始时间
tv_end：循环结束时间
time_used：两者相差的毫秒数

宏 TIME_SUB_MS 把秒和微秒的差值统一换算为毫秒：

#define TIME_SUB_MS(tv1, tv2) \
 ((tv1.tv_sec - tv2.tv_sec) * 1000 + \
 (tv1.tv_usec - tv2.tv_usec) / 1000)

QPS 的基本计算关系是：

QPS = 请求总数 ÷ 耗时秒数
 = 请求总数 × 1000 ÷ 耗时毫秒数

这里的“请求总数”应按实际循环次数和每轮命令数计算。数组测试中是 90000；红黑树测试同样是 10000 × 9 = 90000。阅读输出时先统一这个口径，两个引擎的数据才可以放在一起比较。

5.1 三次粗测说明了什么

笔记记录了 9000 次请求附近的三次结果：

测试环境	耗时	粗测 QPS
客户端输出每次 PASS，服务端也打印	477 ms	18867
屏蔽客户端 PASS 输出	415 ms	21686
继续去掉服务端打印	285 ms	31578

三组数据的重点不是得到一个绝对性能结论，而是观察到：

测试总耗时
 = 网络收发耗时
 + 协议处理耗时
 + 引擎操作耗时
 + 客户端打印耗时
 + 服务端打印耗时

当 printf() 位于高频路径中，它也属于被计时的工作。逐步屏蔽打印后，QPS 上升，说明这次粗测测到的是整个端到端过程，而不只是 KV 引擎本身。

5.2 当前 QPS 的准确含义

当前压力客户端只有一个进程、一条 TCP 连接，并且每次都按下面的顺序执行：

send 一条请求
 ↓
等待 recv 一条响应
 ↓
比较结果
 ↓
发送下一条请求

因此当前结果更准确地说是：

单客户端、单连接、串行请求、包含协议校验的端到端吞吐量。

它适合观察同一环境下的相对变化，例如开关日志前后的差异，以及数组与红黑树在相同测试场景下的差异。

6. 为什么小次数正常，高次数却失败

压力测试增加到 90000 次请求后，出现了：

FAILED-> SET-Dad,ERROR!=OK

从客户端场景看，每轮都执行：

SET Dad Jasper
...
DEL Dad

一轮结束时，Dad 已经删除，所以下一轮的 SET Dad Jasper 应该仍然能够成功。实际数据量始终只在 0 和 1 之间变化：

SET 后：1 个元素
DEL 后：0 个元素
SET 后：1 个元素
DEL 后：0 个元素

但是数组实例使用 total 记录有效元素数量。如果插入成功执行 total++，删除成功却没有对应地维护数量，就会形成两套不同的状态：

实际元素数量：0 → 1 → 0 → 1 → 0 ...
total： 0 → 1 → 1 → 2 → 2 ...

循环次数少时，total 还没有触及 KVS_ARRAY_SIZE，现象不明显；循环次数持续增加后，最终会到达容量判断：

if (inst->total >= KVS_ARRAY_SIZE)

于是后续 SET 返回错误。与此同时，查找范围由 total 决定，total 不断增大也会使遍历范围越来越长，所以压力测试还能观察到性能逐渐变化。

6.1 `total` 的核心约定

数组引擎需要维持一个清楚的不变量：

table[0] 到 table[total - 1]：有效元素
table[total] 以及后面的位置：空闲空间
total：当前有效元素数量

按照这个约定：

插入成功 → total++
删除成功 → total--

如果删除数组中间的元素，可以用最后一个有效元素补到删除位置，从而继续保持有效区间连续：

删除前：[Dad, Mom, Son] total = 3
删除 Mom 后出现空位：[Dad, 空, Son]
把最后一个元素移到空位：[Dad, Son, 空]
最终：total = 2

这个问题说明，容量字段不是只在创建时赋值、插入时递增的计数器，而是数据结构状态的一部分。每一种改变元素数量的操作都必须共同维护它。

7. 压力测试进一步暴露的几个语义问题

高次数运行不仅检查容量，还会不断经过删除、查询不存在和修改不存在等分支，因此能把返回值、内存和状态维护问题一起暴露出来。

7.1 删除 value 时的内存顺序

下面这个表达式先执行赋值：

kvs_free(inst->table[i].value = NULL);

它的实际求值顺序是：

inst->table[i].value = NULL
 ↓
kvs_free(NULL)

原来保存在 value 中的地址因此没有被交给 kvs_free()。正确理解“释放后置空”的顺序是：

先把原地址交给 kvs_free
 ↓
再把保存该地址的指针设为 NULL

也就是：

kvs_free(inst->table[i].key);
inst->table[i].key = NULL;

kvs_free(inst->table[i].value);
inst->table[i].value = NULL;

这里要记住的不是某一行写法，而是指针生命周期：地址仍然可达时释放内存，释放完成后再清除悬空指针。

7.2 循环下标与业务状态不是同一种含义

如果同时存在：

int i = 0;

for (int i = 0; i < inst->total; i++) {
 ...
}

for 中的 i 属于内层作用域，会遮蔽外层的 i。循环结束后，外层 i 仍是初始值 0。

更关键的是，即使只保留一个 i，return i 仍然混合了两种概念：

i：遍历到了哪个数组下标
返回值：本次 KV 操作是什么结果

数组为空时尤其容易看清这个区别：

i = 0
total = 0
循环一次都不执行
return i 得到 0

这里的 0 只是下标初始值，并不能说明修改或删除成功。

因此，学习时应把业务状态单独记忆：

返回值	协议层理解
`< 0`	参数或执行错误，生成 `ERROR`
`0`	操作成功，或 `EXIST` 查询确认存在
`> 0`	SET 时表示已存在；DEL/MOD/EXIST 时表示不存在

7.3 两种失败现象来自同一套返回值约定

删除成功后如果返回 1，协议层会按照既定规则生成：

DEL 返回 1 → NO EXIST

于是客户端看到：

FAILED-> DEL-Dad,NO EXIST!=OK

删除以后再执行 MOD，如果数组为空、循环未执行，最后又通过 return i 返回初始值 0，协议层会生成：

MOD 返回 0 → OK

于是客户端看到：

FAILED-> MOD-Dad,OK!=NO EXIST

这两种现象虽然出现在不同命令中，核心都是同一件事：引擎函数的返回值属于内部业务协议，协议层会严格按照该约定翻译成文本响应。

可以把这条关系记成：

引擎内部状态
 ↓
固定返回值
 ↓
kvs_filter_protocol()
 ↓
客户端可见响应
 ↓
testcase() 与预期比较

测试失败信息最终帮助定位到的，不一定是 TCP 层，也可能是更深处的状态维护或返回值语义。

8. 从单一数组引擎扩展为多引擎

前一阶段的协议层只连接数组：

SET / GET / DEL / MOD / EXIST
 ↓
 global_array

本阶段保留已经成型的数组实现，并通过宏加入红黑树：

#define ENABLE_ARRAY 1
#define ENABLE_RBTREE 1

这两个开关控制相关类型、接口、全局实例、协议分支、初始化和销毁代码是否参与编译。这样可以在接入期间让两种引擎同时存在，并分别运行测试。

项目结构由此变成：

 kvs_protocol
 ↓
 kvs_filter_protocol
 ↓
 根据命令选择对应的引擎
 ↙ ↘
 SET/GET/DEL/MOD/EXIST RSET/RGET/RDEL/RMOD/REXIST
 ↓ ↓
 global_array global_rbtree

这里没有改变底层网络。无论使用 Reactor、Proactor 还是 ntyco，网络层仍然只调用同一个 kvs_protocol()。增加的是协议层后面的存储选择。

9. 为什么给红黑树命令增加 `R` 前缀

一条普通的 SET Dad Jasper 只表达了“设置键值”，没有说明数据应该存进数组还是红黑树。

当前阶段采用最直接的区分方法：在协议命令中加入引擎标识。

数组命令	红黑树命令	语义
`SET`	`RSET`	新增 key-value
`GET`	`RGET`	查询 value
`DEL`	`RDEL`	删除 key-value
`MOD`	`RMOD`	修改 value
`EXIST`	`REXIST`	判断 key 是否存在

命令字符串表因此扩展为十项：

const char *command[] = {
 "SET", "GET", "DEL", "MOD", "EXIST",
 "RSET", "RGET", "RDEL", "RMOD", "REXIST"
};

枚举与字符串表保持相同顺序，kvs_filter_protocol() 找到命令编号后，通过 switch 进入对应分支：

RSET
 ↓
KVS_CMD_RSET
 ↓
kvs_rbtree_set(&global_rbtree, key, value)
 ↓
按照返回值生成 OK / EXIST / ERROR

因此，R 前缀在当前阶段承担的是一个简单的路由信息：让协议层知道应该调用哪种引擎。

10. 每种数据结构都遵守“5 + 2”接口

数组引擎已经形成七个接口：

create
destory
set
get
del
mod
exist

可以压缩为：

2 个生命周期操作 + 5 个 KV 操作 = 5 + 2

红黑树接入时也提供相同形态：

int kvs_rbtree_create(kvs_rbtree_t *inst);
void kvs_rbtree_destory(kvs_rbtree_t *inst);
int kvs_rbtree_set(kvs_rbtree_t *inst, char *key, char *value);
char *kvs_rbtree_get(kvs_rbtree_t *inst, char *key);
int kvs_rbtree_del(kvs_rbtree_t *inst, char *key);
int kvs_rbtree_mod(kvs_rbtree_t *inst, char *key, char *value);
int kvs_rbtree_exist(kvs_rbtree_t *inst, char *key);

协议层因此不需要理解旋转、着色、后继节点等红黑树内部细节。它只关心：

用哪个实例
调用哪个 KV 操作
如何解释返回值

这正是本次“加入红黑树”最值得回顾的部分：不是从零推导红黑树算法，而是把已有数据结构包装成项目已经形成的 KV 引擎接口。

同样的思路也可以用于后续哈希引擎：哈希表内部怎样定位 key 属于数据结构实现；接入项目时，仍围绕生命周期和五种 KV 语义组织接口。

11. 红黑树在项目中的最小理解范围

为了理解本项目中的接入，只需要掌握下面几层关系。

11.1 树实例和节点

红黑树实例保存：

typedef struct _rbtree {
 rbtree_node *root;
 rbtree_node *nil;
} rbtree;

其中：

root 指向根节点；
nil 是哨兵节点，用于表示空孩子和空树边界；
nil 初始化为黑色；
创建完成时，root 指向 nil，表示树中还没有 KV 节点。

节点中与 KV 项目直接相关的是：

key → 用于比较和查找
value → 与 key 对应的数据

父节点、左右孩子和颜色则服务于红黑树结构本身。

11.2 五种 KV 操作如何映射到底层树操作

KV 接口	在红黑树中的主要过程
`kvs_rbtree_set()`	为 key/value 分配空间，构造节点并插入树
`kvs_rbtree_get()`	按 key 搜索节点，返回节点的 value
`kvs_rbtree_del()`	搜索节点，删除节点并释放相关空间
`kvs_rbtree_mod()`	搜索节点，替换已有 value
`kvs_rbtree_exist()`	搜索节点，通过是否到达 `nil` 判断存在性

这些包装函数把“树节点操作”转换成与数组引擎一致的“KV 操作”。

11.3 生命周期怎样进入程序主流程

程序启动时，两种引擎分别初始化：

init_kvengine()
 ├─ kvs_array_create(&global_array)
 └─ kvs_rbtree_create(&global_rbtree)

网络服务结束后，再进入统一销毁阶段：

dest_kvengine()
 ├─ kvs_array_destory(&global_array)
 └─ kvs_rbtree_destory(&global_rbtree)

红黑树销毁时需要逐步删除树中的节点，最后处理树实例的哨兵节点。具体采用最小节点、最大节点或其他顺序，是树内部的销毁策略；对项目主线而言，重要的是 destory 与 create 共同构成完整生命周期。

12. 用同一套语义验证红黑树引擎

rbtree_testcase() 与 array_testcase() 的业务顺序保持一致，只是命令增加了 R 前缀：

数组： SET → GET → MOD → GET → EXIST → DEL → GET → MOD → EXIST
红黑树：RSET → RGET → RMOD → RGET → REXIST → RDEL → RGET → RMOD → REXIST

这使测试具有两个层次：

单独验证每个引擎是否满足五种 KV 操作；
验证两种引擎在相同业务场景下是否表现出相同语义。

可以把两组用例看成一份“行为契约”：

初始状态和操作	数组响应	红黑树响应
不存在时 SET	`OK`	`OK`
SET 后 GET	对应 value	对应 value
已存在时 MOD	`OK`	`OK`
已存在时 EXIST	`EXIST`	`EXIST`
已存在时 DEL	`OK`	`OK`
DEL 后 GET/MOD/EXIST	`NO EXIST`	`NO EXIST`

只要对外行为一致，客户端就不需要了解底层究竟使用数组还是红黑树。当前协议用命令前缀显式选择引擎，但测试验证的是二者共同的 KV 语义。

13. 数组与红黑树在当前项目中的角色

本阶段不是简单地用红黑树替换数组，而是让两种实现同时存在：

维度	数组引擎	红黑树引擎
协议命令	五种普通命令	五种 `R` 前缀命令
全局实例	`global_array`	`global_rbtree`
生命周期	`create/destory`	`create/destory`
KV 接口	`set/get/del/mod/exist`	`set/get/del/mod/exist`
内部组织	连续数组区间	根节点、哨兵和树节点
查找方式	在有效区间中遍历	按 key 在树中搜索

真正稳定下来的不是某一种数据结构，而是数据结构外面的项目边界：

协议命令
 ↓
统一的 KV 语义
 ↓
不同引擎各自实现

这也解释了“要什么需求、用什么技术方案实现”的关系：

需求是保存、查询、删除、修改和判断 key；
数组和红黑树是两种实现这些需求的技术方案；
协议层负责把客户端命令路由给具体方案；
测试用例负责确认不同方案满足相同的外部预期。

14. 关于多进程、多线程压力测试的课后思考

当前单连接测试中，每条请求都要等待上一条响应，无法同时给服务端制造多个在途请求。要观察并发场景，可以让多个执行单元各自建立连接并运行同一组测试。

14.1 多进程思路

父进程
 ├─ fork → 子进程 1 → 建立连接 → 重复测试
 ├─ fork → 子进程 2 → 建立连接 → 重复测试
 └─ fork → 子进程 N → 建立连接 → 重复测试

每个子进程拥有自己的客户端 socket 和测试循环。父进程等待所有子进程结束，再汇总：

总请求数 = 进程数 × 每个进程的请求数
整体 QPS = 总请求数 × 1000 ÷ 整体耗时毫秒数

14.2 多线程思路

一个客户端进程
 ├─ 线程 1 → 独立连接 → 重复测试
 ├─ 线程 2 → 独立连接 → 重复测试
 └─ 线程 N → 独立连接 → 重复测试

每个线程使用独立连接时，测试流程和当前代码最接近；主线程统一记录开始与结束时间，并统计所有线程完成的请求总数。

14.3 并发数增加后观察什么

并发测试不只是期待 QPS 一定上升，还要同时观察：

所有响应是否仍然符合预期；
总吞吐量怎样随客户端数量变化；
单次请求延迟是否增加；
服务端采用的网络模型是否能发挥并发处理能力；
打印、网络、协议或存储引擎中的哪一部分先成为主要耗时。

因此，多进程或多线程的意义是改变负载模型：从“一个客户端串行发请求”变成“多个客户端同时发请求”。

15. 这一阶段形成的完整项目画面

把前三个阶段放在一起，可以得到当前项目结构：

测试客户端
 ├─ 功能用例：检查每一步响应
 └─ 压力用例：重复场景、计时、计算 QPS
 │
 ▼
 TCP 网络
 │
 ▼
网络层：Reactor / Proactor / ntyco
 │
 ▼
kvs_protocol()：切分 token
 │
 ▼
kvs_filter_protocol()：识别命令并选择引擎
 ┌────┴────┐
 ▼ ▼
 数组引擎 红黑树引擎
 5 + 2 接口 5 + 2 接口
 │ │
 └────┬────┘
 ▼
 统一返回值与文本响应

Makefile 则从构建角度把这些模块放到一起：

kvstore.c
reactor.c / proactor.c / ntyco.c
kvs_array.c
kvs_rbtree.c
NtyCo 与 liburing
 ↓
 kvstore

16. 最后的复习提纲

16.1 测试主线

connect
 → send command
 → recv response
 → compare pattern
 → PASS / FAILED

16.2 压力测试主线

固定业务场景
 → 重复执行
 → 统计实际请求数
 → 记录总耗时
 → 计算 QPS
 → 从失败轮次和响应反查内部状态

16.3 数组问题定位主线

少量测试正常、增加次数后 SET 返回 ERROR
 → 检查容量条件
 → 检查 total 的增减
 → 发现实际元素已删除但 total 仍增长
 → 恢复“有效元素数量”的统一约定

同时记住：

释放内存：先 free 原地址，再把指针置 NULL
循环下标：只表示位置
函数返回值：表示业务结果
协议响应：由业务返回值翻译得到

16.4 多引擎扩展主线

保留数组成型代码
 → 用 ENABLE_ARRAY / ENABLE_RBTREE 控制编译
 → 为红黑树提供同样的 5 + 2 接口
 → 增加 RSET/RGET/RDEL/RMOD/REXIST
 → 协议层按命令选择实例
 → 用同一套业务场景验证两种引擎

16.5 本阶段最重要的认识

测试用例不是项目完成后的附属代码，而是项目继续迭代时用来确认行为的固定标准。

小次数测试验证基本功能，高次数测试还会验证状态能否长期保持一致。

total、节点数量和指针生命周期都属于数据结构必须维护的内部状态。

数组、红黑树以及后续哈希表可以采用不同内部实现，但都可以通过相同的 KV 语义接入协议层。

本阶段加入红黑树的重点，是把一种已有数据结构组织成项目需要的存储引擎，而不是从零实现红黑树算法。

KV 存储项目：协议层与数组存储

Mon, 24 Aug 2026 00:00:00 +0800

阅读目标：沿着“收到一条命令—解析命令—操作数组—生成响应”这条主线，回顾 KV 项目从 echo 协议发展到实际命令处理的过程。

本文承接 KV 存储项目网络层：统一接入 Reactor、Proactor 与协程。上一篇已经讲过 Reactor、Proactor、ntyco、msg_handler 和网络收发流程，本文不再重复网络层实现，只说明它怎样把请求交给协议层。

本文以笔记和现有代码为准，解释代码在项目中的作用与执行过程，不讨论修改方案。

1. 从网络层进入协议层

上一篇已经完成了网络层。无论底层选择 Reactor、Proactor 还是 ntyco，收到请求后都会调用同一个入口：

kvs_protocol(msg, length, response);

这一篇从这里继续：

网络层收到客户端数据
 ↓
kvs_protocol() 进入协议层
 ↓
kvs_split_token() 切分命令
 ↓
kvs_filter_protocol() 识别命令
 ↓
kvs_array_xxx() 操作 KV 数据
 ↓
把执行结果写入 response
 ↓
网络层发送响应

网络层解决“数据怎样到达”，协议层解决“收到的数据表示什么、应该返回什么”。

2. 为什么 TCP 之上还需要业务协议

假设浏览器请求一个包含数据的网页，业务链路可以是：

浏览器 → NodeServer → KV 存储服务器

NodeServer 与 KV 存储服务器建立 TCP 连接后，还要约定双方发送数据的格式。例如：

SEND: SET Key Value\r\n
RECV: OK\r\n

SEND: GET Key\r\n
RECV: King\r\n

TCP 是公共的传输协议，只负责按顺序传输字节；SET 和 GET 的含义属于项目自己定义的应用层协议，也可以称为业务协议或私有协议。

本项目采用容易观察的文本命令：

SET Key Value
GET Key
DEL Key
MOD Key Value
EXIST Key

其中空格用于分隔命令和参数，响应通过 response 缓冲区交还给网络层。

3. TCP 消息边界：理解协议的前提

TCP 是字节流，一次 send() 不一定对应一次 recv()。

客户端连续发送：

SET Key Value\r\n
SET Key1 Value1\r\n
SET Key2 Value2\r\n

接收方可能一次 recv() 收到多条命令，也可能只收到一条命令的一部分。因此应用层需要自己识别完整消息的边界。

笔记中记录了两种约定边界的思路。

3.1 在包头记录长度

在数据最前面使用固定字节表示后续消息长度：

short length = 0;

recv(fd, &length, 2, 0);
recv(fd, buffer, length, 0);

概念流程是：

先读取固定长度的包头
 ↓
得到消息体长度 length
 ↓
继续读取 length 个字节
 ↓
取得一条完整消息

3.2 使用结束标记

文本协议也可以约定用 \r\n 表示一行结束，再逐行解析命令。

无论采用长度字段还是结束标记，目的都是让接收方能够从连续的 TCP 字节流中还原出一条条完整命令。

ET、LT 对应不同的事件触发方式；它们都能处理多个数据包，具体读取过程属于上一篇网络层的延伸问题。本文继续关注完整命令到达 kvs_protocol() 之后的处理。

4. Redis 协议带来的解析思路

SET Key Value 可以拆成三个 token：

SET
Key
Value

笔记中的 Redis 协议简化示意不仅传输 token 内容，还记录 token 数量和每个 token 的长度：

3\r\n
3\r\n
SET\r\n
3\r\n
Key\r\n
5\r\n
Value\r\n

可以依次理解为：

共有 3 个 token
SET 的长度是 3
Key 的长度是 3
Value 的长度是 5

GET Teacher 则有两个 token：

2\r\n
3\r\n
GET\r\n
7\r\n
Teacher\r\n

对应的读取伪代码是：

readline(fd, buffer);
count = atoi(buffer);

for (int i = 0; i < count; i++) {
 readline(fd, tokenlen);
 readline(fd, token);
}

解析主线是：

读取 token 数量
 ↓
循环读取每个 token 的长度
 ↓
按照长度读取 token 内容
 ↓
组合成一条完整命令

当前项目代码采用更直接的形式：收到 SET Key Value 后，以空格调用 strtok() 进行切分。

5. 文件职责

本次代码可以按职责分为三部分：

kvstore.h
 ├─ 公共宏与函数声明
 ├─ 数组 KV 数据结构
 └─ CRUD 接口

kvstore.c：协议部分
 ├─ 内存接口封装
 ├─ token 切分
 ├─ 命令识别与响应生成
 ├─ KV 引擎初始化
 └─ main

数组存储部分
 ├─ global_array
 ├─ create / destory
 └─ set / get / del / mod / exist

上一篇的 kvs_protocol() 只是把请求复制到响应中；本次代码让它开始解析并执行真实的 KV 命令。

6. `kvstore.h`：数组引擎的数据结构与接口

6.1 编译配置

#define KVS_MAX_TOKENS 128
#define ENABLE_ARRAY 1
#define KVS_ARRAY_SIZE 1024

宏	代码中的含义
`KVS_MAX_TOKENS`	`tokens` 数组容量
`ENABLE_ARRAY`	是否编译数组 KV 引擎
`KVS_ARRAY_SIZE`	KV 数组的容量

6.2 一个 KV 元素

typedef struct kvs_array_item_s {
 char *key;
 char *value;
} kvs_array_item_t;

数组中的每一个元素保存一对指针：

table[i]
 ├─ key → 键字符串
 └─ value → 值字符串

6.3 整个数组实例

typedef struct kvs_array_s {
 kvs_array_item_t *table;
 int idx;
 int total;
} kvs_array_t;

字段	含义
`table`	指向 KV 元素数组
`idx`	数组实例中的索引字段
`total`	当前记录的元素数量

数组引擎向协议层提供以下操作：

int kvs_array_create(kvs_array_t *inst);
void kvs_array_destory(kvs_array_t *inst);
int kvs_array_set(kvs_array_t *inst, char *key, char *value);
char *kvs_array_get(kvs_array_t *inst, char *key);
int kvs_array_del(kvs_array_t *inst, char *key);
int kvs_array_mod(kvs_array_t *inst, char *key, char *value);
int kvs_array_exist(kvs_array_t *inst, char *key);

7. 封装内存分配接口

代码没有让各个数据操作直接依赖 malloc() 和 free()，而是包了一层：

void *kvs_malloc(size_t size) {
 return malloc(size);
}

void kvs_free(void *ptr) {
 free(ptr);
}

其他模块统一使用：

kvs_malloc(size);
kvs_free(ptr);

笔记中的目的，是给内存管理保留统一入口。后续如果跨平台、引入内存池或定制内存分配，只需要从这一层接入，不必改变所有调用位置。

这体现了项目迭代中的一个思路：先通过统一接口隔开业务代码与底层实现。

8. 创建数组实例：`kvs_array_create()`

全局数组实例定义为：

kvs_array_t global_array = {0};

创建函数：

int kvs_array_create(kvs_array_t *inst) {
 if (inst == NULL) return -1;

 if (inst->table) {
 printf("table has been alloced");
 return -1;
 }

 inst->table = kvs_malloc(
 KVS_ARRAY_SIZE * sizeof(kvs_array_item_t)
 );

 if (!inst->table) return -1;

 inst->total = 0;
 return 0;
}

执行过程：

检查 inst
 ↓
检查 table 是否已经指向数组
 ↓
申请 KVS_ARRAY_SIZE 个元素的空间
 ↓
total 设为 0

程序启动时，init_kvengine() 负责初始化它：

int init_kvengine(void) {
#if ENABLE_ARRAY
 memset(&global_array, 0, sizeof(kvs_array_t));
 kvs_array_create(&global_array);
#endif
 return 0;
}

9. `SET`：保存一组 key-value

接口：

int kvs_array_set(kvs_array_t *inst,
 char *key,
 char *value);

主要执行顺序：

检查 inst、key、value
 ↓
检查 total 是否达到数组容量
 ↓
调用 kvs_array_get() 查找 key
 ↓
key 已存在时返回 1
 ↓
分别为 key 和 value 分配内存
 ↓
复制 key 和 value
 ↓
寻找存放位置并写入 table
 ↓
total 加 1，返回 0

代码为字符串申请 strlen(...) + 1 字节：

char *kcopy = kvs_malloc(strlen(key) + 1);
char *kvalue = kvs_malloc(strlen(value) + 1);

多出的一个字节用于字符串结尾的 \0。

返回值在当前协议中的含义：

ret < 0 → 执行错误
ret == 0 → 设置成功
ret > 0 → key 已存在

10. `GET`：按照 key 查找 value

接口：

char *kvs_array_get(kvs_array_t *inst, char *key);

查询过程：

检查 inst 和 key
 ↓
从 table[0] 开始遍历
 ↓
跳过 key 为空的元素
 ↓
strcmp() 比较元素 key 和目标 key
 ↓
找到后返回 value
 ↓
遍历结束仍未找到则返回 NULL

核心比较：

if (strcmp(inst->table[i].key, key) == 0) {
 return inst->table[i].value;
}

因此 kvs_array_get() 的结果可以直接被 SET、GET 和 EXIST 复用。

11. `DEL`：删除 key-value

接口：

int kvs_array_del(kvs_array_t *inst, char *key);

执行主线：

检查 inst 和 key
 ↓
遍历 table
 ↓
strcmp() 找到相同 key
 ↓
释放 key 对应的内存
 ↓
释放 value 对应的内存
 ↓
返回执行结果

协议层按照约定把返回值转换为：

ERROR / OK / NO EXIST

12. `MOD`：修改已有 key 的 value

接口：

int kvs_array_mod(kvs_array_t *inst,
 char *key,
 char *value);

执行主线：

检查 inst、key、value
 ↓
遍历 table 查找 key
 ↓
释放原来的 value
 ↓
按照新字符串长度申请内存
 ↓
复制新的 value
 ↓
把新 value 写回当前元素

MOD 保留原来的 key，只更新与它关联的 value。

13. `EXIST`：复用 GET 判断 key 是否存在

int kvs_array_exist(kvs_array_t *inst, char *key) {
 char *str = kvs_array_get(inst, key);

 if (!str) {
 return 1;
 }
 return 0;
}

返回值含义：

0 → key 存在
1 → key 不存在

这里没有再次编写数组遍历，而是调用 kvs_array_get() 完成查找。

14. 命令字符串与枚举的对应关系

命令字符串表：

const char *command[] = {
 "SET", "GET", "DEL", "MOD", "EXIST"
};

枚举：

enum {
 KVS_CMD_START = 0,
 KVS_CMD_SET = KVS_CMD_START,
 KVS_CMD_GET,
 KVS_CMD_DEL,
 KVS_CMD_MOD,
 KVS_CMD_EXIST,
 KVS_CMD_COUNT,
};

二者按下标形成对应关系：

`cmd`	`command[cmd]`	枚举
0	`SET`	`KVS_CMD_SET`
1	`GET`	`KVS_CMD_GET`
2	`DEL`	`KVS_CMD_DEL`
3	`MOD`	`KVS_CMD_MOD`
4	`EXIST`	`KVS_CMD_EXIST`

协议解析通过同一个 cmd 同时连接字符串表与 switch 分支，所以代码注释强调二者顺序保持对应。

15. `kvs_split_token()`：把命令切成参数

函数入口：

int kvs_split_token(char *msg, char *tokens[])

首先检查参数：

if (msg == NULL || tokens == NULL) return -1;

然后以空格为分隔符调用 strtok()：

int idx = 0;
char *token = strtok(msg, " ");

while (token != NULL) {
 tokens[idx++] = token;
 token = strtok(NULL, " ");
}

return idx;

对于：

SET Key Value

切分结果是：

tokens[0] → "SET"
tokens[1] → "Key"
tokens[2] → "Value"
返回 count = 3

对于：

GET Key

切分结果是：

tokens[0] → "GET"
tokens[1] → "Key"
返回 count = 2

笔记中强调：函数进入时先进行参数判断。完整项目还会逐步形成统一的参数错误、内存错误和协议错误等返回值约定。

16. `kvs_filter_protocol()`：识别命令并生成响应

函数入口：

int kvs_filter_protocol(char **tokens,
 int count,
 char *response);

16.1 查找命令编号

int cmd = KVS_CMD_START;

for (cmd = KVS_CMD_START;
 cmd < KVS_CMD_COUNT;
 cmd++) {
 if (strcmp(tokens[0], command[cmd]) == 0) {
 break;
 }
}

例如 tokens[0] 是 GET，循环最终得到：

cmd = KVS_CMD_GET

随后统一取出参数位置：

char *key = tokens[1];
char *value = tokens[2];

16.2 SET 分支

ret = kvs_array_set(&global_array, key, value);

数组层结果	协议响应
`ret < 0`	`ERROR\r\n`
`ret == 0`	`OK\r\n`
`ret > 0`	`EXIST\r\n`

16.3 GET 分支

char *result = kvs_array_get(&global_array, key);

查询结果	协议响应
`result == NULL`	`NO EXIST\r\n`
找到 value	`value\r\n`

16.4 DEL 分支

ret = kvs_array_del(&global_array, key);

数组层结果	协议响应
`ret < 0`	`ERROR\r\n`
`ret == 0`	`OK\r\n`
`ret > 0`	`NO EXIST\r\n`

16.5 MOD 分支

ret = kvs_array_mod(&global_array, key, value);

数组层结果	协议响应
`ret < 0`	`ERROR\r\n`
`ret == 0`	`OK\r\n`
`ret > 0`	`NO EXIST\r\n`

16.6 EXIST 分支

ret = kvs_array_exist(&global_array, key);

数组层结果	协议响应
`ret == 0`	`EXIST`
`ret != 0`	`NO EXIST\r\n`

kvs_filter_protocol() 的角色可以概括为：把文本命令转换成数组函数调用，再把数组函数的返回值转换成文本响应。

17. `kvs_protocol()`：本篇代码的总入口

int kvs_protocol(char *msg,
 int length,
 char *response) {
 if (msg == NULL || length <= 0 || response == NULL)
 return -1;

 printf("recv: %d: %s\n", length, msg);

 char *tokens[KVS_MAX_TOKENS] = {0};

 int count = kvs_split_token(msg, tokens);
 if (count == -1) return -1;

 return kvs_filter_protocol(tokens, count, response);
}

三个参数分别来自网络层：

参数	含义
`msg`	收到的请求内容
`length`	请求长度
`response`	协议层写入响应的缓冲区

执行主线：

检查参数
 ↓
创建 tokens 数组
 ↓
kvs_split_token(msg, tokens)
 ↓
得到 token 数量 count
 ↓
kvs_filter_protocol(tokens, count, response)
 ↓
执行命令并形成响应

它把上一篇的“网络回调入口”与本篇的“命令解析和数组 CRUD”连接起来。

18. 程序启动与数组引擎接入

main() 先取得端口，再初始化 KV 引擎：

int port = atoi(argv[1]);
init_kvengine();

之后按照 NETWORK_SELECT 启动对应网络层，并继续把 kvs_protocol 作为回调传入：

reactor_start(port, kvs_protocol);
/* 或 */
ntyco_start(port, kvs_protocol);
/* 或 */
proactor_start(port, kvs_protocol);

这里不再展开三种网络模型。只需记住：网络模型可以切换，协议入口和数组引擎的调用主线保持不变。

19. 一条 `SET` 命令的完整路径

客户端发送：

SET name King

代码中的执行过程：

网络层取得 msg
 ↓
kvs_protocol(msg, length, response)
 ↓
kvs_split_token()
 ↓
tokens[0] = "SET"
tokens[1] = "name"
tokens[2] = "King"
 ↓
kvs_filter_protocol()
 ↓
匹配 KVS_CMD_SET
 ↓
kvs_array_set(&global_array, "name", "King")
 ↓
为 key 和 value 分配内存并写入 table
 ↓
response = "OK\r\n"
 ↓
网络层发送响应

20. 一条 `GET` 命令的完整路径

客户端发送：

GET name

执行过程：

kvs_protocol()
 ↓
切分出 "GET" 和 "name"
 ↓
kvs_filter_protocol()
 ↓
匹配 KVS_CMD_GET
 ↓
kvs_array_get(&global_array, "name")
 ↓
遍历 table 并比较 key
 ↓
找到 value = "King"
 ↓
response = "King\r\n"

如果没有找到，则响应：

NO EXIST\r\n

21. 返回值与协议响应是两个层次

数组函数首先返回内部执行结果，例如：

小于 0：错误
等于 0：成功或存在
大于 0：已存在或不存在

协议层再将其转换成客户端能够理解的文本：

OK
ERROR
EXIST
NO EXIST
具体的 value

这与 HTTP 使用 200、404 等状态表达处理结果的思路相似：一个完整项目会逐步形成统一的参数错误、内存分配失败、协议解析失败等返回值标准。

22. 从功能实现到项目架构

笔记给出的迭代顺序是：

先保证功能
 ↓
保证协议统一
 ↓
保证参数统一
 ↓
保证返回值统一

数组法先直接实现了 KV 的基本操作：

SET → 增加 key-value
GET → 查询 value
DEL → 删除 key-value
MOD → 修改 value
EXIST → 判断 key 是否存在

随着代码不断迭代，公共接口、模块边界和返回值规则逐渐稳定，进而形成项目架构。

可以记住两句话：

架构是在软件不断迭代的过程中逐渐产生的。

软件代码可以通过分层设计，将网络收发、协议处理和数据存储分开。

23. 最后的整体记忆

这一阶段最重要的不是分别记住所有函数，而是记住数据在各层之间怎样移动：

客户端文本命令
 ↓
网络层交给 kvs_protocol
 ↓
kvs_split_token 拆出 command / key / value
 ↓
kvs_filter_protocol 匹配命令
 ↓
kvs_array_set/get/del/mod/exist
 ↓
global_array 中的 key-value 数据
 ↓
协议层生成 OK、ERROR、value 等响应
 ↓
网络层发送给客户端

按函数压缩为：

kvs_protocol
 → kvs_split_token
 → kvs_filter_protocol
 → kvs_array_xxx
 → response

KV 存储项目网络层：统一接入 Reactor、Proactor 与协程

Sat, 22 Aug 2026 00:00:00 +0800

阅读目标：先恢复项目的整体认识，再通过带注释的代码块回忆具体实现。

本文只解析现有成品代码，不讨论修改方案。ntyco 只讲如何作为 KV 项目的网络层使用。

1. 先恢复项目的整体画面

这个项目的核心不是分别写了三个独立服务器，而是让三个网络服务器共同使用同一个 KV 协议入口：

 kvstore.c
 main + kvs_protocol
 │
 msg_handler 回调
 │
 ┌──────────────┼──────────────┐
 │ │ │
 reactor.c ntyco.c proactor.c
 epoll 协程 io_uring
 │ │ │
 └──────────────┼──────────────┘
 │
 TCP

三种网络层只负责连接和收发，kvs_protocol() 负责处理消息：

客户端请求
 ↓
网络层收到 msg 和 length
 ↓
kvs_protocol(msg, length, response)
 ↓
返回 response 的长度
 ↓
网络层发送 response

项目目前的 kvs_protocol() 是 echo 协议：把请求复制成响应。这一实现展示的重点，是三种网络模型如何接入同一个 KV 协议回调。

六份文件分成三组：

公共入口与接口
 ├─ kvstore.c
 └─ kvstore.h

Reactor 公共连接定义
 └─ server.h

三种网络层
 ├─ reactor.c
 ├─ proactor.c
 └─ ntyco.c

2. 公共入口：`kvstore.h` 与 `kvstore.c`

2.1 `kvstore.h`：把三种网络层统一成一种调用方式

#ifndef KV_STORE_H
#define KV_STORE_H

/* 三种网络实现的编号，供 NETWORK_SELECT 选择 */
#define NETWORK_REACTOR 0
#define NETWORK_PROACTOR 1
#define NET_WORK_NTYCO 2

/* 当前编译使用 io_uring Proactor 网络层 */
#define NETWORK_SELECT NETWORK_PROACTOR

/*
 * KV 协议回调类型：
 * msg 网络层收到的请求
 * length 请求的实际长度
 * response 协议层写入响应的位置
 * 返回值 网络层需要发送的响应长度
 */
typedef int (*msg_handler)(char *msg, int length, char *response);

/* 三种网络层向 kvstore.c 暴露相同形式的启动函数 */
extern int reactor_start(unsigned short port, msg_handler handler);
extern int ntyco_start(unsigned short port, msg_handler handler);
extern int proactor_start(unsigned short port, msg_handler handler);

/* KV 项目支持的命令名称 */
const char *command[] = {
 "SET", "GET", "DEL", "MOD", "EXIST"
};

/* 响应字符串表，目前未填充 */
const char *response[] = {
};

#endif

这一文件的整体作用可以概括为：

NETWORK_SELECT 决定使用谁
msg_handler 规定协议函数长什么样
三个 start 规定网络层怎样启动
command 列出 KV 命令集合

2.2 `kvstore.c`：选择网络层，并把协议函数交给它

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "kvstore.h"

/*
 * 当前是 echo 形式的 KV 协议入口。
 * 网络层把请求传进来，本函数把请求复制成响应。
 */
int kvs_protocol(char *msg, int length, char *response) {
 /* 输出本次请求长度与内容 */
 printf("recv: %d: %s\n", length, msg);

 /* 将收到的 length 个字节复制到响应缓冲区 */
 memcpy(response, msg, length);

 /* 把响应长度交还给网络层 */
 return strlen(response);
}

int main(int argc, char *argv[]) {
 /* 启动形式要求为：./kvstore <port> */
 if (argc != 2) return -1;

 /* 将命令行中的端口字符串转换成整数 */
 int port = atoi(argv[1]);

 /*
 * 编译期选择网络模型。
 * 三个分支都把同一个 kvs_protocol 作为 handler 传入。
 */
#if (NETWORK_SELECT == NETWORK_REACTOR)
 reactor_start(port, kvs_protocol);
#elif (NETWORK_SELECT == NETWORK_NTYCO)
 ntyco_start(port, kvs_protocol);
#elif (NETWORK_SELECT == NETWORK_PROACTOR)
 proactor_start(port, kvs_protocol);
#endif
}

这里最需要记住的不是条件编译本身，而是下面三个调用具有完全相同的含义：

reactor_start(port, kvs_protocol);
ntyco_start(port, kvs_protocol);
proactor_start(port, kvs_protocol);

可以统一读作：

在指定端口启动某个网络后端；以后收到消息时，请调用 kvs_protocol()。

3. Reactor 的连接结构：`server.h`

Reactor 是事件驱动的。一次读事件和下一次写事件不是在同一个函数中连续完成，因此需要 struct conn 保存跨事件存在的连接信息。

#ifndef SERVER_H
#define SERVER_H

/* 每个连接的读、写缓冲区都是 1024 字节 */
#define BUFFER_LENGTH 1024

/* 当前 Reactor 上层启用 KVSTORE 协议 */
#define ENABLE_HTTP 0
#define ENABLE_WEBSOCKET 0
#define ENABLE_KVSTORE 1

/* epoll 事件回调：传入发生事件的 fd */
typedef int (*RCALLBACK)(int fd);

struct conn {
 int fd; // 当前连接的 socket fd

 char rbuffer[BUFFER_LENGTH]; // recv 接收到的请求
 int rlength; // 请求的实际长度

 char wbuffer[BUFFER_LENGTH]; // KV 协议生成的响应
 int wlength; // 响应的实际长度

 RCALLBACK send_callback; // EPOLLOUT 时调用 send_cb

 union {
 RCALLBACK recv_callback; // 客户端 fd 可读时调用 recv_cb
 RCALLBACK accept_callback; // 监听 fd 可读时调用 accept_cb
 } r_action;

 int status; // 连接/协议状态字段

#if 1 // websocket
 char *payload; // WebSocket 数据字段
 char mask[4]; // WebSocket 掩码字段
#endif
};

/* 同一套 Reactor 曾为不同上层协议保留入口 */
#if ENABLE_HTTP
int http_request(struct conn *c);
int http_response(struct conn *c);
#endif

#if ENABLE_WEBSOCKET
int ws_request(struct conn *c);
int ws_response(struct conn *c);
#endif

#if ENABLE_KVSTORE
int kvs_request(struct conn *c);
int kvs_response(struct conn *c);
#endif

#endif

struct conn 可以用一条数据流来理解：

recv(fd)
 ↓
rbuffer + rlength
 ↓ kvs_handler
wbuffer + wlength
 ↓
send(fd)

两个函数指针则决定 epoll 返回事件时执行什么：

监听 fd 的 EPOLLIN → accept_cb
连接 fd的 EPOLLIN → recv_cb
连接 fd的 EPOLLOUT → send_cb

4. Reactor 网络层：`reactor.c`

4.1 Reactor 总体流程

创建 epoll
 ↓
创建 20 个监听 socket，并注册 EPOLLIN
 ↓
epoll_wait
 ├─ 监听 fd 可读 → accept_cb
 ├─ 客户端 fd 可读 → recv_cb → kvs_protocol
 └─ 客户端 fd 可写 → send_cb

4.2 KV 回调和连接表

#define CONNECTION_SIZE 1048576 // 连接表容量
#define MAX_PORTS 20 // 连续监听 20 个端口

/* 计算两次 timeval 之间的毫秒差，用于 accept 统计 */
#define TIME_SUB_MS(tv1, tv2) \
 ((tv1.tv_sec - tv2.tv_sec) * 1000 + \
 (tv1.tv_usec - tv2.tv_usec) / 1000)

#if ENABLE_KVSTORE
/* reactor_start 会把 kvs_protocol 保存到这里 */
static msg_handler kvs_handler;

int kvs_request(struct conn *c) {
 /*
 * 将连接的接收缓冲区交给 KV 层；
 * KV 层把响应写入同一连接的发送缓冲区；
 * 返回值记录到 wlength。
 */
 c->wlength = kvs_handler(
 c->rbuffer,
 c->rlength,
 c->wbuffer
 );
}

int kvs_response(struct conn *c) {
 /* 当前 KV 响应不再进行二次处理 */
}
#endif

int epfd = 0; // epoll 实例 fd
struct timeval begin; // accept 统计起点
struct conn conn_list[CONNECTION_SIZE]; // 用 fd 直接索引连接

4.3 添加和切换 epoll 事件

int set_event(int fd, int event, int flag) {
 struct epoll_event ev;
 ev.events = event; // EPOLLIN 或 EPOLLOUT
 ev.data.fd = fd; // epoll 返回事件时带回这个 fd

 if (flag) {
 /* 新 fd 第一次进入 epoll */
 epoll_ctl(epfd, EPOLL_CTL_ADD, fd, &ev);
 } else {
 /* 已登记 fd 在读、写关注之间切换 */
 epoll_ctl(epfd, EPOLL_CTL_MOD, fd, &ev);
 }
}

这份 Reactor 的主要节奏，就是不断切换同一个客户端的事件：

刚建立连接 → EPOLLIN
收到并处理请求 → EPOLLOUT
发送完响应 → EPOLLIN

4.4 初始化一个客户端连接

int event_register(int fd, int event) {
 if (fd < 0) return -1;

 /* fd 同时也是 conn_list 的下标 */
 conn_list[fd].fd = fd;

 /* 客户端可读和可写时对应的处理函数 */
 conn_list[fd].r_action.recv_callback = recv_cb;
 conn_list[fd].send_callback = send_cb;

 /* 初始化这个连接的输入区域 */
 memset(conn_list[fd].rbuffer, 0, BUFFER_LENGTH);
 conn_list[fd].rlength = 0;

 /* 初始化这个连接的输出区域 */
 memset(conn_list[fd].wbuffer, 0, BUFFER_LENGTH);
 conn_list[fd].wlength = 0;

 /* 新连接加入 epoll，调用处传入的是 EPOLLIN */
 set_event(fd, event, 1);
}

4.5 创建监听 socket

int r_init_server(unsigned short port) {
 /* 创建 IPv4 TCP socket */
 int sockfd = socket(AF_INET, SOCK_STREAM, 0);

 struct sockaddr_in servaddr;
 servaddr.sin_family = AF_INET;
 servaddr.sin_addr.s_addr = htonl(INADDR_ANY); // 0.0.0.0
 servaddr.sin_port = htons(port); // 监听端口

 /* 把 socket 绑定到本机端口 */
 if (bind(sockfd,
 (struct sockaddr *)&servaddr,
 sizeof(struct sockaddr)) == -1) {
 printf("bind failed: %s\n", strerror(errno));
 }

 /* 将 socket 变为监听 socket */
 listen(sockfd, 10);

 return sockfd;
}

4.6 接受客户端

int accept_cb(int fd) {
 struct sockaddr_in clientaddr;
 socklen_t len = sizeof(clientaddr);

 /*
 * fd 是监听 socket；
 * clientfd 是新建立的客户端连接。
 */
 int clientfd = accept(
 fd,
 (struct sockaddr *)&clientaddr,
 &len
 );

 printf("accept finshed: %d,fd:%d\n", clientfd, fd);

 if (clientfd < 0) {
 printf("accept errno: %d --> %s\n",
 errno, strerror(errno));
 return -1;
 }

 /* 新客户端从等待读事件开始 */
 event_register(clientfd, EPOLLIN);

 /* 每当 fd 到达 1000 的整数倍，打印一次时间间隔 */
 if ((clientfd % 1000) == 0) {
 struct timeval current;
 gettimeofday(&current, NULL);

 int time_used = TIME_SUB_MS(current, begin);
 memcpy(&begin, &current, sizeof(struct timeval));

 printf("accept finshed: %d, time_used: %d\n",
 clientfd, time_used);
 }

 return 0;
}

4.7 接收请求并进入 KV 协议

int recv_cb(int fd) {
 /* 本次接收前清空该连接的读缓冲区 */
 memset(conn_list[fd].rbuffer, 0, BUFFER_LENGTH);

 /* 从客户端接收数据 */
 int count = recv(
 fd,
 conn_list[fd].rbuffer,
 BUFFER_LENGTH,
 0
 );

 if (count == 0) {
 /* recv 返回 0：客户端断开 */
 printf("client disconnect: %d\n", fd);
 close(fd);
 epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);
 return 0;
 } else if (count < 0) {
 /* recv 返回负数：打印错误并结束连接 */
 printf("count: %d, errno: %d, %s\n",
 count, errno, strerror(errno));
 close(fd);
 epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);
 return 0;
 }

 /* 保存这次实际收到的请求长度 */
 conn_list[fd].rlength = count;

#if 0
 /* echo 分支：直接把读缓冲复制到写缓冲 */
 conn_list[fd].wlength = conn_list[fd].rlength;
 memcpy(conn_list[fd].wbuffer,
 conn_list[fd].rbuffer,
 conn_list[fd].wlength);
#elif ENABLE_HTTP
 http_request(&conn_list[fd]);
#elif ENABLE_WEBSOCKET
 ws_request(&conn_list[fd]);
#elif ENABLE_KVSTORE
 /* 当前启用的分支：通过 handler 生成 KV 响应 */
 kvs_request(&conn_list[fd]);
#endif

 /* 请求处理完成，下一阶段等待发送 */
 set_event(fd, EPOLLOUT, 0);
 return count;
}

这里完成了项目中最重要的一次跨层调用：

recv_cb
 → kvs_request(&conn_list[fd])
 → kvs_handler(rbuffer, rlength, wbuffer)
 → kvs_protocol

4.8 发送响应

int send_cb(int fd) {
#if ENABLE_HTTP
 http_response(&conn_list[fd]);
#elif ENABLE_WEBSOCKET
 ws_response(&conn_list[fd]);
#elif ENABLE_KVSTORE
 /* KV 分支当前不对 wbuffer 做额外处理 */
 kvs_response(&conn_list[fd]);
#endif

 int count = 0;

 /* wlength 非零时，把 KV 响应发给客户端 */
 if (conn_list[fd].wlength != 0) {
 count = send(
 fd,
 conn_list[fd].wbuffer,
 conn_list[fd].wlength,
 0
 );
 }

 /* 响应阶段结束，再次等待客户端请求 */
 set_event(fd, EPOLLIN, 0);
 return count;
}

4.9 启动 Reactor 主循环

int reactor_start(unsigned short port, msg_handler handler) {
 printf("reactor_entry %d\n", port);

 /* 保存由 main 传入的 kvs_protocol */
 kvs_handler = handler;

 /* 创建 epoll 实例 */
 epfd = epoll_create(1);

 /* 从 port 开始连续建立 20 个监听端口 */
 for (int i = 0; i < MAX_PORTS; i++) {
 int sockfd = r_init_server(port + i);

 /* 监听 fd 可读时执行 accept_cb */
 conn_list[sockfd].fd = sockfd;
 conn_list[sockfd].r_action.recv_callback = accept_cb;

 /* 将监听 fd 加入 epoll */
 set_event(sockfd, EPOLLIN, 1);
 }

 /* accept 性能统计的起始时间 */
 gettimeofday(&begin, NULL);

 while (1) {
 struct epoll_event events[1024] = {0};

 /* 阻塞等待，最多取得 1024 个就绪事件 */
 int nready = epoll_wait(epfd, events, 1024, -1);

 for (int i = 0; i < nready; i++) {
 int connfd = events[i].data.fd;

 /*
 * 监听 fd：read callback 是 accept_cb；
 * 客户端 fd：read callback 是 recv_cb。
 */
 if (events[i].events & EPOLLIN) {
 conn_list[connfd]
 .r_action.recv_callback(connfd);
 }

 /* 客户端可写时调用 send_cb */
 if (events[i].events & EPOLLOUT) {
 conn_list[connfd]
 .send_callback(connfd);
 }
 }
 }
}

把整份 Reactor 压缩成一句话：

epoll 主循环根据 fd 和事件找到回调；读回调接收请求并调用 KV handler，写回调发送 handler 生成的响应。

5. io_uring Proactor 网络层：`proactor.c`

5.1 Proactor 总体流程

准备 ACCEPT 操作
 ↓ submit
等待完成队列 CQ
 ↓
ACCEPT 完成 → 得到 connfd → 准备 RECV
 ↓
READ 完成 → 调 kvs_protocol → 准备 SEND
 ↓
WRITE 完成 → 再次准备 RECV

Reactor 是“事件就绪以后调用 I/O”，这份 io_uring 代码是“先提交具体 I/O，再处理完成结果”。

5.2 操作类型与操作标记

/* 用于区分 CQE 对应哪一种操作 */
#define EVENT_ACCEPT 0
#define EVENT_READ 1
#define EVENT_WRITE 2

struct conn_info {
 int fd; // 操作所属的 socket
 int event; // ACCEPT / READ / WRITE
};

#define ENTRIES_LENGTH 1024 // io_uring 队列项参数
#define BUFFER_LENGTH 1024 // 网络缓冲区长度

/* proactor_start 保存 main 传入的 kvs_protocol */
static msg_handler kvs_handler;

每个 SQE 都通过 user_data 带上 conn_info。CQE 返回以后，程序就知道完成的是谁的什么操作。

5.3 准备 send

int set_event_send(struct io_uring *ring,
 int sockfd,
 void *buf,
 size_t len,
 int flags) {
 /* 从提交队列取得一个 SQE */
 struct io_uring_sqe *sqe = io_uring_get_sqe(ring);

 /* 标记这是 sockfd 的写操作 */
 struct conn_info info = {
 .fd = sockfd,
 .event = EVENT_WRITE,
 };

 /* 将 SQE 填写为 send 请求 */
 io_uring_prep_send(sqe, sockfd, buf, len, flags);

 /* 操作完成时，通过 user_data 找回 fd 和事件类型 */
 memcpy(&sqe->user_data, &info, sizeof(struct conn_info));
}

5.4 准备 recv

int set_event_recv(struct io_uring *ring,
 int sockfd,
 void *buf,
 size_t len,
 int flags) {
 struct io_uring_sqe *sqe = io_uring_get_sqe(ring);

 /* 标记这是 sockfd 的读操作 */
 struct conn_info info = {
 .fd = sockfd,
 .event = EVENT_READ,
 };

 /* 将 SQE 填写为 recv 请求 */
 io_uring_prep_recv(sqe, sockfd, buf, len, flags);

 memcpy(&sqe->user_data, &info, sizeof(struct conn_info));
}

5.5 准备 accept

int set_event_accept(struct io_uring *ring,
 int sockfd,
 struct sockaddr *addr,
 socklen_t *addrlen,
 int flags) {
 struct io_uring_sqe *sqe = io_uring_get_sqe(ring);

 /* 标记这是监听 sockfd 的 accept 操作 */
 struct conn_info info = {
 .fd = sockfd,
 .event = EVENT_ACCEPT,
 };

 /* 将 SQE 填写为 accept 请求 */
 io_uring_prep_accept(sqe, sockfd, addr, addrlen, flags);

 memcpy(&sqe->user_data, &info, sizeof(struct conn_info));
}

三个函数的结构完全一致，只有 prep 函数和 event 类型不同：

准备函数	liburing prep	事件标记
`set_event_accept`	`io_uring_prep_accept`	`EVENT_ACCEPT`
`set_event_recv`	`io_uring_prep_recv`	`EVENT_READ`
`set_event_send`	`io_uring_prep_send`	`EVENT_WRITE`

5.6 创建监听 socket

int p_init_server(unsigned short port) {
 /* 创建 IPv4 TCP socket */
 int sockfd = socket(AF_INET, SOCK_STREAM, 0);

 struct sockaddr_in servaddr;
 servaddr.sin_family = AF_INET;
 servaddr.sin_addr.s_addr = htonl(INADDR_ANY);
 servaddr.sin_port = htons(port);

 /* 绑定端口 */
 if (bind(sockfd,
 (struct sockaddr *)&servaddr,
 sizeof(struct sockaddr)) == -1) {
 printf("bind failed: %s\n", strerror(errno));
 }

 /* 开始监听 */
 listen(sockfd, 10);
 return sockfd;
}

5.7 初始化 io_uring 并准备第一个 accept

int proactor_start(unsigned short port, msg_handler handler) {
 /* 创建监听 socket */
 int sockfd = p_init_server(port);

 /* 保存 kvs_protocol */
 kvs_handler = handler;

 /* 初始化 io_uring 参数 */
 struct io_uring_params params;
 memset(&params, 0, sizeof(params));

 /* 创建提交队列和完成队列 */
 struct io_uring ring;
 io_uring_queue_init_params(
 ENTRIES_LENGTH,
 &ring,
 &params
 );

 /* accept 完成后，内核会填写客户端地址 */
 struct sockaddr_in clientaddr;
 socklen_t len = sizeof(clientaddr);

 /* 在进入循环之前，先准备第一个 accept SQE */
 set_event_accept(
 &ring,
 sockfd,
 (struct sockaddr *)&clientaddr,
 &len,
 0
 );

 /* READ 使用 buffer，KV 输出和 WRITE 使用 response */
 char buffer[BUFFER_LENGTH] = {0};
 char response[BUFFER_LENGTH] = {0};

5.8 提交和取得完成事件

 while (1) {
 /* 把当前已经准备好的 SQE 提交给 io_uring */
 io_uring_submit(&ring);

 /* 至少等待一个操作完成 */
 struct io_uring_cqe *cqe;
 io_uring_wait_cqe(&ring, &cqe);

 /* 一次批量取出最多 128 个完成项 */
 struct io_uring_cqe *cqes[128];
 int nready = io_uring_peek_batch_cqe(
 &ring,
 cqes,
 128
 );

 for (int i = 0; i < nready; i++) {
 struct io_uring_cqe *entry = cqes[i];

 /* 从 user_data 还原这个操作的 fd 和类型 */
 struct conn_info result;
 memcpy(&result,
 &entry->user_data,
 sizeof(struct conn_info));

这里的两个信息来源要分清：

result.fd / result.event
 提交 SQE 时由应用保存
 用来识别“谁的什么操作”

entry->res
 操作完成时由内核返回
 用来表示 accept 的新 fd、recv 长度或 send 结果

5.9 分发 ACCEPT、READ 和 WRITE 完成事件

 if (result.event == EVENT_ACCEPT) {
 /*
 * 当前 accept 已完成；
 * 先准备下一个 accept，保持继续接收新连接。
 */
 set_event_accept(
 &ring,
 sockfd,
 (struct sockaddr *)&clientaddr,
 &len,
 0
 );

 /* accept CQE 的 res 是新客户端 fd */
 int connfd = entry->res;

 /* 为新客户端准备第一次 recv */
 set_event_recv(
 &ring,
 connfd,
 buffer,
 BUFFER_LENGTH,
 0
 );

 } else if (result.event == EVENT_READ) {
 /* recv CQE 的 res 是本次收到的字节数 */
 int ret = entry->res;

 if (ret == 0) {
 /* 客户端关闭连接 */
 close(result.fd);
 } else if (ret > 0) {
 /*
 * buffer + ret 构成请求；
 * response 接收 KV 协议输出；
 * 返回值重新赋给 ret，作为响应长度。
 */
 ret = kvs_handler(buffer, ret, response);

 /* 准备把 KV 响应发送给原客户端 */
 set_event_send(
 &ring,
 result.fd,
 response,
 ret,
 0
 );
 }

 } else if (result.event == EVENT_WRITE) {
 /* send CQE 的 res 是写操作完成结果 */
 int ret = entry->res;

 /* 本轮响应结束，再次等待该客户端请求 */
 set_event_recv(
 &ring,
 result.fd,
 buffer,
 BUFFER_LENGTH,
 0
 );
 }
 }

 /* 告诉 ring：这一批 CQE 已经处理完 */
 io_uring_cq_advance(&ring, nready);
 }
}

把整份 Proactor 压缩成一句话：

每处理一个完成事件，就准备这个连接的下一项操作；READ 完成与 WRITE 准备之间插入一次 KV handler 调用。

6. ntyco 协程网络层：`ntyco.c`

6.1 ntyco 在项目中的结构

ntyco_start
 ↓ 创建
server 协程：socket → bind → listen → accept
 ↓ 每个客户端创建
server_reader 协程：recv → kvs_protocol → send

这里不展开 nty_coroutine_create 和 nty_schedule_run 的内部实现，只观察项目怎样调用框架。

6.2 客户端处理协程

/* ntyco_start 保存 main 传入的 kvs_protocol */
static msg_handler kvs_handler;

void server_reader(void *arg) {
 /* server 创建协程时传入的是 cli_fd 地址 */
 int fd = *(int *)arg;
 int ret = 0;

 while (1) {
 /* 每轮准备一个新的接收缓冲区 */
 char buf[1024] = {0};

 /* 接收这个客户端的请求 */
 ret = recv(fd, buf, 1024, 0);

 if (ret > 0) {
 /* 为本轮响应准备缓冲区 */
 char response[1024] = {0};

 /*
 * buf + ret 是请求；
 * response 是 KV 输出；
 * slength 是响应长度。
 */
 int slength = kvs_handler(buf, ret, response);

 /* 将 KV 响应发送给当前客户端 */
 ret = send(fd, response, slength, 0);

 if (ret == -1) {
 close(fd);
 break;
 }
 } else if (ret == 0) {
 /* 客户端正常关闭连接 */
 close(fd);
 break;
 }
 }
}

与 Reactor、Proactor 相比，协程版本把同一个客户端的处理过程写在一个顺序循环里：

recv(...);
kvs_handler(...);
send(...);

6.3 监听协程

void server(void *arg) {
 /* 还原 ntyco_start 传入的端口 */
 unsigned short port = *(unsigned short *)arg;

 /* 创建 IPv4 TCP 监听 socket */
 int fd = socket(AF_INET, SOCK_STREAM, 0);
 if (fd < 0) return;

 /* 填写本地监听地址 */
 struct sockaddr_in local, remote;
 local.sin_family = AF_INET;
 local.sin_port = htons(port);
 local.sin_addr.s_addr = INADDR_ANY;

 /* 绑定并监听 */
 bind(fd,
 (struct sockaddr *)&local,
 sizeof(struct sockaddr_in));
 listen(fd, 20);

 printf("listen port : %d\n", port);

 while (1) {
 socklen_t len = sizeof(struct sockaddr_in);

 /* 接受一个客户端连接 */
 int cli_fd = accept(
 fd,
 (struct sockaddr *)&remote,
 &len
 );

 /*
 * 每个客户端创建一个 server_reader 协程；
 * 该协程负责此后的 recv、KV 处理和 send。
 */
 nty_coroutine *read_co;
 nty_coroutine_create(
 &read_co,
 server_reader,
 &cli_fd
 );
 }
}

6.4 ntyco 网络层入口

int ntyco_start(unsigned short port, msg_handler handler) {
 /* 保存 kvs_protocol */
 kvs_handler = handler;

 /* 创建负责监听和 accept 的 server 协程 */
 nty_coroutine *co = NULL;
 nty_coroutine_create(&co, server, &port);

 /* 启动 ntyco 调度器 */
 nty_schedule_run();
}

把 ntyco 版本压缩成一句话：

server 协程负责产生连接，每个连接再由一个 reader 协程按顺序完成接收、协议处理和发送。

7. 三种网络层放在一起回顾

7.1 同一阶段的代码对应关系

阶段	Reactor	io_uring Proactor	ntyco
保存 KV 函数	`kvs_handler = handler`	`kvs_handler = handler`	`kvs_handler = handler`
等待连接	监听 fd 的 `EPOLLIN`	提交 `ACCEPT` SQE	`server` 协程调用 `accept`
获得连接	`accept_cb()`	`EVENT_ACCEPT` CQE	`accept()` 返回
等待请求	客户端 fd 的 `EPOLLIN`	提交 `RECV` SQE	reader 协程调用 `recv`
KV 接入点	`kvs_request()`	`EVENT_READ` 分支	`server_reader()`
发送响应	`send_cb()`	提交 `SEND` SQE	reader 协程调用 `send`
继续循环	改回 `EPOLLIN`	WRITE 完成后再提交 RECV	while 回到 recv

7.2 一次请求的三条完整路径

Reactor

epoll_wait
 → EPOLLIN
 → recv_cb
 → conn.rbuffer / conn.rlength
 → kvs_request
 → kvs_protocol
 → conn.wbuffer / conn.wlength
 → EPOLLOUT
 → send_cb
 → EPOLLIN

Proactor

提交 RECV
 → READ CQE
 → buffer / entry->res
 → kvs_protocol
 → response / 响应长度
 → 提交 SEND
 → WRITE CQE
 → 再提交 RECV

ntyco

server_reader 协程
 → recv
 → buf / ret
 → kvs_protocol
 → response / slength
 → send
 → 下一轮 recv

7.3 两种回调不要混淆

/* Reactor 内部的网络事件回调 */
typedef int (*RCALLBACK)(int fd);

/* 三种网络层共同使用的 KV 协议回调 */
typedef int (*msg_handler)(char *msg,
 int length,
 char *response);

它们的层次是：

Reactor 中：
epoll → RCALLBACK → recv_cb → msg_handler → kvs_protocol

Proactor 中：
CQE → EVENT_READ 分支 → msg_handler → kvs_protocol

ntyco 中：
server_reader → msg_handler → kvs_protocol

8. 最后的整体记忆

重新回顾这个项目时，只需要先恢复四个关键词：

NETWORK_SELECT
 决定使用 Reactor、Proactor 还是 ntyco

msg_handler
 把网络层与 KV 协议层连接起来

kvs_protocol
 接收请求、生成响应，当前实现为 echo

网络事件循环
 三种模型分别用 epoll、io_uring、协程完成连接和收发

整个程序的共同主干是：

/* main 把协议函数交给网络层 */
network_start(port, kvs_protocol);

/* 网络层保存函数地址 */
kvs_handler = handler;

/* 网络层收到请求后调用它 */
response_len = kvs_handler(
 request,
 request_len,
 response
);

/* 网络层按返回长度发送响应 */
send(clientfd, response, response_len, 0);

这四步就是六份代码共同围绕的核心。三种网络模型改变的是“请求怎样到达这四步、响应怎样离开这四步”，而 KV 协议入口保持一致。

KV 存储 on JasperSao的博客

KV 进化（二）：Snapshot 全量快照 + AOF 增量日志

1. 确立实现模式

2. 建立独立的持久化模块

3. 打开和关闭 AOF

4. 把命令追加到 AOF

5. 从缓冲区同步到文件

6. 判断哪些命令需要写入 AOF

7. 只有命令执行成功才记录

8. AOF 重放

9. AOF 重放函数的实际过程

10. AOF 基础闭环

11. 开始实现全量快照

12. 定义统一的访问函数

13. foreach 的职责

14. context 的意义

15. 把一组 key-value 写进快照

16. 为什么快照中只保存 SET 类型的命令

17. 保存所有引擎的数据

18. 使用临时文件保存快照

19. 把快照同步到磁盘

20. 增加 SAVE 命令

21. 快照与 AOF 的重复问题

22. 获取 AOF 当前偏移量

23. 把 AOF 偏移量写进快照

24. 加载全量快照

25. 读取快照中的偏移量

26. 逐行恢复快照数据

27. 让 AOF 从指定位置开始重放

28. 最终启动恢复顺序

29. 快照与 AOF 最终如何配合

30. 最终验证

31. 当前完成的整体闭环

KV 进化（一）：给 91kvstore 接上一条跳表

先对跳表有个大致印象

写跳表之前，我先整理了项目

第一步：把整数跳表改造成字符串 KV

第二步：补齐统一接口

第三步：统一返回值

第四步：别让测试变成纯苦力

第五步：从“能运行”走向“融入项目”

第六步：创建全局跳表实例

第七步：命令协议融合

最后：用 testcase 做端到端测试

小结

KV 存储项目：Hash 接入、多语言客户端与 SkipList 扩展

与前三篇的关系

1. 本阶段增加了什么

2. Hash 在项目中的位置

3. 第一个接入点：kvstore.h

3.1 增加编译开关

3.2 Hash 实例在项目中的最小理解

3.3 对外仍然使用已有的 5+2 形状

4. 第二个接入点：Makefile

5. 第三个接入点：实例生命周期

5.1 定义全局实例

5.2 网络服务启动前创建

5.3 网络服务停止后销毁

6. 第四个接入点：协议命令

一条 HSET 的新增路径

7. 当前 Hash 代码必须修正的工程问题

7.1 创建后必须把桶数组清零

7.2 下标计算应使用实例容量

7.3 创建节点失败要逆序回滚

7.4 三条释放路径必须一致

7.5 MOD 要先申请，再替换

7.6 其他接口一致性问题

8. 多语言支持：本阶段新增的认识

用同一场景验证五种语言

9. 课后扩展：把 SkipList 融入 KVEngine

9.1 范围查询需要扩展 5+2

10. 面试题

10.1 KV 存储为什么常采用单线程执行命令？

10.2 范围查询应选择什么 KVEngine？

10.3 频繁 malloc/free 时怎样管理 KV 内存？

11. 本阶段的实施顺序

总结

KV 存储项目：客户端测试、压力测试与多引擎扩展

1. 这一阶段解决什么问题

2. 用 Makefile 固定构建过程

3. 第一个接入点：`kvstore.h`

一条 `HSET` 的新增路径

6.1 `total` 的核心约定

9. 为什么给红黑树命令增加 `R` 前缀

6. `kvstore.h`：数组引擎的数据结构与接口

8. 创建数组实例：`kvs_array_create()`

9. `SET`：保存一组 key-value

10. `GET`：按照 key 查找 value

11. `DEL`：删除 key-value

12. `MOD`：修改已有 key 的 value

13. `EXIST`：复用 GET 判断 key 是否存在

15. `kvs_split_token()`：把命令切成参数

16. `kvs_filter_protocol()`：识别命令并生成响应

17. `kvs_protocol()`：本篇代码的总入口

19. 一条 `SET` 命令的完整路径

20. 一条 `GET` 命令的完整路径