2. 多租户架构基础：多租户概念、隔离模式与租户上下文管理

2.1 多租户核心概念

多租户（Multi-Tenancy）是一种软件架构模式，允许单个应用实例同时服务多个租户，每个租户拥有独立的逻辑视图与数据边界。在计费模型中，租户通常对应一个企业客户或组织，其内部的用户、订阅、用量与账单数据必须严格隔离。

2.2 三种隔离模式对比

选择隔离模式直接影响计费数据的安全性、查询性能与运维复杂度。以下是三种主流模式的详细对比：

2.3 隔离模式架构图

下图展示了三种隔离模式在数据库层的物理与逻辑布局：

2.4 租户上下文管理

租户上下文是贯穿整个请求链路的身份标识。在计费接口中，每一次用量上报、账单查询都必须携带正确的租户上下文，否则会导致数据泄露或计费错误。

2.4.1 上下文传递链路

1. 客户端请求：在 HTTP Header 中携带 X-Tenant-ID 或 JWT 中的 tenant_id 声明。
2. API 网关/反向代理：解析并校验租户 ID 的合法性，拒绝无效或格式错误的请求。
3. 鉴权拦截器：从请求中提取租户上下文，注入到当前线程的 TenantContext 对象中。
4. 业务服务层：从 TenantContext 获取租户 ID，用于数据查询过滤、计费策略路由。
5. 数据访问层：在 SQL 查询中自动追加 WHERE tenant_id = ? 条件，或通过 RLS 策略强制过滤。

2.4.2 上下文管理代码示例

以下是一个基于 ThreadLocal 的租户上下文管理实现（Java 示例）：

public class TenantContext {
    private static final ThreadLocal<String> CURRENT_TENANT = new ThreadLocal<>();

    public static void setTenantId(String tenantId) {
        if (tenantId == null || tenantId.isBlank()) {
            throw new IllegalArgumentException("tenantId must not be null or blank");
        }
        CURRENT_TENANT.set(tenantId);
    }

    public static String getTenantId() {
        String tenantId = CURRENT_TENANT.get();
        if (tenantId == null) {
            throw new IllegalStateException("Tenant context not set for current thread");
        }
        return tenantId;
    }

    public static void clear() {
        CURRENT_TENANT.remove();
    }
}

2.4.3 上下文传递流程图

下图展示了从 HTTP 请求到数据库查询的完整租户上下文传递链路：

2.5 隔离模式选型决策表

在计费系统设计阶段，可参考以下决策矩阵选择隔离模式：