如何在 Java 中利用 IllegalArgumentException 实现对公开 API 入参变量的严格合法性校验-java教程-PHP中文网

illegalargumentexception应用于java公开api中参数明显非法时，需在方法入口校验数值范围、空值、枚举合法性等契约约束，并提供具体可读的错误信息。

如何在 java 中利用 illegalargumentexception 实现对公开 api 入参变量的严格合法性校验

在 Java 公开 API 设计中，IllegalArgumentException 是最常用、语义最清晰的异常类型之一，用于表明调用方传入了**明显非法或不满足契约前提的参数值**。它不是兜底错误，而是主动声明“你传错了，且这个错本不该发生”——这正契合公开 API 的契约精神：明确输入边界，快速失败，减少下游误用。

明确校验边界：只对「业务契约」而非「数据完整性」抛出 IAE

不是所有参数问题都该用 IllegalArgumentException。它的核心适用场景是：参数值本身违反方法签名所隐含的逻辑约束，例如：

数值类参数为负数（如 timeoutMs 必须 ≥ 0）
字符串为空或仅空白（如 userId 不允许 blank）
枚举/状态值不在预定义集合内（如 status 只接受 PENDING/COMPLETED）
数组或集合为 null 或长度为 0（当接口明确要求非空容器时）

⚠️ 注意：数据库主键不存在、远程服务不可达、文件路径不存在等属于运行时外部状态，应使用 IllegalStateException、IOException 或自定义业务异常，而非 IAE。

校验时机前置：在 public 方法入口立即检查，不延迟到内部逻辑

公开 API 的第一道防线必须在方法最开始执行。避免把校验逻辑藏在私有方法里，或等到计算中途才报错——这会掩盖真实入参问题，增加调试成本。

✅ 推荐写法（使用 Objects.requireNonNull + 自定义检查）：

JavaStoryDevelop

你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在

下载

public void updateUser(String userId, int age, String email) {
    if (userId == null || userId.trim().isEmpty()) {
        throw new IllegalArgumentException("userId must not be null or blank");
    }
    if (age  150) {
        throw new IllegalArgumentException("age must be between 0 and 150");
    }
    if (!isValidEmail(email)) {
        throw new IllegalArgumentException("email format is invalid");
    }
    // ✅ 此时才进入真正业务逻辑
    doUpdate(userId, age, email);
}

❌ 避免写法：先做部分处理、再校验；或把校验逻辑和业务逻辑混在一起。

异常信息要具体、可读、可定位

IAE 的消息不是给机器看的，而是给调用方开发者看的调试依据。避免模糊表述（如 "invalid parameter"），应明确指出：哪个参数、什么值、违反了什么规则。

❌ throw new IllegalArgumentException("Invalid input")
✅ throw new IllegalArgumentException("timeoutMs = -500: must be >= 0")
✅ throw new IllegalArgumentException("tags cannot be null or empty; received: " + tags)

若参数值敏感（如密码、token），可脱敏后输出类型或长度（如 "authToken is null" 而非打印明文）。

配合现代工具提升可维护性（可选但推荐）

手工写大量 if-check 易遗漏、难复用。可结合以下方式增强一致性：

Apache Commons Lang：用 Validate.notBlank()、Validate.isTrue() 等，自带清晰异常消息
Spring Framework：在 Controller 层用 @NotBlank、@Min 等注解 + @Valid，自动触发 MethodArgumentNotValidException（底层仍常包装为 IAE 语义）
Google Guava：Preconditions.checkArgument() 提供简洁断言，如 checkArgument(age >= 0, "age must be >= 0, got %s", age)