一、核心说明

本文整理了SpringBoot项目开发中，API参数校验最核心的三项实战能力，均为企业项目通用落地方案。内容精简实用，无冗余理论，包含可直接上线使用的完整代码、开发规则、易错点及统一返回规范，适配日常开发、功能迭代及接口标准化整改场景。

三大核心：请求体Body自动化校验、查询参数Query自动化校验、全局统一错误返回格式

1.必备前置依赖
SpringBoot2.3+ 必须手动引入，提供所有校验注解能力

<?xml version="1.0" encoding="UTF-8"?>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
        <version>2.7.0</version>
    </dependency>
</dependencies>

二、请求体（Body）参数校验【POST/PUT】

1. 核心规则
   主要用于POST、PUT请求的复杂入参场景，支持对象、嵌套对象、集合类参数校验。通过@Valid注解开启自动化校验，覆盖全部基础校验规则，开发中无需手写大量if判断，代码更简洁规范。
2. 核心校验注解区分（必记）

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

3.核心DTO代码

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 = []

        # 用户ID校验
        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}")

1. Controller开启校验

package com.example.controller;

import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;

@RestController
@RequestMapping("/api/order")
public class OrderController {
   

    @PostMapping("/create")
    public ResultVO<String> createOrder(@Valid @RequestBody OrderCreateDTO orderDTO) {
   
        return ResultVO.success("订单创建成功");
    }
}

开发高频易错点：如果参数中存在嵌套对象、集合嵌套，仅在顶层参数加@Valid无法生效，嵌套层级必须单独添加@Valid注解，否则子参数校验失效，出现参数穿透问题

三、查询参数（Query）校验

适用于GET请求的分页查询、条件筛选、排序等简单参数场景，是查询参数专属校验方式。和请求体校验用法有明显区别，不需要在方法参数上加@Valid

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<Object> getUserPage(PageQueryDTO pageQueryDTO) {
   
        return ResultVO.success("查询成功", null);
    }
}

四、全局统一错误返回格式

项目原生的参数校验异常会直接抛出堆栈信息，前端无法解析、页面展示异常，还会暴露项目结构。通过全局统一异常处理，可统一接口返回格式，屏蔽错误堆栈，提示信息精准友好，适配前后端联调规范
1.统一返回实体ResultVO

from typing import TypeVar, Generic, Optional

T = TypeVar('T')

class ResultVO(Generic[T]):
    """API结果封装类"""

    def __init__(self, code: int = None, msg: str = None, data: T = None):
        self.code = code
        self.msg = msg
        self.data = data

    @classmethod
    def success(cls, msg: str, data: T = None):
        """成功响应"""
        result = cls()
        result.code = 200
        result.msg = msg
        result.data = data
        return result

    @classmethod
    def success_simple(cls, msg: str):
        """成功响应（无数据）"""
        return cls.success(msg, None)

    @classmethod
    def param_error(cls, msg: str):
        """参数错误响应"""
        result = cls()
        result.code = 400
        result.msg = msg
        return result

    @classmethod
    def error(cls, msg: str):
        """系统异常响应"""
        result = cls()
        result.code = 500
        result.msg = msg
        return result

    def to_dict(self):
        """转为字典格式"""
        return {
   
            'code': self.code,
            'msg': self.msg,
            'data': self.data
        }

# 使用示例
if __name__ == "__main__":
    # 成功响应
    success_result = ResultVO.success("操作成功", {
   "id": 1, "name": "test"})
    print(success_result.to_dict())

    # 参数错误响应
    param_error_result = ResultVO.param_error("参数校验失败")
    print(param_error_result.to_dict())

    # 系统错误响应
    error_result = ResultVO.error("系统异常")
    print(error_result.to_dict())

全局异常处理器

from flask import Flask, request, jsonify
from werkzeug.exceptions import HTTPException
import logging

app = Flask(__name__)

class ValidationError(Exception):
    """参数校验异常"""
    def __init__(self, message):
        self.message = message
        super().__init__(message)

class ResultVO:
    """API结果封装类"""

    @staticmethod
    def param_error(msg: str):
        return {
   
            'code': 400,
            'msg': msg,
            'data': None
        }

    @staticmethod
    def error(msg: str):
        return {
   
            'code': 500,
            'msg': msg,
            'data': None
        }

    @staticmethod
    def success(msg: str, data=None):
        return {
   
            'code': 200,
            'msg': msg,
            'data': data
        }

@app.errorhandler(ValidationError)
def handle_validation_error(error):
    """处理参数校验异常"""
    return jsonify(ResultVO.param_error(error.message)), 400

@app.errorhandler(HTTPException)
def handle_http_exception(error):
    """处理HTTP异常"""
    return jsonify(ResultVO.param_error(f"请求错误: {error.description}")), error.code

@app.errorhandler(Exception)
def handle_all_exceptions(error):
    """全局异常处理器"""
    # 记录错误日志
    logging.error(f"系统错误: {str(error)}", exc_info=True)
    return jsonify(ResultVO.error("系统繁忙，请稍后重试")), 500

# 示例路由用于测试
@app.route('/test-validation', methods=['POST'])
def test_validation():
    data = request.get_json() or {
   }

    # 模拟参数校验
    if not data.get('name'):
        raise ValidationError("姓名不能为空")

    if not isinstance(data.get('age'), int) or data['age'] < 0:
        raise ValidationError("年龄必须为非负整数")

    return jsonify(ResultVO.success("验证通过"))

if __name__ == '__main__':
    app.run(debug=True)

总结

这套API参数校验方案是SpringBoot项目的标准化通用方案，核心由请求体校验、查询参数校验、统一异常返回三部分组成，覆盖绝大多数接口开发场景。针对新增、修改类POST/PUT接口，采用@Valid注解实现复杂嵌套参数的全自动校验，从源头避免参数漏验、非法参数穿透业务层的问题；针对GET查询、分页接口，通过类注解@Validated快速完成简单参数的合法性校验，有效防止越界查询、非法字段查询导致的数据库性能问题。
配合全局异常处理器，统一拦截所有参数校验异常，规整接口返回格式，隐藏底层异常堆栈，既保障了系统安全性，又提升了前后端联调效率。整体方案摒弃了传统手动参数判断的繁琐写法，实现了参数校验前置、异常统一兜底、返回格式标准化的开发闭环，代码简洁、维护性强，完全适配生产环境落地使用