ValidX vs Google Guava Preconditions：验证 vs 断言

ValidX vs Google Guava Preconditions：验证 vs 断言

📋 目录

• 概述
• 快速对比表
• 一、核心哲学：断言 vs 验证
• 二、API 形态对比
• 三、失败方式：异常中断 vs 错误收集
• 四、空值语义对比
• 五、消息与国际化
• 六、性能与依赖
• 七、实战对照：同一个注册接口
• 八、协作：什么时候用谁
• 使用场景建议
• 总结

概述

在 Java 世界里，"先检查、再执行"几乎是每个方法的第一行。这件事有两个主流工具：

• Google Guava Preconditions：com.google.common.base.Preconditions，提供 checkArgument、checkNotNull、checkState 等静态方法，条件不满足立刻抛异常；
• ValidX：一个面向中国业务场景的开源验证库，既提供 @NotBlank 这类注解，也提供 ValidX.init() 链式 API，条件不满足收集错误，由业务决定如何处理。

两者都做"前置检查"，但哲学截然不同——这正是本文标题"验证 vs 断言"要讲清楚的事：Guava 是断言，ValidX 是验证。断言管的是"我的代码假设错了"（开发者违约），验证管的是"用户给的数据不合法"（输入不合格）。搞混它们，代码会变得要么过度防御、要么对用户输入毫无招架。

快速对比表

一、核心哲学：断言 vs 验证

1.1 断言（Guava）：假设错了，程序就别跑了

Preconditions.checkArgument 的隐含语义是：这个条件必须为真，如果为假，说明调用方违反了约定，即程序有 bug。所以它选择 fail-fast——立刻抛异常、立刻停止，把问题暴露在最靠近源头的地方。

// 库的内部实现：假设调用方传了合法参数
public BigDecimal calculateInterest(BigDecimal principal, double rate) {
checkArgument(principal != null && principal.signum() >= 0, "本金不能为负: %s", principal);
checkArgument(rate >= 0 && rate <= 1, "利率必须在 [0,1] 区间: %s", rate);
// … 从这里开始，假设前提都成立
}

“断言失败” ≈ “我的代码有 bug”——这是开发者之间的契约。

1.2 验证（ValidX）：数据不对，提示用户改

ValidX 的隐含语义是：这个输入来自外部（用户、上游系统、文件导入），它不合法是常态，需要被当成业务事件处理——要么返回错误提示让用户重填，要么记录日志、跳过这一行继续处理。

// 业务入口：验证用户提交的数据
ValidX v = ValidX.init()
.field("手机号").notEmpty().isChinesePhone(phone)
.field("邮箱").notEmpty().isEmail(email)
.field("QQ（可选）").allowNull().isQQ(qq);

if (!v.passed()) {
// 错误累积成列表，交给 Controller 返回给前端
throw new ValidationException(v.getErrors());
}

“验证失败” ≈ “用户输入不合格”——这是应用与用户之间的契约。

1.3 一张图看懂区别

一句话记忆：断言失败是你的问题，验证失败是用户的问题。

二、API 形态对比

2.1 Guava：四个静态方法打天下

import static com.google.common.base.Preconditions.*;

// 条件必须为真，否则 IllegalArgumentException
checkArgument(user.getAge() >= 18, "年龄必须大于等于 18：%s", user.getAge());

// 引用不能为 null，否则 NullPointerException（返回原对象便于链式）
User u = checkNotNull(user, "user 不能为 null");

// 状态必须为真，否则 IllegalStateException
checkState(connection.isOpen(), "连接未打开");

// 下标必须在 [0, size) 内，否则 IndexOutOfBoundsException
checkElementIndex(index, list.size(), "index");

2.2 ValidX：一条链搞定多个字段

import io.github.vipxieliang.validx.chain.ValidX;

ValidX v = ValidX.init()
.field("手机号").notEmpty().isChinesePhone(phone)
.field("身份证").notEmpty().isChineseIdCard(idCard)
.field("金额").notNull().isIn(amount, new String[]{"USD", "CNY"})
.field("QQ（可选）").allowNull().isQQ(qq);

if (!v.passed()) {
System.out.println(v.getErrorMessage()); // "手机号: …, 身份证: …"
}

核心差异：Guava 是"一次一个断言"，N 个条件要 N 行 + N 个异常分支；ValidX 是"一条链声明全部规则"，错误自然累积，无需逐个 catch。

三、失败方式：异常中断 vs 错误收集

这是两者最直观的差异，直接影响代码控制流。

3.1 Guava：抛异常 = 中断执行

public void transfer(Account from, Account to, BigDecimal amount) {
checkArgument(amount != null && amount.signum() > 0, "转账金额必须为正: %s", amount);
checkState(from.getBalance().compareTo(amount) >= 0, "余额不足");

// 走到这里，所有前提都成立，不需要再判断
from.debit(amount);
to.credit(amount);
}

好处：后续代码无需任何 if，因为前提已在入口断言；坏处：第一个失败即终止，拿不到全部问题。

3.2 ValidX：收集错误 = 一次告诉你所有问题

ValidX v = ValidX.init()
.field("用户名").notEmpty().isAlphaNumber(username)
.field("邮箱").notEmpty().isEmail(email)
.field("密码").notEmpty().isPassword(password, 8);

if (!v.passed()) {
// 三个字段的问题一次全拿到
List<String> errors = v.getErrors();
// ["用户名: 值不能为空", "邮箱: 邮箱格式不正确", "密码: 长度必须在8到20之间"]
}

好处：一次交互反馈全部问题（对用户体验尤其重要——没人想改完邮箱又被告知密码也错了）；坏处：需要显式判断 passed()。

3.3 什么时候异常反而更好？

当"校验失败 = 程序 bug"时，异常（断言）就是正确的选择。一个典型反例是把用户输入校验写成 checkArgument——一旦抛错，Spring 默认返回 500 而不是 400，前端拿到的是"服务器内部错误"而不是"邮箱格式不对"。错误的数据流向错误的处理通道，是断言/验证混用的最大坑。

四、空值语义对比

// Guava：可选字段要手动 if 包裹
if (qq != null) {
checkArgument(qq.matches("^[1-9]\\\\d{4,10}$"), "QQ 格式不正确");
}

// ValidX：allowNull() 声明式表达"可选"
ValidX.init().field("QQ").allowNull().isQQ(qq);

关键认知：ValidX 链式校验默认允许 null/空（因为 Map/JSON 中字段缺失返回 null 是常态），必须用 notNull()/notEmpty() 显式收紧；Guava 则是"默认严格"，checkNotNull 是最高频方法。两者方向相反，迁移时最容易踩坑。

五、消息与国际化

// Guava：消息靠手写，面向调试
checkArgument(age >= 18, "age 不合法: %s", age);

// ValidX：字段标签 + 语言切换，面向用户
ValidX v = ValidX.init()
.withLocale(Locale.ENGLISH)
.field("Age").notEmpty().isAge(age, 0, 120); // 错误消息自动为英文

对出海应用来说，ValidX 的"一套校验规则、多语言错误消息"能省掉大量硬编码文案。

六、性能与依赖

• Guava Preconditions：本身是纯静态方法调用，开销极小；但为了用它引入整个 Guava（数 MB、几十个模块），对只想要"几个检查方法"的项目是杀鸡用牛刀。轻量替代：JDK 自带 Objects.requireNonNull + Objects.checkIndex（Java 9+）。
• ValidX 链式 API：一次实例一个校验器，无反射（注解方式才涉及反射），链式场景开销可忽略；单一依赖、约 300KB，且内置 100+ 业务验证器（身份证、手机号、银行卡……）——这是 Guava 给不了的。

性能建议：两者在"判断一个布尔值"上的开销都可忽略，真正的性能差异来自引入了多少你根本用不上的代码。

七、实战对照：同一个注册接口

用同一个"用户注册"场景，看两种思路的完整落地：

7.1 Guava 写法：断言风格

public void register(UserDTO dto) {
// 每个条件一个断言，第一个失败即抛异常
checkArgument(dto != null, "dto 不能为 null");
checkArgument(dto.getUsername() != null && !dto.getUsername().isBlank(),
"用户名不能为空");
checkArgument(dto.getEmail() != null && EMAIL_PATTERN.matcher(dto.getEmail()).matches(),
"邮箱格式不正确: %s", dto.getEmail());
checkArgument(dto.getPhone() == null || PHONE_PATTERN.matcher(dto.getPhone()).matches(),
"手机号格式不正确: %s", dto.getPhone());

userService.create(dto);
// 问题：用户改完用户名，又被告知邮箱也错了（一次只能报一个错）
}

7.2 ValidX 写法：验证风格

public void register(UserDTO dto) {
ValidX v = ValidX.init()
.field("用户名").notEmpty().isAlphaNumber(dto.getUsername())
.field("邮箱").notEmpty().isEmail(dto.getEmail())
.field("手机号").allowNull().isChinesePhone(dto.getPhone()); // 可选字段

if (!v.passed()) {
// 一次返回全部错误，直接拼进响应体
throw new ValidationException(v.getErrors());
}

userService.create(dto);
}

直观差异：

• Guava 版每多一个字段就要多写一行正则 + 一个异常；ValidX 版是字段标签 + 现成验证器；
• 手机号/身份证这类中国业务格式，Guava 没有内置，必须手写正则；ValidX 直接 isChinesePhone/isChineseIdCard；
• Guava 一次只能报一个错，ValidX 一次报全部。

八、协作：什么时候用谁

正确的姿势不是二选一，而是各司其职：

混合使用示例：业务入口用 ValidX 验证用户输入，通过后进入内部方法用 Guava 断言内部契约。

public void submitOrder(OrderRequest req) {
// 第一层：用户输入验证（ValidX，错误返回给前端）
ValidX v = ValidX.init()
.field("商品ID").notEmpty().isAlphaNumber(req.getProductId())
.field("数量").notNull().isIn(req.getQuantity(), new String[]{"1", "2", "3", "4", "5"});
if (!v.passed()) {
throw new ValidationException(v.getErrors());
}

// 第二层：内部契约断言（Guava，违约即 bug）
checkState(inventory.isLocked(req.getProductId()), "库存未锁定，流程状态异常");
checkArgument(orderService.calcPrice(req).signum() > 0, "计算出的价格非法");

orderService.submit(req);
}

使用场景建议

总结

• Guava Preconditions 是断言：面向开发者契约，失败即抛异常（fail-fast），消息是给调试看的。它的价值在于把"前提条件"压缩到方法入口，让后续代码免于判断。
• ValidX 是验证：面向用户输入，失败收集错误（可聚合、可多语言、可带字段标签），消息是给用户看的。它的价值在于用声明式链式 API 覆盖中国业务场景的海量格式规则。
• 别混用：把用户输入校验写成 checkArgument，会把"输入不合法"误报成"服务器错误"；把内部契约写成业务验证，又会让 bug 被"友好提示"掩盖。
• 最佳实践是分层协作：入口用 ValidX 验证数据，内部用 Guava 断言契约——验证管用户，断言管自己。

关联阅读：本系列对比文章《ValidX vs Apache Commons Validator：功能与性能对比》《ValidX vs Hutool Validator：专业框架 vs 工具库》，帮你把 ValidX 放进整个 Java 验证生态中选型。