nginx 模块的实现流程
- 初始化
- conf 文件
- 请求处理的流程
关于模块的基础知识，建议先阅读我之前写过的 Nginx: handler 模块的实现，再来看这篇。
1、过滤模块的概念
过滤模块是一种 http 模块，一个请求可以被任意个 http 过滤模块处理，可以根据需要叠加效果或者依次处理，因此常用来处理附加功能，如图片压缩等。
http 过滤模块仅处理服务器发送给客户端的 http 响应，而不处理客户端发往服务器的 http 请求。
http 过滤模块可以选择性处理 http 头部和 http 包体，也可以两者都处理。例如 gzip 过滤模块先处理 http 头部，然后检查 http 头部里的 Content-Type 是否属于配置文件中指定的 gzip 压缩类型，接着处理 http 包体，针对每一块 buffer 缓冲区都进行 gzip 压缩，这样再交给下一个 http 过滤模块处理。
2、过滤模块原理
2.1、过滤链表
所有 http 过滤模块组成一个单链表，http 框架定义两个 static 指针，指向整个链表的第一个元素，分别指向用于处理 http 头部和 http 包体的方法。这个单向链表时围绕着每个文件（http 过滤模块）中的这两个方法来建立的，也就是说，链表中的元素实际上就是处理方法。
typedef ngx_int_t (*ngx_http_output_header_filter_pt)(ngx_http_request_t *r); typedef ngx_int_t (*ngx_http_output_body_filter_pt) (ngx_http_request_t *r, ngx_chain_t *chain); /* 参数 - 参数 r: 当前请求； - 参数 chain：要发送的 http 包体 */ // 单链表的入口 extern ngx_http_output_header_filter_pt ngx_http_top_header_filter extern ngx_http_output_body_filter_pt ngx_http_top_body_filter
当执行 ngx_http_send_header 发送 http 头部时，ngx_http_top_header_filter 指针遍历所有的 http 头部过滤模块，并依次执行；当执行 ngx_http_output_filter 发送 http 包体时，ngx_http_top_body_filter 指针遍历所有的 http 包体过滤模块，并依次执行。
每个 http 过滤模块初始化时，会找到链表的首元素ngx_http_top_header_filter指针和ngx_http_top_body_filter 指针，再使用静态类型的 ngx_http_next_header_filter指针和ngx_http_next_body_filter指针将自己插入到链表的首部，其定义如下。注意两个指针必须是 static 静态变量，仅在当前文件中生效，这就允许所有的过滤模块有各自的指针。
// 定义两个静态指针，分别用于指向下一个过滤模块的 http header 和 http body static ngx_http_output_header_filter_pt ngx_http_next_header_filter; static ngx_http_output_body_filter_pt ngx_http_next_body_filter;
在实际使用中，如果需要调用下一个 http 模块，只需要调用 ngx_http_next_header_filter(r)和ngx_http_next_body_filter(r, chain)即可。
2.2、执行顺序
http 过滤模块的调用顺序由 configure 命令生成。由于每个 http 过滤模块初始化方法都会把自己头插到单链表的首部，所以调用初始化方法的顺序决定过滤模块在链表中的位置。模块的初始化顺序就是 ngx_modules.c 中的 ngx_modules 数组成员的顺序，也可以在 configure 命令执行后，make 编译命令前自行修改。初始化顺序与模块执行顺序相反（头插法）。
3、过滤模块的实现
这里要实现的一个返回给用户的页面增加前缀的过滤模块，如图：Hello World 就是过滤模块添加的前缀。
3.1、编写模块结构
3.1.1、模块配置结构
定义该模块的配置结构来存储配置项（配置命令）。Nginx 的配置信息分为三个作用域 main, server, location，每个模块提供的配置命令需要定义不同的模块配置结构来存储。
typedef struct { ngx_flag_t enable; } ngx_http_myfilter_conf_t;
存储 http 上下文，用于添加前缀。
typedef struct { ngx_int_t add_prefix; } ngx_http_myfilter_ctx_t;
3.1.2、模块配置命令
自定义的 ngx_command_t 类型的 commands 数组
static ngx_command_t ngx_http_myfilter_module_cmds[] = { { ngx_string("add_prefix"), NGX_HTTP_MAIN_CONF | NGX_HTTP_SRV_CONF | NGX_HTTP_LOC_CONF | NGX_CONF_FLAG, ngx_conf_set_flag_slot, NGX_HTTP_LOC_CONF_OFFSET, offsetof(ngx_http_myfilter_conf_t, enable), NULL, }, ngx_null_command };
使用预设的函数 ngx_conf_set_flag_slot 解析命令，作用于 NGX_HTTP_CONTENT_PHASE 阶段。
这里的宏定义 offsetof()：返回一个结构体成员相对于结构体起始的字节偏移量
#define offsetof(s,m) ((size_t)&(((s*)0)->m)) offsetof(type, member-designator)
3.1.3、模块上下文
定义 ngx_http_module_t 类型的 ctx 成员，记录 http 模块的上下文。
static ngx_http_module_t ngx_http_myfilter_module_ctx = { NULL, /* preconfiguration */ ngx_http_myfilter_init, /* postconfiguration */ NULL, /* create main configuration */ NULL, /* init main configuration */ NULL, /* create server configuration */ NULL, /* merge server configuration */ ngx_http_myfilter_create_loc_conf, /* create location configuration */ ngx_http_myfilter_merge_loc_conf, /* merge location configuration */ };
解析配置文件后，http 过滤模块初始化函数
// 定义两个静态指针，分别用于指向下一个过滤模块的 http header 和 http body static ngx_http_output_header_filter_pt ngx_http_next_header_filter; static ngx_http_output_body_filter_pt ngx_http_next_body_filter; // 初始化 http 过滤模块 static ngx_int_t ngx_http_myfilter_init(ngx_conf_t *cf) { // 插入到 http 响应头处理方法链表的首部 ngx_http_next_header_filter = ngx_http_top_header_filter; ngx_http_top_header_filter = ngx_http_myfilter_header_filter; // 插入到 http 响应体处理方法链表的首部 ngx_http_next_body_filter = ngx_http_top_body_filter; ngx_http_top_body_filter = ngx_http_myfilter_body_filter; return NGX_OK; }
loc 配置项回调函数1：分配存储配置项的结构体
void *ngx_http_myfilter_create_loc_conf(ngx_conf_t *cf) { // 创建存储配置项的结构体 ngx_http_myfilter_conf_t *conf = ngx_palloc(cf->pool, sizeof(ngx_http_myfilter_conf_t)); if (conf == NULL) { return NULL; } // 设置当前配置项未使用 // 若使用预设函数 ngx_conf_set_flag_slot 解析配置项参数，则必须初始化为 NGX_CONF_UNSET conf->enable = NGX_CONF_UNSET; return conf; }
loc 配置项回调函数2：合并配置项的方法
char *ngx_http_myfilter_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child) { ngx_http_myfilter_conf_t *prev = (ngx_http_myfilter_conf_t*)parent; ngx_http_myfilter_conf_t *next = (ngx_http_myfilter_conf_t*)child; // 合并 ngx_flag_t 类型的配置项 enable ngx_conf_merge_value(next->enable, prev->enable, 0); return NGX_CONF_OK; }
3.1.4、定义模块
定义 ngx_module_t 类型的变量定义模块本身信息，并添加配置信息，模块上下文信息。
ngx_module_t ngx_http_myfilter_module = { NGX_MODULE_V1, // 宏定义：预设值 &ngx_http_myfilter_module_ctx, /* module context */ ngx_http_myfilter_module_cmd, /* module directives */ NGX_HTTP_MODULE, /* module type */ NULL, /* init master */ NULL, /* init module */ NULL, /* init process */ NULL, /* init thread */ NULL, /* exit thread */ NULL, /* exit process */ NULL, /* exit master */ NGX_MODULE_V1_PADDING // 宏定义：预设值 };
3.2、设置响应头
// 过滤模块的功能：添加前缀 static ngx_str_t prefix = ngx_string("<h2> Hello World !!! </h2>"); // 处理请求中的 http 头部 static ngx_int_t ngx_http_myfilter_header_filter(ngx_http_request_t *r) { ngx_http_myfilter_ctx_t *ctx; ngx_http_myfilter_conf_t *conf; // 若返回的响应码不是200，直接交由下一个过滤模块处理响应码非200的情况 if (r->headers_out.status != NGX_HTTP_OK) { return ngx_http_next_header_filter(r); } // 获取 http 上下文 ctx = ngx_http_get_module_ctx(r, ngx_http_myfilter_module); // 若该请求的上下文已经存在，说明该函数已经被调用，直接交由下一个过滤模块处理 if (ctx) { return ngx_http_next_header_filter(r); } // 获取配置命令 conf = ngx_http_get_module_loc_conf(r, ngx_http_myfilter_module); // 若该配置项的enable成员为0，未开启，直接交由下一个过滤模块处理 if (conf->enable == 0) { return ngx_http_next_header_filter(r); } // 构造 http 上下文 ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_myfilter_ctx_t)); if (ctx == NULL) { return NGX_ERROR; } // 不添加前缀 ctx->add_prefix = 0; // 将构造的上下文设置到当前请求中 ngx_http_set_ctx(r, ctx, ngx_http_myfilter_module); // 自定义过滤模块值处理 Content-Type 是 "text/plain" 类型的 http 响应 if (r->headers_out.content_type.len >= sizeof("text/plain") -1 && ngx_strncasecmp(r->headers_out.content_type.data, (u_char*)"text/plain", sizeof("text/plain") - 1) == 0) { // 设置为1，表示在 http 响应体中添加前缀 ctx->add_prefix = 1; // 添加前缀 prefix 后，http 响应体增加长度 if (r->headers_out.content_length_n > 0) { r->headers_out.content_length_n += prefix.len; } } // 交由下一个过滤模块继续处理 return ngx_http_next_header_filter(r); }
3.3、设置响应体
static ngx_int_t ngx_http_myfilter_body_filter(ngx_http_request_t *r, ngx_chain_t *chain) { ngx_http_myfilter_ctx_t *ctx; ctx = ngx_http_get_module_ctx(r, ngx_http_myfilter_module); // 若获取不到上下文，或者上下文结构体重的 add_prefix 为0或者2，不添加前缀 // 交由下一个过滤模块处理 if (ctx == NULL || ctx->add_prefix != 1) { return ngx_http_next_body_filter(r, chain); } // 设置http响应体中该前缀已添加 ctx->add_prefix = 2; // 从内存池中分配内存，用于存储字符串前缀 ngx_buf_t *b = ngx_create_temp_buf(r->pool, prefix.len); // 将 ngx_buf_t 中的指针正确地指向 prefix 字符串 b->start = b->pos = prefix.data; b->last = b->pos + prefix.len; // 从内存池中生成 ngx_chain_t 链表，将更分配的 ngx_chain_t 设置到 buf 成员中 // 并将它添加到原先待发送的 http 响应体前面 ngx_chain_t *c1 = ngx_alloc_chain_link(r->pool); c1->buf = b; c1->next = chain; // 调用下一个模块的 http body 处理方法，传入新生成的链表 c1 return ngx_http_next_body_filter(r, c1); }
3.4、编译测试
编写配置文件
在对应的模块目录中添加配置文件 config，配置文件中需要定义以下三个变量
# 1、模块名称，仅在 configure 文件执行时使用 ngx_addon_name=ngx_http_myfilter_module # 2、添加新增模块 HTTP_FILTER_MODULES="$HTTP_FILTER_MODULES ngx_http_myfilter_module" # 3、添加新增模块的源代码，多个源代码间用空格符连接 NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_myfilter_module.c"
编译测试
进入 nginx 源码目录，执行 configure 脚本，添加模块所在路径
./configure --add-module=PATH # 例： ./configure --prefix=/usr/local/nginx --with-http_stub_status_module --with-http_ssl_module --with-http_realip_module --with-http_v2_module --with-openssl=../openssl-1.1.1g --add-module=/root/code/ # 这里是我的模块路径
configure 脚本执行完毕后，Nginx 会生成 objs/Makefile 和 objs/ngx_modules.c 两个文件，这里也可以查看到自定义的模块已添加。当然，也可以直接修改这两个文件添加自定义模块。
编译，编译过程中显示自定义模块已添加。
make make install
进入到 nginx 安装目录，在 ./conf/nginx.conf 的 location 块中添加自定义的 add_prefix on命令。
启动 nginx
/usr/local/nginx/sbin/nginx -c /usr/local/nginx/conf/nginx.conf /usr/local/nginx/sbin/nginx -s reload
访问 nginx，可以看到自定义过滤模块的执行效果
3.5、完整代码
#include <ngx_config.h> #include <ngx_core.h> #include <ngx_http.h> // 配置项 typedef struct { ngx_flag_t enable; } ngx_http_myfilter_conf_t; // http 上下文 typedef struct { ngx_int_t add_prefix; } ngx_http_myfilter_ctx_t; // 模块声明 ngx_module_t ngx_http_myfilter_module; // 定义两个静态指针，分别用于指向下一个过滤模块的 http header 和 http body static ngx_http_output_header_filter_pt ngx_http_next_header_filter; static ngx_http_output_body_filter_pt ngx_http_next_body_filter; // 过滤模块的功能：添加前缀 static ngx_str_t prefix = ngx_string("<h2> Hello World !!! </h2>"); // 处理请求中的 http 头部 static ngx_int_t ngx_http_myfilter_header_filter(ngx_http_request_t *r) { ngx_http_myfilter_ctx_t *ctx; ngx_http_myfilter_conf_t *conf; // 若返回的响应码不是200，直接交由下一个过滤模块处理响应码非200的情况 if (r->headers_out.status != NGX_HTTP_OK) { return ngx_http_next_header_filter(r); } // 获取 http 上下文 ctx = ngx_http_get_module_ctx(r, ngx_http_myfilter_module); // 若该请求的上下文已经存在，说明该函数已经被调用，直接交由下一个过滤模块处理 if (ctx) { return ngx_http_next_header_filter(r); } // 获取配置项 conf = ngx_http_get_module_loc_conf(r, ngx_http_myfilter_module); // 若该配置项的 enable 成员为0，配置文件没有配置 add_prefix 配置项，直接交由下一个过滤模块处理 if (conf->enable == 0) { return ngx_http_next_header_filter(r); } // 构造 http 上下文 ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_myfilter_ctx_t)); if (ctx == NULL) { return NGX_ERROR; } // 不添加前缀 ctx->add_prefix = 0; // 将构造的上下文设置到当前请求中 ngx_http_set_ctx(r, ctx, ngx_http_myfilter_module); // 自定义过滤模块值处理 Content-Type 是 "text/plain" 类型的 http 响应 if (r->headers_out.content_type.len >= sizeof("text/plain") -1 && ngx_strncasecmp(r->headers_out.content_type.data, (u_char*)"text/plain", sizeof("text/plain") - 1) == 0) { // 设置为1，表示在 http 响应体中添加前缀 ctx->add_prefix = 1; // 添加前缀 prefix 后，http 响应体增加长度 if (r->headers_out.content_length_n > 0) { r->headers_out.content_length_n += prefix.len; } } // 交由下一个过滤模块继续处理 return ngx_http_next_header_filter(r); } // 处理请求中的 http 包体 static ngx_int_t ngx_http_myfilter_body_filter(ngx_http_request_t *r, ngx_chain_t *chain) { ngx_http_myfilter_ctx_t *ctx; ctx = ngx_http_get_module_ctx(r, ngx_http_myfilter_module); // 若获取不到上下文，或者上下文结构体重的 add_prefix 为0或者2，不添加前缀 // 交由下一个过滤模块处理 if (ctx == NULL || ctx->add_prefix != 1) { return ngx_http_next_body_filter(r, chain); } // 设置http响应体中该前缀已添加 ctx->add_prefix = 2; // 从内存池中分配内存，用于存储字符串前缀 ngx_buf_t *b = ngx_create_temp_buf(r->pool, prefix.len); // 将 ngx_buf_t 中的指针正确地指向 prefix 字符串 b->start = b->pos = prefix.data; b->last = b->pos + prefix.len; // 从内存池中生成 ngx_chain_t 链表，将更分配的 ngx_chain_t 设置到 buf 成员中 // 并将它添加到原先待发送的 http 响应体前面 ngx_chain_t *c1 = ngx_alloc_chain_link(r->pool); c1->buf = b; c1->next = chain; // 调用下一个模块的 http body 处理方法，传入新生成的链表 c1 return ngx_http_next_body_filter(r, c1); } // 初始化 http 过滤模块 static ngx_int_t ngx_http_myfilter_init(ngx_conf_t *cf) { // 插入到 http 响应头处理方法链表的首部 ngx_http_next_header_filter = ngx_http_top_header_filter; ngx_http_top_header_filter = ngx_http_myfilter_header_filter; // 插入到 http 响应体处理方法链表的首部 ngx_http_next_body_filter = ngx_http_top_body_filter; ngx_http_top_body_filter = ngx_http_myfilter_body_filter; return NGX_OK; } // loc 配置项回调函数1：分配存储配置项的结构体 static void *ngx_http_myfilter_create_loc_conf(ngx_conf_t *cf) { // 创建存储配置项的结构体 ngx_http_myfilter_conf_t *conf = ngx_palloc(cf->pool, sizeof(ngx_http_myfilter_conf_t)); if (conf == NULL) { return NULL; } // 设置当前配置项未使用 // 若使用预设函数 ngx_conf_set_flag_slot 解析配置项参数，则必须初始化为 NGX_CONF_UNSET conf->enable = NGX_CONF_UNSET; return conf; } // loc 配置项回调函数2：合并配置项的方法 static char *ngx_http_myfilter_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child) { ngx_http_myfilter_conf_t *prev = (ngx_http_myfilter_conf_t*)parent; ngx_http_myfilter_conf_t *next = (ngx_http_myfilter_conf_t*)child; // 合并 ngx_flag_t 类型的配置项 enable ngx_conf_merge_value(next->enable, prev->enable, 0); return NGX_CONF_OK; } // 定义命令数组 static ngx_command_t ngx_http_myfilter_module_cmds[] = { { ngx_string("add_prefix"), NGX_HTTP_MAIN_CONF | NGX_HTTP_SRV_CONF | NGX_HTTP_LOC_CONF | NGX_CONF_FLAG, ngx_conf_set_flag_slot, NGX_HTTP_LOC_CONF_OFFSET, offsetof(ngx_http_myfilter_conf_t, enable), // 宏定义：返回一个结构体成员相对于结构体起始的偏移量 NULL, }, ngx_null_command }; // 定义 http 模块。记录 http 模块的上下文信息 static ngx_http_module_t ngx_http_myfilter_module_ctx = { NULL, /* preconfiguration */ ngx_http_myfilter_init, /* postconfiguration */ NULL, /* create main configuration */ NULL, /* init main configuration */ NULL, /* create server configuration */ NULL, /* merge server configuration */ ngx_http_myfilter_create_loc_conf, /* create location configuration */ ngx_http_myfilter_merge_loc_conf, /* merge location configuration */ }; // 定义模块。http 过滤模块 ngx_module_t ngx_http_myfilter_module = { NGX_MODULE_V1, &ngx_http_myfilter_module_ctx, ngx_http_myfilter_module_cmds, NGX_HTTP_MODULE, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NGX_MODULE_V1_PADDING };
4、参考
- 陶辉. 深入理解Nginx：模块开发与架构解析[M]. 北京:机械工业出版社,2016.
- 聂松松等. Nginx底层设计与源码分析[M]. 北京:机械工业出版社,2021.
- Nginx 入门指南
