跳转至

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 危险:它让读代码的人以为这条路径有保护, 也让审查时的「有没有错误处理」这一问得到假的肯定答案。