JDK线程工厂构建器链式用法解析

ThreadFactoryBuilder 是 Guava 库（非 JDK 自带）提供的高效线程工厂构建工具，但因依赖缺失、nameFormat 中遗漏或误用 %d 占位符、以及未显式设置 uncaughtExceptionHandler 这三大常见误区，极易导致编译失败、线程命名混乱、异常静默退出等线上疑难问题；本文直击这些高频踩坑点，详解如何正确引入 Guava ≥18.0、规范使用 nameFormat 实现可追溯的递增线程名、绑定日志友好的异常处理器，并澄清其线程安全性，助你写出健壮、可观测、易维护的并发代码。

ThreadFactoryBuilder 是哪个库的？别直接 import com.google.common.util.concurrent

它属于 Guava，不是 JDK 自带的。JDK 并发包（java.util.concurrent）里压根没有 ThreadFactoryBuilder——这是很多人翻源码半天没找到类定义的原因。你看到的示例代码如果用了这个类，一定依赖了 Guava：com.google.guava:guava。Maven 里没加这行，编译就报 Cannot resolve symbol ThreadFactoryBuilder。

常见错误现象：new ThreadFactoryBuilder() 红标、IDE 提示找不到类、打包后 NoClassDefFoundError。

• 确认项目已引入 Guava ≥ 18.0（低版本无此工具类）
• 不要试图从 java.util.concurrent.ThreadFactory 或 Executors 里“找出来”它
• 替代方案：JDK 原生写法是匿名内部类或 Lambda 实现 ThreadFactory 接口，但可读性和复用性差很多

nameFormat 参数必须含 %d，否则线程名不递增

ThreadFactoryBuilder 的 nameFormat 不是简单字符串模板，而是类似 String.format 的格式化规则，且 %d 是唯一被识别为线程序号的占位符。漏写或写成 %s、%i，所有线程都会叫同一个名字，比如 "worker" —— 这会让日志排查和 JFR/Arthas 监控完全失效。

正确写法示例：new ThreadFactoryBuilder().setNameFormat("io-worker-%d").build()，生成线程名为 io-worker-0、io-worker-1…

• 只允许一个 %d，多写了会抛 IllegalFormatException
• 支持其他格式符如 %s（用于固定字符串），但不能替代 %d 做计数
• 若需前缀+时间戳+序号，得自己封装一层，ThreadFactoryBuilder 不支持动态计算

未设置 uncaughtExceptionHandler 时，异常线程静默退出

线程池中任务抛出未捕获异常，默认行为不是打印堆栈，而是直接终止线程且不通知任何人。尤其在 ThreadPoolExecutor 中，如果 ThreadFactory 没绑定异常处理器，execute(Runnable) 提交的任务崩溃后，你只会发现线程数变少、任务卡住，却看不到任何错误日志。

实操建议：显式设置 setUncaughtExceptionHandler，把异常导向 SLF4J 或 Log4j：

new ThreadFactoryBuilder()
    .setNameFormat("biz-task-%d")
    .setUncaughtExceptionHandler((t, e) -> log.error("Thread {} crashed", t.getName(), e))
    .build()

• 不要依赖全局 Thread.setDefaultUncaughtExceptionHandler，它对线程池创建的线程不一定生效
• 若使用 Spring，注意 @Async 底层线程池是否复用了该 ThreadFactory
• 某些监控 SDK（如 SkyWalking）依赖异常处理器注入上下文，漏设会导致链路断掉

build() 后的 ThreadFactory 不是线程安全的？其实它是

有人担心并发调用 ThreadFactory.newThread(Runnable) 会产生命名冲突或状态错乱。实际上 ThreadFactoryBuilder.build() 返回的是一个线程安全的实现（Guava 内部用 AtomicInteger 计数），多个线程同时调用 newThread 不会重复分配相同序号，也不需要额外同步。

但要注意边界场景：

• 同一个 ThreadFactory 实例可被多个线程池共用，没问题；但不要把不同 ThreadFactoryBuilder 配置混用（比如 A 设了 nameFormat，B 设了 exceptionHandler，然后都 build 出来塞进同一个线程池）
• 如果重写了 build() 返回的工厂类（比如继承后覆写 newThread），那线程安全性就得自己保证
• Android 上低版本 Guava 可能有反射兼容问题，建议用 ThreadFactoryBuilder 时锁死 Guava 版本 ≥ 30.0-android

线程名不递增、异常静默、依赖缺失——这三个点卡住的人最多，而且往往在压测或上线后才暴露。别等出事再查。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《JDK线程工厂构建器链式用法解析》文章吧，也可关注golang学习网公众号了解相关技术文章。