当前位置：首页 > news >正文

再见，物理删除！MyBatis-Plus @TableLogic 优雅实现逻辑删除

news 来源：原创 2025/6/26 2:52:56

在开发应用程序时，我们经常会遇到需要删除数据的场景。但直接从数据库中物理删除（DELETE）数据有时并非最佳选择。为什么呢？

数据恢复: 一旦物理删除，数据通常难以恢复，误操作可能导致灾难性后果。
审计追踪: 很多业务场景需要保留操作记录，包括删除记录。
数据关联: 物理删除可能破坏与其他表的关联关系，导致数据不一致或需要复杂的级联删除策略。

这时，逻辑删除就成了一个非常优雅的解决方案。逻辑删除并非真的从数据库移除数据，而是通过一个特定的字段（例如 deleted、is_deleted）来标记记录的状态，将其标记为“已删除”。在应用程序层面，这些被标记的数据通常表现为“不存在”，但在数据库层面，它们仍然保留着。

手动实现逻辑删除通常意味着：

将所有的 DELETE 操作改为 UPDATE ... SET deleted = 1 ...。
在所有的 SELECT 查询中，手动添加 WHERE deleted = 0 的条件。

这无疑会增加大量重复代码，且容易遗漏，维护起来也相当痛苦。幸运的是，强大的 MyBatis-Plus (MP) 框架为我们提供了 @TableLogic 注解，让实现逻辑删除变得极其简单和自动化。

什么是 @TableLogic？

@TableLogic 是 MyBatis-Plus 提供的一个注解，用于标记实体类中代表逻辑删除状态的字段。一旦配置完成，MP 会在底层通过拦截器自动处理逻辑删除相关的 SQL 转换。

如何使用 @TableLogic？

使用 @TableLogic 非常简单，只需三步：

第一步：数据库表设计

在需要支持逻辑删除的表中，添加一个用于标记删除状态的字段。通常使用 TINYINT、INT 或 BOOLEAN 类型。例如，我们添加一个 deleted 字段：

ALTER TABLE `your_table_name`
ADD COLUMN `deleted` tinyint(1) UNSIGNED NOT NULL DEFAULT 0 COMMENT '逻辑删除标记(0:未删除; 1:已删除)';-- 为该字段添加索引通常是个好主意，特别是当已删除数据量较大时
ALTER TABLE `your_table_name` ADD INDEX `idx_deleted` (`deleted`);

第二步：实体类配置

在对应的 Java 实体类中，添加该字段，并使用 @TableLogic 注解标记它：

import com.baomidou.mybatisplus.annotation.TableLogic;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;@Data
@TableName("your_table_name")
public class YourEntity {private Long id;private String name;// ... 其他字段@TableLogic // 标记为逻辑删除字段private Integer deleted; // 字段类型与数据库对应
}

@TableLogic 注解本身就足以启用逻辑删除功能。

第三步：全局配置 (application.yml/properties)

虽然 @TableLogic 注解本身已经能工作，但最佳实践是在项目的配置文件中指定全局的“未删除值”和“已删除值”。这样 MP 就知道在生成 SQL 时应该用哪些具体的值。

mybatis-plus:global-config:db-config:# 逻辑删除字段名（如果实体类中字段名就是这个，可以省略，但推荐写上保持清晰）# 注意：即使配置了全局字段名，实体类中仍然需要 @TableLogic 注解来 *标识* 哪个字段是逻辑删除字段logic-delete-field: deleted# 逻辑已删除值（默认为 1）logic-delete-value: 1# 逻辑未删除值（默认为 0）logic-not-delete-value: 0

如果你的逻辑删除字段名、已删除值、未删除值与全局配置不同，也可以在 @TableLogic 注解中单独指定：

// 假设用 status 字段，0表示正常，-1表示删除
@TableLogic(value = "0", delval = "-1")
private Integer status;

但通常建议保持全局一致性。

@TableLogic 如何工作？

配置完成后，MP 内置的 LogicSqlInnerInterceptor（需要通过 MybatisPlusInterceptor 注册）就会自动生效：

对于删除操作: 当你调用 BaseMapper 提供的标准删除方法时，例如：
```
yourMapper.deleteById(1L);
// 或者
yourMapper.removeById(1L);
```
MP 不会执行物理 DELETE。它会自动将 SQL 转换为：
```
UPDATE your_table_name SET deleted = 1 WHERE id = 1 AND deleted = 0;
```
它只会将当前状态为“未删除”(deleted = 0) 的记录标记为“已删除”(deleted = 1)。

对于查询操作: 当你调用 BaseMapper 提供的所有标准查询方法时，例如：

YourEntity entity = yourMapper.selectById(1L);
List<YourEntity> list = yourMapper.selectList(null); // 查询所有
IPage<YourEntity> page = yourMapper.selectPage(pageParam, wrapper);
// ...等等

MP 会自动在这些查询的 WHERE 子句后面（或 WHERE 子句内，如果没有其他条件）追加逻辑删除的过滤条件：

-- selectById(1L) 可能的 SQL
SELECT id, name, deleted /*, ...*/ FROM your_table_name WHERE id = 1 AND deleted = 0;-- selectList(null) 可能的 SQL
SELECT id, name, deleted /*, ...*/ FROM your_table_name WHERE deleted = 0;-- selectPage(page, wrapper) 可能的 SQL (假设 wrapper 有其他条件)
SELECT id, name, deleted /*, ...*/ FROM your_table_name WHERE name LIKE '%test%' AND deleted = 0 LIMIT ?, ?;

这意味着，通过标准方法查询时，你永远只会得到未被逻辑删除的数据。

如何查询包含已删除的数据？

这是一个常见需求，比如在后台管理界面需要查看回收站内容，或者进行数据恢复操作。

既然 MP 的标准查询方法会自动添加 AND deleted = 0 的限制，那么要查询包含已删除的数据（甚至只查询已删除的数据），我们就必须绕过这个自动行为。

方法就是：使用自定义 SQL (在 Mapper XML 文件中)。

在 Mapper 接口定义方法:

public interface YourMapper extends BaseMapper<YourEntity> {// 查询指定 ID 的记录，无论其删除状态YourEntity selectByIdIncludeDeleted(@Param("id") Long id);// 查询所有已删除的记录List<YourEntity> selectDeletedList();
}

在 Mapper XML 文件中编写 SQL:

<mapper namespace="com.yourpackage.mapper.YourMapper"><resultMap id="BaseResultMap" type="com.yourpackage.domain.YourEntity"><!-- ... 字段映射 ... --><result column="deleted" property="deleted"/></resultMap><select id="selectByIdIncludeDeleted" resultMap="BaseResultMap">SELECT id, name, deleted /*, ...*/FROM your_table_nameWHERE id = #{id}<!-- 注意：这里我们没有写 deleted = 0 条件，MP 也不会自动加 --></select><select id="selectDeletedList" resultMap="BaseResultMap">SELECT id, name, deleted /*, ...*/FROM your_table_nameWHERE deleted = 1 <!-- 手动指定查询已删除的数据 --></select>
</mapper>

关键在于：对于 XML 中手写的 SQL，MP 的逻辑删除拦截器不会去修改它，也不会自动追加 deleted 条件。你可以完全控制查询逻辑。

@TableLogic 的优势

代码简洁: 无需在业务代码中重复编写 deleted = 0 的查询条件和 UPDATE 式的删除逻辑。
不易出错: 自动化处理减少了手动编码时遗漏条件的风险。
全局一致: 保证了整个应用处理逻辑删除行为的一致性。
低侵入性: 对业务代码的侵入非常小，主要通过注解和配置完成。

注意事项

性能: 如果逻辑删除的数据量非常大，查询性能可能会受到影响。确保在逻辑删除字段上建立了索引。考虑定期归档或物理清除不再需要的已删除数据。
唯一约束: 如果表中有唯一约束，逻辑删除可能导致问题（例如，用户注销账号后，其邮箱被标记为删除，但新用户无法使用该邮箱注册，因为唯一约束仍然存在）。需要根据业务场景设计合适的处理策略。

总结

MyBatis-Plus 的 @TableLogic 为 Java 应用实现逻辑删除提供了一个极其便捷和强大的解决方案。它通过简单的注解和配置，将开发者从繁琐、重复的 SQL 处理中解放出来，让我们能更专注于业务逻辑本身。掌握并使用好 @TableLogic，无疑能提升代码质量和开发效率，构建更健壮、更易于维护的应用程序。

什么是 @TableLogic​？

如何使用 @TableLogic​？

@TableLogic​ 如何工作？