URLEncoder和URLDecoder不适用于完整URL编码解码，仅应分别用于表单参数值和原始路径段的单独处理；正确做法是用java.net.URI自动合规编码路径与参数。
URLEncoder 和 URLDecoder 不是用来处理网页路径的，强行用它们编码/解码路径会导致 404 或 500 错误。
URLEncoder.encode() 会把 / 变成 %2F，破坏 URL 路径结构
很多人以为对整个 URL 调用 URLEncoder.encode() 就能“安全传输中文”，结果发现跳转 404、Nginx 返回 400、Spring Boot 报 IllegalArgumentException: Invalid character in path——根本原因就是它把路径分隔符 /、冒号 :、问号 ? 全部编码了。
-
URLEncoder.encode("https://example.com/用户/订单?id=张三", "UTF-8")→https%3A%2F%2Fexample.com%2F%E7%94%A8%E6%88%B7%2F%E8%AE%A2%E5%8D%95%3Fid%3D%E5%BC%A0%E4%B8%89（整个 URL 变成一串不可路由的字符串） - 正确做法：只对路径段（path segment）或查询参数值单独编码，比如
"用户"→%E7%94%A8%E6%88%B7，而不是对/用户/整体编码 - Java 里推荐用
java.net.URI构造器自动处理路径编码，它内部按 RFC 3986 区分 scheme、host、path、query，只编码该编码的部分
URLDecoder.decode() 解码失败常因字符集不匹配或过度解码
收到一个含中文的请求路径如 /api/search?keyword=%E6%9D%AD%E5%B7%9E，用 URLDecoder.decode(keyword, "UTF-8") 是对的；但如果后端框架（如 Spring MVC）已自动解码过一次，你再手动调一次 URLDecoder.decode()，就会出现 NumberFormatException 或乱码——因为 %E6%9D%AD 已变成汉字“杭”，再次解码就报错。
- Spring Boot 默认对 query param 和 form data 自动 URL-decode，
@RequestParam String keyword拿到的就是已解码的字符串，无需再调URLDecoder.decode() - 只有在读取原始请求 URI（如
HttpServletRequest.getRequestURI()）时才可能拿到未解码的字符串，这时才需手动 decode，且必须指定"UTF-8"，不能用平台默认编码 - 若解码抛
IllegalArgumentException: URLDecoder: Illegal hex characters，说明传入字符串里混入了非%xx格式的非法内容，应先过滤或校验
现代 Java 应该优先用 java.net.URI 而不是 URLEncoder
直接拼接字符串 + URLEncoder 是容易出错的老套路。URI 类在构造时就做合规编码，还能避免手滑漏掉某一段。
立即学习“Java免费学习笔记（深入）”；
- 构建带中文路径的 URL：
URI uri = new URI("https", "api.example.com", "/搜索/结果", "q=" + URLEncoder.encode("Java教程", "UTF-8"), null); String url = uri.toString(); // 自动编码 path 中的中文，保留 / 和 ? 的语义 - 解析并安全获取路径段：
URI uri = new URI(request.getRequestURI()); List<String> pathSegments = Arrays.asList(uri.getPath().split("/")); String decodedSegment = URLDecoder.decode(pathSegments.get(2), "UTF-8"); // 只解码具体段 -
URLEncoder是为application/x-www-form-urlencoded设计的（表单提交），不是为通用 URL 路径设计的
真正难的不是怎么编码，而是分清哪部分是路径、哪部分是参数、哪部分已被框架处理过。多一层 decode 或少一层 encode，都可能让中文在某个环节变成 %E4%BD%A0%E5%A5%BD 或 浣犲ソ ——而问题往往出现在日志里看不到的中间层。
