grpc-gateway 请求 URL 中编码后的斜杠 %2F 导致路由不到接口时怎么配置 UnescapingMode【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway当你用 gRPC-Gateway 把 gRPC 服务暴露成 HTTP/JSON 接口后路径参数里如果包含/比如资源名是projects/123/instances/abc这类多段值客户端按 HTTP 规范把它编码成%2F发过来请求就会路由失败返回 404。原因是 gRPC-Gateway 默认会在路由前把整个 URL 路径字符串先解码解码后的/被当成了新的路径分隔符参数段数对不上路由自然匹配不到接口。解决办法是在构造runtime.ServeMux时通过runtime.WithUnescapingMode显式配置解码行为。以下内容来自 docs/docs/mapping/customizing_your_gateway.md 的 “Controlling path parameter unescaping” 一节、README.md 以及 runtime/mux.go 中的类型定义和测试用例。先确认你遇到的是不是这个问题两种典型触发场景都能在文档中找到依据路径参数本身含/默认行为下gRPC-Gateway 在尝试路由前会 unescape 整个 URL 路径字符串当路径参数含有/这类在路径中不合法的字符时就会产生路由错误。重复路径映射导致参数改名当 HTTP 映射中出现了仅靠路径参数约束区分的重复映射例如/v1/{nameprojects/*}和/v1/{nameorganizations/*}两者都变成/v1/{name}插件会给第二个参数加_1后缀改名变成/v1/{name_1organizations/*}。这会促使 OpenAPI 生成的客户端把参数里的/URL 编码成%2F这是 OpenAPI 规范的做法而 gateway 要能接受这个编码后的斜杠并正常路由就必须配置对应的 UnescapingMode。README 中明确给出的可用值是UnescapingModeAllCharacters或UnescapingModeLegacy并提示 Legacy 目前虽是默认值但未来版本可能会变。另外 docs/docs/faq.md 也提到与 grpc-httpjson-transcoding 相比gRPC-Gateway 默认对路径参数的解码方式不同这正是可配置项存在的背景。四种 UnescapingMode 取值定义见 runtime/mux.go语义与源码注释一致取值含义UnescapingModeLegacy当前的 V2 默认行为先对整个路径字符串做解码再进行路由UnescapingModeAllExceptReserved除 RFC 6570 reserved 字符外其余路径参数都解码UnescapingModeAllExceptSlash解码路径参数但路径分隔符保留为%2F不解码UnescapingModeAllCharacters解码所有 URL 路径参数包括编码后的/注意runtime.UnescapingModeDefault当前就等于UnescapingModeLegacy源码注释里带有 TODO表示未来版本计划把默认值改成UnescapingModeAllExceptReserved以对齐 grpc-httpjson-transcoding 的参考实现。也就是说不传这个选项时你得到的是 Legacy 行为且这个默认值以后可能变——建议在代码里显式写出来。配置方法在构造 mux 的地方加入runtime.WithUnescapingMode选项即可文档给出的写法mux : runtime.NewServeMux( runtime.WithUnescapingMode(runtime.UnescapingModeAllExceptReserved), )如果你的诉求是保持 V2 的默认解码行为、同时允许 pct-encoded 的/即%2F通过则配置为mux : runtime.NewServeMux( runtime.WithUnescapingMode(runtime.UnescapingModeAllCharacters), )这两个片段可以直接替换/追加到你现有runtime.NewServeMux(...)的参数列表中其余选项marshaler、header matcher 等不受影响。该选哪个模式结合项目测试用例判断选模式不能只看名字要和你的 proto 中路径参数形态对应。runtime/mux_test.go 和 runtime/pattern_test.go 里的测试用例给出了各模式下的具体行为以下期望值均来自这些测试用例是测试断言不是你必须得到的固定输出单段参数{id*}值里含%2F请求GET /foo/success%2fwith%2Fspace/barpattern 为GET /foo/{id*}/barUnescapingModeAllExceptReserved路由成功200参数解析结果为id part1/part2这类解码后的值UnescapingModeAllCharacters404UnescapingModeLegacy404。也就是说单段参数场景下编码斜杠要路由通反而要用AllExceptReserved。多段参数{id**}请求GET /foo/success%2fwith%2Fspacepattern 为GET /foo/{id**}UnescapingModeAllExceptReserved路由成功200但 RFC 6570 Reserved Expansion 字符保持编码状态测试中参数值为id test%2Fbar即gRPC 服务端需要自己把%2F再解码一次UnescapingModeAllCharacters参数值直接解码为id test/bar由 gateway 完成解码。README 描述的参数改名场景OpenAPI 客户端把/编码后发上来README 建议使用UnescapingModeAllCharacters或UnescapingModeLegacy。两处建议并不冲突适用条件不同README 针对的是多段*/**路径参数被客户端编码的场景测试则说明单段{id*}参数下AllCharacters路由不了。你的请求到底落在哪种 pattern 上就以对应测试用例的行为为准。验证请求已经路由成功验证方式就是重发那条带%2F的原始请求看状态码和错误体配置前/配置错误的模式请求返回404 Not Found。默认路由错误处理会把 HTTP 状态映射成 gRPC 错误返回给客户端其中HTTP 404 Not Found - gRPC 5 NOT_FOUND、HTTP 405 Method Not Allowed - gRPC 12 UNIMPLEMENTED、HTTP 400 Bad Request - gRPC 3 INVALID_ARGUMENT。如果你拿到的是 404 且 gRPC code 为 5NOT_FOUND说明请求仍然没匹配到路由检查模式是否与路径参数形态匹配。配置正确同样的请求能进入 handler 并返回业务响应测试用例中的成功状态为 200。如果选的是UnescapingModeAllExceptReserved且参数是{id**}多段参数再核对 gRPC 服务端收到的参数值此时 reserved 字符仍带编码如test%2Fbar服务端需要自行解码后再使用不要把未解码的值直接当路径处理。限制与注意事项默认值会演进UnescapingModeDefault目前是UnescapingModeLegacy源码和 README 都注明未来版本可能改变默认行为。显式配置WithUnescapingMode可以避免升级后行为突变。UnescapingModeAllExceptReserved下多段参数的解码责任在服务端这是文档明确的行为约定不是 bug。本文覆盖的是路由阶段的解码问题如果请求能路由通但参数值不对检查的应该是模式与 pattern 的匹配关系而不是错误处理器。路由错误处理本身如需定制例如保留 HTTP 405 而不转成 501可在同一份文档的 “Routing Error handler” 一节查看runtime.WithRoutingErrorHandler的用法。【免费下载链接】grpc-gatewaygRPC to JSON proxy generator following the gRPC HTTP spec项目地址: https://gitcode.com/GitHub_Trending/gr/grpc-gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考