后端基础-API设计与OpenAPI

目录

• 第1章 API 契约
  • 1.1 API
  • 1.2 设计 API 时先看什么
• 第2章 RESTful 与资源
  • 2.1 RESTful
  • 2.2 资源
• 第3章 参数与响应结构
  • 3.1 路径参数
  • 3.2 查询参数
  • 3.3 请求体
  • 3.4 响应体
  • 3.5 幂等
  • 3.6 分页
  • 3.7 版本管理
• 第4章 OpenAPI 与 Swagger
  • 4.1 OpenAPI
  • 4.2 Swagger
  • 4.3 OpenAPI 的价值
• 第5章 鉴权要求如何进入接口契约
  • 5.1 登录接口
  • 5.2 受保护接口

第1章 API 契约

1.1 API

• API 是客户端和服务端之间的接口契约。
• 契约至少包含：
  • 路径
  • 方法
  • 参数
  • 返回值
  • 错误码
  • 认证要求

1.2 设计 API 时先看什么

1. 资源是什么
2. 用什么方法操作
3. 参数放路径、查询还是请求体
4. 成功返回什么结构
5. 失败返回什么状态码和错误体
6. 是否需要认证

第2章 RESTful 与资源

2.1 RESTful

• RESTful 是一种 Web API 设计风格，不是协议。
• 核心做法是把业务对象抽象成资源，再用 HTTP 方法操作资源。

示例：

• GET /users/1
• POST /users
• PUT /users/1
• PATCH /users/1
• DELETE /users/1

2.2 资源

• 资源通常用名词表示，不用动词表示。
• 资源路径描述“操作对象”，HTTP 方法描述“操作类型”。

更稳的写法：

• POST /orders

不够稳的写法：

• POST /createOrder

第3章 参数与响应结构

3.1 路径参数

• 路径参数用于标识具体资源。

/users/{userId}

• userId 一般要求明确、稳定、可定位单个资源。

3.2 查询参数

• 查询参数用于筛选、排序、分页、开关项。

/users?page=1&pageSize=20&role=admin

• 查询参数更像“查找条件”，不是资源主标识。

3.3 请求体

• 请求体用于提交结构化输入。
• POST、PUT、PATCH 通常更常见请求体。
• 请求体的格式要和 Content-Type 对应。

3.4 响应体

• 响应体用于返回数据或错误信息。
• 响应格式要尽量稳定，避免字段含义频繁变化。

常见返回结构：

{
  "data": {
    "id": 1,
    "name": "alice"
  }
}

错误结构：

{
  "code": "USER_NOT_FOUND",
  "message": "user not found"
}

3.5 幂等

• 幂等指同一个请求重复执行，多次结果和一次结果在目标状态上保持一致。
• GET、PUT、DELETE 通常要求幂等。
• POST 默认不幂等，但可以通过幂等键等机制约束重复提交。

3.6 分页

• 列表接口通常要提供分页。
• 常见参数：page、pageSize，或游标参数 cursor。
• 偏移分页实现简单，游标分页更适合大数据量和连续翻页。

3.7 版本管理

• API 变化可能影响已有客户端。
• 常见做法：
  • 路径版本：/api/v1/users
  • Header 版本
• 大版本变化才切版本，小字段增加不一定要升版本。

第4章 OpenAPI 与 Swagger

4.1 OpenAPI

• OpenAPI 是描述 HTTP API 的标准格式。
• 它描述的是接口契约，不是接口实现。
• 一个 OpenAPI 文档通常会写清：
  • 路径
  • 方法
  • 参数
  • 请求体
  • 响应体
  • 鉴权方式
  • 数据模型

4.2 Swagger

• Swagger 现在更多指一组围绕 OpenAPI 的工具链。
• 常见理解：
  • OpenAPI：规范
  • Swagger UI：文档展示与调试页面
  • Swagger Editor：文档编辑工具

4.3 OpenAPI 的价值

• 统一前后端接口理解
• 统一调试入口
• 统一数据模型描述
• 可用于生成 SDK、校验器、接口文档

第5章 鉴权要求如何进入接口契约

5.1 登录接口

• 认证不仅是运行时逻辑，也属于接口契约的一部分。
• 登录接口至少应明确：
  • 路径
  • 方法
  • 请求体格式
  • 成功响应结构

常见表达方式：

• POST /auth/login
• 请求体使用 form 或 JSON
• 返回 access_token

5.2 受保护接口

• 受保护接口应明确写清鉴权方式。
• 常见要求：

Authorization: Bearer <token>

• 也就是：
  • token 放在哪个位置
  • 用什么前缀
  • 哪些接口必须登录后访问

在 OpenAPI 里，这类要求通常会被表达成安全方案和接口安全声明。

关联

• 请求与响应怎么承载这些契约：后端基础-HTTP与请求响应
• 登录要求如何进入接口契约：后端基础-认证与登录