Postman 四种请求体格式全解析:区别、用法及 Spring Boot 接收指南

Postman 四种请求体格式全解析:区别、用法及 Spring Boot 接收指南

在接口开发中,请求体格式的选择直接影响数据传输的效率和正确性。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 接收文件。

java 复制代码
@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 的文本参数接收方式一致)。

java 复制代码
@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 绑定到对象或字符串。

java 复制代码
// 定义接收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 的文件接收方式相同)。

java 复制代码
@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

掌握这四种格式的差异,尤其是 Form Data 与 x-www-form-urlencoded 的区别,能帮助我们在前后端联调中快速选择合适的传输方式,避免"传文件失败""参数乱码"等常见问题。

相关推荐
麦兜*27 分钟前
Spring Boot 与 Ollama 集成部署私有LLM服务 的完整避坑指南,涵盖 环境配置、模型管理、性能优化 和 安全加固
java·spring boot·后端·安全·spring cloud·性能优化
烟沙九洲30 分钟前
服务之间远程Feign调用,出现参数丢失
java·spring boot
麦兜*1 小时前
国产大模型平替方案:Spring Boot通义千问API集成指南
java·spring boot·后端·python·spring cloud·系统架构·springboot
顽疲2 小时前
从零用java实现小红书springboot_vue_uniapp(15)评论和im添加图片
java·vue.js·spring boot·uni-app
贰拾wan2 小时前
SpringBoot自动装配原理
java·spring boot·spring
Derek_Smart2 小时前
Netty 客户端与服务端选型分析:下位机连接场景
spring boot·后端·netty
飞翔的佩奇6 小时前
基于SpringBoot+MyBatis+MySQL+VUE实现的房屋交易平台管理系统(附源码+数据库+毕业论文+部署教程+配套软件)
数据库·spring boot·mysql·vue·毕业设计·mybatis·房屋交易平台
洛可可白12 小时前
Spring Boot 应用结合 Knife4j 进行 API 分组授权管理配置
java·spring boot·后端
亲爱的非洲野猪12 小时前
ZooKeeper 深度实践:从原理到 Spring Boot 全栈落地
spring boot·zookeeper·java-zookeeper