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

API优先设计（API Design-First），又称“Schema-First”或“Contract-First”，是一种在编写任何代码之前，优先设计 API 接口的开发方法。其核心理念是先规划 API 合同，明确功能和工作方式，确保开发团队在开始编码前对 API 有统一理解。

随着技术的发展，OpenAPI 已成为 REST API 的标准，而 AsyncAPI 则成为事件驱动 API 的描述标准。这种工作流程显著简化了 API 生命周期中的各个环节。

一. API设计优先的简史

1. 早期：WSDL 与 SOAP

20世纪90年代末至21世纪初，SOAP Web 服务盛行
使用 WSDL（基于 XML）描述服务操作和数据结构
优点：功能强大；缺点：复杂、难以维护

2. REST API 崛起

2000年代初，REST API 因简洁和可扩展性逐渐取代 SOAP
文档通常依赖手动维护（cURL 命令或 Postman 集合）
问题：文档易与实现不一致

3. OpenAPI 时代

2011年前后，Swagger（现 OpenAPI）提供标准化、机器可读的格式
定义 API 操作、参数、验证规则
成为 REST API 的行业标准

4. AsyncAPI 出现

2017 年发布 1.0 版本，为事件驱动架构提供标准描述
支持常见消息代理（Kafka、RabbitMQ 等）
扩展 API 设计的应用范围

二. 什么是 API 设计优先？

API 设计优先意味着在编写任何应用程序代码前，先定义 API 合同，内容包括：

端点（URL）及 HTTP 方法（GET、POST 等）
资源和集合的结构及验证规则
身份验证机制（API Key、OAuth2、OpenID）
错误响应结构及示例

类似为应用编写测试，能够加速交付、节省成本，并避免生产阶段的高代价重构。

三. 为什么选择 API 设计优先？

清晰沟通：前后端及外部用户对 API 功能理解一致
并行开发：通过 Mock API 支持前后端同时开发
一致性：合同达成一致后执行标准化容易
自动化：生成文档、代码片段及部分实现
版本控制：便于跟踪和管理 API 变更

四. API 描述格式及其作用

1. OpenAPI

描述 REST API
使用 JSON 或 YAML
示例：

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

2. AsyncAPI

描述事件驱动 API
类似 OpenAPI，但用于“发布者-消费者”交互
示例：

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

五. 设计优先 vs 代码优先

代码优先：

API 文档常与实现分离
客户端可能看到与预期不符的版本
容易出现返工

设计优先：

先定义合同，避免文档与代码不一致
支持并行开发与自动化生成

六. API设计优先工具与优势

可读性强：YAML/JSON 格式清晰易管理
交互式文档：Bump.sh 等工具可生成互动文档
模拟服务器：Microcks 可在开发早期模拟 API
服务器端验证：确保文档与实现一致
合同测试：自动化验证实现正确性
代码生成：生成客户端库或服务器存根
API 样式指南：强制执行标准，减少错误

七. TypeSpec：简化 OpenAPI 的工具

微软推出的 TypeScript DSL，用于 HTTP API 设计
优势：
- 快速迭代与自动完成
- 可导出 OpenAPI 文档用于验证、模拟和文档生成
将“设计”和“描述”分离，便于调整 API 模型

八. 总结

API 设计优先是一种在编码前确定 API 设计的开发方法，能够：

提升开发效率
保持团队一致性
避免后期高代价错误

OpenAPI 和 AsyncAPI 分别支持 REST 与事件驱动 API。在工具支持下，设计优先方法降低了开发成本，提高了客户满意度。

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