揭秘MyBatis-Plus逻辑删除查询过滤：3种常见误用及最佳实践方案-优快云博客

第一章：揭秘MyBatis-Plus逻辑删除查询过滤的核心机制

MyBatis-Plus 通过内置的逻辑删除功能，能够在不真正删除数据库记录的前提下，实现数据的“软删除”。其核心机制依赖于自动注入的 SQL 过滤器，在执行查询时动态拼接条件，排除已被标记为删除的数据。

逻辑删除字段配置

在实体类中，需通过注解指定逻辑删除字段。MyBatis-Plus 使用 @TableLogic 注解标识该字段：


public class User {
    private Long id;
    private String name;
    
    @TableLogic
    private Integer deleted; // 0-未删除，1-已删除
}

上述代码中，deleted 字段被标注为逻辑删除字段，框架在生成 SQL 时会自动添加过滤条件。

查询时的SQL自动过滤原理

当执行如 selectList() 或 updateById() 等操作时，MyBatis-Plus 会在原有 SQL 条件基础上追加 AND deleted = 0（默认值），从而屏蔽已删除数据。例如：


SELECT id, name, deleted FROM user WHERE deleted = 0;

此过程由 MyBatis-Plus 的自动填充机制与元对象处理器（MetaObjectHandler）协同完成，开发者无需手动编写过滤逻辑。

自定义逻辑删除值

可通过全局配置修改逻辑删除的数值对应关系。支持在配置文件中设置：

未删除值，如：0
已删除值，如：1

状态	对应值
正常（未删除）	0
已删除	1

该机制确保业务数据安全可追溯，同时对上层调用完全透明，极大提升了开发效率与系统健壮性。

第二章：MyBatis-Plus逻辑删除的3种常见误用场景剖析

2.1 未全局配置逻辑删除字段导致查询遗漏

在使用 ORM 框架时，若未全局启用逻辑删除功能，被标记为“已删除”的记录仍可能出现在常规查询结果中，造成数据污染。

问题表现

实体虽设置了 `deleted_at` 字段，但未在框架层面注册逻辑删除策略，导致查询未自动附加 `deleted_at IS NULL` 条件。

解决方案示例（GORM）


type User struct {
    ID        uint
    Name      string
    DeletedAt gorm.DeletedAt `gorm:"index"`
}

通过引入 `gorm.DeletedAt` 类型并添加索引，GORM 自动识别该字段并实现软删除。所有查询将默认忽略已删除记录。

配置建议

在模型中统一定义逻辑删除字段
确保全局初始化时加载软删除插件或配置
测试边界场景：物理删除与恢复逻辑

2.2 自定义SQL中忽略逻辑删除条件引发数据泄露

在使用MyBatis等ORM框架时，逻辑删除通常通过字段（如 `deleted = 1`）标记数据。但自定义SQL若未显式添加该条件，可能导致已“删除”数据被查询返回，造成数据泄露。

典型问题场景

开发者编写自定义SQL时，容易忽略全局逻辑删除插件的生效前提——需依赖标准Wrapper或自动注入条件。手写SQL绕过了这一机制。

SELECT id, name, email FROM users WHERE department_id = #{deptId}

上述语句未包含 `AND deleted = 0`，导致已删除用户信息被暴露。

解决方案

手动补全逻辑删除条件：所有自定义SQL必须显式添加 `AND deleted = 0`
使用MyBatis-Plus的@SqlParser(filter = true)注解控制解析行为

方式	是否安全	说明
标准QueryWrapper	是	自动注入逻辑删除条件
自定义SQL无条件	否	需手动添加deleted过滤

2.3 多表关联查询时逻辑删除过滤失效问题

在多表关联查询中，若仅对主表应用逻辑删除过滤（如 `is_deleted = 0`），而忽略关联表的过滤条件，可能导致已标记删除的无效数据被错误关联。

典型问题场景

例如用户表与订单表联查时，用户已被逻辑删除，但其关联订单仍可被查出，破坏数据一致性。

解决方案示例

需在关联表的 ON 条件中显式添加逻辑删除过滤：

SELECT u.name, o.amount
FROM users u
LEFT JOIN orders o ON u.id = o.user_id AND o.is_deleted = 0
WHERE u.is_deleted = 0;

上述 SQL 确保用户及其订单均排除已删除记录。关键在于将 `is_deleted = 0` 条件嵌入 JOIN 的 ON 子句，而非仅置于 WHERE 中，否则 LEFT JOIN 会退化为 INNER JOIN 效果。

只在 WHERE 过滤：无法阻止已删订单参与连接
在 ON 中过滤：确保关联时即排除无效数据

2.4 使用Wrapper构造器时绕过逻辑删除规则

在某些特殊场景下，需要查询包含已被逻辑删除的记录。MyBatis-Plus 提供了 `Wrapper` 构造器，通常会自动忽略 `is_deleted = 1` 的数据。但可通过自定义条件绕过该规则。

手动添加删除标记条件

使用 `eq` 方法显式包含已删除记录：


QueryWrapper<User> wrapper = new QueryWrapper<>();
wrapper.eq("is_deleted", 1); // 查询已删除的用户
List<User> deletedUsers = userMapper.selectList(wrapper);

上述代码强制将 `is_deleted = 1` 作为查询条件，突破默认的数据过滤机制，适用于回收站或审计功能。

组合条件控制数据可见性

通过动态拼接条件实现灵活控制：

查询全部状态：不添加 `is_deleted` 条件
仅查有效数据：依赖全局逻辑删除配置
专查已删数据：手动指定 `is_deleted = 1`

2.5 动态表名或分表场景下逻辑删除适配缺失

在使用 MyBatis-Plus 等 ORM 框架时，逻辑删除功能依赖于固定的实体映射关系。然而，在动态表名或分库分表场景中，表结构可能按时间、租户等维度拆分，导致框架无法自动识别目标表的 `deleted` 字段。

典型问题表现

当执行删除操作时，MyBatis-Plus 会尝试对主实体对应的表执行 `UPDATE SET deleted = 1`，但若实际数据分布在 `order_2024`、`order_2025` 等子表中，则原生逻辑删除机制失效。

解决方案示例

需结合 AOP 或自定义 SQL 拦截器动态改写 DELETE 语句：


@Intercepts(@Signature(type = Executor.class, method = "update", args = {MappedStatement.class, Object.class}))
public class LogicDeleteInterceptor implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        MappedStatement ms = (MappedStatement) invocation.getArgs()[0];
        Object param = invocation.getArgs()[1];
        // 解析动态表名并注入 soft delete 逻辑
        String tableName = parseDynamicTable(param);
        BoundSql boundSql = ms.getBoundSql(param);
        // 构造 UPDATE 替代 DELETE
        String sql = "UPDATE " + tableName + " SET is_deleted = 1 WHERE id = ?";
        // ...
        return invocation.proceed();
    }
}

上述拦截器通过替换原始 DELETE 为 UPDATE 操作，实现跨分表的统一逻辑删除语义，确保数据可追溯。

第三章：深入理解MyBatis-Plus逻辑删除的工作原理

3.1 全局配置与字段注解的协同机制解析

在现代配置驱动的框架中，全局配置与字段注解形成了一套高效的协同机制。全局配置定义系统级默认行为，而字段注解则提供细粒度的局部覆盖能力。

配置优先级机制

当两者同时存在时，遵循“就近原则”：字段注解 > 局部配置 > 全局配置。这种层级结构确保灵活性与统一性并存。

代码示例：注解与配置融合


type User struct {
    ID   int `config:"required,max=100"`
    Name string `config:"default=guest"`
}

上述代码中，config 注解声明了字段约束。框架在初始化时会解析这些注解，并与全局配置（如 DefaultRequired=true）合并，构建最终校验规则。

协同工作流程

1. 加载全局配置文件（如 YAML）
2. 扫描结构体字段注解
3. 合并配置项，应用覆盖逻辑
4. 生成运行时元数据供调用链使用

3.2 SQL自动注入原理与执行流程追踪

SQL自动注入利用程序对用户输入过滤不严的漏洞，将恶意SQL语句拼接到原始查询中，诱导数据库执行非预期操作。攻击者常通过表单、URL参数等输入点注入构造语句。

典型注入示例

SELECT * FROM users WHERE username = 'admin' OR '1'='1'; --' AND password = 'xxx'

该语句通过闭合原查询条件并引入恒真逻辑（'1'='1'），绕过身份验证。注释符--屏蔽后续代码，确保语法正确。

执行流程解析

应用接收用户输入未做转义处理
恶意字符串拼接至SQL模板形成新逻辑
数据库解析并执行篡改后的语句
返回敏感数据或执行写入、删除等操作

常见注入类型对比

类型	触发方式	危害等级
基于布尔的盲注	通过真假响应推断数据	高
时间延迟注入	利用延时函数探测	高
联合查询注入	直接合并结果集	极高

3.3 逻辑删除在MetaObjectHandler中的底层实现

自动填充机制与逻辑删除字段

MyBatis-Plus通过MetaObjectHandler接口实现字段的自动填充。在逻辑删除场景中，该处理器可在插入或更新时自动设置deleted字段的默认值。

public class MyMetaObjectHandler implements MetaObjectHandler {
    @Override
    public void insertFill(MetaObject metaObject) {
        this.strictInsertFill(metaObject, "deleted", Integer.class, 0);
    }
}

上述代码确保新记录的deleted字段初始化为0，表示未删除状态，为后续逻辑删除操作提供基础。

删除标记的统一管理

通过全局配置logic-delete-value和logic-not-delete-value，框架在执行删除操作时将SQL语句中的DELETE转换为UPDATE，并自动设置deleted=1，实现数据可见性控制。

第四章：逻辑删除查询过滤的最佳实践方案

4.1 正确配置全局逻辑删除策略与字段映射

在现代ORM框架中，逻辑删除是保障数据安全与可追溯性的关键机制。通过统一配置全局策略，可避免物理删除带来的数据丢失风险。

启用全局逻辑删除

以MyBatis-Plus为例，需在配置类中注册逻辑删除插件：


@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
    MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
    LogicalDeleteInnerInterceptor logicalDeleteInterceptor = new LogicalDeleteInnerInterceptor();
    interceptor.addInnerInterceptor(logicalDeleteInterceptor);
    return interceptor;
}

该插件会自动将标记为逻辑删除的字段纳入SQL过滤条件，查询时排除已删除记录。

字段映射配置

实体类中通过注解指定删除字段及值：

@TableLogic(value = "0", delval = "1")：表示未删除为0，删除时更新为1
字段类型支持Integer、Boolean、LocalDateTime等

数据库表需存在对应字段（如deleted），并与实体映射一致，确保运行时行为准确。

4.2 在自定义SQL中安全集成逻辑删除条件

在编写自定义SQL时，必须显式处理逻辑删除字段（如 `deleted_at`），避免误查已软删除数据。忽略该条件可能导致数据泄露或业务异常。

基础查询规范

所有涉及逻辑删除表的查询应包含状态过滤：

SELECT id, name 
FROM users 
WHERE deleted_at IS NULL 
  AND status = 'active';

此条件确保仅返回有效记录，deleted_at IS NULL 是软删除的核心判断依据。

参数化与复用建议

将通用条件抽象为视图或公共表表达式（CTE）
使用ORM提供的作用域机制自动注入条件
禁止拼接SQL字符串，防止SQL注入

4.3 多表联查中保障逻辑删除一致性的编码规范

在多表联查场景中，若涉及逻辑删除字段（如 `is_deleted`），必须确保所有关联表的查询条件统一过滤已删除记录，避免数据不一致。

统一查询过滤条件

所有 JOIN 操作需显式添加 `ON t1.id = t2.ref_id AND t2.is_deleted = 0`，防止已删除数据参与关联。

代码实现示例

SELECT u.name, o.order_sn
FROM users u
LEFT JOIN orders o ON u.id = o.user_id AND o.is_deleted = 0
WHERE u.is_deleted = 0;

该查询确保用户与订单均未被逻辑删除。若忽略 `o.is_deleted = 0`，可能导致返回已删除订单数据，破坏业务一致性。

4.4 利用插件机制扩展逻辑删除的可控性与灵活性

在现代ORM框架中，逻辑删除常通过插件机制实现解耦。通过注册删除策略插件，开发者可动态控制删除行为。

插件注册示例

type SoftDeletePlugin struct{}

func (p *SoftDeletePlugin) BeforeDelete(db *gorm.DB) {
    db.Statement.SetColumn("deleted_at", time.Now())
}

该插件在执行删除前自动注入deleted_at字段赋值逻辑，避免硬编码。

灵活策略切换

软删除：标记删除时间
硬删除：物理清除数据
归档删除：迁移至历史表

不同环境加载不同插件，实现行为热替换。

执行流程控制

Hook → 插件链 → 条件判断 → 执行策略

通过中间件模式串联多个插件，按优先级生效，提升扩展性。

第五章：总结与企业级应用建议

构建高可用微服务架构的实践路径

在金融交易系统中，服务稳定性至关重要。某头部券商采用 Kubernetes 部署 Go 微服务时，通过 Pod 反亲和性策略实现跨节点容灾：


apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchExpressions:
                    - key: app
                      operator: In
                      values:
                        - trade-service
                topologyKey: kubernetes.io/hostname