Skip to main content
Version: 1.0

参数接收与校验

REST 接口的参数来源有多种：路径、查询串、请求体、请求头。Spring MVC 为每种来源提供了对应注解。

参数注解总览​

注解参数来源示例
@PathVariableURL 路径变量/users/{id}
@RequestParam查询串 / 表单键值对?name=xx&page=1
@RequestBody请求体（JSON）POST 的 JSON 报文
@RequestHeader请求头Authorization: Bearer xxx
@CookieValueCookieJSESSIONID
@ModelAttribute表单绑定到对象form 表单提交

@PathVariable​

@GetMapping("/users/{id}/orders/{orderId}")
public Order get(@PathVariable Long id, @PathVariable Long orderId) { }

@RequestParam​

@GetMapping("/users")
public List<User> list(
		@RequestParam(required = false) String name,    // 非必传
		@RequestParam(defaultValue = "1") int page,     // 默认值
		@RequestParam List<Long> ids) {                 // ids=1&ids=2
	// ...
}

@RequestBody 与 DTO​

POST/PUT 的 JSON 请求体绑定到 DTO 对象：

public class UserCreateDTO {

	@NotBlank(message = "用户名不能为空")
	private String username;

	@Email(message = "邮箱格式不正确")
	private String email;

	@Min(value = 0, message = "年龄不能为负")
	private Integer age;
	// getter / setter
}

@PostMapping("/users")
public User create(@RequestBody @Valid UserCreateDTO dto) {
	return userService.create(dto);
}

@Valid 触发 JSR-303 参数校验，校验失败自动抛出 MethodArgumentNotValidException（可在全局异常处理中统一拦截，见下篇）。

常用校验注解​

注解作用
@NotNull / @NotBlank / @NotEmpty非空（对象 / 字符串 / 集合）
@Size(min, max)字符串或集合长度
@Min / @Max数值范围
@Email / @Pattern(regexp)邮箱 / 正则
@Past / @Future日期在过去 / 未来

混合参数示例​

一个真实接口往往同时用多种参数：

@PutMapping("/users/{id}")
public Result<User> update(
		@PathVariable Long id,                          // 路径
		@RequestHeader("X-Token") String token,         // 请求头
		@RequestBody @Valid UserUpdateDTO dto) {        // 请求体
	return Result.ok(userService.update(id, dto));
}
tip

GET 请求不要用 @RequestBody；简单参数用 @RequestParam，复杂对象直接省略注解也能绑定查询串字段。