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

租户业务模块实现

租户业务模块实现

本课以客户管理为例,完成一个同时具备租户隔离、组织数据范围和接口验收能力的业务模块。最终结果是:租户只能访问自己的数据,用户还会受到所属组织范围约束,新增、查询和越权访问都有明确边界。

学习目标

  • 设计带 tenant_id 与 org_id 的最小业务数据模型
  • 在服务层统一合并租户条件和组织权限条件
  • 通过接口验证正常访问与跨租户隔离是否生效

明确模块的安全边界

客户模块至少包含新增客户、分页查询和查看详情三个能力。真正决定安全性的不是接口数量,而是每次读写都必须同时满足两个条件:当前登录人的租户与数据租户一致,目标组织位于登录人的可见组织集合中。

租户编号必须来自认证后的登录上下文,不能直接信任请求体、查询参数或自定义请求头。组织编号可以由用户选择,但保存前必须校验它是否属于当前用户的数据范围,否则攻击者可通过修改参数把数据写入无权访问的组织。

租户与组织双重过滤数据流

建立最小数据模型

客户表需要显式保存租户和组织字段,并把业务唯一性限制在租户内部。下面的 SQL 可直接在 MySQL 8 执行。

sql
CREATE TABLE customer (
    id BIGINT NOT NULL AUTO_INCREMENT,
    tenant_id BIGINT NOT NULL,
    org_id BIGINT NOT NULL,
    customer_no VARCHAR(32) NOT NULL,
    customer_name VARCHAR(100) NOT NULL,
    status TINYINT NOT NULL DEFAULT 1,
    created_by BIGINT NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY uk_tenant_customer_no (tenant_id, customer_no),
    KEY idx_tenant_org_id (tenant_id, org_id, id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

预期结果

text
Query OK, 0 rows affected

联合唯一键允许不同租户使用相同客户编号;idx_tenant_org_id 支持最常见的“先按租户、再按组织、最后分页”的查询顺序。若业务使用逻辑删除,还应把删除标记纳入唯一性设计,避免恢复数据时发生冲突。

在服务层合并隔离条件

下面是片段示例,依赖 Spring Boot 3、MyBatis-Plus 和项目已有的 Customer、CustomerMapper 实体。关键点是所有条件都在服务层集中生成,控制器不接收可伪造的 tenantId。

java
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import lombok.RequiredArgsConstructor;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.stereotype.Service;
import org.springframework.util.StringUtils;

import java.util.List;
import java.util.Set;

@Service
@RequiredArgsConstructor
public class CustomerService {

    private final CustomerMapper customerMapper;

    public Long create(CreateCustomerCommand command, TenantPrincipal principal) {
        if (!principal.readableOrgIds().contains(command.orgId())) {
            throw new AccessDeniedException("无权在目标组织下创建客户");
        }

        Customer customer = new Customer();
        // tenantId 永远取自认证上下文,不能使用客户端传值
        customer.setTenantId(principal.tenantId());
        customer.setOrgId(command.orgId());
        customer.setCustomerNo(command.customerNo());
        customer.setCustomerName(command.customerName());
        customer.setCreatedBy(principal.userId());
        customerMapper.insert(customer);
        return customer.getId();
    }

    public List<Customer> list(String keyword, TenantPrincipal principal) {
        Set<Long> orgIds = principal.readableOrgIds();
        if (orgIds.isEmpty()) {
            return List.of();
        }

        LambdaQueryWrapper<Customer> query = Wrappers.lambdaQuery(Customer.class)
                .eq(Customer::getTenantId, principal.tenantId())
                .in(Customer::getOrgId, orgIds)
                .like(StringUtils.hasText(keyword), Customer::getCustomerName, keyword)
                .orderByDesc(Customer::getId);

        return customerMapper.selectList(query);
    }

    public record CreateCustomerCommand(
            Long orgId,
            String customerNo,
            String customerName
    ) {}

    public record TenantPrincipal(
            Long tenantId,
            Long userId,
            Set<Long> readableOrgIds
    ) {}
}

这段实现有两个重要边界:可见组织集合为空时必须直接返回空列表,不能省略 IN 条件;详情查询也必须使用 tenant_id + id,不能先按主键查出数据后再依赖前端隐藏。

通过接口完成验收

启动服务后,使用当前租户的访问令牌创建客户。示例中的端口、令牌和编号需要替换为实际值。

bash
curl -i -X POST "http://localhost:<PORT>/api/customers"   -H "Authorization: Bearer <TOKEN>"   -H "Content-Type: application/json"   -d '{
    "orgId": 2001,
    "customerNo": "C10001",
    "customerName": "示例客户"
  }'

预期结果

text
HTTP/1.1 201 Created

随后使用同一租户、具备组织 2001 权限的令牌查询,应能看到该客户;换成其他租户令牌访问该客户详情时,应返回 404,而不是 403,避免泄露“这条数据确实存在”。

验收时还要检查数据库中的 tenant_id 是否来自登录上下文,以及 SQL 日志中是否同时出现租户条件和组织条件。只验证页面看不到数据并不足够,因为前端过滤不能替代后端隔离。

常见实现错误

最危险的错误是只有列表接口加了租户条件,而详情、更新或删除仍按主键操作。第二类错误是把组织权限当成租户隔离:组织范围只能缩小当前租户内的数据,不能替代 tenant_id。第三类错误是在管理员场景中直接移除全部过滤条件,正确做法应是只放宽组织范围,租户边界仍然保留。

本课总结

  • 业务读写必须同时应用租户边界和组织数据范围
  • tenant_id 只能来自认证上下文,不能信任客户端输入
  • 列表、详情、更新和删除必须采用一致的隔离策略

下一课预告

下一课将为该模块建立自动化测试体系,分别验证权限计算、数据库过滤、接口行为和跨租户访问,避免隔离规则在重构中失效。

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

目录与阅读设置

阅读设置

17

记录一个想法

租户业务模块实现

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

登录哪都通