名称：nginx C模块 描述：基于官方nginx开发指南的nginx C模块开发指南。该技能应用于编写、审查或重构nginx C模块时，以确保正确的内存管理、请求生命周期处理和事件驱动模式。触发涉及nginx模块开发、ngx_http_module_t、处理程序/过滤器/上游实现、池分配或nginx配置指令的任务。
nginx.org C模块开发最佳实践
nginx C模块的综合开发指南，源自官方nginx开发文档和社区专业知识。包含8个类别中的49条规则，按影响优先级排列，以指导正确的模块实现并防止常见的崩溃、内存泄漏和未定义行为。
应用时机
在以下情况参考这些指南：
- 编写新的nginx C模块（处理程序、过滤器、上游、负载均衡器）
- 实现配置指令和合并逻辑
- 使用nginx池和共享内存区管理内存
- 处理HTTP请求生命周期（请求体读取、子请求、最终化）
- 使用nginx的事件循环、定时器和线程池
按优先级分类规则
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 内存管理 | 关键 | mem- |
| 2 | 请求生命周期 | 关键 | req- |
| 3 | 配置系统 | 高 | conf- |
| 4 | 处理程序开发 | 高 | handler- |
| 5 | 过滤器链 | 中高 | filter- |
| 6 | 上游与代理 | 中 | upstream- |
| 7 | 事件循环与并发 | 中 | event- |
| 8 | 数据结构与字符串 | 中低 | ds- |
快速参考
1. 内存管理（关键）
mem-pool-allocation- 使用池分配代替堆mallocmem-check-allocation- 检查每个分配返回值是否为NULLmem-pcalloc-structs- 使用ngx_pcalloc进行结构体初始化mem-cleanup-handlers- 为外部资源注册池清理处理程序mem-pnalloc-strings- 使用ngx_pnalloc分配字符串数据mem-pfree-limitations- 避免依赖ngx_pfree进行池分配mem-shared-slab- 使用Slab分配器进行共享内存区
2. 请求生命周期（关键）
req-finalize-once- 精确地最终化请求一次req-no-access-after-finalize- 在最终化后永远不要访问请求req-body-async- 异步处理请求体读取req-discard-body- 在不读取时丢弃请求体req-subrequest-completion- 使用后子请求处理程序完成req-count-reference- 在异步操作前增加请求计数req-internal-redirect- 在内部重定向后返回
3. 配置系统（高）
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- 将未使用的模块上下文回调设置为NULLconf-build-config- 为模块编译编写正确的配置构建脚本
4. 处理程序开发（高）
handler-send-header-first- 在主体输出前发送头部handler-last-buf- 在最终缓冲区设置last_buf标志handler-phase-registration- 在postconfiguration中注册阶段处理程序handler-content-handler- 使用content_handler进行位置特定的响应生成handler-error-page- 为错误响应返回HTTP状态码handler-empty-response- 为无主体响应使用header_onlyhandler-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_eventevent-thread-pool- 将阻塞操作卸载到线程池event-posted-events- 使用发布事件进行延迟处理
8. 数据结构与字符串（中低）
ds-ngx-str-not-null-terminated- 永远不要假设ngx_str_t是空终止的ds-ngx-str-set-literals- 仅将ngx_string宏用于字符串字面量ds-cpymem-pattern- 使用ngx_cpymem进行顺序缓冲区写入ds-list-iteration- 使用基于部分的模式迭代ngx_list_tds-hash-readonly- 仅在配置期间构建哈希表
如何使用
阅读个别参考文件获取详细解释和代码示例：
参考文件
| 文件 | 描述 |
|---|---|
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本和参考信息 |