架构与系统设计 / 系统课时
租户开通流程
租户开通流程
本课完成一个可落地的租户开通编排:从创建租户主记录开始,依次生成管理员、默认角色、基础配置和初始化任务,并用明确的状态与验收条件避免“表里有租户、实际却不可用”的半成品。
学习目标
- 划分租户开通的输入、输出与事务边界
- 编排管理员、默认角色、配置和初始化数据的执行顺序
- 通过状态、日志和查询结果验收开通是否成功
明确开通边界
租户开通不是单纯插入一条租户记录,而是把一个新租户推进到可登录、可授权、可使用的状态。最小输入通常包括租户编码、租户名称、管理员账号和初始化模板;最终输出至少包含租户主记录、管理员用户、默认管理员角色、用户角色绑定、默认配置和基础数据任务。
建议把租户状态设计为 PENDING、INITIALIZING、ACTIVE、FAILED。只有全部必需步骤完成后才能进入 ACTIVE;任一后置任务失败时保留 INITIALIZING 或转为 FAILED,避免前端把未准备好的租户当成正常租户使用。
编排执行顺序

同库且必须同时成功的步骤应放在一个核心事务中,例如租户主记录、管理员、角色和授权关系。字典复制、序列初始化、对象存储目录等耗时或依赖外部系统的动作,应登记为初始化任务,在核心事务提交后执行,并允许失败重试。
下面是编排服务的片段示例,依赖同一应用中的仓储与领域服务。每个创建方法都应有业务唯一约束,例如租户编码唯一、管理员账号在租户内唯一、默认角色编码在租户内唯一。
@Service
@RequiredArgsConstructor
public class TenantProvisioningService {
private final TenantRepository tenantRepository;
private final UserService userService;
private final RoleService roleService;
private final TenantConfigService configService;
private final TenantInitTaskService initTaskService;
@Transactional
public Long openTenant(OpenTenantCommand command) {
// 核心身份与授权数据必须在同一事务中提交
Tenant tenant = tenantRepository.createPending(
command.tenantCode(), command.tenantName());
Long adminUserId = userService.createTenantAdmin(
tenant.getId(), command.adminUsername());
Long adminRoleId = roleService.createDefaultAdminRole(tenant.getId());
roleService.bindUser(adminUserId, adminRoleId);
configService.createDefaults(tenant.getId());
// 外部资源和大批量数据不在当前事务内执行,只登记可重试任务
initTaskService.enqueue(tenant.getId(), "BASE_DATA");
tenantRepository.markInitializing(tenant.getId());
return tenant.getId();
}
}预期结果
返回新租户 ID;核心事务提交后,租户状态为 INITIALIZING,管理员、默认角色、授权关系、默认配置和 BASE_DATA 初始化任务各有一条有效记录。完成初始化并激活
初始化任务执行成功后,开通服务不能仅凭“任务已调用”就激活租户,而要检查全部必需任务是否为 SUCCESS。只有必需任务全部完成,才把租户从 INITIALIZING 更新为 ACTIVE;可选任务失败时可以记录告警,但不能影响登录的核心任务必须事先明确。
当初始化失败时,不要直接删除租户。删除可能遗留已经创建的外部资源,也会让审计链断裂。更稳妥的做法是记录失败步骤、错误摘要和重试次数,由管理员重试单个任务;确认租户从未产生业务数据时,才允许执行受控的关闭或清理流程。
运行与验收
开通完成后,可用一条聚合查询检查关键对象是否齐全。下列 SQL 中的 <TENANT_ID> 替换为实际租户 ID,表名可按项目调整。
SELECT
t.status,
COUNT(DISTINCT u.id) AS admin_count,
COUNT(DISTINCT r.id) AS role_count,
COUNT(DISTINCT ur.id) AS binding_count,
COUNT(DISTINCT c.id) AS config_count,
COUNT(DISTINCT CASE WHEN it.status = 'SUCCESS' THEN it.id END)
AS success_task_count
FROM tenant t
LEFT JOIN sys_user u
ON u.tenant_id = t.id AND u.is_tenant_admin = 1
LEFT JOIN sys_role r
ON r.tenant_id = t.id AND r.role_code = 'TENANT_ADMIN'
LEFT JOIN sys_user_role ur
ON ur.user_id = u.id AND ur.role_id = r.id
LEFT JOIN tenant_config c
ON c.tenant_id = t.id
LEFT JOIN tenant_init_task it
ON it.tenant_id = t.id
WHERE t.id = <TENANT_ID>
GROUP BY t.status;预期结果
status=ACTIVE,admin_count=1,role_count=1,binding_count=1,config_count 大于 0,success_task_count 等于必需初始化任务数量。实际列值取决于配置模板和任务清单。验收还应覆盖管理员首次登录、默认角色权限、重复提交开通请求以及初始化任务失败后的重试。若重复请求会生成第二个租户或第二个管理员,说明唯一约束或幂等控制仍不完整。
本课总结
- 租户开通的完成条件是租户真正可登录、可授权、可使用,而不是仅插入主记录
- 核心数据放在短事务中,耗时或外部初始化通过可重试任务完成
- 使用状态机和聚合验收查询,能够及时发现半成品租户
下一课预告
下一课将专门处理初始化任务的幂等问题,确保同一任务重复执行或并发触发时,不会产生重复角色、重复配置和脏数据。