Nginx基础教程（45）Nginx HTTP请求处理之开发handler模块：Nginx Handler模块开发指南：让你的服务器学会“说话”的艺术

内容分享5天前发布 DunLing

0 0 0

网上有句调侃：程序员和Nginx之间只差一个handler模块。今天，就让我们一起揭开这个让无数开发者又爱又恨的技术谜题。

第一章 Handler模块：Nginx的“嘴巴”和“手”

1.1 什么是Handler模块？

用大白话说，handler模块就是Nginx的**“嘴巴”和“手”**——它负责接受客户端请求并产生输出。当请求打到Nginx时，handler模块决定如何回应：是返回一个HTML页面，还是输出JSON数据，或者干脆拒绝请求。

有意思的是，Nginx内部很多基础功能也都是通过handler模块实现的。比如静态文件处理模块ngx_http_static_module，就是一个典型的handler——它看到请求就去找对应文件，找到就返回，找不到就报错。

1.2 为什么需要自己写Handler模块？

你可能会问：Nginx不是已经很强大了吗，为什么还要自己写handler？

想象一下这些场景：

你想在Nginx中实现自定义的业务逻辑需要根据特定参数动态生成内容，而不是简单返回文件想要集成第三方服务，在Nginx层面直接处理需要对请求进行复杂的验证和过滤

这时候，handler模块就派上用场了。它让你可以在Nginx层面直接处理请求，无需依赖后端应用服务器，大大提升性能。

1.3 模块处理的三种结果

handler模块处理请求后，基本上就三种结果：

处理成功：顺利完成任务，返回内容处理失败：处理过程中发生错误拒绝处理：表示“这活我干不了”，让默认的handler模块接手

这就好比餐厅服务员：要么顺利为你点餐（成功），要么记错订单（失败），要么告诉你“这个菜我们不做了”（拒绝处理）。

第二章解剖Handler模块：从外到内看个明白

2.1 模块的基本结构

开发一个handler模块，就像组装一个乐高模型，需要几个核心部件：

模块配置结构：存储配置信息的数据结构模块配置指令：定义在配置文件中使用的指令模块上下文：处理配置合并和模块初始化处理函数：实际处理请求的地方

2.2 模块配置结构：模块的“记忆体”

Nginx的配置分为main、server和location三个作用域，模块也需要为每个作用域定义对应的配置结构。

命名习惯是：ngx_http_<module name>_(main|srv|loc)_conf_t

比如我们准备开发的hello模块，它的location配置结构可能是这样的：



typedef struct {
    ngx_str_t hello_string;
    ngx_int_t hello_counter;
} ngx_http_hello_loc_conf_t;

这个结构体用于存储我们在location配置中设置的hello_string和hello_counter值。

2.3 模块配置指令：模块的“遥控器”

配置指令是用户与模块交互的方式，它告诉模块该如何行为。在Nginx中，配置指令通过一个静态数组定义：



static ngx_command_t ngx_http_hello_commands[] = {
    {
        ngx_string("hello_string"),
        NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
        ngx_http_hello_string,
        NGX_HTTP_LOC_CONF_OFFSET,
        offsetof(ngx_http_hello_loc_conf_t, hello_string),
        NULL
    },
    ngx_null_command
};

这个数组的每个元素都是一个ngx_command_t结构，定义了指令的名称、参数类型、处理函数等信息。

2.4 ngx_command_t结构详解

ngx_command_t结构就像是模块配置指令的“身份证”，包含了指令的所有基本信息：



struct ngx_command_s {
    ngx_str_t             name;
    ngx_uint_t            type;
    char               *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
    ngx_uint_t            conf;
    ngx_uint_t            offset;
    void                 *post;
};

name：指令的名字，比如”hello_string”type：指令的属性，比如能出现在哪里、接受几个参数等set：处理配置值的函数，Nginx提供了一些内置函数，也可以自定义conf：指示配置存储的位置offset：指定配置项在结构体中的偏移量

type字段的常见取值：

NGX_CONF_NOARGS：指令不接受参数NGX_CONF_TAKE1～NGX_CONF_TAKE7：指令接受1～7个参数NGX_CONF_FLAG：指令接受on/off参数NGX_HTTP_MAIN_CONF：指令可出现在http块NGX_HTTP_SRV_CONF：指令可出现在server块NGX_HTTP_LOC_CONF：指令可出现在location块

2.5 模块上下文：模块的“身份证”

模块上下文是一个ngx_http_module_t结构，它定义了模块在配置解析过程中的钩子函数：



static ngx_http_module_t ngx_http_hello_module_ctx = {
    NULL,                          /* preconfiguration */
    NULL,                          /* postconfiguration */
    NULL,                          /* create main configuration */
    NULL,                          /* init main configuration */
    NULL,                          /* create server configuration */
    NULL,                          /* merge server configuration */
    ngx_http_hello_create_loc_conf, /* create location configuration */
    NULL                           /* merge location configuration */
};

对于简单的handler模块，我们通常只需要实现create_loc_conf来创建location配置。

第三章实战开发：手把手编写Hello Handler模块

说了这么多理论，是时候动手实践了！我们将开发一个简单的hello handler模块，它可以根据配置返回问候语和计数。

3.1 准备工作

在开始之前，确保你已经安装了Nginx源代码，并了解基本的编译安装方法。我们将创建一个名为ngx_http_hello_module.c的文件。

3.2 编写config文件

首先，我们需要创建一个config文件，告诉Nginx编译系统如何编译我们的模块：



ngx_addon_name=ngx_http_hello_module
HTTP_MODULES="$HTTP_MODULES ngx_http_hello_module"
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_module.c"

这个文件相当于模块的“出生证明”，让Nginx在configure过程中能找到并编译我们的模块。

3.3 定义模块结构

接下来，我们定义模块的核心结构：



ngx_module_t ngx_http_hello_module = {
    NGX_MODULE_V1,
    &ngx_http_hello_module_ctx,    /* module context */
    ngx_http_hello_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
};

这是模块的“整体外观”，Nginx通过这个结构来识别和管理模块。

3.4 创建配置结构体和指令

现在，我们实现模块的具体功能部件：



/* 配置结构体 */
typedef struct {
    ngx_str_t hello_string;
    ngx_int_t hello_counter;
} ngx_http_hello_loc_conf_t;
 
/* 创建location配置 */
static void *
ngx_http_hello_create_loc_conf(ngx_conf_t *cf)
{
    ngx_http_hello_loc_conf_t *conf;
    
    conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_hello_loc_conf_t));
    if (conf == NULL) {
        return NULL;
    }
    
    /* 设置默认值 */
    conf->hello_string = ngx_string("Hello, World!");
    conf->hello_counter = 0;
    
    return conf;
}
 
/* 配置指令 */
static ngx_command_t ngx_http_hello_commands[] = {
    {
        ngx_string("hello_string"),
        NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
        ngx_conf_set_str_slot,
        NGX_HTTP_LOC_CONF_OFFSET,
        offsetof(ngx_http_hello_loc_conf_t, hello_string),
        NULL
    },
    {
        ngx_string("hello_counter"),
        NGX_HTTP_LOC_CONF|NGX_CONF_FLAG,
        ngx_conf_set_flag_slot,
        NGX_HTTP_LOC_CONF_OFFSET,
        offsetof(ngx_http_hello_loc_conf_t, hello_counter),
        NULL
    },
    ngx_null_command
};

注意这里我们使用了Nginx内置的配置处理函数ngx_conf_set_str_slot和ngx_conf_set_flag_slot，这样可以省去自己编写配置解析逻辑的麻烦。

3.5 实现请求处理函数

这是模块的“大脑”，负责实际处理请求：



/* 请求处理函数 */
static ngx_int_t
ngx_http_hello_handler(ngx_http_request_t *r)
{
    ngx_int_t rc;
    ngx_buf_t *b;
    ngx_chain_t out;
    ngx_http_hello_loc_conf_t *hlcf;
    
    /* 获取location配置 */
    hlcf = ngx_http_get_module_loc_conf(r, ngx_http_hello_module);
    
    /* 只允许GET和HEAD方法 */
    if (!(r->method & (NGX_HTTP_GET|NGX_HTTP_HEAD))) {
        return NGX_HTTP_NOT_ALLOWED;
    }
    
    /* 丢弃请求体 */
    rc = ngx_http_discard_request_body(r);
    if (rc != NGX_OK) {
        return rc;
    }
    
    /* 设置响应头 */
    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = hlcf->hello_string.len;
    r->headers_out.content_type.len = sizeof("text/plain") - 1;
    r->headers_out.content_type.data = (u_char *) "text/plain";
    
    /* 发送响应头 */
    rc = ngx_http_send_header(r);
    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }
    
    /* 如果有计数器，更新它 */
    if (hlcf->hello_counter) {
        /* 这里可以实现计数器逻辑 */
    }
    
    /* 分配响应缓冲区 */
    b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t));
    if (b == NULL) {
        return NGX_HTTP_INTERNAL_SERVER_ERROR;
    }
    
    /* 设置响应缓冲区 */
    b->pos = hlcf->hello_string.data;
    b->last = hlcf->hello_string.data + hlcf->hello_string.len;
    b->memory = 1;
    b->last_buf = 1;
    
    /* 发送响应体 */
    out.buf = b;
    out.next = NULL;
    
    return ngx_http_output_filter(r, &out);
}

这个处理函数完成了以下工作：

获取配置信息检查HTTP方法是否允许设置响应头发送响应头准备并发送响应体

3.6 注册处理函数

最后，我们需要在模块上下文中注册处理函数，让Nginx知道在遇到对应location时调用我们的handler：



/* 模块上下文 */
static ngx_http_module_t ngx_http_hello_module_ctx = {
    NULL,                          /* preconfiguration */
    ngx_http_hello_init,           /* postconfiguration */
    NULL,                          /* create main configuration */
    NULL,                          /* init main configuration */
    NULL,                          /* create server configuration */
    NULL,                          /* merge server configuration */
    ngx_http_hello_create_loc_conf, /* create location configuration */
    NULL                           /* merge location configuration */
};
 
/* 在postconfiguration钩子中注册handler */
static ngx_int_t
ngx_http_hello_init(ngx_conf_t *cf)
{
    ngx_http_handler_pt *h;
    ngx_http_core_main_conf_t *cmcf;
    
    cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);
    
    h = ngx_array_push(&cmcf->phases[NGX_HTTP_CONTENT_PHASE].handlers);
    if (h == NULL) {
        return NGX_ERROR;
    }
    
    *h = ngx_http_hello_handler;
    
    return NGX_OK;
}

第四章编译与测试：让模块跑起来

4.1 编译模块

将我们的C文件和config文件放到一个目录，然后重新编译Nginx：



./configure --add-module=/path/to/hello/module
make
sudo make install

如果一切顺利，我们的handler模块就已经编译进Nginx了。

4.2 配置Nginx

在nginx.conf中添加location配置来使用我们的模块：



server {
    listen 80;
    server_name localhost;
    
    location /hello {
        hello_string "Hello, Nginx Handler Module!";
        hello_counter on;
    }
}

4.3 测试模块

重启Nginx后，访问http://your-server/hello，应该能看到我们自定义的问候语。

第五章高级技巧：让Handler模块更强大

5.1 添加更多配置选项

我们可以扩展配置结构体和指令，让模块更加灵活：



typedef struct {
    ngx_str_t hello_string;
    ngx_int_t hello_counter;
    ngx_int_t show_time;
    ngx_str_t custom_header;
} ngx_http_hello_loc_conf_t;
 
static ngx_command_t ngx_http_hello_commands[] = {
    /* 已有指令... */
    {
        ngx_string("show_time"),
        NGX_HTTP_LOC_CONF|NGX_CONF_FLAG,
        ngx_conf_set_flag_slot,
        NGX_HTTP_LOC_CONF_OFFSET,
        offsetof(ngx_http_hello_loc_conf_t, show_time),
        NULL
    },
    {
        ngx_string("hello_custom_header"),
        NGX_HTTP_LOC_CONF|NGX_CONF_TAKE1,
        ngx_conf_set_str_slot,
        NGX_HTTP_LOC_CONF_OFFSET,
        offsetof(ngx_http_hello_loc_conf_t, custom_header),
        NULL
    },
    ngx_null_command
};

5.2 处理查询参数

我们可以从请求中提取查询参数，实现更动态的响应：



static ngx_int_t
ngx_http_hello_handler(ngx_http_request_t *r)
{
    /* 已有代码... */
    
    /* 处理查询参数 */
    ngx_str_t name;
    if (ngx_http_arg(r, (u_char *)"name", 4, &name) == NGX_OK) {
        /* 根据name参数定制响应 */
    }
    
    /* 更多处理逻辑... */
}

5.3 错误处理最佳实践

健壮的错误处理是高质量模块的关键：



static ngx_int_t
ngx_http_hello_handler(ngx_http_request_t *r)
{
    /* 尝试获取配置 */
    hlcf = ngx_http_get_module_loc_conf(r, ngx_http_hello_module);
    if (hlcf == NULL) {
        ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
                      "Failed to get hello module configuration");
        return NGX_HTTP_INTERNAL_SERVER_ERROR;
    }
    
    /* 其他代码... */
}