此列表并非详尽无遗，但涵盖了最常见的做法。这些建议不应阻止您尝试不同的流程。
译自 The 5 Worst Anti-Patterns in API Management，作者 Emile Vauge。
想象一下：你在一家名为 DonutGPT 的公司担任 平台工程 负责人，你每年通过 AI 生成的食谱在线销售数百万个甜甜圈。你需要通过安全的 API 向数百家经销商提供你的关键服务。由于地球上没有人希望看到他们的甜甜圈订单失败，你的管理层正在施加压力，要求你确保提供高可用性服务。
你目前的生产环境主要由 虚拟机 组成，但你正在逐步迁移到 云原生平台。你处理的大多数生产服务都暴露了 API，但你的团队对它们几乎没有控制权和可见性。每个服务都由不同的开发团队拥有，在语言、部署工件、监控、可观察性、访问控制、加密等方面没有一致性。
一些服务是基于 Java 的，使用旧的 TLS 1.1 证书进行“安全保护”，并位于 JWT 访问控制策略之后。其他服务是基于 Python 的，使用 TLS 1.3 证书，并位于自定义的访问控制策略之后。这种多样性可以扩展到生产环境中的其他服务。
你（合理地）认为这种情况远非理想，你计划在 API 管理解决方案的帮助下，对 DonutGPT 的 API 进行合理化。你的要求包括：
- 你的 API 应该通过集中式和一致的安全策略进行严格治理
- 你需要高级流量管理，例如速率限制或金丝雀发布
- 你需要所有公共端点的实时可观察性和使用指标
简而言之，你想要可预测的操作、安心和更好的睡眠。
看起来你的计划是正确的，你正在走向更美好的日子（或夜晚）。然而，API 之旅 很长，前方的道路充满了障碍。以下是你开始 API 历程时应该避免的五大最差反模式。
你即将投入时间、金钱和精力来设置 API 管理解决方案。在这个过程中，你将集中管理暴露服务的许多方面，例如流量管理、连接安全性以及可观察性。很容易想到，“一切越集中，我的控制权就越大，我的睡眠就越好。”为什么不使用这个 API 管理解决方案来拦截每个 API 调用，并将 HTTP 主体转换为从敏感数据（如私人信息）中进行清理？
这将确保每个 API 调用在整个系统中都是干净的。这是真的，但只是在短期内。
让我们快进三年。你的 API 管理平台现在已经成熟，管理着数十个不同团队的数百个 API。最初在 API 管理工作流程中清理 HTTP 主体的快速胜利逐渐变成了一个白象：
- 第一个快速补丁不可避免地演变成更复杂的要求，需要适应每个 API。你那十行优雅的代码迅速发展成一个无法维护的 5000 行脚本。
- 现在没有人愿意拥有这个自定义脚本，因为它操作着许多团队的 API
- 每个新版本的 API 可能都需要更新和测试这段代码，这段代码位于 API 平台中，与服务的代码库分离。
- 测试这个自定义脚本需要大量工作。如果你有任何问题，你首先会从实时流量中了解到，并且你将很难调试它。
- 你的 API 解决方案非常资源密集。你应该避免将整个 HTTP 主体委托给你的反向代理。这会消耗分配给平台的大部分 CPU，给你很少的安全裕量，同时使其成为一种非常昂贵的方法。
简而言之，最好避免短期决策。当时看起来是个好主意，几年后可能就站不住脚了。API 管理旨在发现、保护、组织和监控你的 API。它不应该被用作执行应用程序代码的捷径。
→ 在设计你的下一个生产平台时，关注点分离至关重要。
另一个有趣的反模式是过度关注长期的、可能是理想化的结果，而没有认识到或理解实现这些结果的步骤。你的 API 转型项目非常昂贵，你希望确保一切顺利运行。因此，你选择功能最丰富的 API 管理解决方案来满足所有可能的未来需求，尽管你今天无法利用其大部分功能。
当然，这更贵，但如果它能防止您在三年内进行潜在的迁移，那它就是一个安全的赌注。这可能看起来没有风险，但您只看到了 API 项目冰山一角。
快进三年，使用这种顶级且昂贵的解决方案：
- 从传统平台过渡的时间比预期长得多。
- 此新解决方案需要供应商为您的团队和公司中的许多开发人员提供付费培训课程。
- 您仍然没有使用该解决方案的许多功能。
- 许多开发团队由于其复杂性而避免采用此新平台。
- 您最初控制公司内所有 API 调用的目标尚未实现。
- 您仍然睡眠不足。
此时，您承认最完整（也是最复杂）的解决方案可能不是最佳选择，因此您咬紧牙关，决定迁移到更简单的解决方案，以满足您现有的需求。在您试图避免在项目开始三年后进行 API 管理迁移的过程中，您最终还是导致了迁移，只是比最初预期的要早。
这里的重点是，虽然您应该以长远目标为目标（并选择与之相符的解决方案），但要解决您今天的需求，并战略性地朝着该目标迈进。这包括规划团队的逐步培训和采用。如果产品无法为您提供渐进式学习曲线和部署旅程，那么您将无法坚持您的计划。
以下是一个使用相同产品的渐进式旅程示例：
- 从 Kubernetes 上的基本入口资源开始。
- 然后，将引入一个 API 网关，它将带来 API 流量管理和安全性。
- 然后，在您对对您的业务很重要的功能有了更好的了解之后，过渡到 API 管理平台。
简而言之，不要因为所有花里胡哨的功能而选择产品。如果从未使用过，再多的酷炫功能也无法解决您的挑战。根据使用它来满足您今天需求的体验以及它是否为将来更高级的使用案例提供渐进式过渡来评估它们。
→ 在过渡到 API 管理平台时，不要领先。
作为现代平台工程主管，您坚信基础设施即代码 (IaC)。在声明性配置文件中管理和配置您的资源是一种现代且出色的设计模式，可以降低成本和风险。自然地，您将在设计基础设施时将其作为坚实的基础。
在您的 API 旅程中，您会忍不住走一些捷径，因为从短期来看，直接在 API 管理 UI 中配置组件可能比设置干净的 IaC 流程更快。或者，一开始，手动更改生产运行时配置可能更容易，而不是从 Git 提交工作流部署更新的配置。当然，您总是可以稍后修复它，但内心深处，这些笨拙的代码永远存在。
或者更糟的是，您的 API 管理产品需要提供一致的 IaC 用户体验。某些组件需要在 UI 中配置。某些部分使用 YAML，其他部分使用 XML，您甚至拥有专有的配置格式。这些不同的方法使得不可能拥有一个一致的流程。
你说，“基础设施即代码很棒，但例外是可以的。几乎基础设施即代码就足够好了。”
快进三年：
- 60% 的基础设施完全在配置文件中声明，并位于 git 存储库中。
- 这些配置文件是用五种格式编写的：YAML、INI、XML、JSON 和自定义格式。
- 剩下的 40% 需要在某些仪表板或文件中进行手动操作。
- 配置格式或流程的多样性使得您的团队无法控制平台，并且不断需要其他了解每种格式或流程的团队来救援。
- 人为错误率很高，导致您的发布流程延长且不可靠。对基础设施的任何更改都需要几天时间才能部署到生产环境中，这是最佳情况。
- 在最坏的情况下，更改部署到生产环境中，导致重大中断。由于您的团队无法快速解决问题，恢复时间以小时为单位。您的老板焦急地盯着您肩膀上的屏幕，等待奇迹般的修复部署。在此过程中，数千份甜甜圈订单被错过。
- 您今晚甚至不想睡觉。
结论很明显——部分地将 API 管理设置为代码会违背降低成本和风险的目的。只有当您的 API 管理解决方案 100% 作为代码 时，您才能从可靠的平台、极快的上市时间和快速恢复中受益。 对流程的例外情况总是会降低平台的整体效率和可靠性。
→ 切勿满足于半成品流程。
在开始 API 之旅时，很难计划和预测每个用例。变化是不可避免的，但如何管理变化却不是。正如我们将在本节中看到的那样，糟糕的变更管理的影响会随着时间的推移而累积。
让我们回到最初：您正在推出全新的 API 平台，并且已经将数百个 API 迁移到生产环境中。您对结果非常满意；您感觉一切都在掌控之中，并且睡得更香了。
一年后，您最先进的监控警报淹没了您的通知，指出了来自您最大客户之一的大量 API 调用，并出现了 404 错误。404 错误很普遍，因此您对此并不太在意，并迅速将问题转交给负责该 API 的开发团队。
在接下来的几个月里，您看到 404 错误和 500 错误的数量显着增加，影响了数十个不同的 API。您开始对此问题感到担忧，并召集团队进行故障排除并找到根本原因。
您的分析发现了一个更严重的问题：您的 API 需要一个一致的版本控制系统。您设计平台时，就好像您的 API 合同永远不会改变，就好像您的 API 会永远存在一样。
因此，为了处理变更管理并发布 API 的新版本，每个团队都遵循了以下流程：
- 一些团队没有费心处理兼容性检查，而是继续推动破坏性更改。
- 一些团队试图不惜一切代价保持 API 向后兼容。这不仅使代码库难以维护，而且逐渐变得明显的是，它阻止了团队进行创新，因为他们希望避免破坏性更改并保持与所有版本的兼容性。
- 一些团队遵循了更强大的流程，使用 URL 版本控制，例如
https://donutgpt.com/v1/donuts和https://donutgpt.com/v2/donuts。他们能够同时维护多个版本，每个版本都有不同的代码库。问题是其他团队正在使用不同的策略，例如查询参数版本控制（https://donutgpt.com/donuts?version=v1）甚至标头版本控制。 - 一些团队始终遵循特定的版本控制策略，例如 URL 版本控制，但没有提供版本化文档。
这项研究让您意识到人类大脑的创造力——开发人员选择了如此多的不同选项！
结果是客户：
- 使用过时的文档
- 调用过时或已失效的 API
- 使用不同的版本控制策略调用不同的 API
- 调用不可靠的 API
- 在订购经典的“Legend GPT Donut”时，收到带有您新的“实验配方”的甜甜圈
关键的要点很明显：没有代码能永远存在，变化是 API 开发的自然组成部分。鉴于这一事实，您必须为您的发布流程和 API 生命周期管理建立一个强大、可靠且可重复的基础。
您选择的 API 管理解决方案也可以提供帮助。选择一个提供灵活的版本控制策略的解决方案，该策略适合您的需求，并且可以在 DonutGPT 的每个 API 上强制执行。
此外，确保团队维护其 API 的多个版本，这些版本可以作为更广泛的变更管理最佳实践的一部分轻松访问。这是保持客户一致且可靠的用户体验的唯一方法。
→ 对所有 API 强制执行统一的版本控制策略。
既然您已经了解了管理 API 版本控制策略的重要性，那么让我们来讨论 API 的依赖项管理——这是一个经常被严重低估的主题，原因很简单。它非常高级。
在经历了糟糕的无版本控制策略事件后，您很欣慰地看到版本控制策略在 DonutGPT 的每一部分代码中都得到了强制执行。您甚至开始睡得更香了，但如果您读到这里，您就知道这不可能持续下去。
两个月后，您最先进的监控再次提醒您，来自您最大客户之一的几个 API 调用导致了 404 错误！您一定是在开玩笑吧！您知道故事的其余部分：特遣部队、故障排除、TooManyDonutsErrors、根本原因分析，以及（敲鼓）……
您所有的 API 确实都遵循了强制执行的版本控制策略：https://donutgpt.com/v1/donuts。那么，发生了什么事？
这仅在 API 管理平台上发布的路由上强制执行。API 背后的服务遵循不同的版本控制策略。即使对于这少数几个，您的 API 路由和后端服务之间也没有依赖项管理。
换句话说，https://donutgpt.com/v1/donuts 和 https://donutgpt.com/v2/donuts 能够调用同一版本的服务，这导致了类似于无版本策略事件的情况，造成了糟糕的客户体验。如果一些服务调用其他服务，情况会变得更加复杂。
你开始明白我的意思了：你需要在所有 API 和服务上强制执行依赖策略。每个 API 都需要进行版本控制并调用特定服务版本（或范围），这种方法也应该应用于每个服务。为了实现这一点，你的 API 管理解决方案必须提供一种灵活的方式来在 API 定义中表达依赖关系。此外，它应该通过智能 linter 在部署阶段检查依赖关系，以避免发布有问题的 API 依赖链。
这些功能在 API 管理产品中并不常见，因此你必须明智地选择。
→ 在部署时强制执行依赖关系检查。
你将大部分职业生涯都投入到构建 DonutGPT 的基础设施中，在这个过程中解决了许多挑战。结果非常令人满意：DonutGPT 利用其最先进的 AI 技术颠覆了甜甜圈市场，创造出令人惊叹的甜甜圈食谱。
你为成为这个成功故事的一部分而感到自豪；然而，随着公司的加速发展，现在面临着更加复杂的问题。迄今为止，最大的问题是 DonutGPT API 的工业化，这些 API 被客户和经销商使用。在这段旅程中，你尝试了多种解决方案，重新开始，并做出了一些很棒的决定……也有一些值得商榷的决定。DonutGPT 在探索 API 世界的过程中搞砸了一些甜甜圈订单。
现在，当你能够退后一步，看到整个项目时，你意识到你已经遇到了你今天认为的反模式。当然，你在这个过程中学到了很多东西，你开始认为将这些知识回馈给社区是一个好主意，例如通过一篇详细的博客文章。
当然，这个故事、人物和公司都是虚构的，即使是 AI 生成的甜甜圈食谱也可能是下一个大事件。然而，这些反模式是真实存在的，在我们与 Traefik Labs 的客户、潜在客户和社区成员的多次对话中反复观察到。
在规划你的 API 旅程时，你应该考虑以下五个原则，以最大限度地提高回报并最小化工作量：
- 用强烈的关注点分离来设计你的 API 平台。避免将业务逻辑委托给平台。
- 不要把目标定得太高或太快。一步一步来。从更简单的概念开始，例如入口，然后在更好地理解它们之后，逐步转向更高级的 API 使用案例。
- 在工业化你的流程时，容忍例外将违背目的，你将无法获得完全自动化平台的所有预期好处。
- 从长远来看，版本控制成为一个关键挑战。从你的 API 旅程开始，在所有 API 中采用强大且一致的版本控制策略，将使你的平台更具可扩展性、可靠性和可预测性。
- 在具有许多活动部件的复杂基础设施中，控制和认证所有组件的运行时依赖关系对于实现平台的高信任度和稳定性至关重要。
当然，这个列表并不详尽，但它涵盖了最常见的做法。尽管如此，这些建议不应该阻止你偏离轨道并尝试不同的流程。创新建立在其他人反馈的基础之上，但仍然需要创造力。