nginx filter模块基于静态注册、初始化串联的单向过滤链表实现响应处理，header_filter须先于body_filter执行，write_filter为唯一与socket交互的终点模块。

Nginx 的 Filter 模块本质是基于“过滤链表（Filter Chain）”实现的响应处理流水线，所有输出内容都必须依次经过这一串预注册的过滤器，每个过滤器只负责一项明确的转换任务，彼此解耦、顺序执行、不可跳过。

过滤链表不是运行时动态拼接的，而是编译期静态注册 + 初始化时线性串联

Nginx 在源码中通过宏（如 ngx_http_top_body_filter、ngx_http_top_header_filter）定义全局过滤器链头指针。各模块（如 gzip、chunked、range、charset）在自己的 ngx_http_module_t 结构中实现 postconfiguration 回调，在该回调里将自己的过滤函数用 ngx_http_next_*_filter 方式“挂载”到对应链表尾部。最终形成一条从 top 到 bottom 的单向链表，例如：

• header_filter 链：addition → charset → gzip → chunked → … → ngx_http_write_filter（最底层）
• body_filter 链：gzip → range → sub → … → ngx_http_write_filter（与 header 共用底层写入）

这个链表一旦初始化完成就固定不变，请求处理过程中不会增删节点，只按序调用。

每个过滤器接收“缓冲区链表（ngx_chain_t *in）”，返回“处理后的链表（ngx_chain_t *out）”

Filter 函数签名统一为：
ngx_int_t filter_name(ngx_http_request_t *r, ngx_chain_t *in)

它不直接操作 socket，也不关心上层逻辑，只做三件事：

• 遍历传入的 ngx_chain_t 链，读取其中每个 ngx_buf_t 的数据（可能为内存或文件）
• 按需修改 buf 内容（如 gzip 压缩）、拆分/合并 buf、新增 buf（如添加 ETag 头）、标记 last_buf 等
• 构造新的 chain 链，调用下一个 filter（即 r->filter_ctx 或全局 next 指针所指函数）

典型例子：gzip filter 会将原始 body 缓冲区压缩后生成新 buf，并把旧 buf 标记为 consumed；chunked filter 则在每个 buf 前插入长度头、末尾加 CRLF，最后追加 “0\r\n\r\n”。

header 和 body 过滤链分离但协同工作，且 header 必须先于 body 发送

Nginx 强制要求：所有 header_filter 必须在第一个 body_filter 调用前执行完毕。这是因为：

• header_filter 链最终会调用 ngx_http_send_header()，触发状态机进入 “HTTP_HEADER_SENT” 阶段
• 此后任何对 r->headers_out 的修改都将被忽略（除非启用 underscores_in_headers 等特殊机制）
• body_filter 只在 header 已发送后才开始处理响应体，避免协议错乱（如 Content-Length 与实际 body 不符）

因此自定义 filter 若需影响 header（如注入 X-Response-Time），必须注册为 header_filter；若要改写响应体（如 HTML 注入脚本），则必须走 body_filter。

底层 write_filter 是链表终点，负责真正写入连接缓冲区并触发 send syscall

ngx_http_write_filter 是整个过滤链的收口模块，它的核心职责包括：

• 聚合上游 filter 输出的多个小 buf，尝试合并以减少系统调用次数
• 检查当前连接是否支持 sendfile、TCP_NOPUSH、TCP_NODELAY 等优化选项
• 将最终 buf 写入 c->buffer（连接级输出缓冲区），并在缓冲区满或显式 flush 时调用 ngx_linux_sendfile_chain 或 ngx_unix_send
• 判断是否已发送全部数据（last_buf / last_in_chain），决定是否关闭连接或等待下一次事件

这意味着：即使你写了 10 个 filter，只要 write_filter 没发出去，客户端就收不到任何字节——它是整个链表唯一与内核 socket 交互的环节。