表单请求为什么需要进行 URL 编码？—详解application/x-www-form-urlencoded的正确用法
大家好，我是G探险者!
先说个奇怪的现象，同样的表单请求通过postman发送就能被正常处理，但是同事通过一个程序发送了同样的表单请求就出现解析报错，原来他使用了hutool工具包里面的HttpRequest来构建了一个表单请求，发送的消息并未使用url编码，导致一些特殊字符未被解析。
今天我就聊一聊这个表单请求的细节和注意点。
在日常开发中，我们经常会使用表单方式发送 HTTP 请求，尤其是在前端提交表单或者后端模拟表单请求（如使用 Hutool、OkHttp、Postman 等工具）时，最常见的 Content-Type 就是：
Content-Type: application/x-www-form-urlencoded
那么问题来了：
表单请求的内容是不是必须进行 URL 编码？如果没有编码，会有什么后果？有哪些例外情况？
本文将从原理、标准、实践三个角度详细解析这个问题。
一、什么是 application/x-www-form-urlencoded？
这是 HTML 默认的表单提交类型，提交的数据格式如下：
key1=value1&key2=value2&key3=value3
每个字段使用 & 分隔，每个键值对使用 = 连接。整个请求体是一个类似查询字符串的格式。
二、是否需要进行 URL 编码？【结论：必须！】
答案是：是的，必须进行 URL 编码！
✅ 原因：
-
HTTP 协议标准规定该类型请求的内容应使用 URL 编码。
-
防止特殊字符冲突：比如：
&本身是分隔符，如果值中包含&，会被误认为是新参数。=是键值对分隔符，如果出现在值中，也会解析错误。
-
支持非 ASCII 字符：如中文、日文、emoji 等。
三、URL 编码规则简述
| 原字符 | 编码后 |
|---|---|
| 空格 | + 或 %20（实现不同） |
& | %26 |
= | %3D |
张三 | %E5%BC%A0%E4%B8%89 |
编码过程通常使用语言内置函数或工具类，如 Java 的 URLEncoder.encode(str, "UTF-8")。
四、浏览器行为举例
HTML 中标准表单如下：
<form action="/submit" method="post"><input name="name" value="张三"><input name="age" value="18"><button type="submit">提交</button>
</form>
浏览器会自动生成如下请求：
POST /submit HTTP/1.1
Content-Type: application/x-www-form-urlencodedname=%E5%BC%A0%E4%B8%89&age=18
注意：中文 “张三” 被正确编码为 %E5%BC%A0%E4%B8%89。
五、Hutool / Java 中的正确做法
❌ 错误示例（没有编码）：
// 直接拼接原始 JSON，无编码
String body = "message={\"name\":\"张三\",\"age\":18}";
HttpRequest.post(url).header("Content-Type", "application/x-www-form-urlencoded").body(body).execute();
后端收到的内容可能乱码或报错。
✅ 正确示例（手动编码）：
String json = "{\"name\":\"张三\",\"age\":18}";
String encoded = URLEncoder.encode(json, "UTF-8");String body = "message=" + encoded;
HttpRequest.post(url).header("Content-Type", "application/x-www-form-urlencoded").body(body).execute();
✅ 推荐方式（自动编码）：
Map<String, Object> form = new HashMap<>();
form.put("message", "{\"name\":\"张三\",\"age\":18}");HttpRequest.post(url).form(form) // 自动编码、自动设置 Content-Type.execute();
六、其他 Content-Type 对比
| Content-Type | 是否需要编码 | 说明 |
|---|---|---|
application/x-www-form-urlencoded | ✅ 必须编码 | 表单默认提交格式 |
application/json | ❌ 不需要编码 | 请求体直接是 JSON 字符串 |
multipart/form-data | ❌ 不需要编码 | 多用于文件上传，每个字段单独传输 |
text/plain | ❌ 不需要编码 | 原始文本内容，主要用于调试或简单请求 |
七、不编码的后果
如果不对表单参数进行 URL 编码，可能出现如下问题：
- 中文乱码
- 后端解析失败，参数缺失或格式错误
- 特殊字符干扰其他字段解析（如
&、=） - 安全隐患，如 XSS 注入、非法字符处理错误
八、结语
凡是使用
application/x-www-form-urlencoded的请求，就必须对请求体的参数值进行 URL 编码！
编码不仅是为了规范，也是确保数据安全和接口兼容性的基本保障。
开发中如果使用第三方工具类或框架（如 Hutool、RestTemplate），请务必确认参数是否已经正确编码，或者直接使用 .form() 方法由框架自动完成。
如你需要附带 JSON 等复杂结构做表单值传输，也可以考虑：
- 对 JSON 做 URL 编码后作为表单字段值（如
message=URLEncoder(JSON)） - 或者改用
application/json类型，后端直接解析 JSON（更清晰）
如需示例代码或想了解更多细节，可随时留言交流。