MyBatis-Plus逻辑删除注解@TableLogic详解与实践

1. @TableLogic注解的本质解析

逻辑删除是数据持久层设计中常见的软删除方案，@TableLogic作为MyBatis-Plus框架的核心注解，通过简单的字段标记即可实现数据的状态化管理。与物理删除不同，逻辑删除会在数据库保留原始数据记录，仅通过状态字段标识数据是否有效。

1.1 注解的底层实现机制

当我们在实体类字段添加@TableLogic注解时，MyBatis-Plus会在SQL层面自动进行以下转换：

• 删除操作：DELETE FROM table → UPDATE table SET deleted=1
• 查询操作：SELECT * FROM table → SELECT * FROM table WHERE deleted=0

这种转换通过MyBatis-Plus的SQL注入器实现，在运行时动态改写SQL语句。框架内置的LogicSqlInjector会处理所有带有@TableLogic注解的字段，确保CRUD操作都遵循逻辑删除规则。

1.2 核心参数配置详解

注解支持两个关键参数：

java复制@TableLogic(
    value = "0",         // 未删除状态值（默认0）
    delval = "1"         // 已删除状态值（默认1）
)
private Integer deleted;

实际项目中常见的配置变体包括：

• 布尔类型：value="false", delval="true"
• 时间戳：delval="NOW()"（记录删除时间）
• 枚举值：value="ACTIVE", delval="DELETED"

注意：delval值必须与数据库字段类型兼容。若使用字符串状态值，需添加单引号：delval="'deleted'"

2. 生产环境中的最佳实践

2.1 多租户场景下的隔离方案

在SaaS系统中，逻辑删除字段需要与tenant_id联合使用：

sql复制-- 错误示例（可能导致数据越权）
UPDATE orders SET deleted=1 WHERE id=100

-- 正确写法
UPDATE orders SET deleted=1 WHERE id=100 AND tenant_id=123

建议通过自定义SQL注入器增强基础功能：

java复制public class TenantLogicSqlInjector extends LogicSqlInjector {
    @Override
    public void injectSqlRunner(Class<?> mapperClass) {
        super.injectSqlRunner(mapperClass);
        // 添加租户过滤条件
    }
}

2.2 审计字段的联动处理

通常逻辑删除需要与审计字段配合使用：

java复制@TableField(fill = FieldFill.UPDATE)
private LocalDateTime deleteTime;

@TableField(fill = FieldFill.UPDATE)
private Long deleteUserId;

建议使用MetaObjectHandler统一处理：

java复制@Override
public void updateFill(MetaObject metaObject) {
    if (metaObject.hasSetter("deleteTime")) {
        strictUpdateFill(metaObject, "deleteTime", LocalDateTime::now, LocalDateTime.class);
    }
}

3. 性能优化与疑难排查

3.1 索引设计要点

逻辑删除字段必须纳入索引策略：

• 联合索引应将deleted字段放在最后：INDEX idx_status_deleted (status, deleted)
• 全表扫描场景添加deleted条件：FORCE INDEX (idx_deleted) WHERE deleted=0

3.2 常见异常解决方案

问题1：@Param注解与逻辑删除冲突

java复制// 错误用法
@Delete("DELETE FROM user WHERE id=#{id}")
int physicalDelete(@Param("id") Long id);

// 正确方案：使用@InterceptorIgnore或XML配置
@InterceptorIgnore(tenantLine = "true", logicDelete = "true")

问题2：联表查询遗漏删除条件

sql复制/* 错误示例 */
SELECT u.*, o.* 
FROM user u LEFT JOIN order o ON u.id=o.user_id

/* 正确写法 */
SELECT u.*, o.* 
FROM user u LEFT JOIN order o ON u.id=o.user_id 
WHERE u.deleted=0 AND (o.deleted=0 OR o.id IS NULL)

4. 高级应用场景

4.1 历史数据归档方案

通过定时任务将逻辑删除的数据转移到历史表：

java复制@Scheduled(cron = "0 0 3 * * ?")
public void archiveDeletedData() {
    // 1. 查询逻辑删除超过30天的数据
    LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>()
        .eq(User::getDeleted, 1)
        .le(User::getUpdateTime, LocalDateTime.now().minusDays(30));
    
    // 2. 批量插入到history_user表
    // 3. 从主表物理删除
}

4.2 多状态删除设计

对于需要区分删除类型的场景：

java复制@TableLogic(
    value = "0",
    delval = "CASE WHEN #{type}='user' THEN 1 ELSE 2 END"
)
private Integer deleted;

配合自定义SQL解析器实现动态逻辑：

java复制public class DynamicLogicDeleteParser extends AbstractLogicDeleteParser {
    @Override
    public String getLogicDeleteSql(TableInfo tableInfo) {
        // 根据线程变量返回不同的删除SQL
    }
}

5. 与其他框架的整合

5.1 Spring Data JPA兼容方案

通过Hibernate过滤器实现逻辑删除：

java复制@FilterDef(
    name = "activeFilter",
    parameters = @ParamDef(name = "deleted", type = "boolean")
)
@Filter(
    name = "activeFilter",
    condition = "deleted = :deleted"
)
@Entity
public class User {
    @Convert(converter = BooleanToIntegerConverter.class)
    private Boolean deleted;
}

5.2 与QueryDSL集成

自定义SQLTemplates支持逻辑删除：

java复制public class MyBatisPlusTemplates extends SQLTemplates {
    public MyBatisPlusTemplates() {
        super("\\", "`", Escaping.DEFAULT);
        // 重写DELETE子句生成逻辑
    }
}

实际查询时需要手动添加条件：

java复制QUser user = QUser.user;
BooleanExpression notDeleted = user.deleted.eq(0);

6. 监控与治理

6.1 删除操作审计日志

通过MyBatis插件记录删除行为：

java复制@Intercepts({
    @Signature(type= Executor.class, method="update", 
        args={MappedStatement.class,Object.class})
})
public class DeleteAuditInterceptor implements Interceptor {
    @Override
    public Object intercept(Invocation invocation) {
        // 解析MappedStatement判断是否逻辑删除操作
        // 记录操作日志
    }
}

6.2 删除比例告警

监控逻辑删除数据占比：

sql复制-- 每日删除率监控
SELECT 
    table_name,
    COUNT(CASE WHEN deleted=1 THEN 1 END)*100.0/COUNT(*) AS delete_ratio
FROM 
    information_schema.tables
GROUP BY 
    table_name
HAVING 
    delete_ratio > 10.0  -- 阈值

建议在数据库层面设置触发器告警：

sql复制CREATE TRIGGER check_delete_ratio
AFTER UPDATE ON important_table
FOR EACH ROW
BEGIN
    DECLARE ratio DECIMAL(5,2);
    SELECT COUNT(*)/total INTO ratio 
    FROM important_table 
    WHERE deleted=1;
    
    IF ratio > 0.3 THEN
        -- 调用告警接口
    END IF;
END;

7. 事务与并发控制

7.1 逻辑删除的事务边界

典型错误案例：

java复制@Transactional
public void deleteUser(Long id) {
    userMapper.deleteById(id);  // 逻辑删除
    logService.insert(id, "DELETE"); // 需要同步记录
    // 如果此处抛出异常，会导致日志记录失败但删除生效
}

正确方案：

java复制@Transactional
public void deleteUser(Long id) {
    int rows = userMapper.logicDeleteById(id);  // 自定义方法
    if (rows > 0) {
        logService.insert(id, "DELETE");
    }
}

7.2 乐观锁冲突处理

结合@Version注解使用：

java复制@Version
private Integer version;

@TableLogic
private Integer deleted;

更新时需要检查版本号：

sql复制UPDATE user 
SET deleted=1, version=version+1 
WHERE id=#{id} AND version=#{version}

8. 数据恢复机制

8.1 回收站功能实现

基础恢复接口设计：

java复制@PostMapping("/recover/{id}")
public Result recover(@PathVariable Long id) {
    User user = new User();
    user.setId(id);
    user.setDeleted(0);
    user.setUpdateTime(LocalDateTime.now());
    userMapper.updateById(user);
    return Result.success();
}

8.2 批量恢复优化

使用MyBatis-Plus的UpdateWrapper：

java复制public int batchRecover(Collection<Long> ids) {
    return userMapper.update(null, 
        new UpdateWrapper<User>()
            .set("deleted", 0)
            .set("update_time", LocalDateTime.now())
            .in("id", ids)
    );
}

对于大量数据恢复，建议分批处理：

java复制Lists.partition(idList, 1000).forEach(batch -> {
    batchRecover(batch);
    // 每批提交后休眠防止锁表
    Thread.sleep(200); 
});

9. 测试策略

9.1 单元测试验证

确保逻辑删除拦截器生效：

java复制@Test
void testLogicDelete() {
    userMapper.deleteById(1L);
    User user = userMapper.selectById(1L);
    assertNull(user);  // 应查询不到
    
    // 需要验证SQL日志是否实际执行了UPDATE
    String sql = sqlInterceptor.getLastSql();
    assertTrue(sql.contains("UPDATE"));
}

9.2 集成测试方案

测试类需禁用自动回滚以验证数据库状态：

java复制@SpringBootTest
@Transactional(propagation = NOT_SUPPORTED)  // 禁用事务
class UserLogicDeleteTest {
    @Test
    void testDeleteFlow() {
        // 执行删除
        // 直接查询数据库验证状态值
        // 最后手动清理测试数据
    }
}

10. 架构设计延伸

10.1 CQRS模式下的处理

在命令查询职责分离架构中，逻辑删除需要同步到读模型：

java复制@EventListener
public void handleUserDeleted(UserDeletedEvent event) {
    // 同步到Elasticsearch
    elasticsearchTemplate.update(
        UserDocument.from(event.getUserId())
            .setDeleted(true)
    );
}

10.2 事件溯源实现

使用事件流记录删除操作：

java复制public class User {
    @TableLogic
    private boolean deleted;
    
    public void delete() {
        apply(new UserDeletedEvent(this.id));
    }
    
    @EventHandler
    private void on(UserDeletedEvent event) {
        this.deleted = true;
    }
}

在实际项目中，我们团队发现逻辑删除字段的默认值配置不当是导致数据问题的常见原因。建议在数据库层设置DEFAULT约束，与注解配置保持双重一致：

sql复制ALTER TABLE user 
MODIFY COLUMN deleted TINYINT NOT NULL DEFAULT 0 
COMMENT '0-有效,1-删除';