Envoy URI 模板路径重写Path Template Rewrite完全指南模式语法、配置字段与实现原理【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读本文围绕 Envoy 的URI 模板路径重写扩展envoy.path.rewrite.uri_template.uri_template_rewriter展开讲解如何在路由转发阶段基于带命名变量的路径模板对请求路径进行匹配与重写实现诸如路径段重排、按语言/格式重组资源路径等能力。读完本文你将掌握path_template_rewrite的完整模板语法*、**、{name}、{namepattern}、它与prefix_rewrite、regex_rewrite的互斥关系、配置字段的校验规则以及重写引擎在源码层面的执行流程。一、URI 模板路径重写是什么URI 模板路径重写Path Template Rewrite是 Envoy 路由动作RouteAction中可选的路径重写机制之一由扩展 api/envoy/extensions/path/rewrite/uri_template/v3/uri_template_rewrite.proto 定义。它允许在转发请求时将路径中与匹配模式pattern对应的部分按重写模板rewrite template重新组合并支持把匹配模式中捕获的命名变量代入新路径。它的典型价值在于传统前缀重写只能做固定字符串替换无法感知动态内容的路径段而 URI 模板重写可以识别诸如标识符identifier、语言代码、媒体格式等可变内容路径段并把它们搬运、重组到新路径中例如把/videos/lang/en/video.m4s这类深层路径收拢为lang/en。从文档定义看该扩展的职责描述如下Indicates that during forwarding, portions of the path that match the pattern should be rewritten, even allowing the substitution of variables from the match pattern into the new path as specified by the rewrite template.同时路由过滤器Router Filter会把重写前的原始路径放入x-envoy-original-path请求头便于下游服务或访问日志感知原始请求对应config_http_filters_router_x-envoy-original-path文档。1.1 三种路径重写方式的互斥在 api/envoy/config/route/v3/route_components.proto 的RouteAction中以下三种重写方式同一时刻只能指定一种prefix_rewrite基于前缀的字符串重写regex_rewrite基于正则表达式的重写path_template_rewrite基于 URI 模板的本扩展重写。proto 注释明确强调了这个约束Only one of prefix_rewrite, regex_rewrite, or path_template_rewrite may be specified如果配置中同时出现多个配置校验会失败。二、模板匹配模式语法path_template_rewrite使用的模板模式支持以下四种匹配类型语义清晰且易于组合模式写法匹配语义说明*匹配单个路径段匹配到下一个路径分隔符/为止**匹配零个或多个路径段若出现必须是模式中的最后一个操作符{name}或{name*}命名变量匹配单个路径段匹配到下一个/为止捕获值绑定到name{namevideos/*}命名变量匹配多个路径段例如videos/*匹配到的路径内容整体捕获为name{name**}命名变量匹配零个或多个路径段通配能力最强通常放在模式尾部关键约束只有命名变量named matches才能用于重写substitution裸的*、**只能参与匹配无法在重写模板中被引用变量名必须可被重写模板引用因此模板解析器会对变量名合法性做校验见下文源码分析模式必须以/开头且不允许出现连续的//源码层会拒绝这类非法模式。三、核心配置字段path_template_rewrite配置入口是UriTemplateRewriteConfig消息其 proto 定义如下message UriTemplateRewriteConfig { string path_template_rewrite 1 [(validate.rules).string {min_len: 1 max_len: 256}]; }字段说明字段名path_template_rewrite字段号 1作用指定重写模板字符串。它描述的是新路径如何由字面量与捕获变量拼接而成而不是匹配模式本身校验规则字符串长度必须满足1 ≤ len ≤ 256空字符串会被校验器拒绝超长模板同样不合法。在配置层面重写模板与路由的匹配策略PathMatchPolicy配合使用——匹配模式决定什么样的路径被选中并捕获哪些变量重写模板决定如何把这些变量与字面量重新拼装成新路径。四、实战示例模板如何变换路径以下三个示例来自 proto 文档直观展示了模式与重写模板的配合方式。4.1 路径段交换匹配模式/{one}/{two}重写模板/{two}/{one}效果/cat/dog→/dog/cat两个命名变量one、two捕获各自的路径段重写时互换位置。这是理解变量代入的最小示例。4.2 多段变量折叠匹配模式/videos/{languagelang/*}/*重写模板/{language}效果/videos/lang/en/video.m4s→lang/en这里{languagelang/*}捕获了lang/en两个路径段而末尾裸*匹配video.m4s但不参与重写最终新路径只剩lang/en。4.3 资源路径重组媒体场景匹配模式/content/{format}/{lang}/{id}/{file}.vtt重写模板/{lang}/{format}/{file}.vtt效果/content/hls/en-us/12345/en_193913.vtt→/en-us/hls/en_193913.vtt注意示例中的{id}与{file}.vtt{id}捕获12345但在重写模板中未被引用丢弃{file}捕获文件名主体en_193913与字面量.vtt重新拼接。这说明模板可以选择性地保留部分捕获变量未引用的变量会被自然丢弃。五、源码级原理模板如何变成正则并完成重写URI 模板路径重写并非简单字符串拼接其底层实现位于 source/extensions/path/rewrite/uri_template/uri_template_rewrite.cc核心执行流程如下5.1 模式 → 正则convertPathPatternSyntaxToRegex在rewritePath()中首先调用convertPathPatternSyntaxToRegex(matched_path)定义于 source/extensions/path/uri_template_lib/uri_template.cc把人类可读的模板模式转换为等价的正则表达式。该函数由两部分组成Internal::parsePathPatternSyntax(path_pattern)解析模板语法区分字面量段与变量段Internal::toRegexPattern(parsed)把解析结果编译成 RE2 正则含命名捕获组。这意味着模板模式的表达能力最终等价于正则的捕获组能力命名变量被映射为正则中的命名捕获组这正是重写时能够按名取值的基础。5.2 重写模板 → 重写段序列parseRewritePatternparseRewritePattern(rewrite_pattern_, regex_pattern_str)负责把重写模板解析为一段有序的RewriteSegment序列字面量段或捕获索引段其校验逻辑包括模板必须以/开头否则报Invalid rewrite variable placement禁止连续//否则报Invalid rewrite literal每个{...}必须成对闭合变量名必须合法Invalid variable name/Unmatched variable bracket模板中引用的每个变量必须在匹配正则的命名捕获组中存在否则报Nonexisting variable name。5.3 正则匹配 按段拼接rewritePath 主流程rewritePath()的完整流程对应 uri_template_rewrite.cc将匹配路径模式转换为正则解析重写模板得到RewriteSegments用 RE2 对请求原始路径做ANCHOR_BOTH全量匹配得到捕获组数组第 0 组为整体匹配遍历RewriteSegments字面量段直接追加absl::StrAppend(new_path, *literal)变量段按捕获索引取出对应捕获值追加captures[*capture_index]返回拼接出的new_path作为重写后的路径。5.4 与路径匹配扩展的强耦合isCompatiblePathMatcherURI 模板重写要求路由同时配置同名模板匹配扩展envoy.path.match.uri_template.uri_template_matcher。isCompatiblePathMatcher()见 uri_template_rewrite.cc会做两项检查路径匹配器必须存在且其name()必须等于Extensions::UriTemplate::Match::NAME否则报错 unable to use ... extension without ... extension匹配模板与重写模板的变量集合必须一致通过isValidSharedVariableSet校验否则报 mismatch between variables in path_match_policy and path_rewrite_policy。这保证匹配阶段捕获的变量一定能被重写阶段引用两个模板之间不会出现变量漂移。5.5 测试验证仓库中的测试用例覆盖了上述行为可作进一步参考test/extensions/path/rewrite/uri_template/library_test.cc重写库的行为测试示例路径变换的断言test/extensions/path/rewrite/uri_template/config_test.cc配置解析与校验测试test/extensions/path/uri_template_lib/uri_template_test.cc模板语法到正则的转换测试以及 fuzz 测试 uri_template_fuzz_test.cc。六、如何在路由配置中使用URI 模板路径重写是路由层能力典型配置片段示意如下route: match: path: /videos/{languagelang/*}/* path_match_policy: name: envoy.path.match.uri_template.uri_template_matcher typed_config: type: type.googleapis.com/envoy.extensions.path.match.uri_template.v3.UriTemplateMatchConfig path_template: /videos/{languagelang/*}/* route: cluster: media_backend path_rewrite_policy: name: envoy.path.rewrite.uri_template.uri_template_rewriter typed_config: type: type.googleapis.com/envoy.extensions.path.rewrite.uri_template.v3.UriTemplateRewriteConfig path_template_rewrite: /{language}需要说明的几点必须成对使用path_rewrite_policy与path_match_policy应同时配置且变量集合一致见 5.4 的强校验与prefix_rewrite/regex_rewrite互斥同一条路由的RouteAction中不能同时配置多种重写方式校验边界path_template_rewrite长度限制在 1256 字符模板需以/开头且不含连续//原始路径保留重写前的路径会写入x-envoy-original-path请求头可在下游侧继续使用。七、常见注意事项与边界行为结合 proto 注释与源码校验逻辑使用时有几个容易踩坑的点裸通配符不可被重写引用*、**只能匹配重写模板只能引用{name}形式的命名变量否则报Nonexisting variable name**位置约束如果使用**它必须位于匹配模式的最后以保持匹配语义清晰变量丢弃是合法行为模板中未引用的捕获变量会被静默丢弃见示例 4.3 的{id}这是按需重组而非报错变量一致性校验在前若匹配模板与重写模板变量不一致配置阶段构造UriTemplateRewriter时校验就会失败而不是等到请求时才报错正则底层模板最终编译为 RE2 正则因此性能与 RE2 引擎特性一致适用于高并发代理路径得益于 RE2 的线性时间匹配特性从源码使用re2/re2.h可以确认。结语URI 模板路径重写把 Envoy 的路径重写能力从固定字符串替换提升到了感知路径结构、按命名变量重组的层次特别适合 CDN 回源路径整理、多语言/多格式资源路径归一化、网关层 URL 友好化等场景。理解其模板语法*/**/{name}/{namepattern}、配置互斥约束、以及模板 → 正则 → 捕获组 → 按段拼接的源码执行链路将帮助你安全、高效地在生产路由中落地这一能力。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考