Google工具包Guava——代码校验Preconditions：

一、Preconditions工具类介绍

Preconditions是guava提供的用于进行代码校验的工具类，其中提供了许多重要的静态校验方法，用来简化我们工作或开发中对代码的校验或预处理。

所有的14个静态方法，如下：

（1）checkArgument(boolean expression)：用来校验表达式是否为真，一般用作方法中校验参数
 
（2）checkArgument(boolean expression, @Nullable Object errorMessage)：校验表达式是否为真，不为真时显示指定的错误信息。
 
（3）checkArgument(boolean expression, @Nullable String errorMessageTemplate, @Nullable Object... errorMessageArgs)：校验表达式是否为真，不为真时显示错误信息，错误信息中允许使用占位符。
 
（4）checkState(boolean expression)：校验表达式是否为真，一般用作校验方法返回是否为真。
 
（5）checkState(boolean expression, @Nullable Object errorMessage)：当表达式为假的时候，显示指定的错误信息。
 
（6）checkState(boolean expression,@Nullable String errorMessageTemplate,@Nullable Object... errorMessageArgs)：允许在错误信息中使用占位符。
 
（7）checkNotNull(T reference)：校验对象是否为空。
 
（8）checkNotNull(T reference, @Nullable Object errorMessage)：对象为空时显示指定的错误信息。
 
（9）checkNotNull(T reference, @Nullable String errorMessageTemplate,@Nullable Object... errorMessageArgs)：允许在错误信息中使用占位符。
 
（10）checkElementIndex( int index, int size, @Nullable String desc)：校验元素的索引值是否有效，index大于等于0小于size，在无效时显示错误描述信息。
 
（11）checkElementIndex(int index, int size)：错误描述信息为“index”
 
（12）checkPositionIndex(int index, int size, @Nullable String desc)：校验元素的索引值是否有效，index大于等于0小于等于size，在无效时显示错误描述信息。
 
（13）checkPositionIndex(int index, int size)：错误描述信息为“index”
 
（14）checkPositionIndexes(int start, int end, int size)：校验大于等于start，小于end的list的长度是否为size。

二、Preconditions详细使用

前置函数特征

目前的前置校验方法有如下特征:

须需要, 下面例子中的checkArgument函数可以替换成任何一个前置条件校验函数

这些前置方法一般接受一个布尔表达式作为入参，并判断表达是否为true, 格式如:

Preconditions.checkArgument(a>1)
// 如果表达式为false, 抛出IllegalArgumentException

除了用于判断的布尔表达式之外, 前置方法可以接受一个额外的Object作为入参, 在抛出异常的时候, 把Object.toString()作为异常信息, 如:

public enum ErrorDetail {
    SC_NOT_FOUND("404", "Resource could not be fount");
    // 省略部分内容
    @Override
    public String toString() {
        return "ErrorDetail{" + "code='" + code + '\'' + ", description='" + description + '\'' + '}';
    }
}
@Test
public void testCheckArgument() {
    Preconditions.checkArgument(1 > 2, ErrorDetail.SC_NOT_FOUND);
}
// 结果如下:
// java.lang.IllegalArgumentException: ErrorDetail{code='404', description='Resource could not be fount'}

Guava的前置表达式还支持类似printf函数那样的格式化输出错误信息, 只不过出于兼容性和性能的考虑, 只支持使用%s指示符格式化字符串, 不支持其他类型. 如:

int i=-1;
checkArgument(i >= 0, "Argument was %s but expected nonnegative", i);
// 结果如下:
// java.lang.IllegalArgumentException: Argument was -1 but expected nonnegative

前置条件函数介绍

须注意的是, 下面介绍的checkArgument,?checkArgument,?checkState函数都有三个对应的重载函数，分别对应前文所述的三种特征, 下文不会三种函数都介绍, 只介绍标准格式的前置条件函数. 以checkArgument函数为例, 三个重载函数分别是(忽略函数体):

public static void checkArgument(boolean expression);
public static void checkArgument(boolean expression, @Nullable Object errorMessage);
public static void checkArgument(boolean expression,@Nullable String errorMessageTemplate,@Nullable Object... errorMessageArgs)

checkArgument 函数的签名如下:

public static void checkArgument(boolean expression);

入参是一个布尔表达式, 函数校验这个表达式是否为true, 如果为false, 抛出IllegalArgumentException. 例子如下:

@Test
public void testCheckArgument() {
    Preconditions.checkArgument(1 > 2);
}

checkNotNull 这是个泛型函数, 函数签名如下:

public static <T> T checkNotNull(T reference);

入参是个任意类型的对象, 函数校验这个对象是否为null, 如果为空, 抛出NullPointerException, 否则直接返回该对象, 所以checkNotNull的用法就比较有趣, 可以在调用setter方法前作前置校验. 例子如下:

PreconditionTest caller = new PreconditionTest();
caller.setErrorDetail(Preconditions.checkNotNull(ErrorDetail.SC_INTERNAL_SERVER_ERROR));

checkState 函数签名如下:

public static void checkState(boolean expression);

看着这个函数, 我个人感觉很奇怪: 这个函数和checkNotNull函数功能非常相似, 实现也基本一样, 都是判断表达式是否为true, 只是抛出的异常不一样而已, 是否有必要开发这个函数. 两个函数的实现如下:

public static void checkArgument(boolean expression) {
  if (!expression) {
    throw new IllegalArgumentException();
  }
}
public static void checkState(boolean expression) {
  if (!expression) {
    throw new IllegalStateException();
  }
}

看着这个函数, 我个人感觉很奇怪: 这个函数和checkNotNull函数功能非常相似, 实现也基本一样, 都是判断表达式是否为true, 只是抛出的异常不一样而已, 是否有必要开发这个函数. 两个函数的实现如下:

public static void checkArgument(boolean expression) {
  if (!expression) {
    throw new IllegalArgumentException();
  }
}
public static void checkState(boolean expression) {
  if (!expression) {
    throw new IllegalStateException();
  }
}

此外, 因为这两个函数相当类似, 就不展示相应例子了.

checkElementIndex 函数签名如下:

public static int checkElementIndex(int index, int size);

这个函数用于判断指定数组, 列表, 字符串的下标是否越界,?index是下标,?size是数组, 列表或字符串的长度, 下标的有效范围是[0,数组长度)?即?0<=index<size. 如果数组下标越界(即index<0 或者?index>=size), 那么抛出IndexOutOfBoundsException异常, 否则返回数组的下标, 也就是index. 例子如下:

Preconditions.checkElementIndex("test".length(), "test".length());
// 运行结果:
// 抛出异常: java.lang.IndexOutOfBoundsException: index (4) must be less than size (4)
Assert.assertEquals(3, Preconditions.checkElementIndex("test".length() - 1, "test".length()));
// 运行结果:
// 通过

checkPositionIndex 函数的签名如下:

public static int checkPositionIndex(int index, int size);

这个函数和checkElementIndex非常类似, 连Guava wiki的说明也基本一致(只有一个单词不同), 除了一点,?checkElementIndex函数的下标有效范围是[0, 数组长度), 而checkPositionIndex函数的下标有有效范围是[0, 数组长度], 即0<=index<=size. 例子如下:

checkPositionIndexes 函数的签名如下:

public static void checkPositionIndexes(int start, int end, int size);

这个函数是用于判断[start,end]这个范围是否是个有效范围, 即[start, end]?是否在[0, size]?范围内(如果[start, end]?和[0, size]相同, 也认为在范围内), 如果不在, 则抛出IndexOutOfBoundsException异常. 例子如下:

Preconditions.checkPositionIndexes(1, 3, 2);
// 运行结果:
// 抛出异常: java.lang.IndexOutOfBoundsException: end index (3) must not be greater than size (2)
Preconditions.checkPositionIndexes(0, 2, 2);
// 运行结果:
// 校验通过

前置条件在实际项目的应用

前置条件在检验条件不成交的时候抛的异常类型虽说是合情合理(比如,?checkArgument函数抛出IllegalArgumentException), 但是对于业务系统来说, 你抛出个IllegalArgumentException或者NullPointerException, 接口调用方对于这个异常摸不着头脑, 虽说只是正常的数据问题, 还是很容易觉得接口提供方服务出了问题, 甚至还会被质疑技术不过硬. 咱们又不是底层组件, 抛个NPE, 着实是不成体统. 基于各种有的没的的原因, 我们的业务系统在使用前置条件的时候进行了封装, 将前置条件抛出的异常进行了转换, 换成正常的业务异常, 提供完整的异常信息, 代码如下:

// 封装代码:
public final class AssertUtils {
        /**
        * 检查条件表达式是否为真
        *
        * @param expression 条件表达式
        * @param errDetailEnum 错误码
        * @param msgTemplate 错误消息模板
        * @param vars 占位符对应变量
        * @throws BkmpException 条件表达式结果为假
        */
    public static void checkArgument(boolean expression, ErrDetailEnum errDetailEnum, String msgTemplate,
                                        Object... vars) {
        try {
            Preconditions.checkArgument(expression);
        } catch (IllegalArgumentException e) {
            throw new BkmpException(errDetailEnum, msgTemplate, vars);
        }
    }
        /**
        * 检查条件表达式是否为假
        *
        * @param expression 条件表达式
        * @param errDetailEnum 错误码
        * @param msgTemplate 错误消息模板
        * @param vars 占位符对应变量
        * @throws BkmpException 条件表达式结果为假
        */
    public static void checkArgumentNotTrue(boolean expression, ErrDetailEnum errDetailEnum, String msgTemplate,
                                            Object... vars) {
        try {
            Preconditions.checkArgument(!expression);
        } catch (IllegalArgumentException e) {
            throw new BkmpException(errDetailEnum, msgTemplate, vars);
        }
    }
}
// 省略其他部分的封装
// 调用例子:
AssertUtils.checkArgument(merchantEntity.exist(), ErrDetailEnum.DATA_NOT_EXIT, "商户不存在");