Spring Boot中通常无需手动调用URLDecoder.decode()，仅在通过getRequestURI()获取原始URI或读取含中文的classpath资源路径时才需显式使用URLDecoder.decode(str, "UTF-8")，且必须硬编码UTF-8，禁用默认编码以防乱码。
Spring Boot 项目中，绝大多数情况下你不需要手动调用 URLDecoder.decode()。框架已自动处理 query 参数和表单数据的解码，@RequestParam 或 @RequestBody 接收的字符串直接就是 UTF-8 解码后的中文，再 decode 会出错。
什么时候才需要手动 URLDecoder
仅在以下两种场景下才需显式使用 URLDecoder.decode(str, "UTF-8")：
- 你通过
HttpServletRequest.getRequestURI()或.getRequestURL()获取原始 URI 字符串（如/api/search?keyword=%E5%8C%97%E4%BA%AC），且要从中提取并解析路径段或未被框架接管的自定义参数部分； - 读取 classpath 资源路径（如
resource.getClassLoader().getResource("xxx").getPath()）时，路径含中文导致出现%E6%B5%8B%E8%AF%95这类编码，需用URLDecoder.decode(path, "UTF-8")恢复真实路径。
必须指定 "UTF-8"，不能用默认编码
浏览器对中文 URL 编码统一采用 UTF-8，Java 平台默认编码（如 Windows 的 GBK）与之不兼容。若写成 URLDecoder.decode(str, Charset.defaultCharset().name())，极大概率解出乱码。务必硬编码为 "UTF-8"。
例如：
错误写法：URLDecoder.decode("%E5%8C%97%E4%BA%AC", Charset.defaultCharset().name())正确写法：
URLDecoder.decode("%E5%8C%97%E4%BA%AC", "UTF-8")
遇到 IllegalArgumentException 怎么办
报错 URLDecoder: Illegal hex characters，说明传入字符串里混入了非法内容——比如本不该出现的 % 单独存在、或 %G1 这类非十六进制字符。
- 先检查来源：是否前端多 encode 了一次（如
encodeURI(encodeURI(...))）导致出现%25E5%258C%2597？此时应只 decode 一次； - 或对输入做预清洗：用正则
str.replaceAll("%[^0-9A-Fa-f]{2}", "")过滤掉格式错误的 %xx 片段； - 更稳妥的方式是捕获异常并记录原始字符串，便于定位上游问题。
现代 Java 更推荐用 URI 类替代拼接 + URLEncoder
手动拼 URL 字符串再用 URLEncoder.encode() 容易遗漏某一段（比如只编了 value 忘了 key），也难维护。从 Java 7 开始，java.net.URI 构造器内部会自动对各组件合规编码：
URI uri = new URI("https", null, "example.com", 8080, "/search", "q=" + keyword + "&lang=zh", null);
这样生成的 URI 字符串天然安全，无需手写 encode/decode 逻辑，也避免了字符集误判风险。
