以为Nginx开发难上天？其实搞定头文件就成功了一半。
还记得第一次打开Nginx源代码时的那种迷茫吗？密密麻麻的文件，错综复杂的关系，不知道从何入手。别担心，今天我们就来聊聊Nginx开发中最基础却又最重要的一部分——头文件。
这就像是探索一个神秘城堡，头文件就是你手中的地图，没了它，你只能在走廊里瞎转悠。有了它，你就能开启密室，找到宝藏！
0 01：Nginx源码探险必备地图
在你开始Nginx模块开发之前，第一件事就是搞清楚代码布局。Nginx的源代码有着清晰的组织结构，理解这个结构是你成为Nginx开发高手的第一步。
打开Nginx源码目录，你会发现以下几个核心文件夹：
- auto — 构建脚本，是Nginx自动化构建的核心。
- src
-
- core — 这里是Nginx的心脏，包含了基本类型和函数——字符串、数组、日志、内存池等基础设施。
- event — 事件核心，Nginx高性能的秘诀就在这里。
- modules — 事件通知模块：epoll、kqueue、select等，根据不同操作系统进行优化。
- http — 核心HTTP模块和通用代码。
- os — 平台特定代码，保证Nginx跨平台的能力。
- stream — 流模块，处理四层协议转发。
想象一下，core目录就像是汽车的发动机，event模块是传动系统，而http和stream则是不同的车型——一个拉人（HTTP请求），一个拉货（TCP/UDP流量）。这样的设计既保证了核心功能的稳定，又为扩展留出了充足空间。
0 02：头文件——Nginx世界的通行证
在Nginx开发中，头文件就像是进入不同区域的通行证。每个Nginx源文件的开头都必须包含两个基础头文件：
#include <ngx_config.h>
#include <ngx_core.h>这两个头文件提供了Nginx最核心的数据结构、函数声明和宏定义。无论你写什么类型的模块，这两个都是必须的。
但故事还没结束——根据你开发的模块类型，还需要额外的通行证：
- HTTP代码应该包含
#include <ngx_http.h>- 邮件代码应该包含
#include <ngx_mail.h>- 流代码应该包含
#include <ngx_stream.h>这就好比你去游乐园，ngx_config.h和ngx_core.h是基础门票，可以进大门但玩不了项目。而要玩水上乐园（HTTP）、过山车（邮件）或者鬼屋（流），就需要额外的通行证。
为什么这么设计？ 为了模块化和编译效率。每个头文件只包含其对应模块所需的声明，避免了不必要的代码暴露和依赖。当你开发HTTP模块时，不需要关心邮件相关的代码，这样编译更快，代码也更清晰。
0 03：Nginx世界的“通用语言”
在Nginx的宇宙里，有一套自成一体的“通用语言”——基本数据类型和返回值代码。掌握这些，是你与Nginx代码沟通的基础。
整数类型：为什么不用int？
Nginx定义了两种整数类型：
ngx_int_t— 有符号整数ngx_uint_t— 无符号整数
它们实际上是intptr_t和uintptr_t的类型定义。为什么不直接用int？为了跨平台兼容性。在不同平台上，int的大小可能不同，而使用这些明确大小的类型可以确保代码在所有平台上行为一致。
返回码：Nginx函数的世界语
当你调用Nginx函数时，它们会返回一套标准化的返回码：
- NGX_OK — 操作成功，皆大欢喜。
- NGX_ERROR — 操作失败，出问题了。
- NGX_AGAIN — 操作未完成，需要再次调用该函数。
- NGX_DECLINED — 操作被拒绝，但不是错误。
- NGX_BUSY — 资源不可用。
- NGX_DONE — 操作完成或在其他地方继续。
- NGX_ABORT — 函数被中止。
这些返回码构成了Nginx内部的错误处理体系，让你的模块可以与Nginx核心以及其他模块顺畅通信。
0 04：字符串处理——Nginx的独门秘籍
如果你以为Nginx会用标准C字符串处理函数，那就大错特错了！Nginx有一套自己设计的字符串处理系统，专门为高性能场景优化。
Nginx字符串类型
与C语言的裸指针不同，Nginx定义了自己的字符串类型：
typedef struct {
size_t len;
u_char *data;
} ngx_str_t;这种设计有两个关键优势：
- 不需要以null结尾：
len字段明确指出了字符串长度，不需要遍历整个字符串找结尾，性能更高。 - 可以包含二进制数据：因为不依赖null终止符，所以可以处理包含null字符的二进制数据。
字符串工具函数
Nginx提供了一系列字符串处理函数，可以分为两大类：
标准C函数的包装：
ngx_strcmp() // 字符串比较
ngx_strncmp() // 有限长度的字符串比较
ngx_strstr() // 查找子串
ngx_strlen() // 字符串长度
ngx_memcmp() // 内存比较
ngx_memset() // 内存设置
ngx_memcpy() // 内存拷贝
ngx_memmove() // 内存移动（处理重叠区域）Nginx特有的函数：
ngx_memzero() // 用零填充内存
ngx_explicit_memzero() // 明确清零，不会被编译器优化掉
ngx_cpymem() // 拷贝内存并返回目标结束地址
ngx_strlow() // 将字符串转换为小写
ngx_strcasecmp() // 不区分大小写的字符串比较字符串初始化的技巧
Nginx提供了方便的宏来初始化字符串：
// 从C字符串字面量静态初始化ngx_str_t
ngx_str_t str = ngx_string("Hello World");
// 静态空字符串初始化器
ngx_str_t empty_str = ngx_null_string;
// 初始化ngx_str_t指针
ngx_str_set(&str, "New String");
// 使用空字符串初始化ngx_str_t指针
ngx_str_null(&str);这些宏简化了代码，减少了出错的可能性，是Nginx开发中的常用技巧。
0 05：错误处理——优雅地应对问题
在Nginx世界中，错误处理是一门艺术。Nginx提供了完善的错误处理机制，让你的模块可以优雅地应对各种问题。
获取错误信息
ngx_errno宏返回最后一个系统错误代码。在POSIX平台上它映射到errno，在Windows上映射到GetLastError()调用。对于套接字错误，使用ngx_socket_errno宏。
但要注意：连续多次访问ngx_errno或ngx_socket_errno可能会导致性能问题。正确的做法是将错误值保存在局部变量中：
ngx_int_t
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
ngx_err_t err;
if (kill(pid, signo) == -1) {
err = ngx_errno;
ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);
if (err == NGX_ESRCH) {
return 2;
}
return 1;
}
return 0;
}这个例子展示了Nginx错误处理的典型模式：获取错误、记录日志、根据错误类型采取不同措施。
设置错误信息
要设置错误，使用ngx_set_errno(errno)和ngx_set_socket_errno(errno)宏。这些宏提供了跨平台的错误设置能力。
0 06：实战！从头文件开始写一个Nginx模块
理论说了这么多，现在让我们动手实践，从头开始创建一个简单的Nginx模块，感受头文件在实际开发中的作用。
第一步：设置基础头文件
我们创建一个HTTP模块，所以需要包含必要的头文件：
#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h> // HTTP模块必须
// 模块函数声明
static ngx_int_t ngx_http_hello_handler(ngx_http_request_t *r);
static char *ngx_http_hello(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
// 模块命令定义
static ngx_command_t ngx_http_hello_commands[] = {
{
ngx_string("hello"),
NGX_HTTP_MAIN_CONF|NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_HTTP_LMT_CONF|NGX_CONF_NOARGS,
ngx_http_hello,
NGX_HTTP_LOC_CONF_OFFSET,
0,
NULL
},
ngx_null_command
};
// HTTP模块上下文
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 */
NULL, /* create location configuration */
NULL /* merge location configuration */
};
// 模块定义
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
};注意看，我们的模块定义中使用了NGX_MODULE_V1和NGX_MODULE_V1_PADDING——这些宏来自头文件，确保了不同Nginx版本间的兼容性。
第二步：实现请求处理函数
现在实现核心的请求处理函数：
static ngx_int_t
ngx_http_hello_handler(ngx_http_request_t *r)
{
// 只允许GET或HEAD方法
if (!(r->method & (NGX_HTTP_GET|NGX_HTTP_HEAD))) {
return NGX_HTTP_NOT_ALLOWED;
}
// 丢弃请求中的包体
ngx_int_t rc = ngx_http_discard_request_body(r);
if (rc != NGX_OK) {
return rc;
}
// 设置返回的Content-Type
ngx_str_t type = ngx_string("text/plain");
// 返回的包体内容
ngx_str_t response = ngx_string("Hello World! This is my first Nginx module!");
// 设置返回状态码
r->headers_out.status = NGX_HTTP_OK;
// 设置Content-Length
r->headers_out.content_length_n = response.len;
// 设置Content-Type
r->headers_out.content_type = type;
// 发送HTTP头部
rc = ngx_http_send_header(r);
if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
return rc;
}
// 构造ngx_buf_t结构体准备发送包体
ngx_buf_t *b;
b = ngx_create_temp_buf(r->pool, response.len);
if (b == NULL) {
return NGX_HTTP_INTERNAL_SERVER_ERROR;
}
// 将响应内容复制到缓冲区
ngx_memcpy(b->pos, response.data, response.len);
b->last = b->pos + response.len;
b->last_buf = 1; // 这是最后一个缓冲区
// 发送包体
ngx_chain_t out;
out.buf = b;
out.next = NULL;
return ngx_http_output_filter(r, &out);
}这个处理函数展示了Nginx模块开发中的几个关键点：
- 方法检查：确保只处理允许的HTTP方法。
- 请求体处理：明确丢弃不需要的请求体。
- 响应头设置：通过
headers_out结构设置响应状态、长度和类型。 - 头部发送：调用
ngx_http_send_header发送响应头。 - 响应体处理：使用Nginx的缓冲区链发送响应体。
第三步：实现配置处理函数
static char *
ngx_http_hello(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
ngx_http_core_loc_conf_t *clcf;
// 找到location配置
clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
// 设置处理函数
clcf->handler = ngx_http_hello_handler;
return NGX_CONF_OK;
}这个配置函数将我们的处理函数注册到location配置中。
第四步：编译和配置
在config文件中定义模块：
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配置中使用模块：
server {
listen 80;
server_name localhost;
location /hello {
hello;
}
}现在访问http://localhost/hello，就能看到我们模块返回的欢迎信息了！
0 07：头文件使用中的“坑”与“术”
即使是经验丰富的Nginx开发者，在头文件使用中也可能会遇到一些坑。下面是一些常见问题及解决方案：
内存管理陷阱
Nginx使用内存池管理内存，这与其他系统有很大不同。永远不要使用标准的malloc/free，而要使用Nginx内存池接口：
// 从内存池分配内存
void *buf = ngx_palloc(r->pool, size);
// 分配并清零内存
void *buf = ngx_pcalloc(r->pool, size);字符串初始化时机
要注意Nginx字符串的初始化时机：
// 错误！局部变量data在函数返回后失效
u_char data[] = "hello";
ngx_str_t str = {5, data};
// 正确！从内存池分配
u_char *data = ngx_palloc(r->pool, 6);
ngx_memcpy(data, "hello", 5);
ngx_str_t str = {5, data};头文件包含顺序
虽然Nginx没有严格规定头文件包含顺序，但推荐以下顺序：
- 系统头文件
- Nginx核心头文件
- 模块特定头文件
这样可以避免隐式依赖和编译错误。
0 08：从读懂到创造——头文件的学习路径
想要真正掌握Nginx头文件？我建议遵循以下学习路径：
- 阅读阶段：从
src/core/ngx_string.h、src/core/ngx_array.h等基础头文件开始，理解Nginx的核心数据结构。 - 模仿阶段：找一些简单的官方模块（如echo模块、empty_gif模块），看看它们如何使用头文件中定义的功能。
- 实践阶段：从修改现有模块开始，逐步尝试编写自己的简单模块。
- 深入阶段：阅读
src/core/ngx_buf.h、src/core/ngx_event.h等高级头文件，理解Nginx的底层机制。
记住，头文件是Nginx模块开发的API文档，通过阅读头文件，你可以了解每个函数、每个数据结构的用途和用法。
结语：头文件——通往Nginx高手之路的钥匙
当我们第一次面对Nginx源代码时，头文件往往是最不起眼的部分。但通过今天的探讨，你会发现这些看似简单的头文件背后，蕴含着Nginx架构设计的智慧。
从最基本的ngx_config.h和ngx_core.h，到专门的ngx_http.h、ngx_mail.h，再到各种工具函数和数据类型，Nginx头文件构成了一套完整的开发框架。
掌握头文件，就等于拿到了开启Nginx开发大门的钥匙。现在，是时候拿起这把钥匙，开启你的Nginx模块开发之旅了！
扫一扫
615
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
