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

租户主表设计

租户主表设计

本课完成一张可落地的租户主表:既能唯一识别租户,又能控制启停与有效期,并为行级、Schema 级和独立数据库隔离保留统一入口。完成后,你可以直接建表、写入样例数据并验证“当前可用租户”的查询条件。

学习目标

  • 设计稳定且不可复用的租户编码与主键
  • 正确表达状态、有效期、联系人、隔离模式和审计信息
  • 通过约束、索引和查询条件验证租户是否可用

从业务约束反推字段

租户主表只保存“租户本身”的稳定属性,不承载套餐、组织、成员或权限明细。tenant_code 用于接口、日志和跨系统引用,创建后不应修改;数据库自增主键 id 只用于内部关联,避免把业务编码传播到所有子表。

字段组 代表字段 设计目的
身份 id、tenant_code、tenant_name 保证内部关联稳定,并提供可读业务标识
可用性 status、valid_from、valid_to 同时控制人工启停和合同有效期
联系信息 contact_name、contact_mobile、contact_email 保存管理联系人,不替代登录账号
隔离策略 isolation_mode、data_namespace 决定数据按租户列、Schema 或独立库隔离
审计控制 version、创建/更新字段、deleted 支持并发更新、追踪变更和软删除

状态与有效期必须同时判断。状态为启用但已经过期的租户仍不可访问;有效期尚未结束但被人工停用的租户同样不可访问。

建表并验证可用租户

下面示例适用于 MySQL 8.0.16 及以上版本,其中 CHECK 约束会被真正执行。示例把隔离模式限制为 ROW、SCHEMA 和 DATABASE,并要求后两种模式必须填写数据命名空间。

sql
DROP TABLE IF EXISTS saas_tenant;

CREATE TABLE saas_tenant (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    tenant_code VARCHAR(32) NOT NULL,
    tenant_name VARCHAR(100) NOT NULL,
    status TINYINT UNSIGNED NOT NULL DEFAULT 1 COMMENT '0=停用,1=启用,2=已过期',
    valid_from DATETIME NOT NULL,
    valid_to DATETIME NULL,
    contact_name VARCHAR(50) NULL,
    contact_mobile VARCHAR(32) NULL,
    contact_email VARCHAR(128) NULL,
    isolation_mode VARCHAR(16) NOT NULL DEFAULT 'ROW',
    data_namespace VARCHAR(128) NULL,
    version INT UNSIGNED NOT NULL DEFAULT 0,
    created_by BIGINT UNSIGNED NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_by BIGINT UNSIGNED NOT NULL,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
        ON UPDATE CURRENT_TIMESTAMP,
    deleted TINYINT UNSIGNED NOT NULL DEFAULT 0,
    PRIMARY KEY (id),
    UNIQUE KEY uk_tenant_code (tenant_code),
    KEY idx_tenant_availability (status, deleted, valid_to),
    CONSTRAINT chk_tenant_status
        CHECK (status IN (0, 1, 2)),
    CONSTRAINT chk_tenant_isolation_mode
        CHECK (isolation_mode IN ('ROW', 'SCHEMA', 'DATABASE')),
    CONSTRAINT chk_tenant_valid_range
        CHECK (valid_to IS NULL OR valid_to > valid_from),
    CONSTRAINT chk_tenant_namespace
        CHECK (
            (isolation_mode = 'ROW' AND data_namespace IS NULL)
            OR
            (isolation_mode IN ('SCHEMA', 'DATABASE')
             AND data_namespace IS NOT NULL)
        )
) ENGINE=InnoDB
  DEFAULT CHARSET=utf8mb4
  COLLATE=utf8mb4_0900_ai_ci;

INSERT INTO saas_tenant (
    tenant_code, tenant_name, status,
    valid_from, valid_to,
    contact_name, contact_mobile, contact_email,
    isolation_mode, data_namespace,
    created_by, updated_by
) VALUES (
    'acme', 'Acme 示例租户', 1,
    '2026-01-01 00:00:00', '2027-01-01 00:00:00',
    '张三', '13800000000', 'admin@acme.example',
    'ROW', NULL,
    10001, 10001
);

SELECT tenant_code, tenant_name, isolation_mode
FROM saas_tenant
WHERE tenant_code = 'acme'
  AND deleted = 0
  AND status = 1
  AND valid_from <= '2026-08-03 12:00:00'
  AND (valid_to IS NULL OR valid_to > '2026-08-03 12:00:00');

预期结果:

text
+-------------+-----------------+----------------+
| tenant_code | tenant_name     | isolation_mode |
+-------------+-----------------+----------------+
| acme        | Acme 示例租户   | ROW            |
+-------------+-----------------+----------------+

生产环境中的自增主键、创建时间和更新时间会随实际执行变化,因此接口响应或日志中的对应值应使用实际生成结果。

处理状态与隔离模式

建议把状态变化限定为“启用、停用、过期”三类业务动作。停用通常可恢复,过期由合同或订阅到期触发;续期时更新 valid_to 后,再根据业务规则恢复为启用。不要仅依赖定时任务写入“过期”状态,在线请求仍应实时校验有效期,避免任务延迟造成越权访问。

ROW 模式下,各业务表必须保存 tenant_id,并由数据访问层强制追加租户条件。SCHEMA 模式的 data_namespace 可保存 Schema 名称;DATABASE 模式可保存数据源别名,而不是明文连接串。连接凭证应进入密钥管理系统,不能存进租户主表。

审计与更新边界

created_by、created_at 创建后不修改;updated_by 与 updated_at 记录最近一次业务变更。version 用于乐观锁,更新语句应同时匹配旧版本并将其加一,受影响行数为零时说明数据已被其他请求修改。

软删除只表示租户不再参与正常查询,不应立即物理删除业务数据。执行删除前还要检查未结算交易、未导出的审计记录和法规要求,并通过后台任务完成归档或脱敏。

本课总结

  • 租户编码负责稳定的业务识别,数据库主键负责内部关联,两者职责不能混用。
  • 租户是否可用必须同时校验状态、有效期和软删除标记。
  • 隔离模式只保存策略与命名空间,连接凭证和业务明细应放在专门组件中。

下一课预告

下一课将基于租户边界设计组织树、成员关系和跨组织任职模型,解决一个用户在同一租户内承担多个岗位的问题。

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

目录与阅读设置

阅读设置

17

记录一个想法

租户主表设计

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

登录哪都通