返回文章列表实践教程

让 AI 修 Bug,先把问题变成能复现的失败

用快速搜索的旧请求覆盖问题,练习把现象变成确定性失败:分开证据与假设,控制 Promise 完成顺序,并检查结果、错误、loading 与清空输入。附可复制提示词和离线单文件测试。

15 分钟阅读Markdown
本页内容8 个章节

结果错了,先固定让它出错的顺序

输入框里已经是 cat,列表却显示 c 的搜索结果。刷新后又好了;让 AI 改过一次,加了防抖,快速输入时仍然偶尔出现。

这类 Bug 最值得先交给 AI 的材料,是一条每次都能失败的测试:发出旧请求 A,再发出新请求 B;先让 B 返回,再让 A 返回。无论网络有多快,最后都只能显示 B 的结果。把这个顺序写进测试后,“好像修好了”就有了可以核对的答案。

本文只处理这一个搜索竞态,读完可以得到一份不联网的单文件练习、一条可复制的调试提示词,以及能检查结果、错误和加载状态的回归测试。关键约定是:只有当前请求可以写入 rows、error、loading,连 finally 里的收尾也必须遵守。

这是一套手工编写并用 Node.js 实际运行的教学参考,数据是虚构的。文中的提示词供你自行试用;没有执行一次独立的真实 AI 修复实验,也不据此评价任何模型或产品的修复效果。练习不需要 API Key、付费服务或浏览器。

先把看到的现象与原因假设分开

设想你在维护一个搜索框。每次输入调用 search(query),它通过注入的 fetchRows(query) 获取列表。我们先约定:新输入立即清空旧列表和错误;非空输入显示 loading;清空输入不发请求,并使以前的请求失去更新页面的资格。这里只把空字符串视为空输入,空白裁剪、缓存和保留旧结果不是本例策略。

次序可观察事件页面应该怎样
1输入 c,发出 A空列表,loading 为 true
2输入 cat,发出 B仍等待 B,A 已过时
3B 成功返回 ["cat"]显示 cat,无错误,loading 为 false
4A 成功返回 ["c"]保持第 3 步的状态

“第 4 步列表变回 c”是证据。“旧请求没有在写状态前检查自己是否仍有效”是待查实现的假设。防抖间隔、服务端缓存、组件重复挂载也可能成为调查方向,但不能只凭这张表认定它们是原因。

最小复现保留两个在途请求和三个可观察字段,移除 UI 框架、真实网络和数据库。若这个版本没有重现原来的偏差,就继续补充条件;不要为了让测试失败,悄悄换成另一个问题。在真实项目中,还应先确认确实发生了这样的请求和写入顺序。

旧请求 A 先发出却后返回。修复前 c 覆盖 cat,修复后只有最新请求可以更新结果、错误和加载状态。
测试主动控制完成顺序;修复后,同样的返回顺序应始终保留最新请求的状态。

把网络时序换成自己能控制的 Promise

查看高清原图,放大阅读标注。

用 setTimeout 模拟“旧请求 200ms,新请求 20ms”仍然依赖计时。我们真正需要控制的是谁先完成,不是机器等了几毫秒。

下面单文件中的 deferred() 暂存 Promise 的 resolve 和 reject。测试主动完成 B,再完成 A。每次完成后,等待对应 search() 返回的 Promise,再检查状态;只调用 resolve() 就立刻断言,异步函数可能还没恢复执行。

oldDone、newDone 等待的是各自调用的处理结束。由于 search() 捕获了请求异常,模拟失败后它们也会正常完成;是否给用户显示正确错误,要检查 state.error,不能把“不抛异常”当成成功。等待旧调用结束也不表示它有权写入当前状态。

这是应用代码的确定性回归,不是在给模型输出打分。现有的 Trace Review 文章讨论如何从任务运行记录设计 AI 评估;这里把一个已经定义清楚的前端失败交给普通断言检查。

可直接交给 AI 的修复请求

先保存下一节的完整代码,再把下面的提示词连同文件交给你已有的编程助手。没有编程助手也可以手工比较两个实现,测试方法相同。

修复这个快速搜索竞态。先不要改测试或增加依赖。

输入与契约:
- 阅读 search.mjs,目标是 createBrokenSearch。
- A=search("c"),B=search("cat"),发出顺序 A→B,完成顺序 B→A。
- 最后只能显示 B 的结果;只有当前请求可写 rows/error/loading。
- 新输入清空旧 rows/error;空字符串不发请求,并让旧请求失效。
- 旧请求晚失败不能写错误;旧请求先结束不能关闭 B 的 loading。
- B 失败应显示 B 的错误,不能回退显示 A 的迟到结果。

先给出:观察到的证据、原因假设、能区分假设的最小复现。
保持 deferred 控制的完成顺序和所有断言,不改为计时器等待。
先运行 SEARCH_IMPL=broken node --test search.mjs,保留失败证据;
再只修改 createBrokenSearch,用同一命令证明修复;
最后运行 node --test search.mjs,确认参考实现仍通过。
说明每一处异步状态写入为什么仍属于当前请求,包含 finally。
报告实际命令、退出码和剩余边界;不能执行时明确说未运行。

这里把证据和修改范围一起给出,能让审阅者检查 AI 是否修了原问题。参考实现已经在文件中,适合对照学习;这不是盲测模型能力的题。若要记录真实 AI 运行,另存你实际使用的模型、输入文件版本、补丁和命令输出,不要把下文的手工参考结果算作 AI 成绩。

复制一份完整、离线的练习

需要 Node.js 20 或更高版本,无须安装依赖。把下面整个代码块保存为一个新目录中的 search.mjs。它包含 broken 起点、reference 参考实现和同一组测试;两个语言版本提供相同代码。

默认运行参考实现:

node --test search.mjs

预期 10 个测试全部通过,退出码 0。需要先看到失败时,macOS/Linux 使用下面的显式命令;PowerShell 可以先设置 $env:SEARCH_IMPL="broken",运行测试后执行 Remove-Item Env:SEARCH_IMPL,避免后续默认测试仍选中 broken。

SEARCH_IMPL=broken node --test search.mjs

原始 broken 实现预期 8 个失败、2 个通过,退出码 1。这是故意选择练习起点的结果;默认运行并不会全部报错。修复 createBrokenSearch 后,应让这个显式命令也全部通过。也可以用 SEARCH_IMPL=reference 显式指定参考实现。

import assert from "node:assert/strict";
import test from "node:test";

// Teaching policy: clear rows/error on every input; empty input sends no request.
export function createBrokenSearch(fetchRows) {
  const state = { rows: [], error: null, loading: false };
  return { state, async search(query) {
    Object.assign(state, { rows: [], error: null, loading: query !== "" });
    if (query === "") return;
    try {
      state.rows = await fetchRows(query);
    } catch (error) {
      state.error = error.message;
    } finally {
      state.loading = false;
    }
  } };
}

export function createReferenceSearch(fetchRows) {
  const state = { rows: [], error: null, loading: false };
  let generation = 0;
  return { state, async search(query) {
    const mine = ++generation; // Empty input also invalidates previous work.
    Object.assign(state, { rows: [], error: null, loading: query !== "" });
    if (query === "") return;
    try {
      const rows = await fetchRows(query);
      if (mine === generation) state.rows = rows;
    } catch (error) {
      if (mine === generation) state.error = error.message;
    } finally {
      if (mine === generation) state.loading = false;
    }
  } };
}

function deferred() {
  let resolve, reject;
  const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
  return { promise, resolve, reject };
}

const mode = process.env.SEARCH_IMPL ?? "reference";
if (!["reference", "broken"].includes(mode)) throw new Error("Invalid SEARCH_IMPL");
const createSearch = mode === "broken" ? createBrokenSearch : createReferenceSearch;
function setup() {
  const requests = [];
  const app = createSearch(query => {
    const request = { query, ...deferred() };
    requests.push(request);
    return request.promise;
  });
  return { ...app, requests };
}
const empty = { rows: [], error: null, loading: false };

test("new success, then old success: keep new rows", async () => {
  const app = setup();
  const oldDone = app.search("c");
  const newDone = app.search("cat");
  app.requests[1].resolve(["cat"]);
  await newDone;
  assert.deepEqual(app.state, { ...empty, rows: ["cat"] });
  app.requests[0].resolve(["c"]);
  await oldDone;
  assert.deepEqual(app.state, { ...empty, rows: ["cat"] });
});

test("old success while new pending: keep loading and empty rows", async () => {
  const app = setup();
  const oldDone = app.search("c");
  const newDone = app.search("cat");
  app.requests[0].resolve(["c"]);
  await oldDone;
  const during = { ...app.state };
  app.requests[1].resolve(["cat"]);
  await newDone;
  assert.deepEqual(during, { ...empty, loading: true });
  assert.deepEqual(app.state, { ...empty, rows: ["cat"] });
});

test("old failure while new pending: no stale error or early loading reset", async () => {
  const app = setup();
  const oldDone = app.search("c");
  const newDone = app.search("cat");
  app.requests[0].reject(new Error("old failure"));
  await oldDone;
  const during = { ...app.state };
  app.requests[1].resolve(["cat"]);
  await newDone;
  assert.deepEqual(during, { ...empty, loading: true });
  assert.deepEqual(app.state, { ...empty, rows: ["cat"] });
});

test("new success, then old failure: keep successful state", async () => {
  const app = setup();
  const oldDone = app.search("c");
  const newDone = app.search("cat");
  app.requests[1].resolve(["cat"]);
  await newDone;
  app.requests[0].reject(new Error("old failure"));
  await oldDone;
  assert.deepEqual(app.state, { ...empty, rows: ["cat"] });
});

test("new failure, then old success: preserve current error", async () => {
  const app = setup();
  const oldDone = app.search("c");
  const newDone = app.search("cat");
  app.requests[1].reject(new Error("new failure"));
  await newDone;
  assert.deepEqual(app.state, { ...empty, error: "new failure" });
  app.requests[0].resolve(["c"]);
  await oldDone;
  assert.deepEqual(app.state, { ...empty, error: "new failure" });
});

for (const outcome of ["resolve", "reject"]) {
  test(`clear input invalidates old ${outcome}`, async () => {
    const app = setup();
    const oldDone = app.search("c");
    await app.search("");
    assert.equal(app.requests.length, 1);
    assert.deepEqual(app.state, empty);
    if (outcome === "resolve") app.requests[0].resolve(["c"]);
    else app.requests[0].reject(new Error("old failure"));
    await oldDone;
    assert.deepEqual(app.state, empty);
  });
}

test("same query twice still creates distinct generations", async () => {
  const app = setup();
  const oldDone = app.search("cat");
  const newDone = app.search("cat");
  app.requests[1].resolve(["fresh"]);
  await newDone;
  app.requests[0].resolve(["stale"]);
  await oldDone;
  assert.deepEqual(app.state, { ...empty, rows: ["fresh"] });
});

test("normal success waits for completion and next search resets state", async () => {
  const app = setup();
  const firstDone = app.search("c");
  assert.deepEqual(app.state, { ...empty, loading: true });
  app.requests[0].resolve(["c"]);
  await firstDone;
  assert.deepEqual(app.state, { ...empty, rows: ["c"] });
  const nextDone = app.search("cat");
  assert.deepEqual(app.state, { ...empty, loading: true });
  app.requests[1].reject(new Error("new failure"));
  await nextDone;
  assert.deepEqual(app.state, { ...empty, error: "new failure" });
  await app.search("");
  assert.deepEqual(app.state, empty);
});

test("synchronous fetch error is handled", async () => {
  const app = createSearch(() => { throw new Error("sync failure"); });
  await app.search("cat");
  assert.deepEqual(app.state, { ...empty, error: "sync failure" });
});

修复的是写入资格,finally 也不能例外

参考实现用递增的 generation 表示最新输入的代数,每次调用捕获自己的 mine。请求返回时,只有 mine === generation 才有权写状态。比较请求文本不够:连续两次搜索 cat 仍然是两次不同的请求,旧 cat 的结果也可能已经过时。

递增必须放在空输入的提前返回之前。否则 search("") 只清空一次列表,旧请求完成后又会把它填回来。发起新调用时的同步重置属于最新输入;异步成功、异常和收尾三个分支则各自重新检查代数。

只保护 rows 仍然不够。A 先结束、B 仍等待时,A 的无条件 finally 会把 loading 设为 false;A 晚失败时,无条件 catch 会给 B 的成功结果附上一条旧错误。看一次“最后显示 cat”的截图,发现不了前一种中间状态错误。

测试分支必须保住的行为
B 成功后 A 才成功B 的 rows 不被覆盖
A 成功或失败,B 仍等待rows 为空、error 为 null、loading 仍为 true
B 成功后 A 才失败不出现 A 的错误
B 失败后 A 才成功保留 B 的错误,rows 为空,loading 为 false
清空输入后 A 才成功或失败三个字段保持空闲状态,不新增请求
同一查询连续发两次以调用代数决定资格,不以字符串相等决定

练习还保留了普通成功、新调用重置状态、当前失败和同步抛错的检查。它们防止修复只会“拒绝所有写入”:如果连最新请求也不更新,正常路径会失败。

取消请求能节省工作,代数标记决定谁能写

如果实际请求支持 AbortController,新输入时取消旧请求可以减少不必要的工作;它不能自动替你完成所有状态归属判断。旧调用可能已经完成网络读取、正在后续解析,注入的请求函数也可能根本不处理 signal。取消引发的异常同样会进入异常和收尾路径。

本练习故意不取消请求,让每个旧 Promise 都有机会成功或失败,验证过时结果确实不能写状态。若加入取消,仍应保留同样的代数检查,并测试“取消后旧调用仍然结束”的情况。取消不等于服务端一定停止执行;代数标记也不停止旧工作的资源消耗。

这里的策略只适用于一个搜索控制器里由最新输入拥有的 rows/error/loading。需要保留旧列表、空白规范化、分页合并、请求去重、多区域并行状态时,要先重新定义谁拥有哪个字段。不能把同一个全局代数直接套到所有业务请求。

组件卸载、订阅清理、框架状态提交及 effect 生命周期没有在这个无 UI 练习中验证。真实组件如果要求卸载后禁止写入,还需要清理时失效或 disposal 机制及相应集成测试;不能把“清空输入已测”当成“所有卸载场景已覆盖”。

拿着什么证据回到真实组件

本练习在 Node.js v23.11.1 下实际运行:参考模式 10/10 通过,退出码 0;原始 broken 模式 8 项失败、2 项通过,退出码 1。它验证的是手工教学代码在固定完成顺序下的状态归属,没有浏览器验收,也没有独立 AI 修复成绩。

接回真实组件时,先确认 UI 的输入确实进入这个控制器,网络适配器的成功和失败确实走到相同分支,再观察 B 等待期间与 A 迟到之后的三个字段。若仍异常,沿着实际写入点查重复控制器、额外状态更新和生命周期;不要直接把 Node 测试的通过扩大成整个页面已修复。

交给同事审阅的核心材料可以很少:让旧实现失败的顺序、修复前后的差异、同一断言在修复后的结果,以及还没接入验证的边界。这样,AI 给出的代码建议就能回到一个具体问题上接受检查:旧请求再晚回来,还能不能改写当前搜索?