URLEncoder只适用于编码URL查询参数的值，不能编码整个URL或路径段；它按x-www-form-urlencoded规范将所有非字母数字字符（除-_.*）转义为%XX，包括/和:，导致非法URL；正确做法是对每个查询参数值单独调用URLEncoder.encode(value, "UTF-8")后拼接。
URLEncoder 在 Java 中**只适用于编码 URL 查询参数的值（即 key=value 中的 value）**，不能直接用来编码整个 URL 或路径段。用错场景会导致双编码、斜杠被转义、无法被服务端正确解析等问题。
为什么 URLEncoder.encode() 会把 / 和 : 也编码？
因为 URLEncoder 的设计目标是“将字符串按 x-www-form-urlencoded 规范编码”，它把所有非字母数字字符（除了 -、_、.、*）一律转成 %XX 形式——包括路径分隔符 /、协议分隔符 :、问号 ? 等。这在 URL 路径或完整 URL 上完全错误。
- 它不区分 URL 的结构（协议、主机、路径、查询），只是粗暴地“全量转义”
-
URLEncoder.encode("https://api.example.com/v1/users", "UTF-8")会把:、/全部变成%3A、%2F，结果根本不是合法 URL - 真正该编码的，只是查询参数里的值，比如
q=hello world&tag=c++中的hello world和c++
如何正确编码 URL 查询参数的值？
对每个 value 单独调用 URLEncoder.encode()，并确保使用 UTF-8 编码，再手动拼接。不要对整个 query string 一次性编码。
将后端 Java 接口文档转换为前端 TypeScript 类型定义（interface / type）。输入：飞书文档、Spring Boot 接口文档、Swagger/OpenAPI、手写 API 文档等。输出：包含请求参数与响应结果的 .md 文件，含完整 JSDoc 注释。触发关键词：Java 转 TS、接口转换、生成前端类型、接口文档转 TypeScript、DTO/VO/BO 转 interface、后端文档转前端类型、生成接口类型、类型定义生成。
- 必须指定字符集：
URLEncoder.encode(value, "UTF-8")（Java 10+ 可用StandardCharsets.UTF_8） - 空格会被编码为
+（符合 x-www-form-urlencoded），这是正确的，不必替换成%20 - 示例：
String q = "java & spring"; String encodedQ = URLEncoder.encode(q, "UTF-8"); // → "java+%26+spring" String url = "https://api.example.com/search?q=" + encodedQ;
- 如果 value 本身含
=或&，也照常编码——它们在 value 内部是合法内容，不应由你手动切分
需要编码 URL 路径段（path segment）时怎么办？
URLEncoder 不适用。路径段需保留 / 字面量，仅对其中的“单个片段”做百分号编码，推荐用 java.net.URI 构造器或第三方库（如 Apache HttpClient 的 URIBuilder）。
立即学习“Java免费学习笔记（深入）”；
- 手动拼接路径 +
URLEncoder是危险的：比如"user/" + URLEncoder.encode("a/b", "UTF-8")→user/a%2Fb，看似 OK，但容易漏掉边界情况 - 更可靠的方式：
URI uri = new URI("https", "api.example.com", "/v1/users/" + username, null); String safeUrl = uri.toString(); // 自动对 path 中的非法字符编码，/ 保持原样 - 注意：
new URI(...)会抛URISyntaxException，且不对查询参数做x-www-form-urlencoded处理（那是URLEncoder的职责）
最易被忽略的一点：URL 编码不是“越全越好”。编码的位置必须和 URL 的语法层级严格对应——路径段用 URI，查询值用 URLEncoder，混淆二者是线上 400 或 404 的常见原因。
