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

租户字段规范

租户字段规范

本课把多租户隔离落实到业务表字段:统一 tenant_id 的类型、命名、非空约束与写入规则,并通过可执行 SQL 验证约束是否真正生效。完成后,你可以建立一套可复用的租户字段规范,避免空租户、类型不一致和默认值误用导致的数据串租。

学习目标

  • 统一业务表中 tenant_id 的字段名称、类型和约束
  • 理解为什么租户字段通常不应设置业务默认值
  • 能通过建表与插入测试验证租户字段规范

统一字段定义

所有需要租户隔离的业务表都使用 tenant_id,不要混用 tenantId、tenant_code、org_id 等名称。统一命名能让 ORM 拦截器、SQL 审计、数据迁移和代码生成器使用同一套规则。

在 MySQL 中,若租户主键采用无符号整数,业务表也应使用完全一致的类型。下面以 BIGINT UNSIGNED 为例;若租户表使用字符串编码,业务表也必须保持相同长度、字符集和排序规则。

推荐定义如下:

sql
CREATE DATABASE IF NOT EXISTS saas_demo
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

USE saas_demo;

DROP TABLE IF EXISTS tenant_order;

CREATE TABLE tenant_order (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    tenant_id BIGINT UNSIGNED NOT NULL COMMENT '租户主键',
    order_no VARCHAR(64) NOT NULL,
    amount DECIMAL(12, 2) NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY idx_tenant_created_at (tenant_id, created_at)
) ENGINE = InnoDB;

这段 DDL 的生效行为是:每条订单必须显式携带租户编号,且租户字段类型与租户主键保持一致。可使用 SHOW CREATE TABLE tenant_order; 检查最终定义。

非空约束与默认值

tenant_id 应设置为 NOT NULL。允许空值会产生“无归属数据”,后续查询即使追加 tenant_id = ?,也无法自然覆盖这些记录,最终只能依赖人工修复。

通常不要为 tenant_id 设置 DEFAULT 0、固定租户号或自动生成值。默认值会掩盖调用方漏传租户上下文的问题,使错误数据悄悄写入公共租户或错误租户。正确做法是让数据库立即拒绝不完整写入。

执行下面的验证 SQL:

sql
USE saas_demo;

INSERT INTO tenant_order (order_no, amount)
VALUES ('ORDER-001', 99.00);

预期结果:

text
ERROR 1364 (HY000): Field 'tenant_id' doesn't have a default value

不同 MySQL 客户端可能附带连接信息,但核心结果应是插入失败,并明确指出 tenant_id 没有默认值。

再执行一条完整写入:

sql
USE saas_demo;

INSERT INTO tenant_order (tenant_id, order_no, amount)
VALUES (1001, 'ORDER-001', 99.00);

SELECT id, tenant_id, order_no, amount
FROM tenant_order
WHERE tenant_id = 1001;

预期结果:

text
id  tenant_id  order_no   amount
1   1001       ORDER-001  99.00

实际自增 id 可能不同,但结果中必须保留正确的 tenant_id,且查询条件明确包含租户维度。

写入、查询与适用范围

租户直接拥有的数据表必须包含 tenant_id,例如订单、商品、客户、门店、员工和租户级配置。判断标准不是表名,而是“不同租户是否可能保存彼此独立的数据”。平台级公共字典可以不带租户字段,但不要用空 tenant_id 在同一张表中混合公共数据和租户数据。

关联表也要单独判断。若关联关系本身属于租户,例如“租户用户与门店关系”,关联表应包含 tenant_id,并在写入时校验两端对象都属于同一租户。

应用层应从已认证的租户上下文获取 tenant_id,而不是直接相信客户端请求体。客户端可以传业务对象编号,但最终租户编号应由网关、认证信息或服务端会话确定。

新增、修改、删除和查询都必须带租户条件。即使通过主键查询,也应同时限定 tenant_id,因为全局自增主键只能保证记录唯一,不能证明调用方有权访问该记录。

Tips:数据库非空约束负责阻止漏写,应用层租户拦截器负责自动追加条件,两者应同时存在。只依赖其中一层,都容易在批处理、原生 SQL 或维护脚本中留下缺口。

本课总结

  • 租户业务表统一使用与租户主键类型一致的 tenant_id
  • tenant_id 应为 NOT NULL,并避免使用会掩盖错误的业务默认值
  • 写入和查询都必须从可信上下文取得并限制租户维度

下一课预告

下一课将把租户维度纳入唯一约束和联合索引,解决不同租户可复用业务编号,同时保证高频租户查询能够稳定命中索引。

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

目录与阅读设置

阅读设置

17

记录一个想法

租户字段规范

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

登录哪都通