12、Nginx:HTTP handler 的签名与返回值

修正 C 语言标记和 NGX_DECLINED 拼写,区分 handler 返回值与响应已完成。

简明结论

不能脱离调用点这样判断。handler 的返回值由所在阶段或上层处理逻辑解释;输出响应头和 body 还需要相应 API,异步处理也有不同结束方式。

返回 NGX_OK 就表示响应已经发送了吗?

不能脱离调用点这样判断。handler 的返回值由所在阶段或上层处理逻辑解释;输出响应头和 body 还需要相应 API,异步处理也有不同结束方式。

历史文本写作 NGX_DECLINE,正确宏名是 NGX_DECLINED。类型签名是 C,不是 Java:

typedef ngx_int_t (*ngx_http_handler_pt)(ngx_http_request_t *r);

应如何阅读一个 handler

先定位模块把函数放进哪个 HTTP 阶段或 location content handler,再看是否生成响应、返回 HTTP 状态或让后续处理器继续。常见的 NGX_OK、NGX_ERROR、NGX_DECLINED 与 HTTP 状态码不处于同一层含义,不能画成一张“成功即已发送”的对照表。

只表示签名与继续处理意图的片段如下,不是完整可编译模块:

static ngx_int_t
example_handler(ngx_http_request_t *r)
{
    /* 在允许继续处理的阶段使用;此处没有生成任何响应体。 */
    return NGX_DECLINED;
}

下一步验证方案

固定目标 Nginx 源码版本,补齐模块上下文、指令定义及注册位置,编译后分别请求命中和未命中的 location,检查 HTTP 状态和日志。本页没有完成模块编译或 HTTP 运行验证,因此仅作为 API 阅读入口,不保证此片段放到任何阶段都具有同样行为。

开发者应对照目标源码而非未标版本的旧教程;官方 development guide 是滚动资料。

整理范围与出处

本次依据下方版本资料整理说明与示例;历史导入资料的来源状态单独列示,不将技术参考认作原作者信息。原始发布日期与地址保留。