架构与系统设计 / 系统课时
消费端上下文恢复
消费端上下文恢复
本课解决消息消费者在线程池中复用线程时的租户上下文污染问题。完成后,你将能在消费前校验并恢复租户信息,在成功或异常结束后可靠清理,并让重试与死信流程继续接管失败消息。
学习目标
- 确定消费端恢复租户上下文的正确边界
- 使用作用域模式保证正常和异常路径都会清理上下文
- 验证同一消费线程连续处理不同租户消息时不会串租户
恢复上下文的执行顺序
消费者应先读取消息头,再校验必填字段和头体一致性,随后建立租户上下文,最后才进入业务服务。业务处理结束后,无论成功、抛出异常还是被取消,都必须在最外层 finally 或等价的作用域关闭逻辑中清理上下文。

正确顺序是“校验后写入、业务后清理”。不能先执行业务再补租户,也不能只在成功分支调用 clear()。消息监听容器通常会在线程池中复用线程,一次遗漏就可能让下一条缺少租户头的消息继承旧值。
使用作用域封装恢复与清理
下面的 Java 17 示例使用 ThreadLocal 模拟消费线程。TenantContext.open() 保存旧值并写入当前租户,Scope.close() 在退出时恢复旧值;即使业务抛出异常,try-with-resources 也会自动执行清理。
import java.util.Map;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
public class TenantConsumerDemo {
record Message(Map<String, String> headers, String payload) {
}
static final class TenantContext {
private static final ThreadLocal<String> CURRENT = new ThreadLocal<>();
static String get() {
return CURRENT.get();
}
static Scope open(String tenantId) {
if (tenantId == null || tenantId.isBlank()) {
throw new IllegalArgumentException("missing tenantId");
}
String previous = CURRENT.get();
CURRENT.set(tenantId);
return new Scope(previous);
}
static final class Scope implements AutoCloseable {
private final String previous;
private boolean closed;
private Scope(String previous) {
this.previous = previous;
}
@Override
public void close() {
if (closed) {
return;
}
if (previous == null) {
CURRENT.remove();
} else {
CURRENT.set(previous);
}
closed = true;
}
}
}
static void consume(Message message) {
String tenantId = message.headers().get("tenantId");
// 作用域覆盖完整业务处理,异常会向外传播给消息容器。
try (TenantContext.Scope ignored = TenantContext.open(tenantId)) {
System.out.printf(
"handle payload=%s, tenant=%s%n",
message.payload(),
TenantContext.get()
);
}
System.out.println("after consume tenant=" + TenantContext.get());
}
public static void main(String[] args) throws Exception {
ExecutorService executor = Executors.newSingleThreadExecutor();
try {
executor.submit(() -> consume(
new Message(Map.of("tenantId", "tenant-a"), "order-1")
)).get();
executor.submit(() -> consume(
new Message(Map.of("tenantId", "tenant-b"), "order-2")
)).get();
} finally {
executor.shutdown();
}
}
}预期输出
handle payload=order-1, tenant=tenant-a
after consume tenant=null
handle payload=order-2, tenant=tenant-b
after consume tenant=null两条消息由同一个线程顺序执行,但每次消费后上下文都回到 null,说明旧租户不会泄漏到下一条消息。在 Spring AMQP、Kafka 或其他框架中,可将同样逻辑放在监听器最外层、消费拦截器或统一消息适配器中。
异常、重试与确认边界
业务异常不应在上下文清理层被吞掉。作用域关闭后应继续向外抛出原异常,让消息容器根据配置执行重试、拒绝或投递死信队列。若捕获异常只记录日志并正常返回,容器可能误判消费成功并确认消息。
手动确认消息时,先完成业务事务,再执行确认;发生异常时不要确认。上下文清理必须独立于确认结果,因此应由 try-with-resources 或 finally 保证,而不是依赖成功回调。
上线前验证清单
至少准备三类验证:同一线程连续消费不同租户消息、业务处理中主动抛出异常、消息缺少或伪造 tenantId。前两类用于证明上下文一定清理,后一类应在进入业务服务前失败,并由统一重试或死信策略处理。
日志中应同时输出 tenantId、traceId 和 eventId,但不要把完整消息体中的敏感业务数据无条件写入日志。验证完成后,还应检查异步线程、下游 HTTP 调用和数据库访问是否都能读取到当前租户上下文。
本课总结
- 租户上下文必须在业务处理前恢复,并在最外层作用域中可靠清理
- 异常应继续交给消息容器处理,不能因清理逻辑而被吞掉
- 单线程连续消费不同租户消息是发现上下文泄漏的最直接测试
下一课预告
下一课将继续处理异步消息场景中的幂等、重试与死信隔离,避免同一事件重复执行或失败消息跨租户混流。