Java 后端 / 系统课时
接收路径、查询与请求体参数
接收路径、查询与请求体参数
一个 Web 请求可能同时携带资源标识、筛选条件、请求元数据和结构化业务数据。本课将用一个更新用户接口,把路径变量、查询参数、请求头与 JSON 请求体准确绑定到 Spring MVC 方法参数,并验证常见失败边界。
学习目标
- 根据数据语义选择路径、查询、请求头或请求体
- 使用 Spring MVC 注解完成类型安全的参数绑定
- 通过实际请求验证成功结果与典型 400 错误
四种输入位置如何选择
路径变量用于定位唯一资源,例如 /users/42 中的 42;查询参数用于控制筛选、排序或可选行为;请求头承载追踪号、认证信息等元数据;请求体适合提交结构化业务对象。选择依据是数据职责,而不是字段多少。
| 数据位置 | 常用注解 | 适合承载 | 示例 |
|---|---|---|---|
| 路径 | @PathVariable |
必填资源标识 | /users/42 |
| 查询串 | @RequestParam |
可选条件或开关 | ?notify=true |
| 请求头 | @RequestHeader |
请求元数据 | X-Request-Id |
| JSON 请求体 | @RequestBody |
新增或修改的数据 | 用户名称与邮箱 |

定义请求模型与控制器
片段示例:以下控制器放入已经引入 spring-boot-starter-web 的 Spring Boot 3 项目中。记录类型让请求体字段和返回字段保持明确,避免用无类型的 Map 接收业务数据。
java
package com.example.demo.web;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/users")
public class UserRequestController {
@PutMapping("/{userId}")
public UpdateResult updateUser(
@PathVariable long userId,
@RequestParam(defaultValue = "false") boolean notify,
@RequestHeader(value = "X-Request-Id", defaultValue = "unknown")
String requestId,
@RequestBody UpdateUserRequest request) {
// 四类输入在进入业务层前已完成名称匹配和基础类型转换
return new UpdateResult(
userId,
notify,
requestId,
request.displayName(),
request.email()
);
}
public record UpdateUserRequest(String displayName, String email) {}
public record UpdateResult(
long userId,
boolean notify,
String requestId,
String displayName,
String email) {}
}生效行为:Spring MVC 会先从 URL、查询串和请求头提取简单值,再由 Jackson 把 JSON 请求体反序列化为 UpdateUserRequest。字段名默认按 Java 属性名匹配。
发起请求并验证绑定
应用启动后执行下面的请求。<PORT> 替换为实际端口,默认通常为 8080。
bash
curl -i -X PUT "http://localhost:<PORT>/api/users/42?notify=true" \
-H "Content-Type: application/json" \
-H "X-Request-Id: req-1001" \
-d '{"displayName":"Lin","email":"lin@example.com"}'预期输出:
text
HTTP/1.1 200
Content-Type: application/json
{"userId":42,"notify":true,"requestId":"req-1001","displayName":"Lin","email":"lin@example.com"}状态行中的协议版本和响应头顺序可能不同,但状态码与 JSON 字段值应一致。
处理缺失值与类型错误
@RequestParam(defaultValue = "false") 表示未传 notify 时使用默认值;请求头也通过默认值变为可选。路径变量 userId 声明为 long,因此传入 /users/abc 会在进入方法前发生类型转换失败,Spring MVC 默认返回 400。
请求体缺失、JSON 语法错误或字段类型不兼容,同样会在反序列化阶段失败。业务必填、长度和格式规则不应靠手写 if 分散处理,后续应结合 Bean Validation 和统一异常响应。
按自己的节奏,确认真正理解。