java多线程中自定义异常透传上下文的关键是保留traceid等业务字段，需结合scopedvalue（虚拟线程）、threadfactory初始化（平台线程）和任务装饰器三重机制，并确保异常结构化可序列化。

Java 自定义异常在多线程中透传上下文，关键不是“把异常对象本身跨线程传递”，而是确保异常发生时，它所携带的业务上下文（如 traceId、userId、orderId）能被准确捕获、保留，并在日志、监控或上层处理中可追溯。线程切换天然割裂执行上下文，所以必须配合线程创建、任务封装和异常包装三重机制。

用 ScopedValue 替代 ThreadLocal（虚拟线程必备）

Java 21+ 虚拟线程下，ThreadLocal 不再自动继承上下文，容易导致 MDC 日志断链。ScopedValue 是官方推荐替代方案，它支持作用域级上下文自动传播：

• 声明一个静态 ScopedValue，例如 static final ScopedValue TRACE_ID = ScopedValue.newInstance();
• 在主线程（如 Web 过滤器）中用 ScopedValue.where(TRACE_ID, "t-123").run(() -> {...}) 包裹业务逻辑
• 所有子虚拟线程（包括 ForkJoinPool.commonPool() 或自定义 virtual thread executor 中的任务）会自动继承该值
• 自定义异常构造时，可直接读取 TRACE_ID.get() 并存为字段，无需依赖调用栈或参数传递

在线程池创建阶段注入上下文（传统/平台线程适用）

对于 FixedThreadPool、CachedThreadPool 等基于平台线程的场景，必须在 ThreadFactory.newThread() 中初始化上下文，避免线程复用污染：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• 自定义 ThreadFactory，在 newThread() 内调用 MDC.put("traceId", currentTraceId) 或 Tracing.currentSpan().context().traceId()
• 若当前无 trace 上下文，可生成新 traceId 并绑定到新线程，保证每个任务有独立指纹
• 务必在 Runnable 执行前后用 try-finally 清理 MDC（尤其 catch 块中），防止上下文泄漏

包装任务并捕获上下文（Runnable/Callable 透传）

当无法修改原始任务逻辑（如第三方 SDK 回调、匿名内部类），需用装饰器模式封装：

• 定义 TracedRunnable：构造时捕获提交时刻的 traceId、userId、操作名等，并保存为 final 字段
• 在 run() 中先记录 “start”，再执行原任务；若抛异常，用自定义异常包装，显式传入 cause + 上下文字段
• 示例：throw new BizException("订单支付失败", orderId, userId).initCause(e);（注意：initCause 不推荐，更应使用带 cause 的构造器）

异常构造本身要结构化且可序列化

多线程环境下异常可能被序列化（如 RPC、异步队列），因此自定义异常必须满足：

• 继承 RuntimeException（非受检，不强制上层处理）
• 提供含 String message, Throwable cause, String errorCode, String orderId, String userId 的构造函数
• 所有业务字段设为 private final，并提供 public getter，确保 Jackson / Kryo 序列化时字段不丢失
• 禁止仅靠 getMessage() 拼接上下文，避免截断、乱码或敏感信息泄露

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南