Nginx模块开发入门(二)

1. Nginx模块的组成

Nginx模块开发的弹性很大,这部分主要是描述Nginx模块的组成,以及如何编写一个简单的Nginx模块.

1.1 模块的配置结构体

模块可以分为三种类型的配置结构体,分别用在main\server\location三种不同的上下文环境中.大部分的模块仅仅需要定义一个location配置结构.模块的配置结构体的名字的格式为ngx_http_<自定义模块名>_(main|srv|loc)conf_t。例如，

typedef struct {
ngx_uint_t methods; #ngx_uint_t是nginx统一定义的类型，如果你对此感兴趣可以查看文件
ngx_flag_t create_full_put_path;
ngx_uint_t access;
} ngx_http_dav_loc_conf_t;

1.2 模块指令

模块的指令都保存在静态数组中，数组的类型是ngx_command_t，例子如下：

 

static ngx_command_t ngx_http_circle_gif_commands[] = {
{ ngx_string("circle_gif"),        #指令的名字，即存在一条名为circle_gif的指令
NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS, #指令的有效范围为Location，没有参数
ngx_http_circle_gif,               #指令执行时调用的函数
NGX_HTTP_LOC_CONF_OFFSET,          #指令执行的结构存放的位置
0,                                 #存放位置的偏移量
NULL                               #指向模块读配置是的一些零碎的变量，一般为空的},

{ ngx_string("circle_gif_min_radius"),
NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
ngx_conf_set_num_slot,
NGX_HTTP_LOC_CONF_OFFSET,
offsetof(ngx_http_circle_gif_loc_conf_t, min_radius),
NULL },
...
ngx_null_command                   #指令数组的结束标志
};

ngx_command_t结构体的定义在中：

struct ngx_command_t {
ngx_str_t name;
ngx_uint_t type;
char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
ngx_uint_t conf;
ngx_uint_t offset;
void *post;
};

name指令名称不能包含空格，name的类型是ngx_str_t，通常的初始化方式是ngx_str("hello_word");

typedef struct {
    size_t len;
    u_char *data;
} ngx_str_t;

type是一系列的标志，用于标记指令的有效范围和需要的参数数目。

NGX_HTTP_MAIN_CONF: 指令出现在全局配置部分是合法的
· NGX_HTTP_SRV_CONF: 指令在主机配置部分出现是合法的
· NGX_HTTP_LOC_CONF: 指令在位置配置部分出现是合法的
· NGX_HTTP_UPS_CONF: 指令在上游服务器配置部分出现是合法的
· NGX_CONF_NOARGS: 指令没有参数
· NGX_CONF_TAKE1: 指令读入一个参数
· NGX_CONF_TAKE2: 指令读入两个参数
· ...
· NGX_CONF_TAKE7: 指令读入七个参数
· NGX_CONF_FLAG: 指令读入一个布尔型数据
· NGX_CONF_1MORE: 指令至少读入1个参数
· NGX_CONF_2MORE: 指令至少读入2个参数

更多的配置信息可以查看core/ngx_conf_file.h

set是函数指针用于设置模块的配置信息，通常这个函数将指令接受到的参数转化为合适的值，将值的结果存储在配置结构体中，即ngx_http__(main|srv|loc)_conf_t，包含三个重要的参数：

• ngx_conf_t指针，包含指令的参数
• ngx_command_t指针，当前执行的指令
• 模块自定义的配置结构体

当遇到指定是，set函数将会被调用，Nginx提供了一系列的函数累保存特定类型的值，如：

· ngx_conf_set_flag_slot: 将"on"或"off"转化为
· ngx_conf_set_str_slot: 将字符串保存为ngx_str_t类型
· ngx_conf_set_num_slot: 解析一个数字并保存为int型
· ngx_conf_set_size_slot: 解析一个数据大小(如："8k", "1m") 并保存为 size_t类型

这些函数的定义可以在core/ngx_conf_file.h查看，模块也可以自己定义自己的函数，如果是nginx内嵌的值类型，建议使用这些set函数。

那么set函数怎么知道如何存储数据呢？ngx_command_t类型接下来的两个元素conf和offset，指示如何存储数据。conf告诉nginx应该把值存储到main配置、server配置、location配置中的哪个里(使用NGX_HTTP_MAIN_CONF_OFFSET,NGX_HTTP_SRV_CONF_OFFSET或NGX_HTTP_LOC_CONF_OFFSET)，offset标记存储的偏移位置,即指令出现的配置结构体+offset指示变量的具体存储位置。

post指针通常是为NULL。

1.3 The Module Context(模块上下文)

静态的ngx_http_module_t 结构体，包含一组把函数引用。用来创建三个部分的配置和合并配置。一般结构体命名为ngx_http__module_ctx。以此，这些函数引用包括：

• 在读入配置文件前调用
• 在读入配置文件后调用
• 在创建全局部分配置时调用（比如，用来分配空间和设置默认值）
• 在初始化全局部分的配置时调用（比如，把原来的默认值用nginx.conf读到的值来覆盖）
• 在创建主机部分的配置时调用
• 与全局部分配置合并时调用
• 创建位置部分的配置时掉用
• 与主机部分配置合并时调用
  这些函数参数不同，依赖于它们的功能。这里有这个结构体的定义，摘自http/ngx_http_config.h，你可以看到属性各不同的回调函数：