HTTP 处理程序

目的与范围

HTTP 处理程序是 Caddy 请求处理管道中处理 HTTP 请求的核心组件。本文档涵盖了处理程序和中间件的系统架构、请求处理流程以及处理程序在路由中的组织方式。

有关特定处理程序实现的更多信息，请参阅反向代理、静态文件服务器、FastCGI、重写、模板、内容编码和头信息和静态响应。有关请求如何与处理程序匹配的详细信息，请参阅请求路由。

处理程序链架构

Caddy 通过编译后的处理程序链处理 HTTP 请求，其中每个处理程序都可以修改请求、生成响应或将控制权传递给链中的下一个处理程序。这遵循了 Web 服务器中常用的中间件模式。

请求处理管道

带有代码实体的请求处理流程

来源：modules/caddyhttp/server.go266-451 modules/caddyhttp/app.go364-382

处理程序链编译

路由在配置阶段被编译成可执行的处理程序链。每个路由都包含匹配器和处理程序，它们被组合成一个顺序处理管道。

路由编译到处理程序链

来源：modules/caddyhttp/app.go364-382 modules/caddyhttp/server.go116-134

处理程序类型和接口

处理程序接口

所有 HTTP 处理程序都实现了核心的 Handler 接口，该接口处理请求并可能返回错误。处理程序主要分为两类

处理程序类型	描述	行为
中间件处理程序	处理请求并委托给下一个处理程序	修改请求/响应，然后调用 `next.ServeHTTP()`
终端处理程序	生成最终响应	返回响应而不调用下一个处理程序

内置处理程序类别

类别	目的	示例
内容服务	提供静态或动态内容	文件服务器、模板、静态响应
请求修改	修改传入请求	重写、头信息
代理	将请求转发到后端	反向代理、FastCGI
响应处理	修改传出响应	内容编码、头信息

来源：modules/caddyhttp/server.go235-237 modules/caddyhttp/app.go364-372

请求处理实现

服务器入口点

Server.ServeHTTP() 方法是所有 HTTP 请求的入口点。它执行必要的设置并将请求委托给处理程序链

TLS 连接状态设置 - 确保 TLS 信息可用
服务器头信息添加 - 设置 "Caddy" 服务器头信息
HTTP/3 广告 - 在适当时候添加 Alt-Svc 头信息
请求准备 - 初始化上下文和替换器
处理程序链执行 - 通过主要处理程序进行处理
错误处理 - 通过错误处理程序链路由错误

来源：modules/caddyhttp/server.go266-451

请求上下文和变量

请求处理利用 Go 的 context.Context 在处理程序之间传递信息

上下文键	目的	类型
`ServerCtxKey`	服务器实例引用	`*Server`
`VarsCtxKey`	处理程序变量表	`map[string]any`
`OriginalRequestCtxKey`	未修改的请求副本	`http.Request`
`ConnCtxKey`	底层网络连接	`net.Conn`

来源：modules/caddyhttp/server.go1071-1090 modules/caddyhttp/server.go873-897

错误处理流程

当处理程序返回错误时，服务器会切换到错误处理模式

错误处理管道

来源：modules/caddyhttp/server.go394-451 modules/caddyhttp/server.go687-731

路由和处理程序关系

路由结构

路由定义了请求何时以及如何通过处理程序系统进行处理

路由到处理程序映射结构

来源：modules/caddyhttp/server.go106-134

处理程序执行顺序

处理程序按照它们在路由配置中出现的顺序执行。中间件处理程序通常

预处理请求（认证、日志记录、修改）
通过 next.ServeHTTP(w, r) 委托给下一个处理程序
后处理响应（压缩、头信息、日志记录）

终端处理程序生成最终响应，并且不调用下一个处理程序。

来源：modules/caddyhttp/server.go453-482