Ocelot网关路由配置中的查询字符串占位符问题解析

问题背景

在Ocelot网关项目的最新版本(22.0.0+)中，路由配置对于查询字符串占位符的处理方式发生了变化，这导致了一些开发者在升级后遇到了路由转发不符合预期的问题。本文将深入分析这一变更的技术细节，并提供合理的解决方案。

问题现象

开发者在使用Ocelot配置路由时，发现从上游路径模板到下游路径模板的查询字符串参数转换出现了异常。具体表现为：

• 上游请求示例：/WeatherForecast/123456/groups?something=9874565
• 预期下游转发：/account/username/groups/groupName/roles?roleId=123456&something=9874565
• 实际下游转发：/account/username/groups/groupName/roles?roleId=123456（丢失了something参数）

技术分析

1. 占位符语法规范

Ocelot要求路由模板中的占位符必须使用单花括号{}包裹，而不是双花括号{{}}。这是许多开发者容易忽视的语法细节。

正确示例：

"UpstreamPathTemplate": "/WeatherForecast/{roleId}/groups",
"DownstreamPathTemplate": "/account/{username}/groups/{groupName}/roles"

2. 查询字符串占位符处理机制

在Ocelot 22.0.0版本中，对查询字符串占位符的处理逻辑进行了优化，主要变更包括：

1. 同名参数处理：当下游查询字符串参数名与路径占位符名相同时，该参数会被自动移除
2. 参数合并规则：上游查询字符串参数默认不会自动合并到下游请求中

3. 路由模板匹配原则

Ocelot要求上下游路径模板中的占位符必须严格匹配。如果下游模板中包含了上游模板中不存在的占位符，会导致验证警告或错误。

解决方案

方案一：使用差异化命名

为避免参数被自动移除，可以采用不同的命名策略：

{
  "UpstreamPathTemplate": "/WeatherForecast/{role}/groups?{everything}",
  "DownstreamPathTemplate": "/account/{user}/groups/{group}/roles?roleId={role}&{everything}"
}

这种方案通过将路径中的{role}映射到查询字符串的roleId参数，避免了同名冲突。

方案二：显式声明所有参数

对于需要保留所有查询参数的情况，可以明确声明每个参数：

{
  "UpstreamPathTemplate": "/WeatherForecast/{role}/groups?userId={user}&groupId={group}&{everything}",
  "DownstreamPathTemplate": "/account/{user}/groups/{group}/roles?roleId={role}&{everything}"
}

方案三：使用捕获所有模式

对于简单的转发需求，可以使用捕获所有模式：

{
  "UpstreamPathTemplate": "/WeatherForecast/{role}/groups?{everything}",
  "DownstreamPathTemplate": "/account/fixedUser/groups/fixedGroup/roles?roleId={role}&{everything}"
}

最佳实践建议

1. 保持命名一致性：在上下游模板中使用相同的占位符名称
2. 显式声明参数：明确列出需要转发的查询参数
3. 利用{everything}占位符：捕获并转发所有未明确声明的查询参数
4. 版本升级测试：在升级Ocelot版本时，充分测试路由转发逻辑
5. 日志监控：关注启动时的路由验证警告信息

总结

Ocelot在22.0.0版本中对查询字符串处理逻辑的变更是为了提供更精确的路由控制能力，而非简单的功能退化。开发者需要理解这些变更背后的设计理念，并相应调整路由配置策略。通过合理使用占位符命名和参数声明，完全可以实现灵活的路由转发需求。