Spring MVC 中@RequestParam与@RequestPart的区别详解

你好呀，我是小邹。

在 Spring MVC 中，@RequestParam 和 @RequestPart 都是用于处理 HTTP 请求数据的注解，但它们的适用场景和底层机制有显著差异。本文将通过对比和示例详细说明两者的区别及使用场景。

一、核心区别总结

二、@RequestParam 详解及示例

适用场景：处理 简单数据类型 的请求参数，如 URL 查询字符串或传统表单提交。

1. 获取 URL 查询参数

// 请求示例：GET /user?name=John&age=25
@GetMapping("/user")
public String getUser(
    @RequestParam String name, 
    @RequestParam int age) {
    return "Name: " + name + ", Age: " + age;
}

2. 处理表单数据 (application/x-www-form-urlencoded)

// 表单提交：POST /submit-form (Content-Type: application/x-www-form-urlencoded)
@PostMapping("/submit-form")
public String handleForm(
    @RequestParam String username,
    @RequestParam String password) {
    // 处理用户名和密码
}

3. 处理 Multipart 请求中的简单字段

// 文件上传表单中的文本字段
@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String uploadFile(
    @RequestParam String description, // 文本字段
    @RequestParam MultipartFile file) { // 文件字段
    // 保存文件及描述
}

三、@RequestPart 详解及示例

适用场景：处理 复杂数据类型 或需要按 Content-Type 解析的 multipart/form-data 请求。

1. 直接绑定上传文件

@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String upload(
    @RequestPart MultipartFile file) { // 更语义化的文件声明
    file.transferTo(new File("/path/to/save"));
    return "Upload success!";
}

2. 解析 JSON 数据到对象

// 请求示例：Part 名称为 "user"，Content-Type: application/json
// 请求体：{"name":"John","age":25}
@PostMapping(value = "/create-user", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String createUser(
    @RequestPart("user") User user) { // 自动通过 HttpMessageConverter 解析
    // 使用 user 对象
    return "User created: " + user.getName();
}

3. 混合处理文件与复杂对象

@PostMapping(value = "/profile", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String updateProfile(
    @RequestPart("metadata") ProfileMeta metadata, // JSON 对象
    @RequestPart("avatar") MultipartFile avatar) { // 图片文件
    // 保存头像并更新元数据
    return "Profile updated";
}

四、关键区别深度解析

1. 数据解析机制

   • @RequestParam：
     直接通过 request.getParameter() 获取字符串值，Spring 仅进行简单类型转换（如 String→int）。
   • @RequestPart：
     使用 HttpMessageConverter 根据 Part 的 Content-Type 解析数据（如 JSON→Object）。

2. Content-Type 处理能力

   • @RequestParam：忽略 Content-Type，按字符串处理。
   • @RequestPart：要求 Part 设置正确的 Content-Type（如 application/json），否则无法解析对象。

3. 文件上传语义

   • 两者都支持 MultipartFile，但 @RequestPart 更明确表示“处理 multipart 的一部分”。

4. 默认行为差异

   • @RequestParam 默认必传（可通过 required=false 修改）。
   • @RequestPart 同样默认必传，但多用于强制要求客户端发送特定 Part。

五、如何选择？

• 使用 @RequestParam 当：

  • 处理 URL 查询参数或传统表单字段。
  • 数据为简单类型（String、int、List 等）。
  • 无需按 Content-Type 解析原始数据。

• 使用 @RequestPart 当：

  • 处理 multipart/form-data 请求中的非文本数据（如文件）。
  • 需要将 Part 数据绑定到复杂对象（如 JSON、XML）。
  • 需要根据 Part 的 Content-Type 动态解析数据。

六、常见问题

Q1：能否用 @RequestParam 接收 JSON 对象？
❌ 不能。@RequestParam 会将整个 JSON 字符串当作 String 处理，无法自动转换为对象。

Q2：上传文件时该用哪个？
✅ 两者均可，但 @RequestPart 更推荐：

// 更佳实践
@RequestPart MultipartFile file

// 等价于
@RequestParam MultipartFile file

Q3：如何接收多个文件？
使用数组或集合：

@RequestPart MultipartFile[] files // 或 List<MultipartFile>

总结

正确区分 @RequestParam 和 @RequestPart 能显著提升代码可读性和健壮性。在处理 multipart/form-data 时，优先考虑 @RequestPart 以充分利用 Spring 的内容协商机制，而对于简单参数场景，@RequestParam 仍是首选。