NGINX模块开发入门——（最简单、最实用、最细腻）

/*
* Copyright (C) Eric Zhang
*/
#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>
/* Module config */
typedef struct {
    ngx_str_t  ed;
} ngx_http_echo_loc_conf_t;
static char *ngx_http_echo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
static void *ngx_http_echo_create_loc_conf(ngx_conf_t *cf);
static char *ngx_http_echo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child);
/* Directives */
static ngx_command_t  ngx_http_echo_commands[] = {
    { ngx_string("echo"),
        NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
        ngx_http_echo,
        NGX_HTTP_LOC_CONF_OFFSET,
        offsetof(ngx_http_echo_loc_conf_t, ed),
        NULL },
        ngx_null_command
};
/* Http context of the module */
static ngx_http_module_t  ngx_http_echo_module_ctx = {
    NULL,                                  /* preconfiguration */
    NULL,                                  /* postconfiguration */
    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */
    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */
    ngx_http_echo_create_loc_conf,         /* create location configration */
    ngx_http_echo_merge_loc_conf           /* merge location configration */
};
/* Module */
ngx_module_t  ngx_http_echo_module = {
    NGX_MODULE_V1,
    &ngx_http_echo_module_ctx,             /* module context */
    ngx_http_echo_commands,                /* module directives */
    NGX_HTTP_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};
/* Handler function */
static ngx_int_t
ngx_http_echo_handler(ngx_http_request_t *r)
{
    ngx_int_t rc;
    ngx_buf_t *b;
    ngx_chain_t out;
    ngx_http_echo_loc_conf_t *elcf;
    elcf = ngx_http_get_module_loc_conf(r, ngx_http_echo_module);
    if(!(r->method & (NGX_HTTP_HEAD|NGX_HTTP_GET|NGX_HTTP_POST)))
    {
        return NGX_HTTP_NOT_ALLOWED;
    }
    r->headers_out.content_type.len = sizeof("text/html") - 1;
    r->headers_out.content_type.data = (u_char *) "text/html";
    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = elcf->ed.len;
    if(r->method == NGX_HTTP_HEAD)
    {
        rc = ngx_http_send_header(r);
        if(rc != NGX_OK)
        {
            return rc;
        }
    }
    b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t));
    if(b == NULL)
    {
        ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, "Failed to allocate response buffer.");
        return NGX_HTTP_INTERNAL_SERVER_ERROR;
    }
    out.buf = b;
    out.next = NULL;
    b->pos = elcf->ed.data;
    b->last = elcf->ed.data + (elcf->ed.len);
    b->memory = 1;
    b->last_buf = 1;
    rc = ngx_http_send_header(r);
    if(rc != NGX_OK)
    {
        return rc;
    }
    return ngx_http_output_filter(r, &out);
}
static char *
ngx_http_echo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_http_core_loc_conf_t  *clcf;
    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
    clcf->handler = ngx_http_echo_handler;
    ngx_conf_set_str_slot(cf,cmd,conf);
    return NGX_CONF_OK;
}
static void *
ngx_http_echo_create_loc_conf(ngx_conf_t *cf)
{
    ngx_http_echo_loc_conf_t  *conf;
    conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_echo_loc_conf_t));
    if (conf == NULL) {
        return NGX_CONF_ERROR;
    }
    conf->ed.len = 0;
    conf->ed.data = NULL;
    return conf;
}
static char *
ngx_http_echo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
    ngx_http_echo_loc_conf_t *prev = parent;
    ngx_http_echo_loc_conf_t *conf = child;
    ngx_conf_merge_str_value(conf->ed, prev->ed, "");
    return NGX_CONF_OK;
}

//模块的配置结构体的定义有三种，分别是全局、主机和位置的配置结构体。
//大多数HTTP模块仅仅需要一个位置的配置结构体。名称是这样的：ngx_http_<module name>_(main|srv|loc)_conf_t。
typedef struct {
    ngx_str_t  ed;
} ngx_http_echo_loc_conf_t;

static ngx_command_t  ngx_http_echo_commands[] = {
    {
        ngx_string("echo"),                  /* 指令名称，利用ngx_string宏定义 */
        NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,    /* 指令属性，可以用“|”将使指令具备多个属性，NGX_CONF_TAKE1：指令读入1个参数 */
        ngx_http_echo,                       /* 定义处理这个指令的回调函数，这个是核心啦。nginx自带了很多处理函数，用于将配置的参数解析为nginx数据类型并存储，可以帮助我们简化编程 */
        NGX_HTTP_LOC_CONF_OFFSET,            /* 是指定配置解析后存放在哪里，有三个选择项：NGX_HTTP_MAIN_CONF_OFFSET，NGX_HTTP_SRV_CONF_OFFSET，或者NGX_HTTP_LOC_CONF_OFFSET，表示分别存入main_conf、srv_conf、loc_conf，对应于HTTP全局配置、某个主机的配置和某个URI的配置。多说两句，这个配置和第二行指令的属性其实是有联系的，比如某个指令可以用在main配置部分、server配置部分，但不能用在location配置部分，那应该使用srv_conf来存储，存在loc_conf中有冗余，存在man_conf中有覆盖。 */
        offsetof(ngx_http_echo_loc_conf_t, ed), /* 承接上一行的配置，表示数据具体保存在main_conf、srv_conf、loc_conf指向的结构体的哪个位置（offset偏移）。 */
        NULL /* 是一个补充字段，一般不用的，填入NULL。只是对于某些特殊的处理函数，比如ngx_conf_set_enum_slot，会用这个指针来指向enum定义表 */
    },
    ngx_null_command
};

//参数转化函数的代码
static char * ngx_http_echo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_http_core_loc_conf_t  *clcf;
    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);    //利用ngx_http_conf_get_module_XXX_conf得到某个模块的配置
    clcf->handler = ngx_http_echo_handler;    //钩子的设置方法：clcf->handler = ngx_http_echo_handler；
    ngx_conf_set_str_slot(cf,cmd,conf);    //处理参数ngx_conf_set_XXX_slot
    return NGX_CONF_OK;
}

/* Handler function
   下面的工作是编写handler。handler可以说是模块中真正干活的代码，它主要有以下四项职责：读入模块配置。处理功能业务。产生HTTP header。产生HTTP body。
 */
static ngx_int_t ngx_http_echo_handler(ngx_http_request_t *r)    //参数指向一个ngx_http_request_t结构体，此结构体存储了这次HTTP请求的一些信息，这个结构定义在http/ngx_http_request.h中
{
    ngx_int_t rc;
    ngx_buf_t *b;  //声明一块缓冲区（buffer）
    ngx_chain_t out;//我们通过ngx_chain_t来维护我们的输出。ngx_chain_t是一条链，其中的元素都是ngx_buf_t（缓冲区），所以内容生成很灵活，如果需要输出什么，就构造一个缓冲区，然后把缓冲区加入缓冲区链；
    ngx_http_echo_loc_conf_t *elcf;
    elcf = ngx_http_get_module_loc_conf(r, ngx_http_echo_module);    //这是handler的第一个职责，读入模块配置，传入request结构体和模块定义(一个被全局定义的变量)。得到我们的配置的（就是那个参数了）
    if(!(r->method & (NGX_HTTP_HEAD|NGX_HTTP_GET|NGX_HTTP_POST)))
    {
        return NGX_HTTP_NOT_ALLOWED;
    }
    r->headers_out.content_type.len = sizeof("text/html") - 1;    //我们通过headers_out.content_type修改HTTP响应的Content-Type字段
    r->headers_out.content_type.data = (u_char *) "text/html";
    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = elcf->ed.len;
    if(r->method == NGX_HTTP_HEAD)
    {
        rc = ngx_http_send_header(r);//HTTP头通过调用ngx_http_send_header来发送
        if(rc != NGX_OK)
        {
            return rc;
        }
    }
    b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t));//我们通过ngx_pcalloc来分配内存。nginx最高效的内存分配方法就是像这样的内存池分配。ngx_pcalloc除了分配内存，还负责对这块内存清零，ngx_palloc只是分配内存；
    if(b == NULL)
    {
        ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, "Failed to allocate response buffer.");
        return NGX_HTTP_INTERNAL_SERVER_ERROR;
    }
    out.buf = b;//我们通过ngx_chain_t来维护我们的输出。ngx_chain_t是一条链，其中的元素都是ngx_buf_t（缓冲区），所以内容生成很灵活，如果需要输出什么，就构造一个缓冲区，然后把缓冲区加入缓冲区链；缓冲区内部并没有存放内容，缓冲区只包含指向内容的指针和标志。memory标志表示内容在内存中，last_buf标志表示这是最后一块缓冲区；
    out.next = NULL;
    b->pos = elcf->ed.data;
    b->last = elcf->ed.data + (elcf->ed.len);
    b->memory = 1;
    b->last_buf = 1;
    rc = ngx_http_send_header(r);
    if(rc != NGX_OK)
    {
        return rc;
    }
    return ngx_http_output_filter(r, &out);//HTTP正文需要调用ngx_http_output_filter来发送。ngx_http_output_filter的第一个参数为ngx_http_request_t结构，第二个为输出链表的起始地址&out。ngx_http_out_put_filter会遍历链表，输出所有数据。
}

/* 结构体ngx_module_t: 这个结构体变量命名为ngx_http_<module name>_module。它包含有模块的主要内容和指令的执行部分，也有一些回调函数（退出线程，退出进程，等等）。这些函数的定义是把数据处理关联到特定模块的关键。模块定义一下这个样子：
*/
ngx_module_t  ngx_http_echo_module = {
    NGX_MODULE_V1,                         /* NGNIX规范的版本号，都使用NGX_MODULE_V1 */
    &ngx_http_echo_module_ctx,             /* 指向包含解析模块配置文件时用到的回调函数集合的定义的数据结构的指针。就是要调用ngx_http_echo_module_ctx结构体*/
    ngx_http_echo_commands,                /* 模块提供的指令集的数据结构，这个结构的一般命名法是<模块名>_commands。同上调用ngx_http_echo_commands结构体 */
    NGX_HTTP_MODULE,                       /* 模块类别，我们这个模块是HTTP模块，所以值是NGX_HTTP_MODULE */
    NULL,                                  /* master进程初始化时调用，直到现在，nginx也没有真正使用过init_master */
    NULL,                                  /* master进程解析配置以后初始化模块时调用一次 */
    NULL,                                  /* worker进程初始化时调用一次 */
    NULL,                                  /* 多线程时，线程初始化时调用。Unix/Linux环境下未使用多线程 */
    NULL,                                  /* 多线程退出时调用 */
    NULL,                                  /* worker进程退出时调用一次 */
    NULL,                                  /* master进程退出时调用一次 */
    NGX_MODULE_V1_PADDING                  /* 未用字段，使用NGX_MODULE_V1_PADDING补齐 */
};

static ngx_http_module_t  ngx_http_echo_module_ctx = {
    NULL,                                  /* preconfiguration */
    NULL,                                  /* postconfiguration */
    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */
    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */
    ngx_http_echo_create_loc_conf,         /* 给我们的“echo”指令分配内存的函数 */
    ngx_http_echo_merge_loc_conf           /* 是把“echo”的参数从一个地方拷贝到另一个地方的函数，nginx有时需要做这样的拷贝。 */
};

static void * ngx_http_echo_create_loc_conf(ngx_conf_t *cf)
{
    ngx_http_echo_loc_conf_t  *conf;
    conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_echo_loc_conf_t));    //ngx_pcalloc用于在Nginx内存池中分配一块空间，是pcalloc的一个包装。使用ngx_pcalloc分配的内存空间不必手工free，Nginx会自行管理，在适当是否释放。
    if (conf == NULL) {
        return NGX_CONF_ERROR;
    }
    conf->ed.len = 0;
    conf->ed.data = NULL;
    return conf;
}
//create_loc_conf新建一个ngx_http_echo_loc_conf_t，分配内存，并初始化其中的数据，然后返回这个结构的指针；merge_loc_conf将父block域的配置信息合并到create_loc_conf新建的配置结构体中

static char * ngx_http_echo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
    ngx_http_echo_loc_conf_t *prev = parent;
    ngx_http_echo_loc_conf_t *conf = child;
    ngx_conf_merge_str_value(conf->ed, prev->ed, "");
    return NGX_CONF_OK;
}
/*ngx_conf_merge_str_value不是一个函数，而是一个宏，其定义在core/ngx_conf_file.h中
#define ngx_conf_merge_str_value(conf, prev, default)                        
    if (conf.data == NULL) {                                                 
        if (prev.data) {                                                     
            conf.len = prev.len;                                             
            conf.data = prev.data;                                           
        } else {                                                             
            conf.len = sizeof(default) - 1;                                  
            conf.data = (u_char *) default;                                  
        }                                                                    
    }
同时可以看到，core/ngx_conf_file.h还定义了很多merge*value的宏用于merge各种数据。它们的行为比较相似：使用prev填充conf，如果prev的数据为空则使用default填充。
*/