MyBatis-Plus逻辑删除在TTS任务管理中的实践
在构建高可用语音合成（Text-to-Speech, TTS）系统时，任务记录的生命周期管理常常被低估，直到某天数据库查询变慢、日志无法追溯、客户追问“我上次生成的音频去哪了”——问题才真正浮出水面。尤其是在基于GLM-TTS等大模型的批量推理场景中，每天可能产生数千甚至上万条任务记录。如何在保障性能的同时保留审计能力？答案不是简单地“删掉”，而是用逻辑删除安全归档已完成的任务。
MyBatis-Plus 提供的逻辑删除机制，恰好为这一难题提供了优雅解法：它不改变开发习惯，却能从根本上提升系统的健壮性与可维护性。
从一个真实故障说起
我们曾在一个生产环境中遇到这样的情况：运维脚本误将状态为“已完成”的TTS任务物理删除，导致用户无法找回历史音频文件路径。虽然数据本身未丢失（存储在对象存储中），但元信息一旦清除，就再也无法关联。更麻烦的是，客服团队无法验证用户的请求是否属实——没有记录，等于没发生过。
这次事件促使我们重新审视数据清理策略。直接删？风险太大；全留着？数据库膨胀得让人焦虑。最终选择的方案是：软删除 + 定期归档，而核心实现依赖的就是 MyBatis-Plus 的@TableLogic功能。
什么是真正的“删除”？
在传统CRUD操作中，“删除”意味着从数据库中抹去一条记录。但在企业级应用中，这种做法越来越站不住脚。试想：
- 某个AI模型输出异常，需要回溯过去一周的成功案例进行对比分析；
- 客户投诉“结果不对”，但你发现对应任务已被清理；
- 运维人员执行了错误的清除命令，希望恢复数据却发现无迹可寻。
这时候你会发现，“删除”其实不该是终点，而是一种状态转换。
MyBatis-Plus 的逻辑删除正是基于这一理念：当你调用removeById()时，框架不会执行DELETE FROM tts_task，而是自动转为：
UPDATE tts_task SET deleted = 1 WHERE id = ? AND deleted = 0;同时，在所有查询中，默认追加AND deleted = 0条件，让已标记的数据“隐形”于常规业务流之外。这就像给文件打上“归档”标签，既不影响日常使用，又能随时翻阅。
如何让框架替你“过滤脏数据”？
关键在于配置和注解的协同工作。先看实体类定义：
@Data @TableName("tts_task") public class TtsTask { @TableId(type = IdType.AUTO) private Long id; private String inputText; private String promptAudioPath; private String outputPath; private Integer status; // 0:待处理, 1:成功, 2:失败 private LocalDateTime createTime; private LocalDateTime finishTime; @TableLogic private Integer deleted; }只需一个@TableLogic注解，MyBatis-Plus 就知道这个字段是用来做逻辑删除的。接下来，在配置文件中明确值的含义：
mybatis-plus: global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0这样设置后，任何通过 MP 提供的方法发起的查询或删除操作都会自动遵循规则。比如：
// 查询所有未完成任务 List<TtsTask> pending = taskService.lambdaQuery() .eq(TtsTask::getStatus, 0) .list();生成的实际SQL会是：
SELECT * FROM tts_task WHERE status = 0 AND deleted = 0;你不需要写.eq("deleted", 0)—— 框架已经帮你加上了。这才是“增强”的意义所在：减少样板代码，降低遗漏风险。
删除 ≠ 消失：如何安全归档已完成任务？
在我们的 GLM-TTS 批量推理系统中，典型的工作流程如下：
- 用户上传 JSONL 文件，触发批量任务创建；
- 后端将每条文本解析为
tts_task记录，初始状态为status=0,deleted=0； - 调度器轮询
status=0 AND deleted=0的任务并提交至推理引擎； - 推理完成后更新状态为
status=1或status=2； - 定时任务每日凌晨运行，将成功且未删除的任务标记为“已归档”。
最后一步的核心代码非常简洁：
@Scheduled(cron = "0 0 2 * * ?") // 每日凌晨两点 public void archiveFinishedTasks() { LambdaQueryWrapper<TtsTask> wrapper = new LambdaQueryWrapper<>(); wrapper.eq(TtsTask::getStatus, 1) // 成功完成 .eq(TtsTask::getDeleted, 0); // 尚未归档 boolean success = this.remove(wrapper); if (success) { log.info("Archived {} successfully completed TTS tasks", count(wrapper)); } }这段代码的作用不是“清空”，而是把已完成的任务从活跃列表中移除，使其不再出现在前端任务面板或调度查询中。但如果管理员需要排查问题，依然可以通过特殊接口查看这些“已归档”记录。
性能真的会受影响吗？
很多人担心：逻辑删除只是“假装看不见”，数据还在表里，会不会拖慢查询？
确实如此——如果不做优化的话。
但我们可以通过几个工程手段缓解甚至逆转这种影响：
✅ 建立联合索引加速常见查询
对高频查询字段组合建立索引至关重要。例如：
ALTER TABLE tts_task ADD INDEX idx_deleted_status_time (deleted, status, create_time DESC);这个索引能显著提升以下两类操作的效率：
- 调度器查找待处理任务：WHERE deleted=0 AND status=0
- 分页查询最新任务：按时间排序且排除已归档项
✅ 结合时间维度做冷热分离
我们进一步引入了“自动物理清理”机制：对于deleted=1且finishTime超过90天的任务，每月由后台Job执行真正的物理删除，并将原始数据导出至归档库或备份系统。
这样做既保留了短期可恢复性，又避免了长期存储压力。
✅ 控制可见范围，减轻前端负担
前端页面默认只加载deleted=0的任务，这意味着随着归档推进，主列表越来越轻量。用户体验上也更清晰：看到的都是“当前相关”的任务，历史记录则需主动进入“归档中心”查看。
绕过限制：什么时候需要查“已删除”的数据？
虽然大多数业务场景下应忽略已删除记录，但总有例外：
- 审计日志审查；
- 数据恢复操作；
- 故障复盘时比对历史输出。
此时，MyBatis-Plus 提供了两种方式强制包含已删数据：
方法一：使用withDeleted()
List<TtsTask> allIncludingDeleted = taskService.lambdaQuery() .withDeleted() // 关键：绕过逻辑删除过滤 .list();方法二：手动指定条件
wrapper.last("OR deleted = 1"); // 慎用，仅限特殊场景或者直接在 Wrapper 中显式判断：
.eq(TtsTask::getDeleted, 1)⚠️ 注意：这类操作应严格限制权限，建议仅允许管理员角色执行，并记录操作日志。
自定义SQL别踩坑：框架控制不了的地方最危险
MyBatis-Plus 的逻辑删除拦截器只能作用于它自己生成的SQL。一旦你写了自定义XML映射，就必须手动处理deleted字段，否则就会绕过整个安全机制。
❌ 危险写法：
<select id="selectRecentTasks" resultType="TtsTask"> SELECT * FROM tts_task WHERE create_time > #{startTime} </select>这条语句会查出包括deleted=1的所有记录！相当于开了后门。
✅ 正确做法：
<select id="selectRecentTasks" resultType="TtsTask"> SELECT * FROM tts_task WHERE create_time > #{startTime} AND deleted = 0 </select>或者更灵活地使用<where>标签：
<select id="selectRecentTasks" resultType="TtsTask"> SELECT * FROM tts_task <where> <if test="startTime != null"> create_time > #{startTime} </if> AND deleted = 0 </where> </select>建议团队内部制定规范：所有自定义SQL必须显式声明deleted = 0条件，并在代码评审中重点检查。
工程最佳实践总结
经过多个版本迭代，我们在实践中沉淀出一套适用于TTS类长周期任务系统的治理模式：
📌 字段命名统一用deleted
不要用is_deleted、del_flag等非标准名称。deleted是 MyBatis-Plus 默认识别的字段名，保持一致可减少配置复杂度。
📌 类型推荐TINYINT(1)或INT
布尔语义清晰，便于索引压缩。避免使用VARCHAR('true')这类反模式。
📌 必须为(deleted, status)建立联合索引
这是任务轮询和状态筛选的核心路径，缺少该索引会导致全表扫描。
📌 定期归档不可少
逻辑删除只是第一步。建议结合定时任务，定期将超过保留期限的已删除记录导出并物理清除，形成闭环。
📌 权限隔离要到位
普通用户不应感知到“已归档”状态的存在；管理员才可通过专用接口访问完整数据集。
📌 日志记录每一次“删除”操作
哪怕只是逻辑标记，也要留下痕迹：
[INFO] [Archiver] Archived 23 tasks (completed before 2025-03-01) at 2025-04-01T02:00:00Z这对后续审计极为重要。
写在最后：不只是TTS，更是通用数据治理范式
这套基于 MyBatis-Plus 逻辑删除的方案，最初为解决 TTS 任务归档而生，但它的价值远不止于此。在任何一个涉及异步处理、状态流转、结果留存的系统中——无论是图像生成、视频渲染、自动化测试还是批处理报表——都可以复用这一模式。
它的本质，是一种以状态代替动作的设计哲学：
不轻易消灭数据，而是赋予其新的生命周期阶段；
不让开发者重复编写过滤条件，而是由框架统一兜底；
不让运维陷入“删还是不删”的两难，而是提供渐进式清理路径。
当你的 AI 服务平台开始面对企业客户、合规要求和长期运营挑战时，你会发现，那些看似“多此一举”的标记字段，恰恰是系统能否走得更远的关键细节。
而这，也正是现代 ORM 框架真正应该提供的能力——不仅是 CRUD 的便利，更是数据治理的基础设施。
