MyBatis-Plus的`@TableField(fill = FieldFill.IGNORE)`在多租户场景下为何不生效？

Question

在多租户场景下，`@TableField(fill = FieldFill.IGNORE)` 常被误认为可阻止字段自动填充（如 `tenant_id`），但实际**该注解仅作用于 MyBatis-Plus 的自动填充机制（`MetaObjectHandler`），对多租户插件（如 `TenantLineInnerInterceptor`）完全无效**。多租户插件通过 SQL 重写（如 `WHERE tenant_id = ?`）或 `INSERT`/`UPDATE` 自动追加租户条件，其执行时机早于字段填充逻辑，且不感知 `@TableField(fill = ...)` 注解。若开发者在实体中将 `tenant_id` 字段标注为 `IGNORE`，却仍期望它由多租户插件自动注入，就会导致插入/更新时该字段为 `null` 或默认值，引发数据越界或约束异常。根本原因在于：**`FieldFill.IGNORE` 控制的是“是否由 `MetaObjectHandler` 填充”，而非“是否参与 SQL 构建”——而多租户插件的字段注入是独立、强制的 SQL 层行为，与字段填充注解无任何耦合**。正确做法是：`tenant_id` 应移除 `fill` 注解，改用 `@TableField(fill = FieldFill.INSERT)` 配合自定义 `MetaObjectHandler`，或直接依赖多租户插件的 `tenantIdColumn` 配置统一管理。

Answer 1

```html

一、现象层：典型错误代码与运行表现

开发者常写出如下实体定义：

@TableName("sys_user")
public class SysUser {
    @TableId
    private Long id;
    
    private String username;
    
    // ❌ 误用：以为 IGNORE 能让多租户插件接管 tenant_id
    @TableField(fill = FieldFill.IGNORE)
    private Long tenantId;
}

配合 TenantLineInnerInterceptor 配置后，执行 userMapper.insert(user) 时，SQL 日志显示：

INSERT INTO sys_user (id, username, tenant_id) VALUES (?, ?, ?) —— 参数中 tenant_id 为 NULL

数据库抛出 NOT NULL constraint violation 或数据归属错误，租户隔离失效。

二、机制层：MyBatis-Plus 两大扩展点的执行时序与职责边界

下图清晰揭示关键执行顺序（基于 MyBatis-Plus 3.5+ 内部流程）：

graph LR
A[SQL 解析开始] --> B[多租户插件介入]
B -->|重写 SQL：追加 WHERE/INSERT VALUES tenant_id=?| C[生成最终 BoundSql]
C --> D[MetaObjectHandler 填充逻辑触发]
D -->|仅对 fill=INSERT/UPDATE 的字段生效| E[设置参数值]
E --> F[执行 JDBC]

可见：多租户插件在 SQL 构建阶段（BoundSql 生成期）注入 tenant_id；而 MetaObjectHandler 在参数绑定前（ParameterHandler 阶段）填充对象属性。二者处于不同拦截链路，无任何调用依赖。

三、原理层：@TableField(fill=...) 的真实作用域与设计契约

fill 值	触发时机	影响范围	是否影响 SQL 字段存在性
FieldFill.INSERT	insert 操作前	仅填充实体对象属性	否（字段仍需在 INSERT 列表中显式出现）
FieldFill.UPDATE	update 操作前	仅填充实体对象属性	否（WHERE 和 SET 中均不自动增删字段）
FieldFill.IGNORE	跳过 MetaObjectHandler 处理	仅跳过填充逻辑	❌ 完全不控制该字段是否出现在 INSERT/UPDATE SQL 中

因此，@TableField(fill = FieldFill.IGNORE) 的语义是：“请 MetaObjectHandler 忽略我”，而非：“请 SQL 构建器忽略我”或“请多租户插件接管我”——这是最根本的认知错位。

四、实践层：三种合规方案对比与选型建议

1. 方案一（推荐）：完全交由多租户插件管理
   移除 @TableField(fill = ...)，配置 tenantIdColumn = "tenant_id"，确保实体字段名与数据库列名一致；插件将自动完成 INSERT/UPDATE 的值注入与 WHERE 过滤。
2. 方案二：混合模式（兼容历史逻辑）
   保留 @TableField(fill = FieldFill.INSERT)，并在自定义 MetaObjectHandler 中显式赋值：metaObject.setValue("tenantId", TenantContext.getTenantId())；此时需禁用插件的 INSERT 自动注入（通过 ignoreInsertColumns 避免重复）。
3. 方案三：SQL 层强约束（高安全场景）
   数据库设 tenant_id DEFAULT current_setting('app.tenant_id')::BIGINT，应用层彻底不传该字段；配合插件的 tenantIdColumn + allowEmptyWhere=false 实现双重保障。

对于 SaaS 平台级系统，方案一具备最低侵入性、最高可维护性及最佳性能表现。

五、诊断层：快速识别该问题的四大信号

• 日志中出现 tenant_id = null 但预期非空
• 实体类中 tenantId 字段标注了 fill = IGNORE 却未在业务代码中手动赋值
• 启用多租户插件后，SELECT 正常（WHERE 自动追加），但 INSERT 报约束异常
• 调试发现 MetaObjectHandler 的 insertFill 方法从未被调用到该字段

以上任一信号组合出现，即可高度怀疑本问题。

```