Redis模块C++封装需用extern "C"导出函数、禁用异常跨接口传递、避免STL频繁拷贝、仅通过模块API访问数据结构，并在OnUnload中手动清理全局状态和线程。
Redis模块API的C++封装必须绕过C ABI限制
Redis 7.0+ 的模块系统是纯C接口，直接用C++类或异常会破坏ABI兼容性。所有导出函数必须用 extern "C" 修饰，否则Redis加载时会报 undefined symbol 错误。
常见错误是把模块入口函数写成：
int RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) { ... }
这在C++中实际被编译为带名字修饰的符号，Redis找不到。正确写法是：
extern "C" int RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) { ... }
- 所有回调函数（如命令实现、keyspace通知）都需加
extern "C" - C++标准库对象（如
std::string、std::vector）只能在模块内部使用，不能跨C接口传递 - 异常绝对不能抛出到Redis调用栈中——必须用
try/catch(...)捕获并转为RedisModule_ReplyWithError()
命令实现中避免STL容器频繁拷贝
Redis模块命令处理路径极敏感延迟，而 std::string 默认构造+赋值可能触发堆分配和内存拷贝。尤其在高频命令（如自定义计数器）中，每毫秒多一次 malloc 就会明显拖慢吞吐。
立即学习“C++免费学习笔记（深入）”；
实操建议：
- 用
RedisModule_StringPtrLen()直接获取客户端传入字符串的原始指针和长度，避免复制到std::string - 内部状态缓存用
std::array或栈上固定缓冲区（如char buf[256]），而非动态分配 - 若必须用容器，优先选
absl::InlinedVector（需静态链接）或预分配容量的std::vector::reserve() - 返回响应时，用
RedisModule_ReplyWithStringBuffer()直接刷原始字节，别先拼std::ostringstream
访问Redis数据结构要用模块API，别碰底层结构体
有人试图直接 cast RedisModuleKey * 到 robj * 或读取 dict * 字段，这是危险且版本不兼容的。Redis 7.2 已重排 redisObject 内存布局，硬访问会导致段错误或数据错乱。
正确路径只有两条：
- 对键操作：用
RedisModule_OpenKey()+RedisModule_ModuleTypeGetValue()获取模块自定义类型值 - 对原生类型（string/list/set等）：只用
RedisModule_String...()、RedisModule_List...()等封装函数，它们内部已适配各版本内存模型 - 需要高性能遍历？用
RedisModule_ScanCursor *而非自己迭代dict—— 它自动处理rehash和并发安全
模块热重载时全局状态清理容易遗漏
Redis支持 MODULE UNLOAD + MODULE LOAD 热更新，但C++全局变量（如 static std::unordered_map、单例）不会自动析构。残留状态会导致新模块行为异常，比如旧的定时器还在往已释放内存写入。
必须显式注册卸载钩子：
extern "C" int RedisModule_OnUnload(RedisModuleCtx *ctx) {
cleanup_global_cache(); // 手动清空所有static容器
stop_background_threads(); // 终止std::thread并join
return REDISMODULE_OK;
}
注意：RedisModule_OnUnload 不保证在所有线程退出后才调用，所以线程终止逻辑要带超时和强制中断标记，不能依赖 std::thread::join() 阻塞等待。
真正难处理的是异步I/O（如libuv或io_uring句柄），它们的资源释放时机与Redis生命周期不同步，这类扩展通常得放弃热重载，改用进程级重启。
