目录
0. 摘要
1. nginx模块组织结构
2. nginx模块数据结构
3. nginx模块初始化
4. 一个简单的http模块
5. 小结
6. 参考资料
0. 摘要
nginx有五大优点：模块化、事件驱动、异步、非阻塞、多进程单线程。其中，模块化设计类似于面向对象中的接口类，它增强了nginx源码的可读性、可扩充性和可维护性。
nginx-1.4.0总共有5大一类模块：core、conf、event、http、mail，和48个二类模块（我自己的安装版本）。每个模块有属于自己的配置项，由commands字段决定；模块在初始化和退出销毁时均有回调函数。多进程模式下的模块初始化主要有四个方面：脚本初始化、静态初始化、动态初始化、进程初始化。脚本初始化是指在安装nginx时，由configure脚本生成的相关文件，比如ngx_modules.c文件包含了nginx的所有模块；静态初始化在编译时就完成，主要通过定义全局变量实现；动态初始化在运行时完成，主要通过master进程main函数，ngx_init_cycle函数，及各模块文件内定义的init函数实现；进程初始化是指各worker进程执行 init_process函数。当nginx退出或重读配置文件或nginx平滑升级时，worker进程会调用各模块的exit_process函数来销毁资源。
开发人员可以根据nginx模块规则注册自己的模块，添加模块后要重新编译源码，并且修改nginx.conf配置文件才能使新模块生效。
1. nginx模块组织结构
nginx源码虽然是用c语言写的，但一点也不妨碍nginx以高度模块化闻名，这来自于nginx作者对c语言和面向对象的高度驾驭能力。
1.1 nginx模块主要轮廓
Nginx模块主要有4种角色：
(1) core(核心模块)：构建nginx基础服务、管理其他模块。
(2) handlers(处理模块)： 用于处理HTTP请求，然后产生输出。
(3) filters（过滤模块）： 过滤handler产生的输出。
(4) load-balancers（负载均衡模块）：当有多于一台的后端备选服务器时，选择一台转发HTTP请求。
Nginx的核心模块主要负责建立nginx服务模型、管理网络层和应用层协议、以及启动针对特定应用的一系列候选模块。其他模块负责分配给web服务器的实际工作：当Nginx发送文件或者转发请求到其他服务器，由处理模块或负载均衡模块提供服务；当需要Nginx把输出压缩或者在服务端加一些东西，由过滤模块提供服务。
那么模块是如何被调用的？当服务器启动，每个处理模块都有机会映射到配置文件中定义的特定位置（location）；如果有多个处理模块映射到特定位置时，只有一个会“赢”（说明配置文件有冲突项，应该避免发生）。处理模块以三种形式返回：OK、ERROR、或者放弃处理这个请求而让默认处理模块来处理（主要是用来处理一些静态文件，事实上如果是位置正确而真实的静态文件，默认的处理模块会抢先处理）。
如果处理模块把请求反向代理到后端的服务器，就变成另外一类的模块：负载均衡模块。负载均衡模块的配置中有一组后端服务器，当一个HTTP请求过来时，它决定哪台服务器应当获得这个请求。Nginx的负载均衡模块采用两种方法：轮转法，它处理请求就像纸牌游戏一样从头到尾分发；IP哈希法，在众多请求的情况下，它确保来自同一个IP的请求会分发到相同的后端服务器。
如果处理模块没有产生错误，过滤模块将被调用。多个过滤模块能映射到每个位置，所以（比如）每个请求都可以被压缩成块。它们的执行顺序在编译时决定。过滤模块是经典的“接力链表（CHAIN OF RESPONSIBILITY）”模型：一个过滤模块被调用，完成其工作，然后调用下一个过滤模块，直到最后一个过滤模块。Nginx完成这个回复。过滤模块链的特别之处在于，每个过滤模块不会等上一个过滤模块全部完成；它能把前一个过滤模块的输出作为其处理内容；有点像Unix中的流水线。过滤模块能以buffer（缓冲区）为单位进行操作，这些buffer一般都是一页（4K）大小，当然你也可以在nginx.conf文件中进行配置。这意味着，比如，模块可以压缩来自后端服务器的回复，然后像流一样的到达客户端，直到整个回复发送完成。总之，过滤模块链以流水线的方式高效率地向客户端发送响应信息。
所以总结下上面的内容，一个典型的处理周期是这样的：
客户端发送HTTP请求->Nginx基于配置文件中的位置选择一个合适的处理模块->（如果有）负载均衡模块选择一台后端服务器->处理模块进行处理并把输出缓冲放到第一个过滤模块上->第一个过滤模块处理后输出给第二个过滤模块->然后第二个过滤模块又到第三个->依此类推->最后把回复发给客户端。
图1.1展示了nginx模块处理流程。
图1.1 nginx模块处理流程图
1.2 nginx模块结构设计
图1.2 nginx 模块结构设计图
图1.3 nginx主要模块组织结构简图
2. nginx模块数据结构
2.1 模块主要数据结构
（1）核心：ngx_module_t（nginx所有模块的数据结构模板）
#define NGX_MODULE_V1 0, 0, 0, 0, 0, 0, 1 // 初始化 ngx_module_s 前7个字段
#define NGX_MODULE_V1_PADDING 0, 0, 0, 0, 0, 0, 0, 0 // 初始化 ngx_module_s 最后8个字段
typedef struct ngx_module_s ngx_module_t;
struct ngx_module_s {
ngx_uint_t ctx_index; // ctx:context 分类模块索引，比如http类型模块有很多实例
ngx_uint_t index; // 全局模块索引,在nginx.c中main函数体内进行动态初始化 ngx_uint_t spare0; // 目前未使用
ngx_uint_t spare1; // 目前未使用
ngx_uint_t spare2; // 目前未使用
ngx_uint_t spare3; // 目前未使用 ngx_uint_t version; // 模块版本 void *ctx; // 该模块的上下文，一般用来创建和初始化模块配置数据结构，每个种类的模块有不同的上下文
ngx_command_t *commands;// 该模块对应的配置文件中的语句块，指向一个ngx_command_t结构数组
ngx_uint_t type;// 该模块的种类，为core/conf/event/http/mail中的一种
// 以下是一些callback函数
ngx_int_t (*init_master)(ngx_log_t *log); // 初始化master： 目前未使用 ngx_int_t (*init_module)(ngx_cycle_t *cycle);// 初始化模块 ngx_int_t (*init_process)(ngx_cycle_t *cycle); // 初始化工作进程
ngx_int_t (*init_thread)(ngx_cycle_t *cycle); // 初始化线程：目前未使用
void (*exit_thread)(ngx_cycle_t *cycle); // 退出线程：目前未使用
void (*exit_process)(ngx_cycle_t *cycle); // 退出工作进程 void (*exit_master)(ngx_cycle_t *cycle); // 退出master：目前未使用
// 这些字段：目前未使用
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;
};
（2） 配置文件指令：ngx_command_t（主要负责模块与配置文件nginx.conf的交互）
typedef struct ngx_command_s ngx_command_t;
#define NGX_CONF_NOARGS 0x00000001
#define NGX_CONF_TAKE1 0x00000002
#define NGX_CONF_TAKE2 0x00000004
#define NGX_CONF_TAKE3 0x00000008
#define NGX_CONF_TAKE4 0x00000010
#define NGX_CONF_TAKE5 0x00000020
#define NGX_CONF_TAKE6 0x00000040
#define NGX_CONF_TAKE7 0x00000080 #define NGX_CONF_MAX_ARGS 8 #define NGX_CONF_TAKE12 (NGX_CONF_TAKE1|NGX_CONF_TAKE2)
#define NGX_CONF_TAKE13 (NGX_CONF_TAKE1|NGX_CONF_TAKE3) #define NGX_CONF_TAKE23 (NGX_CONF_TAKE2|NGX_CONF_TAKE3) #define NGX_CONF_TAKE123 (NGX_CONF_TAKE1|NGX_CONF_TAKE2|NGX_CONF_TAKE3)
#define NGX_CONF_TAKE1234 (NGX_CONF_TAKE1|NGX_CONF_TAKE2|NGX_CONF_TAKE3 \
|NGX_CONF_TAKE4) #define NGX_CONF_ARGS_NUMBER 0x000000ff
#define NGX_CONF_BLOCK 0x00000100
#define NGX_CONF_FLAG 0x00000200
#define NGX_CONF_ANY 0x00000400
#define NGX_CONF_1MORE 0x00000800
#define NGX_CONF_2MORE 0x00001000
#define NGX_CONF_MULTI 0x00000000 /* compatibility */ #define NGX_DIRECT_CONF 0x00010000 #define NGX_MAIN_CONF 0x01000000
#define NGX_ANY_CONF 0x0F000000 #define NGX_CONF_UNSET -1
#define NGX_CONF_UNSET_UINT (ngx_uint_t) -1
#define NGX_CONF_UNSET_PTR (void *) -1
#define NGX_CONF_UNSET_SIZE (size_t) -1
#define NGX_CONF_UNSET_MSEC (ngx_msec_t) -1 #define NGX_CONF_OK NULL
#define NGX_CONF_ERROR (void *) -1 #define NGX_CONF_BLOCK_START 1
#define NGX_CONF_BLOCK_DONE 2
#define NGX_CONF_FILE_DONE 3 // 模块种类宏，定义为一个十六进制的数，这个十六进制的数就是其类型对应的ASCII码。
// 因此，nginx共有5种类型的模块，分别为"CORE","CONF","EVNT","HTTP","MAIL"。
#define NGX_CORE_MODULE 0x45524F43 /* "CORE" */
#define NGX_CONF_MODULE 0x464E4F43 /* "CONF" */ #define NGX_MAX_CONF_ERRSTR 1024 struct ngx_command_s {
ngx_str_t name; // 配置文件中的指令，如 daemon
// 指令出现的位置（main/http/server/location/upstream/mail）
// 指令值的数据类型，如NGX_CONF_FLAG表示指令读入一个布尔型数据
// 指令后带的参数，如NGX_CONF_TAKE1表示带一个参数
ngx_uint_t type;
char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); // 设置指令值到模块自定义数据结构
ngx_uint_t conf; // 一般为 0
ngx_uint_t offset; // 指令在数据结构的偏移量
void *post; // 一般为 NULL
}; #define ngx_null_command { ngx_null_string, 0, NULL, 0, 0, NULL }
（3）指令配置：ngx_conf_t（解析某个具体的指令）
typedef char *(*ngx_conf_handler_pt)(ngx_conf_t *cf, ngx_command_t *dummy, void *conf);
typedef struct ngx_conf_s ngx_conf_t;
struct ngx_conf_s {
char *name; // 指令名
ngx_array_t *args; // 指令后的参数 ngx_cycle_t *cycle; // 全局数据结构
ngx_pool_t *pool; // 内存池
ngx_pool_t *temp_pool; // 临时内存池
ngx_conf_file_t *conf_file; // 指令所在配置文件
ngx_log_t *log; // 日志记录 void *ctx; // 模块上下文
ngx_uint_t module_type; // 模块类型
ngx_uint_t cmd_type; // 指令类型 ngx_conf_handler_pt handler; // set函数指针
char *handler_conf; // set函数返回值
};
（4）全局配置：ngx_cycle_t（nginx绝大部分初始化操作都围绕该结构体）
typedef struct ngx_cycle_s ngx_cycle_t;
struct ngx_cycle_s {
void ****conf_ctx; // 配置上下文数组(含所有模块)
ngx_pool_t *pool; // 内存池 ngx_log_t *log; // 日志
ngx_log_t new_log; ngx_connection_t **files; // 连接文件
ngx_connection_t *free_connections; // 空闲连接
ngx_uint_t free_connection_n; // 空闲连接个数 ngx_queue_t reusable_connections_queue; // 再利用连接队列 ngx_array_t listening; // 监听套接字数组
ngx_array_t pathes; // 路径数组
ngx_list_t open_files; // 打开文件链表
ngx_list_t shared_memory; // 共享内存链表 ngx_uint_t connection_n; // 连接个数
ngx_uint_t files_n; // 打开文件个数 ngx_connection_t *connections; // 连接
ngx_event_t *read_events; // 读事件
ngx_event_t *write_events; // 写事件 ngx_cycle_t *old_cycle; // old cycle指针 ngx_str_t conf_file; // 配置文件
ngx_str_t conf_param; // 配置参数
ngx_str_t conf_prefix; // 配置文件目录
ngx_str_t prefix; // 程序工作目录
ngx_str_t lock_file; // 锁文件，用在不支持accept_mutex的系统中
ngx_str_t hostname; // 主机名
};
2.2 模块数据结构相关操作
（1）指令设置回调函数：*(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
结构体成员set是一个函数指针，用来设定模块的配置；典型地，这个函数会转化指令传进来的参数，然后将合适的值保存到配置结构体。这个设定函数有三个参数：
1）指向ngx_conf_t结构体的指针，包含从指令后面传过来的参数。
2）指向当前ngx_command_t结构体的指针
3）指向自定义模块配置结构体的指针
这个设定函数在指令被遇到的时候就会调用。在自定义的配置结构体中，Nginx提供了多个函数用来保存特定类型的数据，这些函数包含有：
1）ngx_conf_set_flag_slot: 将”on”或”off”转化为布尔类型
2）ngx_conf_set_str_slot: 将字符串保存为ngx_str_t类型
3）ngx_conf_set_num_slot: 解析一个数字并保存为int型
4）ngx_conf_set_size_slot: 解析一个数据大小(如：”8k”, “1m”) 并保存为 size_t类型
还有另外一些，很容易查到（看，core/ngx_conf_file.h）。模块也可以把它们自己函数的引用放在这里，但这样内嵌的类型不是很好。
那这些内嵌函数怎么知道要把值保存在哪里呢？ngx_command_t接下来的两个成员conf和offset正好可用。conf告诉Nginx把这个值是放在全局配置部分、主机配置部分还是位置配置部分呢（用NGX_HTTP_MAIN_CONF_OFFSET, NGX_HTTP_SRV_CONF_OFFSET或NGX_HTTP_LOC_CONF_OFFSET）。然后offset确定到底是保存在结构体的哪个位置。
最后，post指向模块在读配置的时候需要的一些零碎变量。一般它是NULL。
这个ngx_command_t数组在读入ngx_null_command 后停止，也即最后一个成员。