API集成课程

大多数 API 集成课程教你"调一个接口、看是不是 200、完事"。真实的集成根本不是这样。生产环境里的集成，是把两个本来就不是为彼此而生的系统硬拼在一起，天然继承它们的一堆混乱：不一致的数据格式、动不动就超时的第三方、凭空冒出来的限流、以及两边都对不上的数据模型。这篇"课程式"指南按你真正需要、且按使用顺序，带你走一遍这些真实技能，让你集成出来的 API 能一直稳定运行，而不是只在"顺风顺水"的路径上能用。想先把 API 相关的底层概念理清，可以对照我们站内的GraphQL 接口设计和WebSocket 编程一起看。

写第一个请求之前，先读懂"契约"

任何集成最关键的第一个小时，是阅读。像律师一样去读供应商的文档：有哪些端点、哪些字段是必填哪些是可选的、认证流程是什么、有哪些限流、这个服务实际会返回哪些错误码。绝大多数失败的集成，都能追溯到某个被读错的预期——某个你以为是个字符串、结果回来一个嵌套对象的字段，或者某个文档里标成 id、却在不同端点间是两种不同格式的东西。自动发现能帮上忙。OpenAPI（Swagger）规范可以让你生成类型化的客户端，或者至少能拿它来校验你的请求是否符合真实契约。GraphQL 供应商给你 introspection 反射机制，更厉害，因为 schema 是机器可读的。想夯实读文档、把路由转化成可跑代码的基本功，我们站内这篇REST 与 GraphQL 实践是这门课的绝佳伴读。

把认证和凭据处理做到位

小心那个诱人的念头：把 token 硬编码进配置文件。它会泄漏，这也是集成出问题最常见的原因。密钥要用环境变量存，生产环境放在密钥管理服务里，access token 要在一个替你处理"401-重试"舞步的客户端里自动刷新。要搞懂 OAuth 2.0 各流程的区别：client credentials 用于服务器到服务器，authorization code 用于转售或代表某个用户操作，refresh token 用于长会话。还要把 token 行为写进你的错误处理里：当请求返回 401 时，不要盲目无限重试；刷新一次、重试一次、再不行就升级告警。一个在坏 token 上死循环的客户端会猛打认证服务器，然后把自己送上封禁名单。同样的纪律也适用于 API 密钥——按排期轮换，并给它配上集成所需的最小权限。想更系统地守住凭据和端点安全，可以看我们站内这篇软件测试基础里对异常与安全边界的处理思路。

健壮的错误处理：重试、退避、幂等性

顺风顺水的路径大概只占集成代码的一成。剩下九成是决定"出岔子时该怎么办"。要建立一套带指数退避和抖动（jitter）的重试策略——随机延迟能防止你的重试在某个供应商宕机恢复后互相撞车。当供应商下发 Retry-After 头时，务必尊重它——这是关于"要等多久"的直接指令，忽略它就是你被临时封禁的原因。幂等键是可靠写入背后那个低调的英雄。如果你用 POST 创建资源、而网络在半路断了，除非供应商支持幂等键，否则重试就会造出重复数据。很多供应商都支持（Stripe、许多支付和订单系统）。给每个逻辑操作发一个稳定的键，这样重试产出的是同一个资源，而不是第二个。这一个习惯就能消灭整整一大类困扰朴素集成的重复 bug。

在两个不同数据模型之间做映射

集成工作的核心是翻译。供应商管一个字段叫 customer_ref，你的系统管它叫 accountNumber，其中一家用 ISO 8601 字符串存日期，另一家用 Unix 时间戳。要建一个显式的映射层，而不是到处散落的转换代码，并把每一次转换都记录下来。当一个新供应商的字段缺失或格式出乎意料时，是日志让你先发现，而不是等客户来投诉。把日期、货币、地区处理当成一等公民，并按我们站内数据库设计基础里的卫生习惯来对齐。金额存到最小单位（分）和货币自己的基本单位，只在展示边界做格式化，时间戳永远带上时区，而不是想当然地假定是 UTC 或本地时间。这三类是真正会烧钱的 bug，因为它们会悄悄腐蚀记录。

测试带真实依赖的集成代码

测试集成不等于测试供应商；而是测试"你和供应商对话"的那段代码。用 mock 或本地测试服务器（WireMock，或用供应商提供的 mock）来模拟响应，并覆盖那些不愉快的路径：超时、429 限流、500、畸形载荷、字段重排。你的集成必须在供应商作妖时也能可预期地降级，因为供应商绝对会作妖。再加契约测试，锁死你要解析的响应形状。供应商加字段，你的解析器应该忽略它；它改了类型，你的测试应该立刻抓出来。把监控和告警接进集成本身：延迟、错误率、该集成自己的重试计数，而不是只看整体 API。你要在某个具体供应商刚开始拉胯的那一刻就知道，而不是等用户先感觉到。

怎么选集成平台

你可以每个集成都手写，也可以用一套平台来搞定认证、重试、监控和转换。怎么选，取决于你跑多少个集成、每个有多专门。下面是主流选项的对比。

如果你只有一两个集成，按上面那套纪律手写往往是最省钱的——既省了经常性平台费，又对安全和错误处理有完全掌控。如果你的集成有十几个起，平台自带的认证、重试、监控很快就能回本。无论哪种，都要套用同样的错误处理和幂等纪律；平台救不了"设计上就不处理失败"的方案。等你逐步走向更丰富的 API 模式，我们站内这篇GraphQL 设计指南展示了另一种查询模型会怎样改写你刚学到的集成规则。

你往前的学习路径

如果你想让 API 集成真正变强，而不是只过个测验，按这个顺序练：一，在 Postman 里手动操练一个真实 API，把你能触发的每个错误都看一遍；二，写一个小客户端对着 mock 服务器跑，让它挺过超时和 429；三，加一个映射层并记录每一个转换；四，建一个"响应形状一变就失败"的契约测试；五，带着监控去跑一个真实供应商。做完这五步，你就有了绝大多数在职开发者都从未完整练过的集成技能——因为他们都停在了顺风顺水那条路上。

集成课程常见问题

供应商返回了意外或多余的字段，我该怎么办？

让你的解析器变得宽容：忽略未知字段而不是崩溃，并把它们单独记日志以便复查。如果某个已知字段变了类型或消失，要针对那个字段大声失败，同时让载荷的其他部分继续解析。这样，单个供应商的改动才不会拖垮你整条流水线。

存供应商凭据最安全的方式是什么？

永远不要把 token 放进源码或提交到 git 的配置文件里。开发环境用环境变量，生产环境用密钥管理服务，按排期轮换凭据，并把每个 API 密钥都限到集成所需的最小权限。一个泄漏的、权限过大的 token，是最常见的集成安全事故。

为什么我的重试有时会让一次宕机变得更糟，而不是修复它？

朴素的重试会在同一时刻全部爆发，给正在恢复的服务雪上加霜。给你的指数退避加入随机抖动，让重试分散开，尊重 Retry-After 头，并在升级告警之前封顶重试总次数。重试风暴，往往才是被归咎于"供应商宕机"的真凶。

我该手写集成，还是用集成平台？

取决于数量和专门程度。一两个集成手写通常更便宜，因为你省掉了经常性平台费。十几个起，用一台能处理认证、重试、监控、转换的平台就划算多了。无论哪种，都要套同一套错误处理纪律，因为平台救不了一个无视失败的设计。

什么是幂等键，我为什么要用？

幂等键是一个稳定的、客户端生成的、在变更型请求上发送的值。这样，如果网络在半路断了、你重试时，供应商能认出这是同一个操作，就不会造出重复数据。每个逻辑操作发送同一个键。它消灭了整整一类本会困扰 POST 端点重试的重复 bug。