当前位置：首页 > news >正文

[特殊字符] 芋道项目中的参数校验机制详解：以 AppProductActivityListReqVO 为例

news 2025/10/9 5:16:19

在芋道（yudao）框架的 APP 接口开发中，我们经常会遇到这样的代码：

@GetMapping("/list")
@Operation(summary = "获得活动商品列表（按开始日期分组）")
@PermitAll
public CommonResult<List<AppProductActivityListRespVO>> getActivitySpuList(@Valid AppProductActivityListReqVO reqVO) {return success(appProductActivityService.getActivitySpuList(reqVO));
}

你可能会好奇 👇
✅ 为什么加上 @Valid 注解就能自动校验参数？
✅ 错误提示是从哪里来的？
✅ 怎么自定义规则，比如“结束时间不能早于开始时间”？

这篇文章就带你从入门到精通，彻底搞懂芋道的参数校验体系。

🧩 一、基础概念：@Valid 是做什么的？

在 Spring Boot 项目中，@Valid 或 @Validated 用于触发参数自动校验机制。

只要在 Controller 的入参上加上它：

public CommonResult<?> test(@Valid XxxReqVO reqVO)

Spring 会在调用方法前自动验证 reqVO 里的字段，
如果不符合规则，直接抛出异常（由全局异常处理器拦截返回友好提示）。

🧱 二、核心校验注解讲解

我们看下实际的例子：

@Schema(description = "用户 APP - 活动商品查询请求")
@Data
public class AppProductActivityListReqVO {@Schema(description = "开始日期", requiredMode = Schema.RequiredMode.REQUIRED, example = "2025-01-01")@DateTimeFormat(pattern = FORMAT_YEAR_MONTH_DAY)@NotNull(message = "开始日期不能为空")private LocalDate startTime;@Schema(description = "结束日期", requiredMode = Schema.RequiredMode.REQUIRED, example = "2025-01-31")@DateTimeFormat(pattern = FORMAT_YEAR_MONTH_DAY)@NotNull(message = "结束日期不能为空")private LocalDate endTime;@Schema(description = "商品分类编号，可选")private Long categoryId;

🔹 每个注解的含义如下：

注解	作用	示例
`@Schema`	仅用于 Swagger/OpenAPI 文档描述	自动生成接口文档字段说明
`@DateTimeFormat`	指定前端传入日期的格式	避免格式错误，如 `"2025-01-01"`
`@NotNull`	校验字段不为空	`"开始日期不能为空"`
`@Valid`	触发整个对象的校验	用在 Controller 入参上
`@Data`	Lombok 注解，自动生成 getter/setter	简化代码

🧮 三、进阶校验：自定义逻辑（@AssertTrue）

除了基本的非空、长度、正则验证外，芋道还经常使用自定义逻辑校验。
看下面两个方法 👇

@AssertTrue(message = "结束时间不能早于开始时间")
@JsonIgnore
public boolean isEndNotBeforeStart() {if (startTime == null || endTime == null) {return true; // 交给 @NotNull 提示}return !endTime.isBefore(startTime);
}@AssertTrue(message = "时间范围不能超过90天")
@JsonIgnore
public boolean isRangeWithinLimit() {if (startTime == null || endTime == null) {return true;}return ChronoUnit.DAYS.between(startTime, endTime) <= 90;
}

✨ 含义解析：

注解/方法	含义
`@AssertTrue`	表示该方法返回 `true` 时校验通过；返回 `false` 时提示错误信息
`@JsonIgnore`	防止这个方法被序列化到 JSON 中（否则会在响应中看到它）
方法名通常以 `is...()` 开头	Java Bean Validation 默认识别布尔校验方法

这样写的好处：

不用写自定义 Validator；
校验逻辑与字段关系紧密；
一目了然，错误提示友好。

🧰 四、Spring 如何处理这些错误？

当参数不符合要求时（例如 endTime 早于 startTime），
Spring 会抛出 MethodArgumentNotValidException，
芋道框架的全局异常处理器会捕获它，返回统一格式：

{"code": 400,"message": "结束时间不能早于开始时间"
}

这部分逻辑在：

yudao-framework -> web -> core -> handler -> GlobalExceptionHandler.java

中实现，统一把校验错误转为 CommonResult 的标准结构。

🔧 五、如何在自己的项目中使用？

你只要做到以下几步就能复用：

✅ 1. 在依赖中引入 validation

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId>
</dependency>

✅ 2. 在 Controller 入参上加上 `@Valid`

@PostMapping("/create")
public CommonResult<?> create(@Valid @RequestBody OrderCreateReqVO reqVO) {return success(orderService.create(reqVO));
}

✅ 3. 在 VO 上使用注解声明规则

public class OrderCreateReqVO {@NotBlank(message = "订单编号不能为空")private String orderNo;@Min(value = 1, message = "数量必须大于0")private Integer count;
}

✅ 4. 自定义复杂逻辑时用 `@AssertTrue` 或写自定义校验器

💡 六、额外技巧：可选 vs 必填字段

有些字段并不是必须的，比如 categoryId。
如果不加任何注解，Spring 就不会校验它。
要让它“可选但有条件约束”，可以结合 @AssertTrue 动态判断，比如：

@AssertTrue(message = "如果传入分类ID，必须大于0")
@JsonIgnore
public boolean isCategoryIdValid() {return categoryId == null || categoryId > 0;
}

🧭 七、总结

功能	用法	示例
非空验证	`@NotNull`, `@NotBlank`	字符串、数字、对象等
范围验证	`@Min`, `@Max`, `@Size`	限定长度或数值范围
格式验证	`@Email`, `@Pattern`	邮箱、手机号等
自定义逻辑	`@AssertTrue` + 布尔方法	校验时间、组合条件
全局统一返回	GlobalExceptionHandler	自动包装友好提示