nginx的filter模块

过滤（filter）模块是过滤响应头和内容的模块，可以对回复的头和内容进行处理。它的处理时间是在获取回复服务端内容之后，向用户发送响应之前。它的处理过程分为两个阶段，过滤 http回复的头部和主体，在这两个阶段可以分别对头部和主体进行修改，可以放在server或location模块。nginx代码中的函数

ngx_http_top_header_filter(r);
ngx_http_top_body_filter(r, in);

就是分别对头部和主体进行过滤的函数。所有模块的响应内容要返回给客户端，都必须调用这两个接口。
注意与handler模块的区分，handler模块是拿客户端请求的信息（req）进行修改，再放到返回信息中；filter是拿服务端返回的信息（response）进行修改的；另外，upstream模块只做转发，不修改信息。

过滤模块的执行顺序

过滤模块的调用是有顺序的，它的顺序在编译的时候就决定了。当编译完 nginx 以后，可以在 objs 目录下面看到一个 ngx_modules.c 的文件

ngx_module_t *ngx_modules[] = {
    ...
    &ngx_http_write_filter_module,
    &ngx_http_header_filter_module,
    &ngx_http_chunked_filter_module,
    &ngx_http_range_header_filter_module,
    &ngx_http_gzip_filter_module,
    &ngx_http_postpone_filter_module,
    &ngx_http_ssi_filter_module,
    &ngx_http_charset_filter_module,
    &ngx_http_userid_filter_module,
    &ngx_http_headers_filter_module,
    &ngx_http_copy_filter_module,
    &ngx_http_range_body_filter_module,
    &ngx_http_not_modified_filter_module,
    NULL
};

这些是nginx自带的过滤模块。从 write_filter 到 not_modified_filter，模块的执行顺序是反向的。也就是说最早执行的是 not_modified_filter，然后各个模块依次执行。这些模块的执行顺序无法改变。所有第三方的模块只能加入到 copy_filter 和headers_filter 模块之间执行，这些模块的执行顺序可以根据业务场景自己确定。
nginx 执行的时候是怎么按照次序依次来执行各个过滤模块呢？它采用了一种很隐晦的方法，即通过静态的全局变量。比如，在每个 filter 模块，很可能看到如下代码

static ngx_http_output_header_filter_pt 
ngx_http_next_header_filter;
static ngx_http_output_body_filter_pt 
ngx_http_next_body_filter;
...
ngx_http_next_header_filter = ngx_http_top_header_filter;
ngx_http_top_header_filter = ngx_http_example_header_filter;
ngx_http_next_body_filter = ngx_http_top_body_filter;
ngx_http_top_body_filter = ngx_http_example_body_filter;

可以看出，过滤模块是用了类似链表的结构，通过头插法将各个模块添加进来的。ngx_http_top_header_filter 是一个全局变量。当编译进一个 filter 模块的时候，就被赋值为当前 filter 模块的处理函数。而 ngx_http_next_header_filter 是一个局部全局变量，它保存了编译前上一个 filter 模块的处理函数。所以整体看来，就像用全局变量组成的一条单向链表。
每个模块想执行下一个过滤函数，只要调用一下 ngx_http_next_header_filter 这个局部变量。而整个过滤模块链的入口，需要调用 ngx_http_top_header_filter 这个全局变量。ngx_http_top_body_filter 的行为与 header fitler 类似。

相应接口

响应头过滤函数

响应头过滤函数主要的用处就是处理服务端 http响应的头，可以根据实际情况对于响应头进行修改或者添加删除。响应头过滤函数先于响应体过滤函数，而且只调用一次，所以一般可作过滤模块的初始化工作。
响应头过滤函数的入口只有一个：

ngx_int_t ngx_http_send_header(ngx_http_request_t *r)
{
    ...
    return ngx_http_top_header_filter(r);
}

该函数在向客户端发送回复的时候调用，然后按刚才所讲的执行顺序。该函数的返回值一般是 NGX_OK，NGX_ERROR 和 NGX_AGAIN，分别表示处理成功、失败和未完成。
可以把 http响应头的存储方式想象成一个 hash 表，在 nginx 内部可以很方便地查找和修改各个响应头部，ngx_http_header_filter_module 过滤模块把所有的 http 头组合成一个完整的 buffer，最终 ngx_http_write_filter_module 过滤模块把 buffer 输出。

响应体过滤函数

响应体过滤函数是过滤响应主体的函数。ngx_http_top_body_filter 这个函数每个请求可能会被执行多次，它的入口函数是 ngx_http_output_filter

ngx_int_t ngx_http_output_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ngx_int_t rc;
    ngx_connection_t *c;
    c = r->connection;
    rc = ngx_http_top_body_filter(r, in);
    if (rc == NGX_ERROR) {
        /* NGX_ERROR may be returned by any filter */
        c->error = 1;
    }
    return rc;
}

ngx_http_output_filter 可以被一般的静态处理模块调用，也有可能是在 upstream 模块里面被调用，对于整个请求的处理阶段来说，他们处于的用处都是一样的，都是把响应内容过滤，然后发给客户端。具体模块的响应体过滤函数的格式类似这样：

static int ngx_http_example_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ...
    return ngx_http_next_body_filter(r, in);
}

这里再啰嗦一下数据结构，感觉之前buf数据结构讲得不是很清楚。

typedef struct ngx_chain_s ngx_chain_t;

struct ngx_chain_s {
    ngx_buf_t *buf;
    ngx_chain_t *next;
};

一次send所有数据，不如多次send发送各部分数据。多次send会更安全一些，这也是chain的意义。

struct ngx_buf_s {
    u_char *pos; /* 当前 buffer 真实内容的起始位置 */
    u_char *last; /* 当前 buffer 真实内容的结束位置 */
    off_t file_pos; /* 在文件中真实内容的起始位置 */
    off_t file_last; /* 在文件中真实内容的结束位置 */
    u_char *start; /* buffer 内存的开始分配的位置 */
    u_char *end; /* buffer 内存的结束分配的位置 */
    ...
};

buf结构体的各个指针示意图

模块编译和安装

编译和安装步骤与handler基本一致，这里主要注意conf文件与handler的有些不同。

ngx_addon_name=ngx_http_example_filter_module
HTTP_AUX_FILTER_MODULES="$HTTP_AUX_FILTER_MODULES 
ngx_http_example_filter_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS 
$ngx_addon_dir/ngx_http_example_filter_module.c"

注意HTTP_AUX_FILTER_MODULES这个变量与一般的内容处理模块不同。

部分实例代码

下面给出一个filter实例的部分代码，可以看出，基本框架与handler模块的一致。

static void* ngx_http_myfilter_create_conf(ngx_conf_t *cf)
{
    ngx_http_myfilter_conf_t *mycf;
    mycf = (ngx_http_myfilter_conf_t *)ngx_pcalloc(cf->pool,sizeof(ngx_http_myfilter_conf_t));
    if(mycf == NULL) {
        return NULL;
    }
    mycf->enable = NGX_CONF_UNSET;
    return mycf;
}

static char* ngx_http_myfilter_merge_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 *conf = (ngx_http_myfilter_conf_t *)child;

    ngx_conf_merge_value(conf->enable,prev->enable,0);
    return NGX_CONF_OK;
}

static ngx_command_t ngx_http_mytest_commands[] = {
    {
        ngx_string("add_prefix"),
        NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_HTTP_LMT_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
};

static ngx_http_module_t ngx_http_myfilter_module_ctx = {
    NULL,
    ngx_http_myfilter_init,
    NULL,
    NULL,

    NULL,
    NULL,
    ngx_http_myfilter_create_conf,
    ngx_http_myfilter_merge_conf
};

ngx_module_t ngx_http_myfilter_module = {
    NGX_MODULE_V1,
    &ngx_http_myfilter_module_ctx,
    ngx_http_mytest_commands,
    NGX_HTTP_MODULE,
    NULL,
    NULL,
    NULL,
    NULL,
    NULL,
    NULL,
    NULL,
    NGX_MODULE_V1_PADDING
};

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_int_t ngx_http_myfilter_init(ngx_conf_t *cf)
{
    ngx_http_next_header_filter = ngx_http_top_header_filter;
    ngx_http_top_header_filter = ngx_http_myfilter_header_filter;


    ngx_http_next_body_filter = ngx_http_top_body_filter;
    ngx_http_top_body_filter = ngx_http_myfilter_body_filter;
    return NGX_OK;
}