17370845950

URLEncoder仅对URL查询参数值进行application/x-www-form-urlencoded编码，空格转+、中文转%xx，必须指定"UTF-8"，不可用于路径或完整URL编码。

URLEncoder 的作用很明确：专门对 URL 查询参数的值（value）做 application/x-www-form-urlencoded 编码，确保空格、中文、符号等能安全传到服务端。它不是用来编码整个 URL，也不是用来编码路径（如 /user/张三），更不是通用 URI 百分号编码工具。

URLEncoder 只处理参数值，不处理完整 URL 或路径

很多人一上来就对整个 URL 调用 URLEncoder.encode("https://api.com?q=你好", "UTF-8")，结果得到一串乱码甚至非法 URL——这是典型误用。

• 它只该用于拼接在 ? 后面的键值对中的 value 部分，比如 q=你好 中的 你好
• q 这个 key 本身一般不需要编码（除非你真要传含特殊字符的 key，但极少见）
• 路径部分（如 /search/用户中心）应使用 java.net.URI 构造，或手动对路径段做 RFC 3986 兼容编码（URLEncoder 不符合 RFC 3986，比如它把空格转成 + 而非 %20）

String queryValue = "Java 编程 & 测试";
String encodedValue = URLEncoder.encode(queryValue, "UTF-8");
// → "Java+%E7%BC%96%E7%A8%8B+%26+%E6%B5%8B%E8%AF%95"
// 注意：空格→+，&→%26，中文→%xx

必须显式指定 "UTF-8"，否则跨平台会出错

URLEncoder.encode(String) 已被标记为 @Deprecated，因为它依赖系统默认编码（Windows 可能是 GBK，Linux/macOS 通常是 UTF-8），同一段代码在不同机器上编码结果可能完全不同。

• URLEncoder.encode(String, String) 是唯一推荐用法
• 第二个参数必须是 "UTF-8" 字符串，不能写成 "utf8" 或 "utf-8"（虽然多数 JVM 容错，但规范写法是 "UTF-8"）
• Java 10+ 还支持 URLEncoder.encode(String, Charset)，可传 StandardCharsets.UTF_8，类型更安全

// ✅ 正确（推荐）
String s = URLEncoder.encode("张三&李四", "UTF-8");
// ❌ 危险（已废弃，且结果不可控）
String s = URLEncoder.encode("张三&李四"); // 平台相关，别用

空格变 +，不是 %20 —— 这是设计，不是 bug

HTTP 表单提交（application/x-www-form-urlencoded）规范允许空格编码为 +，URLEncoder 严格遵循这一点。如果你需要统一用 %20（例如某些 API 强制要求），得手动替换：

• URLEncoder.encode(...).replace("+", "%20")
• 但注意：+ 本身也要被编码（变成 %2B），所以不能无差别全局 replace；只应在确认原始字符串不含 + 时才这么干
• 更稳妥的做法是：用 java.net.URI 构造完整 URL，它内部会对 path/query 分别按 RFC 3986 处理（空格→%20，+→%2B）

String raw = "hello world+test";
String encoded = URLEncoder.encode(raw, "UTF-8");
// → "hello+world%2Btest" （空格→+，+→%2B）
// 若强行 .replace("+", "%20") → "hello%20world%2Btest"（正确）
// 但如果原始含 +，就别乱 replace

Spring 等框架已自动处理，手写编码往往是多余操作

如果你用的是 Spring MVC 的 @RequestParam、@RequestBody，或 HttpClient、OkHttp 构建 GET 请求时用 HttpUrl.Builder，它们内部都封装了正确的编码逻辑。

• 手动调用 URLEncoder 多见于：
  • 拼接原始查询字符串（如 "?q=" + URLEncoder.encode(q, "UTF-8")）
  • 解析 HttpServletRequest.getQueryString() 后手动拆参（此时需配合 URLDecoder.decode()）
• 常见错误：对已编码的参数重复编码，导致 %25E4%25BD%25A0（即 % 被二次编码成 %25）

• 前端传来的 q=%E4%BD%A0%E5%A5%BD，后端用 request.getParameter("q") 已自动解码为“你好”——无需再 URLDecoder.decode()
• 若你从 header 或 raw body 里读到原始编码串，才需要自己 decode

真正容易被忽略的一点：URLEncoder 不是 URI 编码器，它只服务表单提交场景；路径、片段、用户信息等部分，该用 URI 类或专门的 RFC 3986 工具库。