表单请求为什么需要进行 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 编码！

✅ 原因：

1. HTTP 协议标准规定该类型请求的内容应使用 URL 编码。

2. 防止特殊字符冲突：比如：

   • & 本身是分隔符，如果值中包含 &，会被误认为是新参数。
   • = 是键值对分隔符，如果出现在值中，也会解析错误。

3. 支持非 ASCII 字符：如中文、日文、emoji 等。

三、URL 编码规则简述

编码过程通常使用语言内置函数或工具类，如 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-urlencoded

name=%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 对比

七、不编码的后果

如果不对表单参数进行 URL 编码，可能出现如下问题：

• 中文乱码
• 后端解析失败，参数缺失或格式错误
• 特殊字符干扰其他字段解析（如 &、=）
• 安全隐患，如 XSS 注入、非法字符处理错误

八、结语

凡是使用 application/x-www-form-urlencoded 的请求，就必须对请求体的参数值进行 URL 编码！

编码不仅是为了规范，也是确保数据安全和接口兼容性的基本保障。

开发中如果使用第三方工具类或框架（如 Hutool、RestTemplate），请务必确认参数是否已经正确编码，或者直接使用 .form() 方法由框架自动完成。

如你需要附带 JSON 等复杂结构做表单值传输，也可以考虑：

• 对 JSON 做 URL 编码后作为表单字段值（如 message=URLEncoder(JSON)）
• 或者改用 application/json 类型，后端直接解析 JSON（更清晰）

如需示例代码或想了解更多细节，可随时留言交流。