java-springboot-接口参数接收全解本文详解 Spring Boot 从简单到复杂的参数接收方式：基础：路

Spring Boot 参数接收全解：从简单到复杂

本文将从最简单的参数传递开始，逐步深入到复杂场景，结合浏览器、Postman 的实际使用场景，详解 Spring Boot Controller 的参数接收方式。

概述

Spring Boot 参数接收对照表（总览）

序号	参数类型	适用场景	Spring Boot 实现	浏览器传参方式	Postman 设置	示例代码
1	URL 路径参数	获取资源标识	`@PathVariable`	`http://localhost:8080/user/1001`	URL: `http://localhost:8080/user/1001`	`java<br>@GetMapping("/user/{id}")<br>public String getUser(<br> @PathVariable String id<br>)`
2	URL 查询参数	过滤/分页/排序	`@RequestParam`	`http://localhost:8080/search?keyword=spring&page=2`	Params 标签页： Key: keyword, Value: spring Key: page, Value: 2	`java<br>@GetMapping("/search")<br>public String search(<br> @RequestParam String keyword,<br> @RequestParam int page<br>)`
3	表单文本参数	登录/注册等简单表单	`@RequestParam` 或对象绑定	`html<br><form action="/login"><br><input name="username"><br></form>`	Body → x-www-form-urlencoded： Key: username, Value: test	`java<br>@PostMapping("/login")<br>public String login(<br> @RequestParam String username<br>)`
4	JSON 对象	创建/更新复杂对象	`@RequestBody`	需通过 JavaScript 提交	Body → raw → JSON： `{"name":"张三","age":25}`	`java<br>@PostMapping("/users")<br>public User createUser(<br> @RequestBody User user<br>)`
5	单个文件上传	头像/文档上传	`MultipartFile`	`html<br><input type="file" name="avatar">`	Body → form-data： Key: avatar, Type: File	`java<br>@PostMapping("/upload")<br>public String upload(<br> @RequestParam MultipartFile avatar<br>)`
6	多个文件上传	批量文件上传	`List<MultipartFile>`	`html<br><input type="file" multiple>`	Body → form-data：多个 Key 相同的 File 字段	`java<br>@PostMapping("/uploads")<br>public String upload(<br> @RequestParam List<MultipartFile> files<br>)`
7	混合参数	表单数据+文件	组合使用 `@RequestParam`	包含文本和文件的表单	Body → form-data：文本字段 + 文件字段	`java<br>@PostMapping("/profile")<br>public String update(<br> @RequestParam String name,<br> @RequestParam MultipartFile avatar<br>)`
8	JSON 嵌套对象	多层复杂数据	`@RequestBody`	需前端构造嵌套对象	Body → raw → JSON： `{"items":[{"id":1},...]}`	`java<br>public class Order {<br> private List<Item> items;<br>}`
9	请求头参数	认证/设备信息	`@RequestHeader`	浏览器自动添加	Headers 标签页： Key: User-Agent, Value: ...	`java<br>@GetMapping("/info")<br>public String get(<br> @RequestHeader("User-Agent") String ua<br>)`
10	数组参数	多选值	`@RequestParam List<String>`	`http://...?categories=1&categories=2`	Params → 多个相同Key： categories:1 categories:2	`java<br>@GetMapping("/filter")<br>public String filter(<br> @RequestParam List<String> categories<br>)`
11	日期参数	时间范围查询	`@DateTimeFormat`	`http://...?start=2023-05-01`	Params 标签页： Key: start, Value: 2023-05-01	`java<br>@GetMapping("/events")<br>public String get(<br> @DateTimeFormat(pattern="yyyy-MM-dd") LocalDate start<br>)`
12	混合：表单+JSON	复杂配置场景	`@RequestPart`	需前端构造特殊格式	Body → form-data：文本字段 + JSON字段（需设置类型为JSON）	`java<br>@PostMapping("/project")<br>public String create(<br> @RequestPart ProjectConfig config<br>)`
13	混合：文件+JSON	文件+元数据	`@RequestPart` + `MultipartFile`	需前端特殊构造	Body → form-data：文件字段 + JSON字段	`java<br>@PostMapping("/upload")<br>public String upload(<br> @RequestPart("file") MultipartFile file,<br> @RequestPart("meta") MetaData meta<br>)`
14	全混合参数	终极复杂场景	组合使用多种注解	几乎无法直接通过浏览器访问	组合使用： 1. Path Variable 2. Query Params 3. Headers 4. Form-data:文本+文件+JSON	`java<br>@PostMapping("/{id}")<br>public String update(<br> @PathVariable Long id,<br> @RequestHeader String auth,<br> @RequestParam String type,<br> @RequestPart MultipartFile file,<br> @RequestPart Config config<br>)`

@RequestParam 与 @RequestBody 区别

特性	`@RequestParam`	`@RequestBody`
数据位置	URL 或 Form-data	请求体（JSON/XML）
数据类型	简单类型/字符串	复杂对象
Content-Type	application/x-www-form-urlencoded	application/json
数量限制	可多个	只能有一个

一、基础参数传递（GET 请求）

1. URL 路径参数 - `@PathVariable`

适用场景：获取 URL 路径中的资源标识

@GetMapping("/user/{userId}/order/{orderId}")
public String getOrder(
    @PathVariable String userId,
    @PathVariable Long orderId
) {
    return "用户: " + userId + " 的订单: " + orderId;
}

浏览器访问：

http://localhost:8080/user/U1001/order/12345

Postman 设置：

方法：GET
URL：http://localhost:8080/user/U1001/order/12345

2. URL 查询参数 - `@RequestParam`

适用场景：过滤、分页等简单参数

@GetMapping("/products")
public String searchProducts(
    @RequestParam String keyword,
    @RequestParam(defaultValue = "1") int page,
    @RequestParam(required = false) String sort
) {
    return "搜索: " + keyword + ", 页码: " + page + ", 排序: " + sort;
}

浏览器访问：

http://localhost:8080/products?keyword=手机&page=2&sort=price_desc

Postman 设置：

GET http://localhost:8080/products?keyword=手机&page=2&sort=price_desc

3. URL 数组参数

适用场景：多选框值等场景

@GetMapping("/filter")
public String filterProducts(
    @RequestParam List<String> categories
) {
    return "选中的分类: " + categories;
}

浏览器访问：

http://localhost:8080/filter?categories=手机&categories=电脑

Postman 设置：

GET http://localhost:8080/filter?categories=手机&categories=电脑

二、表单数据处理（POST 请求）

4. 简单表单参数 - `@RequestParam`

适用场景：登录表单等简单场景

@PostMapping("/login")
public String login(
    @RequestParam String username,
    @RequestParam String password
) {
    return "用户: " + username + " 登录成功";
}

HTML 表单：

<form action="/login" method="post">
  <input name="username" placeholder="用户名">
  <input name="password" type="password" placeholder="密码">
  <button>登录</button>
</form>

Postman 设置：

方法：POST
Body > x-www-form-urlencoded：
```
username: testuser
password: 123456
```

5. 对象绑定 - 无注解

适用场景：多字段表单提交

public class User {
    private String name;
    private String email;
    private int age;
    // getters/setters
}

@PostMapping("/register")
public String register(User user) {
    return "注册用户: " + user.getName();
}

HTML 表单：

<form action="/register" method="post">
  <input name="name" placeholder="姓名">
  <input name="email" placeholder="邮箱">
  <input name="age" type="number" placeholder="年龄">
  <button>注册</button>
</form>

Postman 设置：

方法：POST

Body > form-data：

name: 张三
email: zhangsan@example.com
age: 25

三、JSON 数据处理（POST/PUT）

6. 简单 JSON 对象 - `@RequestBody`

适用场景：接收单个 JSON 对象

@PostMapping("/create-user")
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

前端代码（Fetch API）：

fetch('/create-user', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '李四',
    email: 'lisi@example.com',
    age: 30
  })
});

Postman 设置：

方法：POST

Body > raw > JSON：

{
  "name": "李四",
  "email": "lisi@example.com",
  "age": 30
}

7. JSON 数组 - `@RequestBody`

适用场景：批量操作

@PostMapping("/batch-delete")
public String batchDelete(@RequestBody List<Long> ids) {
    return "删除ID数量: " + ids.size();
}

Postman 设置：

方法：POST
Body > raw > JSON：
```
[1001, 1002, 1003]
```

8. 复杂嵌套 JSON

适用场景：多层次数据结构

public class Order {
    private String orderId;
    private List<OrderItem> items;
    private Address address;
    // getters/setters
}

@PostMapping("/orders")
public Order createOrder(@RequestBody Order order) {
    return orderService.save(order);
}

Postman 设置：

{
  "orderId": "ORD-20230501",
  "items": [
    {"productId": "P1001", "quantity": 2},
    {"productId": "P1005", "quantity": 1}
  ],
  "address": {
    "province": "广东省",
    "city": "深圳市",
    "district": "南山区"
  }
}

四、文件上传处理

9. 单个文件上传

适用场景：头像上传等简单场景

@PostMapping("/upload-avatar")
public String uploadAvatar(
    @RequestParam MultipartFile avatar
) {
    return "头像上传成功: " + avatar.getOriginalFilename();
}

HTML 表单：

<form action="/upload-avatar" method="post" enctype="multipart/form-data">
  <input type="file" name="avatar">
  <button>上传</button>
</form>

Postman 设置：

方法：POST
Body > form-data：
- Key: avatar
- Type: File
- Value: 选择文件

10. 多个文件上传

适用场景：图库上传等场景

@PostMapping("/upload-images")
public String uploadImages(
    @RequestParam List<MultipartFile> images
) {
    return "成功上传 " + images.size() + " 张图片";
}

Postman 设置：

方法：POST
Body > form-data：
- Key: images
- Type: File
- Value: 选择文件 1
- 点击 "+" 添加多个文件字段

五、混合参数高级用法

11. 表单数据 + 文件上传

@PostMapping(value = "/create-profile", 
            consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String createProfile(
    @RequestParam String name,
    @RequestParam String bio,
    @RequestParam MultipartFile avatar
) {
    return "创建资料: " + name + " 头像: " + avatar.getOriginalFilename();
}

Postman 设置：

方法：POST

Body > form-data：

name: 张三
bio: 软件工程师
avatar: [选择图片文件]

12. 复杂表单数据 + 文件 + JSON（终极方案）

@PostMapping(value = "/create-project", 
            consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public String createProject(
    @RequestParam String projectName,
    @RequestParam String manager,
    @RequestParam MultipartFile proposal,
    @RequestPart ProjectConfig config
) {
    return "项目 " + projectName + " 配置: " + config.getBudget();
}

public class ProjectConfig {
    private BigDecimal budget;
    private List<String> teamMembers;
    private LocalDate deadline;
    // getters/setters
}

Postman 设置（关键点）：

POST http://localhost:8080/create-project
Body > form-data:
  projectName: 智慧城市系统
  manager: 张总
  proposal: [选择PDF文件]
  config: {
    "budget": 5000000.00,
    "teamMembers": ["张三", "李四", "王五"],
    "deadline": "2023-12-31"
  }   // 手动设置为 JSON 类型

六、特殊参数处理技巧

13. 日期时间格式化

解决方案：使用 @DateTimeFormat

@GetMapping("/schedule")
public String getSchedule(
    @RequestParam @DateTimeFormat(pattern="yyyy-MM-dd") LocalDate start,
    @RequestParam @DateTimeFormat(pattern="yyyy-MM-dd") LocalDate end
) {
    return "查询日期范围: " + start + " 到 " + end;
}

浏览器访问：

/schedule?start=2023-05-01&end=2023-05-31

14. 枚举类型处理

解决方案：Spring Boot 自动处理枚举转换

public enum OrderStatus {
    NEW, PROCESSING, COMPLETED, CANCELLED
}

@GetMapping("/orders")
public String filterOrders(
    @RequestParam OrderStatus status
) {
    return "筛选订单状态: " + status;
}

浏览器访问：

/orders?status=COMPLETED

七、参数验证与错误处理

@PostMapping("/users")
public ResponseEntity<?> createUser(
    @Valid @RequestBody UserDTO userDTO,
    BindingResult bindingResult
) {
    if (bindingResult.hasErrors()) {
        // 获取所有错误信息
        List<String> errors = bindingResult.getAllErrors()
                .stream()
                .map(DefaultMessageSourceResolvable::getDefaultMessage)
                .collect(Collectors.toList());
        
        return ResponseEntity.badRequest().body(errors);
    }
    
    // 处理有效请求...
}

public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;
    
    @Email(message = "邮箱格式不正确")
    private String email;
    
    @Min(value = 18, message = "年龄必须满18岁")
    private int age;
    
    // getters/setters
}

八、最佳实践总结

简洁原则：
- 优先使用简单参数形式（路径参数、查询参数）
- 在满足需求前提下，选择最简单的实现方式
一致性原则：
- 保持参数命名风格一致（统一用驼峰或下划线）
- 相同类型的参数使用相同的传递方式
安全原则：
- 敏感参数放在请求体中而非 URL
- 对重要操作参数进行验证
文档原则：
- 使用 Swagger 提供 API 文档
- 在文档中明确参数要求和格式
兼容原则：
- 为可选参数提供默认值
- 对重要参数设置 required = false

通过掌握这些参数传递方式，你可以轻松应对各种 API 开发场景，让 Spring Boot 成为你高效开发的得力助手！

java-springboot-接口参数接收全解

Spring Boot 参数接收全解：从简单到复杂

概述

Spring Boot 参数接收对照表（总览）

​​@RequestParam 与 @RequestBody 区别​​

一、基础参数传递（GET 请求）

1. URL 路径参数 - @PathVariable

2. URL 查询参数 - @RequestParam

3. URL 数组参数

二、表单数据处理（POST 请求）

4. 简单表单参数 - @RequestParam

5. 对象绑定 - 无注解

三、JSON 数据处理（POST/PUT）

6. 简单 JSON 对象 - @RequestBody

7. JSON 数组 - @RequestBody

8. 复杂嵌套 JSON

四、文件上传处理

9. 单个文件上传

10. 多个文件上传

五、混合参数高级用法

11. 表单数据 + 文件上传

12. 复杂表单数据 + 文件 + JSON（终极方案）

六、特殊参数处理技巧

13. 日期时间格式化

14. 枚举类型处理

七、参数验证与错误处理

八、最佳实践总结

@RequestParam 与 @RequestBody 区别

1. URL 路径参数 - `@PathVariable`

2. URL 查询参数 - `@RequestParam`

4. 简单表单参数 - `@RequestParam`

6. 简单 JSON 对象 - `@RequestBody`

7. JSON 数组 - `@RequestBody`