ngx_http_request_t 是 Nginx 中动态生命周期的 HTTP 请求核心结构体，创建于 ngx_http_create_request()，经初始化、处理、子请求复用后于 ngx_http_free_request() 销毁，字段按阶段有效。

ngx_http_request_t 是 Nginx HTTP 模块最核心的数据结构，代表一次完整的 HTTP 请求上下文。它不是静态定义后就一成不变的，而是在请求生命周期中动态创建、逐步填充、多阶段复用、最终销毁的“活”结构体。理解它的字段含义和何时被赋值、何时被释放，是读懂 Nginx 源码、编写高效模块、排查内存/逻辑问题的关键。

关键字段及其初始化时机

该结构体定义在 src/http/ngx_http_request.h，大小超过 2KB（含大量指针与缓存字段），但并非所有字段都在请求开始时就有效：

• connection：指向所属 ngx_connection_t，在 ngx_http_init_request() 中由事件回调传入并绑定，是请求与 TCP 连接的唯一纽带；
• ctx 和 main_conf / srv_conf / loc_conf：分别存储各模块的请求级上下文和配置指针，在 ngx_http_init_request() 后期通过 ngx_http_create_req_ctx() 和配置查找完成初始化；
• headers_in 和 headers_out：分别保存解析后的请求头与待发送响应头；headers_in 在读取并解析完首行+头部后（ngx_http_process_request_headers()）才完整可用；headers_out 则常在 content handler 或 filter 阶段逐步设置；
• request_line、uri、args 等字符串字段：均为 ngx_str_t 类型，其 data 指向 request buffer 中已解析出的原始内存（如 request_start ~ header_end 区域），不额外分配；它们在 ngx_http_parse_request_line() 和 ngx_http_parse_header_line() 过程中被赋值；
• pool：请求专属内存池，在 ngx_http_create_request() 中创建，贯穿整个请求生命周期，所有 request 级临时分配（如变量值、重写缓冲区、子请求结构）都从此池分配；

生命周期四阶段：创建 → 处理 → 子请求/重定向 → 销毁

ngx_http_request_t 的生命周期严格对应 HTTP 请求处理流程，且支持嵌套与复用：

• 创建：由 ngx_http_create_request() 分配内存 + 初始化基础字段（pool、connection、ctx 置 NULL），此时仅具备骨架；
• 初始化与解析：进入 ngx_http_init_request()，读取并解析请求行、头部，填充 headers_in、uri、args 等，建立模块上下文（ctx）、合并配置；
• 处理与转发：执行 location 匹配、access/content/handler、output filter 链；若触发内部重定向（ngx_http_internal_redirect()）或子请求（ngx_http_subrequest()），会复用当前 request 结构体的部分字段（如 pool、connection），但重置 uri、args、headers_out 等，并新建子 request 结构体挂到 parent->postponed 链上；
• 销毁：在 ngx_http_finalize_request() 调用末尾，执行 ngx_http_free_request()，先调用各模块的 cleanup 回调，再销毁 pool（自动释放所有 pool 分配内存），最后释放 request 结构体本身内存；注意：若连接保持长连接，request 销毁但 connection 仍存活，可能用于下一次请求。

易踩坑点：字段有效性 ≠ 生命周期全程有效

很多字段只在特定阶段合法，误用会导致段错误或逻辑错乱：

• request->upstream 仅在启用 upstream 模块（如 proxy_pass）后才非 NULL，且在 ngx_http_upstream_init_request() 中才完成初始化；在 access 阶段直接访问可能为空；
• request->variables 数组由变量系统懒加载，首次调用 ngx_http_get_variable() 时才分配并初始化，不能假设其初始就可读写；
• request->request_body 默认为 NULL，仅当显式调用 ngx_http_read_client_request_body()（如需读取 POST body）后才被分配并填充，且该函数异步执行，回调中才能安全使用；
• 子请求（subrequest）的 parent 字段指向父请求，但父请求可能早已进入 finalization 阶段，此时访问 parent->headers_out 等字段需加锁或判断状态，否则引发 use-after-free。

调试建议：结合日志与内存断点定位字段状态

源码级调试时，不要只看结构体定义，要跟踪字段实际赋值位置：

• 在 ngx_http_create_request() 下断点，观察初始字段值（多数为 0 或 NULL）；
• 在 ngx_http_process_request_headers() 返回前检查 headers_in 是否已解析完成；
• 对关键字段（如 upstream, request_body）在赋值处（如 ngx_http_upstream_init_request, ngx_http_read_client_request_body）加日志或断点，确认是否如期初始化；
• 使用 AddressSanitizer 编译 Nginx，可捕获对已销毁 request 字段的非法访问；
• 查看 ngx_http_finalize_request 中的 cleanup 链表调用顺序，确保自定义 cleanup 回调在依赖资源释放前执行。