架构与系统设计 / 系统课时
过滤器解析租户
过滤器解析租户
本课实现一个可落地的租户入口过滤器:从请求头读取租户标识,依次完成必填、格式和状态校验,校验通过后写入线程上下文,并在请求结束时可靠清理,避免后续业务拿到错误租户。
学习目标
- 明确租户解析过滤器的校验顺序与失败边界
- 使用
OncePerRequestFilter写入并清理租户上下文 - 通过接口请求验证正常、缺失和停用租户三类结果
入口过滤器的职责边界
过滤器只负责“识别当前请求属于哪个租户”,不应在这里加载完整商户资料、权限菜单或业务配置。入口层做得越重,请求延迟越高,也越容易把数据库故障扩散到全部接口。
推荐按固定顺序处理:先判断请求是否需要租户,再读取租户标识,然后做格式校验,最后查询租户状态。只有全部通过,才允许进入后续控制器。

定义租户上下文
下面代码是片段示例,依赖 Spring Boot Web。上下文只保存当前租户编号,并通过 remove() 清除线程变量;不要用 set(null) 代替清理。
public final class TenantContext {
private static final ThreadLocal<String> TENANT_ID = new ThreadLocal<>();
private TenantContext() {
}
public static void setTenantId(String tenantId) {
TENANT_ID.set(tenantId);
}
public static String getTenantId() {
return TENANT_ID.get();
}
public static void clear() {
// remove 会同时移除当前线程上的 ThreadLocal 条目
TENANT_ID.remove();
}
}该类不负责校验租户,也不保存可变业务对象。上下文越小,线程传播和清理越容易控制。
实现解析与校验
下面过滤器约定租户编号由 3~32 位字母、数字和短横线组成。TenantStatusService 只返回租户是否可用,实际项目可从缓存读取,并在缓存未命中时查询数据库。
import java.io.IOException;
import java.util.Set;
import java.util.regex.Pattern;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
@Component
public class TenantResolveFilter extends OncePerRequestFilter {
private static final String HEADER_NAME = "X-Tenant-Id";
private static final Pattern TENANT_PATTERN =
Pattern.compile("^[A-Za-z0-9-]{3,32}$");
private static final Set<String> PUBLIC_PATHS =
Set.of("/health", "/login");
private final TenantStatusService tenantStatusService;
public TenantResolveFilter(TenantStatusService tenantStatusService) {
this.tenantStatusService = tenantStatusService;
}
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
if (PUBLIC_PATHS.contains(request.getRequestURI())) {
filterChain.doFilter(request, response);
return;
}
String tenantId = request.getHeader(HEADER_NAME);
if (tenantId == null || tenantId.isBlank()) {
writeError(response, 400, "TENANT_REQUIRED");
return;
}
if (!TENANT_PATTERN.matcher(tenantId).matches()) {
writeError(response, 400, "TENANT_FORMAT_INVALID");
return;
}
if (!tenantStatusService.isEnabled(tenantId)) {
writeError(response, 403, "TENANT_UNAVAILABLE");
return;
}
try {
// 校验完成后再写入,避免非法值进入业务链路
TenantContext.setTenantId(tenantId);
filterChain.doFilter(request, response);
} finally {
// 容器线程会复用,请求结束必须清理
TenantContext.clear();
}
}
private void writeError(
HttpServletResponse response,
int status,
String code) throws IOException {
response.setStatus(status);
response.setContentType(MediaType.APPLICATION_JSON_VALUE);
response.getWriter().write("{\"code\":\"" + code + "\"}");
}
}finally 是这段实现的关键。无论控制器正常返回、抛出异常,还是后续过滤器中断,请求线程上的租户值都会被清除。
验证三类请求
假设测试租户 tenant-a 处于启用状态,接口 /api/orders/current-tenant 返回当前上下文中的租户编号。
curl -i -H "X-Tenant-Id: tenant-a" http://localhost:<PORT>/api/orders/current-tenant
curl -i http://localhost:<PORT>/api/orders/current-tenant
curl -i -H "X-Tenant-Id: tenant-disabled" http://localhost:<PORT>/api/orders/current-tenant预期结果如下,实际响应头和时间可能不同。
HTTP/1.1 200
{"tenantId":"tenant-a"}
HTTP/1.1 400
{"code":"TENANT_REQUIRED"}
HTTP/1.1 403
{"code":"TENANT_UNAVAILABLE"}常见实现错误
把租户编号直接交给业务层校验,会导致每个接口重复处理;在格式校验前查询数据库,会让恶意请求消耗连接池;只在正常路径调用 clear(),则异常请求可能把旧租户遗留在线程中。
公共接口白名单应精确到路径,不要简单跳过整个 /api/**。若登录接口本身需要识别租户,应继续解析租户,只放宽身份认证,而不是绕过租户过滤器。
本课总结
- 租户过滤器应按“是否需要、是否存在、格式是否合法、状态是否可用”的顺序处理
- 上下文必须在校验通过后写入,并在
finally中调用remove()清理 - 过滤器只承担入口识别,不应承载完整租户业务数据加载
下一课预告
下一课将处理线程池和异步任务中的租户上下文传播,并说明为什么只依赖普通 ThreadLocal 会产生上下文丢失或串租。