在 Spring Boot 中如何使用 Assert 进行断言校验

前言

在开发 Spring Boot 应用时，确保程序逻辑的正确性和数据的有效性是非常重要的。Java 提供了内置的 assert 机制，而 Spring 框架也提供了更强大的 Assert 工具类来帮助开发者进行参数校验和状态检查。

本文将详细介绍：

• Java 原生 assert 的使用；
• Spring 提供的 Assert 类；
• 如何在 Spring Boot 中合理使用断言；
• 实际应用场景与示例；
• 最佳实践建议。

一、Java 原生 assert 简介

Java 自 J2SE 1.4 开始引入了 assert 关键字，用于在运行时对某些条件进行验证。如果断言失败（即条件为 false），则会抛出 AssertionError。

1.1 使用方式

assert condition;
assert condition : errorMessage;

1.2 示例代码

public class AssertExample {
    public static void main(String[] args) {
        int age = -5;
        assert age >= 0 : "年龄不能为负数: " + age;
        System.out.println("年龄是：" + age);
    }
}

注意：默认情况下 JVM 是禁用断言的，需要加上 -ea（enable assertions）参数启动：

java -ea AssertExample

1.3 优缺点分析

二、Spring Framework 中的 Assert 工具类

Spring 提供了 org.springframework.util.Assert 工具类，封装了一系列静态方法，专门用于参数校验和状态断言。

2.1 引入依赖

如果你使用的是 Spring Boot，默认已经包含了 Spring Core 模块，因此可以直接使用 Assert 类。

Maven 项目中可以确认是否包含以下依赖（通常不需要手动添加）：

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
</dependency>

2.2 常用方法介绍

2.3 示例代码

示例 1：检查参数非空

import org.springframework.util.Assert;

public class UserService {
    public void createUser(String username) {
        Assert.notNull(username, "用户名不能为空");
        // 创建用户逻辑
    }
}

示例 2：检查集合元素非空

import java.util.List;
import org.springframework.util.Assert;

public class OrderService {
    public void processOrders(List<String> orderIds) {
        Assert.notEmpty(orderIds, "订单ID列表不能为空");
        Assert.noNullElements(orderIds, "订单ID中不能包含null值");
        // 处理订单逻辑
    }
}

示例 3：检查状态

public class PaymentService {
    private boolean initialized = false;

    public void init() {
        // 初始化逻辑
        initialized = true;
    }

    public void pay() {
        Assert.state(initialized, "支付服务未初始化");
        // 支付逻辑
    }
}

三、在 Spring Boot 中的最佳使用场景

3.1 Controller 层参数校验

虽然 @Valid 和 @RequestBody 注解更适合做请求参数校验，但在业务逻辑处理前也可以使用 Assert 来进一步确保参数有效。

@RestController
@RequestMapping("/users")
public class UserController {

    @PostMapping
    public ResponseEntity<Void> createUser(@RequestBody UserDto userDto) {
        Assert.notNull(userDto, "用户信息不能为空");
        Assert.hasText(userDto.getUsername(), "用户名不能为空");

        // 调用 service 保存用户
        return ResponseEntity.ok().build();
    }
}

3.2 Service 层参数或状态校验

这是最推荐使用 Assert 的地方，可以避免非法参数传递到核心业务逻辑中。

@Service
public class OrderService {

    public void placeOrder(Order order) {
        Assert.notNull(order, "订单不能为空");
        Assert.notNull(order.getItems(), "订单商品列表不能为空");

        if (order.getItems().isEmpty()) {
            throw new IllegalArgumentException("订单必须包含至少一个商品");
        }

        // 下单逻辑
    }
}

3.3 Repository 层数据一致性校验（可选）

对于数据库操作之前的数据一致性检查，也可以加入断言辅助判断。

@Repository
public class UserRepository {

    public void save(User user) {
        Assert.notNull(user, "用户实体不能为空");
        Assert.hasText(user.getEmail(), "邮箱不能为空");

        // 执行保存操作
    }
}

四、与 Bean Validation 的对比

结论：

• @Valid 更适合前端传参的统一校验；
• Assert 更适合在 Service、Repository 或内部逻辑中进行细粒度的参数或状态检查。

五、最佳实践建议

1. 不要替代正式异常处理：断言用于“不应该发生”的情况，而不是预期中的错误。
2. 避免在公有 API 中使用 assert：因为原生 assert 可能被关闭，行为不可控。
3. 优先使用 Spring 的 Assert 类：它抛出的是 IllegalArgumentException 或 IllegalStateException，易于捕获和处理。
4. 结合日志记录：在断言失败时记录详细信息，有助于排查问题。
5. 断言信息要清晰明确：便于定位问题，如 "用户名不能为空" 比 "invalid input" 更好。

六、总结

在 Spring Boot 项目中，assert 和 Assert 类是两个非常实用的工具，可以帮助我们在开发过程中尽早发现问题，提升代码健壮性。尽管它们不具备完整的校验能力，但作为轻量级的防御性编程手段，非常适合用于中间层的参数和状态检查。

掌握并合理使用这些断言机制，不仅能提高代码质量，也能减少运行时错误的发生。

参考文档：

• Spring Framework Assert 文档
• Java assert 官方教程