《深入理解Nginx》阅读与实践（二）：配置项的使用

　　前文链接：《深入理解Nginx》阅读与实践（一）：Nginx安装配置与HelloWorld

 

　　HelloWorld的完成意味着已经踏入了nginx的大门，虽然很振奋人心，但在编写中仍有很多疑惑的存在：nginx.conf的配置项中各个参数是如何读入程序中的？ngx_command_t如何完成配置项的读入工作？名称相同的配置项的冲突如何解决？HelloWorld中的ngx_http_module_t何以称为模块的上下文？同时我在读第4章"配置项的使用"时又有成见：不就是各种琐碎的参数设置嘛，有什么好读的？（这个成见来自于UNP中某一章节套接字选项）不过经过仔细阅读并实践这部分内容之后，我发现完全八竿子打不着要点。其实这里的配置项的使用，是指将我们在nginx.conf中设置的配置项的参数传递到nginx程序的过程。同时，经过这一章，你将学到如何将一个“根据用户请求的URI返回HelloWorld的模块”变成一个“可以完成解析各种nginx配置项的模块”。

 

一、存放配置项的值的数据结构

　　先来看看文中介绍的保存配置参数的数据结构ngx_http_mytest_conf_t：

typedef struct {
    ngx_str_t       my_str;
    ngx_int_t       my_num;
    ngx_flag_t      my_flag;
    size_t          my_size;
    ngx_array_t*    my_str_array;
    ngx_array_t*    my_keyval;
    off_t            my_off;
    ngx_msec_t      my_msec;
    time_t          my_sec;
    ngx_bufs_t      my_bufs;
    ngx_uint_t      my_enum_seq;
    ngx_uint_t      my_bitmask;
    ngx_uint_t      my_access;
    ngx_path_t*     my_path;
} ngx_http_mytest_conf_t;

　　与原书提到的问题（为什么不用全局变量来存储）不同，我的问题是，既然想要统一用一个结构体存放各种各样的配置项如整数、标记（非0即1）、字符串、时间等等，为什么不用一个联合从而节省空间？带着疑问继续往下读才会发现：这里的数据结构是为了便于后面说明预设配置项解析方法而定义的，它能处理的配置项是下面这种形式：

name [ngx_str_t] [ngx_int_t] ... [ngx_path_t*] [[ngx_str_t][ngx_int_t]]

这种配置项的名称后面可以跟着14种参数以及在后文定义的myconfig的2个参数，这16个参数可以全部出现，也可以只出现其中之一。也即，它的功能并不是仅仅处理配置项名+单一参数的配置项，而是所有可能形式的配置项。这样复杂在所难免，如果实际使用的配置项是我们所能控制的有限几种，没有必要设计这么复杂，正如HelloWorld中mytest配置项后根本就没有值，只是设立了个遇到该配置项就启动mytest模块的函数而已，那时甚至没有必要设计这么一个保存配置项的值的结构。

 

二、对配置项的值的操作：读取与合并

　　回顾HelloWorld中的代表模块上下文的ngx_http_module_t结构，之前虽然提到它是模块的上下文，使得模块具有自己的特性，但当时把它的8个回调方法都设置成了NULL，也看不出什么名堂。这时《深入理解Nginx》对它做了个回顾并说明，我是这样理解的：所谓“上文”，就是做preconfiguration的工作、处理nginx.conf的配置项（将所有配置项读入、建立数据结构保存、各级同名配置项合并）；“下文”就是在处理完配置项后调用函数postconfiguration进行一些后续工作。

static ngx_http_module_t  ngx_http_mytest_module_ctx =
{
    NULL,                              /* preconfiguration */
    ngx_http_mytest_post_conf,      /* postconfiguration */

    NULL,                              /* create main configuration */
    NULL,                              /* init main configuration */

    NULL,                              /* create server configuration */
    NULL,                              /* merge server configuration */

    ngx_http_mytest_create_loc_conf, /* create location configuration */
    ngx_http_mytest_merge_loc_conf   /* merge location configuration */
};

　　为了便于说明，这里只实现了create_loc_conf和merge_loc_conf，前者在nginx.conf中的每一个http{...}、server{...}、location{...}都会调用来为ngx_http_mytest_conf_t赋初值；后者用来合并create_loc_conf生成的所有ngx_http_mytest_conf_t的配置项。

　　除此以外，为了打印出读取的配置项的值，需要实现ngx_http_mytest_post_conf，在处理完配置项后调用。这样，模块的上下文便写好了。

关于create_loc_conf、create_srv_conf、create_main_conf的调用时机：

　　create_loc_conf是遇到每一个http{...}、server{...}、location{...}时；

　　create_srv_conf是遇到每一个server{...}、location{...}时；

　　create_main_conf只在遇到http{...}时。

　　这个细节可以参考原书。

关于merge_srv_conf的调用作用：合并main级别和server级别的配置项，请参考10.2.4。

 

　　这时就可以通过设定ngx_command_s来设定配置项的解析方式了，简单概括就是配置项的名称、它所能出现的位置、对值处理的回调方法也即解析方法、值存放于之前定义的数据结构的偏移量。这一系列解析方式构成了一个数组，用来解析所有可能出现的配置项的形式。这里原书说的比较详细，就不再重复。对应14种配置项的值的类型，书上讲了14种解析方式和针对自定义配置项的处理方法（对应的回调函数是ngx_conf_set_myconfig）。

　　这里不得不提一下ngx_conf_t类型。原书中多次出现在函数原型形参中但并未提及，我查了一些资料，它的定义如下：

struct ngx_conf_s {
    char                 *name;
    ngx_array_t          *args;

    ngx_cycle_t          *cycle;
    ngx_pool_t           *pool;
    ngx_pool_t           *temp_pool;
    ngx_conf_file_t      *conf_file;
    ngx_log_t            *log;

    void                 *ctx;
    ngx_uint_t            module_type;
    ngx_uint_t            cmd_type;

    ngx_conf_handler_pt   handler;
    char                 *handler_conf;
};

在http://kenby.iteye.com/blog/1169675中提到，“解析配置文件的时候, 用结构体ngx_conf_s来暂时存放指令的参数”。同时查阅nginx源码，排除掉作为函数形参时的出现，出现在下面几处，作用和这个描述很类似：

　　src\core\Ngx_cycle.c

　　src\event\Ngx_event.c

　　src\http\Ngx_http.c 

　　src\http\Ngx_http_script.h

　　src\mail\Ngx_mail.c

　　那么就暂时不去管它，当作一个中间数据的结构体就行了。

 

　　原书以test_str配置项为例，编写了用于合并test_str类型的ngx_http_mytest_loc_conf()函数，并可以看出当父子配置块有相同配置项的处理方法：以父配置块为准或子配置块为准均可，可以自由选择，或者进行运算生成。原书后文是更详细的配置块合并时的数据结构存储模型和合并逻辑的概括，值得仔细揣摩。

 

三、error日志和请求上下文

　　这一部分没有什么好写的，原书已经很详细了。不过error日志的输出会在后面用到。

 

四、把HelloWorld变成配置项输出

　　按着第4章的线索，对HelloWorld做出相应修改就能完成这个转变了。其实整体逻辑组成和第3章图示差不多，只是具体实现方法不大一样：

1. 定义结构体ngx_http_mytest_conf_t；
2. 原先的ngx_module_t类型ngx_http_mytest_module以及config文件保持不变；
3. 将原先的所有成员为空的模块上下文ngx_http_module_t进行修改，添加回调函数create_loc_conf()、merge_loc_conf()、ngx_http_mytest_post_conf()并实现（ngx_http_mytest_post_conf()可以放在最后来进行）；
4. 为所有值类型编写解析方式ngx_command_t  ngx_http_mytest_commands[]替代原先的，在此之前需要实现解析自定义类型的ngx_conf_set_myconfig()方法；
5. 原先用于处理HTTP报文并返回请求的ngx_http_mytest_handler已无用，删去；
6. 编写ngx_http_mytest_post_conf()取的不是这个模块的信息而是已传递给ngx_http_module和ngx_http_core_module的数据因此需要在源码中extern进二者。ngx_http_mytest_post_conf()的具体实现有些超出本章内容，不做详解。
7. 将nginx.conf修改，在各个配置块中增加test_str，重新编译运行源码，就可以在屏幕上看到相应的输出了，如下图所示：

 

　　完整的源码可以在《深入理解Nginx》作者的页面上进行下载：http://nginx.weebly.com/31034203632830430721.html