架构与系统设计 / 系统课时
内部调用租户透传
内部调用租户透传
当一个请求跨越多个服务时,租户标识和追踪标识必须随调用链继续传递,否则下游服务可能查错数据、写错租户或丢失日志关联。本课完成一套“入口写入上下文、客户端拦截器透传、下游重新校验”的最小实现。
学习目标
- 理解租户标识在服务调用链中的传递位置
- 使用客户端拦截器自动写入租户与追踪请求头
- 处理上下文清理、异步任务和缺失租户等边界
透传链路如何工作
外部请求先在网关完成身份认证和租户解析,业务服务只把可信租户写入本地 TenantContext。当服务 A 调用服务 B 时,客户端拦截器从上下文读取租户编号,并写入内部请求头;服务 B 接收后再次校验,再建立自己的上下文。

透传应采用“白名单复制”,只携带业务必需字段。不要把 Authorization、Cookie 或全部入站请求头原样复制到下游,否则会扩大凭证泄露和请求头注入风险。
实现客户端拦截器
下面是片段示例,依赖 Spring Cloud OpenFeign。入口过滤器需先调用 TenantContext.setTenantId,Feign 客户端再通过该配置自动补充内部请求头。
package com.example.tenant;
import feign.RequestInterceptor;
import org.slf4j.MDC;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.StringUtils;
public final class TenantContext {
// 只保存入口过滤器已经验证过的租户编号。
private static final ThreadLocal<String> TENANT = new ThreadLocal<>();
private TenantContext() {
}
public static void setTenantId(String tenantId) {
TENANT.set(tenantId);
}
public static String getTenantId() {
return TENANT.get();
}
public static void clear() {
TENANT.remove();
}
}
@Configuration
class TenantFeignConfiguration {
@Bean
RequestInterceptor tenantHeaderForwarder() {
return template -> {
String tenantId = TenantContext.getTenantId();
// 缺少租户时阻断调用,避免下游误用默认租户。
if (!StringUtils.hasText(tenantId)) {
throw new IllegalStateException("Missing trusted tenant context");
}
template.header("X-Tenant-Id", tenantId);
// 追踪标识用于日志关联,可以缺省,但不能替代租户校验。
String traceId = MDC.get("traceId");
if (StringUtils.hasText(traceId)) {
template.header("X-Trace-Id", traceId);
}
};
}
}生效后,任意绑定该配置的 Feign 客户端都会在发送请求前补充租户头;缺少可信租户时立即失败,而不是让下游按“默认租户”继续执行。
验证时在出站请求日志中应看到类似结果,实际追踪编号可能不同:
X-Tenant-Id: tenant-1001
X-Trace-Id: <TRACE_ID>上下文清理与异步边界
ThreadLocal 必须在请求结束时通过 finally 清理。线程池会复用工作线程,如果只设置不删除,后续请求可能读取到上一个租户,形成严重的数据串租。
异步任务、消息队列和定时任务不会自动继承当前线程上下文。此时应把 tenantId 与 traceId 作为任务参数或消息元数据显式传递,消费端校验后重新建立上下文,不要依赖可继承线程变量。
验证与常见错误
验证应覆盖三种情况:正常请求能透传同一租户;缺少租户上下文时客户端拒绝调用;并发请求使用不同租户时互不污染。日志中应同时记录当前租户、调用目标和追踪编号,便于定位跨服务问题。
常见错误包括复制全部请求头、允许空租户继续执行、在下游直接信任任意来源的 X-Tenant-Id,以及忘记清理线程上下文。租户透传只解决“传过去”,可信来源与防伪造还需要边界控制。
本课总结
- 租户与追踪标识应由客户端拦截器按白名单自动透传
- 缺少可信租户时应立即失败,不能回退到默认租户
- 异步链路必须显式携带上下文,线程结束后必须清理
下一课预告
下一课将建立租户标识的可信边界,说明如何在网关删除外部伪造请求头、重新解析租户,并阻止越权切换租户。