Java Thread.Builder.OfVirtual 怎么统一处理未捕获异常：线程命名、异常回调与任务验收

线上一个轻量异步任务抛了异常，线程却没有把任务结果返回给调用方，日志里只剩一行难以检索的堆栈。把线程换成虚拟线程并不会自动改变这个排查习惯：需要在创建线程时把名称和未捕获异常处理器一起配置好，再用一条可检索的日志确认回调真的执行。

先把问题缩小：异常到底从哪条线程边界出去

这个场景的关键不是“虚拟线程会不会抛异常”，而是异常有没有离开线程的 run() 边界。下面的示例刻意让任务抛出一个 IllegalStateException，并在处理器中打印线程名和订单号。这样每一项输出都能对应到一条配置。

Thread.Builder.OfVirtual builder = Thread.ofVirtual()
        .name("invoice-worker", 1)
        .uncaughtExceptionHandler((thread, error) ->
                System.err.printf("uncaught thread=%s type=%s order=%s%n",
                        thread.getName(), error.getClass().getSimpleName(), "A-20260826"));

Thread worker = builder.start(() -> {
    throw new IllegalStateException("invoice state is not READY");
});
worker.join();

这里的 join() 只是让主线程等到演示线程结束，并不会把异常重新抛给调用方。真正的验收证据是错误处理器收到的 thread 和 error 参数。

Thread.Builder.OfVirtual 适合把哪些规则放在一起

把线程名和异常处理器写在同一个 builder 上，是一种小范围的架构约束：凡是从这个 builder 创建的线程，都带有相同的可观测性入口。Oracle API 中，name(String prefix, long start) 会在每次创建线程后递增计数；uncaughtExceptionHandler 则为线程设置未捕获异常处理器。

如果任务需要把异常转成业务结果，就不要把这件事交给未捕获异常处理器。处理器更像最后一道观测边界，适合记录线程上下文、异常类型和任务标识；业务重试、补偿和状态落库仍应在任务代码或上层流程里完成。

一个容易踩坑的反例：异常被任务自己吃掉了

下面的代码不会触发 builder 上配置的处理器，因为异常已经在 run() 内被捕获。日志可能看起来“任务正常结束”，但业务实际上已经失败。

Thread.ofVirtual()
    .name("invoice-worker", 1)
    .uncaughtExceptionHandler((thread, error) ->
        System.err.println("should not be reached"))
    .start(() -> {
        try {
            throw new IllegalStateException("bad state");
        } catch (IllegalStateException ignored) {
            // 错误被吞掉，未捕获异常处理器不会收到它
        }
    });

这也是为什么验收不能只测“启动成功”。至少准备一条真正从线程体冒出的异常，并确认处理器输出了线程名、异常类型和任务标识。若业务代码本来就要处理异常，应该显式记录失败结果，别依赖最后一道兜底回调。

直接启动还是生成 ThreadFactory：边界要先定清

单个一次性任务，用 builder 的 start 最直观；同一模块要创建很多虚拟线程，则先调用 factory()，把创建规则交给需要它的执行组件。两种方式共享 builder 中已配置的名称前缀和异常处理器，但工厂本身不负责业务异常聚合。

ThreadFactory factory = Thread.ofVirtual()
        .name("invoice-worker", 10)
        .uncaughtExceptionHandler((thread, error) ->
                System.err.printf("thread=%s error=%s%n",
                        thread.getName(), error.getMessage()))
        .factory();

Thread first = factory.newThread(() -> {
    throw new IllegalArgumentException("missing invoice id");
});
first.start();
first.join();

判断这套模式是否适合当前任务

如果团队正在补齐异步任务的可观测性，这个 builder 模式值得采用；如果异常必须被调用方同步感知，单靠 UncaughtExceptionHandler 就不够，应该使用显式结果、Future 或其他任务协议。一个简单的检查清单如下：

• 是否能从线程名看出任务类型，而不是只看到一串数字？
• 是否有一条可检索的异常日志，包含异常类型和业务标识？
• 任务是否在内部吞掉了异常，导致最后一道处理器永远不执行？
• 多个创建方是否应共享同一个 ThreadFactory，还是各自需要不同的上下文？
• 异常发生后是否还要补偿、重试或改变业务状态？若要，应该把责任放在任务协议中。

常见问题

Thread.Builder.OfVirtual 是从哪个 Java 版本开始可用的？

虚拟线程在 Java 21 正式可用，Thread.ofVirtual() 和 Thread.Builder.OfVirtual 可按目标 JDK 的 API 文档核对。编译和运行环境应保持在项目声明的 Java 版本范围内。

处理器能捕获线程内部所有异常吗？

不能。只有没有在线程体内被捕获的异常才会进入未捕获异常处理器；已经被捕获、保存或转换成返回值的异常，需要由业务代码自行记录和传递。

为什么日志里没有我设置的线程名？

先确认实际启动的是这个 builder 创建的线程，而不是另一个默认线程工厂；再检查是否在创建后又调用了 setName，以及日志是否打印了传入处理器的 thread.getName()。

UncaughtExceptionHandler 可以替代重试机制吗？

不建议。它适合做兜底观测和告警入口，不知道业务是否允许重试，也不掌握幂等键、补偿顺序和最终状态。

收尾：把“线程出错”变成可核对的工程信号

Thread.Builder.OfVirtual 的价值不在于少写几行创建代码，而在于把线程命名和异常观测规则前置到创建边界。先用一条未捕获异常验证回调，再决定是否抽成共享工厂；这样出错时看到的就不只是堆栈，而是可定位的任务类型、线程名和业务标识。