(Guava 译文系列)先决条件

先决条件

Guava 提供了大量的判断先决条件的工具。我们强烈建议将之通过 static import 引入。

每一种方法,都有以下三种变体形式: 1. 无额外入参。任何抛出的异常都不包含错误描述。 2. 存在一个Object参数。任何抛出异常的错误描述都通过Object.toString()获取。 3. 存在一个String参数加数个额外的Object参数。上述参数表现为类似 printf 方法的使用形式(当然更高效且与 GWT 兼容),但只支持%s指示器。 - 注意:checkNotNullcheckArgumentcheckState有大量的重载采用基本类型和Object类型结合的方式实现,而不是采用 varargs 数组。这可以使调用在大多数情况下无需进行自动装箱与 varargs 数组分配的工作。

上述第三中变体的示例:

1
2
checkArgument(i >= 0, "Argument was %s but expected nonnegative", i);
checkArgument(i < j, "Expected i < j, but %s >= %s", i, j);

方法签名(不包括附加入参) 描述 错误抛出的异常
checkArgument(boolean) 检查输入的booleantrue。用于校验方法的输入参数 IllegalArgumentException
checkNotNull(T) 检查值不为 null,并直接返回该值,因此本方法可直接用与行内嵌 NullPointerException
checkState(boolean) 检查对象的状态,不依赖于方法参数。例如,Iterator可以使用本方法来确保在调用remove之前,next先被调用。 IllegalStateException
checkElementIndex(int index, int size) 检查index是一个在给定长度的 List、String 或 array 中有效的元素。一个元素的 index 可能会从 0(包含)至size不包含)。你无需传入 List,String 或 array,只需传入他们的大小。本方法会将 index 返回。 IndexOutOfBoundsException
checkPositionIndex(int index, int size) 检查index是一个在给定长度的 List、String 或 array 中有效的位置。一个位置的 index 可能会从 0(包含)至size包含)。你无需传入 List,String 或 array,只需传入他们的大小。本方法会将 index 返回。 IndexOutOfBoundsException
checkPositionIndexes(int start, int end, int size) 检查给定的范围[start, end)是一个在给定长度的 List、String 或 array 中有效的子范围。本方法包含一个给定的错误信息。 IndexOutOfBoundsException

我们更喜欢使用我们自己的先决条件检查工具而不是例如 Apache Commons 提供的比较工具类,是因为: - 通过 static import 后,Guava 的方法更清晰、准确。checkNotNull的名字清晰地告知了他会做什么,且会抛出什么样的异常。 - checkNotNull会在检查完毕后返回输入参数,这允许在构造函数中使用简单的单行实现:this.field = checkNotNull(field);。 - 简单、多样(支持 varargs)的异常信息。(正是这一项优势,因此我们更倾向于使用checkNotNull而不是Objects.requireNonNull

我们建议你将多个先决条件检查语句分开多行书写,这可以帮助你在 debug 时找到究竟是哪一个先决条件失败。此外,你也应提供有帮助性的错误信息,这能让处于独立行的先决条件检查更简单。