7.1 ngx_command_t 数组

commands 数组用于定义模块的配置文件参数，每一个数组元素都是ngx_command_t类型，数组的结尾是用ngx_numm_command表示。Nginx在解析配置文件中的一个配置项时首先会遍历所有的模块，对于每一个模块而言，即通过遍历commands数组进行，另外，在数组中检查到ngx_numm_command时，会停止使用当前模块解析该配置项。每一个ngx_command_t结构体定义个如下配置:

  1. typedef struct ngx_command_s ngx_command_t;
  3. struct ngx_command_s {
  4.     //配置项名称，如"gzip"
  5.     ngx_str_t       name;
  6.     //配置项类型，type将制定配置项可以出现的位置，
  7.     //例如：出现在server{}活location{}中，等等
  8.     ngx_uint_t      type;
  9.     //出现了name中指定的配置项后，将会调用set方法处理配置项的参数
  10.     char            *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
  11.     //在配置文件中的偏移量
  12.     ngx_uint_t      conf;
  13.     //通常用于使用预设的解析方法解析配置项，这是配置模块的一个优秀的设计,
  14.     //需要与conf配合使用
  15.     ngx_uint_t      offset;
  16.     //配置项读取后的处理方法，必须是ngx_conf_post_t结构的指针
  17.     void            *post;
  18. };

ngx_null_command只是一个空的ngx_command_s：

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

也就是说，对于我们在nginx.cong 中编写的配置项mytest来说，nginx首先会遍历所有的模块（modules）,而对于每个模块，会遍历他所对应的ngx_command_t数组，试图找到关于我们配置项目mytest的解析方式。

  1. static ngx_command_t  ngx_http_mytest_commands[] =
  2. {
  4.     {
  5.         ngx_string("mytest"),
  6.         NGX_HTTP_MAIN_CONF | NGX_HTTP_SRV_CONF | NGX_HTTP_LOC_CONF | NGX_HTTP_LMT_CONF | NGX_CONF_NOARGS,
  7.         ngx_http_mytest,
  8.         NGX_HTTP_LOC_CONF_OFFSET,
  9.         0,
  10.         NULL
  11.     },
  13.     ngx_null_command
  14. };

7.2 command中用于处理配置项参数的set方法

  1. static char *
  2. ngx_http_mytest(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
  3. {
  4.     ngx_http_core_loc_conf_t  *clcf;
  6.     //首先找到mytest配置项所属的配置块，clcf貌似是location块内的数据
  7. //结构，其实不然，它可以是main、srv或者loc级别配置项，也就是说在每个
  8. //http{}和server{}内也都有一个ngx_http_core_loc_conf_t结构体
  9.     clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
  11.     //http框架在处理用户请求进行到NGX_HTTP_CONTENT_PHASE阶段时，如果
  12. //请求的主机域名、URI与mytest配置项所在的配置块相匹配，就将调用我们
  13. //实现的ngx_http_mytest_handler方法处理这个请求
  14.     clcf->handler = ngx_http_mytest_handler;
  16.     return NGX_CONF_OK;
  17. }

关于ngx_http_conf_get_module_loc_conf 的定义可以参考：

http://lxr.nginx.org/source/src/http/ngx_http_config.h#0065

本质： 就是设置ngx_http_mytest_handler, 匹配项被选中的时候， 应该如何解析。

7.3 定义ngx_http_module_t接口

这部分的代码， 是用于http框架的， 相当于http框架的回掉函数， 由于这里并不需要框架做任何操作。

  1. static ngx_http_module_t  ngx_http_mytest_module_ctx =
  2. {
  3.     NULL,                              /* preconfiguration */
  4.     NULL,                       /* postconfiguration */
  6.     NULL,                              /* create main configuration */
  7.     NULL,                              /* init main configuration */
  9.     NULL,                              /* create server configuration */
  10.     NULL,                              /* merge server configuration */
  12.     NULL,                   /* create location configuration */
  13.     NULL                    /* merge location configuration */
  14. };

7.4 定义处理“mytest”command的handler


我们这里需要定义配置项被匹配之后的处理方法.

  1. static ngx_int_t ngx_http_mytest_handler(ngx_http_request_t *r)
  2. {
  3.     //必须是GET或者HEAD方法，否则返回405 Not Allowed
  4.     if (!(r->method & (NGX_HTTP_GET | NGX_HTTP_HEAD)))
  5.     {
  6.         return NGX_HTTP_NOT_ALLOWED;
  7.     }
  9.     //丢弃请求中的包体
  10.     ngx_int_t rc = ngx_http_discard_request_body(r);
  11.     if (rc != NGX_OK)
  12.     {
  13.         return rc;
  14.     }
  16.     //设置返回的Content-Type。注意，ngx_str_t有一个很方便的初始化宏
  17. //ngx_string，它可以把ngx_str_t的data和len成员都设置好
  18.     ngx_str_t type = ngx_string("text/plain");
  19.     //返回的包体内容
  20.     ngx_str_t response = ngx_string("Hello World!");
  21.     //设置返回状态码
  22.     r->headers_out.status = NGX_HTTP_OK;
  23.     //响应包是有包体内容的，所以需要设置Content-Length长度
  24.     r->headers_out.content_length_n = response.len;
  25.     //设置Content-Type
  26.     r->headers_out.content_type = type;
  28.     //发送http头部
  29.     rc = ngx_http_send_header(r);
  30.     if (rc == NGX_ERROR || rc > NGX_OK || r->header_only)
  31.     {
  32.         return rc;
  33.     }
  35.     //构造ngx_buf_t结构准备发送包体
  36.     ngx_buf_t                 *b;
  37.     b = ngx_create_temp_buf(r->pool, response.len);
  38.     if (b == NULL)
  39.     {
  40.         return NGX_HTTP_INTERNAL_SERVER_ERROR;
  41.     }
  42.     //将Hello World拷贝到ngx_buf_t指向的内存中
  43.     ngx_memcpy(b->pos, response.data, response.len);
  44.     //注意，一定要设置好last指针
  45.     b->last = b->pos + response.len;
  46.     //声明这是最后一块缓冲区
  47.     b->last_buf = 1;
  49.     //构造发送时的ngx_chain_t结构体
  50.     ngx_chain_t     out;
  51.     //赋值ngx_buf_t
  52.     out.buf = b;
  53.     //设置next为NULL
  54.     out.next = NULL;
  56.     //最后一步发送包体，http框架会调ngx_http_finalize_request方法
  57.     //结束请求
  58.     return ngx_http_output_filter(r, &out);
  59. }

7.5 定义ngx_module_t中的mytest模块


定义HTTP模块方式很简单，例如：

  1. ngx_module_t ngx_http_mytest_module;

其中ngx_module_t是一个Nginx模块的数据结构，下面来分析一下Nginx模块中的所有成员：

  1. typedef struct ngx_module_s ngx_module_t;
  2. struct ngx_module_s {
  3.   /*
  4.   下面的ctx_index、index、spare0,spare1,
  5.   spare2,spare3,version变量不需要再定义时候赋值，
  6.   可以用Nginx准备好的宏NGX_MODULE_V1来定义，
  7.   已经定义好了这7个值
  9.     #define NGX_MODULE_V1  0,0,0,0,0,0,1
  11.     对于一类模块（由下面的type成员决定类别）而言，
  12.     ctx_index表示当前模块在这类模块中的序号。
  13.     这个成员常常是由管理这类模块的一个Nginx核心模块设置的，
  14.     对于所有的HTTP模块而言，ctx_index是由
  15.     核心模块ngx_http_module设置的。
  16.     ctx_index非常重要，Nginx的模块化设计非常依赖于各个模块的顺序，
  17.     他们既用于表达优先级，也用于表明每个模块的位置，
  18.     借以帮助Nginx框架快速获得某个模块的数据.
  19.   */
  20.   ngx_uint_t           ctx_index;
  23.   /*
  24.   index表示当前模块在ngx_module数组中的序号。
  25.   注意，ctx_index表示的是当前模块在一类模块中的序号，
  26.   而index表示当前模块在所有模块中的序号，同样很关键.
  27.   Nginx启动时会根据ngx_modules数组设置各模块的index值，
  28.   例如：
  29.     ngx_max_module = 0;
  30.     for(i = 0; ngx_module[i]; i++) {
  31.         ngx_modules[i]->index = ngx_max_module++;
  32.     }
  33.   */
  34.   ngx_uint_t           index;
  37.   //spare系列的保留变量，暂未使用
  38.   ngx_uint_t           spare0;
  39.   ngx_uint_t           spare1;
  40.   ngx_uint_t           spare2;
  41.   ngx_uint_t           spare3;
  43.   //模块的版本，便于将来的拓展，目前只有一种，默认为1
  44.   ngx_uint_t           version;
  47.   /*
  48.   ctx用于指向一类模块的上下文结构体，
  49.   为什么需要ctx呢？因为前面说过，
  50.   Nginx模块有许多种类，不同类模块之间的功能差别很大。
  51.   例如，
  52.   事件类型的模块主要处理I/O事件的相关功能，
  53.   HTTP类型的模块主要处理HTTP应用层的功能。
  54.   这样每个模块都有了自己的特性，
  55.   而ctx会指向特定类型模块的公共接口。
  56.   例如，
  57.   在HTTP模块中，ctx需要指向ngx_http_module_t结构体
  58.   */
  59.   void                 *ctx;
  61.   /*
  62.   commands处理nginx.conf中的配置项
  63.   */
  64.   ngx_command_t        *commands;
  66.   /*
  67.   type表示该模块的类型，它与ctx指针是紧密相关的。
  68.   在官方Nginx中，它的取值范围有以下5种：
  69.   NGX_HTTP_MODULE
  70.   NGX_CORE_MODULE
  71.   NGX_CONF_MODULE
  72.   NGX_EVENT_MODULE
  73.   NGX_MAIL_MODULE
  74.   */
  75.   ngx_uint_t            type;
  77.   /*
  78.   在Nginx的启动、停止过程中，以下7个函数指针表示7个
  79.   执行点分别用调用这7种方法。对于任意一个方法而言，
  80.   如果不需要Nginx再某个时刻执行它，那么简单地把它设为NULL
  81.   空指针即可。
  82.   */
  84.   /*
  85.   虽然从字面上理解应当在master进程启动的时，回调
  86.   init_master,但到目前为止，框架代码从来不会调动它，
  87.   所以设置为NULL
  88.   */
  89.   ngx_int_t   (*init_master)(ngx_log_t *log);
  91.   /*
  92.   init_module回调方法在初始化所有模块时候被调用。
  93.   在master/worker模式下，这个阶段将在启动worker子进程前完成。
  94.   */
  95.   ngx_int_t   (*init_module)(ngx_cycle_t *cycle);
  97.   /*
  98.   init_process 回调方法在正常服务前被调用。
  99.   在master/worker模式下，多个worker子进程已经产生。
  100.   在每个worker进程的初始化过程会调用所有模块的init_process函数
  101.   */
  102.   ngx_int_t   (*init_process)(ngx_cycle_t *cycle);
  104.   /*
  105.   由于Nginx暂时不支持多线程模式，所以init_thread在框架中
  106.   没有被调用过，设置为NULL
  107.   */
  108.   ngx_int_t   (*init_thread)(ngx_cycle_t *cycle);
  110.   /*
  111.   同上、exit_thread也不支持，设为NULL
  112.   */
  113.   void        (*exit_thread)(ngx_cycle_t *cycle);
  115.   /*
  116.   exit_process回调方法在服务停止前被调用。
  117.   在/master/worker模式下，worker进程会在退出前调用
  118.   */
  119.   void        (*exit_process)(ngx_cycle_t *cycle);
  122.   /*
  123.   exit_master回调方法将在master进程退出前被调用
  124.   */
  125.   void        (*exit_master)(ngx_cycle_t *cycle);
  128.   /*
  129.   一下8个spare_hook变量也是保留字段，目前没有使用，
  130.   但可用Nginx提供的NGX_MODULE_V1_PADDING宏来填充
  131.   #define NGX_MODULE_V1_PADDING 0,0,0,0,0,0,0,0
  132.   */
  133.   uintptr_t             spare_hook0;
  134.   uintptr_t             spare_hook1;
  135.   uintptr_t             spare_hook2;
  136.   uintptr_t             spare_hook3;
  137.   uintptr_t             spare_hook4;
  138.   uintptr_t             spare_hook5;
  139.   uintptr_t             spare_hook6;
  140.   uintptr_t             spare_hook7;
  141. };

所以在定义一个HTTP模块的时候，务必把type字段设置为NGX_HTTP_MODULE.

对于下列回调方法：init_module、init_process、exit_process、exit_master
调用他们的是Nginx框架代码。换句话说，这4个回调方法与HTTP框架无关。
即使nginx.conf中没有设置http{…}这种开启HTTP功能的配置项，这些
回调方法仍然会被调用。因此，通常开发HTTP模块时候都把他们设置为NULL。
这样Nginx不作为web服务器使用时，不会执行HTTP模块的任何代码。

定义HTTP时候，最重要的是要设置ctx和commands这两个成员。
对于HTTP类型模块来说，ngxmodule中的ctx指针必须指向ngx_http_module_t接口。

所以最终我们定义个ngx_module_t 模块如下：

  1. ngx_module_t  ngx_http_mytest_module =
  2. {
  3.     NGX_MODULE_V1,
  4.     &ngx_http_mytest_module_ctx,           /* module context */
  5.     ngx_http_mytest_commands,              /* module directives */
  6.     NGX_HTTP_MODULE,                       /* module type */
  7.     NULL,                                  /* init master */
  8.     NULL,                                  /* init module */
  9.     NULL,                                  /* init process */
  10.     NULL,                                  /* init thread */
  11.     NULL,                                  /* exit thread */
  12.     NULL,                                  /* exit process */
  13.     NULL,                                  /* exit master */
  14.     NGX_MODULE_V1_PADDING
  15. };

这样， mytest 模块在编译的时候， 就可以被加入到ngx_modules的全局数组中了。

7.6 完整代码 ngx_http_mytest_module.c

所以全部的编码工作完毕，最终的代码应该如下：

  1. #include <ngx_config.h>
  2. #include <ngx_core.h>
  3. #include <ngx_http.h>
  4. #include <sys/types.h>
  5. #include <unistd.h>
  8. //定义处理用户请求hello world handler
  9. static ngx_int_t ngx_http_mytest_handler(ngx_http_request_t *r)
  10. {
  11.     //必须是GET或者HEAD方法，否则返回405 Not Allowed
  12.     if (!(r->method & (NGX_HTTP_GET | NGX_HTTP_HEAD)))
  13.     {
  14.         return NGX_HTTP_NOT_ALLOWED;
  15.     }
  17.     //丢弃请求中的包体
  18.     ngx_int_t rc = ngx_http_discard_request_body(r);
  19.     if (rc != NGX_OK)
  20.     {
  21.         return rc;
  22.     }
  24.     //设置返回的Content-Type。注意，ngx_str_t有一个很方便的初始化宏
  25.     //ngx_string，它可以把ngx_str_t的data和len成员都设置好
  26.     ngx_str_t type = ngx_string("text/plain");
  27.     //返回的包体内容
  28.     ngx_str_t response = ngx_string("Hello World!");
  29.     //设置返回状态码
  30.     r->headers_out.status = NGX_HTTP_OK;
  31.     //响应包是有包体内容的，所以需要设置Content-Length长度
  32.     r->headers_out.content_length_n = response.len;
  33.     //设置Content-Type
  34.     r->headers_out.content_type = type;
  36.     //发送http头部
  37.     rc = ngx_http_send_header(r);
  38.     if (rc == NGX_ERROR || rc > NGX_OK || r->header_only)
  39.     {
  40.         return rc;
  41.     }
  43.     //构造ngx_buf_t结构准备发送包体
  44.     ngx_buf_t                 *b;
  45.     b = ngx_create_temp_buf(r->pool, response.len);
  46.     if (b == NULL)
  47.     {
  48.         return NGX_HTTP_INTERNAL_SERVER_ERROR;
  49.     }
  50.     //将Hello World拷贝到ngx_buf_t指向的内存中
  51.     ngx_memcpy(b->pos, response.data, response.len);
  52.     //注意，一定要设置好last指针
  53.     b->last = b->pos + response.len;
  54.     //声明这是最后一块缓冲区
  55.     b->last_buf = 1;
  57.     //构造发送时的ngx_chain_t结构体
  58.     ngx_chain_t     out;
  59.     //赋值ngx_buf_t
  60.     out.buf = b;
  61.     //设置next为NULL
  62.     out.next = NULL;
  64.     //最后一步发送包体，http框架会调用ngx_http_finalize_request方法
  65.     //结束请求
  66.     return ngx_http_output_filter(r, &out);
  67. }
  70. //定义command用于处理配置项参数的set方法
  71.     static char *
  72. ngx_http_mytest(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
  73. {
  74.     ngx_http_core_loc_conf_t  *clcf;
  76.     //首先找到mytest配置项所属的配置块，clcf貌似是location块内的数据
  77.     //结构，其实不然，它可以是main、srv或者loc级别配置项，也就是说在每个
  78.     //http{}和server{}内也都有一个ngx_http_core_loc_conf_t结构体
  79.     clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
  81.     //http框架在处理用户请求进行到NGX_HTTP_CONTENT_PHASE阶段时，如果
  82.     //请求的主机域名、URI与mytest配置项所在的配置块相匹配，就将调用我们
  83.     //实现的ngx_http_mytest_handler方法处理这个请求
  84.     clcf->handler = ngx_http_mytest_handler;
  86.     return NGX_CONF_OK;
  87. }
  89. //定义ngx mytest 配置匹配的command
  90. static ngx_command_t  ngx_http_mytest_commands[] =
  91. {
  93.     {
  94.         ngx_string("mytest"),
  95.         NGX_HTTP_MAIN_CONF | NGX_HTTP_SRV_CONF | NGX_HTTP_LOC_CONF | NGX_HTTP_LMT_CONF | NGX_CONF_NOARGS,
  96.         ngx_http_mytest,
  97.         NGX_HTTP_LOC_CONF_OFFSET,
  98.         0,
  99.         NULL
  100.     },
  102.     ngx_null_command
  103. };
  106. //定义ngx_http_module_t接口
  107. static ngx_http_module_t  ngx_http_mytest_module_ctx =
  108. {
  109.     NULL,                       /* preconfiguration */
  110.     NULL,                       /* postconfiguration */
  112.     NULL,                       /* create main configuration */
  113.     NULL,                       /* init main configuration */
  115.     NULL,                       /* create server configuration */
  116.     NULL,                       /* merge server configuration */
  118.     NULL,                   /* create location configuration */
  119.     NULL                    /* merge location configuration */
  120. };
  124. //定义mytest模块
  125. ngx_module_t  ngx_http_mytest_module =
  126. {
  127.     NGX_MODULE_V1,
  128.     &ngx_http_mytest_module_ctx,           /* module context */
  129.     ngx_http_mytest_commands,              /* module directives */
  130.     NGX_HTTP_MODULE,                       /* module type */
  131.     NULL,                                  /* init master */
  132.     NULL,                                  /* init module */
  133.     NULL,                                  /* init process */
  134.     NULL,                                  /* init thread */
  135.     NULL,                                  /* exit thread */
  136.     NULL,                                  /* exit process */
  137.     NULL,                                  /* exit master */
  138.     NGX_MODULE_V1_PADDING
  139. };

7.7 配置文件 config

但是之后我们还需要给该模块相同目录下提供一个配置文件”config”表示在nginx编译的时候的一些编译选项。

  1. ngx_addon_name=ngx_http_mytest_module
  2. HTTP_MODULES="$HTTP_MODULES ngx_http_mytest_module"
  3. NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_mytest_module.c"

所以我们的模块编写完毕了，当前目录应该有两个文件

  1. ls
  3. config  ngx_http_mytest_module.c

7.8 重新编译Nginx 并添加自定义模块

进入Nginx源码目录
执行

  1. ./configure --prefix=/usr/local/nginx --add-module=/home/ace/openSource_test/nginx_module_http_test

—add-module为刚才自定义模块源码的目录

  1. make 
  2. sudo make install

测试自定义模块

修改nginx.conf文件

  1.    server {
  2.         listen 8777;
  4.         server_name localhost;
  6.         location / {
  7.             mytest;#我们自定义模块的名称
  8.         }
  9.     }

重新启动nginx

打开浏览器输入地址和端口

打开浏览器输入地址和端口