架构与系统设计 / 系统课时
租户识别入口
租户识别入口
本课解决“一个请求到底属于哪个租户”的入口判定问题。你将比较域名、请求头、路径、令牌和应用标识五种方式,并实现一个具备优先级、冲突检测和可信来源约束的统一识别器。
学习目标
- 说清五种租户识别方式的适用场景与风险
- 设计统一的识别优先级和冲突处理规则
- 编写可验证的租户识别示例
五种识别方式怎么选
| 方式 | 典型形式 | 适合场景 | 主要风险 |
|---|---|---|---|
| 域名 | 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 过滤器中调用同样的核心逻辑。
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();
}
}预期输出:
resolvedTenant=tenant-1001把 path 改成 tenant-2001 后,程序会抛出冲突异常。Web 层可将“未识别租户”映射为 400 Bad Request,将“身份无权访问该租户”映射为 403 Forbidden,将多个可信来源不一致映射为 409 Conflict。
安全边界与落地检查
租户编号不是普通业务参数,而是数据隔离边界。任何来自公网的 X-Tenant-Id 都不能直接写入上下文;应由网关根据认证结果重写,内部服务还要校验调用方身份,避免客户端绕过网关伪造请求头。
域名和应用标识都应通过服务端表映射到租户编号,并支持停用状态。令牌中的租户编号还要与用户可访问租户集合核对,不能因为令牌格式正确就默认授权成功。
上线前至少验证三类请求:只有一个合法来源时正常识别;多个来源一致时正常通过;多个来源冲突、来源缺失或映射停用时明确拒绝,并在日志中记录来源、追踪号和拒绝原因。
本课总结
- 租户识别应统一收口,不能由各业务接口自行读取参数
- 识别过程必须同时处理来源可信度、优先级和冲突检测
- 租户编号只有经过认证、映射和授权校验后才能进入上下文
下一课预告
下一课将把识别结果封装为租户上下文,并处理线程复用、异步任务和请求结束后的清理问题。