Nginx 模块开发之 Handler 与 Filter 区别

Handler模块负责生成响应内容，Filter模块负责对响应进行二次加工；Handler决定返回什么，每个location最多一个，直接操作请求结构体；Filter不产生内容，仅链式处理响应头或体，可叠加多个。

Handler 模块负责“怎么响应”，Filter 模块负责“怎么加工响应”。这是理解 Nginx 模块分工最直接的切入点。

Handler 是响应的源头

它接到请求后，决定返回什么内容——可能是读一个文件、调用后端服务、拼一段字符串，或者直接返回 404。整个过程发生在请求处理流程的早期阶段（如 NGX_HTTP_CONTENT_PHASE），且通常只有一个 Handler 参与最终响应生成。

• 每个 location 最多绑定一个 Handler，比如 ngx_http_static_module 处理静态文件，ngx_http_proxy_module 转发请求
• Handler 直接操作请求结构体（ngx_http_request_t*），可修改响应头、设置状态码、写入响应体
• 一旦某个 Handler 完成输出并调用 ngx_http_finalize_request，后续 Handler 就不再执行

Filter 是响应的流水线

它不产生原始内容，只在 Handler 输出之后介入，对已生成的响应头或响应体做二次处理。多个 Filter 可按顺序叠加，形成链式加工流程。

• 分为两类：Header Filter 修改 r->headers_out（如添加 X-Frame-Options）；Body Filter 处理输出缓冲区（如 gzip 压缩、HTML 插入脚本）
• 所有 Filter 模块注册到全局钩子（ngx_http_top_header_filter 和 ngx_http_top_body_filter），由 Nginx 自动串接调用
• 一个响应可能依次经过 gzip → chunked → charset 等多个 Filter，彼此互不影响、职责清晰

配置和加载方式不同

Handler 通常通过 location 块中的指令触发（如 proxy_pass、root），而 Filter 多数是全局启用或按条件启用，不依赖 location 绑定。

• Handler 模块需在配置中显式调用，例如 location /api { proxy_pass http://backend; } 激活 proxy handler
• Filter 模块常通过开关指令控制，如 gzip on; 或 add_header X-Powered-By "Nginx";，它们自动插入到 filter 链中
• 自定义模块开发时，Handler 注册到 phase handler 链，Filter 则挂载到 header/body filter 链，入口函数和回调机制完全不同

典型协作流程

一次请求的完整路径是：客户端 → Nginx 核心 → 匹配 location → 调用 Handler 生成初始响应 → 依次经过各 Header Filter → 再经各 Body Filter 加工 → 发送给客户端。

• Handler 输出的是“原材料”，比如未压缩的 HTML 字节流
• Filter 不改变语义逻辑，只优化传输或增强表现，比如压缩体积、统一编码、注入监控埋点
• 如果 Handler 没输出（如被 access 阶段拒绝），Filter 就完全不会运行