1 定义ngx_http_send_header 函数 定义在 ./nginx-1.24.0/src/http/ngx_http_core_module.cngx_int_tngx_http_send_header(ngx_http_request_t*r){if(r-post_action){returnNGX_OK;}if(r-header_sent){ngx_log_error(NGX_LOG_ALERT,r-connection-log,0,header already sent);returnNGX_ERROR;}if(r-err_status){r-headers_out.statusr-err_status;r-headers_out.status_line.len0;}returnngx_http_top_header_filter(r);}2 目的1. 核心设计目的 ngx_http_send_header 是 Nginx HTTP 框架中 发送响应头的统一入口。 它的设计目的可以归纳为三点 1. 提供一个唯一且安全的发送起点 确保在整个 Nginx 系统中响应头的实际发送动作只从这一个地方开始 防止各个模块擅自发送头部而导致混乱。 2. 执行发送前的必要检查与修正 在数据流出前统一处理几项全局性的前置条件 如“是否还需要发送”、“状态码是否需要覆盖”等。 3. 将响应头推入过滤器链 调用 ngx_http_top_header_filter 启动由各个模块串起来的“头部过滤链”。 这条链可以对即将发送的头部做最后的修改、压缩或序列化 然后通过操作系统网络接口发送出去。2. 它在整体流程中的角色 ngx_http_send_header 的设计意图可以概括为 在请求处理的“内容生成阶段”结束后作为从“准备响应头”过渡到“网络发送”的闸门。 它依次完成了 - 检查是否应该跳过post_action - 检查是否已经发送过防止重复 - 最终确定 HTTP 状态码err_status 覆盖 - 启动过滤器链让所有模块完成最后的处理并发送 因此它是 Nginx 保证响应头正确、安全、且只发送一次的关键机制 也是模块化处理 HTTP 头部的基础。3 详解1 函数签名ngx_int_tngx_http_send_header(ngx_http_request_t*r)1. 返回值类型ngx_int_t 用于表示函数的执行状态。 这个函数返回一个整数值用来告诉调用者操作的结果。可能的返回值包括 NGX_OK成功。 可能是头部已经发送成功也可能因为特殊情况如 post_action 请求而无需发送。 NGX_ERROR 错误。例如检测到头部已经被重复发送或者底层发送操作失败。 调用者通过检查返回值是否为 NGX_OK 来判断函数是否正常完成。2. 函数名ngx_http_send_header 函数名由下划线分隔的多个部分组成遵循 Nginx 的命名惯例 ngx全局前缀表明这是 Nginx 源码的一部分用于避免命名冲突。 http表明该函数属于 HTTP 模块子系统处理 HTTP 协议相关的逻辑。 send动词意为“发送”。这里指将数据通过网络连接传输给客户端。 header名词指 HTTP 响应中的头部部分响应行和各个头部字段。 因此ngx_http_send_header 的完整含义是 在 HTTP 模块中将准备好的响应头发送给客户端的函数。3. 参数列表(ngx_http_request_t *r) 参数类型 ngx_http_request_t * ngx_http_request_t 是一个结构体类型包含了处理一个 HTTP 请求所需的所有信息 请求行、请求头部、将要发送的响应头部r-headers_out、客户端连接、 各种状态标志如 header_sent、err_status等。4. 签名整体反映出的设计信息 功能直接函数名明确指出了“发送头部”这个动作没有歧义。 依赖请求上下文 函数所需的一切都来自 r 参数状态标志、响应头内容、底层连接 不依赖外部全局变量。这使得函数的行为完全由请求状态决定安全且可预测。 返回状态 通过返回 NGX_OK 或 NGX_ERROR 来报告操作结果 与 Nginx 整体的错误处理风格一致。2 逻辑流程1. 特殊请求跳过 如果是 post_action 子请求不需要发送任何头部直接返回成功。 2. 重复发送防护 如果头部已经被发送过记录告警日志并返回错误避免协议违规。 3. 错误状态码覆盖 如果在处理过程中产生了错误状态码err_status则覆盖原有的响应状态码 并清空自定义状态行保证错误响应的一致性和正确性。 4. 启动过滤器链 调用 ngx_http_top_header_filter(r)将控制权交给过滤器链 由各个模块完成最终的头部处理、序列化和网络发送。1. 特殊请求跳过{if(r-post_action){returnNGX_OK;}检查是否为post_action请求r-post_action是请求结构体中的一个标志字段。当 Nginx 配置了post_action指令时主请求完成后会触发一个内部子请求这个子请求的post_action字段为非零值。作用判断当前请求是否是一个“后置动作”子请求。对于post_action子请求它的目的仅仅是在后台执行某个操作比如记录日志不需要向客户端返回任何数据包括响应头。因此函数直接返回NGX_OK表示“成功无事发生”。意义避免向客户端错误地发送多余的响应头确保post_action请求完全静默。2. 重复发送防护if(r-header_sent){ngx_log_error(NGX_LOG_ALERT,r-connection-log,0,header already sent);returnNGX_ERROR;}检查是否已经发送过响应头r-header_sent是请求结构体中的一个整数标志。当响应头已经被发送过一次后这个标志会被设置为 1。作用检测是否有重复发送头部的尝试。记录错误日志返回错误状态3. 错误状态码覆盖if(r-err_status){r-headers_out.statusr-err_status;r-headers_out.status_line.len0;}检查是否有错误状态码需要覆盖r-err_status是请求结构体中的一个整数字段。Nginx 在处理请求的任何阶段如果遇到错误可以设置这个字段例如 403、500 等 HTTP 状态码。如果请求正常完成该字段为 0。作用判断在最终发送前是否需要用错误状态码替换当前响应头中的状态码。保证错误的优先级最高无论之前流程如何设置最终都以错误状态码为准清空自定义状态行当错误状态码覆盖后自定义的状态行可能不再匹配例如原本为 200 OK 设置的文本对于 500 是无意义的清空它让 Nginx 为错误状态码生成正确的标准文本。4. 启动过滤器链returnngx_http_top_header_filter(r);}启动头部过滤器链并返回结果ngx_http_top_header_filter是一个函数指针指向 Nginx 头部过滤器链的第一个过滤器函数。Nginx 的过滤器链机制允许各个模块如 gzip、charset、not_modified 等注册自己的头部处理函数这些函数首尾相连形成一条链。调用ngx_http_top_header_filter(r)会依次执行链中的所有头部过滤函数完成对响应头的最后修改、序列化并最终通过操作系统调用如 write发送到网络。作用真正执行“发送响应头”动作的是这条过滤器链这个调用将请求对象传入链中让整个链条运转起来。return将过滤链的返回值直接作为本函数的返回值。如果过滤链执行成功最终会返回NGX_OK如果发送过程中出现错误则返回NGX_ERROR
ngx_http_send_header
发布时间：2026/7/7 3:45:57
1 定义ngx_http_send_header 函数 定义在 ./nginx-1.24.0/src/http/ngx_http_core_module.cngx_int_tngx_http_send_header(ngx_http_request_t*r){if(r-post_action){returnNGX_OK;}if(r-header_sent){ngx_log_error(NGX_LOG_ALERT,r-connection-log,0,header already sent);returnNGX_ERROR;}if(r-err_status){r-headers_out.statusr-err_status;r-headers_out.status_line.len0;}returnngx_http_top_header_filter(r);}2 目的1. 核心设计目的 ngx_http_send_header 是 Nginx HTTP 框架中 发送响应头的统一入口。 它的设计目的可以归纳为三点 1. 提供一个唯一且安全的发送起点 确保在整个 Nginx 系统中响应头的实际发送动作只从这一个地方开始 防止各个模块擅自发送头部而导致混乱。 2. 执行发送前的必要检查与修正 在数据流出前统一处理几项全局性的前置条件 如“是否还需要发送”、“状态码是否需要覆盖”等。 3. 将响应头推入过滤器链 调用 ngx_http_top_header_filter 启动由各个模块串起来的“头部过滤链”。 这条链可以对即将发送的头部做最后的修改、压缩或序列化 然后通过操作系统网络接口发送出去。2. 它在整体流程中的角色 ngx_http_send_header 的设计意图可以概括为 在请求处理的“内容生成阶段”结束后作为从“准备响应头”过渡到“网络发送”的闸门。 它依次完成了 - 检查是否应该跳过post_action - 检查是否已经发送过防止重复 - 最终确定 HTTP 状态码err_status 覆盖 - 启动过滤器链让所有模块完成最后的处理并发送 因此它是 Nginx 保证响应头正确、安全、且只发送一次的关键机制 也是模块化处理 HTTP 头部的基础。3 详解1 函数签名ngx_int_tngx_http_send_header(ngx_http_request_t*r)1. 返回值类型ngx_int_t 用于表示函数的执行状态。 这个函数返回一个整数值用来告诉调用者操作的结果。可能的返回值包括 NGX_OK成功。 可能是头部已经发送成功也可能因为特殊情况如 post_action 请求而无需发送。 NGX_ERROR 错误。例如检测到头部已经被重复发送或者底层发送操作失败。 调用者通过检查返回值是否为 NGX_OK 来判断函数是否正常完成。2. 函数名ngx_http_send_header 函数名由下划线分隔的多个部分组成遵循 Nginx 的命名惯例 ngx全局前缀表明这是 Nginx 源码的一部分用于避免命名冲突。 http表明该函数属于 HTTP 模块子系统处理 HTTP 协议相关的逻辑。 send动词意为“发送”。这里指将数据通过网络连接传输给客户端。 header名词指 HTTP 响应中的头部部分响应行和各个头部字段。 因此ngx_http_send_header 的完整含义是 在 HTTP 模块中将准备好的响应头发送给客户端的函数。3. 参数列表(ngx_http_request_t *r) 参数类型 ngx_http_request_t * ngx_http_request_t 是一个结构体类型包含了处理一个 HTTP 请求所需的所有信息 请求行、请求头部、将要发送的响应头部r-headers_out、客户端连接、 各种状态标志如 header_sent、err_status等。4. 签名整体反映出的设计信息 功能直接函数名明确指出了“发送头部”这个动作没有歧义。 依赖请求上下文 函数所需的一切都来自 r 参数状态标志、响应头内容、底层连接 不依赖外部全局变量。这使得函数的行为完全由请求状态决定安全且可预测。 返回状态 通过返回 NGX_OK 或 NGX_ERROR 来报告操作结果 与 Nginx 整体的错误处理风格一致。2 逻辑流程1. 特殊请求跳过 如果是 post_action 子请求不需要发送任何头部直接返回成功。 2. 重复发送防护 如果头部已经被发送过记录告警日志并返回错误避免协议违规。 3. 错误状态码覆盖 如果在处理过程中产生了错误状态码err_status则覆盖原有的响应状态码 并清空自定义状态行保证错误响应的一致性和正确性。 4. 启动过滤器链 调用 ngx_http_top_header_filter(r)将控制权交给过滤器链 由各个模块完成最终的头部处理、序列化和网络发送。1. 特殊请求跳过{if(r-post_action){returnNGX_OK;}检查是否为post_action请求r-post_action是请求结构体中的一个标志字段。当 Nginx 配置了post_action指令时主请求完成后会触发一个内部子请求这个子请求的post_action字段为非零值。作用判断当前请求是否是一个“后置动作”子请求。对于post_action子请求它的目的仅仅是在后台执行某个操作比如记录日志不需要向客户端返回任何数据包括响应头。因此函数直接返回NGX_OK表示“成功无事发生”。意义避免向客户端错误地发送多余的响应头确保post_action请求完全静默。2. 重复发送防护if(r-header_sent){ngx_log_error(NGX_LOG_ALERT,r-connection-log,0,header already sent);returnNGX_ERROR;}检查是否已经发送过响应头r-header_sent是请求结构体中的一个整数标志。当响应头已经被发送过一次后这个标志会被设置为 1。作用检测是否有重复发送头部的尝试。记录错误日志返回错误状态3. 错误状态码覆盖if(r-err_status){r-headers_out.statusr-err_status;r-headers_out.status_line.len0;}检查是否有错误状态码需要覆盖r-err_status是请求结构体中的一个整数字段。Nginx 在处理请求的任何阶段如果遇到错误可以设置这个字段例如 403、500 等 HTTP 状态码。如果请求正常完成该字段为 0。作用判断在最终发送前是否需要用错误状态码替换当前响应头中的状态码。保证错误的优先级最高无论之前流程如何设置最终都以错误状态码为准清空自定义状态行当错误状态码覆盖后自定义的状态行可能不再匹配例如原本为 200 OK 设置的文本对于 500 是无意义的清空它让 Nginx 为错误状态码生成正确的标准文本。4. 启动过滤器链returnngx_http_top_header_filter(r);}启动头部过滤器链并返回结果ngx_http_top_header_filter是一个函数指针指向 Nginx 头部过滤器链的第一个过滤器函数。Nginx 的过滤器链机制允许各个模块如 gzip、charset、not_modified 等注册自己的头部处理函数这些函数首尾相连形成一条链。调用ngx_http_top_header_filter(r)会依次执行链中的所有头部过滤函数完成对响应头的最后修改、序列化并最终通过操作系统调用如 write发送到网络。作用真正执行“发送响应头”动作的是这条过滤器链这个调用将请求对象传入链中让整个链条运转起来。return将过滤链的返回值直接作为本函数的返回值。如果过滤链执行成功最终会返回NGX_OK如果发送过程中出现错误则返回NGX_ERROR
)
 获取与实战)
