ISSUE-0147 · 「异常 vs 返回值」的约定分歧¶
怎么发现的¶
v0.10.166 给 createTask 的入库失败加留痕时,两家独立审查方同时报出:
那个 catch 在生产中永远不会触发。
insertMany (jsstore/base.ts)
try { ... return { success: true, data } }
catch (err) { return { success: false, message: '保存数据失败:...' } } ← 吞成返回值
↓
addSearchData (jsstore/search-data.ts)
const result = await insertMany(...); return result; ← 原样透传
↓
createTask (background/task-manager.ts)
try { await addSearchData(...) } catch (e) { appendSysLog(...) } ← 却在等异常
⇒ 真实 DB 失败(配额满 / 事务冲突)时 catch 不触发 ⇒ 零日志 ⇒ 引擎照开、数据页无行。
而且比不加更糟:代码里有一个看起来在处理错误的 catch,读代码的人会以为这条路径有保护。
配套的测试用 addSearchData.mockRejectedValue() 构造了一个生产中不可达的场景,
给出虚假覆盖信心 —— 又一次「测试比被测物宽」(同 0145-source-text-assertion-false-green)。
jsstore/base.ts 的契约全景¶
同一个模块里吞和抛混着来,调用方每次都得记住哪个是哪个:
| 类型 | 导出 | 失败时 |
|---|---|---|
| 吞型 4 个 | selectAll · insertOne · insertMany · clearData |
返回 { success: false, message } |
| 抛型 5 个 | initJsStore · selectByQuery · removeByQuery · countByQuery · updateByQuery |
抛 |
| 原生 | connection / dbname |
jsstore promise reject |
⇒ 两类误用各自出现:
- 「用 try/catch 等一个不抛的函数」3 处:
createTask(v0.10.166 已修)、storePageOneData、runPagingJob - 「不检查返回值就往下走」5 处
未修的两条,都在用户主路径上(比已修的更严重)¶
① storePageOneData(batch-controller.ts)¶
地图任务第 1 页入库失败时:
- 用户看到任务进度照常上涨 —— 失败页按
list.length计入进度 - 数据页永久缺这页行
- 引擎继续跑完全程
- 痕迹 = 零(
console.error与 v0.10.166 加的 sysLog 都挂在永不触发的 catch 上)
核心地图管线首入口,行量最大。
② runPagingJob(batch-controller.ts)¶
同款形状作用于第 2+ 页:翻页循环照走、进度虚增、缺页。
而且不会自愈:本轮的 seen 去重已经登记了 googleId,同一页不会重试。
修复(v0.10.167)¶
两处都改成按返回值判,原有逻辑原样搬进 else:
const res = await addSearchData(...);
if (res && res.success === false) {
logShortCircuitOnce(`...-ingest-failed:${taskId}`, ..., 'error'); // 记痕,不 notify/不泵/不计进度
} else {
// 与改动前逐字一致:notifyDataUpdated / manageQueue / recordTaskProgress
}
关键是进度不再虚增 —— 旧版 added 在失败时回退成 list.length,把没进库的整页计入进度。
三次变异自证(主控自己写的代码,更要验)¶
| 变异 | 期望 | 实测 |
|---|---|---|
两处判据都改成 if (false && ...) |
K6c 红 | rc=1 · Tests 1 failed \| 14 passed (15) |
半修:保留日志分支、去掉 else(失败仍记进度) |
进度断言单独红 | rc=1 · expected 1 to be +0 |
| 只变异翻页那处判据 | K9b 红 | rc=1 · Tests 1 failed \| 15 passed (16) |
🔴 第二次变异是审查方逼出来的。 主控最初只做了第一种,而在那个变异下
expect(recordTaskProgress.mock.calls.length).toBe(0) 根本没被执行到(第一条日志断言先失败)——
审查方原话:「作者『变异验证了进度不虚增』的说法名不副实」。
它推演出存在「保留日志、只破坏进度」的定向变异能单独打红那条,主控照做后实证成立。
⇒ 一次变异让整组测试变红,不等于每条断言都有牙。 要让某条断言被单独实证, 必须构造只破坏它的变异。
审查方确认的一件事¶
担心「失败不记进度会不会让任务永远完不成」—— 不会。
recordTaskProgress 只维护 local:taskProgress:${taskId} 的展示用累计;
任务完成判定链 maybeFinishAll → maybeFinishTask 的判据是
status / nextIndex / 活跃 tab / pagingQueue,从不读 taskProgress。
仍未修(记档)¶
search-data.ts的deleteByQuery空where分支丢弃clearData的吞型返回值 —— 当前不可达(UI 调用全带非空 where),但违反本条判据,是个 footgun- 本次判据把
res === undefined/null归为成功、走list.length回退 —— 若未来addSearchData契约漂移会静默复活进度虚增
判据(可机械检查)¶
同一个模块的导出,失败表达方式必须统一;混用时每个调用点都是一次赌博。
检查方法: 1. 列出模块所有导出,标注「失败时抛 / 失败时返回」 2. grep 每个导出的调用点 3. 抛型 → 调用方必须有 try/catch 或明确向上传播 4. 吞型 → 调用方必须检查返回值;如果它外面包了 try/catch,那个 catch 十有八九是死的
🔴 死 catch 比没有 catch 危险:它让读代码的人以为这条路径有保护, 也让审查时的「有没有错误处理」这一问得到假的肯定答案。