Spring Boot 中 @RequestParam 和 @RequestPart 的区别详解（含实际项目案例）

news2026/3/2 1:08:35

Spring Boot 中 @RequestParam 和 @RequestPart 的区别详解（含实际项目案例）

在日常的 Spring Boot 开发中，我们经常会遇到表单提交、文件上传、JSON 参数绑定等需求。而在处理这类请求时，两个常见的注解——@RequestParam 和 @RequestPart——经常被用来接收前端传递的参数。

它们看似相似，但适用场景却有着本质区别。在本文中，我将结合我在项目中的两个真实场景，对这两个注解进行详细解析，希望能帮助你更好地理解并灵活运用它们。

一、先看基本概念

1. @RequestParam 是什么？

用于接收表单中的简单参数，例如字符串、数字或单个文件等。
支持 application/x-www-form-urlencoded、multipart/form-data 等常见的表单类型。
可用于绑定 URL 查询参数或表单字段。

@PostMapping("/upload-mp3")
public String upload(@RequestParam("file") MultipartFile file) {
    // 处理单个文件上传
}

2. @RequestPart 是什么？

专门用于处理 multipart/form-data 类型的请求。
常用于接收复杂结构的数据（例如 JSON + 文件）。
支持将 part 中的 JSON 自动转换为 Java 对象。

@PostMapping("/create-prize")
public String createPrize(@RequestPart("param") PrizeParam param,
                          @RequestPart("pic") MultipartFile picFile) {
    // 同时处理 JSON 参数和文件上传
}

二、结合项目实战场景

✅ 场景一：上传 MP3 文件 —— 使用 @RequestParam

在我的项目中有一个上传音频的功能，用户只需上传一个 MP3 文件，不涉及其他参数。此时前端表单格式如下：

<form method="post" enctype="multipart/form-data">
    <input type="file" name="file" />
</form>

后台接口使用的是 @RequestParam：

@PostMapping("/music/upload")
public ResponseEntity<String> upload(@RequestParam("file") MultipartFile file) {
    // 简单文件上传处理
    return ResponseEntity.ok("上传成功");
}

👉 这个场景中参数结构非常简单，使用 @RequestParam 是最自然的选择。

✅ 场景二：创建奖品 —— 使用 @RequestPart

在奖品管理模块中，用户需要上传两类数据：

奖品的详细信息（如名称、数量、规则等）：使用一个 JSON 对象提交；
奖品的图片：作为文件上传。

前端以 multipart/form-data 格式提交这两个字段：

let formData = new FormData();
formData.append("param", new Blob([JSON.stringify(prizeParam)], { type: "application/json" }));
formData.append("prizePic", file);

后端控制器这样写：

@RequestMapping("/prize/create")
public CommonResult<Long> createPrize(@RequestPart("param") CreatePrizeParam param,
                                      @RequestPart("prizePic") MultipartFile picFile) {
    // 处理复杂 multipart 请求
    return CommonResult.success(prizeService.createPrize(param, picFile));
}

👉 由于传递的是JSON 对象 + 文件的复合结构，必须使用 @RequestPart，否则 JSON 无法被正常转换为 Java Bean。

三、总结：@RequestParam 与 @RequestPart 的区别

比较点	@RequestParam	@RequestPart
适用请求类型	`application/x-www-form-urlencoded`	`multipart/form-data`
适用参数类型	简单类型（字符串、文件、数字）	复杂类型（JSON 对象、多个文件、嵌套结构）
JSON 自动转换	❌ 不支持	✅ 支持（通过 HttpMessageConverter）
常见使用场景	普通表单提交、单文件上传	JSON + 文件上传、富表单场景

四、面试回答建议

如果在面试中被问到这个问题，可以这样回答：

我在项目中有两个典型的场景分别用到了 @RequestParam 和 @RequestPart。一个是上传 MP3 文件，仅需要上传一个文件，使用 @RequestParam 足够；另一个是创建奖品，需要同时上传一个 JSON 格式的奖品信息和一张图片，因此使用了 @RequestPart。因为 @RequestPart 支持将 multipart 请求中的 JSON 自动绑定到 Java 对象，这也是它比 @RequestParam 更适合处理复杂表单的原因。