API调用和函数调用的区别

写代码时经常混着说「调个函数」和「调个接口」，真到上手才发现两件事完全不是一个量级：一个在自己进程里，几微秒就返回；一个要过网络、过鉴权、过限流，随时可能超时或失败。这篇不绕概念，直接给判断边界、开销对照和排查顺序，看完你能决定某段逻辑该放本地还是走远程。

写代码时经常混着说「调个函数」和「调个接口」，真上手才发现两件事完全不是一个量级。一个在自己进程里，几微秒就返回，出错抛异常就行；一个要过网络、过鉴权、过限流，随时可能超时或者返回一个你没见过的错误码。

这篇不绕概念，直接给判断边界、开销对照和排查顺序。看完你能决定某段逻辑该放本地还是走远程，以及走远程时要补哪些兜底动作。

先分清边界：谁在执行、错在哪一层

函数调用的执行方是当前进程，参数要么传值要么传引用，都在同一块内存里，出错就是抛异常或者返回错误码。API 调用的执行方在另一台机器上，中间隔着 DNS、TCP、TLS、网关、鉴权、限流、上游服务，任何一环出问题都会变成你这边的一个失败结果。

函数调用

同进程内执行，输入输出只依赖本机内存，失败通常是代码逻辑问题

API 调用

跨进程跨网络执行，失败可能来自链路任意一层，你只能看到最终状态

一个简单的判断口诀：这段逻辑的输入输出是否只依赖本机内存？是就写成函数，否就走接口。如果是混合场景，比如本地预处理完再发远程请求，就把它拆成两段，标清楚哪段是本地计算、哪段是远程等待，后面给超时和重试定策略时才好下手。

开销对照：延迟、钱和失败率三本账分开算

很多人把「慢」和「贵」混在一起谈，其实要拆成三本账：延迟账、成本账、失败率账。延迟上至少要分开看连接耗时、首字节耗时和整体耗时，具体基线别靠感觉，先到 /tools/speed-test 量一遍再谈优化。

成本这块最容易想当然。函数调用基本只消耗 CPU，API 调用要看是按调用次数还是按用量计费，单价口径和模型差异去 /official-api 看当时的数字，自己估算用量可以去 /tools/token-price-calculator 算一遍。别拿旧印象下结论，价格是会调整的。

超时、重试和幂等：远程调用必须补的三件事

只要走了网络，就必须假设它会失败。三件事按顺序补：超时、重试、幂等。超时至少要分连接超时和读取超时两档，再在业务层兜一个整体上限，别用一个数字糊过去，否则你分不清是连不上还是对方处理太慢。

1. 设超时连接超时和读取超时分开设，业务层再加一个总时限。验证方式：本地用工具模拟慢响应，确认超时能被触发而不是一直挂着。
2. 定重试条件只对可重试的错误重试，比如连接失败、服务端临时错误；参数错误、鉴权失败这类重试多少次都没用。重试要加退避和抖动，别固定间隔猛打。
3. 想幂等有副作用的接口先设计幂等键，否则一次下单可能因为重试变成两次。验证方式：用同一个幂等键重复请求，确认结果只生效一次。

还有一种情况不适用：如果你的调用本身是幂等的读操作，且上游有强缓存，那重试的收益会更高，但仍要控制总次数和总耗时，不然会把故障放大。

降级和日志：怎么让失败可复盘

失败不可怕，怕的是失败之后没人知道发生了什么。降级路径要提前准备：换备用源、换更小的模型、返回缓存结果，或者干脆告诉用户稍后再试。具体切换策略可以参考 /guides/multi-model-routing-fallback 里的做法，别等出事才临时想。

• 日志至少记请求 id、耗时、状态码、重试次数和用量，缺了哪项事后都复盘不了
• 降级触发要有明确条件，比如连续失败达到阈值，别靠人工盯
• 上线前按「超时没触发、重试没超预算、降级真能用」三条各跑一遍，别只测成功路径
• 把失败样本存下来，下次调超时和重试参数时有依据

最后提醒一句：如果某段逻辑既能写成函数也能走接口，先问三个问题——它是不是只依赖本机数据、失败会不会影响用户、调用量级有多大。三个都指向本地，就别为了「统一架构」硬套远程调用。