Postman中四种请求体格式用法全解析及SpringBoot接收指南_Java

在接口开发中，请求体格式的选择直接影响数据传输的效率和正确性。postman 作为主流的接口调试工具，提供了 form data、x-www-form-urlencoded、raw、binary 四种常用请求体格式。本文将详细解析这四种格式的区别，重点对比 form data 与 x-www-form-urlencoded，并结合 spring boot 示例说明如何正确接收参数。

一、四种请求体格式的核心区别

postman 的 body 选项中，四种格式的设计初衷和适用场景差异显著，具体如下：

1. form data（multipart/form-data）

本质：通过“分隔符（boundary）”分割多个键值对的复合格式，支持文本和二进制数据（如文件）。

核心特点：

每个字段独立成块，包含字段名、内容类型（如文本/文件）等元信息。
非 ascii 字符（如中文、特殊符号）无需手动编码，直接传输原始字节。
支持同时传递文本和文件（例如：上传用户头像时，同时传递用户 id 和昵称）。

请求体示例（简化版）：

--boundary123456  // 分隔符（自动生成）
content-disposition: form-data; name="username"  // 文本字段名

张三  // 字段值（中文无需编码）
--boundary123456
content-disposition: form-data; name="avatar"; filename="head.jpg"  // 文件字段
content-type: image/jpeg  // 文件类型

[二进制文件内容]  // 直接传输文件字节
--boundary123456--  // 结束符

2. x-www-form-urlencoded

本质：将键值对拼接为字符串（如 key1=value1&key2=value2），并对非 ascii 字符进行 url 编码。

核心特点：

仅支持文本数据，不支持文件传输（因编码后为纯文本，无法承载二进制）。
数据体积小，编码后为单一字符串，适合简单表单提交（如登录、搜索框查询）。

请求体示例：

username=%e5%bc%a0%e4%b8%89&age=20  // "张三"被url编码为%e5%bc%a0%e4%b8%89

3. raw

本质：纯文本格式，支持 json、xml、html 等结构化数据，需手动指定 content-type。

核心特点：

适合传递复杂结构化数据（如 api 接口的 json 请求体）。
postman 会根据选择的格式自动设置 content-type（例如：选 json 则自动添加 application/json 头）。

常见场景：后端接口要求接收 json 格式的用户信息（如 {"name":"张三","age":20}）。

4. binary

本质：二进制数据流，对应 content-type: application/octet-stream。

核心特点：

仅支持单个二进制文件（如上传压缩包、图片），无键值对概念。
直接传输文件原始字节，适合纯文件上传场景（如“上传附件”功能）。

二、重点：form data 与 x-www-form-urlencoded 的核心区别

虽然两者都以键值对形式传输数据，但在编码方式、支持类型、适用场景上有本质区别，具体对比如下：

对比维度	form data（multipart/form-data）	x-www-form-urlencoded
编码方式	用分隔符分割多个字段，每个字段独立成块	所有字段拼接为单一字符串，url编码
支持数据类型	文本 + 二进制文件（如图片、文档）	仅支持文本（无法传输文件）
非ascii字符处理	直接传输原始字节（无需编码）	强制url编码（如中文→%e5%bc%a0…）
数据体积	较大（含分隔符和元信息）	较小（纯字符串）
适用场景	上传文件、混合文本与二进制数据	简单表单提交（登录、搜索、参数提交）
spring boot接收差异	支持 multipartfile 接收文件	仅支持文本参数，无法接收文件

一句话总结：如果需要传文件，必须用 form data；如果只是简单文本提交，x-www-form-urlencoded 更轻量。

三、postman 中如何设置四种格式

1. form data 设置

步骤：body → 选择 form-data → 点击“+”添加键值对。

文本参数：默认选“text”，直接输入键和值（如 username: 张三）。
文件参数：选择“file”，点击“select files”上传文件（如 avatar: head.jpg）。

注意：postman 会自动添加 content-type: multipart/form-data 及分隔符，无需手动设置。

2. x-www-form-urlencoded 设置

步骤：body → 选择 x-www-form-urlencoded → 直接添加键值对（如 name: 张三、age: 20）。

注意：postman 会自动对非 ascii 字符编码（如“张三”→%e5%bc%a0%e4%b8%89），并设置 content-type: application/x-www-form-urlencoded。

3. raw 设置

步骤：body → 选择 raw → 右侧下拉框选格式（如 json）→ 输入对应格式内容（如 {"name":"张三","age":20}）。

注意：格式需与内容匹配（如选 json 就必须输入合法 json 字符串）。

4. binary 设置

步骤：body → 选择 binary → 点击“select file”选择单个二进制文件（如 test.zip）。

注意：一次只能传一个文件，无键名，仅传输文件字节流。

四、spring boot 中如何接收四种格式的参数

1. 接收 form data（multipart/form-data）

适用于文本+文件混合传输，用 @requestparam 接收文本，multipartfile 接收文件。

@restcontroller
public class formdatacontroller {
    // 接收文本+文件
    @postmapping("/upload")
    public string handleformdata(
            @requestparam("username") string username,  // 文本参数
            @requestparam("avatar") multipartfile avatar  // 文件参数
    ) {
        string filename = avatar.getoriginalfilename(); // 获取文件名
        long filesize = avatar.getsize(); // 获取文件大小
        return "收到用户：" + username + "，上传文件：" + filename + "（大小：" + filesize + "字节）";
    }
}

2. 接收 x-www-form-urlencoded

适用于纯文本键值对，直接用 @requestparam 接收（与 form data 的文本参数接收方式一致）。

@restcontroller
public class urlencodedcontroller {
    @postmapping("/submit")
    public string handleurlencoded(
            @requestparam("name") string name,  // 接收文本参数
            @requestparam("age") integer age    // 自动转换类型
    ) {
        return "收到用户：" + name + "，年龄：" + age;
    }
}

3. 接收 raw

适用于结构化数据（如 json、xml），用 @requestbody 绑定到对象或字符串。

// 定义接收json的实体类
public class user {
    private string name;
    private integer age;
    // 必须提供getter和setter（spring通过反射赋值）
    public string getname() { return name; }
    public void setname(string name) { this.name = name; }
    public integer getage() { return age; }
    public void setage(integer age) { this.age = age; }
}

@restcontroller
public class rawcontroller {
    // 接收json并自动绑定到user对象
    @postmapping("/user")
    public string handlejson(@requestbody user user) {
        return "用户信息：姓名=" + user.getname() + "，年龄=" + user.getage();
    }
    
    // 直接接收原始xml文本
    @postmapping("/xml")
    public string handlexml(@requestbody string xml) {
        return "收到xml内容：" + xml;
    }
}

4. 接收 binary

适用于单个二进制文件，用 multipartfile 接收（与 form data 的文件接收方式相同）。

@restcontroller
public class binarycontroller {
    @postmapping("/upload-file")
    public string handlebinary(@requestparam("file") multipartfile file) {
        return "收到二进制文件：" + file.getoriginalfilename() 
               + "，类型：" + file.getcontenttype();
    }
}

五、总结

请求体格式	适用场景	核心特点	spring boot 接收方式
form data	文本+文件混合传输	支持二进制，分隔符分隔	@requestparam（文本）+ multipartfile（文件）
x-www-form-urlencoded	纯文本表单提交	url编码，仅支持文本	@requestparam
raw	结构化数据（json/xml等）	纯文本，需指定格式	@requestbody（绑定对象或字符串）
binary	单个二进制文件	无键值对，原始字节流	multipartfile