SpringBoot API参数校验最佳实践指南

一、核心说明

平时做SpringBoot项目，参数校验这块总是绕不开。很多同学要么手写一堆if/else，要么用了注解但踩坑不断。这次直接把最核心的三项实战能力拎出来——都是企业项目里通用的落地方案，没有花哨的理论，拿来就能用。附带完整代码、开发规则、易错点和统一返回规范，无论是日常开发、功能迭代还是接口标准化整改，都能对上。

这次主要讲三块：请求体Body自动校验、查询参数Query自动校验、以及全局统一错误返回格式。哪一块都是生产中高频使用的。

先说前置依赖。如果你用的是SpringBoot 2.3及以上版本，需要手动引入一个starter——spring-boot-starter-validation，它提供了所有校验注解。注意是手动引入，因为从2.3开始它不再默认包含。代码这样加：

    org.springframework.boot
    spring-boot-starter-validation
    2.7.0

二、请求体（Body）参数校验：POST/PUT接口的核心

这部分主要用在POST和PUT这种复杂入参场景，支持对象、嵌套对象、集合类参数校验。靠@Valid注解就能开启自动化校验，覆盖全部基础校验规则，开发中再也不用手写大量if判断了，代码干净很多。

下面这几个注解得记牢，最常用：

• @NotNull：数值、对象非空
• @NotBlank：字符串非空
• @NotEmpty：集合、字符串非空
• @Min / @Max：数值范围限制
• @Size：字符串/集合长度限制
• @Pattern：正则格式校验

这里给出一段订单创建的DTO校验代码（示例是用Python写的，逻辑可移植到Ja va）：

from dataclasses import dataclass
from typing import List, Optional
from decimal import Decimal
import re

class ValidationError(Exception):
    def __init__(self, field, message):
        self.field = field
        self.message = message
        super().__init__(f"{field}: {message}")

@dataclass
class OrderItemDTO:
    goods_id: int
    count: int
    def validate(self):
        errors = []
        if self.goods_id is None:
            errors.append(ValidationError("goodsId", "商品ID不能为空"))
        elif self.goods_id < 1:
            errors.append(ValidationError("goodsId", "商品ID非法"))
        if self.count is None:
            errors.append(ValidationError("count", "购买数量不能为空"))
        elif self.count < 1:
            errors.append(ValidationError("count", "数量不能小于1"))
        if errors:
            raise ValueError("; ".join([f"{e.field}: {e.message}" for e in errors]))

@dataclass
class OrderCreateDTO:
    user_id: int
    phone: str
    amount: Decimal
    item_list: List[OrderItemDTO]
    remark: Optional[str] = None
    def validate(self):
        errors = []
        if self.user_id is None:
            errors.append(ValidationError("userId", "用户ID不能为空"))
        elif self.user_id < 1:
            errors.append(ValidationError("userId", "用户ID取值非法"))
        if not self.phone or not self.phone.strip():
            errors.append(ValidationError("phone", "手机号不能为空"))
        elif not re.match(r"^1[3-9]d{9}$", self.phone):
            errors.append(ValidationError("phone", "手机号格式错误"))
        if self.amount is None:
            errors.append(ValidationError("amount", "订单金额必须大于0"))
        elif self.amount <= 0:
            errors.append(ValidationError("amount", "订单金额必须大于0"))
        if self.remark and len(self.remark) > 500:
            errors.append(ValidationError("remark", "备注不能超过500字符"))
        if not self.item_list:
            errors.append(ValidationError("itemList", "商品列表不能为空"))
        else:
            for i, item in enumerate(self.item_list):
                try:
                    item.validate()
                except ValueError as e:
                    errors.append(ValidationError(f"itemList[{i}]", str(e)))
        if errors:
            raise ValueError("; ".join([f"{e.field}: {e.message}" for e in errors]))

if __name__ == "__main__":
    item1 = OrderItemDTO(goods_id=123, count=2)
    item2 = OrderItemDTO(goods_id=456, count=1)
    order = OrderCreateDTO(user_id=1001, phone="13812345678", amount=Decimal("99.99"), item_list=[item1, item2], remark="请尽快发货")
    try:
        order.validate()
        print("订单验证通过")
    except ValueError as e:
        print(f"验证失败: {e}")

Controller开启校验：

package com.example.controller;
import org.springframework.web.bind.annotation.*;
import ja vax.validation.Valid;
@RestController
@RequestMapping("/api/order")
public class OrderController {
    @PostMapping("/create")
    public ResultVO createOrder(@Valid @RequestBody OrderCreateDTO orderDTO) {
        return ResultVO.success("订单创建成功");
    }
}

有个大坑必须提醒：如果你的参数里嵌套了对象或集合，只在顶层加@Valid是不够的。必须在嵌套层级上也单独加@Valid注解，否则子参数校验会失效，参数直接穿透过去。这一点很容易忽略。

三、查询参数（Query）校验：GET请求的利器

这部分适用于GET请求的分页查询、条件筛选、排序这类简单参数场景。和请求体校验的用法有明显区别——不需要在方法参数上加@Valid，而是在类上加@Validated就行。

1.分页参数DTO

from dataclasses import dataclass
from typing import Optional

class ValidationError(Exception):
    def __init__(self, field, message):
        self.field = field
        self.message = message
        super().__init__(f"{field}: {message}")

@dataclass
class PageQueryDTO:
    pageNum: int = 1
    pageSize: int = 10
    sortField: Optional[str] = None
    sortType: Optional[str] = None
    def validate(self):
        errors = []
        if self.pageNum is None or self.pageNum < 1:
            errors.append(ValidationError("pageNum", "页码不能小于1"))
        if self.pageSize is None or self.pageSize < 1:
            errors.append(ValidationError("pageSize", "每页大小不能小于1"))
        elif self.pageSize > 100:
            errors.append(ValidationError("pageSize", "每页最大100条，防止全表查询"))
        if self.sortField:
            import re
            if not re.match(r"^[a-zA-Z0-9_]{1,30}$", self.sortField):
                errors.append(ValidationError("sortField", "排序字段非法"))
        if self.sortType:
            if self.sortType.lower() not in ["asc", "desc"]:
                errors.append(ValidationError("sortType", "排序方式仅支持asc/desc"))
        if errors:
            raise ValueError("; ".join([f"{e.field}: {e.message}" for e in errors]))

2.Controller开启校验

// 仅需在类上加@Validated，全局开启Query/路径参数校验
@Validated
@RestController
@RequestMapping("/api/user")
public class UserController {
    @GetMapping("/page")
    public ResultVO