nginx-c-modules

nginx.org nginx C 模块开发最佳实践

这是一份全面的 nginx C 模块开发指南，基于 nginx 官方开发文档和社区经验整理而成。指南涵盖 8 个类别中的 49 条规则，并按影响程度排序，旨在指导正确实现模块，避免常见崩溃、内存泄漏和未定义行为。

适用场景

以下情况可参考这些指南：

• 编写新的 nginx C 模块（处理程序、过滤器、上游、负载均衡器）
• 实现配置指令和合并逻辑
• 使用 nginx 内存池和共享内存区域管理内存
• 处理 HTTP 请求生命周期（读取请求体、子请求、完成请求）
• 使用 nginx 事件循环、定时器和线程池

规则类别与优先级

优先级	类别	影响	前缀
1	内存管理	CRITICAL	mem-
2	请求生命周期	CRITICAL	req-
3	配置系统	HIGH	conf-
4	处理程序开发	HIGH	handler-
5	过滤器链	MEDIUM-HIGH	filter-
6	上游与代理	MEDIUM	upstream-
7	事件循环与并发	MEDIUM	event-
8	数据结构与字符串	LOW-MEDIUM	ds-

快速参考

1. 内存管理（CRITICAL）

• mem-pool-allocation - 使用内存池分配，而不是堆分配 malloc
• mem-check-allocation - 检查每次分配的返回值是否为 NULL
• mem-pcalloc-structs - 使用 ngx_pcalloc 初始化结构体
• mem-cleanup-handlers - 为外部资源注册内存池清理处理程序
• mem-pnalloc-strings - 使用 ngx_pnalloc 分配字符串数据
• mem-pfree-limitations - 避免依赖 ngx_pfree 释放内存池分配
• mem-shared-slab - 对共享内存区域使用 Slab 分配器

2. 请求生命周期（CRITICAL）

• req-finalize-once - 每个请求只能完成一次
• req-no-access-after-finalize - 请求完成后绝不再访问该请求
• req-body-async - 异步处理请求体读取
• req-discard-body - 不读取请求体时应丢弃请求体
• req-subrequest-completion - 使用子请求后的处理程序处理完成逻辑
• req-count-reference - 异步操作前增加请求计数
• req-internal-redirect - 内部重定向后立即返回

3. 配置系统（HIGH）

• conf-unset-init - 使用 UNSET 常量初始化配置字段
• conf-merge-all-fields - 在 merge_loc_conf 中合并所有配置字段
• conf-context-flags - 为指令使用正确的上下文标志
• conf-null-command - 使用 ngx_null_command 终止命令数组
• conf-custom-handler - 使用自定义处理程序解析复杂指令
• conf-module-ctx-null - 将未使用的模块上下文回调设为 NULL
• conf-build-config - 为模块编译编写正确的 config 构建脚本

4. 处理程序开发（高）

• handler-send-header-first - 在输出正文之前发送标头
• handler-last-buf - 在最后一个缓冲区上设置 last_buf 标志
• handler-phase-registration - 在 postconfiguration 中注册阶段处理程序
• handler-content-handler - 使用 content_handler 为特定 Location 生成响应
• handler-error-page - 为错误响应返回 HTTP 状态码
• handler-empty-response - 对空正文响应使用 header_only
• handler-module-ctx - 使用模块上下文保存每个请求的状态
• handler-add-variable - 在 preconfiguration 中注册自定义变量

5. 过滤器链（中高）

• filter-registration-order - 在 postconfiguration 中保存并替换顶部过滤器
• filter-call-next - 始终调用链中的下一个过滤器
• filter-check-subrequest - 在过滤器中区分主请求和子请求
• filter-buffer-chain-iteration - 使用 cl->next 模式遍历缓冲区链
• filter-buffering-flag - 累积响应数据时设置缓冲标志

6. 上游与代理（中）

• upstream-create-request - 在 create_request 中构建完整的请求缓冲区
• upstream-process-header - 在 process_header 中增量解析上游响应
• upstream-peer-free - 在 peer free 回调中跟踪故障
• upstream-finalize - 在 finalize_request 回调中清理资源
• upstream-connection-reuse - 为上游连接启用 Keepalive

7. 事件循环与并发（中）

• event-no-blocking - 切勿在事件处理程序中使用阻塞调用
• event-timer-management - 释放关联数据前删除定时器
• event-handle-read-write - 在 I/O 操作后调用 ngx_handle_read/write_event
• event-thread-pool - 将阻塞操作交由线程池处理
• event-posted-events - 使用已投递事件进行延迟处理

8. 数据结构与字符串（低中）

• ds-ngx-str-not-null-terminated - 切勿假设 ngx_str_t 以 null 结尾
• ds-ngx-str-set-literals - 仅对字符串字面量使用 ngx_string 宏
• ds-cpymem-pattern - 使用 ngx_cpymem 顺序写入缓冲区
• ds-list-iteration - 使用基于部分的模式遍历 ngx_list_t
• ds-hash-readonly - 仅在配置期间构建哈希表

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息