ngx_http_core_generic_phase

1 定义

ngx_http_core_generic_phase 函数 定义在 ./nginx-1.24.0/src/http/ngx_http_core_module.c

ngx_int_tngx_http_core_generic_phase(ngx_http_request_t*r,ngx_http_phase_handler_t*ph){ngx_int_trc;/* * generic phase checker, * used by the post read and pre-access phases */ngx_log_debug1(NGX_LOG_DEBUG_HTTP,r->connection->log,0,"generic phase: %ui",r->phase_handler);rc=ph->handler(r);if(rc==NGX_OK){r->phase_handler=ph->next;returnNGX_AGAIN;}if(rc==NGX_DECLINED){r->phase_handler++;returnNGX_AGAIN;}if(rc==NGX_AGAIN||rc==NGX_DONE){returnNGX_OK;}/* rc == NGX_ERROR || rc == NGX_HTTP_... */ngx_http_finalize_request(r,rc);returnNGX_OK;}

ngx_http_core_generic_phase 函数是一个通用的阶段检查器， 它调用模块处理函数，并根据返回值进行调度

2 详解

1 函数签名

ngx_int_tngx_http_core_generic_phase(ngx_http_request_t*r,ngx_http_phase_handler_t*ph)

返回值 用于返回函数执行结果的状态码

参数1 ngx_http_request_t *r 指向当前 HTTP 请求上下文结构体

参数2 ngx_http_phase_handler_t *ph 指向 ngx_http_phase_handler_t 结构体的指针， 代表当前在 阶段处理引擎 数组 中的处理器项

2 逻辑流程

1 调用 handler 2 handler 返回结果处理 2-1 NGX_OK 2-2 NGX_DECLINED 2-3 NGX_AGAIN || rc == NGX_DONE 2-4 错误

1 调用 handler

{ngx_int_trc;/* * generic phase checker, * used by the post read and pre-access phases */ngx_log_debug1(NGX_LOG_DEBUG_HTTP,r->connection->log,0,"generic phase: %ui",r->phase_handler);rc=ph->handler(r);

执行当前阶段注册的模块处理函数， 并将请求对象 r 传入 ph->handler 是某个模块在配置加载阶段设置的函数指针。 该函数执行实际业务逻辑，并返回一个标准的状态码 返回值被存入 rc

2 handler 返回结果处理

2-1 NGX_OK

if(rc==NGX_OK){r->phase_handler=ph->next;returnNGX_AGAIN;}

条件 rc == NGX_OK： 模块 handler 返回 NGX_OK， 表示当前处理器已经成功处理了该请求， 并且不期望同阶段的其他 handler 再处理， 请求应该直接进入下一个阶段。 动作： r->phase_handler = ph->next;： 将阶段处理器索引设置为当前处理器项中预存的 next 值 return NGX_AGAIN;： 向阶段引擎返回 NGX_AGAIN， 告诉引擎继续循环，并使用新的索引执行后续处理器。

2-2 NGX_DECLINED

if(rc==NGX_DECLINED){r->phase_handler++;returnNGX_AGAIN;}

条件 rc == NGX_DECLINED： 模块 handler 返回 NGX_DECLINED， 表示“我不处理这个请求”， 请求应当由同阶段的下一个 handler 继续尝试。 动作： r->phase_handler++;： 将索引简单加 1， 指向引擎数组中紧挨着的下一个处理器项 （可能是另一个模块的 handler）。 return NGX_AGAIN;： 同样通知引擎继续循环。

2-3 NGX_AGAIN || rc == NGX_DONE

if(rc==NGX_AGAIN||rc==NGX_DONE){returnNGX_OK;}

条件： rc == NGX_AGAIN： handler 需要异步等待（例如等待子请求完成或非阻塞 I/O 就绪）。 此时 handler 内部已经设置了 r->write_event_handler，以便将来事件触发时能恢复执行。 请求处理必须暂停。 rc == NGX_DONE： handler 已经完成了请求的最终化（调用了 ngx_http_finalize_request 等）， 请求对象不应再被访问。任何后续处理都是错误且危险的。 动作： 直接返回 NGX_OK 给阶段引擎。 引擎的响应： 会捕获该值并退出循环，停止当前处理流程。 请求或挂起在事件循环中，或已完全结束。 意义： 这两个返回值都表示当前请求不能或不应继续沿阶段链向前推进。 checker 用统一的 NGX_OK 通知引擎退出， 保护了请求的安全性，同时与异步挂起机制完美配合。

2-4 错误

/* rc == NGX_ERROR || rc == NGX_HTTP_... */ngx_http_finalize_request(r,rc);returnNGX_OK;}

注释：剩余情况 /* rc == NGX_ERROR || rc == NGX_HTTP_... */ 作用： 提示以下代码处理 handler 返回 NGX_ERROR 或任何 HTTP 状态码的情况。 逻辑： 这些返回值都表示请求遇到了错误 或需要立即生成一个 HTTP 错误响应， 并且不能继续后续阶段。 意义：注释增强了代码可读性，明确告诉维护者这里的逻辑覆盖了哪些情况。

调用 Nginx 的请求最终化函数， 以 rc 作为终止状态码结束当前请求。 意义： 集中处理请求的结束， 返回 NGX_OK 退出引擎 意义： 确保在请求终结后引擎立即停止， 不会错误地进入后续阶段，保证了处理的干净和安全。