Nginx 模块-细节详探

本文主要基于

http://www.codinglabs.org/html/intro-of-nginx-module-development.html

和

http://www.evanmiller.org/nginx-modules-guide.html#compiling

的学习些的

 

nginx模块要负责三种角色

handler：接收请求+产生Output

filters：处理hander产生的output

load-balancer：负载均衡，选择一个后端server发送请求（如果把nginx当做负载均衡服务器的话，这个角色必须实现）

 

---

nginx内部流程(非常重要)

图片讲解：

英文讲解：

Client sends HTTP request → Nginx chooses the appropriate handler based on the location config → (if applicable) load-balancer picks a backend server → Handler does its thing and passes each output buffer to the first filter → First filter passes the output to the second filter → second to third → third to fourth → etc. → Final response sent to client

中文讲解：

客户端发送http请求 -- nginx根据配置文件conf中的location来确定由哪个handler处理-- handler执行完request返回output给filter--第一个filter处理output -- 第二个filter处理output--- … -- 生成Response

 

---

Nginx模块的几个数据结构

1 Module Configuration Struct(s) 模块配置结构

2 Module Directives 模块命令结构

3 The Module Context模块内容

3.1 create_loc_conf

3.2 merge_loc_conf

4 The Module Definition模块整合

5 Module Installation模块安装

 

 

1 模块配置结构：

这个结构的命名规则为ngx_http_[module-name]_[main|srv|loc]_conf_t。

main,srv,loc表示这个模块的作用范围是配置文件中的main/server/location三种范围（这个需要记住，后面会经常用到）

例子：

typedef struct {
ngx_str_t ed; //echo模块只有一个参数 比如 echo "hello"
} ngx_http_echo_loc_conf_t; //echo 模块

2 模块命令结构：
例子：

static ngx_command_t ngx_http_echo_commands[] = {
{ ngx_string("echo"), //命令名字
NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1, //代表是local配置，带一个参数
ngx_http_echo, //组装模块配置结构
NGX_HTTP_LOC_CONF_OFFSET, //上面的组装模块配置获取完参数后存放到哪里？使用这个和下面的offset参数来进行定位
offsetof(ngx_http_echo_loc_conf_t, ed), //同上
NULL // Finally, post is just a pointer to other crap the module might need while it's reading the configuration. It's often NULL.我也没理解是什么意思。通常情况下设置为NULL
},
ngx_null_command //必须使用ngx_null_command作为commands的结束标记
};

 

注1：

ngx_http_echo 是组装模块配置结构的函数指针，有三个参数：

ngx_conf_t *cf 包含这个命令的所有参数

ngx_command_t *cmd 执行这个command命令结构的指针

void *conf 模块订制的配置结构

这个函数比较不好理解，其功能是把参数传到命令结构体中，并且把合适的值放入到模块配置结构中。我们称之为"setup function"。它会在命令运行的时候被调用。

nginx已经提供了几个现成的方法了：

ngx_conf_set_flag_slot

ngx_conf_set_str_slot

ngx_conf_set_num_slot

ngx_conf_set_size_slot

…

所以你可以这样定义cmd:

{ ngx_string("add_after_body"),
NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
ngx_conf_set_str_slot,
NGX_HTTP_LOC_CONF_OFFSET,
offsetof(ngx_http_addition_conf_t, after_body),
NULL },

也可以这样：

static ngx_command_t ngx_http_echo_commands[] = {
{ ngx_string("echo"),
NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
ngx_http_echo,
NGX_HTTP_LOC_CONF_OFFSET,
offsetof(ngx_http_echo_loc_conf_t, ed),
NULL },
ngx_null_command
};
static char *
ngx_http_echo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
ngx_http_core_loc_conf_t *clcf;
clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
clcf->handler = ngx_http_echo_handler; //这里指定了handler，那么就会使用新的handler进行处理
ngx_conf_set_str_slot(cf,cmd,conf); //这里还是使用系统的函数
return NGX_CONF_OK;
}

3 模块内容

static ngx_http_module_t ngx_http_circle_gif_module_ctx = {

NULL, /* preconfiguration */

NULL, /* postconfiguration 这里是放置filter的地方，在filter章节会说*/

NULL, /* create main configuration */

NULL, /* init main configuration */

NULL, /* create server configuration */

NULL, /* merge server configuration */

ngx_http_circle_gif_create_loc_conf, /* create location configuration */

ngx_http_circle_gif_merge_loc_conf /* merge location configuration */

};

模块的内容ngx_http_<module name>_module_ctx是为了定义各种钩子函数，就是nginx在各个不同的时期将会运行的函数。

一般的location只需要配置create location configuration（在创建location配置的时候运行）和merge location configuration（和server config如何合并，一般包含如果配置有错误的话应该抛出异常）

这两个函数的例子：（来自https://github.com/evanmiller/nginx_circle_gif/）

static void *

ngx_http_circle_gif_create_loc_conf(ngx_conf_t *cf)

{

ngx_http_circle_gif_loc_conf_t *conf;

conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_circle_gif_loc_conf_t));

if (conf == NULL) {

return NGX_CONF_ERROR;

}

conf->min_radius = NGX_CONF_UNSET_UINT; //对conf中的每个参数进行配置，min_redius和max_redius是nginx_circle_gif模块的配置结构的字段

conf->max_radius = NGX_CONF_UNSET_UINT;

return conf;

}

和

static char *

ngx_http_circle_gif_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)

{

ngx_http_circle_gif_loc_conf_t *prev = parent; //server的loc配置

ngx_http_circle_gif_loc_conf_t *conf = child; // 自己的loca配置

ngx_conf_merge_uint_value(conf->min_radius, prev->min_radius, 10);

ngx_conf_merge_uint_value(conf->max_radius, prev->max_radius, 20);

if (conf->min_radius < 1) {

ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,

"min_radius must be equal or more than 1");

return NGX_CONF_ERROR; //这里负责抛出错误

}

if (conf->max_radius < conf->min_radius) {

ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,

"max_radius must be equal or more than min_radius");

return NGX_CONF_ERROR; //这里负责抛出错误

}

return NGX_CONF_OK;

}

注1 ： ngx_conf_merge_uint_value是nginx core中自带的函数

ngx_conf_merge_<data type>_value

ngx_conf_merge_uint_value(conf->min_radius, prev->min_radius, 10);的意思是：

如果设置了conf->min_redius的话使用conf->min_redius

如果没有设置conf->min_redius的话使用 prev->min_radius

如果两个都没有设置的话使用10

更多函数请看 core/ngx_conf_file.h

4 模块整合

ngx_module_t ngx_http_<module name>_module = {

NGX_MODULE_V1,

&ngx_http_<module name>_module_ctx, /* module context 模块内容 */

ngx_http_<module name>_commands, /* module directives 模块命令*/

NGX_HTTP_MODULE, /* module type 模块类型，HTTP模块，或者HTTPS*/

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

};

5 模块安装

模块安装文件的编写依赖于这个模块是handler,filter还是load-balancer的工作角色

下面开始是Handler，filter,load-balancer的编写和安装

1 Handler安装

还记得在模块命令的时候有设置handler的语句吗？

clcf->handler = ngx_http_echo_handler;

这个语句就是handler的安装

2 Handler编写

Handler的执行有四部：

读入模块配置

处理功能业务

产生HTTP header

产生HTTP body

读入模块配置

例子：

static ngx_int_t
ngx_http_circle_gif_handler(ngx_http_request_t *r)
{
ngx_http_circle_gif_loc_conf_t *circle_gif_config;
circle_gif_config = ngx_http_get_module_loc_conf(r, ngx_http_circle_gif_module);
...

就是使用nginx已经有的函数ngx_http_get_module_loc_conf,第一个参数是当前请求，第二个参数是前面写好的模块

处理功能业务

这个部分是我们要模块处理的实际部分

用需求举例：

这个模块有个命令是 getRedisInfo 192.168.0.1 //获取redis的信息

那么这个功能业务就是(伪代码)：

case cmd->opcode

{

"getRedisInfo" :

获取redis 的信息

}

这里应该把所有这个模块设置的命令的业务逻辑都写好

产生HTTP Header

例子：

r->headers_out.status = NGX_HTTP_OK;

r->headers_out.content_length_n = 100;

r->headers_out.content_type.len = sizeof("image/gif") - 1;

r->headers_out.content_type.data = (u_char *) "image/gif";

ngx_http_send_header(r);

产生HTTP Body

这个部分是最重要的一步

借用codingLabs的图讲解一下nginx的IO

handler是可以一次产生出一个输出，也可以产生出多个输出使用ngx_chain_t的链表来进行连接

struct ngx_chain_s {

ngx_buf_t *buf;

ngx_chain_t *next;

};

buf中有pos和last来代表out数据在内存中的位置，next是代表下一个ngx_chain_t

下面来说一下只有一个ngx_chain_t的设置

1 申明

ngx_buf_t *b;

ngx_chain_t out

2 设置buffer

b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t));

if (b == NULL) {

ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,

"Failed to allocate response buffer.");

return NGX_HTTP_INTERNAL_SERVER_ERROR;

}

b->pos = some_bytes; /* first position in memory of the data */

b->last = some_bytes + some_bytes_length; /* last position */

b->memory = 1; /* content is in read-only memory */

/* (i.e., filters should copy it rather than rewrite in place) */

b->last_buf = 1; /* there will be no more buffers in the request */

3 模块加入链表

out.buf = b;

out.next = NULL; //如果有下一个链表可以放到这里

4 返回

return ngx_http_output_filter(r, &out);

 

 

2 Filter的编写和安装

Filter作为过滤器又可以细分为两个过滤器: Header filters 和 body filters

 

Filter的安装

filter是在模块内容设置的时候加上的

例子：

static ngx_http_module_t ngx_http_chunked_filter_module_ctx = {

NULL, /* preconfiguration */

ngx_http_chunked_filter_init, /* postconfiguration */

...

};

static ngx_int_t

ngx_http_chunked_filter_init(ngx_conf_t *cf)

{

ngx_http_next_header_filter = ngx_http_top_header_filter;

ngx_http_top_header_filter = ngx_http_chunked_header_filter;

ngx_http_next_body_filter = ngx_http_top_body_filter;

ngx_http_top_body_filter = ngx_http_chunked_body_filter;

return NGX_OK;

}

注1: ngx_http_top_hreader_filter是什么意思呢？

当handler生成了response的时候，它调用了两个方法：ngx_http_output_filter和ngx_http_send_header

ngx_http_output_filter会调用ngx_http_top_body_filter

ngx_http_send_header会调用ngx_top_header_filter

Filter的编写

Header filters

分为三个部分：

是否操作这个handler的response

操作response

调用下一个filter

例子：

static
ngx_int_t ngx_http_not_modified_header_filter(ngx_http_request_t *r)
{
time_t if_modified_since;
if_modified_since = ngx_http_parse_time(r->headers_in.if_modified_since->value.data,
r->headers_in.if_modified_since->value.len);
/* step 1: decide whether to operate */
if (if_modified_since != NGX_ERROR &&
if_modified_since == r->headers_out.last_modified_time) {
/* step 2: operate on the header */
r->headers_out.status = NGX_HTTP_NOT_MODIFIED; //返回304
r->headers_out.content_type.len = 0; //长度设置为0
ngx_http_clear_content_length(r); //清空
ngx_http_clear_accept_ranges(r); //清空
}
/* step 3: call the next filter */
return ngx_http_next_header_filter(r);
}

Body filters

假设有个需求：在每个request后面插入"<l!-- Served by Nginx -->"

1 要找出最后chain的最后一个buf

ngx_chain_t *chain_link;
int chain_contains_last_buffer = 0;
for ( chain_link = in; chain_link != NULL; chain_link = chain_link->next ) {
if (chain_link->buf->last_buf)
chain_contains_last_buffer = 1;
}

2 创建一个新的buf

ngx_buf_t *b;
b = ngx_calloc_buf(r->pool);
if (b == NULL) {
return NGX_ERROR;
}

3 放数据在新buf上

b->pos = (u_char *) "<!-- Served by Nginx -->";
b->last = b->pos + sizeof("<!-- Served by Nginx -->") - 1;

4 把新buf放入一个新chain_t

ngx_chain_t *added_link;
added_link = ngx_alloc_chain_link(r->pool);
if (added_link == NULL)
return NGX_ERROR;
added_link->buf = b;
added_link->next = NULL;

5 把新的chain链接到原来的chain_link中

chain_link->next = added_link;

6 重新设置last_buf

chain_link->buf->last_buf = 0;

added_link->buf->last_buf = 1;

7 传给下一个filter

return ngx_http_next_body_filter(r, in);

 

最后一点是如何写和编译nginx模块

必须写两个文件config和ngx_http_<your module>_module.c

其中config会被./configure包含

ngx_addon_name=ngx_http_<your module>_module

HTTP_MODULES="$HTTP_MODULES ngx_http_<your module>_module"

NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_<your module>_module.c"

几乎都是填空

ngx_http_<your module>_module.c文件就是你的所有模块代码

 

编译nginx：

./configure --add-module=path/to/your/new/module/directory #这里是config放置的地方

 

----------------------

作者：yjf512（轩脉刃）

出处：http://www.cnblogs.com/yjf512/

本文版权归yjf512和cnBlog共有，欢迎转载，但未经作者同意必须保留此段声明