Java Thread.Builder.OfVirtual 设置线程异常处理器

使用 Thread.Builder.OfVirtual 创建虚拟线程时，可以直接在 builder 上调用 uncaughtExceptionHandler。这个处理器会成为新线程的线程级未捕获异常处理器；任务没有自行捕获异常并结束时，JVM 会把线程对象和异常对象交给它。配置点应放在创建线程或线程工厂之前，而不是把异常处理逻辑散落到每个 Runnable 中。

先确定异常处理器挂在哪一层

Java 的查找顺序是线程自己的处理器、线程组处理器，最后才是默认未捕获异常处理器。对虚拟线程来说，最容易控制的是第一层：用 Thread.Builder.OfVirtual 在创建线程前绑定处理器。这样既不会改变进程中其他线程的默认策略，也能让一组由同一 builder 创建的线程拥有一致的记录入口。

需要注意“未捕获”这个边界：如果任务内部写了 try/catch，并在 catch 中处理了异常，处理器不会被调用；如果处理器自己的 uncaughtException 再抛出异常，JVM 会忽略这个异常，所以处理器里应尽量只做安全的日志和指标记录。

用 uncaughtExceptionHandler 绑定虚拟线程

下面的示例把线程名写进日志，便于将异常和任务实例对应起来。uncaughtExceptionHandler 的参数是 Thread.UncaughtExceptionHandler，可以使用 lambda；调用后仍返回 builder，因此后续可以继续设置线程名。

import java.util.concurrent.atomic.AtomicInteger;

public class VirtualThreadErrorLog {
    public static void main(String[] args) throws InterruptedException {
        AtomicInteger errorCount = new AtomicInteger();
        Thread.UncaughtExceptionHandler handler = (thread, error) -> {
            // 这里只记录线程与异常；不要在处理器里尝试恢复业务状态。
            int count = errorCount.incrementAndGet();
            System.err.printf("uncaught[%d] thread=%s type=%s message=%s%n",
                    count, thread.getName(), error.getClass().getName(), error.getMessage());
        };

        Thread.Builder.OfVirtual builder = Thread.ofVirtual()
                // builder 会把处理器配置复制到之后创建的虚拟线程。
                .name("order-worker-")
                .uncaughtExceptionHandler(handler);

        Thread worker = builder.start(() -> {
            // 这个异常没有在任务内部捕获，会交给 handler。
            throw new IllegalStateException("order state is incomplete");
        });
        worker.join(); // 等待线程结束，避免主线程提前退出。
    }
}

这里的关键不是把异常“吞掉”，而是把异常记录集中到一个边界。worker.getUncaughtExceptionHandler() 可以用来确认该线程拿到的正是 handler；检查通过后再进入业务创建流程，定位问题会比依赖全局默认处理器更直接。

确认 start、unstarted 和 factory 的继承边界

同一个 builder 可以直接 start 任务，也可以先得到未启动线程，或者转换为 ThreadFactory。三者复用 builder 中已设置的命名与异常处理器配置，但每次调用仍然创建独立的线程对象。不要把一个已经启动的线程再次提交给工厂，也不要把 unstarted 线程误认为已经开始执行。

若工厂交给其他组件使用，应把处理器设计成线程安全、低阻塞的实现。虚拟线程数量可以很多，处理器里同步写慢速外部系统，反而可能放大故障时的压力。

把日志与兜底策略放在处理器里

处理器适合做最后一道观测入口：记录线程名、异常类型、关联标识和必要的堆栈，然后让线程自然结束。它不适合替代业务层的重试、事务回滚或用户提示。若某类异常需要恢复，应在任务内部或更上层显式设计恢复路径。

上线前可按这张清单检查：是否只记录真正未捕获的异常；日志输出是否不会再次抛错；是否避免把敏感参数直接拼入日志；默认处理器是否仍保留给未配置线程；使用 factory 时是否确认下游组件不会改变线程级处理器。

常见问题

任务内部 catch 住异常后还会触发处理器吗？

不会。只有异常离开线程任务、导致线程因未捕获异常结束时，线程级处理器才会收到回调。

可以在处理器里重新抛出异常让主线程感知吗？

不应这样设计。处理器中的异常会被 JVM 忽略；需要让主线程感知时，应通过任务结果、显式状态或其他并发通信机制传递。

虚拟线程和平台线程的配置方法一样吗？

两者都实现 builder 的异常处理器配置，但本文只讨论 Thread.ofVirtual() 返回的 OfVirtual builder；平台线程的资源与调度边界另行评估。