📦 断言工具-Assert

Assert 是 Hutool 提供的断言工具类，用于验证对象或值是否符合规定，否则抛出异常。它提供了丰富的断言方法，常用于变量检查、参数验证等场景，可以在生产环境中使用。

🔧 核心功能

功能分类	主要方法	描述
布尔断言	isTrue()、isFalse()	断言布尔值是否为真或假
空值断言	isNull()、notNull()	断言对象是否为 null 或非 null
空集合断言	notEmpty()	断言数组、集合、Map、字符串是否非空
空白字符串断言	notBlank()	断言字符串是否非空白
包含关系断言	notContain()	断言字符串是否不包含子串
数组元素断言	noNullElements()	断言数组是否不包含 null 元素
类型断言	isInstanceOf()、isNotInstanceOf()、isAssignable()	断言对象类型
状态断言	state()	断言对象状态
下标断言	checkIndex()	断言下标是否合法
范围断言	checkBetween()	断言值是否在指定范围内
相等断言	equals()、notEquals()	断言两个对象是否相等

🎯 主要方法示例

1. 布尔断言

// 断言布尔值为真，否则抛出 IllegalArgumentException
Assert.isTrue(1 > 0, "值必须大于0");

// 断言布尔值为真，使用 Supplier 提供异常信息
Assert.isTrue(1 > 0, () -> new IllegalArgumentException("值必须大于0"));

// 断言布尔值为假，否则抛出 IllegalArgumentException
Assert.isFalse(1 < 0, "值必须小于0");

// 断言布尔值为假，使用 Supplier 提供异常信息
Assert.isFalse(1 < 0, () -> new IllegalArgumentException("值必须小于0"));

2. 空值断言

// 断言对象为 null，否则抛出 IllegalArgumentException
Assert.isNull(null, "对象必须为null");

// 断言对象为 null，使用 Supplier 提供异常信息
Assert.isNull(null, () -> new IllegalArgumentException("对象必须为null"));

// 断言对象非 null，否则抛出 IllegalArgumentException
Assert.notNull(new Object(), "对象不能为空");

// 断言对象非 null，使用 Supplier 提供异常信息
Assert.notNull(new Object(), () -> new IllegalArgumentException("对象不能为空"));

// 断言对象非 null，并返回该对象
Object obj = Assert.notNull(new Object(), "对象不能为空");

3. 空集合断言

// 断言数组非空
String[] array = {"a", "b", "c"};
Assert.notEmpty(array, "数组不能为空");

// 断言集合非空
List<String> list = Arrays.asList("a", "b", "c");
Assert.notEmpty(list, "集合不能为空");

// 断言 Map 非空
Map<String, String> map = new HashMap<>();
map.put("key", "value");
Assert.notEmpty(map, "Map不能为空");

// 断言字符串非空
Assert.notEmpty("hello", "字符串不能为空");

4. 空白字符串断言

// 断言字符串非空白（null、空串或只包含空白符）
Assert.notBlank("hello", "字符串不能为空白");

// 断言字符串非空白，使用 Supplier 提供异常信息
Assert.notBlank("hello", () -> new IllegalArgumentException("字符串不能为空白"));

5. 包含关系断言

// 断言字符串不包含子串
Assert.notContain("hello world", "test", "字符串不能包含'test'");

// 断言字符串不包含子串，使用 Supplier 提供异常信息
Assert.notContain("hello world", "test", () -> new IllegalArgumentException("字符串不能包含'test'"));

6. 数组元素断言

// 断言数组不包含 null 元素
String[] array = {"a", "b", "c"};
Assert.noNullElements(array, "数组不能包含null元素");

// 断言数组不包含 null 元素，使用 Supplier 提供异常信息
Assert.noNullElements(array, () -> new IllegalArgumentException("数组不能包含null元素"));

7. 类型断言

// 断言对象是指定类型的实例
Assert.isInstanceOf(String.class, "hello", "对象必须是String类型");

// 断言对象不是指定类型的实例
Assert.isNotInstanceOf(Integer.class, "hello", "对象不能是Integer类型");

// 断言子类继承自父类或实现了接口
Assert.isAssignable(Number.class, Integer.class, "Integer必须是Number的子类");

8. 状态断言

// 断言对象状态，当表达式为 false 时抛出 IllegalStateException
boolean isActive = true;
Assert.state(isActive, "对象必须处于激活状态");

// 断言对象状态，使用 Supplier 提供异常信息
Assert.state(isActive, () -> "对象必须处于激活状态");

9. 下标断言

// 断言下标是否合法（0 <= index < size）
int index = 1;
int size = 5;
Assert.checkIndex(index, size, "下标越界");

// 断言长整型下标是否合法
long longIndex = 1L;
long longSize = 5L;
Assert.checkIndex(longIndex, longSize, "下标越界");

10. 范围断言

// 断言 int 值是否在指定范围内（包含边界）
int value = 5;
int min = 1;
int max = 10;
Assert.checkBetween(value, min, max, "值必须在1到10之间");

// 断言 long 值是否在指定范围内（包含边界）
long longValue = 5L;
long longMin = 1L;
long longMax = 10L;
Assert.checkBetween(longValue, longMin, longMax, "值必须在1到10之间");

// 断言 double 值是否在指定范围内（包含边界）
double doubleValue = 5.5;
double doubleMin = 1.0;
double doubleMax = 10.0;
Assert.checkBetween(doubleValue, doubleMin, doubleMax, "值必须在1.0到10.0之间");

// 断言 Number 值是否在指定范围内（包含边界）
Number number = 5;
Number numMin = 1;
Number numMax = 10;
Assert.checkBetween(number, numMin, numMax, "值必须在1到10之间");

11. 相等断言

// 断言两个对象不相等
Assert.notEquals("a", "b", "两个对象必须不相等");

// 断言两个对象相等
Assert.equals("a", "a", "两个对象必须相等");

📋 注意事项

1. 异常类型：

   • 大多数断言方法抛出 IllegalArgumentException
   • state() 方法抛出 IllegalStateException
   • checkIndex() 方法抛出 IndexOutOfBoundsException

2. 自定义异常：

   • 所有断言方法都支持通过 Supplier 接口提供自定义异常
   • 可以根据需要抛出特定类型的异常

3. 返回值：

   • 部分断言方法返回被检查的对象，支持链式调用
   • 例如：Assert.notNull(obj).doSomething()

4. 生产环境使用：

   • 与 JDK 断言不同，Assert 类可以在生产环境中使用
   • 可以用于参数验证、状态检查等场景

5. 性能考虑：

   • 断言会增加一定的性能开销
   • 对于频繁调用的代码，建议谨慎使用断言

💡 最佳实践

1. 参数验证：

   public void doSomething(String param1, List<String> param2) {
       Assert.notBlank(param1, "param1不能为空");
       Assert.notEmpty(param2, "param2不能为空");
       // 业务逻辑
   }
   

2. 状态检查：

   public void updateStatus() {
       Assert.state(isActive(), "对象必须处于激活状态才能更新");
       // 更新状态
   }
   

3. 链式调用：

   String result = Assert.notBlank(getName())
       .toUpperCase();
   

4. 自定义异常：

   Assert.isTrue(condition, () -> new BusinessException("业务异常信息"));
   

通过 Assert 工具类，可以大幅简化参数验证和状态检查代码，提高代码的可读性和可维护性，同时确保系统的健壮性。