test(phase-0): 1A 中断上报→进度快照终态同步契约钉上——markTerminal 此前零引用
重构蓝图 Phase 0 · 1A 那句「把心跳与进度接进 task contract 套件」逐条对撞后,心跳轴其实早被 别的路钉透了(TaskModuleHeartbeatSpiCoverageTest 12 支 SPI 与 moduleType 一一对上、 TaskHeartbeatServiceTest 进度随心跳转发、StaleTaskHeartbeatPolicyTest 首次心跳前的宽限、 TaskProgressSnapshotServiceThrottleTest 节流与终态豁免、三支 contract 用例 verify touchTaskHeartbeat) ⇒ 那一半本轮不重造,登记为「已闭·复用」。 真缺口在终态那一头:`TaskProgressSnapshotService.markTerminal` 在 src/test 里**一处引用都没有**, 而它对应的是一起真机事故(2026-09-13 客户端重启后店铺数据采集一直显示 28094「处理中」并阻塞该工具 后续任务——progress/batch 读缓存/快照,DB 行已终态而快照还停在 RUNNING)。Phase 2/3 抽公共管线时 这个出口最容易被当「顺手的小方法」漏在新契约之外,故补 10 例钉死: - markTerminal:快照不存在不许凭空造行;同 status 同 message 幂等不空写;只换 message 也要落; 非法入参一次库都不碰;写完必须摘限写窗(附对照组:不插终态时第二笔确被 500ms 窗吞掉, 否则「三笔都落」说不清是摘窗摘对了还是限写窗压根没生效)。 - markInterrupted:DB 仍 RUNNING ⇒ 模块缓存与快照同步 FAILED 并带真因;DB 已终态 ⇒ 按现值自愈 刷一遍快照(历史遗留旧缓存就是在这儿卡住前端的);快照写抛异常不得让中断接口本身失败; 非法 taskId 不落到快照。 门禁:`mvn -o test` 全量 4427 passed/0 failures/7 skipped(6:58,BUILD SUCCESS)。
This commit is contained in:
+277
@@ -0,0 +1,277 @@
|
||||
package com.nanri.aiimage.modules.task.contract;
|
||||
|
||||
import com.baomidou.mybatisplus.core.MybatisConfiguration;
|
||||
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
|
||||
import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
|
||||
import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
|
||||
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||
import com.nanri.aiimage.modules.task.mapper.TaskProgressSnapshotMapper;
|
||||
import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
|
||||
import com.nanri.aiimage.modules.task.model.dto.TaskHeartbeatRequest;
|
||||
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
|
||||
import com.nanri.aiimage.modules.task.model.entity.TaskProgressSnapshotEntity;
|
||||
import com.nanri.aiimage.modules.task.model.vo.TaskHeartbeatVo;
|
||||
import com.nanri.aiimage.modules.task.service.TaskHeartbeatLivenessService;
|
||||
import com.nanri.aiimage.modules.task.service.TaskHeartbeatService;
|
||||
import com.nanri.aiimage.modules.task.service.TaskProgressSnapshotService;
|
||||
import com.nanri.aiimage.modules.task.spi.TaskModuleHeartbeatSpi;
|
||||
import org.apache.ibatis.builder.MapperBuilderAssistant;
|
||||
import org.junit.jupiter.api.BeforeAll;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.api.extension.ExtendWith;
|
||||
import org.mockito.ArgumentCaptor;
|
||||
import org.mockito.Mock;
|
||||
import org.mockito.junit.jupiter.MockitoExtension;
|
||||
import org.mockito.junit.jupiter.MockitoSettings;
|
||||
import org.mockito.quality.Strictness;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.assertEquals;
|
||||
import static org.junit.jupiter.api.Assertions.assertFalse;
|
||||
import static org.mockito.ArgumentMatchers.any;
|
||||
import static org.mockito.ArgumentMatchers.eq;
|
||||
import static org.mockito.ArgumentMatchers.isNull;
|
||||
import static org.mockito.Mockito.doThrow;
|
||||
import static org.mockito.Mockito.mock;
|
||||
import static org.mockito.Mockito.never;
|
||||
import static org.mockito.Mockito.times;
|
||||
import static org.mockito.Mockito.verify;
|
||||
import static org.mockito.Mockito.when;
|
||||
|
||||
/**
|
||||
* 中断上报 → 进度快照终态同步的跨模块契约(重构蓝图 Phase 0 · 1A)。
|
||||
*
|
||||
* 为什么这一格值得单独钉:心跳轴本身早被别的路钉透了——{@code TaskModuleHeartbeatSpiCoverageTest}
|
||||
* (12 支 SPI 与 moduleType 一一对上)、{@code TaskHeartbeatServiceTest}(进度随心跳转发)、
|
||||
* {@code StaleTaskHeartbeatPolicyTest}(首次心跳前的宽限)、
|
||||
* {@code TaskProgressSnapshotServiceThrottleTest}(节流与终态豁免)。
|
||||
* 但把终态写回快照的那个出口 {@code markTerminal} 在 {@code src/test} 里**一处引用都没有**,
|
||||
* 而它对应的是一起真机事故:2026-09-13 客户端重启后店铺数据采集一直显示 28094「处理中」并阻塞
|
||||
* 该工具后续任务——因为 progress/batch 读的是缓存/快照(Redis,跨实例共享、不随 JVM 重启清空),
|
||||
* DB 行已终态而快照还停在 RUNNING。Phase 2/3 把管线四段抽成公共件时,这个出口最容易被当成
|
||||
* 「顺手的小方法」漏在新契约之外,故在此钉死。
|
||||
*
|
||||
* 覆盖面:{@code markTerminal} 的幂等与「不凭空造行」、终态写完必须清节流记录(否则后续补写
|
||||
* 被自己刚写的窗口吞掉),以及 {@code markInterrupted} 两条路径(DB 现值 RUNNING/已终态自愈)
|
||||
* 都必须把终态同步到缓存与快照,且**快照写失败不得让中断接口本身失败**。
|
||||
*/
|
||||
@ExtendWith(MockitoExtension.class)
|
||||
@MockitoSettings(strictness = Strictness.LENIENT)
|
||||
class TerminalProgressSyncContractTest {
|
||||
|
||||
private static final Long TASK_ID = 28094L;
|
||||
private static final String MODULE_TYPE = "SHOP_DATA_CRAWL";
|
||||
|
||||
@BeforeAll
|
||||
static void initializeMybatisMetadata() {
|
||||
MapperBuilderAssistant assistant = new MapperBuilderAssistant(new MybatisConfiguration(), "");
|
||||
TableInfoHelper.initTableInfo(assistant, TaskProgressSnapshotEntity.class);
|
||||
TableInfoHelper.initTableInfo(assistant, FileTaskEntity.class);
|
||||
}
|
||||
|
||||
@Mock private TaskProgressSnapshotMapper snapshotMapper;
|
||||
@Mock private FileTaskMapper fileTaskMapper;
|
||||
|
||||
private TaskProgressSnapshotService snapshotService() {
|
||||
return new TaskProgressSnapshotService(snapshotMapper, new ObjectMapper());
|
||||
}
|
||||
|
||||
private static TaskProgressSnapshotEntity snapshot(String status, String message) {
|
||||
TaskProgressSnapshotEntity existing = new TaskProgressSnapshotEntity();
|
||||
existing.setId(77L);
|
||||
existing.setTaskId(TASK_ID);
|
||||
existing.setModuleType(MODULE_TYPE);
|
||||
existing.setStatus(status);
|
||||
existing.setTotalCount(10);
|
||||
existing.setSuccessCount(4);
|
||||
existing.setFailedCount(1);
|
||||
existing.setPendingCount(5);
|
||||
existing.setCurrentScopeKey("scope-1");
|
||||
existing.setMessage(message);
|
||||
return existing;
|
||||
}
|
||||
|
||||
// ---- markTerminal 自身 ----
|
||||
|
||||
@Test
|
||||
void markTerminalDoesNotCreateSnapshotRowWhenAbsent() {
|
||||
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(null);
|
||||
|
||||
snapshotService().markTerminal(TASK_ID, MODULE_TYPE, "FAILED", "客户端异常中断");
|
||||
|
||||
verify(snapshotMapper, never()).update(isNull(), any(LambdaUpdateWrapper.class));
|
||||
verify(snapshotMapper, never()).insert(any(TaskProgressSnapshotEntity.class));
|
||||
}
|
||||
|
||||
@Test
|
||||
void markTerminalIsIdempotentOnSameStatusAndMessage() {
|
||||
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class)))
|
||||
.thenReturn(snapshot("FAILED", "客户端异常中断"));
|
||||
|
||||
snapshotService().markTerminal(TASK_ID, MODULE_TYPE, "FAILED", "客户端异常中断");
|
||||
|
||||
verify(snapshotMapper, never()).update(isNull(), any(LambdaUpdateWrapper.class));
|
||||
}
|
||||
|
||||
@Test
|
||||
void markTerminalWritesWhenOnlyMessageChanged() {
|
||||
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class)))
|
||||
.thenReturn(snapshot("FAILED", "旧文案"));
|
||||
|
||||
snapshotService().markTerminal(TASK_ID, MODULE_TYPE, "FAILED", "客户端异常中断: crash");
|
||||
|
||||
verify(snapshotMapper).update(isNull(), any(LambdaUpdateWrapper.class));
|
||||
}
|
||||
|
||||
@Test
|
||||
void markTerminalIgnoresInvalidArguments() {
|
||||
for (Object[] args : List.of(
|
||||
new Object[]{null, MODULE_TYPE, "FAILED", "x"},
|
||||
new Object[]{0L, MODULE_TYPE, "FAILED", "x"},
|
||||
new Object[]{TASK_ID, null, "FAILED", "x"},
|
||||
new Object[]{TASK_ID, "", "FAILED", "x"},
|
||||
new Object[]{TASK_ID, MODULE_TYPE, null, "x"},
|
||||
new Object[]{TASK_ID, MODULE_TYPE, " ", "x"})) {
|
||||
snapshotService().markTerminal((Long) args[0], (String) args[1], (String) args[2], (String) args[3]);
|
||||
}
|
||||
verify(snapshotMapper, never()).update(isNull(), any(LambdaUpdateWrapper.class));
|
||||
verify(snapshotMapper, never()).selectOne(any(LambdaQueryWrapper.class));
|
||||
}
|
||||
|
||||
/**
|
||||
* 终态写完必须把节流记录一起清掉。限写窗(默认 500ms)按 {@code taskId:moduleType} 记:
|
||||
* 若终态不摘这条记录,紧随其后那笔非终态补写(纠正文案、或同一 key 复用的下一轮进度)
|
||||
* 会被自己刚写的窗口吞掉,前端就又回到「永远处理中」。
|
||||
* 本用例把三步摆在一起:进度写(顺带武装限写窗)⇒ 终态写(必须摘窗)⇒ 补写(必须还落得下去)。
|
||||
*/
|
||||
@Test
|
||||
void markTerminalClearsThrottleWindowForFollowingWrites() {
|
||||
TaskProgressSnapshotService service = snapshotService();
|
||||
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class)))
|
||||
.thenReturn(snapshot("RUNNING", "processing"));
|
||||
|
||||
service.save(TASK_ID, MODULE_TYPE, "RUNNING", 10, 4, 1, "scope-1", "第一步", null);
|
||||
service.markTerminal(TASK_ID, MODULE_TYPE, "FAILED", "客户端异常中断");
|
||||
service.save(TASK_ID, MODULE_TYPE, "RUNNING", 10, 5, 0, "scope-1", "第二步", null);
|
||||
|
||||
verify(snapshotMapper, times(3)).update(isNull(), any(LambdaUpdateWrapper.class));
|
||||
}
|
||||
|
||||
/**
|
||||
* 上一条的对照组:同样两笔进度写之间**不**插终态写,第二笔就被限写窗吞掉。
|
||||
* 没有这条对照,上一条的「三笔都落」说不清是摘窗摘对了,还是限写窗压根没生效。
|
||||
*/
|
||||
@Test
|
||||
void followUpWriteIsThrottledWhenNoTerminalSyncHappens() {
|
||||
TaskProgressSnapshotService service = snapshotService();
|
||||
when(snapshotMapper.selectOne(any(LambdaQueryWrapper.class)))
|
||||
.thenReturn(snapshot("RUNNING", "processing"));
|
||||
|
||||
service.save(TASK_ID, MODULE_TYPE, "RUNNING", 10, 4, 1, "scope-1", "第一步", null);
|
||||
service.save(TASK_ID, MODULE_TYPE, "RUNNING", 10, 5, 0, "scope-1", "第二步", null);
|
||||
|
||||
verify(snapshotMapper, times(1)).update(isNull(), any(LambdaUpdateWrapper.class));
|
||||
}
|
||||
|
||||
// ---- markInterrupted 与快照的接线 ----
|
||||
|
||||
private static final class RecordingSpi implements TaskModuleHeartbeatSpi {
|
||||
private final List<FileTaskEntity> cacheWrites = new java.util.ArrayList<>();
|
||||
|
||||
@Override
|
||||
public String moduleType() {
|
||||
return MODULE_TYPE;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void touchHeartbeat(Long taskId, TaskHeartbeatRequest request) {
|
||||
// 本支只验终态同步,心跳刷新另有归属用例
|
||||
}
|
||||
|
||||
@Override
|
||||
public void saveTaskCache(FileTaskEntity task) {
|
||||
cacheWrites.add(task);
|
||||
}
|
||||
}
|
||||
|
||||
private TaskHeartbeatService heartbeatService(TaskProgressSnapshotService snapshotService, RecordingSpi spi) {
|
||||
return new TaskHeartbeatService(fileTaskMapper, snapshotService,
|
||||
mock(com.nanri.aiimage.modules.task.spi.BrandTaskHeartbeatSpi.class),
|
||||
mock(TaskHeartbeatLivenessService.class), List.of(spi));
|
||||
}
|
||||
|
||||
private static FileTaskEntity runningTask() {
|
||||
FileTaskEntity task = new FileTaskEntity();
|
||||
task.setId(TASK_ID);
|
||||
task.setModuleType(MODULE_TYPE);
|
||||
task.setStatus("RUNNING");
|
||||
task.setUserId(7L);
|
||||
return task;
|
||||
}
|
||||
|
||||
@Test
|
||||
void markInterruptedSyncsCacheAndSnapshotWhenTaskStillRunning() {
|
||||
when(fileTaskMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(runningTask());
|
||||
when(fileTaskMapper.update(isNull(), any(LambdaUpdateWrapper.class))).thenReturn(1);
|
||||
TaskProgressSnapshotService snapshotService = mock(TaskProgressSnapshotService.class);
|
||||
RecordingSpi spi = new RecordingSpi();
|
||||
|
||||
TaskHeartbeatVo vo = heartbeatService(snapshotService, spi).markInterrupted(TASK_ID, "客户端崩溃重启");
|
||||
|
||||
assertFalse(vo.isAlive());
|
||||
assertEquals("FAILED", vo.getStatus());
|
||||
ArgumentCaptor<String> message = ArgumentCaptor.forClass(String.class);
|
||||
verify(snapshotService).markTerminal(eq(TASK_ID), eq(MODULE_TYPE), eq("FAILED"), message.capture());
|
||||
assertEquals("客户端异常中断: 客户端崩溃重启", message.getValue());
|
||||
assertEquals(1, spi.cacheWrites.size(), "模块缓存也得同步终态,否则读缓存的那侧仍是 RUNNING");
|
||||
assertEquals("FAILED", spi.cacheWrites.get(0).getStatus());
|
||||
}
|
||||
|
||||
/** DB 已是终态(重复上报)时仍要按 DB 现值自愈刷一遍快照——历史遗留的旧缓存就是在这儿卡住前端的。 */
|
||||
@Test
|
||||
void markInterruptedHealsStaleSnapshotWhenTaskAlreadyTerminal() {
|
||||
FileTaskEntity terminal = runningTask();
|
||||
terminal.setStatus("CANCELLED");
|
||||
terminal.setErrorMessage("用户取消");
|
||||
when(fileTaskMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(terminal);
|
||||
when(fileTaskMapper.update(isNull(), any(LambdaUpdateWrapper.class))).thenReturn(0);
|
||||
TaskProgressSnapshotService snapshotService = mock(TaskProgressSnapshotService.class);
|
||||
|
||||
TaskHeartbeatVo vo = heartbeatService(snapshotService, new RecordingSpi())
|
||||
.markInterrupted(TASK_ID, "重复上报");
|
||||
|
||||
assertFalse(vo.isAlive());
|
||||
assertEquals("CANCELLED", vo.getStatus());
|
||||
verify(snapshotService, times(1)).markTerminal(TASK_ID, MODULE_TYPE, "CANCELLED", "用户取消");
|
||||
}
|
||||
|
||||
/** 快照/缓存写失败只该告警:中断接口本身的成功语义不能被它拖下水。 */
|
||||
@Test
|
||||
void markInterruptedStillSucceedsWhenSnapshotWriteFails() {
|
||||
when(fileTaskMapper.selectOne(any(LambdaQueryWrapper.class))).thenReturn(runningTask());
|
||||
when(fileTaskMapper.update(isNull(), any(LambdaUpdateWrapper.class))).thenReturn(1);
|
||||
TaskProgressSnapshotService snapshotService = mock(TaskProgressSnapshotService.class);
|
||||
doThrow(new IllegalStateException("redis down"))
|
||||
.when(snapshotService).markTerminal(any(), any(), any(), any());
|
||||
|
||||
TaskHeartbeatVo vo = heartbeatService(snapshotService, new RecordingSpi())
|
||||
.markInterrupted(TASK_ID, "客户端崩溃重启");
|
||||
|
||||
assertFalse(vo.isAlive());
|
||||
assertEquals("FAILED", vo.getStatus(), "快照写失败不得让中断上报变成失败");
|
||||
}
|
||||
|
||||
@Test
|
||||
void markInterruptedIgnoresInvalidTaskId() {
|
||||
TaskProgressSnapshotService snapshotService = mock(TaskProgressSnapshotService.class);
|
||||
|
||||
// List.of 不收 null,非法值只能走 Arrays.asList
|
||||
for (Long taskId : java.util.Arrays.asList(null, 0L, -1L)) {
|
||||
TaskHeartbeatVo vo = heartbeatService(snapshotService, new RecordingSpi()).markInterrupted(taskId, "x");
|
||||
assertFalse(vo.isAlive(), "非法 taskId 也必须回「不活着」,不能让客户端以为任务还在跑");
|
||||
}
|
||||
verify(snapshotService, never()).markTerminal(any(), any(), any(), any());
|
||||
verify(fileTaskMapper, never()).selectOne(any(LambdaQueryWrapper.class));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user