架构与系统设计 / 系统课时
租户管理功能实现
租户管理功能实现
本课实现一条完整的租户管理闭环:管理员提交开通请求,系统创建租户、绑定套餐、保存配置并初始化管理员;后续还能安全地停用、冻结、恢复和调整套餐。完成后,你将掌握事务边界、状态约束和接口验收方法。
学习目标
- 设计租户开通所需的最小数据模型
- 在一个事务中完成租户、套餐、配置和管理员初始化
- 为状态变更与套餐调整设置安全边界
明确最小业务模型
租户管理至少需要四类数据:租户主记录保存名称和状态,租户套餐关系决定功能范围,租户配置保存可变参数,租户管理员建立初始管理入口。开通操作必须保证四类数据要么全部成功,要么全部回滚。
推荐使用稳定的状态枚举,例如 PENDING、ACTIVE、FROZEN、DISABLED。其中 FROZEN 表示暂时禁止业务访问但保留数据,DISABLED 表示停止使用;恢复操作只能从允许的来源状态迁移,不能任意覆盖。

创建数据库表
下面 SQL 给出最小可用结构。真实项目可以增加审计字段、版本号和软删除标记,但租户编码与管理员账号必须建立唯一约束,防止并发开通产生重复数据。
CREATE TABLE saas_tenant (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_code VARCHAR(64) NOT NULL,
tenant_name VARCHAR(128) NOT NULL,
status VARCHAR(16) NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_tenant_code (tenant_code)
);
CREATE TABLE saas_tenant_plan (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL,
plan_code VARCHAR(64) NOT NULL,
effective_at DATETIME NOT NULL,
UNIQUE KEY uk_tenant_plan (tenant_id)
);
CREATE TABLE saas_tenant_config (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL,
config_key VARCHAR(64) NOT NULL,
config_value VARCHAR(512) NOT NULL,
UNIQUE KEY uk_tenant_config (tenant_id, config_key)
);
CREATE TABLE saas_tenant_admin (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL,
username VARCHAR(64) NOT NULL,
password_hash VARCHAR(255) NOT NULL,
status VARCHAR(16) NOT NULL,
UNIQUE KEY uk_tenant_admin_username (tenant_id, username)
);生效行为是:同一个租户编码只能创建一次,每个租户只有一条当前套餐关系,同一配置键不能重复,管理员账号在租户内部唯一。执行后可通过数据库元数据或 SHOW INDEX 检查唯一索引是否存在。
实现原子化开通
开通服务应先校验输入与套餐,再进入事务创建数据。下面是片段示例,依赖项目中的 Repository、密码编码器和请求对象;重点是事务边界与写入顺序。
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.time.LocalDateTime;
@Service
public class TenantApplicationService {
private final TenantRepository tenantRepository;
private final TenantPlanRepository tenantPlanRepository;
private final TenantConfigRepository tenantConfigRepository;
private final TenantAdminRepository tenantAdminRepository;
private final PasswordEncoder passwordEncoder;
public TenantApplicationService(
TenantRepository tenantRepository,
TenantPlanRepository tenantPlanRepository,
TenantConfigRepository tenantConfigRepository,
TenantAdminRepository tenantAdminRepository,
PasswordEncoder passwordEncoder) {
this.tenantRepository = tenantRepository;
this.tenantPlanRepository = tenantPlanRepository;
this.tenantConfigRepository = tenantConfigRepository;
this.tenantAdminRepository = tenantAdminRepository;
this.passwordEncoder = passwordEncoder;
}
@Transactional
public Long openTenant(OpenTenantCommand command) {
if (tenantRepository.existsByCode(command.tenantCode())) {
throw new IllegalStateException("Tenant code already exists");
}
Tenant tenant = Tenant.pending(command.tenantCode(), command.tenantName());
tenantRepository.save(tenant);
// 套餐、配置和管理员必须与租户主记录处于同一事务
tenantPlanRepository.save(new TenantPlan(
tenant.getId(), command.planCode(), LocalDateTime.now()));
tenantConfigRepository.saveDefaults(tenant.getId(), command.config());
tenantAdminRepository.save(new TenantAdmin(
tenant.getId(),
command.adminUsername(),
passwordEncoder.encode(command.adminPassword()),
"ACTIVE"));
tenant.activate();
tenantRepository.updateStatus(tenant.getId(), tenant.getStatus());
return tenant.getId();
}
}事务提交后,四类记录应同时存在,租户最终状态为 ACTIVE。若管理员账号冲突、套餐不存在或配置写入失败,整个方法应抛出异常并回滚,不能留下只有主表记录的“半开通”租户。
提供管理接口
开通接口应只接收必要字段,服务端生成主键、审计时间和密码哈希。下面请求以 JSON 展示一个最小示例,实际地址和端口按部署环境替换。
curl -i -X POST "http://localhost:<PORT>/admin/tenants" -H "Content-Type: application/json" -H "Authorization: Bearer <ADMIN_TOKEN>" -d '{
"tenantCode": "acme",
"tenantName": "Acme Store",
"planCode": "PRO",
"adminUsername": "admin",
"adminPassword": "<PASSWORD>",
"config": {
"timezone": "Asia/Kuala_Lumpur",
"locale": "zh-CN"
}
}'预期结果:
HTTP/1.1 201 Created
Content-Type: application/json
{"code":"0","message":"success","data":{"tenantId":"<ID>"}}动态主键会因环境不同而变化。请求完成后,应查询四张表确认使用同一个 tenant_id,并使用新管理员登录,验证令牌中包含正确租户标识。
实现状态与套餐变更
状态变更不能直接接受任意字符串后覆盖数据库。服务层应读取当前状态,按迁移规则判断目标状态是否合法,再使用版本号或条件更新避免并发覆盖。例如冻结操作只允许 ACTIVE 进入 FROZEN,恢复只允许 FROZEN 进入 ACTIVE。
套餐变更还要处理生效时间与缓存一致性。数据库提交成功后再删除租户权限缓存,下一次访问重新加载新套餐;如果先清缓存后事务回滚,旧数据可能被重新缓存,造成短暂不一致。对会移除功能的降级操作,还应提前检查是否存在无法兼容的存量配置。
管理员管理应支持新增、停用、重置密码和角色调整,但必须始终限定在当前租户内。停用管理员前要确认不会移除租户最后一个可登录的超级管理员;重置密码后应使旧会话失效,避免旧令牌继续访问。
验收租户管理闭环
验收至少覆盖五类场景:正常开通成功、重复租户编码被拒绝、初始化任一步失败时全部回滚、冻结后业务接口被禁止、恢复后重新可用。套餐切换后,应验证权限缓存刷新,并确认新增或移除的功能与套餐定义一致。
还要检查管理员密码只保存哈希值,日志不输出明文密码,跨租户管理员账号不会互相冲突。对于删除租户,优先采用停用与保留审计数据,而不是直接物理删除核心业务记录。
本课总结
- 租户开通必须在一个事务中完成主记录、套餐、配置和管理员初始化
- 状态变更需要显式迁移规则,套餐变更应在提交后刷新权限缓存
- 验收既要检查接口响应,也要验证数据库一致性、登录结果和租户隔离
下一课预告
下一课将进入综合故障排查,围绕认证失败、权限异常、串租户和缓存不一致建立可复用的定位顺序。