架构与系统设计 / 系统课时
租户主表设计
租户主表设计
本课完成一张可落地的租户主表:既能唯一识别租户,又能控制启停与有效期,并为行级、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,并要求后两种模式必须填写数据命名空间。
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');预期结果:
+-------------+-----------------+----------------+
| 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 用于乐观锁,更新语句应同时匹配旧版本并将其加一,受影响行数为零时说明数据已被其他请求修改。
软删除只表示租户不再参与正常查询,不应立即物理删除业务数据。执行删除前还要检查未结算交易、未导出的审计记录和法规要求,并通过后台任务完成归档或脱敏。
本课总结
- 租户编码负责稳定的业务识别,数据库主键负责内部关联,两者职责不能混用。
- 租户是否可用必须同时校验状态、有效期和软删除标记。
- 隔离模式只保存策略与命名空间,连接凭证和业务明细应放在专门组件中。
下一课预告
下一课将基于租户边界设计组织树、成员关系和跨组织任职模型,解决一个用户在同一租户内承担多个岗位的问题。