什么是 API 生命周期？

API 是一套规则或协议，使软件应用程序能够相互通信，以交换数据、特性和功能。 API 包含生产者生命周期和消费者生命周期。前者侧重于 API 的创建与分发，后者聚焦于 API 的使用。

API 生产者生命周期并无通用统一模式。不同来源可能有不同划分，但生命周期通常包含以下阶段： 规划、设计、开发、测试、部署、监控和退役。

API 管理平台常用于协助组织 API 生命周期各阶段的工作。它还能在 IT 环境中集中管理 API 策略、治理、文档和目录。许多平台包含高级分析功能以及 API 发现和变现工具，帮助组织最大化 API 价值。

对 API 全生命周期的考量与理解，有助于开发团队更有效地分配资源、制定切实可行的交付时间表、在整个过程中让所有利益相关方保持信息同步，并确保 API 满足业务需求。本质上，经过深思熟虑并有效执行的生命周期，有助于交付高性能、安全的 API 和更优的用户体验。

端到端的 API 生命周期管理包含几个关键阶段，从初步规划开始，通常（但并非总是）以退役或替换结束。以一家软件公司为例，假设其决定构建一个 API，用于将其客户数据与工单系统、会计系统、项目管理平台等业务工具同步。

构建 API 始于回答一些基本问题：为何需要这个 API？为谁而建？它将如何被使用？如何衡量成功？ 

明确 API 项目的目标，有助于厘清 API 设计所需具备的特性和功能。在上述软件开发示例中，该 API 的目标是确保客户数据能够在公司现有或计划使用的应用与平台之间无缝流转。 

在此规划阶段，组织需：

• 评估 API 的潜在业务效益
• 阐述此 API 将如何满足业务需求
• 确认在原生集成市场中，没有现存的 API 或其他可用产品能实现所需功能（即确认构建此 API 的必要性）
• 清晰界定哪些应用和平台将依赖此 API，以及 API 将如何与现有工作流集成。

接下来，团队应讨论潜在用户和使用场景。这是仅供内部使用吗？哪些团队将使用此 API？用于什么目的？在设计开发阶段有哪些安全问题需要解决？关键一点是，API 生产各阶段的责任人是谁？

设定项目完成时间表有助于确保项目不超预算。重要的是，时间表必须切实可行且具有灵活性。 

团队需回答诸如此类的问题：是否有必须满足的特定日期（例如新功能上线日）？在 API 部署前，是否需要安全或法律合规团队或其他利益相关方批准？ 

关于 API 的文档和其他信息将存储于何处，以便开发者和用户访问？代码变更将在何处跟踪和存储？

在一开始就回答这类问题，有助于为生命周期的后续阶段制定清晰的计划。

规划阶段描述了期望的成果，而设计阶段则明确了团队实现该成果的计划。在整个设计过程中，API 设计团队决定如何构建 API，以满足规划阶段所详述的要求。 

团队必须就 API 将采用的协议和架构风格做出设计决策。这一决策可能基于组织现有的 API 架构，也可能基于该新 API 的预期使用场景。

例如，常见的 API 框架和架构包括 REST、GraphQL 和 gRPC；每种都有其优缺点。 

• REST：简单、直观、普遍，但不适用于复杂查询，且不提供强类型。
  
  
• GraphQL：高效，具有强类型和内置文档。但 GraphQL 也可能较为复杂，且比 REST 需要更多的设置和特定专业知识。
  
  
• gRPC：快速，具有强类型、自动代码生成和双向流式传输。gRPC 常用于微服务通信。但作为较新的框架，存在学习曲线，且其文档格式是二进制而非人类可读。 

在设计 API 时，团队还需确定采用何种身份验证方式（如 OAuth 2.0）是合适的，以及 API 是否应置于 API Gateway 之后。

规范文档以标准化方式描述 API 的结构、行为和功能。它提供了关于 API 如何构建、能做什么以及如何与之交互的单一可信信息源。 

最流行的标准化规范是 OpenAPI 规范，它允许开发者定义路径、方法、参数、身份验证方式等。OpenAPI 专用于 REST API，并支持一套名为 Swagger 的开源工具，提供代码生成、编辑和自动文档创建功能。

对于 GraphQL，其对应规范是 GraphQL schema，这是一种用模式定义语言（SDL，一种人类可读格式）编写的强类型契约。GraphQL 生态系统提供了几种不同的工具，它们利用这种模式以提供与 OpenAPI 类似的功能；例如，GraphiQL 是一个浏览器内的集成开发环境 (IDE)，供开发者作为沙盒使用。 

对于gRPC，Protocol Buffers（protobuf）是一种序列化格式和接口定义语言 (IDL)，是规范最常用的文件格式。Protobuf 不提供交互式测试，尽管有一些网页用户界面支持此功能。 

在此阶段，开发者开始依据上一步规划好的 API 设计方案进行编码。开发过程中，使用版本控制系统来跟踪版本和代码变更。

版本控制系统的行业标准是 Git，这是一款开源软件，用于跟踪存储在开发者本地设备上的代码变更。开发者使用 Git 创建、管理和跟踪代码变更，但随后需要一个可供自己和他人访问这些代码的位置。 

GitHub 是最流行的 Git 托管服务，提供免费和付费层级，支持 Git 代码仓库的存储、检索和协作。此外，还有 GitLab、AWS CodeCommit 和 Microsoft Azure Repos 等替代方案可用于托管 Git 仓库。

API 测试在 API 开发阶段之中和之后都会进行；持续测试通过揭示漏洞和需求并支持定期更新来辅助开发。 

单元测试涉及将代码中的小部分隔离出来单独测试。以我们软件公司的 API 为例，假设团队需要测试获取用户信息的请求响应。GET 命令旨在根据客户数据库中的用户 ID 获取用户的姓名和电子邮件地址。单元测试将确保此 GET 请求能获取到预期信息，并且针对不存在的用户 ID 发起的请求会返回适当的错误消息。

集成测试通常在单元测试之后进行，用于发现单元测试未能检测到的问题。集成测试有助于确保多个组件或服务能够通过 API 按预期进行通信。 

回到我们的例子，假设 API 的一个特性是，当发生特定事件（如新增客户）时，会从一个系统向另一个系统发送一个 Webhook（即通知）。为确保其正常工作，设置一个集成测试：当新客户信息被添加到 CRM 时，一个模拟服务器接收通知并执行预期操作。 此过程将对所有集成点重复进行。

API 契约测试用于确保 API 的行为符合用户的预期。该契约通常以 OpenAPI 规范文件的形式构建。OpenAPI 规范是一种标准的、机器可读的文档，其中描述了 API 功能与能力的各个要素。API 规范文件通常用 JSON 或 YAML 编写，包含 API 端点、身份验证方法、可接受的请求与响应的具体格式、元数据和输入参数等要素。

评估 API 性能通常涉及对其速度和效率的衡量。在此阶段，测试人员着眼于衡量查询响应时间、错误率、资源使用情况（如 CPU 和内存使用）、延迟和吞吐量。在此阶段了解 API 的性能，有助于发现可能拖慢用户体验的瓶颈或冗余。

API 常被用于传输敏感数据，这使得安全测试至关重要。API 安全测试本质上是通过各种方式尝试“破坏” API，以确保其安全性和稳定性。这些尝试可能包括输入验证测试，确保仅当数据以预先批准的格式输入时才被接受。 

输入验证测试旨在防范各类攻击。常见的攻击类型包括 SQL 注入，即恶意行为者向应用程序插入恶意代码。SQL 是一种用于与数据库通信的语言，某些通用的 SQL 命令可能触发未经授权的响应，例如返回所有用户列表。 

其他安全测试方法包括身份验证测试（确保生物识别等身份识别措施正常运行）和授权测试（确保用户只能访问其被批准访问的功能）。 

安全测试在开发阶段之中和之后都会进行，而新的人工智能 (AI) 功能和自动化正在提高这些测试的强度和准确性。AI 安全测试工具可以自动生成测试、扫描代码中的错误、分析性能数据以帮助预测问题、标记异常行为，等等。

在医疗保健和金融服务等行业，存在相关法规、法律和指南来保护用户的安全、保障和隐私。例如 HIPAA（美国健康信息）、GDPR（欧盟个人信息）和 CCPA（加州个人信息）。 

合规测试是确保 API 遵守任何适用法律和指南的测试。例如，GDPR 赋予“被遗忘权”，意味着用户可以要求无不当延迟地完全删除其数据。对于符合 GDPR 的 API，合规测试将需要确保该规则得到遵守。

部署阶段是 API 的发布。此时 API 已通过功能、安全和合规性测试，准备就绪可供使用。在部署阶段，API 从测试环境转移到生产环境。部署 API 涉及几个步骤。

部署前，团队应再次检查，确保支持性基础设施、API 文档、用户支持、分发与沟通策略以及监控协议均已完备并准备就绪。此检查清单可能包括扩展服务器、配置警报和通知、创建常见问题解答页面、向客户发送公告（或公开发布）等等。

CI/CD（持续集成/持续部署）是一套自动化并简化软件开发、测试和交付周期的实践。它是 DevOps 方法论中的基本实践。与软件应用类似，API 也常被纳入 CI/CD 管道中，简化和自动化 API 的部署、测试和更新。 

API Gateway 是一个软件层，为客户端访问各种后端服务或后端服务的多个实例提供单一入口点。API Gateway 可以提供多项优势：

• 简化：客户端只需记录一个服务 URL，而不是多个
  
  
• 负载均衡：组织可以将单个服务的流量分配到多个实例上，分散负载，避免性能瓶颈
  
  
• 安全与治理：网关可用于跨多个 API 应用标准化的安全和治理协议。 
  
  
• 缓存： 网关可通过存储跨多个服务的频繁访问数据来协助缓存。这有助于加速响应、提升性能。

组织通常会在完全公开发布 API 之前，向特定用户发布测试版。这使组织能够在更安全、更可控的环境中发现并修复错误、征求反馈、衡量性能以及推广 API。

一旦检查清单和任何测试版发布工作完成，就到了“拨动开关”、全面部署 API 的时候。此过程可能包括启动分发策略，进一步告知内部或外部客户有关 API 的信息并鼓励其使用。分发过程还可能包括发布用户指南和其他对外宣传材料、更新网站或 API 目录，以及调整设置以实现即时访问，而非要求私有身份验证。

了解并规划完整 API 生命周期的主要益处之一，是确保从最初就关注监控、可观测性和维护。发布上线并不意味着工作完成；仍有后续工作需要做。 API 监控是一个持续的过程，旨在实时观察 API 在真实环境中的表现。 

监控的关键指标包括响应时间（即 API 响应请求所需的时间）、错误率（即失败请求的百分比）、吞吐量与流量（即 API 能处理的请求数量），以及基础设施分析（衡量服务器的负载与运行状况）。

维护环节则是对监控工具收集到的数据做出响应。维护可以采取修复错误、优化性能，甚至增加新特性或新功能等形式。

在我们 CRM 的例子中，监控工具可能检测到当客户数据从一个平台发送到另一个平台时延迟较高；维护阶段可以通过减少代码冗余、微调缓存设置，或将服务器迁移到离服务客户更近的位置来解决该问题。

API 生命周期的终结阶段，与其他任何阶段同样重要、充满动态且富有价值。

版本管理是指通过在其活跃生命周期内进行更新，维持 API 效能的持续过程。版本管理的关键在于，在提供变更和改进的同时，不破坏现有用户已有的功能。 

对于简单的错误修复等情况，通常无需发布新的 API 版本即可完成更新，因为这些小改动被视为“非破坏性”变更。但对于“破坏性”变更（新版本与待替换的旧版本不向后兼容），最佳实践是将此变更作为一个新版本引入。

沟通，无论是及早沟通还是频繁沟通，对版本管理都至关重要。一种常见做法是支持并行版本：旧版本与新版本保持同时激活和运行，开发者通过沟通敦促用户迁移至新版本。一旦所有或足够多的用户完成迁移，旧版本便可停用。

退役是指永久移除并禁用 API。并非所有 API 都会被退役，但最终被替换是常见情况。API 可能被退役的原因有多种：

• 新版本提供了更优性能
•  无法再充分 满足合规或安全需求
• 组织内部的业务或财务状况发生变化
• 与更新软件不兼容

退役之后，API 将不再具备功能。但有几个阶段可以帮助平稳完成这一过渡。

API 的退役需要讨论。是否有必要退役该 API？为什么？如有替代方案，是什么？需要告知哪些人即将退役的消息？

通常，组织会发布公告，宣布某 API 即将退役。该公告包含 API 用户所需的所有信息，例如进行此项变更的原因、变更发生的时间，以及用户需要采取的行动（如有）。 

此后，API 即被正式弃用。此时 API 仍保持运行，但将不再接收新更新或新功能。弃用期的设立是为了给予用户时间和知晓度，以便进行任何必要的调整。

“日落日”是指公开 API 被完全关闭的日子，届时请求将不再得到响应，尝试连接该 API 的客户端将收到错误消息。最佳实践是更新文档以反映此变更，并释放该 API 所使用的服务器空间或其他基础设施。 

对已退役的 API 进行事后回顾是一项有益的实践。团队可以讨论在整个 API 生命周期中学到的经验教训，以及如何将其应用于未来的项目。