API集成指南
你的对接今天正常，十九天后崩了。你接好了一家第三方支付 API，demo 也过了，然后凌晨两点支付开始失败——因为厂商悄悄废弃了一个你从没校验过的响应字段。这就是 API 集成的现实：你交付的代码只算一半工作量，另一半是围绕重试、幂等、错误处理和变更管理做的决策。几乎每个涉及外部 API 的生产事故，根源都追得上集成第一小时做的某个选择，而不是厂商服务的 bug。本文按决策树组织，从上往下走，就能覆盖多数团队直到出问题才补的部分。想从零补起接口两侧的能力（既有消费端也有提供端），可以搭配我们的 API 集成课程 或从更底层的 Python 自动化脚本 入手，让接口从需求到运维都更扎实。
分支一：你的负载到底适配哪种集成模式
第一个决策不是选库，而是"这次集成必须容忍什么"。选模式前先回答几个问题。
- 厂商调用是同步且快的吗？如果响应稳定在约 500ms 内、你承受得住阻塞，直接"请求—响应"是最简单、最好排障的选项。
- 响应会合理花几秒吗？大文件处理、支付结算、报表生成常立刻返回一个 job ID 再异步完成。这时你需要轮询循环或 webhook 来获知任务何时结束。
- 失败后要安全重试吗？这正是决定你幂等策略的地方。重试一个非幂等操作（比如创建一笔扣款）可能造成重复扣款。若厂商支持幂等键请求头，就为每个逻辑操作发一个稳定的 UUID；若不支持，常需用你自己生成的唯一引用对账。
- 厂商会推送事件给你吗？Webhook 反转了调用方向，对可用性很好，但你要负责去重和校验投递。多数生产 webhook 会保留 last-seen 头和签名校验。
把这个决策写下来。跳过模式决策的团队，最终在异步任务上阻塞、或在快调用上轮询——两种都别扭。
分支二：设计好请求与响应契约
写代码前，先把两边的消息形态定死。三个字段占比不成比例地重要。
- 相关 ID（correlation ID）：你生成并随每个请求发送。跨系统日志和厂商支持团队要对齐时，这一个字符串能省下几个钟。
- 显式 accept 头和版本：把 API 版本钉在 URL 或请求头里（如
/v2/charges），而不是依赖厂商默默滑动默认值。 - 严格的响应校验：遇到意外结构怎么办？开发期大声失败、生产期日志加防御性编组。对新字段选"fail-loud"，容忍未知字段，但绝不静默丢弃必需字段。
如果接口两端都在你手里，就投资一个机器可读的 schema。像 GraphQL API 设计 那样用类型化 schema 和显式 introspection，能大幅减少拖垮 REST 集成的"无文档破坏性变更"这一类事故。国内团队也可借助 Python 自动化脚本 里的脚本化链路来跑契约校验。
分支三：挑传输与错误模型
不同的失败需求指向不同协议。下表对比生产集成中最常见的几类选择，价格折算为人民币参考。
| 平台 / 工具 | 核心能力 | 参考定价 |
|---|---|---|
| Postman | 按集合测试 API、环境变量、mock 服务器、回归扫描监控 | 免费档限 3 人；付费约 100 元/人/月 |
| Apifox | 国产 API 文档、调试、Mock、自动化测试一体 | 个人免费；团队版按档付费 |
| Stripe API | 幂等键、强类型 SDK、清晰错误码、webhook 签名 | 按交易计费；API 集成与测试免费 |
| 支付宝开放平台 / 微信支付 | 国内主流支付、密钥签名、异步回调机制 | 支付费率约 0.6% 以内、按行业阶梯报价 |
| FastAPI / OpenAPI | 类型化端点、自动生成 OpenAPI 文档、内部服务快速迭代 | 开源免费 |
| Zapier / 腾讯云 SCF | 管理 SaaS 连接器、函数式集成、重试与错误监控 | Zapier 免费档受限、付费约 140 元/月；SCF 按量计费 |
| Datadog 或阿里云 SLS | 跨 API 端点的时延、错误率、正确性检查与告警 | 免费试用；商用按主机/日志量计费 |
对走 HTTP 的直接 REST 调用，定好状态类怎么映射：4xx（客户端错误，多半永久，少重试）对比 5xx（服务端错误，带退避重试安全）。常见生产默认：重试 5xx 和幂等的 429 限流，使用指数退避加抖动；除非代码已知是瞬时的（如锁冲突的 409），否则不静默重试 4xx。
分支四：把重试做对，别放大负载
重试是集成从"能用"走向"有韧性、或彻底熔断"的分水岭。守好这些规则就能躲过最糟的故障雪崩。
- 指数退避加抖动：按 1 秒、2 秒、4 秒、8 秒重试，并加随机抖动，避免一群客户端同时踩踏厂商。
- 设重试次数上限：三到五次、配一个最大总窗口（比如 60 秒），胜过无限重试在队列里堆摞。
- 用幂等键：每个逻辑操作生成稳定键，让被重试的请求不能重复执行副作用。
- 持续失败开熔断：连续 N 次 5xx 就打开熔断、在冷却期内快速失败，而不是去捶打一个已经不健康的下游。
- 盯着重试率而不是最终失败：重试率上升是最早的上游恶化信号，远在用户看到错误之前。
多数团队踩的坑：重试瞬时 429 却不尊重厂商的 Retry-After 头，把温和的限流变成一场激战，反而让密钥被限流或拉黑。
分支五：把 Webhook 做可信
如果你接收推送通知，安全和去重是你的两件事。具体来说：
- 校验签名：绝不信任来自开放端点的 webhook。用厂商密钥算 HMAC 并拒绝不匹配者。支付宝、微信支付、Stripe、GitHub 等严肃厂商都会签名；在任何别的逻辑之前先把它接好。
- 按事件 ID 去重：把收到的事件 ID 或投递头存进内存或表，任何已处理过的 ID 都跳过。厂商的重试是常态，不是异常。
- 返回正确的状态：一旦确实收到事件，尽快用 2xx 确认；真正的业务用幂等键在下方异步做，别让慢处理阻塞 webhook 处理器。
- 规划回放：如果厂商允许你在沙箱回放近期事件，把它写进你的本地集成测试。
分支六：为变更与废弃做规划
厂商经常上破坏性变更，有时只给一个季度通知。可持续的集成默认"变更必然发生"。
- 解耦内部抽象：把厂商 SDK 包在你自己的接口后面，这样换供应商或升级 SDK 只碰一个边界，而不是整块代码库。
- 读变更日志与废弃通知：每周或每月排一次，审查你前三家厂商的 API 生命周期，记录任何待移除项。
- 按计划测沙箱：一直不碰的沙箱会渐渐偏离厂商行为；每月跑一遍小型冒烟套件。
- 给自己接口也做版本：如果这个 API 被其他团队消费，发布你自己的契约版本，让消费方能按你的时间线迁移而不是它们的时间线。
把变更当常态的团队，通常能在后台无声无息地完成废弃升级；而冻结契约的团队，只会在厂商拨动开关时烧一场救火演练。想把集成所在的更大架构一起夯实，可以看我们的 软件测试基础 里关于 API 契约测试与回归的部分。
收尾：最小运行手册
当有人用两句话问你"稳健的集成长什么样"，就这样答：一个带版本、幂等的契约，收在你自己的抽象后面，配抖动指数退避重试、熔断器、已校验且去重的 webhook、以及在用户感受痛苦之前就盯着重试率的监控。把决策树建一次、把假设装进运行手册，剩下的季度就能花在功能上而不是救火上。涉及并发与实时推送时，WebSocket 编程 也值得一并纳入你的传输工具库。
常见问题
第三方 API 不支持幂等键怎么办？
幂等由你这一侧来扛。为每个逻辑操作生成稳定引用、连同调用记录存好，并在任何重试前后用该引用查询，以发现是否已执行副作用。若厂商提供查询或对账端点，就用它；否则接受一个较窄的重试窗口，并在改写状态前先校验结果。
慢异步任务什么时候选 webhook 而不是轮询？
当厂商能可靠投递已签名、去重的推送通知、而你又能跑一个处理器做签名校验时，选 webhook。当你要更紧的可观测性、厂商 webhook 可靠性差、或重试稀少又便宜时，选轮询。很多团队用轮询走正常路径、再加一个对账任务去兜住漏掉的事件。
被限流返回 429 时最安全的重试策略是什么？
若厂商给 Retry-After 头就精确照做；否则从小基数（1 秒、2 秒）做指数退避加抖动。尊重厂商的节流而不是硬刚，能防止你的密钥被拉黑，也能避免上游承压时重试继续放大负载。
包一层内部抽象在厂商 SDK 外头，总是值得的吗？
生产集成通常是值得的。接口前期成本低，却能在厂商破坏 schema 或下线时，让你不用改每一处调用点。对单一、微小且稳定的集成可能过度设计；对任何别处模块有依赖的东西，这个缝在第一次废弃时就会回本。