如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
Codex

Codex 使用场景

调查故障并测试修复方案

根据故障资料复现缺陷,编写针对性补丁,并整理可供评审的交接材料。

难度 Intermediate
时间跨度 Long-running

向 Codex 云端提供经过脱敏的故障资料和可用的测试环境,让它分析证据,复现有证据支持的代码缺陷,并提供针对性补丁、回归测试证据以及部署和回滚交接材料。

最适合

  • 正在调查已受控故障的小型工程团队。
  • 已有脱敏证据和安全复现输入的应用缺陷。
  • 在可用的隔离测试环境中评审针对性修复的团队。

目录

    ← 所有使用场景

    调查故障并测试修复方案

    根据故障资料复现缺陷,编写针对性补丁,并整理可供评审的交接材料。

    向 Codex 云端提供经过脱敏的故障资料和可用的测试环境,让它分析证据,复现有证据支持的代码缺陷,并提供针对性补丁、回归测试证据以及部署和回滚交接材料。

    Intermediate
    Long-running
    准备云端环境

    向 Codex 云端提供经过脱敏的故障资料和可用的测试环境,让它分析证据,复现有证据支持的代码缺陷,并提供针对性补丁、回归测试证据以及部署和回滚交接材料。

    Intermediate
    Long-running

    相关链接

    最适合

    • 正在调查已受控故障的小型工程团队。
    • 已有脱敏证据和安全复现输入的应用缺陷。
    • 在可用的隔离测试环境中评审针对性修复的团队。

    起始提示词

    使用 [path to sanitized incident packet] 中的资料,调查 [repository/service] 中编号为 [incident ID] 的故障。请在为此任务选定的已发布云端环境中开展调查。 故障资料列出了故障发生的时间范围、受影响版本的提交 SHA、预期行为、实际观察到的行为、相关日志和追踪片段,以及可安全用于复现的输入。先阅读 AGENTS.md 和代码仓库中的环境配置及测试说明。核对当前检出的代码是否与受影响的版本一致。如有差异,先说明差异,再得出结论。 整理一份简明时间线,并标明所引用的故障资料和源代码的文件名及行号。分别列出观察到的事实、待验证的假设和尚缺的证据。在隔离测试环境中检验证据最充分的假设。如果无法复现故障,或缺少决定性证据,请提交调查结果并说明下一步如何诊断。不要声称已确认根因,也不要凭猜测修改代码。 如果证据表明代码存在缺陷,请添加回归测试,并先在原始代码上运行该测试,展示测试失败的结果。以最小改动修复缺陷,重新运行该测试,然后运行代码仓库中可用的、覆盖范围更广的相关测试,以及 lint 检查和类型检查。记录运行的命令、退出码和所有未能运行的检查。 准备分支的代码差异、Pull Request 描述草稿、test-evidence.md,以及部署和回滚交接材料。说明证据支持的故障原因、仍不确定的事项,以及修复改变了哪些行为。每项判定标准用一行记录证据,列明代码版本和环境版本、修复前与修复后各自的命令、退出码和日志、实际结果,以及状态(通过、失败、受阻或未运行)和局限性。将 Pull Request 描述保存在本地,作为草稿供评审。 对于这个 webhook 重复投递示例,指出数据库事务提交前和提交后的具体故障点,用独立的数据库连接证明并发处理重复投递时会发生争用,并说明有关事务隔离、接收记录保留以及新旧版本混合部署的假设。 在这个 webhook 重复投递示例中,先等旧版消费者处理完在途任务,再找出没有匹配接收记录的旧版订单,之后才能建议恢复处理保留下来的投递。按现有队列或隔离流程,暂停处理受影响事件键对应的事件。添加一个测试,预置一笔缺少接收记录的订单及一次待执行的投递重试,验证暂停处理期间既不会创建第二笔订单,也不会返回成功确认。仅依据可信且不可变的事件标识、规范载荷和订单已提交的证据进行核对。如果证据缺失或相互矛盾,继续隔离相关事件,交由负责人审查。不要凭空构造指纹、删除接收记录或重放尚未查清的旧版事件。 除非我指定其他获准使用的来源,否则只使用提供的故障资料和代码仓库。如果提供了监控数据源,只访问明确获准使用的只读监控数据源。仅在此代码仓库中写入代码和任务产物,并且只使用该代码仓库的隔离测试数据库。不要直接连接生产环境的应用主机或数据库主机,也不要修改生产系统。不要重放生产事件、修改线上数据或监控、创建或发布对外通报、合并代码或部署。
    使用 [path to sanitized incident packet] 中的资料,调查 [repository/service] 中编号为 [incident ID] 的故障。请在为此任务选定的已发布云端环境中开展调查。 故障资料列出了故障发生的时间范围、受影响版本的提交 SHA、预期行为、实际观察到的行为、相关日志和追踪片段,以及可安全用于复现的输入。先阅读 AGENTS.md 和代码仓库中的环境配置及测试说明。核对当前检出的代码是否与受影响的版本一致。如有差异,先说明差异,再得出结论。 整理一份简明时间线,并标明所引用的故障资料和源代码的文件名及行号。分别列出观察到的事实、待验证的假设和尚缺的证据。在隔离测试环境中检验证据最充分的假设。如果无法复现故障,或缺少决定性证据,请提交调查结果并说明下一步如何诊断。不要声称已确认根因,也不要凭猜测修改代码。 如果证据表明代码存在缺陷,请添加回归测试,并先在原始代码上运行该测试,展示测试失败的结果。以最小改动修复缺陷,重新运行该测试,然后运行代码仓库中可用的、覆盖范围更广的相关测试,以及 lint 检查和类型检查。记录运行的命令、退出码和所有未能运行的检查。 准备分支的代码差异、Pull Request 描述草稿、test-evidence.md,以及部署和回滚交接材料。说明证据支持的故障原因、仍不确定的事项,以及修复改变了哪些行为。每项判定标准用一行记录证据,列明代码版本和环境版本、修复前与修复后各自的命令、退出码和日志、实际结果,以及状态(通过、失败、受阻或未运行)和局限性。将 Pull Request 描述保存在本地,作为草稿供评审。 对于这个 webhook 重复投递示例,指出数据库事务提交前和提交后的具体故障点,用独立的数据库连接证明并发处理重复投递时会发生争用,并说明有关事务隔离、接收记录保留以及新旧版本混合部署的假设。 在这个 webhook 重复投递示例中,先等旧版消费者处理完在途任务,再找出没有匹配接收记录的旧版订单,之后才能建议恢复处理保留下来的投递。按现有队列或隔离流程,暂停处理受影响事件键对应的事件。添加一个测试,预置一笔缺少接收记录的订单及一次待执行的投递重试,验证暂停处理期间既不会创建第二笔订单,也不会返回成功确认。仅依据可信且不可变的事件标识、规范载荷和订单已提交的证据进行核对。如果证据缺失或相互矛盾,继续隔离相关事件,交由负责人审查。不要凭空构造指纹、删除接收记录或重放尚未查清的旧版事件。 除非我指定其他获准使用的来源,否则只使用提供的故障资料和代码仓库。如果提供了监控数据源,只访问明确获准使用的只读监控数据源。仅在此代码仓库中写入代码和任务产物,并且只使用该代码仓库的隔离测试数据库。不要直接连接生产环境的应用主机或数据库主机,也不要修改生产系统。不要重放生产事件、修改线上数据或监控、创建或发布对外通报、合并代码或部署。

    在准备好的云端环境中,让 Codex 调查一起范围明确的故障。目标是交付可供工程师审查的结果,包括有证据支持的故障解释、修复前无法通过的回归测试、针对该缺陷的补丁,以及实际运行测试所得的证据。

    这种做法适用于故障已得到控制、接下来需要查明并修复应用缺陷的情况。如果现有证据不足以确定原因,请清楚记录调查过程,并指出下一步如何诊断。

    准备环境和故障资料包

    1. 在网页应用或桌面应用中,选择工作位置 > 云端,然后选择已发布的环境。

    2. 如需创建环境,请选择创建环境,选好 GitHub 代码仓库,然后让 Codex 准备运行时、依赖项和隔离的测试服务。

    3. 查看环境配置报告,解决导致检查失败的问题,并在开始新任务前发布环境。

    如果依赖项或服务配置发生变化,请编辑可复用环境,测试后重新发布,然后在新任务中验证更新后的环境。

    刷新代码仓库不会重新运行安装或启动命令,已有任务也会保留各自的状态。

    请分别配置需要访问的网络目标和测试凭据。允许连接某个目标并不会授予服务访问权限。

    在新任务中,确认受影响版本的检出代码、依赖项、各项检查和可丢弃的测试数据库均可正常使用。记录起始提交和测试基线。

    请备齐初步调查所需的资料。将脱敏后的资料包放入代码仓库,或通过其他方式让任务能够访问其中的文件。开始前,应由工程师整理并核对以下资料:

    输入 应包含的内容
    故障摘要 故障 ID、UTC 时间范围、预期行为和实际观察到的行为、已知影响及当前状态。区分已确认的数量和估算值。
    发布版本信息 已部署的提交 SHA、部署时间、不含机密信息的相关配置值,以及最后一个已知正常的发布版本(如有)。
    关联证据 带有时间戳、事件 ID、请求 ID、追踪 ID 和文件引用的日志及追踪片段。脱敏时,同一标识符的替换值应保持一致。
    安全复现 测试请求体、相关测试夹具,以及如何在不调用线上服务的情况下执行可疑代码路径。
    代码仓库说明 相关路径、数据库引擎、测试命令、允许的改动,以及负责审查结果的工程师。

    请勿在资料包中包含访问令牌、客户载荷或个人数据。

    监控集成是可选的。如果您使用监控集成,请仅授予相关项目和时间范围内的只读访问权限。基于文件的工作流无需监控集成。代码仓库说明应要求将测试凭据与生产配置分开。

    运行起始提示词

    使用本页的起始提示词,并将占位符替换为您的故障 ID、代码仓库和资料包路径。首轮结果应说明证据与受影响代码之间的联系、哪些行为可以复现,以及还缺少哪些信息。

    只有当证据表明代码存在缺陷时,才让 Codex 继续实施修复。否则,请审查调查结果并补充缺少的输入。看似合理的解释、最近的代码改动或在另一发布版本上通过的测试,都不足以确定故障原因。

    示例:重试 webhook 时生成了重复订单

    使用可运行的故障示例练习调查。示例包含准备好的故障资料包、存在可复现缺陷的处理程序、修正后的处理程序,以及 PostgreSQL 测试。

    服务收到 order.created webhook 后,会写入订单并记录该事件已处理。故障期间,一次重试似乎生成了第二笔订单。团队已让服务恢复稳定,现在需要一个可供审查的补丁。

    示例使用 TypeScript、Node.js 测试运行器和 PostgreSQL。其可丢弃的测试夹具包含 event_receipts 表。该表的标识列不允许为空,且 (provider, account_id, event_id) 上有不可延迟检查的唯一键。

    该数据库模式允许在订单创建前先写入回执以取得事件处理权,并保留规范化载荷的指纹,以检测同一事件键是否被重复用于相互冲突的载荷。

    如果您的应用要求在取得处理权时就提供订单外键,或缺少判断此类冲突所需的证据,请先暂停,单独决定如何处理数据库模式或设计。

    在证据记录中注明确切的运行时、依赖锁定信息、PostgreSQL 版本、事务隔离级别和回执表模式。可下载的夹具固定使用 Node.js 24.19.0、PostgreSQL 17.6 和 pg 8.23.1。

    对于示例提供的 Compose 配置,请准备一个 Docker 守护进程可正常运行的环境,并在发布前验证 docker info 能成功执行。其数据库仅接受公开的测试凭据,且仅绑定到本地回环接口。调整测试以适配您的应用时,请使用应用实际采用的数据库引擎和相关设置。

    本示例假设 PostgreSQL 使用 READ COMMITTED 隔离级别,提供方的事件 ID 保持稳定,且回执保留期覆盖提供方的重试和重放窗口。

    修正后的处理程序在同一个数据库事务中写入回执和订单。测试夹具创建可丢弃的数据库及 delivery_holds 表,以模拟现有队列的隔离流程。该表仅用于测试基础设施,无需为应用添加相应的迁移。

    应用修复不会新增队列、数据库服务、模式迁移或监控集成。如果上述假设不成立,请暂停并重新确定修复范围。

    运行示例

    解压 ZIP 文件,进入解压后的目录,然后使用 Docker 和 Compose 运行以下命令:

    docker compose -p codex-incident-rehearsal up -d --wait postgres
    docker compose -p codex-incident-rehearsal run --rm runner node --experimental-strip-types main.ts baseline
    docker compose -p codex-incident-rehearsal run --rm runner node --experimental-strip-types main.ts regression
    docker compose -p codex-incident-rehearsal run --rm runner
    docker compose -p codex-incident-rehearsal down --volumes

    基线命令必须以退出码 1 结束。重试断言预期有一笔订单和一条回执,实际却有两笔订单和一条回执。回归命令对修正后的处理程序运行相同的断言,必须以退出码 0 结束。

    最后一条测试命令覆盖完整的测试矩阵,包括独立连接、数据库锁争用,以及对历史遗留的无回执订单所对应的投递进行隔离。

    如果您的安装提供的是 docker-compose,请用它替换 docker compose。按顺序执行这些命令。测试套件仅重置其标记的测试数据库模式。

    查看事务处理程序

    TypeScript 代码片段来自 ZIP 压缩包中的 main.ts。

    使用随附的数据库夹具,运行所选语言的完整示例文件。

    在同一事务中取得事件处理权并写入订单
    插入回执以取得事件处理权并写入订单
    import type { Client } from "pg";
    
    type IncidentEvent = {
      provider: string;
      accountId: string;
      eventId: string;
      payload: { type: string; orderId: string; amountCents: number };
    };
    
    async function fixed(
      client: Client,
      input: IncidentEvent,
      hook = async (_boundary: string) => {}
    ) {
      await assertNotHeld(client, input);
      await hook("beforeClaim");
      await client.query("BEGIN ISOLATION LEVEL READ COMMITTED");
      let committed = false;
      try {
        const claimed = await client.query(
          `INSERT INTO event_receipts(provider, account_id, event_id, payload_fingerprint)
           VALUES ($1,$2,$3,$4)
           ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING event_id`,
          [...key(input), fingerprint(input)]
        );
        trace("receipt-claim-result", client, input, {
          inserted: claimed.rowCount === 1,
        });
        if (claimed.rowCount === 1) {
          await hook("afterClaim");
          await writeOrder(client, input);
          await hook("afterOrder");
        } else {
          // A new READ COMMITTED statement sees the winner after its commit.
          await checkReceipt(client, input);
        }
        await client.query("COMMIT");
        committed = true;
        trace("transaction-committed", client, input);
        await hook("afterCommit");
        trace("acknowledged", client, input, acknowledgment);
        return acknowledgment;
      } catch (error) {
        if (!committed) {
          await client.query("ROLLBACK");
          trace("transaction-rolled-back-no-ack", client, input);
        } else {
          trace("committed-response-lost-no-ack", client, input);
        }
        throw error;
      }
    }

    1. 提供精简的故障资料包

    可按以下文件组织资料包:

    incidents/INC-DEMO-014/incident.md
    incidents/INC-DEMO-014/logs.ndjson
    incidents/INC-DEMO-014/release.json
    incidents/INC-DEMO-014/order-created.sanitized.json

    在此场景中,release.json 记录的示例发布版本 SHA 为 4a1c9e7d2b6f8a0c3d5e7f9012a4b6c8d0e2f413,部署时间为 2026-09-22T11:58:00Z。故障发生在同一天的 12:03:00Z–12:05:00Z。资料包显示,两笔内部订单关联到提供方的同一事件。准备自己的资料包时,请列出已确认的受影响数量,并标明哪些数字是估算值。

    脱敏日志中包含以下可相互关联的观测记录:

    UTC 时间 关联信息 观测结果
    12:03:04.110 事件 evt_demo_042,账户 acct_demo_01,请求 req_demo_a,追踪 trace_demo_a 首次投递进入 webhook 处理程序。
    12:03:04.145 同一事件,首次投递的追踪 订单 ord_demo_101 已提交。
    12:03:04.150 同一工作进程 工作进程退出,此前未记录回执写入成功或响应。仅凭这段日志无法证明回执不存在。
    12:03:14.203 同一提供方、账户和事件,请求 req_demo_b,追踪 trace_demo_b 重试请求进入处理程序。处理程序在日志中记录未找到匹配的回执。
    12:03:14.241 同一事件,第二次投递的追踪 订单 ord_demo_102 已提交,并已记录一条回执。

    同一事件的各次投递应使用稳定的事件 ID,而每次投递应使用不同的请求 ID 和追踪 ID。如果仅按请求标识事件,就无法看出重试与原始事件的关系。

    2. 追查证据并检验假设

    故障报告推测重复订单由重试风暴引起。Codex 应将其视为有待检验的假设。观察到两次投递不足以证明发生了重试风暴,而且 webhook 处理程序本就必须能够处理正常的重试。

    检查示例中存在缺陷的源代码可以看到,处理程序先查询回执,再提交订单,最后在另一个事务中写入回执。两次提交之间的间隙更能解释故障。如果工作进程在这段时间内发生故障,已提交的订单可能没有回执,重试就可能再创建一笔订单。如果检查和写入分开执行,两次并发投递也可能在任何一方写入回执之前都通过检查。

    让 Codex 追查实际运行的处理程序及其事务边界,并引用相关代码行。它应确认资料包中的发布版本与被测代码一致。如果测试使用其他提交,则应说明这会如何限制结论的适用范围。

    3. 修改处理程序前先复现故障

    使用示例 webhook 和隔离的 PostgreSQL 数据库添加回归测试。在原处理程序中,紧接订单写入操作、尚未写入回执时,设置一个仅用于测试的故障注入钩子。

    根据实际事务边界确认,此时原订单已经提交。使用相同的提供方、账户和事件重试,并断言恰好存在一笔订单和一条匹配的回执。示例中预置缺陷的实现应因出现两笔订单而未通过测试。

    修复后,在订单写入语句执行完毕、共享事务提交之前触发相应的钩子。失败的尝试必须既不留下订单,也不留下回执。

    重试并断言恰好有一笔订单和一条回执。各版本使用相同的业务断言,并记录每个版本中钩子的位置。

    先在原实现上运行新测试。对于本示例预置的缺陷,预期测试会因出现两笔订单而失败。保存命令、起始提交、退出码和断言输出。如果未出现预期的失败,请先调查差异,再修改处理程序。

    注入异常可以检验应用的事务行为。请在记录中注明,此方法无法复现所有可能的主机、网络或数据库故障。

    4. 实施证据支持的最小修复

    针对这一缺陷,请在同一个数据库连接的同一个事务中,先通过插入事件回执取得处理权,再写入订单。利用现有唯一键执行 INSERT ... ON CONFLICT (provider, account_id, event_id) DO NOTHING RETURNING ...。

    只有成功插入回执的投递才能写入订单,并且只能在提交后返回成功确认。事务失败时,两次写入都会回滚。请勿捕获唯一性约束错误后继续使用已中止的事务。

    并发到达的另一次投递可能需要等待第一个事务。如果第一个事务提交,第二次投递尝试取得处理权时不会插入任何行。此时应在 READ COMMITTED 隔离级别下重新执行 SELECT,按既定策略核验已存储的事件标识和载荷,然后直接返回既有的重复投递确认响应。

    如果第一个事务回滚,竞争方就可以取得处理权并处理事件。如果跳过插入后找不到回执、事件标识冲突,或数据库出现暂时性错误,必须按文档规定的重试或错误处理流程操作,不得返回虚假的成功响应。

    在更严格的隔离级别下,如果出现序列化失败,必须按代码仓库规定的策略重试整个事务,并遵守重试限制。请参阅 PostgreSQL 的 INSERT 冲突处理行为和事务隔离文档。

    无论使用内存集合,还是分开执行“先检查再插入”,都无法防止并发工作进程或重启导致的重复处理。请根据提供方对事件标识的约定确定键的作用域。如果看似同一事件的标识或载荷信息相互冲突,应明确报告不一致,不能将其默认为有效的重复投递。

    本示例的业务数据变更完全发生在同一个数据库中。如果实际处理程序还会发送邮件、从银行卡扣款或调用其他服务,仅靠该事务无法保证这些外部操作的幂等性。在扩大修复范围前,请明确这一边界,并查明系统现有的投递或幂等机制。

    5. 验证修复后的行为

    请让 Codex 同时提供原实现的失败结果和修复后的结果。在明确标出的事务边界使用仅用于测试的钩子,并从单独的连接检查已提交的状态。示例通过了 11 项本地 PostgreSQL 测试。下载包中的 test-evidence.md 记录了这些结果,以及在云端运行和部署时仍需完成的检查。请在已发布的环境中运行测试套件,并在依赖该恢复流程之前测试提交期间连接实际断开的情形。

    检查项或故障注入点 必须满足的行为
    首次投递,以及首次提交后的重复投递 首次投递创建一笔订单和一条回执。重复投递返回约定的确认响应,记录数量保持不变。记录确切的状态码和响应体。
    取得事件处理权之前 发生故障时不创建订单或回执,也不返回成功确认。重试后创建一笔订单和一条回执。
    取得处理权之后、写入订单之前 发生故障时回执回滚,订单不存在。重试可以正常取得处理权并处理事件。
    写入订单之后、提交之前 发生故障时两条记录均回滚。该检查对应原代码中订单已提交但缺少回执的缺陷。修复后重试,最终有一笔订单和一条回执。
    提交之后、返回确认之前 模拟响应丢失。两条记录均保持已提交状态。重试返回重复投递确认,不会再创建订单。
    提交结果未知 将提交前后连接断开的情况与普通异常分开模拟。没有依据时不得返回成功确认。无论第一个事务提交还是回滚,使用同一个稳定的事件键重试都必须安全。如果未测试这种传输故障,请标记为未运行。
    并发重复投递:第一个事务提交 让两个独立的连接或工作进程争用同一事件键。让先取得处理权的一方暂停,并在放行之前启动竞争方。验证确实发生争用,再放行先取得处理权的一方。双方都按预期流程返回确认,最终恰好有一笔订单和一条回执。
    并发重复投递:第一个事务回滚 重复上述受控的并发过程,但让先取得处理权的一方在提交前失败。回滚后,竞争方取得处理权,创建一笔订单和一条回执。检查双方的响应和最终状态。
    事件标识和载荷冲突 不同事件应互不影响。不同账户或提供方使用相同事件 ID 时也应互不影响。对于同一作用域内 ID 相同但规范化载荷冲突的事件,应按约定流程处理冲突。不得创建第二笔订单,也不得将不同的业务操作默认为已成功处理。
    历史订单缺少回执且仍有待重试的投递 预置一笔已提交但没有回执的历史订单。恢复重试前,识别其事件键并暂停该键的投递。被暂停的重试既不返回成功确认,也不创建记录。依据可信证据完成核对补录后,系统可返回重复投递确认,此时有一笔原有订单和一条回执。如果证据缺失或冲突,则继续暂停该键的投递。
    更广泛的服务检查 运行相关集成测试、代码规范检查和类型检查。分别列出新增失败、原有失败和无法运行的检查。

    使用屏障或闭锁等同步机制协调并发,并设置有限的超时时间。不要靠休眠或仅靠两个 Promise 来协调执行时序。测试清理时要释放被阻塞的工作进程,并使用可丢弃的测试夹具。仅测试异常不足以证明进程突然终止、传输中断或生产环境并发时的实际行为。

    示例在版本固定的运行器中使用 node --experimental-strip-types main.ts baseline、node --experimental-strip-types main.ts regression 和 node --experimental-strip-types main.ts。结构化输出会记录事务边界、已提交的行数、确认响应的状态码和响应体,以及实际观察到的造成阻塞的数据库后端进程 ID。

    调整此工作流时,请使用您的代码仓库实际定义的命令,并报告真实结果。交接材料中应注明跳过的检查或不可用的依赖项,并说明这些情况对结论可信度的影响。

    审查交接材料

    共用证据记录

    针对每项验收标准,使用故障处理工作流的证据格式。根据实际观察到的输出填写以下模板。如果基线版本中还没有某项新测试,请将“尚未添加”与已有检查失败区分开来。

    Criterion / test: [specific behavior and test location]
    Environment: [published setup reference; runtime, database and dependency versions]
    Before: [revision + test-only diff ID; command; exit code; observed assertion; log path]
    After: [final revision or base + diff ID; command; exit code; observed assertion; log path]
    Status: [pass / fail / blocked / not run]
    Limits / reviewer action: [untested behavior, blocker, or decision required]

    将失败和通过的每次运行分别关联到实际测试的代码状态,包括在原版本上仅为测试添加的改动。交接时一并保留日志、响应夹具和最终代码差异。如果最终版本有变动,就需要更新证据。未运行或受阻的检查不能计为通过。

    让 Codex 将代码差异和以下审查材料保存在代码仓库中:

    • incident-investigation.md:时间线、证据引用、已检验的假设、有证据支持的原因,以及仍不确定的事项。
    • test-evidence.md:基线提交、回归测试失败时的输出、修复提交或代码差异、已通过的针对性检查、更广泛的检查及局限性。
    • pr-draft.md:简要说明缺陷、行为变化、测试证据和剩余风险。
    • deployment-handoff.md:已验证的数据库模式、隔离级别和回执保留期假设,明确指定的发布负责人,部署前检查,重复订单、确认响应及错误指标,以及下文所述的发布和回滚条件。

    接受补丁前,请确认原代码无法通过新测试、修复后能够通过,且代码改动确实解决了已证实的缺陷。在 webhook 示例中,请检查事件键的作用域、事务边界、并发测试覆盖情况,以及事务以外的影响。已有的重复订单应单独审查。防止新增重复订单并不能修复历史记录。

    规划部署和回滚

    代码补丁只能保护运行修正后处理程序的工作进程。旧工作进程仍可能先写入订单,再尝试插入回执取得处理权,因此混合版本的金丝雀发布不能证明缺陷已消除。

    部署负责人必须选择经过测试的混合版本策略,或遵循已有操作手册,暂停接收事件,等待旧工作进程处理完在途任务,更新所有消费者,然后恢复投递已保留的事件,确保不丢失任何投递。

    选择后一种方案前,请确认提供方和队列的重试及保留行为。不要假设暂停处理一定不会造成丢失。

    恢复投递已保留的事件前,找出已经提交但没有匹配回执的历史订单。暂停接收并等待旧消费者处理完在途任务,可以阻止旧逻辑继续写入,但无法修复已有订单。使用现有队列或隔离流程,暂停每个受影响事件键的投递。如果历史记录不足以确定完整的事件标识,应继续暂停受影响的投递或受影响时间范围内的投递,交由负责人审查,不能宣布扫描已经完成。

    只有当可信且不可变的提供方、账户和事件标识,加上规范化载荷证据和已提交的业务记录,足以确定此前实际执行了哪些操作时,才可对已暂停的事件键进行核对补录。

    按照获批的核对补录流程,记录匹配的回执,不重复执行业务变更,然后解除对该键的暂停措施。

    如果证据缺失、载荷冲突或存在多条业务记录,应继续隔离受影响的键,交由负责人审查。重建原始事件的指纹时,不能用重试载荷代替原始事件的可信证据。

    只有当每个受影响的键都已完成核对补录,或其暂停措施仍对所有消费者有效时,才满足恢复投递的条件。

    在预发布环境中预置一笔历史订单及其待处理的重试。验证暂停措施能阻止创建另一笔订单,并阻止返回任何成功确认。依据可信证据完成核对补录后,重试可以收到重复投递确认,订单数量仍为一笔。还要演练无法完成核对的情况,确保该键继续处于暂停状态,且不会凭空生成回执。将这一恢复条件连同暂停和排空、消费者版本、保留期及回滚检查一并写入部署交接材料。

    发布前,请验证现有唯一约束存在且有效,所有消费者的回执键和载荷处理策略一致,清理回执不会使仍可能被重放的事件失去去重保护,并确认外部操作仍在此补丁的范围之外。

    在预发布环境中演练所选流程,以及工作进程发生故障后的重试。记录负责人设定的观察窗口,以及重复订单、webhook 错误、确认响应延迟、锁等待和重试积压达到何种阈值时应停止发布。不要自行编造生产环境阈值。

    回退到旧处理程序可能再次引发重复订单。回滚交接材料必须明确遏制故障的措施(例如获批的暂停和排空流程)、可安全使用的版本,以及决定何时恢复处理的负责人。保留回执,不要为了让重试继续而删除回执。历史重复订单的补救方案需要单独审查。

    部署决策和生产环境的补救工作由工程师负责。隔离测试通过可作为审查证据,但不足以证明生产环境运行正常。请创建 Pull Request,执行常规 CI 和审查流程,并在审查草稿后按照团队既定的管控流程部署。

    在同一任务中继续

    使用有针对性的后续提示词来澄清疑点或完善交接材料:

    请针对两种情况审查补丁:同一事件的两次投递并发到达,以及工作进程发生故障后重试。说明测试已验证哪些行为,还有哪些行为未经测试。只修改这个处理程序及其回归测试,并在交接材料中补充仍然存在的风险。

    如果首次运行未能复现故障:

    请停止实施修复。列出现有证据已排除的假设,并指出剩余假设中最有依据的一个。说明要将它与其他假设区分开来,最少还需要哪些脱敏资料,或需要做哪个最小规模的隔离实验。根因仍应标记为未确认。

    相关使用场景