数据结构 on JasperSao的博客

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 存储项目：客户端测试、压力测试与多引擎扩展

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

数据结构 on JasperSao的博客

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

先对跳表有个大致印象

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

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

第二步：补齐统一接口

第三步：统一返回值

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

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

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

第七步：命令协议融合

最后：用 testcase 做端到端测试

小结

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

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

2. 用 Makefile 固定构建过程

2.1 NtyCo 是项目的外部依赖

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

3.1 一个测试用例包含什么

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

4.1 测试覆盖的两个方向

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

5.1 三次粗测说明了什么

5.2 当前 QPS 的准确含义

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

6.1 total 的核心约定

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

7.1 删除 value 时的内存顺序

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

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

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

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

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

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

11.1 树实例和节点

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

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

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

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

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

14.1 多进程思路

14.2 多线程思路

14.3 并发数增加后观察什么

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

16. 最后的复习提纲

16.1 测试主线

16.2 压力测试主线

16.3 数组问题定位主线

16.4 多引擎扩展主线

16.5 本阶段最重要的认识

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

1. 从网络层进入协议层

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

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

3.1 在包头记录长度

3.2 使用结束标记

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

5. 文件职责

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

6.1 编译配置

6.2 一个 KV 元素

6.3 整个数组实例

7. 封装内存分配接口

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

9. SET：保存一组 key-value

10. GET：按照 key 查找 value

11. DEL：删除 key-value

12. MOD：修改已有 key 的 value

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

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

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

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

16.1 查找命令编号

16.2 SET 分支

16.3 GET 分支

16.4 DEL 分支

16.5 MOD 分支

16.6 EXIST 分支

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

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

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` 命令的完整路径