API 技术栈指南

REST API 已成为 Web 上应用程序之间通信的标准。基于简单而强大的原则，REST API 为编程接口的设计、开发和使用提供了一种标准化且灵活的方法。通过采用客户端-服务器架构并适当使用 HTTP 方法，REST API 实现了分布式系统的平滑且高效的集成。

作为一种标准，API 生态系统近年来变得更加丰富，并逐步融入 DevOps 生态系统。它注入了敏捷性、CI/CD 和 FinOps，并继续自我发展。本文将汇总这些新的实践和工具，以帮助您了解“API 方法”可以实现的功能。

API 设计和文档

API 设计和文档阶段至关重要，因为它为后续开发奠定了基础。通过使用领域驱动设计（DDD）、事件风暴和 API 目标画布（表示什么、谁、如何、输入、输出和目标）等方法，可以理解业务需求并确定 API 的相关领域和目标。这些研讨会使业务和开发团队能够共同工作，定义 API 的目标和不同业务领域之间的交互。

在设计和记录 API 时，必须遵循 REST API 的基本原则。这包括识别资源并使用有意义的 URL 表示它们，适当地使用 HTTP 方法进行 CRUD（创建、读取、更新、删除）操作，以及以无状态的方式管理资源状态。通过采用面向资源的方法，开发团队可以为客户端开发人员设计直观且易于使用的 REST API。REST API 文档应突出显示可用的端点、支持的方法、接受和返回的数据格式，以及任何安全性或分页约束。

API 风格书籍在这一阶段发挥着关键作用。它们提供了设计指南和标准，以确保开发的 API 一致性和质量。这些样式书定义了 URI 结构、要使用的 HTTP 方法、数据格式、错误处理等规则，并可作为组织内 API 项目的通用参考。常用工具包括信号灯和 SwaggerHub，简单的 Wiki 工具也足够。

数据模型库通过提供可重用的数据模型，定义 API 中使用的标准数据结构，来完成这一阶段。数据模型库包括 JSON 模式、数据库定义、对象模型等，提供现成的资产，减少错误，加速开发。常用工具有 Apicurio 和 Signal Lights。

API 门户上的 API 经常缺少工作流 API 的描述，这带来了如下问题：

如何链接 API 调用？
如何描述这些调用的顺序？用图示还是文本？
如何确保最了解 API 的人能够读懂并定期更新？

理解 API 调用的顺序往往比较困难，但通常通过 API 门户上的附加文档进行补充。然而，这些文档与开发人员提供的代码分离。OpenAPI 规范允许定义链接和回调，但这在解释过程中有限制。因此，最近出现了 OpenAPI 工作流规范，用于定义 API 工作流，这些步骤用 JSON 描述，允许生成模式来解释调用顺序。

如果希望从 OpenAPI 规范描述工作流，可以使用 Swagger Editor 或 SwaggerHub。也可以使用 Swagger to UML 或 OpenAPI to PlantUML。例如，可以使用 PlantUml 或 LucidChart 从设计序列图开始。工具链的选择取决于是否偏好自顶向下还是自底向上的方法。像 Stolight Studio 和 Redocly 这样的工具，通常用于处理这些主题，Apicurio 也是如此。它们可以用于 API 设计，使团队能够使用用户友好的界面轻松创建和可视化 OpenAPI 规范，并自动生成交互式文档，确保文档始终是最新的，并且与 API 规范保持一致。

API 开发

一旦定义了 API 规范，下一步就是根据设计阶段制定的指导方针和模型来开发 API。敏捷软件开发方法、有效的协作以及版本管理是确保高效开发的关键实践。

对于版本控制，团队使用 Git 或 GitHub 等版本控制系统来管理 API 源代码。版本控制支持开发人员之间的无缝协作，并确保 API 随时间变化的完全可跟踪性。

在开发过程中，可以使用检查工具来确保 API 规范的质量。这些工具可以检查以下内容：

代码的语法和结构
遵守编码标准和命名约定
正确使用库和框架
是否存在死代码或冗余代码
潜在的安全问题

Swagger-Lint 和 Apicurio Studio 或 Stoltlight 可以用来执行这些检查，确保 API 规范的质量。这些检查也可以集成到 CI/CD 工具链中，以实现自动化和持续集成。

自动化在开发阶段非常关键，可以通过工具如 Postman 和 Newman 进行单元、安全性和负载测试，以确保 API 的质量和安全性。其他解决方案包括 REST Assured、Karate 和 K6。

支持 API REST 开发的框架非常常见，最流行的包括 Express.js（与 Node.js）、Spring Boot 和 Meteor。选择合适的框架不仅要考虑其 API 能力，还需要符合开发团队的需求和技术挑战。

模拟原型也很重要，它可以减少开发人员之间的相互依赖。Mock API 通常基于 API 的 OpenAPI 描述进行创建，API 管理门户通常会支持这一点。开源项目如 MockServer 和 WireMock 也是常用的模拟工具。

API 的安全

API安全性是开发和管理过程中的关键问题，涉及以下主要协议：

API密钥：由于其易用性和低开销，API密钥仍广泛用于API访问。它们以一对唯一字符的形式存在，应像密码一样安全地存储。
OAuth 2.0：一种基于令牌的身份验证方法，涉及三个参与者：用户、集成应用程序（通常是API网关）和目标应用程序。用户通过OAuth端点交换令牌，授予应用程序对服务提供者的访问权限。OAuth 2.0因其粒度访问控制和基于时间的限制而受到青睐。
OpenID Connect：这是OAuth 2.0的扩展，增加了标准化的第三方标识和用户身份，适用于细粒度授权控制和管理多个身份提供者，尽管并非所有API提供者都需要它。

除了使用API密钥、OAuth 2.0 和 OpenID Connect，您还可以部署集中管理工具如 Keycloak 来管理身份和API访问。其替代品包括 OAuth2 Proxy、Gluu Server、WSO2 Identity Server 和 Apache Syncope。

不过，仅仅依赖这些工具和协议并不足以完全保障API安全。实现 OWASP 规则的前端 Web 应用程序防火墙 (WAF) 可以防止许多常见安全问题。为了更深入的安全管理，可以参考像 DZone Refcard 这样的资源，或采用 DevSecOps 方法来降低风险。

此外，自动化安全测试也是必不可少的，工具如 ZAP 可以进行自动化的安全测试，帮助识别和修复API中的潜在漏洞，确保API的稳健性。

API 生命周期管理

一旦开发了API，就需要在整个生命周期中有效地部署和管理它们。这包括版本管理、部署管理、性能监控，以及确保API的可用性和可靠性。API管理平台如Gravitee、Tyk、WSO2 API Manager、Google Cloud Apigee和Amazon API Gateway等，可以帮助进行API的部署、版本管理和监控。这些平台提供了一些高级特性，如缓存、速率限制、API安全性和配额管理。这些功能对于扩展规模非常重要。

为了确保符合设计阶段建立的标准和指导方针，使用诸如stolight的spectrum之类的工具对OpenAPI规范进行检查分析，识别潜在问题并确保API与设计标准的一致性。

当然，在链的最后，你需要记录你的API。现有的工具可以自动执行许多任务，例如Redocly，它可以根据OpenAPI规范生成交互式文档。额外的好处是，您可以确保您的文档始终是最新的，并且对于每个人（开发人员和业务分析人员）都始终是简单可读的。

API管理还包括持续监控API的性能、可用性和安全性，以及及时实施补丁和更新，以确保其顺利运行。

API 性能监控与优化

API的分析和监控对于确保其性能、可靠性和可用性至关重要。实时监控API性能、收集使用数据并及早发现潜在问题是关键。ELK Stack（Elasticsearch、Logstash、Kibana）常用于收集、存储和分析API访问日志，以监控性能和检测错误。OpenTelemetry也是监控端到端流程的好工具，特别是在包含API的复杂流程中。

在API性能指标方面，Prometheus和Grafana是常用的实时监控工具，能够提供关于使用趋势、瓶颈和性能问题的有价值信息。

总结

显然，您不需要一开始就准备好所有这些工具和实践来开始您的API开发之旅。您应该首先考虑您希望如何开展工作以及您的优先事项是什么。可能需要优先考虑设计工具，如检测工具，或定义您的API风格书和API设计工具。优先选择常用的工具，避免重新发明轮子，是一个明智的策略。实际上，我建议您从建立工具链的基础开始，因为这样在后续阶段的调整会更加容易。

希望这些要点能帮助您在确定API需求的优先级时，能够从容地开始您的工作。

原文链接：Get Some Rest! A Full API Stack