Nginx开发HTTP模块（三）：HTTP模块的数据结构

• 定义HTTP模块

  ngx_module_t ngx_http_mytest_module;
  

• ngx_module_t数据结构

  typedef struct ngx_module_s		ngx_module_t;
  struct ngx_module_s {
  	/* 
  	下面的ctx_index、index、spare0、spare1、spare2、spare3、version变量不需要在定义时赋值。
  	可以用Nginx准备好的宏NGX_MODULE_MODULE_V1来定义：#define NGX_MODULE_V1		0，0，0，0，0，0，1
  	*/
  	/* 
  	ctx_index表示当前模块在某一类模块中的序号。
  	这个成员通常由管理着这类模块的一个Nginx核心模块设置的。
  	ctx_index非常重要，Nginx的模块化设计非常依赖于各个模块的顺序。
  	他们既用于表达优先级，也用于表明各个模块的位置，借以帮助Nginx框架快速获得某个模块的数量。
  	*/
      ngx_uint_t            ctx_index;
      /* 
      index表示当前模块在ngx_modules数组中的序号。
      Nginx启动时会根据ngx_modules数组设置各模块的index值。
      */
      ngx_uint_t            index;
  
      char                 *name;
  	// spare系列的保留变量，暂未使用
      ngx_uint_t            spare0;
      ngx_uint_t            spare1;
      ngx_uint_t            spare2;
      ngx_uint_t            spare3;
   	// 模块的版本，便于将来的扩展。目前只有一种，默认为1
      ngx_uint_t            version;
      const char           *signature;
  	/*
  	ctx用于指向一类模块的上下文结构。Nginx模块由许多种类，
  	不同类模块之间的功能差别很大，每个模块都有自己的特性，而ctx将会指向特定类型模块的公共接口
  	*/
      void                 *ctx;
      // commands将处理nginx.conf中的配置项
      ngx_command_t        *commands;
      /* 
      type表示该模块的类型，它与ctx指针式紧密相关的。
      取值范围：
      NGX_HTTP_MODULE、NGX_CORE_MODULE、NGX_CONF_MODULE、NGX_EVENT_MODULE、NGX_MAIL_MODULE 
      */
      ngx_uint_t            type;
  	/* 
  	从字面上理解应该在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;
  };	
  

  • 务必把type字段设为NGX_HTTP_MODULE

  • init_module、init_process、exit_process、exit_process这四个回调方法与HTTP框架无关，即使nginx.conf中没有设置http {…}配置项，这些回调方法仍然会被调用。

  • 定义HTTP模块时，最重要的是要设置ctx和commands这两个成员。

    • ngx_module_t中的ctx指针必须指向ngx_http_module_t中相应的方法。
    • commands数组用于定义模块的配置文件参数，每一个数组元素都是ngx_command_t类型，数组的结尾用ngx_null_command表示。Nginx在解析配置文件中的一个配置项时首先会遍历所有的模块，对于每一个模块而言，即通过commands数组进行，另外，在数组中检查到ngx_null_command时，会停止使用当前模块解析该配置项。
      • ngx_null_command只是一个空的ngx_command_t

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

  • ngx_http_module_t结构体

    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;
    

    • 在Nginx启动过程中，HTTP框架调用这些回调方法的实际顺序可能是如下的顺序：
      • create_main_conf
      • create_srv_conf
      • create_loc_conf
      • preconfiguration
      • init_main_conf
      • merge_srv_conf
      • merge_loc_conf
      • postconfiguration

  • ngx_command_t结构体

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