跳转至

一个死参数让 wiki 说了十几个版本的错话

事实

// batch-controller.ts(v0.10.0 → v0.10.192)
export async function startBatch(taskId, urls, _batchSettings: BatchSettings) { … }
//                                              ↑ 下划线前缀 = 明示不使用,函数体里一次没碰

// task-manager.ts
async function batchSettings() {
  const s = await settingParamsStorageItem.getValue();   // ← 每次起任务跑一次
  return { concurrency: s.requestConcurrency || 1, … };  // ← 打包四个字段
}
await startBatch(next.id, urls, bs);                     // ← 送进去,直接丢掉

🔴 危害不是那一次多余的 storage 读

是它制造的假象:读代码的人看到「调度参数从 task-manager 传进 batch-controller」, 会以为改那边的打包逻辑能影响调度 —— 而调度器自己现读 settings,送进来的四个字段直接丢。

更糟的连带:wiki 说了十几个版本的错话

docs/wiki/settings-field-semantics.md 从 v0.10.0 起就写着:

⚠️ 废弃:requestConcurrency(v0.10.0+ 不再读,但 storage 保留兼容)

那句话一直是错的。 batchSettings() 读了它十几个版本,只是读完就扔。

🔴 「读了就扔」不是「不读」 —— 区别在于: grep 到这个字段的人会看到一个活着的读取点,然后花时间去搞清楚它影响什么; 而 wiki 告诉他「不再读」,两个信息对不上,他只能自己做实验。

这条 wiki 的错误在 v0.10.183 的字段覆盖断言里被顺手发现过(EXEMPT 的理由里写了 「它并非完全没人读」),但当时只记了档,没清代码 —— 于是又活了十个版本。

修

  • 删 startBatch 第三参 + BatchSettings 接口 + task-manager.batchSettings() 与两处调用
  • requestConcurrency 的 storage 字段保留(本仓规则:只加不删,防老用户数据报错), 补 @deprecated 注释说明「v0.10.193 起真的没有读取方」
  • wiki 那两处订正,写明「原话是错的」及错在哪
  • 断言豁免理由同步更新

🔴 死代码天然没有断言守着它

清理时实测:把死参数加回来,全仓 1629 条断言一条都不会红。

死代码不产生行为,也就没有行为可断言 —— 它只能用源码形态钉死:

  • startBatch 的签名必须恰好两个参数
  • BatchSettings 不许再被定义
  • 除类型定义处外,src/ 里不许有 .requestConcurrency 的读取形态

⚠️ 这三条全部走 codeOnly:本轮为解释这件事写了大量注释, 里面反复出现 BatchSettings / requestConcurrency / batchSettings() —— 不剥注释,三条断言会全部恒真(今天为这个栽过四次)。

3 条定向变异打红(死参数回来 ×2、重新读该字段 ×1)。

元教训

「发现了但只记档、没清」= 把问题留给下一个人,附赠一份说它不存在的文档。

v0.10.183 写豁免理由时已经查清了这条死链,当时判断「不在本刀范围」—— 没错,但那之后它又活了十个版本,而 wiki 继续对每个读它的人说假话。 记档的价值在于被兑现,挂着不清的记档会变成另一种误导: 它证明有人知道这件事,于是后来的人更不会去查。