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

租户管理功能实现

租户管理功能实现

本课实现一条完整的租户管理闭环:管理员提交开通请求,系统创建租户、绑定套餐、保存配置并初始化管理员;后续还能安全地停用、冻结、恢复和调整套餐。完成后,你将掌握事务边界、状态约束和接口验收方法。

学习目标

  • 设计租户开通所需的最小数据模型
  • 在一个事务中完成租户、套餐、配置和管理员初始化
  • 为状态变更与套餐调整设置安全边界

明确最小业务模型

租户管理至少需要四类数据:租户主记录保存名称和状态,租户套餐关系决定功能范围,租户配置保存可变参数,租户管理员建立初始管理入口。开通操作必须保证四类数据要么全部成功,要么全部回滚。

推荐使用稳定的状态枚举,例如 PENDING、ACTIVE、FROZEN、DISABLED。其中 FROZEN 表示暂时禁止业务访问但保留数据,DISABLED 表示停止使用;恢复操作只能从允许的来源状态迁移,不能任意覆盖。

租户开通与状态变更流程图

创建数据库表

下面 SQL 给出最小可用结构。真实项目可以增加审计字段、版本号和软删除标记,但租户编码与管理员账号必须建立唯一约束,防止并发开通产生重复数据。

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、密码编码器和请求对象;重点是事务边界与写入顺序。

java
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 展示一个最小示例,实际地址和端口按部署环境替换。

bash
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"
    }
  }'

预期结果:

text
HTTP/1.1 201 Created
Content-Type: application/json

{"code":"0","message":"success","data":{"tenantId":"<ID>"}}

动态主键会因环境不同而变化。请求完成后,应查询四张表确认使用同一个 tenant_id,并使用新管理员登录,验证令牌中包含正确租户标识。

实现状态与套餐变更

状态变更不能直接接受任意字符串后覆盖数据库。服务层应读取当前状态,按迁移规则判断目标状态是否合法,再使用版本号或条件更新避免并发覆盖。例如冻结操作只允许 ACTIVE 进入 FROZEN,恢复只允许 FROZEN 进入 ACTIVE。

套餐变更还要处理生效时间与缓存一致性。数据库提交成功后再删除租户权限缓存,下一次访问重新加载新套餐;如果先清缓存后事务回滚,旧数据可能被重新缓存,造成短暂不一致。对会移除功能的降级操作,还应提前检查是否存在无法兼容的存量配置。

管理员管理应支持新增、停用、重置密码和角色调整,但必须始终限定在当前租户内。停用管理员前要确认不会移除租户最后一个可登录的超级管理员;重置密码后应使旧会话失效,避免旧令牌继续访问。

验收租户管理闭环

验收至少覆盖五类场景:正常开通成功、重复租户编码被拒绝、初始化任一步失败时全部回滚、冻结后业务接口被禁止、恢复后重新可用。套餐切换后,应验证权限缓存刷新,并确认新增或移除的功能与套餐定义一致。

还要检查管理员密码只保存哈希值,日志不输出明文密码,跨租户管理员账号不会互相冲突。对于删除租户,优先采用停用与保留审计数据,而不是直接物理删除核心业务记录。

本课总结

  • 租户开通必须在一个事务中完成主记录、套餐、配置和管理员初始化
  • 状态变更需要显式迁移规则,套餐变更应在提交后刷新权限缓存
  • 验收既要检查接口响应,也要验证数据库一致性、登录结果和租户隔离

下一课预告

下一课将进入综合故障排查,围绕认证失败、权限异常、串租户和缓存不一致建立可复用的定位顺序。

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

目录与阅读设置

阅读设置

17

记录一个想法

租户管理功能实现

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

登录哪都通