Remi Resume复杂业务系统、工程交付与产品化实践

2026-08-06T08:20:46.044Z / restful-api

通用 API 设计指南

从 API First、OpenAPI Specification 到 API 用户文档，梳理 RESTful API 设计与交付中的通用实践。

Restful ApiApi DesignOpenapi

2. 通用 API 设计指南

2.1 API First 原则

概述

API First 原则强调：

API 应该作为契约优先进行设计，然后再开始实现代码。

API Specification 是 API 生命周期中的核心产物，应作为整个开发过程中的事实来源。

通过优先设计 API，可以：

  • 建立 API 提供方和消费者之间清晰的沟通
  • 支持不同团队之间并行开发
  • 降低集成风险
  • 提高 API 一致性和可维护性

设计要求

实现前定义 API

API 应该在编写实现代码之前完成设计。

API 契约应该定义：

  • Resource 和 Endpoint
  • HTTP Method
  • Request 和 Response Model
  • 数据 Schema
  • 错误处理行为
  • 安全要求
  • 版本策略

API Specification 应使用 OpenAPI 作为 API 描述语言。

推荐流程：

text 
API Design
    |
    v
OpenAPI Specification
    |
    v
API Review
    |
    v
Implementation
    |
    v
Testing and Validation

遵循 API 设计规范

API 设计应该遵循成熟的 RESTful API 设计原则。

API Specification 应通过自动化 API Linter 工具进行验证。

API Linter 可以帮助发现：

  • 命名不一致
  • 缺少必要元数据
  • HTTP 语义错误
  • Resource 建模问题
  • 文档问题
  • 兼容性风险

自动化验证应该集成到 API 生命周期中。

提前进行 API Review

对于外部消费者使用的 API，应提前收集：

  • API 使用方反馈
  • 客户端开发人员反馈
  • 同行评审意见

提前 Review 可以在实现之前发现设计问题，并降低后期修改成本。

Review 重点包括：

  • API 易用性
  • Resource 建模
  • Request / Response 设计
  • 客户端兼容性
  • 长期维护能力

2.2 使用 OpenAPI 定义 API Specification

概述

OpenAPI 是描述 RESTful API 契约的推荐标准。

API Specification 应使用完整独立的 OpenAPI 文档进行维护。

示例：

yaml 
openapi: 3.0.3

info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        "200":
          description: Success

完善的 OpenAPI Specification 可以支持：

  • 自动生成 API 文档
  • 自动生成客户端 SDK
  • API 验证
  • 自动化测试
  • 团队协作

OpenAPI 版本选择

新 API

新 API 应使用：

text 
OpenAPI 3.0+

OpenAPI 3.0 是目前兼容性较好的默认选择。

Legacy API

已有旧版本 API 可以继续维护原有格式。

但是：

新的 API 开发不应该继续采用过时规范。

OpenAPI 3.1 使用建议

OpenAPI 3.1 可以用于：

  • 需要更强 JSON Schema 支持
  • 从其他 API 描述格式迁移
  • 工具链已经支持

采用 OpenAPI 3.1 前，应确认：

  • 文档工具支持
  • Code Generator 支持
  • API Gateway 支持
  • Validation 工具支持

工具兼容性考虑

选择 OpenAPI 版本时，应考虑实际使用场景。

场景 关注点
API 文档 文档工具支持
代码生成 Generator 成熟度
API 校验 Linter 支持
SDK 生成 编程语言支持

Schema 设计注意事项

虽然 OpenAPI 支持高级 Schema 组合能力，但使用以下特性时需要谨慎：

  • oneOf
  • anyOf
  • allOf
  • not

过度依赖工具支持不足的 Schema 特性可能导致：

  • SDK 生成失败
  • 客户端兼容性下降
  • 工具链异常

2.3 API 用户文档

概述

对于外部 API，仅提供 OpenAPI Specification 通常是不够的。

API User Documentation 应作为 API Specification 的补充。

OpenAPI 描述：

API 技术契约

用户文档描述：

如何理解和正确使用 API

推荐文档内容

一个完整的 API 用户手册通常包括：

API 范围和用途

文档应该说明：

  • API 负责的能力
  • 支持的业务场景
  • 目标消费者
  • 常见使用方式

示例：

text 
User API 提供用户生命周期管理相关操作。

API 使用示例

应该提供：

  • Request 示例
  • Response 示例
  • 认证示例
  • 常见调用流程

示例：

http 
GET /users/123

Response：

json 
{
  "id": "123",
  "name": "Alice"
}

错误处理和问题排查

文档应该说明：

  • 错误码
  • 错误信息
  • 可能原因
  • 修复方式

示例：

HTTP 状态码 描述 建议操作
400 请求错误 检查请求参数
401 认证失败 刷新认证信息
404 资源不存在 检查资源 ID
500 服务器错误 重试或联系维护人员

架构背景

复杂 API 应提供：

  • 系统架构图
  • 服务依赖
  • 数据流说明
  • 集成关系

示例：

text 
客户端
  |
  | REST API
  |
API Gateway
  |
Backend Service
  |
Database

Sequence Flow 示例

复杂流程建议提供时序图。

示例：

sequenceDiagram
    participant Client
    participant API
    participant Service

    Client->>API: 请求
    API->>Service: 处理请求
    Service-->>API: 返回结果
    API-->>Client: 响应

总结

优秀的 RESTful API 应遵循：

原则 说明
API First API 设计优先于代码实现
OpenAPI Contract 使用 OpenAPI 作为 API 契约
Early Review 提前让消费者参与设计
API Validation 使用自动化检查保证质量
Documentation 提供清晰使用说明
Developer Experience 降低 API 使用和集成成本

目标是构建：

  • 一致的 API
  • 易维护的 API
  • 易发现的 API
  • 可持续演进的 API
  • 易于集成的 API

优秀 API 不仅需要功能正确，更需要提供清晰、稳定、可预测的接口契约。

通用 API 设计指南 | Remi Resume