Spring Boot 请求参数接收速查手册

Spring Boot 请求参数接收速查手册

---

1. 简单参数（URL 查询参数）

• 场景：接收单个键值对参数（如 ?name=John&age=20）。

• 注解：@RequestParam

• 示例：

  @GetMapping("/user")
  public String getUser(
      @RequestParam("username") String name, // 显式映射参数名
      @RequestParam(required = false, defaultValue = "18") Integer age // 非必填，默认值
  ) {
      return "User: " + name + ", Age: " + age;
  }
  

• 注意：

  • 参数名与形参名一致时，可省略 @RequestParam。
  • 基本类型（如 int）建议用包装类（如 Integer）避免空指针。

---

2. 路径参数（RESTful 风格）

• 场景：从 URL 路径中提取参数（如 /user/1001）。

• 注解：@PathVariable

• 示例：

  @GetMapping("/user/{id}")
  public String getUserById(@PathVariable Long id) {
      return "User ID: " + id;
  }
  

• 注意：

  • URL 模板需与注解参数匹配（如 {id} → @PathVariable("id")）。

---

3. POJO 对象参数（表单/查询参数绑定）

• 场景：自动将多个参数绑定到对象属性。

• 示例：

  @PostMapping("/user")
  public String createUser(User user) { // 自动映射 name=John&age=20
      return "Created: " + user;
  }
  

• 规则：

  • 参数名与对象属性名严格匹配。
  • 支持嵌套对象（如 user.address.province=Beijing）。

---

4. 数组/集合参数

• 场景：接收多个同名参数（如 ?hobby=game&hobby=music）。

• 示例：

  // 数组接收
  @GetMapping("/hobbies")
  public String getHobbies(String[] hobby) {
      return Arrays.toString(hobby);
  }
  
  // 集合接收（需 @RequestParam）
  @GetMapping("/hobbiesList")
  public String getHobbiesList(@RequestParam List<String> hobby) {
      return hobby.toString();
  }
  

---

5. JSON 参数（请求体）

• 场景：接收 JSON 格式的请求体数据。

• 注解：@RequestBody

• 示例：

  @PostMapping("/user")
  public String createUser(@RequestBody User user) {
      return "Created: " + user;
  }
  

• 注意：

  • 需设置请求头 Content-Type: application/json。
  • 仅适用于 POST、PUT 等有请求体的方法。

---

6. 混合使用示例

@PostMapping("/order/{orderId}")
public String updateOrder(
    @PathVariable Long orderId,
    @RequestParam String action,
    @RequestBody OrderDTO orderDTO
) {
    return "Order " + orderId + " updated with action: " + action;
}

---

总结对比表

参数类型	接收方式	注解	典型请求示例
简单参数	方法形参	@RequestParam	GET /user?name=John
路径参数	URL 路径占位符	@PathVariable	GET /user/1001
POJO 对象	对象属性自动绑定	无	POST /user (form-data)
JSON 参数	请求体 + POJO	@RequestBody	POST /user (JSON body)
数组/集合	数组或集合类型	@RequestParam	GET /hobbies?hobby=game&hobby=music

---

常见问题

1. @RequestParam vs @PathVariable

   • @RequestParam：从 URL 查询参数获取（?key=value）。
   • @PathVariable：从 URL 路径中获取（/users/{id}）。

2. 何时必须用 @RequestBody？

   • 当参数通过请求体传递（如 JSON/XML）时必须使用。

3. POJO 绑定失败处理

   • 检查属性名是否与参数名一致。
   • 使用 @JsonIgnore 忽略无关字段。