Nginx 模块的基本结构

由 小路依依 创建， 最后一次修改 2016-08-12 模块的基本结构在这一节我们将会对通常的模块开发过程中，每个模块所包含的一些常用的部分进行说明。这些部分有些是必须的，有些不是必须的。同时这里所列出的这些东西对于其他类型的模块，例如 filter 模块等也都是相同的。模块配置结构基本上每个模块都会提供一些配置指令，以便于用户可以通过配置来控制该模块的行为。那么这些配置信息怎么存储呢？那就需要定义该模块的配置结构来进行存储。大家都知道 Nginx 的配置信息分成了几个作用域(scope,有时也称作上下文)，这就是 main，server 以及 location。同样的每个模块提供的配置指令也可以出现在这几个作用域里。那对于这三个作用域的配置信息，每个模块就需要定义三个不同的数据结构去进行存储。当然，不是每个模块都会在这三个作用域都提供配置指令的。那么也就不一定每个模块都需要定义三个数据结构去存储这些配置信息了。视模块的实现而言，需要几个就定义几个。有一点需要特别注意的就是，在模块的开发过程中，我们最好使用 Nginx 原有的命名习惯。这样跟原代码的契合度更高，看起来也更舒服。对于模块配置信息的定义，命名习惯是ngx_http_<module name>_(main|srv|loc)_conf_t。这里有个例子，就是从我们后面将要展示给大家的 hello module 中截取的。 typedef struct { ngx_str_t hello_string; ngx_int_t hello_counter; }ngx_http_hello_loc_conf_t;模块配置指令一个模块的配置指令是定义在一个静态数组中的。同样地，我们来看一下从 hello module 中截取的模块配置指令的定义。 static ngx_command_t ngx_http_hello_commands[] = { { ngx_string("hello_string"), NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS|NGX_CONF_TAKE1, ngx_http_hello_string, NGX_HTTP_LOC_CONF_OFFSET, offsetof(ngx_http_hello_loc_conf_t, hello_string), NULL }, { ngx_string("hello_counter"), NGX_HTTP_LOC_CONF|NGX_CONF_FLAG, ngx_http_hello_counter, NGX_HTTP_LOC_CONF_OFFSET, offsetof(ngx_http_hello_loc_conf_t, hello_counter), NULL }, ngx_null_command };其实看这个定义，就基本能看出来一些信息。例如，我们是定义了两个配置指令，一个是叫 hello_string，可以接受一个参数，或者是没有参数。另外一个命令是 hello_counter，接受一个 NGX_CONF_FLAG 类型的参数。除此之外，似乎看起来有点迷惑。没有关系，我们来详细看一下 ngx_command_t，一旦我们了解这个结构的详细信息，那么我相信上述这个定义所表达的所有信息就不言自明了。ngx_command_t 的定义，位于src/core/ngx_conf_file.h中。 struct ngx_command_s { 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: 配置指令的名称。type: 该配置的类型，其实更准确一点说，是该配置指令属性的集合。Nginx 提供了很多预定义的属性值（一些宏定义），通过逻辑或运算符可组合在一起，形成对这个配置指令的详细的说明。下面列出可在这里使用的预定义属性值及说明。NGX_CONF_NOARGS：配置指令不接受任何参数。NGX_CONF_TAKE1：配置指令接受 1 个参数。NGX_CONF_TAKE2：配置指令接受 2 个参数。NGX_CONF_TAKE3：配置指令接受 3 个参数。NGX_CONF_TAKE4：配置指令接受 4 个参数。NGX_CONF_TAKE5：配置指令接受 5 个参数。NGX_CONF_TAKE6：配置指令接受 6 个参数。NGX_CONF_TAKE7：配置指令接受 7 个参数。可以组合多个属性，比如一个指令即可以不填参数，也可以接受1个或者2个参数。那么就是NGX_CONF_NOARGS|NGX_CONF_TAKE1|NGX_CONF_TAKE2。如果写上面三个属性在一起，你觉得麻烦，那么没有关系，Nginx 提供了一些定义，使用起来更简洁。NGX_CONF_TAKE12：配置指令接受 1 个或者 2 个参数。NGX_CONF_TAKE13：配置指令接受 1 个或者 3 个参数。NGX_CONF_TAKE23：配置指令接受 2 个或者 3 个参数。NGX_CONF_TAKE123：配置指令接受 1 个或者 2 个或者 3 参数。NGX_CONF_TAKE1234：配置指令接受 1 个或者 2 个或者 3 个或者 4 个参数。NGX_CONF_1MORE：配置指令接受至少一个参数。NGX_CONF_2MORE：配置指令接受至少两个参数。NGX_CONF_MULTI: 配置指令可以接受多个参数，即个数不定。 NGX_CONF_BLOCK：配置指令可以接受的值是一个配置信息块。也就是一对大括号括起来的内容。里面可以再包括很多的配置指令。比如常见的 server 指令就是这个属性的。NGX_CONF_FLAG：配置指令可以接受的值是"on"或者"off"，最终会被转成 bool 值。NGX_CONF_ANY：配置指令可以接受的任意的参数值。一个或者多个，或者"on"或者"off"，或者是配置块。最后要说明的是，无论如何，Nginx 的配置指令的参数个数不可以超过 NGX_CONF_MAX_ARGS 个。目前这个值被定义为 8，也就是不能超过 8 个参数值。下面介绍一组说明配置指令可以出现的位置的属性。NGX_DIRECT_CONF：可以出现在配置文件中最外层。例如已经提供的配置指令 daemon，master_process 等。NGX_MAIN_CONF: http、mail、events、error_log 等。NGX_ANY_CONF: 该配置指令可以出现在任意配置级别上。对于我们编写的大多数模块而言，都是在处理http相关的事情，也就是所谓的都是NGX_HTTP_MODULE，对于这样类型的模块，其配置可能出现的位置也是分为直接出现在http里面，以及其他位置。NGX_HTTP_MAIN_CONF: 可以直接出现在 http 配置指令里。NGX_HTTP_SRV_CONF: 可以出现在 http 里面的 server 配置指令里。NGX_HTTP_LOC_CONF: 可以出现在 http server 块里面的 location 配置指令里。NGX_HTTP_UPS_CONF: 可以出现在 http 里面的 upstream 配置指令里。NGX_HTTP_SIF_CONF: 可以出现在 http 里面的 server 配置指令里的 if 语句所在的 block 中。