claude code 对第三方 API 调用的错误重试策略生成是否健壮

去年秋天，我给一家支付中台做代码审查。项目大量使用 Claude Code 生成 API 集成层，其中涉及 Stripe 的扣款调用、Twilio 的短信下發、以及一个内部风控接口。审查日志里有一条记录我记得很清楚：某个扣款请求因为网络抖动连续重试了四次，最终成功扣款，但 Stripe 后台出现了两笔完全相同的 charge ID。财务对账的同事花了整整一个下午才把这件事搞清楚。

问题出在重试策略上。Claude Code 生成了那个 try-catch 块，但它没有生成 Idempotency-Key。

这不是一个“Claude Code 写不好代码”的故事，而是一个“我们误解了健壮性”的故事。大多数人问的是：Claude Code 能生成重试策略吗？能。指数退避、随机抖动、状态码分支判断，这些它都会。但“能生成”和“能投入生产”之间，隔着一整套可靠性工程的实践判断。

过去四个月，我在三个不同项目上系统性地压测和审查了 Claude Code 生成的 API 错误重试代码，涵盖 Python 和 TypeScript 两种语言环境，分别面向支付、物流追踪、内部微服务调用三种场景。本文的结论不是“好不好”的二选一判断，而是一份解剖报告：在什么条件下，Claude Code 生成的重试策略是健壮的；在什么条件下，它会悄无声息地埋雷。

一、核心结论：一个分层判断框架

先说结论，再展开论证。

Claude Code 对第三方 API 调用的错误重试策略生成，在基础网络容错层面是健壮的，但在幂等性、熔断、超时协同这三个生产级维度上存在系统性缺失。 这并不意味着它“差”，事实上，对于大多数内部服务间调用、低频请求、非关键路径的场景，它生成的重试逻辑已经足够。但如果你把它用在了支付、下单、库存扣减、短信验证码下发等高频/高敏场景，且没有进行二次封装，那么你正在承担一个本可以避免的风险。

下面这张表是我基于四个月测试得出的分层判断框架，它可以帮你快速定位自己的场景属于哪一层：

如果你只记住一句话：Claude Code 生成的是一个合格的重试骨架，但不是一件直接可穿的铠甲。在关键场景下，你需要亲手给它装上三块护甲，幂等性、熔断器、超时协同。

二、评测方法：我是怎么测试的

在展开详细分析之前，先交代我的测试方法和边界条件。这不是一个跑几个 demo 就下结论的评测，而是一个模拟生产环境的系统性压测。

2.1 测试环境配置

我搭建了一个本地 API 模拟服务，使用 Python 的 FastAPI 搭建，能够返回我预设的各种 HTTP 错误和异常。模拟服务部署在一台 4核8G 的机器上，网络延迟通过 tc（traffic control）命令注入，模拟了五种典型故障场景：

Claude Code 版本：claude.ai 上使用的 Claude 3.5 Sonnet 和 Claude 3 Opus（部分场景对比），以及本地 CLI 环境下的 Claude Code。

生成方式：我使用相同的 Prompt，在三个不同日期、三个不同会话中重复生成重试代码，以观察 Claude Code 输出的一致性。Prompt 只描述业务需求，不加任何“请添加熔断器”之类的硬性提示，以评估其默认行为。

2.2 评测标准

我从可靠性工程的角度定义了六个评测维度：

1. 可重试错误识别准确性：是否正确区分了网络层错误、可重试的 HTTP 状态码（429、5xx）、不可重试的客户端错误（400、401、403、404）和协议异常。
2. 退避算法质量：是否采用了指数退避（exponential backoff）加随机抖动（jitter），退避基数、上限是否合理。
3. 幂等性保障：是否在内置重试机制中包含了幂等性 Key 的生成或传递逻辑。
4. 熔断能力：是否在连续失败达到阈值后自动中止重试，防止雪崩。
5. 超时协同：单次请求超时时间与总重试时间窗口的关系是否合理。
6. 边界条件处理：是否处理了最大重试次数耗尽后的降级行为、并发重试下的线程安全性、异常吞噬等细微问题。

每个维度评分 1-5（5 分为生产级可信任），然后再根据业务场景加权综合。

三、Claude Code 做对了什么，它的“及格线”表现

在进入“补丁”之前，我想先说清楚 Claude Code 在重试策略上确实做得不错的部分。这些能力构成了一个及格的重试骨架，也是我们信任它的基础。

3.1 指数退避加随机抖动的生成质量

我在所有测试会话中，Claude Code 无一例外地生成了指数退避逻辑。下面是一段典型的 Python 输出（经过我的格式化，保留了逻辑结构）：

import random
import time

import asyncio

from typing import Callable, Any

async def retry_with_backoff(

func: Callable,

max_retries: int = 3,

base_delay: float = 1.0,

max_delay: float = 30.0,

jitter_factor: float = 0.1

) -> Any:

"""

执行带有指数退避和随机抖动的重试逻辑。

"""

last_exception = None

for attempt in range(max_retries + 1):

try:

return await func()

except (aiohttp.ClientError, asyncio.TimeoutError) as e:

last_exception = e

if attempt == max_retries:

break

指数退避：delay = min(base * 2^attempt, max_delay)

delay = min(base_delay * (2  attempt), max_delay)

随机抖动：在 [delay*(1-jitter), delay*(1+jitter)] 范围内随机

jitter = random.uniform(-jitter_factor * delay, jitter_factor * delay)

actual_delay = delay + jitter

await asyncio.sleep(actual_delay)

raise last_exception

• 真正的指数退避：base_delay * (2 attempt) 确保每次重试间隔以 2 倍增长，1s、2s、4s，而不是线性增长。在第三方 API 负载高时，这给了服务端呼吸空间。
• 全抖动（Full Jitter）的变体：虽然没有采用 AWS 推荐的 random.uniform(0, delay) 全抖动，但这种 ±10% 的抖动已经能有效避免多个客户端在相同时间点重试导致的“惊群效应”。
• 合理的异常捕获范围：只捕获了 ClientError 和 TimeoutError，没有愚蠢地 except Exception。

但这些参数也是我需要提醒你的第一个地方：base_delay=1.0 和 max_retries=3 是 Claude Code 的默认值，在你的业务场景下可能完全不合适。 比如，如果你的下游是一个平均响应时间 2 秒的 API，那么 1 秒的 base_delay 意味着第一次重试几乎会在下游还在处理上一次请求时就发出，这会导致重复处理。我会在后文详细讲这个问题。

3.2 HTTP 状态码的智能分支判断

更让我意外的是 Claude Code 对 HTTP 状态码的处理。它不是简单地“遇到 200 以外的都重试”，而是构建了清晰的分支逻辑。下面是我直接从 Claude Code 输出中提取的实际代码片段（经过了我在测试中触发的边界条件标识）：

// TypeScript 版本：Claude Code 自动生成的 HTTP 状态码判断逻辑
async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {

let lastError: Error;

for (let attempt = 0; attempt <= maxRetries; attempt++) {

try {

const response = await fetch(url, options);

if (response.ok) return response;

// 关键分支点：按状态码分类处理

if (response.status === 429) {

// 限流：读取 Retry-After 头

const retryAfter = response.headers.get('Retry-After');

const delay = retryAfter

? parseInt(retryAfter) * 1000

: Math.pow(2, attempt) * 1000 + Math.random() * 1000;

await sleep(delay);

continue;

}

if (response.status >= 500) {

// 服务端错误：可以重试

const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;

await sleep(delay);

continue;

}

// 4xx 客户端错误（非429）：不重试，直接抛出

throw new ApiError(response.status, await response.text());

} catch (error) {

if (error instanceof ApiError) throw error; // 客户端错误直接抛出

if (attempt === maxRetries) throw error;

lastError = error as Error;

// 网络层错误：重试

const delay = Math.min(1000 * Math.pow(2, attempt), 30000);

await sleep(delay + Math.random() * 1000);

}

}

throw lastError!;

}

这段代码有三个我在传统手写代码中经常看到但 Claude Code 自动处理了的细节：

第一，它对 HTTP 429 的专用处理：读取 Retry-After 响应头。这是很多中级开发者会忽略的行为。当你的下游是一个有严格限流策略的 API（比如 GitHub API、Twitter API），遵循 Retry-After 比你自己胡乱退避要靠谱得多。

第二，它清晰区分了“可重试错误”和“不可重试错误”：HTTP 4xx（除 429 外）表示客户端的问题，你的请求格式错了、鉴权失败了、或者资源不存在。在这些情况下，重试毫无意义，只会浪费资源并可能触达下游的限流阈值。Claude Code 在这一点上的判断是精准的。

第三，它将网络层异常与 HTTP 层状态码分开处理：fetch 网络失败时返回的不是 HTTP 响应，而是一个异常；它在 catch 块中正确地完成了回退逻辑。

但这些代码也暴露了一个信息：HTTP 429 的处理中，如果 Retry-After 头不存在，它回退到了指数退避，这是合理的。但如果 Retry-After 的值是 120 秒呢？你的总重试窗口可能会膨胀到难以接受的程度。Claude Code 没有为这个边界设置最大等待上限。

四、三个致命缺陷：Claude Code 系统性地遗漏了什么

现在进入本文的核心部分。前面说的是“及格线”，接下来要说的是“为什么及格不等于可以上生产”。

在经历了四个月的测试和三个项目的代码审查后，我总结出了 Claude Code 默认重试策略的三个系统性缺失。这三个缺失不是偶发的，它们在我的每一次测试中，无论 Prompt 如何变化，只要不显式提及相关关键词，Claude Code 都不会主动生成。

4.1 致命缺陷一：幂等性，它不理解“支付”这个词的含义

回到开头那个 Stripe 重复扣款的例子。当我审查那段导致重复扣款的代码时，我发现 Claude Code 生成的重试逻辑本身是没有 bug 的，它正确地捕获了网络超时、正确地执行了退避、正确地重试了。问题在于，重试之前的那个请求，可能在服务端已经被处理了。

这就是幂等性的核心：在分布式系统中，一个请求可能因为网络延迟而超时，但实际已经在服务端执行完毕。当你“重试”时，你不是在“重新发送第一次请求”，而是在“发送第二次请求”。

Claude Code 默认生成的重试策略中，完全没有 Idempotency-Key 的概念。 这不是一个代码 bug，而是一个业务理解的缺失。它不“知道”它在调用的是一个支付 API、一个库存扣减 API、还是一个幂等的查询 API。

下面是我在测试中使用的 Prompt 和生成结果的关键差异：

Prompt A（不提及幂等性）：

"Write a Python function that calls the Stripe API to create a charge, with proper error handling and retry logic."

生成结果：包含指数退避、状态码判断、网络异常捕获，但没有 Idempotency-Key 生成逻辑。

Prompt B（明确提及幂等性）：

"Write a Python function that calls the Stripe API to create a charge, with proper error handling, retry logic, and idempotency support."

生成结果：在请求头中包含了基于 UUID 的 Idempotency-Key，且正确理解了这个 Key 应该在重试中保持不变。

这个对比揭示了一个关键事实：Claude Code 的能力天花板不在于代码编写，而在于业务语义的识别精度。 当你没有在 Prompt 中明确告知它“这个 API 需要幂等性”时，它不会从“create a charge”这个表述中自行推断出幂等性的必要性。在它的训练数据中，“写一个 API 调用的重试逻辑”和“写一个支付 API 的重试逻辑”共享了同一套“重试”模式，而没有进行场景分层。

为什么这在实际项目中特别危险？

不是因为 Claude Code 写错了什么，它没有写错，而是因为开发者对它的信任会产生盲区。

如果你手动写支付重试代码，你大概率会搜索 Stripe 文档，看到 Idempotency-Key 的说明，然后加上。但当你用 Claude Code 生成代码时，它的输出“看起来”是完整的，有退避、有抖动、有状态码处理，你会天然地认为“它考虑到了该考虑的”。这种“看似完整”的假象，是 AI 辅助编程中最危险的陷阱。

我在自己的团队里做了一个小实验：让三个中级开发者 review 一段 Claude Code 生成的支付 API 重试代码，但不告诉他们这是 AI 生成的。三个人中只有一个人在第一次 review 时指出了缺少幂等性处理。其他两人在被告知后才意识到这个问题。

4.2 致命缺陷二：熔断器，当失败循环耗尽你的线程

第二个系统性缺失是在高并发场景下更加致命的问题：Claude Code 默认不会生成熔断器（Circuit Breaker）模式。

让我用一个真实配置来说明这个问题。假设你有一个 API 网关，它的线程池大小是 200。下游的第三方物流 API 因为故障进入了持续性 503 响应。如果你使用的是 Claude Code 默认生成的重试逻辑（没有熔断器），以下是会发生的事：

1. 第一批 200 个请求到来，全部调用物流 API。
2. 全部 200 个请求在等待 503 响应后进入指数退避的等待状态（比如第一次重试等 1秒，第二次等 2秒，第三次等 4秒）。
3. 在退避期间，这些线程仍然被占用。
4. 第二批请求到来，可用线程数接近 0。
5. 线程池耗尽，整个网关对外表现为不可用。

这就是“雪崩”。一个下游服务的故障，通过无防护的重试机制，扩散到了整个系统。

Claude Code 生成的重试代码解决的是“单个请求的局部可靠性”，而熔断器解决的是“系统级的全局可靠性”。这两个层面在它的默认输出中被完全割裂了。

下面是我在压测中得到的对比数据。我使用了相同的 Python FastAPI 网关，分别测试了三种重试策略在“下游持续 503”场景下的表现：

在我的日志中也观察到了相同的时间线事件：

熔断器的缺失不是一个小问题，它是一个在特定场景下从“功能正常”到“系统崩溃”的质变点。

4.3 致命缺陷三：超时与重试的策略协同，它们在对打

第三个问题是大多数人在审查代码时根本不会注意到的细节。

Claude Code 生成的代码通常会同时配置“请求超时”和“重试间隔”。但它们之间缺少协同计算。

让我用数字来解释。假设你的下游 API 的 P99 响应时间是 5 秒。Claude Code 默认可能生成这样的配置：

• 单次请求超时：timeout=10（秒）
• 最大重试次数：3
• 退避策略：指数 base=2，即 2s, 4s, 8s

现在计算总耗时：

• 第一次请求超时：10秒
• 第一次重试等待：2秒
• 第二次请求超时：10秒
• 第二次重试等待：4秒
• 第三次请求超时：10秒
• 第三次重试等待：8秒
• 第四次请求超时：10秒

总等待时间上限：10+2+10+4+10+8+10 = 54 秒。

如果你的上游（比如一个用户的前端页面）设置的超时是 30 秒，那么这个重试策略就是无意义的，用户早在 30 秒的时候就收到超时错误了。更糟的是，你的服务器还在后台消耗资源继续重试。

Claude Code 生成代码的“局部合理性”和“系统合理性”之间存在断裂。 它会在一个函数内部写出自洽的逻辑，但不会跨边界计算：上游的超时阈值是多少？当前请求在整个链路中的位置是什么？总的重试时间窗口是否超过了上游的容忍度？

这种断裂在微服务架构中会被放大。一个请求可能穿过三个服务，每个服务对它的下游都有重试逻辑。Claude Code 为每个服务独立生成的重试策略叠加在一起，会出现重试次数指数爆炸的问题。

举个例子：

从最外层的“重试3次”，变成最内层第三方API收到的最多256次请求。 这不是一个理论上的极端情况，在一个故障持续30秒的场景下，如果延迟在每个层面都在累积，这个数字会真实发生。

Claude Code 不会看到这个全局图。它只看到了函数内部的局部最优解。

五、为什么这些缺失会发生，一个模型行为的解释

我不想停留在“Claude Code 缺了什么”的层面，我想解释为什么它会缺这些。这个解释本身对于如何更好地使用 Claude Code 至关重要。

前面三个缺失有一个共同点：幂等性、熔断器、超时协同，它们都不是“代码书写”层面的问题，而是“系统设计”层面的决策。

Claude Code 的训练数据中，有很大一部分是开源代码。开源代码的 API 调用重试实现天然偏向于演示性质：它展示的是“如何做重试”，而不是“如何在生产环境中做重试”。在开源示例中：

• 幂等性 Key 的生成通常被省略，因为它依赖于具体的业务逻辑。
• 熔断器在库级别被提及（比如 pybreaker 的文档），但在具体的 API 调用示例中很少被集成。
• 超时协同是一个很少有人写文档讨论的话题，大多数开发者只在出了事故后才去修正。

Claude Code 生成的不是“最优的生产级代码”，而是它在训练数据中看到的“最常见模式的加权平均”。 由于“完整的、考虑到了幂等性和熔断的生产级重试代码”在公开训练数据中占比极低，Claude Code 在统计上就缺少生成它们的基础。

这也是为什么，当你在 Prompt 中明确提及“需要幂等性”或“需要熔断器”时，Claude Code 的输出质量会显著提升，不是因为它“学会了”，而是因为它被引导到了训练数据中那个“更高质量但数量更少”的子集。

六、不同场景下的行动建议：什么时候可以直接用，什么时候必须补

到现在为止，我已经说清楚了 Claude Code 生成了什么、缺了什么、为什么缺。接下来是你可以直接落地执行的部分。

我把使用场景分成了四个层级，每个层级有不同的处理策略。

6.1 绿区场景：可以直接使用

适用场景：

• 内部微服务之间的调用
• 幂等性由下游数据库唯一约束保证的写操作（例如insert时有唯一索引）
• 纯读操作
• 不影响用户体验的后台任务

可以信任的生成质量：

• 指数退避加抖动的质量已经合格
• HTTP 状态码分支判断正确

但你仍然需要做一件事：检查 max_retries 和 base_delay 是否适合你的下游响应时间特征。我建议一个简单的经验公式：base_delay ≥ 下游P95响应时间 × 1.5。

代码审查清单：

• [ ] 最大重试次数是否合适？（内部调用建议 max_retries=3）
• [ ] 退避上限是否合理？（建议 max_delay=30s 以内）
• [ ] 异常捕获范围是否过于宽泛？（不要 except Exception）

6.2 黄区场景：需要参数调优

适用场景：

• 面向用户的 API 网关
• 有明确 SLA 的第三方 API（但不能接受重复请求）
• 并发较高但不是关键链路的调用

需要补充的内容：

• 计算并设置合理的总超时时间窗口（总超时 = 上游超时 – 序列化耗时 – 网关耗时）
• 添加重试次数的环境变量配置（而不是硬编码）
• 添加结构化日志（每次重试记录 attempt_count、status_code、delay）

配置模板（Python 版本，可直接套用）：

from os import environ
RETRY_CONFIG = {

"max_retries": int(environ.get("API_MAX_RETRIES", 3)),

"base_delay": float(environ.get("API_RETRY_BASE_DELAY", 1.0)),

"max_delay": 30.0,  # 硬上限，防止无限等待

"total_timeout": float(environ.get("API_TOTAL_TIMEOUT", 20.0)),  # 总重试窗口

}

6.3 红区场景：必须二次封装

适用场景：

• 支付、下单、库存扣减
• 短信、邮件验证码下发
• 任何不可重入的写操作
• 高并发核心链路

必须补充三项内容：

第一项：幂等性 Key 注入

不要期望 Claude Code 自动生成。在你的二次封装层中，显式处理：

import uuid
def make_api_call_with_idempotency(payload: dict):

idempotency_key = payload.get("idempotency_key") or str(uuid.uuid4())

headers = {

"Idempotency-Key": idempotency_key,

**base_headers

}

调用 Claude Code 生成的重试核心逻辑，但传入这个 header

return retry_with_backoff(lambda: requests.post(url, json=payload, headers=headers))

关键点：idempotency_key 必须在重试之间保持不变，所以它必须在重试循环外部生成。

第二项：引入熔断器库

我推荐使用经过生产验证的库，而不是让 Claude Code 从零实现一个：

Python：pybreaker 或整合进 tenacity 的自定义停止条件

TypeScript：opossum

封装方式示例（不破坏 Claude Code 生成的核心逻辑）：

from pybreaker import CircuitBreaker
这个 breaker 是独立于 Claude Code 代码的

payment_breaker = CircuitBreaker(

fail_max=5,           # 5次连续失败后断开

timeout_duration=60,  # 60秒后尝试半开

exclude=[ValueError]  # 非网络错误不计数

)

@payment_breaker

async def call_downstream_api(data):

这里放入 Claude Code 生成的重试逻辑

return await retry_with_backoff(lambda: post_to_stripe(data))

熔断器参数建议：

第三项：超时策略协同

这是我开发的一个简单计算方法：

总窗口 ≥ base_delay × (2^0 + 2^1 + ... + 2^(max_retries)) + single_timeout × (max_retries + 1)
确定上游的总超时容忍度（比如 30 秒）。
减去序列化/反序列化耗时（假设 1 秒）。
减去网关和中间件的固定耗时（假设 2 秒）。
剩余可用于重试的总窗口：27 秒。
在这个窗口内反推 max_retries 和 base_delay：
如果你的 single_timeout=5、max_retries=3：

总重试等待 = 1 + 2 + 4 + 8 = 15 秒

总请求耗时（含超时）= 5 × 4 = 20 秒

总计 = 15 + 20 = 35 秒 > 27 秒的窗口 → 需要降低 max_retries 到 2




6.4 黑区场景：不建议使用 Claude Code 的默认输出

场景：

金融交易（银行转账、证券下单）

生命安全保障系统

需要严格顺序保证的操作链

原因：这些场景下，任何“可能但不保证”的行为都是一个不可接受的风险敞口。Claude Code 生成的代码是概率性正确的，它在大多数情况下是对的，但你不应该在人的生命或巨额资金上赌这个“大多数”。

替代方案：手写重试逻辑，并由至少两个高级工程师独立审查。使用经过形式化验证的库或自研的确定性组件。

七、Prompt 的极限：它能被“调教”到什么程度

在完成上述测试后，我花了额外的时间去探索一个延伸问题：如果我优化 Prompt，能让 Claude Code 自动补全这些缺失吗？

答案是：部分可以，但有上限。

以下是我测试过的最佳 Prompt 策略（在红区场景下使用）：

You are writing a production-grade integration with [支付/金融/关键] API. 
The function you write MUST include:

Idempotency key generation using UUID v4, passed via the "Idempotency-Key" header.
This key must remain IMMUTABLE across retry attempts for the same logical request.
A circuit breaker pattern: after [X] consecutive failures, stop retrying and
raise a CircuitBreakerOpen exception.
Coordinated timeout calculation: compute the total allowable retry window as
[upstream_timeout] - [serialization_overhead] - [network_latency]. Ensure that

(single_request_timeout * max_retries + sum_of_backoff_delays) ≤ total_window.

Exponential backoff with full jitter, NOT just ±% jitter.
Non-retryable errors: HTTP 400, 401, 403, 404 must be raised immediately.
Structured logging at each retry attempt (attempt_number, backoff_seconds,
status_code or exception_type).

在这个 Prompt 下，Claude Code 的输出质量从“及格骨架”提升到了“中等偏上”，它补全了幂等性和熔断器，但在超时协同的精确计算上仍然需要我手动校验。

但这里有一个我称之为 “Prompt 天花板”的现象：即便 Prompt 写得再详细，Claude Code 也无法替代你对自身业务系统的理解。它不会知道你的上游超时是多少、你的下游 P99 是多少、你的线程池大小是多少。 这些数字只能由你在代码审查时手动填入。

这也引出了我的核心观点：Claude Code 是一个强大的代码生成器，但不是一个系统设计师。 把系统设计的判断留给 Claude Code 去做，是对自己专业责任的逃避。

八、我的二创工作流：一个可复用的流程

基于四个月的实践，我这里沉淀了一个个人工作流。它和“让 AI 生成然后我检查”的最大区别在于：我把 Claude Code 定位为“骨架生成器”，把自己定位为“肌肉和神经系统的装配工”。

第一步：Claude Code 生成骨架

使用中等复杂度的 Prompt，只描述 API 类型和基本重试需求，不特意要求幂等性或熔断器。

第二步：场景判断

套用前面的四层判断框架，确定当前场景属于绿/黄/红/黑哪一档。

第三步：按层补充

• 绿区：只检查退避参数是否匹配下游特征。
• 黄区：添加结构化日志、环境变量配置、总超时门限。
• 红区：注入幂等性 Key、封装熔断器、计算超时协同。

第四步：防御性压测

在本地环境使用故障注入工具（我用的是 toxiproxy 或自建的故障模拟 API），测试三种极端：

1. 下游持续 5xx（测试熔断器）
2. 下游间歇性网络超时（测试退避和抖动）
3. 下游返回 429 + 超长 Retry-After（测试边界条件）

第五步：代码审查清单

使用我总结出的审查清单（见下文）做最终检查。

九、生产级第三方 API 重试策略审查清单

这是一个你可以直接拿去用的清单，覆盖了 Claude Code 生成代码的已知盲区和我从实际生产事故中总结出的关键点。

幂等性与安全性

• [ ] 支付/下单/扣库存类 API 是否包含 Idempotency-Key 头？
• [ ] Idempotency-Key 是否在重试之间保持不变（在循环外生成）？
• [ ] 重试逻辑是否不会改变请求体（payload immutability）？

熔断与资源保护

• [ ] 是否引入了熔断器模式（连续 N 次失败后停止重试）？
• [ ] 熔断器的 fail_max 和 timeout_duration 是否根据 API 重要性调整？
• [ ] 在高并发场景下，重试是否可能耗尽线程池？

超时与时间窗口

• [ ] 单次请求超时（read_timeout）是否小于重试等待间隔的上限？
• [ ] 总重试时间窗口是否小于上游调用方的超时阈值？
• [ ] 在微服务多层级调用中，是否考虑了重试次数的叠加效应？

HTTP 语义正确性

• [ ] HTTP 4xx（除 429 外）是否被正确识别为不可重试错误？
• [ ] HTTP 429 的处理是否读取了 Retry-After 头？
• [ ] HTTP 429 的 Retry-After 是否有合理的上限（防止无限等待）？

可观测性

• [ ] 每次重试是否记录了 attempt_count、delay、status_code 或异常类型？
• [ ] 重试耗尽的最终失败是否以结构化日志记录且触发了告警？
• [ ] 是否在重试逻辑中避免了 print() 而使用了 logger？

降级与异常处理

• [ ] 最大重试次数耗尽后，是否有明确的降级行为（而非 silence fail）？
• [ ] 异常捕获范围是否精确（避免 except Exception）？
• [ ] 原始异常信息是否在最终抛出时保留（avoid exception swallowing）？

十、总结：AI 给的骨架，你来赋血肉

回到标题的问题：Claude Code 对第三方 API 调用的错误重试策略生成是否健壮？

答案是分层级的。对于非关键、内部、低频的 API 调用，是的，它是健壮的。 指数退避、随机抖动、正确的 HTTP 状态码分支判断，这些基础能力它做得很好，超过了“随便写写”的水平。

但对于支付、下单、库存扣减、高并发核心链路，不，它不够健壮。 “不够”不是因为它的代码有 bug，而是因为它不知道它在写什么。它不知道这一次 API 调用背后的资金可能是什么量级，不知道下游 P99 是多少，不知道上游的线程池还有多少余量，不知道请求失败可能导致用户在页面上等多久。而这些，恰好是“健壮性”在脱离了教科书示例、进入真实商业系统之后最核心的要求。

下一步你应该做什么？

如果你正在使用 Claude Code 生成 API 集成代码，今天你可以做的第一件事不是重写所有代码，而是做一次快速审计。拿我上面那张审查清单，对着你项目里三个最关键的第三方 API 调用检查一遍。你大概率会发现至少一个需要立即修补的点。

修补的顺序我建议是：先处理红区场景的幂等性，再全局引入熔断器库，最后统一计算超时协同。 这三个动作的成本都不高，幂等性是一个 header 的事，熔断器是一个装饰器的事，超时协同是一个 excel 公式的事，但它们能防住的事故成本，远超你的投入。

Claude Code 是你团队里那个代码写得很快、但从不质疑需求的初级工程师。它能帮你省掉 80% 的时间，但剩下的 20%，那个决定了系统是“在晚上能睡安稳觉”还是“半夜被告警叫醒”的 20%，必须由掌握上下文的人来完成。那个人是你。