架构与系统设计 / 系统课时

过滤器解析租户

过滤器解析租户

本课实现一个可落地的租户入口过滤器:从请求头读取租户标识,依次完成必填、格式和状态校验,校验通过后写入线程上下文,并在请求结束时可靠清理,避免后续业务拿到错误租户。

学习目标

  • 明确租户解析过滤器的校验顺序与失败边界
  • 使用 OncePerRequestFilter 写入并清理租户上下文
  • 通过接口请求验证正常、缺失和停用租户三类结果

入口过滤器的职责边界

过滤器只负责“识别当前请求属于哪个租户”,不应在这里加载完整商户资料、权限菜单或业务配置。入口层做得越重,请求延迟越高,也越容易把数据库故障扩散到全部接口。

推荐按固定顺序处理:先判断请求是否需要租户,再读取租户标识,然后做格式校验,最后查询租户状态。只有全部通过,才允许进入后续控制器。

租户过滤器处理流程

定义租户上下文

下面代码是片段示例,依赖 Spring Boot Web。上下文只保存当前租户编号,并通过 remove() 清除线程变量;不要用 set(null) 代替清理。

java
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 只返回租户是否可用,实际项目可从缓存读取,并在缓存未命中时查询数据库。

java
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 返回当前上下文中的租户编号。

bash
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

预期结果如下,实际响应头和时间可能不同。

text
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 会产生上下文丢失或串租。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

过滤器解析租户

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通