Redis虽然内置了丰富的数据结构和命令，但在某些场景下仍然需要自定义功能，例如添加新的数据结构、实现特殊的搜索算法或者接入外部系统。模块系统为此提供了一种优雅的扩展方式，通过动态链接库在运行时加载进Redis进程，从而获得与内置命令相同的执行效率。然而模块不是永久驻留的，理解其加载与卸载的完整流程，对保证Redis实例的稳定运行至关重要。
模块加载与卸载看似简单的两条命令，背后涉及动态库的加载、符号解析、回调函数执行、资源引用计数等复杂机制。如果操作不当，轻则导致模块命令不可用，重则引起Redis进程崩溃或内存泄漏。下文将从模块机制、加载、卸载以及最佳实践四个层面展开，帮助读者形成系统性的知识框架。
Redis模块机制概述
Redis从4.0版本开始正式引入模块系统，允许开发者使用C语言（或其他能够生成兼容动态库的语言）编写扩展模块。模块本质上是一个共享库文件，例如Linux下的.so文件，其内部实现了一系列Redis规定的回调函数。最关键的两个回调函数是RedisModule_OnLoad和RedisModule_OnUnload，分别在模块被加载和卸载时由Redis核心调用。
模块加载的本质是Redis通过dlopen系列函数将共享库载入进程地址空间，然后查找并执行RedisModule_OnLoad函数。在该函数中，模块通常会调用RedisModule_Init完成初始化，并通过RedisModule_CreateCommand注册新的命令。卸载时则调用RedisModule_OnUnload，用于执行清理工作，例如释放申请的堆内存、关闭文件描述符等。需要注意的是，模块卸载并非一定会成功，如果模块注册的命令正在被客户端执行，或者模块自己持有引用，卸载请求会被拒绝。
与内置命令不同，模块命令拥有自己的命名空间，通常以模块名.命令名的形式出现，例如hellomodule.hello。这种设计避免了不同模块之间的命令冲突。模块还可以注册数据类型、事件处理器、后台线程等，但无论功能多么复杂，加载与卸载的基本原理保持不变。
加载Redis模块
加载Redis模块有两种常用方式：配置文件加载和运行时命令加载。配置文件方式是在redis.conf中添加loadmodule /path/to/module.so，Redis在启动时会自动加载指定的模块。这种方式适合模块需要随Redis实例一起启动的场景，但修改配置后需要重启Redis。运行时加载则使用MODULE LOAD命令，语法为MODULE LOAD /path/to/module.so [arg ...]，后面的可选参数会传递给模块的OnLoad函数。这种方式更加灵活，可以在不中断服务的情况下动态扩展功能。
无论哪种加载方式，Redis都会执行相同的内部流程：首先打开共享库文件并解析符号，然后查找RedisModule_OnLoad函数指针。如果函数不存在，则直接报错并中止加载。接下来构造一个RedisModuleCtx上下文对象，并调用OnLoad函数。模块在OnLoad中调用RedisModule_Init时必须传入模块名称、模块版本和API版本，如果API版本不兼容，RedisModule_Init会返回错误。随后模块可以注册命令、数据类型等。若OnLoad返回REDISMODULE_ERR，加载过程终止，共享库会被卸载。
下面给出一个最简单的模块示例，它注册了一个返回固定字符串的命令。
#include "redismodule.h"
#include <string.h>
int HelloCommand(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) {
RedisModule_ReplyWithSimpleString(ctx, "Hello from module");
return REDISMODULE_OK;
}
int RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) {
// 初始化模块，模块名为hellomodule，版本1，API版本1
if (RedisModule_Init(ctx, "hellomodule", 1, REDISMODULE_APIVER_1) == REDISMODULE_ERR) {
return REDISMODULE_ERR;
}
// 注册命令 hellomodule.hello，只读命令，参数个数固定为1个
if (RedisModule_CreateCommand(ctx, "hellomodule.hello", HelloCommand, "readonly", 1, 1, 1) == REDISMODULE_ERR) {
return REDISMODULE_ERR;
}
return REDISMODULE_OK;
}
编译该模块生成hellomodule.so后，可以在redis-cli中执行MODULE LOAD /path/to/hellomodule.so进行加载。加载成功后执行hellomodule.hello命令即可看到输出。如果加载失败，错误信息会包含具体原因，例如动态库无法打开、API版本不匹配或者OnLoad返回错误等。
卸载Redis模块
卸载模块使用MODULE UNLOAD命令，语法为MODULE UNLOAD modulename，其中modulename是模块在RedisModule_Init中声明的名称，而不是共享库文件名。例如上面示例中的模块名是hellomodule，卸载命令就是MODULE UNLOAD hellomodule。这个设计允许同一个共享库被加载多次，只要模块名不同，就能在Redis中同时运行多个实例。
执行卸载时，Redis首先检查模块注册的命令是否正在被客户端执行。如果存在正在进行的调用，卸载会立即失败并返回错误，提示模块忙。Redis还会检查模块是否创建了后台线程、是否注册了数据类型等复杂资源。只有在确认模块不再被任何客户端引用、且没有其他依赖时，才会调用模块的RedisModule_OnUnload函数执行清理工作。清理完成后，Redis使用dlclose卸载共享库，并释放相关内存。
模块开发人员需要在RedisModule_OnUnload中完成所有必要的资源释放操作。如果遗漏了释放内存或关闭文件描述符，即使模块被成功卸载，也可能造成内存泄漏或文件句柄耗尽。下面展示一个带有清理逻辑的OnUnload实现，假设模块在加载时分配了一个全局缓冲区。
#include "redismodule.h"
#include <stdlib.h>
static char *global_buffer = NULL;
int RedisModule_OnLoad(RedisModuleCtx *ctx, RedisModuleString **argv, int argc) {
if (RedisModule_Init(ctx, "buffer_module", 1, REDISMODULE_APIVER_1) == REDISMODULE_ERR) {
return REDISMODULE_ERR;
}
global_buffer = (char *)malloc(1024);
if (global_buffer == NULL) {
return REDISMODULE_ERR;
}
// 注册命令等...
return REDISMODULE_OK;
}
int RedisModule_OnUnload(RedisModuleCtx *ctx) {
if (global_buffer != NULL) {
free(global_buffer);
global_buffer = NULL;
}
RedisModule_Log(ctx, "notice", "buffer_module unloaded, resources freed");
return REDISMODULE_OK;
}
需要注意的是，卸载模块并不会自动撤销模块注册的命令或其他资源，这些工作必须由开发人员在OnUnload中显式完成。如果模块没有实现OnUnload函数或者实现不完整，卸载后可能出现悬挂指针或命令残留，影响Redis的后续运行。
加载与卸载的常见问题及最佳实践
在实际使用中，模块加载失败的原因多种多样。最常见的是API版本不匹配，例如模块使用REDISMODULE_APIVER_1编译，而运行的Redis只支持API版本2，此时RedisModule_Init会报错。解决方法是使用与Redis版本匹配的头文件重新编译模块。另一个常见问题是动态库依赖缺失，如果模块链接了其他系统库，而这些库在运行环境中不存在，dlopen会失败并提示找不到动态库。建议使用ldd命令检查模块的依赖关系。
对于卸载操作，最需要注意的就是模块忙状态。开发人员应该确保模块命令的执行时间不会过长，否则在卸载时机不巧时可能长时间无法卸载。一种更好的做法是在模块中实现优雅降级：当收到卸载请求时，模块可以拒绝新的命令调用，并等待正在执行的命令完成后自动释放。但Redis核心并不提供这样的自动等待机制，需要模块自行设计。此外，频繁加载和卸载模块会产生内存碎片，建议在开发测试环境中使用，生产环境尽量在启动时加载稳定的模块。
另一个值得关注的实践是模块版本管理。由于模块名是唯一标识，加载不同版本的同一模块需要使用不同的模块名，否则第二次加载会报错。建议在模块名中加入版本号，例如my_module_v1、my_module_v2，这样可以在卸载旧版本的同时平滑切换到新版本。同时，利用MODULE LIST命令可以查看当前已加载模块的状态，包括模块名、版本和加载路径，有助于排查问题。理解加载与卸载的每个细节，能让Redis模块扩展之路更加顺畅。