架构与系统设计 / 系统课时
租户业务模块实现
租户业务模块实现
本课以客户管理为例,完成一个同时具备租户隔离、组织数据范围和接口验收能力的业务模块。最终结果是:租户只能访问自己的数据,用户还会受到所属组织范围约束,新增、查询和越权访问都有明确边界。
学习目标
- 设计带
tenant_id与org_id的最小业务数据模型 - 在服务层统一合并租户条件和组织权限条件
- 通过接口验证正常访问与跨租户隔离是否生效
明确模块的安全边界
客户模块至少包含新增客户、分页查询和查看详情三个能力。真正决定安全性的不是接口数量,而是每次读写都必须同时满足两个条件:当前登录人的租户与数据租户一致,目标组织位于登录人的可见组织集合中。
租户编号必须来自认证后的登录上下文,不能直接信任请求体、查询参数或自定义请求头。组织编号可以由用户选择,但保存前必须校验它是否属于当前用户的数据范围,否则攻击者可通过修改参数把数据写入无权访问的组织。

建立最小数据模型
客户表需要显式保存租户和组织字段,并把业务唯一性限制在租户内部。下面的 SQL 可直接在 MySQL 8 执行。
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;预期结果
Query OK, 0 rows affected联合唯一键允许不同租户使用相同客户编号;idx_tenant_org_id 支持最常见的“先按租户、再按组织、最后分页”的查询顺序。若业务使用逻辑删除,还应把删除标记纳入唯一性设计,避免恢复数据时发生冲突。
在服务层合并隔离条件
下面是片段示例,依赖 Spring Boot 3、MyBatis-Plus 和项目已有的 Customer、CustomerMapper 实体。关键点是所有条件都在服务层集中生成,控制器不接收可伪造的 tenantId。
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,不能先按主键查出数据后再依赖前端隐藏。
通过接口完成验收
启动服务后,使用当前租户的访问令牌创建客户。示例中的端口、令牌和编号需要替换为实际值。
curl -i -X POST "http://localhost:<PORT>/api/customers" -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{
"orgId": 2001,
"customerNo": "C10001",
"customerName": "示例客户"
}'预期结果
HTTP/1.1 201 Created随后使用同一租户、具备组织 2001 权限的令牌查询,应能看到该客户;换成其他租户令牌访问该客户详情时,应返回 404,而不是 403,避免泄露“这条数据确实存在”。
验收时还要检查数据库中的 tenant_id 是否来自登录上下文,以及 SQL 日志中是否同时出现租户条件和组织条件。只验证页面看不到数据并不足够,因为前端过滤不能替代后端隔离。
常见实现错误
最危险的错误是只有列表接口加了租户条件,而详情、更新或删除仍按主键操作。第二类错误是把组织权限当成租户隔离:组织范围只能缩小当前租户内的数据,不能替代 tenant_id。第三类错误是在管理员场景中直接移除全部过滤条件,正确做法应是只放宽组织范围,租户边界仍然保留。
本课总结
- 业务读写必须同时应用租户边界和组织数据范围
tenant_id只能来自认证上下文,不能信任客户端输入- 列表、详情、更新和删除必须采用一致的隔离策略
下一课预告
下一课将为该模块建立自动化测试体系,分别验证权限计算、数据库过滤、接口行为和跨租户访问,避免隔离规则在重构中失效。