请求路由

相关源文件

• listeners.go
• listeners_test.go
• modules/caddyhttp/app.go
• modules/caddyhttp/caddyhttp.go
• modules/caddyhttp/matchers.go
• modules/caddyhttp/matchers_test.go
• modules/caddyhttp/routes.go
• modules/caddyhttp/server.go

请求路由是 Caddy HTTP 服务器的核心，它决定了如何将传入的请求与处理程序匹配。本文档解释了 Caddy 中的 HTTP 请求路由系统如何工作，从请求进入服务器的那一刻起，到它被适当的处理程序处理为止。

有关路由后处理请求的特定 HTTP 处理程序的更多信息，请参阅HTTP 处理程序。

请求路由概述

Caddy 的路由系统是一个强大的基于规则的机制，用于确定哪些处理程序应处理每个传入的 HTTP 请求。路由按顺序进行评估，每个路由包含

1. 匹配器：确定路由是否适用于请求
2. 处理程序：如果路由匹配，则处理请求
3. 附加控件：终止标志、分组等

来源：modules/caddyhttp/server.go264-451 modules/caddyhttp/routes.go242-301

路由结构

Caddy 中的路由由 caddyhttp 包中的 Route 结构体定义。每个路由包含以下关键组件：

来源：modules/caddyhttp/routes.go29-100 modules/caddyhttp/routes.go335-451

路由配置

路由被配置为一个列表，每个路由包含

1. 分组（可选）：用于对互斥路由进行分组的名称
2. 匹配器：用于确定路由是否适用于请求的规则
3. 处理程序：路由匹配时要采取的操作
4. 终止：指示路由在此路由后是否应停止的标志

JSON 中的示例路由结构

来源：modules/caddyhttp/server.go106-116 modules/caddyhttp/routes.go29-100

请求流程

当 HTTP 请求进入 Caddy 时，它会经历以下流程：

来源：modules/caddyhttp/server.go264-451 modules/caddyhttp/routes.go224-301

请求处理的主要组件

1. Server.ServeHTTP：HTTP 请求的入口点
2. PrepareRequest：设置请求上下文、变量、替换器
3. primaryHandlerChain：主路由处理链
4. 路由匹配：将请求与路由匹配器进行测试
5. 路由分组：确保组中只有一个匹配的路由被执行
6. 处理程序执行：通过中间件链处理请求
7. 错误处理：失败时路由到错误处理程序

来源：modules/caddyhttp/server.go264-451 modules/caddyhttp/caddyhttp.go59-99

匹配器系统

匹配器决定路由是否应处理请求。Caddy 提供几种内置的匹配器类型：

匹配器	描述	示例
主机	按主机名匹配	example.com、*.example.com
path	按请求路径匹配	/api/*、/images/*.jpg
path_regexp	按正则表达式匹配路径	^/user/\d+$
method	按 HTTP 方法匹配	GET、POST
query	按查询参数匹配	?key=value
header	按 HTTP 标头匹配	User-Agent: *Chrome*
protocol	按协议匹配	http、https、h2
not	反转其他匹配器

来源：modules/caddyhttp/matchers.go43-221

匹配器逻辑

匹配器逻辑遵循以下规则：

1. 多个匹配器集：通过 OR 逻辑连接——如果任何一个集合匹配，则路由匹配
2. 集合内的匹配器：通过 AND 逻辑连接——集合中的所有匹配器都必须匹配
3. 空的匹配器集：匹配所有请求
4. 匹配器评估顺序：匹配器按照配置中定义的顺序进行评估

来源：modules/caddyhttp/routes.go335-451

常见匹配器类型详解

Host 匹配器

按 Host 标头值（不区分大小写）匹配请求。

来源：modules/caddyhttp/matchers.go44-66 modules/caddyhttp/matchers.go297-362

Path 匹配器

按 URI 路径（不区分大小写）匹配请求。

来源：modules/caddyhttp/matchers.go68-109 modules/caddyhttp/matchers.go398-534

Method 匹配器

按 HTTP 方法匹配请求。

来源：modules/caddyhttp/matchers.go121-123 modules/caddyhttp/matchers.go783-792

处理程序链

处理程序在路由匹配后处理请求。它们以类似中间件的方式串联在一起。

处理程序流向

1. 请求阶段：请求从处理程序 1 → 处理程序 2 → 处理程序 3 流动
2. 响应阶段：响应从处理程序 3 → 处理程序 2 → 处理程序 1 流回

这种双向流动很重要：处理程序可以转换请求（进入时）和响应（出来时）。

来源：modules/caddyhttp/routes.go47-87 modules/caddyhttp/caddyhttp.go59-75

路由编译

路由在配置和请求处理期间被编译成中间件链。

编译过程

1. 以空处理程序为基础
2. 按 **反向顺序**（从上到下）处理路由
3. 将每个路由的处理程序链包装到当前堆栈周围
4. 结果是单一的统一中间件链

来源： modules/caddyhttp/routes.go219-234 modules/caddyhttp/routes.go241-301

路由分组

路由分组允许您定义互斥的路由。当同一组中的多个路由匹配请求时，仅执行第一个。

路由分组通过请求上下文中的一个映射进行跟踪，该映射位于 routeGroupCtxKey 键下，其中包含已满足的分组。

来源： modules/caddyhttp/routes.go29-35 modules/caddyhttp/routes.go269-282

错误处理

当处理程序返回错误时，Caddy 的错误处理系统将被激活。

错误处理系统

1. 捕获错误和 HTTP 状态码
2. 将错误添加到请求上下文
3. 通过占位符使错误信息可用
4. 处理配置的错误处理路由
5. 如果没有路由匹配，则回退到默认错误响应

来源： modules/caddyhttp/server.go386-450 modules/caddyhttp/server.go689-731

性能考量

Caddy 的请求路由系统效率很高。

1. 匹配器优化:

   • Host 匹配器对大型列表使用二分查找。
   • Path 匹配器对常见模式具有快速路径。

2. 编译策略:

   • 路由在供应期间被预编译。
   • 中间件链被构建一次并重复使用。

3. 延迟评估:

   • 匹配器仅在必要时进行评估。
   • 路由处理程序仅在路由匹配时才编译。

来源： modules/caddyhttp/matchers.go256-395 modules/caddyhttp/routes.go219-234

与其他系统集成

路由系统与其他 Caddy 部分集成。

1. Replacer：匹配器和处理程序中可用的变量和占位符。
2. TLS：基于主机匹配器的自动 HTTPS。
3. Metrics：可选的处理程序仪表化。
4. Logs：请求日志记录和跟踪。

这些集成使路由系统具有可扩展性和强大功能，能够实现复杂的路由规则和 HTTP 处理。

来源： modules/caddyhttp/server.go307-359 modules/caddyhttp/replacer.go58-386