Spring Cloud Gateway中URL双重编码问题的排查与解决

问题背景

在使用Spring Cloud Gateway进行请求路由时，开发人员遇到了一个特殊的400错误问题。具体表现为：当请求路径中包含URL编码字符时（如%3D表示等号），网关会返回BAD_REQUEST响应。值得注意的是，这个问题在从Spring Boot 2.7.6升级到3.3.6版本后出现，且最初误以为是不同CPU架构（arm64与amd64）的JDK镜像导致的差异。

问题现象

开发人员配置了一个简单的路由规则，将匹配特定路径模式的请求转发到后端服务。当请求路径类似/user/1/file/-3CxBi2Z0t3GPhFXPKCnBw==时，客户端会将其编码为/user/1/file/-3CxBi2Z0t3GPhFXPKCnBw%253D%253D发送到网关。在Spring Boot 3.3.6环境下，这种请求会被网关拒绝。

深入分析

通过详细的日志分析，发现问题实际上与URL双重编码有关。关键日志显示：

The request was rejected because the URL contained a potentially malicious String "%25"

这表明Spring Security的防火墙机制检测到了可疑的URL编码字符。%25实际上是百分号%的URL编码形式，当客户端对已经编码的字符串再次进行编码时，就会出现这种情况。

根本原因

问题根源在于客户端使用了OpenAPI生成的Axios代码，这部分代码对URL进行了双重编码：

1. 第一次编码：将=编码为%3D
2. 第二次编码：将%编码为%25，导致最终路径中出现%253D

Spring Cloud Gateway的安全机制（特别是StrictServerWebExchangeFirewall）会主动拦截这种看似恶意的双重编码URL，从而保护系统免受潜在的编码攻击。

解决方案

1. 客户端修改：替换OpenAPI生成的Axios客户端代码，使用标准HTTP客户端库，确保URL只进行一次正确编码。

2. 服务端验证：虽然可以调整网关的安全策略来允许双重编码，但这会降低系统安全性，不推荐在生产环境中使用。

经验总结

1. 升级Spring Boot版本时，安全机制往往会变得更加严格，需要特别注意这类变化。

2. 不同CPU架构的JDK镜像通常不会导致这类功能性问题，排查时应优先考虑应用逻辑本身。

3. 日志级别设置非常重要，适当的日志级别能帮助快速定位问题根源。

4. URL编码处理是Web开发中的常见痛点，客户端和服务端需要统一编码策略。

最佳实践建议

1. 对于包含特殊字符的路径参数，建议明确文档化编码要求。

2. 在网关层可以添加全局过滤器，对入站请求的URL编码进行统一处理和验证。

3. 考虑使用Path变量而非查询参数传递复杂标识符，可以减少编码相关问题。

这个案例很好地展示了在微服务架构中，一个小小的编码差异如何引发连锁反应，也提醒我们在系统升级时需要全面考虑各个组件的兼容性和安全策略变化。