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

租户识别入口

租户识别入口

本课解决“一个请求到底属于哪个租户”的入口判定问题。你将比较域名、请求头、路径、令牌和应用标识五种方式,并实现一个具备优先级、冲突检测和可信来源约束的统一识别器。

学习目标

  • 说清五种租户识别方式的适用场景与风险
  • 设计统一的识别优先级和冲突处理规则
  • 编写可验证的租户识别示例

五种识别方式怎么选

方式 典型形式 适合场景 主要风险
域名 tenant-a.example.com 浏览器访问、独立品牌站点 Host 伪造、域名映射过期
请求头 X-Tenant-Id: t1001 内部服务、可信网关转发 客户端可伪造,不能直接信任公网输入
路径 /tenants/t1001/orders 开放 API、管理接口 路径与登录身份可能冲突
令牌 JWT 中的 tenant_id 登录后的业务请求 必须先验签并校验令牌有效期
应用标识 X-App-Id: app-pos-01 POS、移动端、合作方应用 应用与租户映射必须由服务端维护

没有一种方式适合所有入口。浏览器通常优先使用域名,登录后的接口应优先使用已验签令牌,设备或合作方请求则常通过应用标识映射租户。请求头更适合作为可信网关到内部服务之间的传递字段,而不是公网客户端自行声明租户。

统一识别规则

识别器不要简单采用“谁先有值就用谁”。更稳妥的规则是:先收集候选租户,再按可信度选主来源,最后检查其他来源是否与主来源冲突。只要出现两个不同租户编号,就应拒绝请求,而不是静默覆盖。

租户识别入口与冲突检测流程

推荐把优先级定义成配置或常量,并明确每个来源成立的前提。例如,令牌中的租户编号只有在验签成功后才可信;请求头只有在请求确实来自受信网关时才参与判断;应用标识必须先查服务端映射表,不能把应用编号直接当租户编号。

主示例:实现候选收集与冲突检测

下面的 Java 17 示例不依赖 Web 框架,用 Map 模拟请求信息。真实项目可在网关过滤器或 Servlet 过滤器中调用同样的核心逻辑。

java
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Objects;

public class TenantIdentifierDemo {

    public static void main(String[] args) {
        Map<String, String> candidates = new LinkedHashMap<>();
        candidates.put("verifiedToken", "tenant-1001");
        candidates.put("hostMapping", "tenant-1001");
        candidates.put("appMapping", null);
        candidates.put("trustedHeader", null);
        candidates.put("path", "tenant-1001");

        String tenantId = resolve(candidates);
        System.out.println("resolvedTenant=" + tenantId);
    }

    static String resolve(Map<String, String> candidates) {
        String selected = null;
        String selectedSource = null;

        for (Map.Entry<String, String> entry : candidates.entrySet()) {
            String value = normalize(entry.getValue());
            if (value == null) {
                continue;
            }
            if (selected == null) {
                selected = value;
                selectedSource = entry.getKey();
                continue;
            }
            // 多个可信来源必须指向同一租户,否则立即拒绝。
            if (!Objects.equals(selected, value)) {
                throw new IllegalStateException(
                        "Tenant conflict: " + selectedSource + "=" + selected
                                + ", " + entry.getKey() + "=" + value);
            }
        }

        if (selected == null) {
            throw new IllegalStateException("Tenant not found");
        }
        return selected;
    }

    static String normalize(String value) {
        if (value == null || value.isBlank()) {
            return null;
        }
        return value.trim().toLowerCase();
    }
}

预期输出:

text
resolvedTenant=tenant-1001

把 path 改成 tenant-2001 后,程序会抛出冲突异常。Web 层可将“未识别租户”映射为 400 Bad Request,将“身份无权访问该租户”映射为 403 Forbidden,将多个可信来源不一致映射为 409 Conflict。

安全边界与落地检查

租户编号不是普通业务参数,而是数据隔离边界。任何来自公网的 X-Tenant-Id 都不能直接写入上下文;应由网关根据认证结果重写,内部服务还要校验调用方身份,避免客户端绕过网关伪造请求头。

域名和应用标识都应通过服务端表映射到租户编号,并支持停用状态。令牌中的租户编号还要与用户可访问租户集合核对,不能因为令牌格式正确就默认授权成功。

上线前至少验证三类请求:只有一个合法来源时正常识别;多个来源一致时正常通过;多个来源冲突、来源缺失或映射停用时明确拒绝,并在日志中记录来源、追踪号和拒绝原因。

本课总结

  • 租户识别应统一收口,不能由各业务接口自行读取参数
  • 识别过程必须同时处理来源可信度、优先级和冲突检测
  • 租户编号只有经过认证、映射和授权校验后才能进入上下文

下一课预告

下一课将把识别结果封装为租户上下文,并处理线程复用、异步任务和请求结束后的清理问题。

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

目录与阅读设置

阅读设置

17

记录一个想法

租户识别入口

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

登录哪都通