API 调用

它是什么

API 调用是应用按一份接口约定向外部服务发一个请求、再处理返回的动作：请求要带什么字段、用什么方式鉴权、成功与失败分别返回什么形状，都由对方的接口文档规定。[S1]

它的定位很具体：它是「连接」这一层的最小单位。模型能判断、能生成，但要读到你公司的库存、写一条记录、发一封邮件，都得有人真正把那个请求发出去。发请求的是应用，不是模型——模型最多是提出「我想调用这个接口，参数是这些」。

为什么需要它

因为绝大部分 AI 应用的价值不在「说得好」，而在「接得上」。接不上的 AI 只能聊天；接得上的才能查真实数据、触发真实动作。

而对产品经理来说，需要理解 API 调用的真正原因不是「知道它是什么」，而是知道它哪里会坏。一次调用会经历：网络传输、对方鉴权、对方业务处理、返回解析——每一段都可能失败，且失败方式不同。把调用简化成「成功/失败」两种结果，等于把四类问题压成一个，之后就无法定位。

还有一笔常被忽略的成本：调用是要花钱和花时间的。同一个功能用一次调用还是五次调用，直接影响延迟与单价。这也是后面 模型服务 与成本优化的起点。

它如何工作

一次健康的调用至少要处理六件事：

• 鉴权：密钥放在哪里、怎么轮换、泄露了怎么办。密钥硬编码在前端脚本里是最常见的事故来源。
• 超时：不设置超时，一次对方卡住就能拖垮你的整个请求。超时时间要按「这个动作慢到什么程度算异常」来定，不是抄一个默认值。
• 重试：只重试幂等的操作。查一次和转账一次，重试的安全性完全不同——对写操作重试之前，必须先确认对方接口是否幂等。
• 失败分类：把「对方明确拒绝」（4xx，重试无用）和「暂时不可用」（超时、5xx，可重试）分开。混成一个失败计数，等于把需要人工处理的错误埋进日志。
• 返回校验：对方返回 200 不代表你要的字段在里面。空结果、字段改名、类型变化都要当作正常情况处理。
• 可观测：每次调用留下耗时、状态、请求标识。没有这一层，线上出问题时只能靠猜。

必须澄清的误会

API 调用 ≠ 函数调用。 函数调用描述的是模型侧的一个动作：模型按约定格式提出「要调用哪个函数、参数是什么」。API 调用描述的是应用侧的动作：真的发出网络请求、处理响应、处理失败。两者之间隔着一整层鉴权、超时、重试和错误处理——把两者当成一件事，会在「模型说要调」和「系统真的调了还能善后」之间留下一个没人负责的缺口。

API 调用 ≠ 模型 API。 模型 API 是众多接口里的一类，特指向模型要推理结果；API 调用是通用动作，调用对象可以是库存系统、支付网关、内部工单。这个区分之所以重要，是因为两者的失败后果完全不同：模型 API 失败可以降级到备用模型或直接返回错误；支付网关的重复调用可能意味着重复扣款。

调用成功不等于业务成功。 返回 200 只说明这次请求被受理。这一步该不该做、参数对不对、产生的副作用可否接受，都是应用侧要判断的事。把「接口通了」当作「事情办成了」，是集成类故障里最普遍的一种。

还有一个容易忽略的：调用是有副作用的。 读接口可以随便重试，写接口不能。设计时要先问「这个动作重复执行一次，会发生什么」——如果答案是「会多转一笔钱」，那它就需要幂等键或人工确认，而不是靠重试策略解决。

真实例子

一个「查订单状态并回复客户」的流程里，调用设计可以是这样：超时 3 秒；只对 5xx 与超时重试，最多 2 次，采用递增间隔；每次调用带一个请求标识，便于对方排查；解析响应时显式判断「订单号不存在」这种业务失败（对方返回 200 但结果为空）；连续失败时不再重试，改为回复「正在人工核查」并创建工单。[S1][S2]

这里最值得抄走的不是那 3 秒，而是**「返回 200 但结果为空」被当成一种正常分支处理了**。多数线上事故不是因为接口挂了，而是因为接口没挂、只是答了个空，而下游把它当成了一条正常数据。

什么时候适合与不适合

适合：需要读写外部系统的真实数据；对方提供了稳定的接口与文档；失败可以由你的系统兜住（重试、降级、转人工）。这类场景里，API 调用是最直接的连接方式。

不适合：没有稳定接口、只能靠人工操作系统（此时正确答案是流程 + 人，而不是强行自动化）；或者对方的接口本身没有幂等保证、却要执行不可撤回的写操作——这种要先解决幂等与确认，再考虑自动化。

静默降级与重试放大是两类不同的故障，成因差得远。 一种是静默降级：调用失败后返回了一个空结果或默认值，流程照旧走完，用户拿到的是错的答案而不是一个错误提示。另一种是重试放大：一个已经过载的下游，因为上游重试而收到成倍的请求——重试必须带退避与上限，否则重试本身就是故障源。

亲自试一下

拿一个你真在调用（或准备调用）的接口，用约 30 分钟补齐三项内容：

1. 超时：写下你的超时值，并回答「为什么是这个数」。
2. 失败处理：把失败分成「可重试」与「必须停下」两类，各自写一句处理动作；对写操作额外回答「重复执行一次会发生什么」。
3. 空结果兜底：写下「对方返回成功但没有数据」时，系统应该给出什么，而不是让它当成一条正常数据继续走。

观察点是第三项：如果你发现自己从来没为「成功但为空」写过分支，那么你现在的系统里大概率已经存在一条静默错误路径。

接下来学什么

API 调用是这一站（给接口）里最基础的执行单位。把它往上推一层，就是这一站真正要解决的问题：为什么每个工具都要各接一遍？ 答案在 模型上下文协议——它把「模型 × 工具」的对接矩阵收敛成一次实现。与之配套的还有 模型 API、模型服务 与 限流。

在上一站（给手脚）里，API 调用是 工具调用 连接现实系统的常见方式；两者的分工是「谁决定要调」与「谁真的调」。如果你关心的是「调用失败之后怎么让人接手」，那是 给安全 的 人工升级处理。

来源与修订

把工具调用作为 Agent 与外部世界交互的关键组件、并强调失败处理与权限的边界，来自 Anthropic 的 Building Effective Agents；对不可撤回动作需要额外约束的判断，参考 Trustworthy Agents in Practice。[S1][S2]

需要说明一处边界：「超时、幂等、失败分类、返回校验、可观测」这一组要求，以及「成功但为空」必须显式处理这条，是本站在落地时总结的操作性要求，不是上述来源的原文。来源讨论的是架构与原则，不展开接口层的实现细节。

2026-09-21 按决策页规范重写，本次修订补入幂等与「成功但返回为空」的处理要求——这两类恰好是集成故障里最安静、也最常发生的位置。