Hutool中UrlBuilder.build()方法双重编码问题解析

问题背景

在使用Hutool工具库的UrlBuilder构建URL时，开发者可能会遇到URL参数被双重编码的问题。具体表现为：当开发者已经手动对参数值进行URL编码后，UrlBuilder在构建URL时会再次对参数值进行编码，导致最终生成的URL不符合预期。

问题复现

考虑以下代码示例：

String url = "http://192.168.17.234:8080/xxx-ui/yidong/index.html/#/callback";
UrlBuilder urlBuilder = UrlBuilder.of("https://bi-uat.baidu.cn/idp/oauth2/authorize")
    .addQuery("redirect_uri", URLUtil.encodeAll(url, StandardCharsets.UTF_8))
    .addQuery("client_id", "aaaaaaa");
System.out.println(urlBuilder.build());

开发者期望的输出是：

https://bi-uat.baidu.cn/idp/oauth2/authorize?redirect_uri=http%3A%2F%2F192.168.17.234%3A8080%2Fxxx-ui%2Fyidong%2Findex.html%2F%23%2Fcallback&client_id=aaaaaaa

但实际得到的却是双重编码的结果：

https://bi-uat.baidu.cn/idp/oauth2/authorize?redirect_uri=http%253A%252F%252F192.168.17.234%253A8080%252Fxxx-ui%252Fyidong%252Findex.html%252F%2523%252Fcallback&client_id=aaaaaaa

问题原因分析

这个问题源于UrlBuilder的设计理念。UrlBuilder默认会对所有通过addQuery方法添加的参数值进行URL编码，这是为了确保生成的URL总是符合规范。当开发者已经手动对参数值进行编码后，UrlBuilder会再次编码，导致双重编码问题。

这种设计实际上是为了处理两种不同的使用场景：

1. 原始值场景：开发者传入的是未编码的原始值，UrlBuilder负责编码
2. 预编码值场景：开发者传入的是已经编码的值，希望UrlBuilder不再编码

解决方案

Hutool提供了两种方式来解决这个问题：

方案一：传入原始值

最简单的解决方案是直接传入原始值，让UrlBuilder完成编码工作：

String url = "http://192.168.17.234:8080/xxx-ui/yidong/index.html/#/callback";
UrlBuilder urlBuilder = UrlBuilder.of("https://bi-uat.baidu.cn/idp/oauth2/authorize")
    .addQuery("redirect_uri", url)
    .addQuery("client_id", "aaaaaaa");
System.out.println(urlBuilder.build());

方案二：禁用自动编码

如果确实需要手动控制编码过程，可以创建UrlBuilder时传入null禁用自动编码：

String url = "http://192.168.17.234:8080/xxx-ui/yidong/index.html/#/callback";
UrlBuilder urlBuilder = UrlBuilder.of("https://bi-uat.baidu.cn/idp/oauth2/authorize", null)
    .addQuery("redirect_uri", URLUtil.encodeAll(url, StandardCharsets.UTF_8))
    .addQuery("client_id", "aaaaaaa");
System.out.println(urlBuilder.build());

最佳实践建议

1. 优先使用方案一：让UrlBuilder处理编码工作，这样可以避免编码不一致的问题
2. 特殊情况使用方案二：只有在确实需要精确控制编码过程时才使用手动编码方式
3. 注意编码一致性：确保整个项目中URL编码的处理方式一致，避免混用两种方案

总结

Hutool的UrlBuilder默认自动编码的设计是为了简化开发者的工作，但在特定场景下可能会导致双重编码问题。理解这一设计理念后，开发者可以根据实际需求选择合适的使用方式。在大多数情况下，直接传入原始值让UrlBuilder处理编码是最简单可靠的做法。