Spring Boot六边形架构如何跨类传递correlationId无需修改方法入参

核心思路是用线程绑定的请求上下文容器做隐式传递，全程不需要修改业务层方法签名，完全符合端口与适配器的分层依赖规则。 #

1. 定义无框架依赖的上下文容器 #

把上下文类放在公共端口模块，所有层都可以依赖，不引入任何Web、中间件相关依赖，不破坏分层：

public class CorrelationIdContext {
    // 传统Servlet/Spring MVC场景用ThreadLocal，WebFlux响应式场景替换为Reactor Context
    private static final ThreadLocal<String> ID_HOLDER = new ThreadLocal<>();

    public static void set(String correlationId) {
        ID_HOLDER.set(correlationId);
        // 同步放到日志MDC，方便后续自动打印
        MDC.put("correlationId", correlationId);
    }

    public static String get() {
        return ID_HOLDER.get();
    }

    public static void clear() {
        ID_HOLDER.remove();
        MDC.remove("correlationId");
    }
}

注意：线程池复用场景如果不手动清理，会出现上下文串号、内存泄漏问题，必须在请求结束后执行clear操作。

2. 入站适配器层做ID初始化 #

所有接收外部请求的入站适配器（Web Controller、MQ消费者、RPC服务端），在请求进入业务逻辑前完成ID解析和上下文赋值，请求结束后清理：
以Spring MVC场景为例，实现全局拦截器即可，不需要修改任何Controller代码：

@Component
public class CorrelationIdInterceptor implements HandlerInterceptor {
    private static final String ID_HEADER = "X-Correlation-Id";

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        // 优先取网关传入的ID，没有就自行生成兼容直连场景
        String correlationId = request.getHeader(ID_HEADER);
        if (correlationId == null || correlationId.isBlank()) {
            correlationId = UUID.randomUUID().toString();
        }
        CorrelationIdContext.set(correlationId);
        // 把ID写回响应头，方便链路排查
        response.setHeader(ID_HEADER, correlationId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        CorrelationIdContext.clear();
    }
}

把拦截器注册到Spring MVC的拦截器链中，即可覆盖所有HTTP请求。 #

3. 出站适配器层做ID自动透传 #

所有调用外部服务的出站适配器（Feign客户端、RestTemplate、MQ生产者），在发起调用前自动从上下文取ID，塞到请求头/消息属性中传递，业务层调用端口时完全感知不到透传逻辑：
以OpenFeign为例，实现全局请求拦截器：

@Component
public class FeignCorrelationIdInterceptor implements RequestInterceptor {
    @Override
    public void apply(RequestTemplate template) {
        String correlationId = CorrelationIdContext.get();
        if (correlationId != null) {
            template.header("X-Correlation-Id", correlationId);
        }
    }
}

RestTemplate、WebClient、MQ客户端都用同样的思路，在对应适配器的拦截器/钩子方法里完成ID注入即可。 #

4. 日志配置自动打印ID #

不需要在每次打日志时手动传入correlationId，只要在日志框架的pattern中配置MDC字段即可自动输出。以Logback为例，日志输出格式配置如下：

<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [correlationId:%X{correlationId}] - %msg%n</pattern>

配置完成后所有日志行会自动携带当前请求的correlationId。 #

异步场景适配 #

如果使用@Async、自定义线程池处理异步任务，需要配置任务装饰器，把主线程的上下文传递到子线程，避免异步场景丢ID：

@Bean
public TaskDecorator correlationIdTaskDecorator() {
    return runnable -> {
        // 提交任务时捕获当前线程的ID
        String currentId = CorrelationIdContext.get();
        return () -> {
            try {
                // 异步线程执行前设置上下文
                CorrelationIdContext.set(currentId);
                runnable.run();
            } finally {
                CorrelationIdContext.clear();
            }
        };
    };
}

把这个装饰器配置到所有异步执行器、线程池实例中即可覆盖异步场景。 #

方案分层合规性说明 #

• 上下文容器放在端口层，没有引入任何适配器实现依赖，领域层、业务层不需要感知Web、RPC等外部协议细节，符合六边形架构的依赖方向要求。
• 所有ID解析、传递、清理逻辑全部收敛在入站、出站适配器层，业务逻辑、端口接口不需要做任何修改，不需要给方法新增correlationId入参，零侵入。
• 后续如果替换适配器实现（比如从Spring MVC迁移到WebFlux、从Feign替换为gRPC），只需要调整对应适配器层的上下文存取逻辑，核心业务代码完全不需要改动。

内容的提问来源于stack exchange，提问作者Noobnoob