PI 优先设计（API Design-First）全面解析

OpenAPI已成为REST API设计的默认标准，而AsyncAPI则成为事件驱动API的描述标准。这种工作流程能够显著简化API生命周期中的各个环节。

API设计优先的简史

为了更好地理解API设计优先的重要性，我们可以回顾其发展历程：

早期：WSDL和SOAP

在20世纪90年代末和21世纪初，SOAP Web服务非常流行。开发者使用基于XML的WSDL（Web服务描述语言）来描述这些服务。WSDL文件以详细的XML格式定义了所有操作和数据结构，尽管功能强大，但其复杂性让开发者感到困惑和挫败。

REST API的崛起

2000年代初，REST API因其简单性和可扩展性逐渐取代SOAP。然而，REST并没有统一的描述标准，开发者通常依赖手动文档（如cURL命令或Postman集合）来记录API。这种方式虽然有效，但容易导致文档与实际实现不一致。

OpenAPI时代

2011年前后，Swagger（后更名为OpenAPI）引入了一种标准化的机器可读格式，用于定义API的操作、参数和验证规则。OpenAPI的出现解决了REST API描述的混乱问题，并逐渐成为行业标准。

AsyncAPI的出现

2017年，AsyncAPI发布了1.0版本，为事件驱动架构提供了类似OpenAPI的描述标准。它支持常见的消息代理（如Apache Kafka和RabbitMQ），进一步扩展了API设计的应用范围。

什么是API设计优先？

API设计优先意味着在编写任何应用程序代码之前，先定义API的合同。该合同通常包括以下内容：

端点（URL）及其HTTP方法（如GET、POST等）。
资源和集合的结构及其验证规则。
身份验证规则（如API密钥、OAuth 2.x、OpenID）。
错误结构及示例。

尽管这种方法在初期可能看起来增加了工作量，但它类似于为应用程序编写测试，能够加速API交付，节省时间和成本，避免在测试或生产阶段进行代价高昂的重构。

为什么选择API设计优先？

以下是API设计优先的主要优势：

清晰的沟通：所有团队成员（包括前端开发人员、测试人员和外部用户）都能明确API的功能。
并行开发：前后端团队可以同时工作，通过Mock API实现无缝协作。
一致性：在合同达成一致后，执行标准更加容易。
自动化：工具可以自动生成文档、代码片段甚至部分实现。
版本控制：便于跟踪和管理API的变更。

API描述格式及其作用

在API设计优先的工作流程中，选择合适的API描述格式至关重要：

OpenAPI

OpenAPI文档使用JSON或YAML编写，既可机器读取，也对人类友好。它包含API接口的详细信息，如请求、响应和可重用组件。例如：

openapi: 3.0.0
info:
  title: 示例API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

AsyncAPI

AsyncAPI的工作方式类似于OpenAPI，但它用于描述“发布者”和“消费者”之间的事件驱动交互。例如：

asyncapi: 3.0.0
channels:
  user/signedup:
    subscribe:
      message:
        $ref: '#/components/messages/userSignedUp'

设计优先与代码优先的对比

长期以来，代码构建API的主流方式。然而，这种方法通常会导致以下问题：

客户端看到的API版本与预期不符，导致大量返工。
文档与代码分离，容易出现不一致。

相比之下，设计优先方法通过先定义合同，避免了上述问题。以下是两种方法的对比：

设计优先与代码优先对比

API设计优先的工具与优势

结合OpenAPI或AsyncAPI的API设计优先工作流程，可以带来以下好处：

人机可读：YAML/JSON格式既清晰又易于管理。
交互式文档：工具如Bump.sh可以将API描述转化为交互式文档，便于客户端快速集成。
模拟服务器：工具如Microcks允许开发者在API开发初期模拟API行为。
服务器端验证：通过API描述直接驱动验证逻辑，确保文档与实现一致。
合同测试：自动化工具可以根据API描述验证实现的正确性。
代码生成：从描述文档生成客户端库或服务器存根，节省开发时间。
API样式指南：通过描述文件强制执行API标准，减少人为错误。

TypeSpec：简化OpenAPI的工具

如果觉得编写大量YAML文件过于繁琐，可以尝试TypeSpec。TypeSpec是微软推出的一种基于TypeScript的DSL，用于设计HTTP API。它将“设计”和“描述”分离，允许开发者快速调整模型，并在需要时导出为OpenAPI文档。

TypeSpec的主要优势包括：

快速迭代：通过TypeScript的自动完成和批量重命名功能，轻松调整API设计。
工具兼容性：设计完成后，可导出为OpenAPI文档，使用现有工具进行验证、模拟和文档生成。

总结

API设计优先是一种在编码前确定API设计的开发方法。它能够帮助团队更快地工作，保持一致性，并避免后期的代价高昂的错误。OpenAPI和AsyncAPI分别为REST API和事件驱动API提供了强大的支持。在工具的加持下，API设计优先方法不仅提升了开发效率，还显著降低了开发成本和客户的不满。

原文链接: https://bump.sh/blog/dev-guide-api-design-first