字符串、数组长度验证和可接受范围内的数字验证

在 Jakarta Validation (JSR 380) 中，验证字符串或数组的长度以及数值是否在指定范围内是常见的校验需求。以下是相关的注解及其用法：

1. 长度验证 (@Size)

@Size 注解用于验证字符串、集合、映射或数组的大小（长度）是否在指定的范围内。

• 适用类型: CharSequence, Collection, Map, 数组。
• 常用参数:
  • min: 最小长度（包含），默认为 0。
  • max: 最大长度（包含），无默认值。
  • message: 校验失败时的错误消息。

示例代码：

import jakarta.validation.constraints.Size;
import java.util.List;

public class UserForm {

    // 用户名长度必须在 2 到 20 个字符之间
    @Size(min = 2, max = 20, message = "用户名长度必须在 2 到 20 之间")
    private String username;

    // 标签列表不能为空，且最多包含 5 个标签
    @Size(min = 1, max = 5, message = "至少需要一个标签，最多五个")
    private List<String> tags;

    // 数组长度验证
    @Size(max = 3, message = "电话号码数组不能超过 3 个")
    private String[] phoneNumbers;
    
    // getters and setters...
}

2. 数值范围验证 (@Min, @Max, @DecimalMin, @DecimalMax, @Digits)

对于数字类型的字段，可以使用以下注解来验证其值是否在允许的范围内。

整数范围 (@Min, @Max)

适用于 byte, short, int, long 以及对应的包装类，还有 BigInteger。

• @Min(value): 验证值是否大于或等于指定值。
• @Max(value): 验证值是否小于或等于指定值。

示例代码：

import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Max;

public class ProductForm {

    // 年龄必须在 18 到 100 之间
    @Min(value = 18, message = "年龄不能小于 18 岁")
    @Max(value = 100, message = "年龄不能大于 100 岁")
    private Integer age;

    // 库存数量不能为负数
    @Min(value = 0, message = "库存数量不能为负")
    private Long stock;
    
    // getters and setters...
}

高精度数值范围 (@DecimalMin, @DecimalMax)

适用于 BigDecimal, String, char, CharSequence 以及任何实现了 Comparable 接口的类型。支持字符串形式的数值，适合处理金额等高精度场景。

• @DecimalMin(value): 验证值是否大于或等于指定值（支持 inclusive 参数）。
• @DecimalMax(value): 验证值是否小于或等于指定值（支持 inclusive 参数）。

示例代码：

import jakarta.validation.constraints.DecimalMin;
import jakarta.validation.constraints.DecimalMax;
import java.math.BigDecimal;

public class OrderForm {

    // 订单金额必须大于 0.00 且小于等于 10000.00
    @DecimalMin(value = "0.00", inclusive = false, message = "订单金额必须大于 0")
    @DecimalMax(value = "10000.00", message = "订单金额不能超过 10000")
    private BigDecimal amount;
    
    // getters and setters...
}

数字精度验证 (@Digits)

@Digits 注解用于验证数字是否符合指定的精度要求，即整数部分和小数部分的位数限制。这对于需要严格控制数字格式的场景（如货币金额、特定精度的测量值）非常有用。

• 适用类型: BigDecimal, BigInteger, CharSequence 以及基本数值类型 (byte, short, int, long, float, double) 及其包装类。
• 常用参数:
  • integer: 允许的最大整数位数。
  • fraction: 允许的最大小数位数。
  • message: 校验失败时的错误消息。

示例代码：

import jakarta.validation.constraints.Digits;
import java.math.BigDecimal;

public class PaymentForm {

    // 金额必须是有效的货币格式：最多 10 位整数，2 位小数
    @Digits(integer = 10, fraction = 2, message = "金额格式无效，最多 10 位整数和 2 位小数")
    private BigDecimal amount;

    // 评分：最多 1 位整数，1 位小数 (例如: 9.5)
    @Digits(integer = 1, fraction = 1, message = "评分格式无效")
    private Double rating;
    
    // getters and setters...
}

总结

注解	描述	适用数据类型
@Size	验证长度/大小范围	字符串，集合，数组，Map
@Min / @Max	验证整数范围	int, long, short, byte 等
@DecimalMin / @DecimalMax	验证高精度数值范围	BigDecimal, String, BigInteger
@Digits	验证数字的整数和小数位数	BigDecimal, BigInteger, 数值类型，String

通过组合使用这些注解，可以轻松实现对数据长度、数值范围以及数字格式的严格校验。