MyBatis-Plus逻辑删除配置全攻略（从入门到生产级实战）

第一章：MyBatis-Plus逻辑删除查询过滤概述

在现代企业级应用开发中，数据安全与历史记录的保留至关重要。MyBatis-Plus 作为 MyBatis 的增强工具，在简化 CRUD 操作的同时，提供了逻辑删除功能，避免物理删除带来的数据丢失风险。逻辑删除通过标记字段（如 `deleted`）来标识数据是否“已删除”，从而在查询时自动过滤掉这些记录。

逻辑删除的基本原理

MyBatis-Plus 在执行查询操作时，会自动拼接逻辑删除字段的过滤条件。例如，当配置了 `deleted = 0` 表示未删除时，所有 `select` 语句都会附加 `WHERE deleted = 0` 条件，确保被逻辑删除的数据不会出现在结果集中。

配置方式与字段约定

逻辑删除功能需在实体类和全局配置中同时声明。通常使用注解 `@TableLogic` 标识逻辑删除字段，并在配置文件中指定值映射关系。

// 实体类中定义逻辑删除字段
public class User {
    private Long id;
    private String name;
    
    @TableLogic
    private Integer deleted; // 0-未删除，1-已删除
}

在 Spring Boot 配置文件中启用逻辑删除：

mybatis-plus:
  global-config:
    db-config:
      logic-delete-value: 1
      logic-not-delete-value: 0

查询过滤的自动应用

一旦启用逻辑删除，以下操作将自动生效：

• 调用 selectList 等方法时，SQL 自动追加删除状态过滤
• update 和 delete 操作也会受逻辑删除状态影响，防止对已删数据重复操作
• 使用 selectById 查询已被逻辑删除的记录将返回 null

操作类型	是否自动过滤已删除数据
select*	是
update	是（基于未删除记录）
delete	转为更新 deleted 字段

第二章：逻辑删除查询过滤的核心机制解析

2.1 逻辑删除的基本原理与MyBatis-Plus集成方式

逻辑删除是一种通过标记字段而非物理移除记录来实现数据“删除”效果的设计模式，常用于需要保留历史数据的业务场景。在 MyBatis-Plus 中，通过 `@TableLogic` 注解可快速实现该机制。

注解配置示例

@TableField("is_deleted")
@TableLogic
private Integer deleted;

上述代码中，`is_deleted` 字段用于标识数据状态：0 表示未删除，1 表示已删除。MyBatis-Plus 在执行删除或查询操作时，自动拼接 `WHERE is_deleted = 0` 条件，并将删除操作转为更新该字段值。

全局配置参数

• insert-value：插入时默认填充值，如 0
• delete-value：删除时更新为目标值，如 1
• select-ignore：查询时自动过滤已删除数据

通过 application.yml 配置即可统一管理行为，提升开发效率与一致性。

2.2 全局配置中查询过滤的实现逻辑分析

在全局配置中，查询过滤机制通过中间件拦截请求参数，结合预定义规则对查询条件进行规范化处理。

过滤规则解析流程

系统启动时加载 YAML 配置文件中的过滤策略，构建字段白名单与操作符限制映射表。

// 示例：过滤规则结构体定义
type FilterRule struct {
    Field     string   `yaml:"field"`     // 允许过滤的字段名
    Operators []string `yaml:"operators"` // 支持的操作符 in, eq, like
}

上述代码定义了基本过滤规则模型，Field 表示可被过滤的目标字段，Operators 限定该字段允许使用的比较操作类型，防止非法查询构造。

请求处理链路

• 接收 HTTP 请求中的 query 参数
• 匹配路由对应实体的过滤策略
• 校验字段是否在白名单内
• 转换为数据库原生查询语句

2.3 自动注入SQL条件背后的执行流程剖析

在现代ORM框架中，自动注入SQL条件的核心在于运行时动态构建查询语句。该机制通常依托于拦截器或注解处理器，在SQL执行前对原始语句进行改写。

执行流程关键阶段

1. 解析上下文中的安全上下文（如用户租户ID）
2. 匹配当前操作的数据表与需注入的过滤字段
3. 重构AST（抽象语法树）或直接拼接WHERE子句
4. 执行修改后的SQL并返回结果

代码示例：条件注入逻辑

// 拦截查询方法
@Intercepts({@Signature(type = Executor.class, method = "query", ...)})
public class TenantInjectInterceptor implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // 获取当前用户租户ID
        String tenantId = SecurityContext.getTenantId();
        // 解析原SQL并注入 tenant_id = ? 条件
        BoundSql boundSql = ((MappedStatement)invocation.getArgs()[0])
            .getBoundSql(invocation.getArgs()[1]);
        String modifiedSql = injectTenantCondition(boundSql.getSql(), tenantId);
        // 执行新SQL
        return invocation.proceed();
    }
}

上述代码通过MyBatis拦截器机制，在不修改业务代码的前提下，自动为所有查询添加租户隔离条件。参数tenantId来自会话上下文，在SQL解析阶段被安全注入，确保数据访问边界。

2.4 实体字段注解@TableLogic的作用与生效时机

逻辑删除的核心机制

在持久层框架中，@TableLogic 注解用于标识实体类中表示逻辑删除状态的字段。该注解通常应用于布尔类型或整型字段，标记数据是否已被“软删除”。

@TableLogic
private Integer deleted;

上述代码中，deleted 字段被标注为逻辑删除字段。默认情况下，未删除状态值为 0，删除后值为 1。

自动拦截与SQL改写

当执行查询操作时，框架会自动在 SQL 的 WHERE 条件中添加逻辑未删除的过滤条件。例如：

• 查询语句自动追加 AND deleted = 0
• 删除操作被转换为更新语句，设置 deleted = 1

操作类型	实际行为
select	自动过滤已删除记录
delete	更新 deleted 字段值

该注解在执行 CRUD 操作时由 MyBatis-Plus 自动解析并生效，无需手动干预。

2.5 多租户场景下逻辑删除过滤的兼容性探讨

在多租户系统中，数据隔离与逻辑删除机制需协同工作。当不同租户共享同一数据表时，逻辑删除标记（如 deleted_at）必须与租户ID（tenant_id）联合使用，避免跨租户的数据泄露或误过滤。

查询过滤策略

通用查询需自动注入双层过滤条件：

SELECT * FROM orders 
WHERE tenant_id = 'T1001' 
  AND deleted_at IS NULL;

该语句确保仅返回当前租户未被逻辑删除的数据。若全局启用软删除，ORM 层应自动附加 tenant_id 和 deleted_at 条件，减少手动干预风险。

权限与索引优化

• 复合索引 (tenant_id, deleted_at) 显著提升查询性能；
• 租户上下文须在请求链路中传递，确保过滤条件可依赖；
• 超级管理员跨租户查询时，需显式绕过租户过滤，但仍应尊重删除状态。

第三章：配置与使用实践

3.1 application.yml中逻辑删除属性的正确配置方法

在使用MyBatis-Plus等ORM框架时，逻辑删除功能需在application.yml中正确配置相关属性，以实现数据的软删除。

核心配置项说明

mybatis-plus:
  global-config:
    db-config:
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

上述配置中，logic-delete-field指定逻辑删除字段名；logic-delete-value表示已删除状态值；logic-not-delete-value表示未删除状态值。框架在执行删除操作时，会自动将该字段更新为1，查询时自动添加deleted = 0条件。

注意事项

• 数据库表必须包含对应字段（如deleted），且默认值为0
• 实体类中建议添加@TableLogic注解标记该字段
• 确保版本兼容性，低版本可能不支持部分配置项

3.2 实体类中逻辑删除字段的定义与类型选择

在持久化实体设计中，逻辑删除字段用于标记数据是否被“软删除”，避免物理删除带来的数据丢失。常见的字段名为 `deleted` 或 `is_deleted`。

字段类型对比

• 布尔型（boolean）：语义清晰，适合只有“存在”和“已删”两种状态的场景；
• 整数型（int）：支持多级删除状态（如：0-正常，1-用户删除，2-管理员删除）；
• 时间戳（timestamp）：可记录删除时间，推荐使用 TIMESTAMP 或 DATETIME 类型。

代码示例

/**
 * 用户实体类
 */
@Entity
public class User {
    @Id
    private Long id;

    private String name;

    /**
     * 逻辑删除标记：0-未删除，1-已删除
     */
    private Integer deleted = 0;

    // getter and setter
}

上述示例采用整型字段 deleted，便于数据库索引优化与状态扩展，配合 MyBatis-Plus 等框架可自动识别该字段实现逻辑删除拦截。

3.3 自定义值处理：从默认0/1到Boolean或枚举类型的扩展

在现代ORM框架中，数据库字段的值通常以0或1存储布尔状态，但应用层更倾向于使用Boolean类型或自定义枚举值提升可读性。

类型映射配置示例

// 定义支持true/false与1/0互转的布尔类型
type CustomBool bool

func (c CustomBool) Value() (driver.Value, error) {
    if c {
        return 1, nil
    }
    return 0, nil
}

func (c *CustomBool) Scan(value interface{}) error {
    val, _ := value.(int64)
    *c = val == 1
    return nil
}

上述代码通过实现driver.Valuer和sql.Scanner接口，完成数据库整型与Go语言布尔类型的双向转换。

枚举类型扩展支持

• 定义业务状态枚举：如订单状态（待支付、已发货、已完成）
• 通过字符串或数值映射数据库字段值
• 增强代码语义性和维护性

第四章：高级应用场景与问题规避

4.1 联表查询中逻辑删除字段的手动过滤策略

在进行多表关联查询时，若涉及逻辑删除字段（如 `is_deleted`），需手动添加过滤条件以排除已标记删除的记录，确保数据一致性。

过滤条件的显式声明

在 SQL 查询中，应显式指定各表的逻辑删除状态：

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

上述代码通过 WHERE u.is_deleted = 0 AND o.is_deleted = 0 显式过滤出未删除的用户及其订单，避免脏数据参与联表运算。

通用化处理建议

• 所有关联表均需检查逻辑删除字段
• 建议在 ORM 层封装全局作用域，但复杂联查仍需手动控制
• 避免依赖数据库默认值，应明确写入判断条件

4.2 使用Wrapper时绕过或强制启用删除过滤的控制技巧

在使用ORM Wrapper操作数据库时，软删除机制常通过自动附加`deleted_at IS NULL`条件实现。然而，在特定场景下需绕过该过滤以访问历史数据。

强制查询包含已删除记录

可通过禁用默认作用域来实现：

db.Unscoped().Where("name = ?", "example").Find(&records)

Unscoped() 方法会移除所有软删除过滤，适用于数据恢复或审计日志等场景。

条件性启用删除过滤

若需根据业务逻辑动态控制，可结合作用域封装：

func WithDeleted(filter bool) func(*gorm.DB) *gorm.DB {
    return func(db *gorm.DB) *gorm.DB {
        if !filter {
            return db.Unscoped()
        }
        return db
    }
}

此模式允许在调用链中灵活注入是否启用删除过滤，提升数据访问的可控性与复用性。

4.3 性能影响评估：索引设计与查询优化建议

在数据库性能调优中，合理的索引设计直接影响查询效率。不恰当的索引会增加写操作开销，并占用额外存储空间。

索引选择原则

应优先为频繁用于 WHERE、JOIN 和 ORDER BY 的列创建索引。复合索引需遵循最左前缀原则。

• 避免在低选择性字段（如性别）上建立单列索引
• 覆盖索引可减少回表次数，提升查询性能

执行计划分析

使用 EXPLAIN 分析 SQL 执行路径：

EXPLAIN SELECT user_id, name FROM users WHERE age > 25 AND dept_id = 10;

该语句应利用 (dept_id, age) 的复合索引。若执行计划显示 "type=ALL" 或 "Using filesort"，则需优化索引结构或重写查询。

查询优化建议

问题类型	优化策略
全表扫描	添加针对性索引
临时表排序	使用覆盖索引避免回表

4.4 常见误区与典型Bug排查（如null值判断、缓存污染）

null值处理不当引发空指针异常

开发中常因忽略对象或返回值为null导致运行时异常。尤其在RPC调用或JSON反序列化场景，未校验null直接调用方法极易触发NPE。

if (user != null && user.getProfile() != null) {
    System.out.println(user.getProfile().getEmail());
}

上述代码通过双重判空规避风险，推荐使用Optional提升可读性。

缓存污染导致数据不一致

缓存未及时失效或键冲突会造成脏数据。例如同一key被不同业务写入结构不同的对象，反序列化时抛出类型转换异常。

问题	原因	解决方案
缓存穿透	查询不存在的数据	布隆过滤器+空值缓存
缓存雪崩	大量key同时过期	随机过期时间+高可用集群

第五章：生产环境下的最佳实践总结

配置管理与环境隔离

在生产环境中，统一的配置管理是系统稳定运行的基础。推荐使用集中式配置中心（如 Consul 或 Apollo），避免硬编码敏感信息。通过环境变量区分开发、测试与生产配置。

• 数据库连接字符串应通过环境变量注入
• 密钥管理建议集成 Hashicorp Vault
• 配置变更需支持热更新，减少重启频率

日志与监控策略

结构化日志输出能显著提升故障排查效率。以下为 Go 服务中推荐的日志格式示例：

log.JSON("event", "user_login",
    "uid", userID,
    "ip", clientIP,
    "status", "success")

所有服务必须接入统一监控平台（如 Prometheus + Grafana），关键指标包括： - 请求延迟 P99 - 每秒请求数（QPS） - 错误率阈值告警

部署与回滚机制

采用蓝绿部署或金丝雀发布降低上线风险。Kubernetes 环境下建议配置就绪探针与存活探针：

探针类型	初始延迟	检查周期	超时时间
liveness	30s	10s	5s
readiness	10s	5s	3s

[用户请求] → [API网关] → [服务A] → [数据库] ↓ [事件队列] → [异步任务处理]