使用 CEL 进行表达式匹配

相关源文件

• internal/filesystems/map.go
• modules/caddyevents/app.go
• modules/caddyfs/filesystem.go
• modules/caddyhttp/celmatcher.go
• modules/caddyhttp/celmatcher_test.go
• modules/caddyhttp/fileserver/matcher.go
• modules/caddyhttp/fileserver/matcher_test.go
• modules/caddyhttp/ip_matchers.go
• modules/caddyhttp/vars.go

本文档涵盖了 Caddy 用于高级 HTTP 请求匹配的通用表达式语言 (CEL) 的实现。CEL 表达式提供了一种强大的方式来创建复杂的匹配逻辑，超越了简单的字符串或模式匹配。有关使用内置匹配器的基本请求匹配，请参阅 匹配器和路由。

目的与范围

Caddy 中的 CEL (通用表达式语言) 集成允许用户使用熟悉的、类似 JavaScript 的语法编写复杂的布尔表达式来进行请求匹配。该系统支持复杂的匹配逻辑，可以组合多个请求属性、执行文件系统操作以及在请求时评估动态条件。

CEL 表达式处理架构

CEL 表达式系统通过一个多阶段管道处理用户定义的表达式，该管道对传入的 HTTP 请求进行编译、优化和评估。

来源： modules/caddyhttp/celmatcher.go122-201 modules/caddyhttp/celmatcher.go203-224

MatchExpression 实现

MatchExpression 结构是基于 CEL 的请求匹配的主要接口，负责表达式的编译和评估。

来源： modules/caddyhttp/celmatcher.go49-77 modules/caddyhttp/celmatcher.go122-201

MatchExpression 支持字符串格式和结构化 JSON 格式的配置

字段	类型	目的
Expr	字符串	要评估的 CEL 表达式
姓名	字符串	可选的正则表达式匹配器名称
expandedExpr	字符串	展开占位符后的表达式
prg	cel.Program	已编译的 CEL 程序

CEL 库生产者系统

Caddy 匹配器可以通过实现 CELLibraryProducer 接口向 CEL 表达式公开自己，这允许它们注册自定义函数和宏。

来源： modules/caddyhttp/celmatcher.go363-370 modules/caddyhttp/celmatcher.go391-432

匹配器集成流程

1. 库注册：匹配器实现 CELLibrary() 方法
2. 宏创建：CELMatcherImpl() 为匹配器函数创建宏
3. 函数绑定：函数绑定并进行类型验证
4. 运行时优化：静态表达式预编译以提高性能

占位符集成系统

Caddy 的占位符系统通过自动扩展和函数注册与 CEL 表达式无缝集成。

来源： modules/caddyhttp/celmatcher.go125-131 modules/caddyhttp/celmatcher.go257-281 modules/caddyhttp/celmatcher.go779-791

占位符处理规则

模式	转换	示例
{http.request.uri.path}	ph(req, "http.request.uri.path")	路径访问
\{literal}	{literal}	转义的字面量
{var} + "suffix"	ph(req, "var") + "suffix"	连接

使用 CEL 进行文件系统操作

MatchFile 匹配器通过 CEL 表达式提供复杂的文件系统操作，支持文件存在性检查、目录匹配和高级文件选择策略。

来源： modules/caddyhttp/fileserver/matcher.go166-223 modules/caddyhttp/fileserver/matcher.go225-271

文件匹配器 CEL 示例

表达式	目的
file()	检查请求路径是否存在
file("index.php")	检查特定文件
file({http.request.uri.path}, "/index.php")	尝试多个文件
file({"root": "./www", "try_files": ["index.html"]})	高级配置

类型系统和适配器

Caddy 中的 CEL 表达式使用自定义类型适配器系统来处理 Go 类型并提供与 HTTP 请求的无缝集成。

来源： modules/caddyhttp/celmatcher.go346-361 modules/caddyhttp/celmatcher.go286-318

表达式编译和优化

CEL 系统在编译时和运行时都提供优化，以实现高效的请求处理。

来源： modules/caddyhttp/celmatcher.go164-178 modules/caddyhttp/celmatcher.go467-548

性能优化

1. 静态分析：常量表达式在编译时进行评估
2. 匹配器预编译：静态匹配器参数被预先提供
3. 类型优化：自定义类型适配器可减少转换开销
4. 内存效率：interpreter.Activation 接口可减少分配

错误处理与验证

CEL 表达式在配置期间经过全面验证，并在评估期间提供详细的错误报告。

来源： modules/caddyhttp/celmatcher.go184-200 modules/caddyhttp/celmatcher.go206-209

此 CEL 集成通过强大的、灵活的表达式语言为 Caddy 提供了处理复杂请求匹配场景的能力，同时保持了类型安全和性能优化。