项目记录 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 协议入口保持一致。

Go 项目反推：Feed 流系统实战——Feed 流设计

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——数据库与 GORM，这一篇继续拆解 feedsystem_video_go 的核心 Feed 流：从推拉模型到游标分页，再到热榜、关注流、话题流与缓存策略。

什么是 Feed 流

打开抖音/微博，往下刷，不断出来新内容，这就是 Feed 流。

这个项目的 4 种 Feed 流

类型	说明	排序方式
最新视频	全站最新发布的视频	按时间倒序
热榜	最热门的视频	按热度排序
关注流	只看关注的人发的视频	按时间倒序
话题流	某个话题下的视频	按时间倒序

推模型 vs 拉模型

拉模型（这个项目用的）

发视频：只写Video表（不做额外操作）
刷视频：实时查询Video表（拉取数据）

数据流动：用户刷的时候才从 DB 拉。

推模型

发视频：写Video表 + 把视频ID推送到所有粉丝的Feed列表里
刷视频：直接从自己的Feed列表读（不用查DB）

数据流动：发的时候就推给粉丝了，粉丝刷的时候直接读。

推拉结合

普通用户发视频 → 推送给粉丝（粉丝少，推送成本低）
大V发视频 → 不推送，粉丝读的时候实时拉取

对比

	拉模型	推模型	推拉结合
发视频成本	低	高（大V要推给几百万粉丝）	中
刷视频成本	高（每次都要查DB）	低（直接读列表）	中
实时性	实时	略有延迟	中
复杂度	简单	复杂	最复杂
场景	用户量小	用户量大	抖音/微博

这个项目用拉模型，因为是学习项目，用户量小，拉模型简单够用。

游标分页 vs 页码分页

页码分页

第1页：GET /feed?page=1&size=10
第2页：GET /feed?page=2&size=10

对应 SQL：

SELECT * FROM videos ORDER BY create_time DESC LIMIT 5 OFFSET 0 -- 第1页
SELECT * FROM videos ORDER BY create_time DESC LIMIT 5 OFFSET 5 -- 第2页

问题：数据变化时可能重复或漏数据

数据库：[100, 90, 80, 70, 60, 50, 40, 30]

第1页（page=1, size=3）：跳过0条，取3条 → [100, 90, 80]

插入新视频110，数据库变成：[110, 100, 90, 80, 70, 60, 50, 40, 30]

第2页（page=2, size=3）：跳过3条，取3条 → [80, 70, 60]

视频80重复出现了！

为什么？因为 OFFSET 是基于"位置"的，不是基于"数据"的。新视频插入后，原来第 4 个位置的视频 80 变成了第 5 个，但 OFFSET 还是 3，所以又取到了。

游标分页（这个项目用的）

第1页：GET /feed?limit=10
 返回：video_list + next_time=1000

第2页：GET /feed?limit=10&latest_time=1000
 返回：video_list + next_time=900

对应 SQL：

SELECT * FROM videos ORDER BY create_time DESC LIMIT 10
SELECT * FROM videos WHERE create_time < 1000 ORDER BY create_time DESC LIMIT 10

为什么游标分页不会重复？

第1页：WHERE create_time < now() LIMIT 3
 返回 [100, 90, 80]
 next_time = 80的时间

插入110

第2页：WHERE create_time < 80的时间 LIMIT 3
 返回 [70, 60, 50]

没有重复！

游标是基于数据的值（时间），不是位置。新视频插入不影响查询条件。

对比

	页码分页	游标分页
请求方式	page=2	latest_time=1000
数据变化时	可能重复或漏数据	不会重复
SQL	OFFSET 跳过	WHERE 条件过滤
场景	后台管理系统	Feed 流、时间线

游标分页的实现

服务器代码

func (repo *FeedRepository) ListLatest(ctx context.Context, limit int, latestBefore time.Time) ([]*video.Video, error) {
 query := repo.db.WithContext(ctx).Model(&video.Video{}).Order("create_time DESC")

 // 关键：如果有游标，加上WHERE条件
 if !latestBefore.IsZero() {
 query = query.Where("create_time < ?", latestBefore)
 }

 query.Limit(limit).Find(&videos)
 return videos, nil
}

游标怎么生成的

// 取本页最后一条视频的时间作为游标
var nextTime int64
if len(baseVideos) > 0 {
 nextTime = baseVideos[len(baseVideos)-1].CreateTime.UnixMilli()
}

本页最后一条视频的时间 = 下一页的起点。

响应结构

type ListLatestResponse struct {
 VideoList []FeedVideoItem `json:"video_list"`
 NextTime int64 `json:"next_time"` // 游标
 HasMore bool `json:"has_more"` // 还有没有更多
}

完整流程

客户端：GET /feed?limit=10
 ↓
服务器：SELECT * FROM videos ORDER BY create_time DESC LIMIT 10
 ↓
返回：video_list + next_time = 本页最后一条的时间
 ↓
客户端：GET /feed?limit=10&latest_time=next_time
 ↓
服务器：SELECT * FROM videos WHERE create_time < next_time ORDER BY create_time DESC LIMIT 10
 ↓
返回：video_list + next_time = 新的游标
 ↓
...循环，直到 has_more = false

热榜实现

热榜排序算法

query := repo.db.WithContext(ctx).Model(&video.Video{}).
 Order("popularity DESC, create_time DESC, id DESC")

排序规则：热度高的优先，热度相同按时间倒序，时间也相同按 ID 倒序。

热度分数怎么算的

func UpdatePopularityCache(ctx context.Context, cache *rediscache.Client, id uint, change int64) {
 now := time.Now().UTC().Truncate(time.Minute)
 windowKey := cache.Key("hot:video:1m:%s", now.Format("200601021504"))
 member := strconv.FormatUint(uint64(id), 10)

 cache.ZincrBy(opCtx, windowKey, member, float64(change)) // 热度+change
 cache.Expire(opCtx, windowKey, 2*time.Hour)
}

每次点赞/评论/关注，热度+1。

热榜查询流程（冷热分离）

func (f *FeedService) ListByPopularity(ctx context.Context, limit int, reqAsOf int64, offset int, ...) {
 // 1. 确定时间窗口（最近60分钟）
 asOf := time.Now().UTC().Truncate(time.Minute)

 // 2. 生成60个ZSET的key
 keys := make([]string, 0, 60)
 for i := 0; i < 60; i++ {
 keys = append(keys, f.rediscache.Key("hot:video:1m:%s", asOf.Add(-time.Duration(i)*time.Minute).Format("200601021504")))
 }

 // 3. 合并成一个ZSET（快照）
 dest := f.rediscache.Key("hot:video:merge:1m:%s", asOf.Format("200601021504"))
 f.rediscache.ZUnionStore(opCtx, dest, keys, "SUM")

 // 4. 从合并后的ZSET取top N
 members, _ := f.rediscache.ZRevRange(opCtx, dest, start, stop)

 // 5. 根据ID去查视频详情
 videos, _ := f.repo.GetByIDs(ctx, ids)

 return videos
}

快照 key 是什么

快照 key 就是"合并结果的缓存"。

没有快照key：
 用户A请求 → 合并60个ZSET → 返回
 用户B请求 → 合并60个ZSET → 返回
 100个用户请求 → 合并100次 → 浪费！

有快照key：
 用户A请求 → 合并60个ZSET → 存到快照key → 返回
 用户B请求 → 发现快照key已存在 → 直接用 → 返回
 100个用户请求 → 只合并1次 → 省资源！

代码：

dest := f.rediscache.Key("hot:video:merge:1m:%s", asOf.Format("200601021504"))
exists, _ := f.rediscache.Exists(opCtx, dest)
if !exists {
 f.rediscache.ZUnionStore(opCtx, dest, keys, "SUM")
 f.rediscache.Expire(opCtx, dest, 2*time.Minute)
}
members, _ := f.rediscache.ZRevRange(opCtx, dest, start, stop)

快照 key 2 分钟后过期，下次请求重新合并，拿到最新数据。

关注流实现

核心代码

func (repo *FeedRepository) ListByFollowing(ctx context.Context, limit int, viewerAccountID uint, latestBefore time.Time) ([]*video.Video, error) {
 var videos []*video.Video
 query := repo.db.WithContext(ctx).Model(&video.Video{}).Order("create_time DESC")

 if viewerAccountID > 0 {
 // 子查询：找到我关注的所有人
 followingSubQuery := repo.db.WithContext(ctx).
 Model(&social.Social{}).
 Select("vlogger_id").
 Where("follower_id = ?", viewerAccountID)

 // 只查这些人发的视频
 query = query.Where("author_id IN (?)", followingSubQuery)
 }

 if !latestBefore.IsZero() {
 query = query.Where("create_time < ?", latestBefore)
 }

 query.Limit(limit).Find(&videos)
 return videos, nil
}

等价 SQL

SELECT * FROM videos
WHERE author_id IN (
 SELECT vlogger_id FROM socials WHERE follower_id = 123 -- 我关注的人
)
AND create_time < 1000 -- 游标
ORDER BY create_time DESC
LIMIT 10

子查询是什么

子查询就是"查询里的查询"，拆成两步理解：

第1步（子查询）：
 SELECT vlogger_id FROM socials WHERE follower_id = 123
 → 结果：[456, 789]（用户A关注的人）

第2步（主查询）：
 SELECT * FROM videos WHERE author_id IN (456, 789)
 → 结果：视频100（B发的）、视频200（C发的）

子查询是一次 SQL 搞定，数据库内部优化，比两条 SQL 更快。

流程

用户A关注了B和C
 ↓
子查询：从social表找到 [456, 789]
 ↓
主查询：从video表找 author_id 是 456 或 789 的视频
 ↓
返回：视频100（B发的）、视频200（C发的）
 ↓
用户D的视频300不会出现（A没关注D）

话题流实现

核心代码

func (repo *FeedRepository) ListByTag(ctx context.Context, tagName string, limit int) ([]*video.Video, error) {
 var videos []*video.Video
 err := repo.db.WithContext(ctx).Model(&video.Video{}).Table("videos").
 Joins("JOIN video_tags ON video_tags.video_id = videos.id").
 Joins("JOIN tags ON tags.id = video_tags.tag_id").
 Where("tags.name = ?", tagName).
 Order("videos.create_time desc").
 Limit(limit).
 Find(&videos).Error
 return videos, err
}

等价 SQL

SELECT videos.* FROM videos
JOIN video_tags ON video_tags.video_id = videos.id
JOIN tags ON tags.id = video_tags.tag_id
WHERE tags.name = 'Go语言'
ORDER BY videos.create_time DESC
LIMIT 10

三张表的关系

tags表：
┌────┬──────────┐
│ id │ name │
├────┼──────────┤
│ 1 │ Go语言 │
│ 2 │ Python │
└────┴──────────┘

video_tags表（多对多关联）：
┌──────────┬─────────┐
│ video_id │ tag_id │
├──────────┼─────────┤
│ 100 │ 1 │ ← 视频100有"Go语言"标签
│ 100 │ 2 │ ← 视频100也有"Python"标签
│ 200 │ 1 │ ← 视频200有"Go语言"标签
└──────────┴─────────┘

videos表：
┌────┬──────────┐
│ id │ title │
├────┼──────────┤
│ 100 │ Go入门 │
│ 200 │ 并发编程 │
└────┴──────────┘

查询流程

1. 从tags表找到"Go语言"的id = 1
2. 从video_tags表找到tag_id = 1的video_id = [100, 200]
3. 从videos表找到id = [100, 200]的视频

JOIN一次搞定。

三级缓存架构

这个项目在 Feed 查询里用了三级缓存：

请求 → L1本地缓存 → L2 Redis → L3 MySQL
 ↓ 快 ↓ 较快 ↓ 慢
 纳秒级 毫秒级 毫秒级

代码

type FeedService struct {
 localcache *cache.Cache // L1：本地缓存（进程内存，3秒过期）
 rediscache *rediscache.Client // L2：Redis缓存
 repo *FeedRepository // L3：MySQL
}

// L1：本地缓存
localcache: cache.New(3*time.Second, 5*time.Second)

// L2：Redis缓存（50ms超时）
cacheCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)

// L3：MySQL
videos, err := f.repo.GetByIDs(ctx, ids)

查询流程

请求来了
 ↓
查L1本地缓存（进程内存）
 ├── 命中 → 直接返回（最快）
 └── 没命中
 ↓
 查L2 Redis（50ms超时）
 ├── 命中 → 写回L1 → 返回
 └── 没命中
 ↓
 查L3 MySQL
 → 写回L2 Redis → 写回L1 → 返回

singleflight 防并发

什么是 singleflight

Go 内置的工具，保证同一个请求只执行一次，其他并发请求等着用结果。

场景

100个用户同时请求热榜
 ↓
没有singleflight：
 用户1：查DB → 返回
 用户2：查DB → 返回
 ...
 用户100：查DB → 返回
 DB被查了100次！

有singleflight：
 用户1：查DB → 返回
 用户2-100：等着 → 用户1查完后直接用结果
 DB只被查了1次！

代码

type FeedService struct {
 requestGroup singleflight.Group
}

v, err, _ := f.requestGroup.Do(sfKey, func() (interface{}, error) {
 return f.repo.GetByIDs(ctx, []uint{videoID})
})

第 1 个请求：执行 func，查 DB
其他请求：同一个 sfKey，等着，拿到同样的结果

sfKey 是什么

请求的唯一标识：

sfKey := f.rediscache.Key("sf:entity:%d", videoID)
// 结果："sf:entity:123"

同一个视频 ID 的请求，sfKey 相同，会共享结果。

和分布式锁的对比

	分布式锁	singleflight
作用范围	多台机器	单机内
实现	Redis	Go 内存
复杂度	高	低
场景	分布式系统	单机内防并发

面试要点总结

Q: 推模型和拉模型的区别？

A: 推是发视频时推送给粉丝，拉是刷视频时实时查 DB。推的读快写慢，拉的读慢写快。抖音用推拉结合。

Q: 游标分页和页码分页的区别？

A: 游标用 WHERE 条件过滤，不会重复；页码用 OFFSET 跳过，数据变化时可能重复。Feed 流用游标分页。

Q: 热榜怎么实现的？

A: ZSET 按分钟分窗口，点赞时热度+1，查询时合并 60 个窗口算总分，快照 key 缓存合并结果。

Q: 关注流怎么实现的？

A: 子查询找关注列表，再查这些人发的视频。一次 SQL 搞定。

Q: 话题流怎么实现的？

A: 三表 JOIN（videos + video_tags + tags），查某个标签下的视频。

Q: 什么是 singleflight？

A: Go 内置工具，保证同一个请求只执行一次，其他并发请求等着用结果。和分布式锁类似，但作用于单机内。

Q: 三级缓存是什么？

A: L1 本地缓存（进程内存）→ L2 Redis → L3 MySQL。先查快的，没命中再查慢的。

Go 项目反推：Feed 流系统实战——SSE 实时推送与分片上传

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——Feed 流设计，这一篇继续拆解 feedsystem_video_go 的两个关键能力：用 SSE 实时推送通知，以及用分片上传和断点续传处理大文件。

阶段6：SSE实时推送

SSE 是什么

SSE = Server-Sent Events，服务器主动给客户端推送消息。

就像外卖 APP 的订单状态：

你下单 → 服务器推送"商家已接单"
 → 服务器推送"骑手已取餐"
 → 服务器推送"骑手已送达"

客户端不用一直问"好了没？好了没？"，服务器有消息就主动推。

SSE vs WebSocket

	SSE	WebSocket
方向	服务器 → 客户端（单向）	双向
协议	HTTP	独立协议
复杂度	简单	复杂
场景	通知、状态更新、新闻推送	聊天、游戏、实时协作

这个项目用 SSE 推送通知（点赞、评论、关注），因为只需要服务器→客户端，不需要客户端→服务器。

为什么用 SSE 不用轮询

方案	做法	问题
轮询	客户端每隔几秒问一次"有新消息吗？"	浪费资源、实时性差、大部分请求返回空
SSE	服务器有消息就推，没有就等着	省资源、实时性高

项目里 SSE 用在哪

用户A给用户B的视频点赞
 ↓
LikeWorker处理点赞事件
 ↓
NotificationWorker收到MQ消息
 ↓
创建Notification记录，写入DB
 ↓
SSEHub.Push(userID, notification)
 ↓
用户B的浏览器收到推送，实时显示"xxx点赞了你的视频"

SSEHub 数据结构

type SSEHub struct {
 mu sync.RWMutex
 clients map[uint][]chan *Notification // userID -> 多个通知channel
 db *gorm.DB
}

数据结构：

map[uint][]chan *Notification

用户1 → [channel1, channel2] （可能多个设备）
用户2 → [channel3]
用户3 → [channel4, channel5, channel6] （三个设备）

代码实现

Notification 表结构

type Notification struct {
 ID uint
 RecipientID uint // 接收者ID
 SenderID uint // 发送者ID
 Type string // 通知类型：like、comment、follow
 TargetID uint // 目标ID（视频ID、用户ID）
 Content string // 通知内容
 IsRead bool // 是否已读
 CreatedAt time.Time
}

SSEHub 核心方法

// 订阅：用户连接时调用
func (h *SSEHub) Subscribe(userID uint) chan *Notification {
 ch := make(chan *Notification, 20) // 缓冲区20
 h.mu.Lock() // 写锁
 h.clients[userID] = append(h.clients[userID], ch)
 h.mu.Unlock()
 return ch
}

// 取消订阅：用户断开时调用
func (h *SSEHub) Unsubscribe(userID uint, ch chan *Notification) {
 h.mu.Lock() // 写锁
 defer h.mu.Unlock()
 chs := h.clients[userID]
 for i, c := range chs {
 if c == ch {
 chs = append(chs[:i], chs[i+1:]...)
 if len(chs) == 0 {
 delete(h.clients, userID)
 } else {
 h.clients[userID] = chs
 }
 close(c)
 return
 }
 }
}

// 推送：有新通知时调用
func (h *SSEHub) Push(userID uint, n *Notification) {
 h.mu.RLock() // 读锁
 defer h.mu.RUnlock()
 chs, ok := h.clients[userID]
 if !ok {
 return
 }
 for _, ch := range chs {
 select {
 case ch <- n: // 往channel里塞消息
 default: // 塞不进去就跳过（防阻塞）
 }
 }
}

SSEHandler - 处理 SSE 连接

func (h *SSEHub) SSEHandler(c *gin.Context) {
 userID, ok := sseAccountID(c)
 if !ok {
 c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid account"})
 return
 }

 // 设置SSE响应头
 c.Writer.Header().Set("Content-Type", "text/event-stream")
 c.Writer.Header().Set("Cache-Control", "no-cache")
 c.Writer.Header().Set("Connection", "keep-alive")
 c.Writer.WriteHeader(http.StatusOK)

 // 订阅通知
 ch := h.Subscribe(userID)
 defer h.Unsubscribe(userID, ch)

 ctx := c.Request.Context()
 flusher, _ := c.Writer.(http.Flusher)

 for {
 select {
 case <-ctx.Done(): // 客户端断开
 return
 case n, ok := <-ch: // 收到通知
 if !ok {
 return
 }
 b, _ := json.Marshal(n)
 fmt.Fprintf(c.Writer, "data: %s\n\n", b) // SSE格式
 if flusher != nil {
 flusher.Flush() // 立刻发送给客户端
 }
 case <-time.After(30 * time.Second): // 心跳
 fmt.Fprintf(c.Writer, ": keepalive\n\n")
 if flusher != nil {
 flusher.Flush()
 }
 }
 }
}

Push 为什么用 RLock 不用 Lock

什么是读写锁（RWMutex）

普通锁（Mutex）：同一时刻只能一个人进去，不管是读还是写。

读写锁（RWMutex）：

多个人可以同时读（RLock）
写的时候只能一个人进去，其他人不能读也不能写（Lock）

对比

操作	做什么	用什么锁
Push	读 map，往 channel 塞消息	RLock（读锁）
Subscribe	往 map 里加一个 channel	Lock（写锁）
Unsubscribe	从 map 里删一个 channel	Lock（写锁）

为什么 Push 能用 RLock

Push 只做两件事：

从 map 里找到用户的 channel（读）
往 channel 里塞消息（不改 map）

map 结构没变，所以多个 Push 可以同时进行。

一句话：读用 RLock（可以并发），写用 Lock（必须独占）。

场景对比

场景：100个用户同时收到通知

用普通锁（Mutex）：
 Push1加锁 → 推送 → 解锁
 Push2加锁 → 推送 → 解锁
 ... 一个一个来，慢

用读写锁（RWMutex）：
 Push1加RLock → 推送
 Push2加RLock → 推送
 Push3加RLock → 推送
 ... 100个同时推，快

心跳机制

什么是心跳

SSE 连接可能因为网络问题断开，客户端不知道。

解决方案：每 30 秒发一次空消息（keepalive），告诉客户端"我还活着"。

case <-time.After(30 * time.Second):
 fmt.Fprintf(c.Writer, ": keepalive\n\n")
 flusher.Flush()

为什么需要心跳

没有心跳：
 客户端连接服务器 → 网络抖动 → 连接断了
 客户端不知道断了 → 一直等 → 漏掉通知

有心跳：
 客户端连接服务器 → 每30秒收到keepalive
 30秒没收到 → 知道断了 → 重新连接

select 里的 default 防阻塞

for _, ch := range chs {
 select {
 case ch <- n: // 往channel里塞消息
 default: // 塞不进去就跳过
 }
}

channel 缓冲区满了（20条），塞不进去怎么办？

没有 default：阻塞等着，Push 卡住，其他用户的推送也卡住
有 default：直接跳过，不等，保证其他用户能正常收到推送

这是防阻塞设计：一个用户的消息堆积不影响其他用户。

NotificationWorker 处理流程

func (w *NotificationWorker) process(ctx context.Context, d amqp.Delivery) error {
 routingKey := d.RoutingKey

 var notif *Notification

 switch {
 case routingKey == "like.like":
 // 解析点赞事件
 // 查询视频作者ID
 // 如果是自己给自己点赞，不通知
 notif = &Notification{RecipientID: authorID, SenderID: evt.UserID, Type: "like", Content: "点赞了你的视频"}

 case routingKey == "comment.publish":
 // 解析评论事件
 // 查询视频作者ID
 // 如果是自己评论自己，不通知
 notif = &Notification{RecipientID: authorID, SenderID: evt.AuthorID, Type: "comment", Content: "评论了你的视频"}

 case routingKey == "social.follow":
 // 解析关注事件
 notif = &Notification{RecipientID: evt.VloggerID, SenderID: evt.FollowerID, Type: "follow", Content: "关注了你"}
 }

 if notif == nil {
 return nil
 }

 // 写入DB
 w.db.Create(notif)

 // 实时推送给用户
 w.hub.Push(notif.RecipientID, notif)

 return nil
}

接口设计

接口	方法	作用
`/stream`	GET	SSE 连接，实时接收通知
`/list`	POST	查询通知列表（最近 50 条）
`/markRead`	POST	标记已读
`/unreadCount`	POST	查询未读数量

阶段7：分片上传

为什么需要分片上传

视频文件可能很大（几十 MB 到 200MB），一次上传的问题：

一次上传100MB：
 网络抖动 → 上传到99%断了 → 重头再来
 用户体验极差

分片上传：

100MB文件，分成5MB一片，共20片
 第1片上传成功 ✓
 第2片上传成功 ✓
 ...
 第17片网络断了 ✗
 重新连接 → 只需要重新上传第17片，1-16不用重传

分片上传流程

整体流程

1. 客户端：计算文件MD5 → 调用Init接口 → 获得upload_id + 已上传分片列表
2. 客户端：逐片上传（跳过已上传的） → 每片带MD5校验
3. 客户端：全部上传完 → 调用Complete接口 → 服务器合并分片 → 返回视频URL

流程图

客户端 服务器
 | |
 |--- Init(文件名, 大小, MD5) ----------->|
 |<-- upload_id + 已上传列表 -------------|
 | |
 |--- UploadChunk(分片0, MD5) ----------->| 保存到临时目录
 |<-- chunk_index: 0 ----------------------|
 | |
 |--- UploadChunk(分片1, MD5) ----------->| 保存到临时目录
 |<-- chunk_index: 1 ----------------------|
 | |
 | ...（中间可能断线重连） |
 | |
 |--- Complete(upload_id) --------------->| 合并所有分片
 |<-- url: 视频地址 -----------------------|

核心数据结构

ChunkUploadSession（上传会话）

const ChunkSize = 5 << 20 // 5 MB

type ChunkUploadSession struct {
 UploadID string // 上传会话ID（随机生成）
 AccountID uint // 上传者ID
 Filename string // 原始文件名
 FileSize int64 // 文件总大小
 ChunkSize int64 // 每片大小（默认5MB）
 TotalChunks int // 总片数
 FileHash string // 整个文件的MD5
 UploadedBits []bool // 每片是否已上传（位图）
}

UploadedBits 是什么

UploadedBits: []bool{true, true, true, false, false}

这个数组表示：

分片 0：已上传 ✓
分片 1：已上传 ✓
分片 2：已上传 ✓
分片 3：未上传
分片 4：未上传

用 bool 数组而不是存已上传的分片列表，好处是：

判断某片是否已上传：O(1)，直接 index
判断是否全部上传完：遍历一次，O(n)

两个辅助方法

// 返回已上传的分片索引列表
func (s *ChunkUploadSession) UploadedChunks() []int {
 var indices []int
 for i, uploaded := range s.UploadedBits {
 if uploaded {
 indices = append(indices, i)
 }
 }
 return indices
}

// 判断是否全部上传完
func (s *ChunkUploadSession) IsComplete() bool {
 for _, b := range s.UploadedBits {
 if !b {
 return false
 }
 }
 return true
}

会话存在哪：Redis

上传会话存在 Redis，不是 MySQL，原因是：

存储	读写速度	持久化	适合存什么
Redis	微秒级	可配置过期	临时状态（上传进度）
MySQL	毫秒级	永久	持久数据（用户信息、视频记录）

上传会话是临时的（24 小时过期），用 Redis 更合适。

Redis Key 设计

// 上传会话
func (h *ChunkUploadHandler) sessionKey(uploadID string) string {
 return h.cache.Key("chunk_upload:%s", uploadID)
}

// 文件哈希 → upload_id 的映射（用于断点续传）
func (h *ChunkUploadHandler) hashKey(accountID uint, fileHash string) string {
 return h.cache.Key("chunk_upload_hash:%d:%s", accountID, fileHash)
}

两个 Key 的作用：

chunk_upload:<upload_id>：存完整的上传会话
chunk_upload_hash:<account_id>:<file_hash>：文件哈希到 upload_id 的映射，用于断点续传

四个接口详解

接口 1：InitChunkUpload（初始化上传）

func (h *ChunkUploadHandler) InitChunkUpload(c *gin.Context)

做了什么：

校验请求参数（文件名、大小、哈希、总片数）
检查文件大小是否超过 200MB 限制
断点续传检查：用文件哈希查 Redis，如果找到之前的会话，直接返回
创建新会话，存入 Redis
返回 upload_id + 已上传列表（新上传为空）

断点续传的实现：

// 检查是否有同文件的旧会话
hashKey := h.hashKey(accountID, req.FileHash)
existingID, err := h.cache.GetBytes(c.Request.Context(), hashKey)
if err == nil && len(existingID) > 0 {
 session, sessErr := h.getSession(c, string(existingID))
 if sessErr == nil {
 // 找到了！返回旧的upload_id和已上传列表
 c.JSON(http.StatusOK, gin.H{
 "upload_id": session.UploadID,
 "uploaded_chunks": session.UploadedChunks(),
 })
 return
 }
}

为什么用文件哈希做断点续传？

用户上传 video.mp4（100MB，MD5: abc123）
 → Init，upload_id: xxx，开始上传
 → 上传了15片，浏览器关闭

用户重新选择同一个 video.mp4
 → Init，参数里带同样的 file_hash: abc123
 → 服务器查Redis：chunk_upload_hash:<uid>:abc123 → xxx
 → 找到旧会话！返回已上传的15片
 → 客户端跳过这15片，只上传剩下的5片

接口 2：UploadChunk（上传单片）

func (h *ChunkUploadHandler) UploadChunk(c *gin.Context)

做了什么：

从表单获取 upload_id、chunk_index、chunk_hash
查 Redis 获取会话
校验：会话存在、是本人上传、分片索引合法
幂等检查：如果这片已经上传过，直接返回成功（不重复处理）
读取上传的文件内容，计算 MD5
哈希校验：对比客户端传的 chunk_hash 和实际计算的 MD5
保存分片到临时目录：.run/uploads/tmp/<upload_id>/<chunk_index>
更新 Redis 中的会话状态

幂等设计：

if session.UploadedBits[req.ChunkIndex] {
 c.JSON(http.StatusOK, gin.H{"chunk_index": req.ChunkIndex})
 return
}

如果分片已上传过，直接返回成功，不重复处理。这保证了重试的安全性。

哈希校验：

hash := md5.New()
io.Copy(hash, chunkFile)
actualHash := fmt.Sprintf("%x", hash.Sum(nil))

if actualHash != req.ChunkHash {
 c.JSON(http.StatusBadRequest, gin.H{"error": "chunk hash mismatch"})
 return
}

每个分片都有 MD5 校验，防止传输过程中数据损坏。

分片存储位置：

.run/uploads/tmp/
 └── <upload_id>/
 ├── 0 ← 第0片
 ├── 1 ← 第1片
 ├── 2 ← 第2片
 └── ...

接口 3：ChunkStatus（查询上传状态）

func (h *ChunkUploadHandler) ChunkStatus(c *gin.Context)

返回：upload_id + 已上传分片列表 + 总片数。

用于客户端轮询或断线后查询进度。

接口 4：CompleteChunkUpload（完成上传）

func (h *ChunkUploadHandler) CompleteChunkUpload(c *gin.Context)

做了什么：

校验会话、校验是否本人
检查是否所有分片都已上传（IsComplete()）
如果有未上传的分片，返回错误和缺失信息
合并分片：按顺序读取所有分片，写入最终文件
清理临时文件和 Redis 会话
返回视频 URL

合并过程：

tmpDir := filepath.Join(".run", "uploads", "tmp", req.UploadID)
for i := 0; i < session.TotalChunks; i++ {
 chunkPath := filepath.Join(tmpDir, fmt.Sprintf("%d", i))
 cf, _ := os.Open(chunkPath)
 io.Copy(finalFile, cf) // 按顺序拼接
 cf.Close()
}

最终文件位置：

.run/uploads/
 └── videos/
 └── <account_id>/
 └── <date>/
 └── <random>.mp4

清理：

// 删除临时分片
os.RemoveAll(tmpDir)

// 删除Redis会话
h.cache.Del(ctx, sessionKey)
h.cache.Del(ctx, hashKey)

安全设计

文件大小限制

const maxSize = 200 << 20 // 200MB
if req.FileSize > maxSize {
 c.JSON(http.StatusBadRequest, gin.H{"error": "file size exceeds 200MB limit"})
 return
}

权限校验

每个接口都检查：会话存在 + 是本人操作。

accountID, _ := jwt.GetAccountID(c)
if session.AccountID != accountID {
 c.JSON(http.StatusForbidden, gin.H{"error": "forbidden"})
 return
}

分片哈希校验

每个分片上传时都验证 MD5，防止数据损坏。

接口总结

接口	方法	作用
`/chunk/init`	POST	初始化上传，返回 upload_id
`/chunk/upload`	POST	上传单个分片
`/chunk/status`	POST	查询上传状态
`/chunk/complete`	POST	完成上传，合并分片

面试要点总结

Q: SSE 是什么？

A: Server-Sent Events，服务器主动推送消息给客户端，单向，基于 HTTP。场景：通知、状态更新、新闻推送。

Q: SSE 和 WebSocket 怎么选？

A: 只要服务器推用 SSE（简单），需要双向通信用 WebSocket（复杂）。这个项目用 SSE 推送通知，因为只需要服务器→客户端。

Q: 为什么用 SSE 不用轮询？

A: 轮询客户端每隔几秒问一次，浪费资源、实时性差。SSE 服务器有消息就推，省资源、实时性高。

Q: 心跳机制是什么？

A: 每 30 秒发一次空消息（keepalive），告诉客户端"我还活着"。客户端 30 秒没收到，知道连接断了，重新连接。

Q: Push 为什么用 RLock？

A: Push 只读 map 不改 map，用读锁可以多个 Push 并发。Subscribe/Unsubscribe 要改 map，用写锁必须独占。

Q: select 里的 default 是干什么的？

A: 防阻塞。channel 满了塞不进去就跳过，保证一个用户的消息堆积不影响其他用户。

Q: 为什么要分片上传？

A: 大文件一次上传，网络断了要重头来。分片后断点续传，只需重传失败的分片。

Q: 断点续传怎么实现？

A: 用文件 MD5 做唯一标识，Init 时查 Redis 是否有同文件的旧会话。有就返回已上传列表，客户端跳过这些分片。

Q: 上传会话存在哪？为什么？

A: 存 Redis，因为是临时状态（24 小时过期），读写快。MySQL 存持久数据。

Q: 怎么保证分片数据没损坏？

A: 每片上传时计算 MD5，和客户端传的 chunk_hash 对比，不匹配就拒绝。

Q: 分片重复上传怎么办？

A: 幂等设计——检查 UploadedBits，已上传的分片直接返回成功，不重复处理。

Q: 会话里 UploadedBits 是什么？

A: bool 数组，每个元素对应一个分片是否已上传。长度等于总片数，直接用下标访问，O(1) 判断某片是否已上传。

Go 项目反推：Feed 流系统实战——工程化

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——SSE 实时推送与分片上传，这一篇回到工程全景，梳理 feedsystem_video_go 的容器编排、配置管理、性能分析、持续集成与本地启动流程。

Docker Compose（容器编排）

什么是 Docker Compose

把所有服务打包成容器，一键启动。

没有 Docker Compose：

手动启动MySQL → 手动启动Redis → 手动启动RabbitMQ → 手动启动Backend → 手动启动Worker → 手动启动Frontend
每次都要敲6条命令，还要记住启动顺序

有 Docker Compose：

docker compose up -d
一键启动所有服务

这个项目的 Docker Compose

services:
 mysql: # 数据库
 redis: # 缓存
 rabbitmq: # 消息队列
 backend: # API进程
 worker: # Worker进程
 frontend: # 前端

相关文件：~/dev/projects/feedsystem_video_go/docker-compose.yml

depends_on + healthcheck（保证启动顺序）

depends_on 是什么

告诉 Docker：某个服务依赖其他服务，要等依赖的服务启动后才能启动自己。

backend:
 depends_on:
 mysql:
 condition: service_healthy  # MySQL健康了才启动backend
 redis:
 condition: service_healthy  # Redis健康了才启动backend
 rabbitmq:
 condition: service_healthy  # RabbitMQ健康了才启动backend

healthcheck 是什么

判断服务是否"健康"（真正能接受连接）。

mysql:
 healthcheck:
 test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uroot -p123456"]
 interval: 5s  # 每5秒检查一次
 timeout: 5s  # 超时5秒
 retries: 20 # 重试20次

MySQL 启动后，每 5 秒 ping 一次，连续 ping 成功才算"健康"。

为什么要 healthcheck

没有healthcheck：
 MySQL容器启动了 → backend立刻启动
 但MySQL还没初始化完 → backend连接失败 → 崩溃

有healthcheck：
 MySQL容器启动了 → 等MySQL真正能接受连接 → backend再启动

所有服务的 healthcheck

服务	healthcheck 测试	作用
mysql	`mysqladmin ping`	确认 MySQL 能接受连接
redis	`redis-cli ping`	确认 Redis 能接受连接
rabbitmq	`rabbitmq-diagnostics ping`	确认 RabbitMQ 能接受连接
backend	`wget http://127.0.0.1:8080/healthz`	确认 API 进程正常
worker	`pgrep worker`	确认 Worker 进程存在
frontend	`wget http://127.0.0.1:80/`	确认前端能访问

配置管理（优先级）

配置文件位置

~/dev/projects/feedsystem_video_go/backend/configs/
├── config.yaml # 本地开发用（MySQL端口3306）
├── config.compose-local.yaml # Docker Compose本地用（MySQL端口3307）
└── config.docker.yaml # Docker部署用（容器内部通信）

三个配置文件的区别

文件	MySQL 端口	用途
config.yaml	3306	本地开发，MySQL 装在本机
config.compose-local.yaml	3307	Docker Compose，MySQL 容器映射到 3307
config.docker.yaml	3306	Docker 部署，容器内部通信

配置加载优先级

环境变量 > .env文件 > YAML文件

来源	举例	优先级
环境变量	`export MYSQL_DATABASE=feedsystem`	最高
.env 文件	`MYSQL_DATABASE=feedsystem`	中
YAML 文件	`database.dbname: feedsystem`	最低

为什么要这样设计

开发环境：
 用YAML文件，配置写死在代码里，方便开发

Docker部署：
 用环境变量覆盖，不用改配置文件

 docker run -e MYSQL_DATABASE=feedsystem -e JWT_SECRET=*** ...

环境变量覆盖的好处

场景	做法
本地开发	用 YAML 文件的默认配置
Docker 部署	用环境变量覆盖数据库地址、密码等
生产环境	用环境变量覆盖，敏感信息不写进代码

启动时指定配置文件

# 本地开发
cd backend && CONFIG_PATH=configs/config.yaml go run ./cmd

# Docker Compose本地
cd backend && CONFIG_PATH=configs/config.compose-local.yaml go run ./cmd

API 进程和 Worker 进程为什么要分开

两个进程

cmd/
├── main.go # API进程（处理HTTP请求）
└── worker/
 └── main.go # Worker进程（消费MQ消息）

各自做什么

	API 进程	Worker 进程
职责	处理 HTTP 请求	消费 MQ 消息
入口	`go run ./cmd`	`go run ./cmd/worker`
启动方式	接收 HTTP 请求	订阅 MQ 队列

为什么要分开

1. 职责不同

API进程：用户发请求 → 处理 → 返回响应（要求快）
Worker进程：从MQ取消息 → 更新DB、推送通知（可以慢）

2. 独立扩展

场景：API扛不住了

没分开：只能整体加机器
分开后：只加API机器，Worker不动

场景：Worker扛不住了

分开后：只加Worker机器，API不动

3. 故障隔离

Worker崩了：不影响API，用户还能正常访问
API崩了：不影响Worker，后台任务还在处理

4. 资源分配不同

API进程：需要低延迟，分配更多CPU
Worker进程：可以容忍高延迟，分配更多内存

Docker Compose 里的配置

backend:
 build:
 dockerfile: backend/Dockerfile
 target: api  # 构建API镜像

worker:
 build:
 dockerfile: backend/Dockerfile
 target: worker  # 构建Worker镜像

同一个 Dockerfile，用不同的 target 构建两个镜像。

pprof（性能分析）

pprof 是什么

Go 内置的性能分析工具，帮你找出程序哪里慢、哪里吃内存。

能分析什么

类型	作用
CPU	哪个函数最耗 CPU
内存	哪个函数最耗内存
goroutine	有没有 goroutine 泄漏
阻塞	哪里卡住了

配置

observability:
 pprof:
 enabled: true
 api_addr: localhost:6060  # API进程的pprof端口
 worker_addr: localhost:6061  # Worker进程的pprof端口

启动后，访问 http://localhost:6060/debug/pprof/ 就能看到性能数据。

常用命令

# CPU分析（30秒）
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# 内存分析
go tool pprof http://localhost:6060/debug/pprof/heap

# goroutine分析
go tool pprof http://localhost:6060/debug/pprof/goroutine

场景举例

用户反馈：API响应慢

1. 用pprof抓CPU分析
2. 发现某个函数占了80%的CPU时间
3. 优化这个函数
4. 响应变快了

CI 流程（持续集成）

CI 是什么

代码推送到 GitHub 后，自动运行检查，确保代码质量。

这个项目的 CI

# .github/workflows/ci.yml
jobs:
 test:
 steps:
 - go vet ./...  # 静态检查
 - go test -race ./...  # 运行测试，检测数据竞争

go vet 是什么

静态分析，找出语法错误和可疑代码，不需要运行程序。

举例：
- 变量声明了但没用
- 格式化字符串参数不对
- 死代码（永远不会执行的代码）

go test -race 是什么

运行测试，同时检测数据竞争。

什么是数据竞争

多个 goroutine 同时读写同一个变量，没有加锁。

// 数据竞争的例子
var count int

go func() { count++ }() // goroutine1写
go func() { count++ }() // goroutine2写

// 两个goroutine同时写count，结果不确定

-race 怎么检测

go test -race ./...

如果发现数据竞争：
 WARNING: DATA RACE
 Write by goroutine 1
 Read by goroutine 2
 ...
 FAIL

CI 流程

开发者推送代码到GitHub
 ↓
GitHub Actions自动触发
 ↓
go vet ./... → 静态检查
 ↓
go test -race ./... → 运行测试 + 检测数据竞争
 ↓
全部通过 → 绿色 ✅
有失败 → 红色 ❌，不允许合并

好处

	没有 CI	有 CI
代码质量	靠人工 review	自动检查
数据竞争	上线后才发现	提交时就发现
合并代码	随便合并	检查通过才能合并

启动脚本（start.sh）

一键启动所有服务

./start.sh

相关文件：~/dev/projects/feedsystem_video_go/start.sh

脚本是什么语言写的

Bash（Shell 脚本），文件扩展名 .sh = Shell 脚本。

#!/usr/bin/env bash # 声明用bash解释器
set -euo pipefail # 遇到错误立刻停止

Bash 是 Linux/macOS 终端的脚本语言，用来自动化命令行操作。

脚本做的事

1. 启动Redis（如果没有运行）
2. 启动RabbitMQ（通过Docker Compose）
3. 启动Backend（go run ./cmd）
4. 启动Worker（go run ./cmd/worker）
5. 启动Frontend（npm run dev）
6. Ctrl+C停止所有服务

核心逻辑

# 启动Redis
start_redis() {
 redis-server --bind 127.0.0.1 --port 6379
}

# 启动RabbitMQ（通过Docker Compose）
start_rabbitmq_compose() {
 docker compose up -d rabbitmq
}

# 启动Backend
start_backend_bg() {
 cd backend && go run ./cmd &
}

# 启动Worker
start_worker_bg() {
 cd backend && go run ./cmd/worker &
}

# 启动Frontend
start_frontend_bg() {
 cd frontend && npm run dev &
}

# Ctrl+C停止所有服务
trap cleanup INT TERM EXIT
cleanup() {
 kill $BACKEND_PID
 kill $WORKER_PID
 kill $FRONTEND_PID
 docker compose stop
}

环境变量控制

START_REDIS=1 # 是否启动Redis
START_RABBITMQ=1 # 是否启动RabbitMQ
START_BACKEND=1 # 是否启动Backend
START_WORKER=1 # 是否启动Worker
START_FRONTEND=1 # 是否启动Frontend

可以按需启动：

# 只启动Backend和Worker
START_FRONTEND=0 ./start.sh

面试要点总结

Q: Docker Compose 怎么保证启动顺序？

A: depends_on + healthcheck，服务健康了才启动下一个。

Q: 配置优先级？

A: 环境变量 > .env 文件 > YAML 文件。

Q: API 和 Worker 为什么要分开？

A: 职责不同、独立扩展、故障隔离、资源分配不同。

Q: pprof 能分析什么？

A: CPU、内存、goroutine、阻塞。

Q: CI 做了什么？

A: go vet 静态检查 + go test -race 检测数据竞争。

Q: 什么是数据竞争？

A: 多个 goroutine 同时读写同一个变量，没有加锁。用 go test -race 检测。

Q: 为什么要用 healthcheck？

A: 确保服务真正能接受连接，而不是只启动了容器。

Go 项目反推：Feed 流系统实战——消息队列与异步架构

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——Redis 缓存设计，这一篇继续反推 feedsystem_video_go 的消息队列与异步架构，梳理 RabbitMQ 的消息路由、消费重试、降级策略、Outbox 模式和死信队列。

什么是消息队列（MQ）

想象一个餐厅：

没有 MQ：顾客点餐 → 厨师做完一个才能做下一个 → 顾客等着
有 MQ：顾客点餐 → 写在小票上放窗口 → 厨师按顺序做 → 做好了喊号

消息队列就是那个"窗口"，消息就是"小票"。

为什么需要消息队列

用户点赞后要做的事：

用户点赞 → 更新Like表 → 更新Video点赞数 → 更新热度 → 推送通知 → 返回成功

没有 MQ 的问题：

用户等太久（每个操作都要时间）
任何一个失败，整个流程卡住
高并发时 DB 扛不住

有了 MQ：

用户点赞 → 更新Like表 → 发一条"点赞消息"到MQ → 立刻返回成功
 ↓
 Worker从MQ取消息 → 更新点赞数 → 更新热度 → 推送通知

好处：

用户不用等所有操作完成，体验快
点赞服务和热度计算服务解耦，改一个不影响另一个
高并发时消息排队，DB 不会被打垮

MQ 的三个核心概念

概念	比喻	作用
Exchange	邮局	接收消息，根据规则分发
Queue	邮箱	存储消息，等 Worker 来取
Routing Key	地址	消息的"目的地"，Exchange 根据它决定放哪个 Queue

流程：

生产者（点赞服务） → 发消息到Exchange → Exchange根据Routing Key → 放到Queue → Worker从Queue取消息消费

三种 Exchange 类型

类型	规则	举例
Direct	Routing Key 完全匹配	发到"like.like"，只有绑定了"like.like"的 Queue 才能收到
Topic	支持通配符（* 和 #）	发到"like.*"，能匹配"like.like"、“like.unlike”
Fanout	广播，忽略 Routing Key	发到所有绑定的 Queue，每个 Queue 都能收到

这个项目用的是 Topic Exchange。

项目里的 6 种 MQ

Exchange	Routing Key	用途
like.events	like.like / like.unlike	点赞/取消点赞
comment.events	comment.publish / comment.delete	评论/删除评论
social.events	social.follow / social.unfollow	关注/取关
video.popularity.events	video.popularity.update	热度更新
video.timeline.events	video.timeline.publish	视频发布
dlx.events	#	死信队列（重试/告警）

代码实现

MQ 相关文件

backend/internal/middleware/rabbitmq/
├── rabbitMQ.go # MQ基础封装（连接、Channel、DeclareTopic、PublishJSON）
├── dlx.go # 死信队列声明和重试计数
├── likeMQ.go # 点赞MQ
├── commentMQ.go # 评论MQ
├── socialMQ.go # 关注MQ
├── popularityMQ.go # 热度MQ
└── timelineMQ.go # Feed流MQ（Outbox模式）

Worker 相关文件

backend/internal/worker/
├── likeworker.go # 点赞Worker
├── commentworker.go # 评论Worker
├── socialworker.go # 关注Worker
├── popularityworker.go # 热度Worker
├── outboxworker.go # Outbox定时任务
├── notificationworker.go # 通知Worker
└── ssehub.go # SSE推送Hub

消息生产（发消息）

rabbitMQ.go - PublishJSON

func PublishJSON(ctx context.Context, ch *amqp.Channel, exchange string, routingKey string, payload any) error {
 b, _ := json.Marshal(payload) // 第1步：把数据变成JSON
 return ch.PublishWithContext(ctx, exchange, routingKey, false, false, amqp.Publishing{
 ContentType: "application/json", // 第2步：告诉MQ这是JSON格式
 DeliveryMode: amqp.Persistent, // 第3步：消息持久化
 Body: b, // 第4步：消息内容
 })
}

逐行解释：

json.Marshal(payload)：把 Go 结构体变成 JSON 字节
ch.PublishWithContext(...)：调用 MQ 客户端，发一条消息
exchange：发到哪个 Exchange（邮局）
routingKey：消息地址（like.like）
amqp.Persistent：消息存到磁盘，MQ 重启不丢
Body: b：消息内容

消息长什么样

{
 "video_id": 123,
 "account_id": 456,
 "event_type": "like.like",
 "timestamp": "2026-07-28T14:30:00Z"
}

就是一个 JSON，告诉 Worker"用户 456 给视频 123 点了赞"。

消息消费（Worker 处理）

likeworker.go - Run

func (w *LikeWorker) Run(ctx context.Context) error {
 deliveries, err := w.ch.Consume(w.queue, "", false, false, false, false, nil)

 for {
 select {
 case <-ctx.Done():
 return ctx.Err()
 case d, ok := <-deliveries:
 if !ok {
 return errors.New("deliveries channel closed")
 }
 w.handleDelivery(ctx, d)
 }
 }
}

逐行解释：

w.ch.Consume(w.queue, ...)：从 Queue 订阅消息，返回一个 channel
for { select { ... } }：循环读消息，有消息来就处理
w.handleDelivery(ctx, d)：调用处理函数，执行业务逻辑

handleDelivery - 重试逻辑

func (w *LikeWorker) handleDelivery(ctx context.Context, d amqp.Delivery) {
 const maxRetries = 3
 for i := 0; i <= maxRetries; i++ {
 if err := w.process(ctx, d.Body); err != nil {
 if i >= maxRetries {
 // 超过3次，放弃，Ack删除消息
 log.Printf("like worker: 重试 %d 次后仍失败, 丢弃", maxRetries)
 _ = d.Ack(false)
 return
 }
 // 等一下再重试（指数退避）
 wait := time.Duration(1<<uint(i)) * time.Second // 1s, 2s, 4s
 log.Printf("like worker: 处理失败, %v 后重试 (%d/%d)", wait, i+1, maxRetries)
 time.Sleep(wait)
 continue
 }
 // 成功，Ack删除消息
 _ = d.Ack(false)
 return
 }
}

重试流程：

第1次处理 → 失败 → 等1秒
第2次处理 → 失败 → 等2秒
第3次处理 → 失败 → 等4秒
第4次处理 → 失败 → 放弃，Ack删除消息

指数退避（1s → 2s → 4s）

1<<uint(i) 是位运算：

i=0: 1«0 = 1秒
i=1: 1«1 = 2秒
i=2: 1«2 = 4秒

为什么要等这么久？避免疯狂重试打垮服务器。

为什么失败了还 Ack？

不 Ack 的话，消息会一直留在 Queue 里，Worker 会一直重试，卡住后面的消息。Ack 后消息从 Queue 删除，避免阻塞。

MQ 发布失败的降级策略

场景：用户点赞成功，DB 写入了，但发 MQ 消息失败了。

如果直接忽略：热度不会更新，点赞数据和热度不一致。

fallback 直写

func (s *LikeService) publishLikeEvent(ctx context.Context, videoID, accountID uint, routingKey string) {
 event := LikeEvent{VideoID: videoID, AccountID: accountID}

 err := rabbitmq.PublishJSON(ctx, s.ch, "like.events", routingKey, event)
 if err != nil {
 // MQ发送失败，降级：直接更新热度
 go s.popularityWorker.HandleLikeEvent(event)
 }
}

意思：

MQ 能用 → 走 MQ 异步处理
MQ 挂了 → 直接调 Worker 的处理函数，同步处理

为什么不用重试？如果 MQ 挂了，重试大概率还是失败，用户要等很久。直接降级：虽然绕过了 MQ，但保证功能正常，用户体验不受影响。

Outbox 模式

什么是 Outbox 模式

发视频时用的模式。

场景：用户发视频 → 更新 DB → 发 MQ 消息

问题：如果 DB 更新成功，MQ 发送失败，视频发布了但 Feed 流里没有。

为什么不能放在一个事务里？DB 和 MQ 是两个系统，没法用一个事务包起来。

Outbox 的解法

把 MQ 消息先存到数据库里，用数据库事务保证一致性：

数据库事务（保证原子性）：
 INSERT INTO videos (title, play_url, ...) VALUES (...)
 INSERT INTO outbox_msgs (video_id, status) VALUES (xxx, 'pending')
 COMMIT

两步在同一个 DB 事务里，要么都成功，要么都失败。

然后用定时任务把消息发出去：

OutboxPoller（每秒运行一次）：

 查询：SELECT * FROM outbox_msgs WHERE status = 'pending'

 对于每条消息：
 发MQ消息
 更新：UPDATE outbox_msgs SET status = 'sent' WHERE id = xxx

OutboxMsg 表结构

type OutboxMsg struct {
 ID uint
 VideoID uint
 EventType string
 CreateTime time.Time
 Status string // "pending" 或 "sent"
}

完整流程

00:00 用户发视频
 → 写Video表 + 写OutboxMsg表（同一个事务，保证原子）

00:01 OutboxPoller扫到这条消息
 → 发MQ消息成功
 → 标记为sent

00:02 Worker收到MQ消息
 → 更新Feed流

为什么这样能保证消息不丢？

消息先存在 DB 里，和业务数据在同一个事务
定时任务保证最终会发出去
即使 MQ 暂时挂了，消息还在 DB 里，等 MQ 恢复了再发

回滚只发生在 DB 层面

数据库事务：
 INSERT INTO videos ... → 成功
 INSERT INTO outbox_msgs ... → 失败
 ROLLBACK → 两个都撤销

MQ 发送失败不回滚：

数据库事务：COMMIT（消息已经存到outbox_msgs表了）

OutboxPoller：
 发MQ消息 → 失败（MQ挂了）

 → 不回滚！消息还在outbox_msgs表里
 → 等MQ恢复了，下次扫描再发

为什么发视频用 Outbox，点赞不用？

场景	方案	原因
点赞	直接发 MQ + fallback	点赞失败可以重试，用户能接受
发视频	Outbox 模式	视频必须进 Feed 流，不能丢

视频发布是关键业务，不能丢消息，所以用 Outbox 保证"至少发一次"。

死信队列（DLX）

什么是死信队列

消息"死了"（消费失败），放到一个专门的队列里等处理。

就像快递派送失败：

正常流程：快递 → 送到你家 → 签收

派送失败：快递 → 送到你家 → 没人签收 → 退回快递站（死信队列）
 → 重新派送（重试）
 → 联系收件人（告警）

消息为什么会"死"

原因	举例
业务逻辑报错	热度计算除零了
消费超时	Worker 处理太久，MQ 等不及了
拒绝消息	代码里主动 reject

正常消费流程

Worker从Queue取消息
 ↓
处理成功 → msg.Ack() → MQ删除消息

消费失败了

Worker从Queue取消息
 ↓
处理失败 → msg.Nack() 或 超时
 ↓
MQ把消息放到死信队列（DLX）
 ↓
死信Worker处理：
 - 记录日志
 - 重试（最多N次）
 - 超过重试次数 → 告警/人工处理

dlx.go - DeclareDLX

const DLXExchange = "dlx.events"
const MaxRetryCount = 3

func DeclareDLX(ch *amqp.Channel, queueName string) error {
 // 1. 声明死信Exchange
 ch.ExchangeDeclare(DLXExchange, "topic", true, false, false, false, nil)

 // 2. 声明死信Queue（名字是 原Queue名 + ".dlx"）
 dlxQueue := queueName + ".dlx"
 ch.QueueDeclare(dlxQueue, true, false, false, false, nil)

 // 3. 绑定：# 匹配所有Routing Key
 ch.QueueBind(dlxQueue, "#", DLXExchange, false, nil)
}

like.events 的死信队列叫 like.events.dlx
comment.events 的死信队列叫 comment.events.dlx

GetRetryCount - 获取重试次数

func GetRetryCount(d amqp.Delivery) int {
 deaths, ok := d.Headers["x-death"].([]interface{})
 if !ok || len(deaths) == 0 {
 return 0
 }
 death, ok := deaths[0].(amqp.Table)
 if !ok {
 return 0
 }
 count, ok := death["count"].(int64)
 if !ok {
 return 0
 }
 return int(count)
}

MQ 会自动在消息头里记录"这条消息死了几次"，从 x-death 里取出来。

正常 Queue 声明时绑定 DLX

func DeclareTopic(ch *amqp.Channel, exchange string, queue string, bindingKey string) error {
 // 声明Exchange
 ch.ExchangeDeclare(exchange, "topic", true, false, false, false, nil)

 // 声明Queue，绑定死信Exchange
 q, err := ch.QueueDeclare(queue, true, false, false, false,
 amqp.Table{"x-dead-letter-exchange": DLXExchange})

 // 绑定：Queue订阅Exchange的消息
 ch.QueueBind(q.Name, bindingKey, exchange, false, nil)
}

x-dead-letter-exchange：告诉 MQ，这个 Queue 的消息如果"死了"，发到 DLXExchange。

完整流程举例

正常流程：
 点赞 → like.events Queue → LikeWorker消费 → 成功 → Ack

失败流程：
 点赞 → like.events Queue → LikeWorker消费 → 失败 → Nack
 ↓
 like.events.dlx Queue（死信队列）
 ↓
 死信Worker处理（重试/告警）

API 进程和 Worker 进程为什么要分开

cmd/
├── main.go # API进程（处理HTTP请求）
└── worker/
 └── main.go # Worker进程（消费MQ消息）

分开的原因：

职责不同：API 处理请求，Worker 处理后台任务
独立扩展：API 扛不住加 API 机器，Worker 扛不住加 Worker 机器
故障隔离：Worker 崩了不影响 API，API 崩了不影响 Worker
资源分配：API 需要低延迟，Worker 可以容忍高延迟

ch.Qos(50, 0, false) - 预取数量控制

ch.Qos(50, 0, false)

50：每次最多取 50 条消息
0：不限制消息大小
false：只对当前 Channel 生效

为什么要控制预取数量？

太多：Worker 内存爆了
太少：Worker 闲着没事干
50：平衡点，Worker 处理完一批再取下一批

面试要点总结

Q: 为什么用 MQ？

A: 削峰（高并发时消息排队）、解耦（点赞服务和热度计算独立）、异步（用户不用等所有操作完成）。

Q: MQ 发布失败了怎么办？

A: 降级策略，直接调 Worker 的处理函数同步处理。点赞用 fallback 直写，发视频用 Outbox 模式保证消息不丢。

Q: Outbox 模式是什么？

A: 把 MQ 消息先存到数据库里，用 DB 事务保证一致性。定时任务扫描 outbox_msgs 表，发 MQ 消息，标记已发送。

Q: 死信队列怎么用的？

A: 消息消费失败时，MQ 自动把消息放到死信队列。Worker 里有重试逻辑，最多重试 3 次，指数退避（1s→2s→4s），超过 3 次放弃。

Q: API 进程和 Worker 进程为什么要分开？

A: 职责不同、独立扩展、故障隔离、资源分配不同。

Q: 什么是指数退避？

A: 重试间隔按 2 的幂次增长（1s→2s→4s），避免疯狂重试打垮服务器。

Q: 三种 Exchange 的区别？

A: Direct 精确匹配，Topic 支持通配符，Fanout 广播到所有 Queue。

Q: 为什么点赞用 fallback，发视频用 Outbox？

A: 点赞失败用户能接受重试，视频发布是关键业务不能丢消息。Outbox 保证"至少发一次"。

Go 项目反推：Feed 流系统实战——Redis 缓存设计

Tue, 28 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——数据库与 GORM，这一篇继续反推 feedsystem_video_go 的 Redis 设计，梳理缓存读写、一致性与高并发防护，以及 Lua 限流和 ZSET 热榜的实现。

项目里 Redis 的 7 种用途

#	用途	数据结构	Key模式
1	JWT Token 缓存	String	`account:<id>`
2	Refresh Token 缓存	String	`account:<id>:refresh` / `refresh:<token>`
3	视频详情缓存	String(JSON)	`video:detail:id=<id>`
4	视频实体缓存	String(JSON)	`video:entity:<id>`
5	热榜	ZSET	`hot:video:1m:<时间窗口>`
6	分片上传会话	String(JSON)	`chunk_upload:<upload_id>`
7	接口限流	String(计数器)	`ratelimit:<prefix>:<subject>`

1. 缓存读取流程（video_service.go 的 GetDetail）

func (vs *VideoService) GetDetail(ctx context.Context, id uint) (*Video, error) {
 cacheKey := vs.cache.Key("video:detail:id=%d", id)

 // 第一步：查缓存（50ms 超时）
 getCached := func() (*Video, bool) {
 opCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
 defer cancel()

 b, err := vs.cache.GetBytes(opCtx, cacheKey)
 if err != nil {
 return nil, false // 缓存没命中
 }
 var cached Video
 if err := json.Unmarshal(b, &cached); err != nil {
 return nil, false // 数据损坏
 }
 return &cached, true // 缓存命中
 }

 // 尝试读缓存
 if v, ok := getCached(); ok {
 return v, nil // 命中，直接返回
 }

 // 缓存没命中，查数据库...
}

为什么缓存读取要设 50ms 超时？

50ms 超时不是判断"没命中"，而是防止 Redis 卡住的降级策略：

缓存没命中：Redis 快速返回"key 不存在"，几毫秒就完成
Redis 卡住：网络抖动、Redis 内部阻塞、连接池耗尽，可能卡几秒

没有超时：Redis 卡住 → 请求一直等着 → 用户体验很差有 50ms 超时：Redis 超过 50ms 没响应 → 放弃缓存 → 直接查数据库

为什么不设更短的超时，比如 5ms？

Redis 正常操作本身需要几毫秒，设 5ms 正常情况都可能超时，缓存形同虚设。50ms 是平衡点：覆盖正常操作 + 轻微网络波动，同时不会让用户等太久。

2. 缓存写入

setCached := func(video *Video) {
 b, err := json.Marshal(video)
 if err != nil {
 return
 }
 opCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
 defer cancel()
 _ = vs.cache.SetBytes(opCtx, cacheKey, b, vs.cacheTTL)
}

为什么缓存要设过期时间（TTL）？

TTL = Time To Live，缓存的"保质期"。

主要原因：数据一致性

09:00 缓存存了视频标题"今天天气真好"
09:05 作者把标题改成"今天下雨了"
 → 数据库更新了，但缓存还是旧的
09:06 用户查这个视频 → 从缓存读到"今天天气真好"
 → 看到的是过期数据

没有 TTL：缓存永远是旧数据，用户看到的和数据库不一致有了 TTL（比如 10 分钟）：最多 10 分钟后缓存自动过期，下次请求加载最新数据

这是用时间换一致性：允许短暂不一致，但最终会一致。

次要原因：缓存空间有限

缓存满了需要淘汰旧数据，TTL 帮助自动清理。

3. 缓存删除（主动失效）

为什么不等 TTL 过期，要主动删缓存？

看 video_service.go 删视频时：

func (vs *VideoService) DeleteVideo(ctx context.Context, id uint) error {
 // 先删数据库
 if err := vs.repo.DeleteVideo(ctx, id); err != nil {
 return err
 }
 // 再删缓存
 if vs.cache != nil {
 cacheKey := vs.cache.Key("video:detail:id=%d", id)
 _ = vs.cache.Del(context.Background(), cacheKey)
 }
 return nil
}

DB 更新后立刻删缓存，下次请求来了缓存没命中，从数据库加载最新数据。

4. 缓存和 DB 的一致性策略

两种方案对比

方案	做法	风险
先删缓存，再更新 DB	删缓存 → 写 DB	删完缓存、还没写 DB 时，另一个请求读 DB 旧数据写入缓存
先更新 DB，再删缓存	写 DB → 删缓存	写完 DB、还没删缓存时，另一个请求读到旧缓存

为什么"先更新 DB 再删缓存"更安全？

方案 1：先删缓存，再更新 DB

00:00 请求A：删缓存
00:01 请求B：查视频 → 缓存没命中 → 从DB读到旧数据 → 写入缓存
00:02 请求A：更新DB为新数据

结果：DB是新数据，缓存里是旧数据（脏数据）

发生概率不低，因为"删缓存"到"更新 DB"之间可能有几百毫秒（DB 写入比 Redis 慢）。

方案 2：先更新 DB，再删缓存

00:00 请求A：更新DB为新数据
00:01 请求B：查视频 → 从缓存读到旧数据（概率小）
00:02 请求A：删缓存

结果：即使请求B读到旧缓存，00:02缓存就被删了

出问题窗口极小：必须在"更新 DB"和"删缓存"之间，恰好有另一个请求来读。

共同风险点：删缓存失败了怎么办？

00:00 更新DB成功 → DB是新数据
00:01 删缓存失败（网络抖动、Redis挂了）
 → 缓存还是旧数据

解决方案：靠 TTL 兜底

代码里删缓存都用了 _ = 忽略错误：

_ = vs.cache.Del(context.Background(), cacheKey)

即使删缓存失败，最多等 TTL 过期（比如 10 分钟），缓存自动失效，下次请求从 DB 加载新数据。

这是最终一致性：允许短暂不一致，但最终会一致。

5. 缓存穿透/击穿/雪崩

三个概念的区别

问题	现象	危害
缓存穿透	查询不存在的数据，缓存永远没命中	每次请求都打到 DB
缓存击穿	热点 key 过期，大量请求同时打到 DB	DB 瞬间压力暴增
缓存雪崩	大量 key 同时过期	DB 瞬间压力暴增

缓存击穿的解法（这个项目用的）

场景：一个热门视频的缓存过期了，100 个用户同时请求

// 缓存没命中，尝试获取分布式锁
lockKey := "lock:" + cacheKey
token, locked, lockErr := vs.cache.Lock(lockCtx, lockKey, 2*time.Second)

if lockErr == nil && locked {
 // 拿到锁：去查DB，回填缓存
 defer func() { _ = vs.cache.Unlock(context.Background(), lockKey, token) }()

 video, err := vs.repo.GetByID(ctx, id)
 if err != nil {
 return nil, err
 }
 setCached(video)
 return video, nil
}

// 没拿到锁：等待别人回填缓存（最多100ms）
for i := 0; i < 5; i++ {
 time.Sleep(20 * time.Millisecond)
 if v, ok := getCached(); ok {
 return v, nil // 别人已经回填了，直接用
 }
}

// 降级：直接查DB
video, err := vs.repo.GetByID(ctx, id)

核心逻辑：让一个请求干活，其他请求等着用结果

❌ 没有锁的击穿场景：
100个请求同时来 → 缓存没命中 → 100个都去查DB → DB压力x100

✅ 有锁的保护：
100个请求同时来 → 缓存没命中
 ↓
请求1：拿到锁 → 查DB → 写缓存 → 返回
请求2-100：没拿到锁 → 等20ms → 查缓存 → 命中 → 返回

时序示例（DB 查询 15ms）：

00:00 请求1拿到锁，开始查DB（耗时15ms）
 请求2-100没拿到锁，开始sleep 20ms
00:15 请求1查完DB，写入缓存
00:20 请求2-100醒来，查缓存 → 命中！

降级策略（DB 查询很慢时）：

请求 2-100 最多等 100ms（5次x20ms），如果请求 1 还没完成，降级去查 DB。

但这种情况很少见，DB 查询通常几毫秒到几十毫秒。

缓存穿透的解法（这个项目没做）

缓存穿透：查询不存在的数据，比如 GET /video/999999999，数据库里没有，每次请求都打到 DB。

方案	做法
缓存空值	查 DB 没结果，也写入缓存（value=""），设短 TTL
布隆过滤器	在缓存前加一层，快速判断 key 是否存在

项目为什么没做：视频 ID 通过 Feed 流返回，不存在"查不存在 ID"的正常场景。接口有限流保护，攻击成本高。

缓存雪崩的解法（这个项目没做）

缓存雪崩：大量 key 同时过期，DB 瞬间压力暴增。

方案	做法
随机 TTL	给缓存 TTL 加随机值，避免同时过期
多级缓存	L1 本地缓存 + L2 Redis 缓存
永不过期 + 异步更新	缓存不设 TTL，由后台任务定期更新

项目用的是固定 TTL，没做随机化，业务量可控。

6. 限流中间件（ratelimit.go）

限流是什么？

防止用户发太多请求打垮服务器。像银行取号机：每分钟最多服务 100 个人，第 101 个人来了告诉他"请稍后再来"。

限流中间件是什么？

Gin 中间件，所有请求都要经过它：

用户请求 → 限流中间件检查 → 通过 → handler处理 → 返回
 ↓
 超限 → 直接返回429 "too many requests"

限流实现原理

func Limit(cache *rediscache.Client, keyPrefix string, maxRequests int64, window time.Duration, keyFunc KeyFunc) gin.HandlerFunc {
 return func(c *gin.Context) {
 subject, ok := keyFunc(c)
 key := buildKey(keyPrefix, subject)

 count, err := cache.IncrementWithExpire(c.Request.Context(), key, window)
 if err != nil {
 c.Next()
 return
 }
 if count > maxRequests {
 c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{"error": "too many requests"})
 return
 }
 c.Next()
 }
}

IncrementWithExpire 的 Lua 脚本

local count = redis.call("INCR", KEYS[1])
if count == 1 then
 redis.call("PEXPIRE", KEYS[1], ARGV[1])
end
return count

限流流程（1 分钟内最多 100 次）：

00:00.000 请求1来 → INCR → count=1
 因为count==1，是第一个请求
 → PEXPIRE设60000毫秒（60秒）过期

00:00.001 请求2来 → INCR → count=2
 count!=1，不设过期（沿用之前的）

...

00:00.500 请求100来 → INCR → count=100
 → 通过（100 <= 100）

00:00.600 请求101来 → INCR → count=101
 → 拒绝！（101 > 100）
 → 返回429 "too many requests"

01:00.000 key自动过期，Redis删除这个key
 计数器归零

01:00.001 请求来 → INCR → count=1（重新开始计数）
 → PEXPIRE重新设60秒
 → 通过

为什么用 Lua 脚本？

原子执行 = 两条命令之间不会有其他命令插队

没有 Lua 脚本（可能被插队）：

00:00 你的程序：INCR key → count=1
00:01 另一个程序：INCR key → count=2
00:02 你的程序：EXPIRE key 60秒
00:03 另一个程序：EXPIRE key 60秒

你的 INCR 和 EXPIRE 之间，被别人插队了。

有 Lua 脚本（不会插队）：

00:00 你的程序：开始执行Lua脚本
 INCR key → count=1
 EXPIRE key 60秒
00:01 Lua脚本执行完，其他程序才能执行

注意：原子执行 ≠ 回滚，原子执行 = 不插队

如果 INCR 成功了，EXPIRE 失败了，INCR 的结果不会撤销。

为什么需要原子执行？

如果分开写：

count = redis.INCR(key) // count=1
// 这里程序崩了，EXPIRE没执行
redis.EXPIRE(key, 60秒) // 没执行到

结果：key 永远不过期，计数永远不会归零，限流永久生效。

Lua 脚本保证 INCR 和 EXPIRE 一起执行，不会出现"只执行了一半"的情况。

EXPIRE 和 PEXPIRE

EXPIRE：单位是秒
PEXPIRE：单位是毫秒

限流的 key 设计

func buildKey(keyPrefix, subject string) string {
 return fmt.Sprintf("feedsystem:ratelimit:%s:%s", keyPrefix, strings.TrimSpace(subject))
}

两种维度：

KeyByIP：按 IP 限流，防止单 IP 攻击
KeyByAccount：按用户 ID 限流，防止单用户刷接口

7. ZSET 热榜（popularity_cache.go）

ZSET 是什么？

Redis 的有序集合，每个元素有一个分数，自动按分数排序。

ZSET "热榜"
┌─────────┬─────────┐
│ 元素 │ 分数 │
├─────────┼─────────┤
│ video_5 │ 1000 │ ← 最热
│ video_2 │ 800 │
│ video_8 │ 500 │
│ video_1 │ 100 │ ← 最冷
└─────────┴─────────┘

热榜更新代码

func UpdatePopularityCache(ctx context.Context, cache *rediscache.Client, id uint, change int64) {
 // 删掉旧缓存
 _ = cache.Del(context.Background(), cache.Key("video:detail:id=%d", id))
 _ = cache.Del(context.Background(), cache.Key("video:entity:%d", id))

 // 写入热榜
 now := time.Now().UTC().Truncate(time.Minute) // 当前时间，精确到分钟
 windowKey := cache.Key("hot:video:1m:%s", now.Format("200601021504")) // 热榜key
 member := strconv.FormatUint(uint64(id), 10) // 视频ID

 _ = cache.ZincrBy(opCtx, windowKey, member, float64(change)) // 热度+change
 _ = cache.Expire(opCtx, windowKey, 2*time.Hour) // 2小时后过期
}

滑动窗口设计

热榜 key 是 hot:video:1m:202607281430，意思是"2026 年 7 月 28 日 14:30 这一分钟的热榜"。

00:00 video_5被点赞 → hot:video:1m:202607281430 → video_5分数+1
00:30 video_5又被点赞 → hot:video:1m:202607281430 → video_5分数+1
01:00 新的一分钟 → hot:video:1m:202607281431

每分钟一个 ZSET，2 小时后自动过期。

为什么要按分钟分窗口？

如果用一个大的 ZSET（不分窗口）：

所有点赞都写到同一个key "hot:video"

1月1日：video_5被点赞1000次，分数=1000，排第一
1月2日：video_8被点赞500次，分数=500
1月3日：video_5被点赞0次，但分数还是1000，还是排第一

问题：旧视频的热度永远不衰减，新视频永远追不上。

按分钟分窗口：

每分钟一个ZSET：

hot:video:1m:202607281430 → 14:30这一分钟的热度
hot:video:1m:202607281431 → 14:31这一分钟的热度
hot:video:1m:202607281432 → 14:32这一分钟的热度

查热榜时，把最近几个窗口合并：

14:35查热榜：
→ 合并 14:30、14:31、14:32、14:33、14:34、14:35 这6个窗口
→ 算总分，排序

好处：

14:30 的热度，到 14:35 时已经衰减了（只有 1/6 权重）
14:35 新产生的热度立刻反映
热榜是"最近几分钟"的热度，不是"历史累计"

ZSET 常用操作

// 分数增加
cache.ZincrBy(ctx, key, member, score)

// 按分数倒序取 top N
cache.ZRevRange(ctx, key, 0, 99) // 取前100名

// 合并多个ZSET
cache.ZUnionStore(ctx, dst, keys, "SUM")

// 设置过期时间
cache.Expire(ctx, key, 2*time.Hour)

面试要点总结

Q: 缓存和 DB 的一致性怎么保证？

A: 先更新 DB，再删缓存。删缓存失败靠 TTL 兜底，最终一致性。

Q: 缓存穿透/击穿/雪崩的区别和解法？

A: 穿透是查不存在的数据（缓存空值/布隆过滤器），击穿是热点 key 过期（分布式锁 + 等待重试），雪崩是大量 key 同时过期（随机 TTL）。

Q: 限流怎么实现的？

A: Redis 计数器，Lua 脚本原子执行 INCR + PEXPIRE，超限返回 429。

Q: 为什么用 Lua 脚本？

A: 保证 INCR 和 EXPIRE 原子执行，不会被其他命令插队，避免"只执行了一半"的问题。

Q: 热榜怎么实现的？

A: ZSET 按分钟分窗口，点赞时 ZincrBy 加分数，查热榜时合并最近几个窗口算总分。分窗口实现热度自动衰减。

Go 项目反推：Feed 流系统实战——数据库与 GORM

Mon, 27 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——认证体系，这一篇继续反推 feedsystem_video_go 的数据库代码，理解表结构、索引设计和 GORM 的常见用法。

理解所有表结构、索引设计、GORM 用法。

1. entity.go 的两种结构体

entity.go 里有两种东西：

1. 存数据库的（有 gorm 标签） → Social struct、Like struct...
2. 不存数据库的（没有 gorm 标签）→ FeedVideoItem、Request、Response...

gorm:"xxx" 标签 = 给 GORM 看的指令（怎么存数据库）
json:"xxx" 标签 = 给 JSON 看的指令（怎么显示给客户端）
两者互不影响，各管各的

2. gorm 标签汇总

标签	含义	示例
`gorm:"primaryKey"`	主键（唯一标识，类似身份证号）	`ID uint gorm:"primaryKey"`
`gorm:"unique"`	唯一（不能重复）	`Username string gorm:"unique"`
`gorm:"index"`	普通索引（加快查询，可以重复）	`VideoID uint gorm:"index"`
`gorm:"uniqueIndex:idx_name"`	唯一索引（不能重复）	`VideoID uint gorm:"uniqueIndex:idx_like_video_account"`
`gorm:"uniqueIndex:idx_name;not null"`	联合唯一索引（多个字段组合唯一）	见 Like 表
`gorm:"index:idx_name,priority:1,sort:desc"`	索引排序优先级	见 Video 表
`gorm:"not null"`	不能为空	`Title string gorm:"not null"`
`gorm:"default:false"`	默认值	`IsRead bool gorm:"default:false"`
`gorm:"autoCreateTime"`	自动填创建时间	`CreateTime time.Time gorm:"autoCreateTime"`
`gorm:"type:varchar(255)"`	字符串长度限制	`Title string gorm:"type:varchar(255)"`
`gorm:"type:text"`	长文本（无固定限制）	`Content string gorm:"type:text"`
`gorm:"column:likes_count"`	指定数据库列名	Go 驼峰 → DB 下划线
`gorm:"-"`	不存数据库	临时字段

3. json 标签

标签	含义
`json:"id"`	JSON 里显示为 “id”
`json:"-"`	JSON 里不显示（密码、Token 等敏感信息）
`json:"description,omitempty"`	空值时不显示这个字段

4. 表结构一览

Account 表（用户表）

ID → 主键
Username → 唯一（不能重复注册）
Password → 不显示在 JSON 里
Token → 不显示在 JSON 里
RefreshToken → 不显示在 JSON 里
AvatarURL → 头像地址
Bio → 个人简介

Video 表（视频表）

ID → 主键
AuthorID → 外键（关联 Account 表，存的是用户ID）
Username → 作者名（冗余存储，方便查询）
Title → 标题
Description → 描述
PlayURL → 播放地址
CoverURL → 封面地址
CreateTime → 自动填创建时间
LikesCount → 点赞数（统计字段）
Popularity → 热度值（统计字段）

Video 表的三个索引：

索引名	排序规则	用途
idx_videos_create_time	CreateTime DESC	最新视频
idx_videos_likes_count_id	LikesCount DESC	最热视频（按点赞）
idx_videos_popularity_time_id	Popularity DESC, CreateTime DESC	综合热度

priority = 优先级，数字越小越优先。

Like 表（点赞表）

ID → 主键
VideoID → 外键 + 联合唯一索引
AccountID → 外键 + 联合唯一索引

联合唯一索引：VideoID + AccountID 的组合不能重复

张三给视频 A 点赞 ✓
张三再给视频 A 点赞 ✗（违反唯一索引）
李四给视频 A 点赞 ✓（不同人）
张三给视频 B 点赞 ✓（不同视频）

为什么需要 Like 表 + Video 表的 LikesCount？

Like 表 → 记录"关系"（谁点了谁）
LikesCount → 记录"总数"（点赞数）
两者配合：Like 管关系，LikesCount 管统计

Comment 表（评论表）

ID → 主键
Username → 普通索引
VideoID → 外键 + 普通索引
AuthorID → 外键 + 普通索引
Content → 长文本（type:text）
CreatedAt → 自动填创建时间

index vs uniqueIndex：

index = 普通索引（可以重复，一个视频可以有很多评论）
uniqueIndex = 唯一索引（不能重复）

ID → 主键
FollowerID → 外键 + 联合唯一索引（谁在关注）
VloggerID → 外键 + 联合唯一索引（关注谁）

联合唯一索引：一个人不能关注同一个人两次。

Tag 表 + VideoTag 表（标签表）

Tag 表：
 ID → 主键
 Name → 唯一索引（标签名不能重复）

VideoTag 表（中间表）：
 ID → 主键
 VideoID → 外键 + 普通索引
 TagID → 外键 + 普通索引

多对多关系：一个视频可以有多个标签，一个标签可以属于多个视频，需要中间表 VideoTag 来记录关系。

Message 表（私信表）

ID → 主键
FromID → 外键 + 普通索引（谁发的）
ToID → 外键 + 普通索引（发给谁）
Content → 长文本
IsRead → 是否已读（默认 false）
CreatedAt → 自动填创建时间

ChunkUploadSession（分片上传）

不是 MySQL 表，存 Redis 的。

UploadID → 上传会话ID
AccountID → 谁在上传
UploadedBits → []bool 位图，记录每片上传状态

FeedVideoItem（Feed 流响应格式）

不是数据库表，是 API 响应格式。

Author → FeedAuthor（包含 ID + Username，不是外键）
IsLiked → 动态计算（查 Like 表），不存在数据库里

5. db.go（数据库初始化）

三个函数：

NewDB() → 连接数据库（DSN 格式：用户名:密码@tcp(地址:端口)/数据库名）
AutoMigrate() → 根据 struct 自动建表/更新表
CloseDB() → 关闭数据库连接

AutoMigrate 的好处：

手动建表：写 SQL，容易忘、容易错
AutoMigrate：改 struct，重启程序，自动更新表

6. repo.go（数据库操作）

每个模块都有自己的 repo.go，包含增删改查操作。

基础套路

// 创建
ar.db.WithContext(ctx).Create(&data)

// 查询（根据ID）
ar.db.WithContext(ctx).First(&result, id)

// 查询（根据条件）
ar.db.WithContext(ctx).Where("username = ?", name).First(&result)

// 更新（单字段）
ar.db.WithContext(ctx).Model(&Account{}).Where("id = ?", id).Update("username", newName)

// 更新（多字段）
ar.db.WithContext(ctx).Model(&Account{}).Where("id = ?", id).Updates(map[string]interface{}{"token": "", "refresh_token": ""})

// 删除
ar.db.WithContext(ctx).Delete(&Like{}).Where("video_id = ? AND account_id = ?", vID, aID)

db.WithContext(ctx) 的作用

把 context 传进去，支持超时取消。

事务（db.Transaction）

ar.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 // 操作1
 tx.Model(&Account{}).Where("id = ?", id).Update("username", newName)
 // 操作2
 tx.Model(&Account{}).Where("id = ?", id).Update("token", token)
 return nil
})

事务 = 要么全做，要么全不做。

类比：银行转账，A 扣钱与 B 加钱必须同时成功或同时失败。

原子操作（gorm.Expr）

// 错误做法：先读再写，并发会出错
likes_count = 100
用户A读到100，用户B读到100
用户A写入101，用户B写入101
结果：只加了1 ❌

// 正确做法：让数据库直接加
gorm.Expr("likes_count + ?", 1)
数据库排队执行：100+1=101, 101+1=102
结果：正确加了2 ✓

GREATEST(likes_count + ?, 0)：防止点赞数变成负数。

LikeIgnoreDuplicate（忽略重复点赞）

err = r.db.WithContext(ctx).Create(like).Error
if err == nil {
 return true, nil // 创建成功
}
// 如果是"重复主键"错误（1062），忽略
var mysqlErr *mysql.MySQLError
if errors.As(err, &mysqlErr) && mysqlErr.Number == 1062 {
 return false, nil // 已经点过赞了，不报错
}

为什么需要这个？

联合唯一索引：保证数据正确（一人只能点一次）
LikeIgnoreDuplicate：保证用户体验（重复点赞不报错）
两个配合：数据对 + 体验好

gorm.ErrRecordNotFound（判断记录不存在）

if err == gorm.ErrRecordNotFound {
 return false, nil // 记录不存在
}

关联查询（Joins）

// 查"张三点赞过的所有视频"
r.db.WithContext(ctx).
 Model(&Video{}).
 Joins("JOIN likes ON likes.video_id = videos.id").
 Where("likes.account_id = ?", accountID).
 Find(&videos)

分步查询（GetAllFollowers）

-- 第1步：从 Social 表查出 follower_id 列表
SELECT follower_id FROM socials WHERE vlogger_id = 1;
-- 得到 [2, 5, 8]

-- 第2步：用 ID 列表去 Account 表查用户信息
SELECT * FROM accounts WHERE id IN (2, 5, 8);

为什么分两步？

Social 表只存 ID（避免数据冗余），Account 表存用户信息。用户改名只改 Account 表，Social 表不用动。

7. 数据库规范化

同一份数据只存一个地方，其他地方只存 ID（外键）。

反范例：Social 表存用户名
 用户改名 → 要更新 Account 表 + Social 表 + 其他表...
 牵一发动全身

正范例：Social 表只存 ID
 用户改名 → 只改 Account 表
 需要名字时，拿着 ID 去 Account 表查

8. 面试要点

1. Video 表为什么有三个索引？

因为有三种查询需求：

idx_videos_create_time → 按时间排序（查最新视频）
idx_videos_likes_count_id → 按点赞数排序（查最热视频）
idx_videos_popularity_time_id → 按热度 + 时间排序（综合排名）

每种查询方式都需要自己的“目录”（索引），没有索引就要全表扫描，很慢。

2. 点赞表为什么使用联合唯一索引？

点赞表用 uniqueIndex:idx_like_video_account，保证 VideoID + AccountID 的组合唯一。一个人只能给一个视频点一次赞，如果重复点赞会违反唯一索引报错。配合 LikeIgnoreDuplicate 函数，重复点赞时静默忽略，不向用户报错。

3. gorm.Expr 是怎么解决并发问题的？

错误做法：先读 likes_count=100，再写 100+1=101。两个用户同时读到 100，都写入 101，结果只加了 1。

正确做法：用 gorm.Expr("likes_count + ?", 1)，让数据库直接执行 likes_count = likes_count + 1，数据库保证原子更新，结果正确。GREATEST(likes_count + ?, 0) 可以防止点赞数变成负数。

4. 改名 + 更新 Token 为什么要用事务？

因为改名后 Token 里的 Username 就过期了，必须同时更新。事务保证“要么全做，要么全不做”：改名成功但更新 Token 失败时回滚，改名也不生效。

如果存用户名，用户改名时要更新 Account 表、Social 表和其他表，牵一发动全身。只存 ID 时，用户改名只改 Account 表，Social 表不用动；需要名字时拿着 ID 去 Account 表查询。

6. Tag 和 Video 为什么需要中间表？

一个视频可以有多个标签，一个标签也可以属于多个视频，这是多对多关系。一个外键字段只能存一个值，因此需要中间表 VideoTag 存储 VideoID + TagID，记录“哪个视频有哪些标签”。

Go 项目反推：Feed 流系统实战——认证体系

Sat, 25 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——请求生命周期，这一篇继续反推 feedsystem_video_go 的认证代码，梳理 JWT、Refresh Token、Token 撤销，以及软硬鉴权中间件之间的关系。

一、jwt.go 文件结构

文件位置：internal/auth/jwt.go

jwtSecret() → 获取密钥
Claims → Token 里存什么
GenerateToken() → 生成 accessToken（JWT 格式，15 分钟）
GenerateRefreshToken() → 生成 refreshToken（随机字符串）
ParseToken() → 验证 Token（签名 + 过期）

二、密钥与 Claims

jwtSecret()：获取密钥

优先使用环境变量 JWT_SECRET，没有就随机生成：

JWT_SECRET=*** go run ./cmd

如果没有设置环境变量，每次服务器启动时密钥都会改变，之前签发的 Token 将全部失效，所有用户都要重新登录。因此正式环境必须设置稳定且足够随机的 JWT_SECRET。

Claims：Token 里存什么

type Claims struct {
 AccountID uint // 用户 ID
 Username string // 用户名
 jwt.RegisteredClaims // 标准字段（过期时间、签发时间等）
}

可以把 Claims 类比为一张有有效期的身份证，上面记录用户名、用户 ID、签发时间和过期时间。

需要注意：JWT Payload 只是经过 Base64URL 编码，并不是加密，客户端也能读取其中的内容。因此 Claims 里不能放密码、密钥等敏感数据。

三、生成 Token

GenerateToken()：生成 accessToken

1. 创建 Claims，写入用户 ID、用户名和 15 分钟后的过期时间
2. 使用 HS256 算法创建 Token 对象
3. 使用 JWT Secret 签名，生成 Token 字符串

结果是一串类似 eyJhbG...xxxx 的 JWT。它内部包含经过编码的 Header 和 Payload，以及用于防止内容被篡改的签名。

HS256 只负责签名和验签，不负责加密。其他人虽然可以读取 Payload，但没有 JWT_SECRET 就无法生成有效签名。

GenerateRefreshToken()：生成 refreshToken

Refresh Token 和 Access Token 完全不同：

accessToken → JWT 格式，携带 Claims，并使用密钥签名
refreshToken → 随机字符串，本身不携带用户信息

项目使用 32 个随机字节，再转换为 64 位十六进制字符串。Refresh Token 不需要携带 Claims，它只需要成为一个难以猜中的长期凭证。

双 Token 时间设定

accessToken 15 分钟：泄露后的可利用时间较短
refreshToken 7 天： 用于换取新的 Access Token，减少重复登录

Access Token 有效期短，降低泄露风险；Refresh Token 有效期长，保证使用体验。二者配合，在安全性和便利性之间取得平衡。

四、验证 Token

ParseToken()：验证 Token

输入：客户端发送的 Token 字符串
输出：Claims（用户 ID、用户名）或错误

流程：

1. 解析 Token
2. 确认签名算法是 HS256
3. 使用 JWT Secret 验证签名
4. 检查 Token 是否过期
5. 全部通过 → 返回 Claims
6. 任一失败 → 返回错误

这里不是“解密 Token”，因为 JWT Payload 没有被加密。服务器做的是解析内容并验证签名。

还需要注意：ParseToken() 只检查格式、签名和过期时间，不检查 Token 是否已被撤销。

五、Refresh 流程

Access Token 过期后，可以使用 Refresh Token 换取新的 Access Token：

客户端：Access Token 过期，这是 Refresh Token，请签发新的 Access Token

服务器：
 1. 使用 Refresh Token 查询 Redis 中的 refresh:<token>
 2. 查询成功后得到 accountID
 3. 查询数据库，确认 Refresh Token 与账户记录匹配
 4. 生成新的 Access Token
 5. 将新 Token 写入数据库和 Redis
 6. 返回给客户端

可以类比为：短期门禁卡过期后，使用长期凭证到前台换一张新卡。

关键点是：使用 Refresh Token 换取 Access Token，而不是反过来。

六、Token 撤销

JWT 的签名和过期时间一旦确定，单靠 ParseToken() 无法让一个尚未过期的 Token 提前失效。因此项目额外在 Redis 和 MySQL 中保存当前有效 Token。

登出时删除旧 Token：

删除 Redis 中的三个 Key：
 account:<id> → accessToken
 account:<id>:refresh → refreshToken
 refresh:<token> → accountID

清空 MySQL 中的字段：
 token
 refresh_token

删除后，即使旧 JWT 的签名正确且尚未过期，中间件也无法在 Redis 或 MySQL 中匹配到它，因此会拒绝请求。

修改密码时也可以使用相同思路：

清空旧 Token
→ 签发新 Token
→ 让其他设备上的旧登录状态立即失效

七、JWTAuth 中间件

文件位置：internal/middleware/jwt/jwt.go

处理流程：

1. 从请求头读取 Authorization
2. 检查格式是否为 Bearer <token>
3. 调用 auth.ParseToken() 验证格式、签名和过期时间
4. 调用 check() 检查 Token 是否仍是当前有效 Token
5. 验证通过后将用户信息写入 Gin Context

客户端发送：

Authorization: Bearer ***

check()：为什么同时查询 Redis 和 MySQL

第一步：查询 Redis
 查到 → 对比请求 Token 是否为当前有效 Token
 相同 → 放行
 不同 → 拒绝，Token 已被替换或撤销

 Redis 未命中或不可用 → 查询 MySQL

第二步：查询 MySQL
 查到账户 → 对比数据库保存的 Token
 相同 → 放行，并回填 Redis
 不同 → 拒绝

Redis 是缓存，速度快但可能未命中或不可用；MySQL 是持久化的数据来源，可以作为兜底。MySQL 本身也可能发生故障，因此更准确的说法是“Redis 失败时降级查询 MySQL”，而不是“MySQL 永远可用”。

check() 主要完成两件事：

将请求中的 Token 与服务器保存的当前 Token 对比，判断是否已被撤销
将用户信息写入 gin.Context，方便后续 Handler 使用

八、两种鉴权

JWTAuth（硬鉴权）：
 没有 Token 或 Token 无效 → 拒绝请求

SoftJWTAuth（软鉴权）：
 没有 Token → 继续放行
 有 Token且有效 → 识别用户身份后放行

项目中的使用示例：

JWTAuth（必须登录）：
 /logout
 /rename
 /uploadAvatar

SoftJWTAuth（不强制登录）：
 /feed/listLatest
 /feed/listByPopularity

用户没有 Token 也能浏览 Feed；携带有效 Token 时，系统可以识别用户并提供个性化结果。

可以类比为：

JWTAuth → 会员俱乐部，没有会员卡不能进入
SoftJWTAuth → 商场，没有会员卡也能进入，有会员卡则能获得个性化服务

九、面试要点

JWT 如何生成：Claims + HS256 + JWT Secret 签名
JWT 不等于加密：Payload 可以读取，签名用于防篡改
双 Token：短期 Access Token + 长期 Refresh Token
Refresh 流程：使用 Refresh Token 换取新的 Access Token
Token 撤销：清理 Redis 与 MySQL 中保存的 Token，使旧 JWT 立即失效
中间件 check()：优先查询 Redis，未命中或不可用时查询 MySQL
两种鉴权：JWTAuth 强制登录，SoftJWTAuth 允许匿名访问

这一套设计实际上让 JWT 从“完全无状态”变成了“带服务端状态的认证方案”。它牺牲了一部分无状态带来的简单扩展能力，换取了主动登出、修改密码后强制失效和单会话控制等能力。

Go 项目反推：Feed 流系统实战——请求生命周期

Tue, 21 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——从 Docker 到开源贡献，这一篇继续反推 feedsystem_video_go 的后端代码。这次不再从整体架构看项目，而是以 POST /account/login 为例，追踪一个请求从进来到返回的完整路径。

路由基础

router.go 是什么

router.go = 路由表 = “地址簿”。它告诉服务器：什么方式 + 访问哪个路径 → 转发到哪个函数。

POST /account/login → accountHandler.Login
POST /account/register → accountHandler.CreateAccount
GET /healthz → 返回 {"status":"ok"}

类比：router.go 是前台接待（“办 login 业务找张三”），handler.go 是张三的工位（“我来处理”）。

路由组

accountGroup := r.Group("/account")

创建一个路由组，前缀是 /account。组里的所有路由，路径前面自动加上前缀：

accountGroup.POST("/login", ...) → 实际路径 POST /account/login
accountGroup.POST("/register", ...) → 实际路径 POST /account/register

类比：把用户相关接口都放在 /account 这个“文件夹”下。

路由注册

accountGroup.POST("/login", loginLimiter, accountHandler.Login)

三个参数：

"/login" → 路径（拼上 /account，变成 /account/login）
loginLimiter → 限流中间件（先过这一关）
accountHandler.Login → 最终处理请求的函数（过了限流才到这里）

请求流程：

POST /account/login 进来
 ↓
loginLimiter（限流中间件）
 ↓
accountHandler.Login（handler 处理）

函数引用 vs 函数调用

accountGroup.POST("/login", loginLimiter, accountHandler.Login)

accountHandler.Login 是函数本身，不是调用。Go 里函数可以当变量传来传去，和 CS61A 的高阶函数一个意思：

accountHandler.Login → 函数本身（把函数“交给”路由器，等有人请求时再调用）
accountHandler.Login(c) → 调用函数（立刻执行）

类比：给你一张纸条写上张三的电话号码（函数引用） vs 现在立刻拨打电话（函数调用）。

现在不执行，等有人发 POST /account/login 时，路由器才会调用 Login(c) 并传入请求信息。

三层架构

结构创建

router.go 第 40-42 行：

accountRepository := account.NewAccountRepository(db)
accountService := account.NewAccountService(accountRepository, cache)
accountHandler := account.NewAccountHandler(accountService)

创建三个“工人”：

Repository → 操作数据库的人（查表、写表）
Service → 处理业务逻辑的人（校验密码、生成 Token）
Handler → 接收请求的人（解析参数、返回结果）

依赖关系：db → Repository → Service → Handler → 路由

类比：先招档案员（Repository）给数据库钥匙，再招业务员（Service）管档案员，再招前台（Handler）对接业务员，最后门口挂牌子（路由）：“办 login 业务找前台”。

Handler 结构体

type AccountHandler struct {
 accountService *AccountService
}

func NewAccountHandler(accountService *AccountService) *AccountHandler {
 return &AccountHandler{accountService: accountService}
}

AccountHandler 是一个结构体，里面有一个字段 accountService。NewAccountHandler 创建这个结构体并把 Service 存进去。

分层的意义

handler 只管：解析请求 → 调用 service → 返回结果
service 处理：校验密码 → 生成 Token → 写数据库
repo 处理： 操作数据库

handler 不关心密码怎么校验、Token 怎么生成，它只管“调用 service”。

文件目录结构

internal/http/router.go → 路由目录，负责“找谁”
internal/account/handler.go → 用户模块，负责“怎么干”
internal/account/service.go → 用户模块，负责“核心逻辑”
internal/account/repo.go → 用户模块，负责“操作数据库”

按模块分目录：account 目录下放所有跟用户相关的代码，video 目录下放所有跟视频相关的代码。

Handler 层：Login 函数

handler.go 第 116-133 行：

func (h *AccountHandler) Login(c *gin.Context) {
 var req LoginRequest // 声明容器
 if err := c.ShouldBindJSON(&req); err != nil { ... } // 解析 JSON
 account, err := h.accountService.FindByUsername(...) // 查数据库存不存在
 accessToken, refreshToken, err := h.accountService.Login(...) // 校验密码+生成Token
 c.JSON(200, LoginResponse{Token, RefreshToken, ...}) // 返回给客户端
}

完整流程：

1. 解析客户端发的 JSON（用户名、密码）
2. 去数据库查这个用户存不存在
3. 存在的话，让 service 校验密码、生成 Token
4. 把 Token 返回给客户端

ShouldBindJSON

c.ShouldBindJSON(&req)

把客户端发的 JSON 解析到 req 变量里。客户端发 {"username": "zhangsan", "password": "***"}，解析后 req.Username = "zhangsan"，req.Password = "123456"。

ShouldBindJSON vs json.NewDecoder：两个干的事一样，都是把 JSON 解析到变量里。c.ShouldBindJSON(&req) 是 Gin 封装的一行搞定；json.NewDecoder(r.Body).Decode(&req) 是原生写法，要三行还要检查 err。类比：自动挡 vs 手动挡。

Service 层：Login 函数

handler 调用 service 的 Login：

accessToken, refreshToken, err := h.accountService.Login(c.Request.Context(), req.Username, req.Password)

service.go 的 Login 做了 6 件事：

1. 查数据库拿用户信息（FindByUsername）
2. bcrypt 校验密码
3. 生成 accessToken 和 refreshToken
4. Token 存进 MySQL（调用 repo.Login）
5. Token 存进 Redis（3 个 key）
6. 返回两个 Token

ctx（context）

ctx = 请求的“身份证”，带着两个信息：

超时时间：这个请求最多等多久
取消信号：客户端断开了，别再查了

每一层都要传 ctx，这样整条链路都能感知到“客户端还在不在”。

类比：你去饭店点菜，等了 5 分钟走了。没有 ctx → 厨师还在炒，炒完发现你走了，菜倒掉。有 ctx → 服务员告诉厨师“客人走了”，厨师立刻停手。

bcrypt 校验密码

bcrypt.CompareHashAndPassword([]byte(account.Password), []byte(password))

传入两个参数：数据库里存的加密密码（哈希）和用户这次输入的明文密码。bcrypt 把明文密码加密，和数据库里的对比，一样返回 nil（成功），不一样返回 error（失败）。

为什么不存明文？数据库被黑了，黑客拿到的是加密字符串，反推不出原始密码。

[]byte() = 把字符串转成字节数组，bcrypt 只接收这种格式。

双 Token（JWT）

登录成功返回两个 Token：

accessToken → 短期有效（15分钟），用来证明“我是谁”
refreshToken → 长期有效（7天），用来续期 accessToken

为什么两个？只用一个 token 的问题：设太短 → 用户每 15 分钟重新登录，体验差；设太长 → 被偷了就一直能用，不安全。双 token 解决了这个问题：accessToken 短，被偷了也很快过期；refreshToken 长，用户不用频繁登录；accessToken 过期了，用 refreshToken 换新的。

类比：accessToken = 门禁卡（每天过期，重新刷卡续期），refreshToken = 身份证（长期有效，门禁卡丢了拿身份证补办）。

Token 根据用户信息生成（不是纯随机）：

accessToken → 包含用户ID + 用户名 + 过期时间（15分钟）
refreshToken → 只包含用户ID + 过期时间（7天）
用密钥加密生成一串乱码字符串

为什么有 ID 又有用户名

ID（account.ID） → 数据库主键，不可变，用来精确查找
用户名（username）→ 可以改，用来方便识别

类比：身份证号（ID）不可变，查账户用；姓名（username）可以改，写在凭证上让人看。生成 Token 时两个都存：ID 用来查人，用户名用来识别。

Repo 层：Login 函数

service 调用 repo 把 Token 存进 MySQL：

as.accountRepository.Login(ctx, account.ID, accessToken, refreshToken)

repo.go 里用 GORM 操作数据库：

ar.db.WithContext(ctx).Model(&Account{}).Where("id = ?", id).Updates(
 map[string]interface{}{"token": token, "refresh_token": refreshToken})

翻译：在 account 表里，找到 id 等于 id 的那一行，更新 token 和 refresh_token。

等价 SQL：

UPDATE account SET token = 'xxx', refresh_token = 'yyy' WHERE id = 1;

GORM = 用 Go 代码描述“我要干什么”，GORM 帮你翻译成 SQL。

Redis 缓存

登录成功后，Token 存两份：

MySQL 存一份 → 保险，重启不丢，但慢
Redis 存一份 → 快，验证时直接查这里

Redis 存了 3 个 key：

key: "account:1" → accessToken TTL 24小时
key: "account:1:refresh" → refreshToken TTL 7天
key: "refresh:xxxxx" → accountID TTL 7天

为什么存 3 个？第 1 个验证 Token 时查，第 2 个刷新 Token 时查，第 3 个用 refreshToken 反查用户 ID。

Redis 不可用时降级：跳过缓存，只靠 MySQL，功能不丢，只是慢一点。

中间件

怎么执行的

中间件 = 挡在 handler 前面的一道关卡。两个关键函数：

c.Next() → 放行，让请求继续走到下一个中间件或 handler
c.Abort() → 拦截，不让请求继续走，handler 不会执行

类比：c.Next() = 安检通过，放你进去；c.Abort() = 安检不过，拦住你。

为什么是两层函数

func Limit(cache, name string, ...) gin.HandlerFunc { // 外层：传配置
 return func(c *gin.Context) { // 内层：处理请求
 c.Next()
 }
}

外层传配置，内层处理请求。外层函数执行一次，创建中间件；内层函数每次有人访问都执行一次。

类比：外层 = 装修奶茶店（执行一次，买机器、买原料）；内层 = 每天营业（执行无数次，客人来了做奶茶）。

gin.HandlerFunc = Gin 要求中间件必须是这种格式的函数。

gin.Context 的数据传递

中间件把用户 ID 塞进 c 里：

c.Set("accountID", accountID) // 中间件：往 c 里存

handler 从 c 里取出来：

value, exists := c.Get("accountID") // handler：从 c 里取

c 就是一个“传话筒”，中间件往里塞东西，handler 从里拿东西。c 是临时对象，只活在一次请求里，请求结束就没了，不会存到 Redis。

类比：安检员检查完证件，在你手上盖个章“1号”（中间件 c.Set）；柜员看你手上的章，知道你是“1号”（handler c.Get）。

错误到 HTTP 状态码的映射

ClassifyHTTPStatus 就是一张对照表：

error 类型 → 状态码 → 含义
nil（没错误） → 200 → 成功
ErrUnauthorized（未登录） → 401 → 未授权
ErrValidation（参数错误） → 400 → 请求格式错
gorm.ErrRecordNotFound（查不到）→ 404 → 资源不存在
其他错误 → 500 → 服务器内部错误

handler 里用法：

c.JSON(apierror.ClassifyHTTPStatus(err), gin.H{"error": err.Error()})

翻译：看一眼 error 是什么类型，返回对应的状态码。

1. 用户发 POST /account/login

2. router.go 找到这条路由，先过 loginLimiter（限流中间件）

3. 进入 handler.go 的 Login 函数：
 - 解析 JSON（拿到 username 和 password）
 - 调用 service.FindByUsername（查用户存不存在）
 - 调用 service.Login（校验密码 + 生成 Token）

4. 进入 service.go 的 Login 函数：
 - 再查一次数据库（拿到密码哈希）
 - bcrypt 校验密码
 - 生成 accessToken 和 refreshToken
 - 调用 repo.Login（把 Token 存 MySQL）
 - 把 Token 存进 Redis（3 个 key）

5. 进入 repo.go 的 Login 函数：
 - 用 GORM 把 Token 写进 account 表

6. Token 一层一层返回：repo → service → handler → 客户端

涉及 4 个文件：

router.go → 注册路由，把路径和函数连起来
handler.go → 解析请求，调用 service
service.go → 校验密码，生成 Token，存数据库和缓存
repo.go → 操作 MySQL

涉及 2 个存储：

MySQL → 存用户信息和 Token（持久化，重启不丢）
Redis → 缓存 Token（快，重启会丢）

Go 项目反推：Feed 流系统实战——从 Docker 到开源贡献

Sun, 19 Jul 2026 00:00:00 +0800

承接 Go 语言基础：从变量到指针、Go 语言进阶：方法、接口与错误处理、Go 语言工程化：模块管理与项目结构、Go 语言并发：从 Goroutine 到 Worker Pool 和 Go Web 开发：从 net-http 到 Gin，这一篇跳出语法学习，反推一个真实的开源项目——feedsystem_video_go（279 star，Go + Vue 3 短视频 Feed 流系统），从跑通项目到提交 PR，走一遍完整的工程实战。

项目概览

这个项目是一个短视频 Feed 流系统，技术栈：

后端：Go + Gin + GORM + RabbitMQ + Redis
前端：Vue 3 + TypeScript
基础设施：Docker Compose 编排 MySQL、Redis、RabbitMQ

核心功能包括用户注册登录、视频发布、点赞评论、关注取关、Feed 流推送。架构上采用 API + Worker 的消息队列模式。

Docker Compose：启动基础设施

项目的三个"帮手"——MySQL、Redis、RabbitMQ——通过 Docker Compose 一键启动：

cd ~/dev/projects/feedsystem_video_go
docker compose up -d mysql redis rabbitmq

docker compose up — 根据 docker-compose.yml 启动服务
-d — 后台运行（detach），不占终端窗口
mysql redis rabbitmq — 只启动这三个，不启动 backend/worker/frontend

镜像 vs 容器

Docker 里有两个核心概念：

镜像 = 打包好的集装箱（里面有程序 + 配置），是静态文件
容器 = 集装箱正在运行的实例

类比：.app 文件是镜像，双击打开后正在运行就是容器。

端口映射

MySQL 默认端口 3306，但本机可能已经装了 MySQL 占用了 3306。所以 docker-compose.yml 里写的是：

ports: "3307:3306"

意思是：外部访问 3307 → 转发到容器内部的 3306。就像你家门牌号是 3307，但内部房间编号是 3306。项目配置文件里写的也是 3307，Go 程序连接 MySQL 时用的就是 3307。

通过 docker compose ps 可以查看所有容器的运行状态：

NAME IMAGE STATUS PORTS
feedsystem_video_go-mysql-1 mysql:8.0 Up 5 minutes (healthy) 0.0.0.0:3307->3306/tcp
feedsystem_video_go-redis-1 redis:7-alpine Up 5 minutes (healthy) 0.0.0.0:6379->6379/tcp
feedsystem_video_go-rabbitmq-1 rabbitmq:3 Up 5 minutes (healthy) 0.0.0.0:5672->5672/tcp

0.0.0.0 表示"接受任何来源的连接"，即对外部开放。

启动 Go 后端

基础设施就位后，启动后端：

cd backend
CONFIG_PATH=configs/config.compose-local.yaml go run ./cmd

CONFIG_PATH=... — 告诉程序用哪个配置文件（里面写好了 MySQL 3307、Redis 6379、RabbitMQ 5672 的地址）
go run ./cmd — 编译并运行 cmd/main.go 入口程序

日志解读

启动后会看到几段日志：

第一段：依赖下载

go: downloading github.com/gin-gonic/gin v1.11.0
go: downloading gorm.io/gorm v1.31.1

Go 在下载第三方库，类似 npm install，下载一次以后就不需要了。

第二段：连接建立

Loading config from configs/config.compose-local.yaml
Redis connected (cache enabled)
RabbitMQ connected

注意没有 “MySQL connected”，因为 GORM 连接 MySQL 是在后面 AutoMigrate 时才真正连接。

第三段：Gin 路由注册

[GIN-debug] GET /healthz
[GIN-debug] POST /account/register
[GIN-debug] POST /account/login
[GIN-debug] POST /video/publish
[GIN-debug] POST /like/like
[GIN-debug] POST /feed/listLatest

格式是 HTTP方法路由路径，后面的 (4 handlers) 表示这条路由经过几个中间件（如限流 + JWT 鉴权 + 业务处理）。

第四段：消息队列

DLX ready: exchange=dlx.events queue=like.events.dlx
Timeline consumer 已启动, queue=video.timeline.update.queue

DLX = Dead Letter Exchange（死信队列），专门处理失败的消息。

第五段：启动完成

Server is running on port 8080

为什么不把 Go 也放进 Docker？

Docker 适合最终部署，不适合日常开发调试。本地直接 go run 的好处：

日志直接打印在终端，实时可见
改了代码立刻能跑，不用重新打包镜像
出错了能直接看到报错信息

日志不是中间件

日志是 Go 标准库 log 包写出来的，是程序员手动写的"程序进行到哪一步了"的提示。中间件是处理请求的"关卡"，两者没有关系。

核心概念：缓存与消息队列

Redis 缓存

缓存 = 把经常用的数据放在"取用更快的地方"。

类比：冰箱里有水（MySQL，容量大但取用慢），你拿了一瓶放在桌上（Redis 缓存，取用极快），下次喝水直接从桌上拿，不用再去冰箱。

代码里 cache enabled 表示数据会先从 Redis 取，取不到再去 MySQL。

RabbitMQ 消息队列

消息队列是 API 和 Worker 之间的"传话筒"。API 处理完核心逻辑后，把"后续要做的事"发到队列，Worker 从队列里取任务执行。

前后端分离架构

后端和前端是两个完全不同的程序：

后端：Go 写的，负责业务逻辑、读写数据库，监听 8080 端口
前端：Vue 写的，负责页面展示、用户交互，监听 5173 端口

它们通过 HTTP 请求通信：用户在浏览器点"登录" → 前端发请求到 localhost:8080/account/login → 后端处理 → 返回结果 → 前端展示。

就像餐厅里厨房（后端）和前厅（前端）是两个地方，前厅接到顾客点单传给厨房，厨房做完菜传给前厅。

前端用 npm（Node Package Manager）管理依赖，跟 Go 的 go get、Python 的 pip install 是同一个道理：

cd frontend
npm install # 下载依赖
npm run dev # 启动开发服务器

Worker 进程模式

这是整个项目最核心的架构设计。Worker 是一个独立进程，和 API 分开启动：

cd backend
CONFIG_PATH=configs/config.compose-local.yaml go run ./cmd/worker

为什么要分开？

想象一个外卖平台：

方案 A：一个人又要接单又要送餐 — 接单时有新订单没人接，送餐时又有新订单没人接，效率低。

方案 B：两个人分工 — 前台专门接单（API），骑手专门送餐（Worker），前台接完单把订单放进"待送餐队列"（RabbitMQ），骑手从队列里取订单去送。

对应到项目：

角色	职责
API 进程	接收用户请求（点赞、评论、发布视频），处理核心业务逻辑，把"后续要做的事"发到消息队列
Worker 进程	监听消息队列，处理异步任务：更新点赞数、计算热度、推送通知

这个项目有四个 Worker：

LikeWorker — 处理点赞/取消点赞事件
PopularityWorker — 更新视频热度
SocialWorker — 处理关注/取关事件
CommentWorker — 处理评论事件

分开的好处

性能：用户点赞时，API 只需要返回"点赞成功"，不需要等热度计算完成
独立伸缩：请求量大时启动多个 API 进程，任务多时启动多个 Worker 进程
故障隔离：Worker 挂了 API 还能正常接收请求，API 挂了 Worker 还能把队列里的任务处理完

一句话总结：API 是"接单的"，Worker 是"干活的"，通过消息队列解耦。

开源贡献实战：修复 JWT 密钥缓存 Bug

跑通项目后，在实际使用中发现了一个真实 Bug。

问题复现

不设置 JWT_SECRET 环境变量，启动后端
注册一个账号
登录成功（页面提示"登录成功"）
但左侧栏仍然显示"未登录"
浏览器控制台报错：invalid or expired token (401)

登录本身成功，但所有需要鉴权的接口全部返回 401。

根因定位

文件：backend/internal/auth/jwt.go

func jwtSecret() []byte {
 secret := os.Getenv("JWT_SECRET")
 if secret == "" {
 b := make([]byte, 32)
 rand.Read(b)
 secret = hex.EncodeToString(b)
 }
 return []byte(secret)
}

问题出在这个函数每次调用都生成一个新的随机密钥：

登录时：GenerateToken() 调用 jwtSecret() → 拿到密钥 A → 用 A 签名 token
验证时：ParseToken() 调用 jwtSecret() → 拿到密钥 B → 用 B 验证
A ≠ B → 签名不匹配 → 返回 401

修复方案

用包级别的变量缓存密钥，保证每个进程只生成一次：

var cachedSecret []byte

func jwtSecret() []byte {
 if cachedSecret != nil {
 return cachedSecret
 }
 secret := os.Getenv("JWT_SECRET")
 if secret == "" {
 b := make([]byte, 32)
 if _, err := rand.Read(b); err != nil {
 log.Printf("FATAL: cannot generate JWT secret: %v", err)
 cachedSecret = []byte("fallback-unsafe-key-change-me")
 return cachedSecret
 }
 secret = hex.EncodeToString(b)
 log.Printf("WARNING: JWT_SECRET not set, generated random key.")
 }
 cachedSecret = []byte(secret)
 return cachedSecret
}

修复方案兼顾安全性（缓存保证签名一致）和灵活性（仍然允许随机密钥兜底）。

走通开源贡献流程

步骤	内容
1. 本地复现	按步骤触发 Bug
2. 阅读源码	从前端 → API → JWT 中间件，定位根因
3. 提 Issue	描述问题，附带复现步骤 → #15
4. Fork + 修复分支	`fix/jwt-secret-caching`
5. 提 PR	关联 Issue → #16

面试话术

在一个 279 star 的开源项目中发现了真实 bug
从前端（Vue/TypeScript）追踪到 API（Gin/Go）再到 JWT 鉴权中间件，定位了根因
提出的修复方案兼顾安全性和灵活性
走通了完整的开源贡献流程

这一篇从"跑通项目"出发，反推了 Docker Compose 编排、Gin 路由注册、Redis 缓存、RabbitMQ 消息队列、Worker 进程模式等工程概念，最后通过一次真实的开源贡献把整条链路串了起来。相比纯语法学习，反推真实项目能更快建立工程直觉。

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