Java Thread.Builder factory 怎样复用虚拟线程的命名规则

Java 21 起，Thread.ofVirtual() 可以创建虚拟线程构建器。若多个提交方都需要使用统一的线程名前缀，适合先在 Thread.Builder.OfVirtual 上完成命名配置，再调用 factory() 得到可复用的 ThreadFactory。关键点是：builder 负责配置且不是线程安全的，factory() 返回的工厂可以被多个并发创建方安全使用。

官方资料：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/lang/Thread.Builder.html

实际写法是把 Thread.ofVirtual().name("worker-", 0).factory() 保存为共享工厂，再把它交给需要 ThreadFactory 的执行器或封装层。这样每次 newThread 都沿用同一命名规则，调用方不用并发修改 builder。

builder 和 factory 不是同一个并发角色

Thread.Builder 是配置对象，能设置线程类型、名字和继承选项；factory() 则把当前配置转成线程工厂。官方 API 明确指出 builder 不是线程安全的，而由它创建的 ThreadFactory 可以被多个并发线程使用。

因此不要把一个 builder 放进共享对象后，让不同请求同时调用 name()、inheritInheritableThreadLocals() 或 factory()。更稳妥的生命周期是“初始化阶段配置一次，运行阶段只共享工厂”。

用 name(prefix, start) 固定前缀和编号

name(String prefix, long start) 会把前缀和计数器值拼成线程名。计数器从 start 开始，创建一个线程后递增；start 为负数会抛出 IllegalArgumentException。

import java.util.concurrent.ThreadFactory;

public final class VirtualThreadNames {
    public static ThreadFactory createFactory() {
        // 只在初始化阶段配置 builder，运行阶段共享返回的工厂。
        return Thread.ofVirtual()
                .name("order-worker-", 100)
                .factory();
    }
}

上面的配置表达的是一条命名规则，而不是提前创建 100 个线程。工厂第一次创建的线程会从当前计数器值开始，后续名称继续递增。前缀应尽量包含稳定的职责名，例如 order-worker-，不要把用户 ID、密码、完整请求内容等敏感信息拼进线程名。

把工厂交给多个提交方复用

得到工厂后，可以把它作为依赖传给负责提交任务的组件。下面的例子只展示命名和生命周期，不创建线程池，也不把虚拟线程误当成固定大小的工作线程池。

import java.util.concurrent.ThreadFactory;

public final class TaskLauncher {
    private final ThreadFactory factory;

    public TaskLauncher(ThreadFactory factory) {
        // 依赖在构造时注入，避免每个任务重新修改 Thread.Builder。
        this.factory = factory;
    }

    public Thread launch(Runnable task) {
        // newThread 只负责创建；调用 start 才会调度任务执行。
        Thread thread = factory.newThread(task);
        thread.start();
        return thread;
    }
}

如果应用内部有多个提交方，它们可以持有同一个 ThreadFactory。工厂的线程安全只解决“创建线程时的工厂状态”问题，不会替你同步业务数据，也不会自动等待任务完成。

先使用 builder 再 factory 时要看编号起点

命名计数器属于配置状态的一部分。官方文档说明：由 builder 创建过线程后，再调用 factory()，工厂会以 builder 当前计数器值作为自己的起点；工厂内部随后维护自己的计数器副本。

Thread.Builder.OfVirtual builder = Thread.ofVirtual().name("job-", 0);

// 先由 builder 直接创建一个线程，消耗编号 0。
Thread first = builder.start(() -> {
    // 这里放一个短任务；真实业务应自行处理异常和取消。
});

// 工厂从 builder 当前状态取得配置，后续命名从下一个编号继续。
ThreadFactory factory = builder.factory();
Thread second = factory.newThread(() -> {
    // 工厂创建的线程使用同一前缀和独立递增计数器。
});
second.start();

工程上更容易维护的做法是：如果所有线程都由工厂创建，就不要先拿 builder 直接 start()；初始化时一次性配置并立即保存工厂。若确实需要两种创建方式，就在文档和日志字段中明确编号由哪一条路径消耗。

线程名适合定位，不等于请求追踪

线程名可以帮助日志快速识别线程职责，但虚拟线程数量可能很大，单靠递增编号不能替代请求 ID、任务 ID 或结构化日志字段。建议把线程名作为低成本的辅助标签，把真正的业务关联信息放在日志上下文中。

几个容易忽略的边界

• factory() 返回的是工厂，不是已经启动的线程；仍要通过 newThread 创建，并根据需要调用 start()。
• Thread.Builder 不是线程安全对象，配置阶段不要让多个线程同时修改。
• name(prefix, start) 的起始值不能为负数；若配置来自外部输入，应在创建 builder 前完成边界处理。
• 线程名是诊断信息，不应写入密钥、令牌、完整用户输入或其它敏感内容。

总结

复用虚拟线程命名规则的核心只有两步：用 Thread.ofVirtual().name(prefix, start) 完成一次性配置，再调用 factory() 保存共享工厂。builder 留在初始化边界，factory 进入运行阶段；这样既能保持命名连续，也能避开并发修改配置对象的风险。

相关问题

ThreadFactory 创建的虚拟线程会自动启动吗？不会，newThread 只创建线程，仍需调用 start()。

可以把同一个 Thread.Builder 交给多个线程吗？不建议，官方接口没有把 builder 声明为线程安全；应在初始化阶段创建并共享工厂。

线程名能代替 Trace ID 吗？不能。线程名用于定位线程职责，Trace ID 应作为独立的请求或任务字段传播。