Nginx读书笔记(4) —— HTTP模块的数据结构

古城微笑少年丶 2021-12-21 17:53 189阅读 0赞

## **HTTP模块的数据结构** ##

定义HTTP模块方式很简单,例如:

ngx\_module\_t ngx\_http\_mytest\_module;

其中,ngx\_module\_t是一个Nginx模块的数据结构。下面来分析一下Nginx模块中所有的成员,如下所示:

typedef struct ngx_module_s ngx_module_t;
    
    
    
    struct ngx_module_s
    
    {
    
    /* 下面的ctx_index、index、spare0、spare1、spare2、spare3、version变量不需要在定义时赋值,可以用Nginx准备好的宏NGX_MODULE_V1来定义,它已经定义好了这7个值。
    
    #define NGX_MODULE_V1    0, 0, 0, 0, 0, 0, 1
    
    对于一类模块(由下面的type成员决定类别)而言,ctx_index表示当前模块在这类模块中的序号。这个成员常常是由管理这类模块的一个Nginx核心模块设置的,对于所有的HTTP模块而言,ctx_index是由核心模块ngx_http_module设置的。
    
    ctx_index非常重要,Nginx的模块化设计非常依赖于各个模块的顺序,它们既用于表达优先级,也用于表明每个模块的位置,借以帮助Nginx框架快速获得某个模块的数据。
    
    */
    
    ngx_uint_t  ctx_index;
    
    
    
    /*index表示当前模块在ngx_modules数组中的序号。注意,ctx_index表示的是当前模块在一类模块中的序号,而index表示当前模块在所有模块中的序号,它同样关键。
    
    Nginx启动时会根据ngx_modules数组设置各模块的index值。
    
    例如:
    
    ngx_max_module = 0;
    
    for (i = 0; ngx_modules[i]; i++) 
    
    {
    
        ngx_modules[i]->index = ngx_max_module++; 
    
    }
    
    */
    
    ngx_uint_t  index;
    
    
    
    // spare系列的保留变量,暂未使用
    
    ngx_uint_t spare0;
    
    ngx_uint_t spare1;
    
    ngx_uint_t spare2;
    
    ngx_uint_t spare3;
    
    
    
    // 模块的版本,便于将来的扩展。目前只有一种,默认为1
    
    ngx_uint_t  version;
    
    
    
    /*ctx用于指向一类模块的上下文结构体,为什么需要ctx呢?因为前面说过,Nginx模块有许多种类,不同类模块之间的功能差别很大。
    
    例如,事件类型的模块主要处理I/O事件相关的功能,HTTP类型的模块主要处理HTTP应用层的功能。这样,每个模块都有了自己的特性,而ctx将会指向特定类型模块的公共接口。
    
    例如,在HTTP模块中,ctx需要指向ngx_http_module_t结构体
    
    */
    
    void  *ctx;
    
    
    
    // commands将处理nginx.conf中的配置项
    
    ngx_command_t  *commands;
    
    
    
    /*type表示该模块的类型,它与ctx指针是紧密相关的。在官方Nginx中,它的取值范围是以下5种:
    
    NGX_HTTP_MODULE、
    
    NGX_CORE_MODULE、
    
    NGX_CONF_MODULE、
    
    NGX_EVENT_MODULE、
    
    NGX_MAIL_MODULE。
    
    实际上,还可以自定义新的模块类型
    
    */
    
    ngx_uint_t  type;
    
    
    
    /*在Nginx的启动、停止过程中,以下7个函数指针表示有7个执行点会分别调用这7种方法。对于任一个方法而言,如果不需要Nginx在某个时刻执行它,那么简单地把它设为NULL空指针即可
    
    */
    
    /*虽然从字面上理解应当在master进程启动时回调init_master,但到目前为止,框架代码从来不会调用它,因此,可将init_master设为NULL 
    
    */
    
    ngx_int_t  (*init_master)(ngx_log_t *log);
    
    
    
    /*init_module回调方法在初始化所有模块时被调用。在master/worker模式下,这个阶段将在启动worker子进程前完成
    
    */
    
    ngx_int_t  (*init_module)(ngx_cycle_t *cycle);
    
    
    
    /* init_process回调方法在正常服务前被调用。在master/worker模式下,多个worker子进程已经产生,在每个worker进程的初始化过程会调用所有模块的init_process函数
    
    */
    
    ngx_int_t  (*init_process)(ngx_cycle_t *cycle);
    
    
    
    /* 由于Nginx暂不支持多线程模式,所以init_thread在框架代码中没有被调用过,设为NULL
    
    */
    
    ngx_int_t  (*init_thread)(ngx_cycle_t *cycle);
    
    
    
    //同上,exit_thread也不支持,设为NULL
    
    void  (*exit_thread)(ngx_cycle_t *cycle);
    
    
    
    /* exit_process回调方法在服务停止前调用。在master/worker模式下,worker进程会在退出前调用它
    
    */
    
    void  (*exit_process)(ngx_cycle_t *cycle);
    
    
    
    //exit_master回调方法将在master进程退出前被调用
    
    void  (*exit_master)(ngx_cycle_t *cycle);
    
    
    
    /*以下8个spare_hook变量也是保留字段,目前没有使用,但可用Nginx提供的NGX_MODULE_V1_PADDING宏来填充。
    
    看一下该宏的定义:
    
    #define NGX_MODULE_V1_PADDING  0, 0, 0, 0, 0, 0, 0, 0
    
    */
    
    uintptr_t  spare_hook0;
    
    uintptr_t  spare_hook1;
    
    uintptr_t  spare_hook2;
    
    uintptr_t  spare_hook3;
    
    uintptr_t  spare_hook4;
    
    uintptr_t  spare_hook5;
    
    uintptr_t  spare_hook6;
    
    uintptr_t  spare_hook7;
    
    };

定义一个HTTP模块时,务必把type字段设为NGX\_HTTP\_MODULE。

对于下列回调方法:init\_module、init\_process、exit\_process、exit\_master,调用它们的是Nginx的框架代码。换句话说,定义HTTP模块时,最重要的是要设置ctx和commands这两个成员。在HTTP模块中,ctx需要指向ngx\_http\_module\_t结构体。

HTTP框架在读取、重载配置文件时定义了由ngx\_http\_module\_t接口描述的8个阶段。

typedef struct
    
    {
    
    //解析配置文件前调用
    
    ngx_int_t  (*preconfiguration)(ngx_conf_t *cf);
    
    
    
    //完成配置文件的解析后调用
    
    ngx_int_t  (*postconfiguration)(ngx_conf_t *cf);
    
    
    
    /* 当需要创建数据结构用于存储main 级别(直属于http{...} 块的配置项)的全局配置项时,可以通过create_main_conf 回调方法创建存储全局配置项的结构体
    
    */
    
    void  *(*create_main_conf)(ngx_conf_t *cf);
    
    
    
    //常用于初始化main 级别配置项
    
    char  *(*init_main_conf)(ngx_conf_t cf, void conf);
    
    
    
    /* 当需要创建数据结构用于存储srv 级别(直属于虚拟主机server{...} 块的配置项)的配置项时,可以通过实现create_srv_conf 回调方法创建存储srv 级别配置项的结构体
    
    */
    
    void  *(*create_srv_conf)(ngx_conf_t *cf);
    
    
    
    //merge_srv_conf 回调方法主要用于合并main 级别和srv 级别下的同名配置项
    
    char  *(*merge_srv_conf)(ngx_conf_t cf, void prev, void *conf);
    
    
    
    /* 当需要创建数据结构用于存储loc 级别(直属于location{...} 块的配置项)的配置项时,可以实现create_loc_conf 回调方法
    
    */
    
    void  *(*create_loc_conf)(ngx_conf_t *cf);
    
    
    
    //merge_loc_conf 回调方法主要用于合并srv 级别和loc 级别下的同名配置项
    
    char  *(*merge_loc_conf)(ngx_conf_t cf, void prev, void *conf);
    
    } ngx_http_module_t;

不过,这8个阶段的调用顺序与上述定义的顺序是不同的。在Nginx启动过程中,HTTP框架调用这些回调方法的实际顺序如下：

1)create\_main\_conf

2)create\_srv\_conf

3)create\_loc\_conf

4)preconfiguration

5)init\_main\_conf

6)merge\_srv\_conf

7)merge\_loc\_conf

8)postconfiguration

commands数组用于定义模块的配置文件参数,每一个数组元素都是ngx\_command\_t类型,数组的结尾用ngx\_null\_command

typedef struct 　ngx_command_s　ngx_command_t; 
    
    struct ngx_command_s 
    
    {
    
    //配置项名称,如"gzip"
    
    ngx_str_t  name;
    
    /* 配置项类型,type 将指定配置项可以出现的位置。例如,出现在server{} 或location{} 中,以及它可以携带的参数个数
    
    */
    
    ngx_uint_t  type;
    
    
    
    //出现了name 中指定的配置项后,将会调用set 方法处理配置项的参数
    
    char  *(*set)(ngx_conf_t cf, ngx_command_t cmd, void *conf);
    
    
    
    //在配置文件中的偏移量
    
    ngx_uint_t  conf;
    
    
    
    /* 通常用于使用预设的解析方法解析配置项,这是配置模块的一个优秀设计。它需要与
    
    conf 配合使用
    
    */
    
    ngx_uint_t  offset;
    
    
    
    //配置项读取后的处理方法,必须是ngx_conf_post_t 结构的指针
    
    void  *post;
    
    };

ngx\_null\_command只是一个空的ngx\_command\_t,如下所示:

#define ngx_null_command  { ngx_null_string, 0, NULL, 0, 0, NULL }