SpringBoot API参数校验

Alan_752026-06-12 16:09

一、核心说明

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

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

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

js 复制代码 
<?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代码

pyton 复制代码 
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开启校验
java 复制代码 
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**

```python

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开启校验**
```python
// 仅需在类上加@Validated，全局开启Query/路径参数校验
@Validated
@RestController
@RequestMapping("/api/user")
public class UserController {
    @GetMapping("/page")
    public ResultVO<Object> getUserPage(PageQueryDTO pageQueryDTO) {
        return ResultVO.success("查询成功", null);
    }
}

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

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

python 复制代码 
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())```  
**全局异常处理器**
```python

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快速完成简单参数的合法性校验，有效防止越界查询、非法字段查询导致的数据库性能问题。
配合全局异常处理器，统一拦截所有参数校验异常，规整接口返回格式，隐藏底层异常堆栈，既保障了系统安全性，又提升了前后端联调效率。整体方案摒弃了传统手动参数判断的繁琐写法，实现了参数校验前置、异常统一兜底、返回格式标准化的开发闭环，代码简洁、维护性强，完全适配生产环境落地使用
相关推荐
网安情报局2 天前
告别排队与高延迟：直连GPT全系列，解锁低门槛、高稳定的AI生产力
人工智能·gpt·api·ai大模型
天空属于哈夫克33 天前
企微 RPA 接口开放：无需官方权限，外部群自由操作
自动化·企业微信·api
ZorChi3 天前
AI API 调用优化实战：统一入口与超时处理指南
人工智能·aigc·接口·api·agent·token·中转站
Resistance丶未来3 天前
管控用量，降本增效,MAI Gateway：助力企业搭建 Tokens 统一管理体系
人工智能·大模型·api·claude·ai安全·魔芋ai·maigateway
星浩AI4 天前
Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费
llm·api·claude
触底反弹5 天前
大模型时代：5 个 Prompt 替代 BERT 训练，搞定 NLP 五大任务
人工智能·node.js·api
极连AI5 天前
国产大模型譬如DeepSeek接入codex教程分享
人工智能·gpt·chatgpt·api·token·极连ai·zovelox.com
MageGojo5 天前
OCR 火车票识别 API 服务介绍与使用考量
ocr·接口·api·数据提取·火车票识别
147API6 天前
Project Glasswing 扩展后，AI 安全扫描不能只看发现漏洞
人工智能·安全·api·claude
热门推荐
01《置身钉内》原文-可播放阅读02Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析03【AI】2026 年具身智能模型和世界模型总结04AI科技热点日报 | 2026年6月1日05GitHub 镜像站点062026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？072026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？082026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf09Codex 下载安装指南：Windows 和 macOS 官方版下载10【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法