API 入门与设计

原始素材：4-服务器与后端/4.08-api-intro.md

什么是 API? 这就像问:餐厅的菜单怎么设计,客人一看就懂?服务员怎么记单,不会出错?API 解决的就是"程序之间如何对话"的问题。你写代码的第一天就在用 API,只是你可能没意识到。

0. 新手常见的三个困惑

困惑一:API 是很高深的东西吗?

很多人一听到 API,就觉得是高级工程师才能理解的概念。其实你早就用过 API 了:

len("hello")        # 这就是 Python 提供的 API
open("file.txt")    # 这也是 API
requests.get(url)   # 这还是 API

困惑二:Web API 和普通 API 有什么区别?

困惑三:我该用 HTTP 还是 SDK?

import requests
response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx"},
    json={"model": "deepseek-chat", "messages": [...]}
)
result = response.json()["choices"][0]["message"]["content"]

from openai import OpenAI
client = OpenAI(api_key="sk-xxx")
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[...]
)
result = response.choices[0].message.content

1. API 的本质:插头与插座

API(Application Programming Interface,应用程序编程接口)就是"程序之间对话的约定"。

1.1 用电器来类比

1.2 三种 API 形态对比

调用对象本地代码库

通信方式函数调用

延迟纳秒级

典型场景数据处理、文件操作

函数 API 示例

len("hello")           # 返回 5
max([1, 5, 3])         # 返回 5
open("file.txt").read() # 读取文件

1.3 函数 API vs HTTP API 的区别

很多初学者会困惑：函数 API 和 HTTP API 到底有什么区别？看文档时该如何区分？

函数 API 示例：

# 调用内置函数
length = len("hello")      # 返回 5

# 调用库函数
import math
result = math.sqrt(16)     # 返回 4.0

# 调用自定义函数
def add(a, b):
    return a + b
sum = add(3, 5)            # 返回 8

HTTP API 示例：

POST /v1/chat/completions HTTP/1.1
Host: api.deepseek.com
Authorization: Bearer sk-xxx
Content-Type: application/json

{"model": "deepseek-chat", "messages": [{"role": "user", "content": "你好"}]}

核心要点： 函数 API 是"本地办事"，HTTP API 是"远程通信"。看文档时，函数关注参数和返回值，HTTP API 关注 Endpoint、认证和请求/响应格式。

1.4 不同类型的 API 文档怎么看

面对不同类型的 API 文档，关注重点各不相同：

函数文档示例

### json.loads(s, *, cls=None, object_hook=None...)

将 JSON 字符串解析为 Python 对象

**参数：**
- s (str): 要解析的 JSON 字符串
- cls (JSONDecoder): 自定义解码器类
- object_hook (callable): 可选的转换函数

**返回值：**
- dict | list: 解析后的 Python 对象

**异常：**
- JSONDecodeError: 字符串格式非法

**示例：**
>>> import json
>>> json.loads('{"name": "Alice"}')
{'name': 'Alice'}

阅读建议

• 先看函数签名，了解需要什么参数
• 注意参数的类型和是否必填
• 查看返回值类型，方便后续处理
• 关注可能抛出的异常，做好错误处理

阅读建议 ：函数文档看签名，API 文档看请求格式，SDK 文档看示例。遇到不会的，先找「Quick Start」或「Getting Started」章节。

2. 一次完整的 API 调用

API 调用演示：选择端点 GET /api/users | POST /api/users | GET /api/users/999 | POST /api/orders → HTTP Request → 等待中... → HTTP Response ←

2.1 API 调用的四个阶段

2.2 餐厅类比

3. HTTP 方法:你是在"问"还是在"做"?

调用 Web API 时,你需要告诉服务器你想做什么。这就是 HTTP 方法的由来。

3.1 用餐厅点餐来理解

关于幂等性

幂等性 :多次执行结果是否相同?

• 幂等的操作(GET/PUT/DELETE):点 10 次和点 1 次,结果一样
• 不幂等的操作(POST):点 10 次,可能创建 10 个订单

解决方案 :POST 操作用唯一 ID 校验,避免重复处理。

3.2 HTTP 方法速查表

4. HTTP 状态码:服务器在告诉你什么?

服务器回复时,会先返回一个状态码,告诉你请求是否成功。

4.1 状态码分类

4.2 常见状态码详解

快速参考表

5. HTTP vs SDK:自己跑腿还是让管家代办?

5.1 两种调用方式对比

5.2 如何选择?

能用 SDK 就用 SDK ,把麻烦事留给库,把时间留给自己。

6. 如何阅读 API 文档?

API 文档就像说明书和菜单的结合体。你不需要从头读到尾,只需要学会"查字典"。

6.1 文档阅读清单

打开任何一个 API 文档（如 OpenAI 或 DeepSeek），你只需要找这几样东西：

翻译成代码：

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "你好"}]
)

核心思想： 看文档找三样：地址（Base URL）、鉴权（Authorization）、参数（Parameters）。

6.2 阅读文档的步骤

1. 找到 Base URL - 这是所有请求的前缀
2. 看懂认证方式 - API Key 放在 Header 还是 Query?
3. 找到需要的 Endpoint - 你要调用的具体接口
4. 查看请求参数 - 哪些必填?哪些可选?
5. 理解返回格式 - 数据是如何组织的?

Endpoint

方法

GETPOSTPUTDELETE

API Key

试着触发以下场景:

• ✅ 成功请求 :填入正确的 Endpoint 和 API Key
• ❌ 404 错误 :填一个不存在的地址

8. 小结

核心要点

1. API 就是传声筒 ,帮你把话传给另一段代码或远程服务器
2. 你早就用过 API 了 ,从 len() 到 open() 都是 API
3. Web API 是超能力 ,让你调用千里之外的超级电脑
4. SDK 是好管家 ,能用 SDK 就别自己跑腿
5. 看文档找三样 :地址、鉴权、参数

在 AI 编程的时代,你只需要记住这几个核心概念。剩下的细节,IDE 和 AI 助手会帮你处理。

名词速查表

原始素材：4-服务器与后端/4.07-api-design.md

前后端如何高效对话？ 这就像问：餐厅的菜单怎么设计，客人一看就懂？服务员怎么记单，不会出错？上菜怎么规范，客人满意？API 设计解决的就是"对话规则"的问题。

0. 先问一个问题：你有没有经历过这些噩梦？

场景一：接口命名随心所欲

GET /getUserData
GET /fetchUserInfo
GET /queryUserById
GET /users/query

四个接口，功能一样，命名风格完全不同。新人入职一脸懵：我该用哪个？

场景二：错误处理五花八门

// 有的返回 HTTP 状态码
HTTP/1.1 404 Not Found

// 有的返回 200 + code
HTTP/1.1 200 OK
{ "code": 404, "message": "用户不存在" }

// 有的直接抛异常
HTTP/1.1 200 OK
{ "error": "出错了" }

前端不知道该怎么判断请求是否成功。

场景三：响应结构千人千面

// 接口 A
{ "data": { ... } }

// 接口 B
{ "result": { ... } }

// 接口 C
{ "content": { ... } }

每个接口返回格式都不一样，前端需要针对每个接口单独处理。

好的 API 设计就像餐厅的点餐系统 ——菜单清晰、流程规范、出错有提示。

1. 什么是 API？

API （Application Programming Interface，应用程序编程接口）就是"程序之间对话的约定"。

1.1 用餐厅来类比

1.2 一个完整的 API 请求

API 调用演示：选择端点 GET /api/users | POST /api/users | GET /api/users/999 | POST /api/orders → HTTP Request → 等待中... → HTTP Response ←

2. API 设计哲学：RPC / REST / GraphQL / gRPC

在开始具体的 RESTful 设计之前，先了解四种主流的 API 设计风格：

REST

最常用

Representational State Transfer，表述性状态转移。由 Roy Fielding 于 2000 年在其博士论文中提出。面向资源，用 URL 标识资源，用 HTTP 方法操作资源。

示例：获取用户信息

GET    /users           # 获取用户列表
GET    /users/123       # 获取单个用户
POST   /users           # 创建用户
PUT    /users/123       # 全量更新
PATCH  /users/123       # 部分更新
DELETE /users/123       # 删除用户

核心特点

✓URL 是名词，不是动词

✓使用 HTTP 方法表达操作

✓无状态，请求包含所有信息

✓可缓存，支持分层系统

适用场景公开 API、CRUD 操作、资源边界清晰的业务

官方地址https://restfulapi.net/

2.1 REST vs RESTful：有什么区别？

很多人会混淆这两个概念：

类比 ：

• REST 就像"极简主义"——一种设计理念
• RESTful API 就像"极简风格的房间"——应用了这个理念的具体实现

REST 的六大约束 ：

1. 学习成本低 ：HTTP 协议本身就体现了 REST 思想
2. 生态成熟 ：工具、框架、文档丰富
3. 通用性强 ：任何语言、任何平台都能调用
4. 易于缓存 ：GET 请求天然可缓存，CDN 友好

3. RESTful 设计：让 URL 会说话

REST （Representational State Transfer）是一种架构风格，核心思想是：

• 把网络上的事物抽象为"资源"（Resource）
• 用 URL 标识资源
• 用 HTTP 方法操作资源

3.1 用仓库来类比

关键原则 ：URL 是名词，不是动词。

3.2 URL 设计规则

统一用小写 + 连字符（-）是最安全的做法，避免大小写混乱和下划线风格不一致的问题。

3.3 HTTP 方法选择

幂等性 ：多次执行结果相同。

• 幂等的操作 （GET/PUT/DELETE）：点 10 次和点 1 次，结果一样
• 不幂等的操作 （POST）：点 10 次，可能创建 10 个订单

解决方案 ：POST 操作用唯一 ID 校验，避免重复处理。

4. 状态码：让错误"会说话"

HTTP 状态码是服务器告诉客户端"发生了什么"的标准方式。

4.1 状态码分类

✅ 2xx 成功

⚠️ 4xx 客户端错误

❌ 5xx 服务器错误

5. 错误处理：优雅地"拒绝"

好的错误处理能让客户端"看状态码就知道怎么回事"，而不是去猜。

4.1 错误处理的"避坑指南"

坑 1：所有错误都返回 200

// ❌ 错误做法
HTTP/1.1 200 OK
{ "error": "出错了" }

问题：缓存层会缓存这个"成功"响应，监控系统发现不了问题。

坑 2：错误信息太笼统

// ❌ 错误做法
HTTP/1.1 400 Bad Request
{ "message": "参数错误" }

问题：客户端不知道哪个参数错了、为什么错。

坑 3：暴露敏感信息

// ❌ 危险做法
HTTP/1.1 500 Internal Server Error
{ "stack": "at UserService.login...", "sql": "SELECT * FROM..." }

危险：暴露了代码结构、数据库查询，攻击者可以利用这些信息。

// 对比好的和差的错误处理方式

❌ 差: 所有错误都 200``❌ 差: 错误信息太笼统``❌ 差: 暴露敏感信息``✅ 好: 正确的状态码``✅ 好: 详细的错误信息``✅ 好: 安全的错误响应

响应结构

6. 版本控制：API 的"向后兼容"

6.1 为什么要版本控制？

场景：你的 App 有 100 万用户，需要修改订单接口。

如果不做版本控制 ：

• 新 App 调用新接口 → 正常
• 旧 App 调用新接口 → 字段缺失，崩溃！

正确的做法 ：

• /v1/orders - 旧接口，继续服务旧 App
• /v2/orders - 新接口，新功能在这里

6.2 版本控制策略

6.3 版本演进示例

以用户接口为例，展示 v1 到 v2 的演进：

• 保持向后兼容 ：v1 接口至少维护 6-12 个月，给客户端升级时间
• 文档同步更新 ：每个版本有独立的 API 文档
• 废弃公告 ：提前通知 v1 将在何时下线，引导迁移
• 监控使用情况 ：统计 v1 调用量，确认可以安全下线后再停止服务

7. 响应结构设计

响应结构是前后端协作的"数据契约"，统一格式能大幅降低沟通成本。

❓ 为什么统一📝 字段说明🔢 状态码📄 示例📑 分页

为什么要统一响应格式？

❌ 问题：不同接口返回格式不一致

// 接口 A
{ "data": { "user": {...} } }

// 接口 B
{ "result": { "user": {...} } }

// 接口 C
{ "user": {...} }

前端需要针对每个接口单独处理，代码冗余，容易出错

✅ 解决：统一响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "request_id": "req-xxx"
}

7.1 大厂实践参考

Google API 设计指南

参考 Google API Design Guide，Google 要求所有 API 错误响应必须包含 google.rpc.Status 消息结构：

{
  "error": {
    "code": 429,
    "message": "资源不足，请稍后重试",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_AVAILABILITY",
        "domain": "compute.googleapis.com",
        "metadata": {
          "zone": "us-east1-a",
          "service": "compute"
        }
      }
    ]
  }
}

核心要求 ：

• 必须包含 ErrorInfo 提供机器可读的错误标识
• message 面向开发者，用简洁语言描述问题和解决方案
• details 数组可包含 LocalizedMessage（本地化消息）、Help（帮助链接）等

Microsoft REST API 指南

参考 Microsoft REST API Guidelines，微软强调响应的一致性：

错误与故障的分类 ：

• 错误（Error） ：客户端传递无效数据导致，返回 4xx，不影响 API 可用性
• 故障（Fault） ：服务端无法正确响应有效请求，返回 5xx，影响 API 可用性

响应标头规范 ：

• Date：必须返回，使用 RFC 5322 格式（GMT 时区）
• Content-Type：必须返回
• ETag：支持乐观并发控制的资源必须返回

阿里巴巴 Java 开发手册

参考 阿里巴巴 Java 开发手册，阿里对 API 响应有以下规范：

统一返回对象 ：

public class Result<T> {
    private Integer code;
    private String message;
    private T data;
    private String requestId;
}

错误码分段设计 ：

参考 Stripe API Documentation，Stripe 的错误响应设计非常精细：

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "param": "number",
    "decline_code": "insufficient_funds",
    "doc_url": "https://stripe.com/docs/error-codes/card-declined"
  }
}

设计亮点 ：

• type 区分错误类型：api_error、card_error、invalid_request_error
• param 指出具体哪个参数出错，前端可直接定位表单字段
• doc_url 提供文档链接，开发者可深入了解
• decline_code 提供更细粒度的错误原因

JSON:API 规范

参考 JSON:API Specification，这是一个业界广泛采纳的 JSON API 响应规范：

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API 规范详解"
    },
    "relationships": {
      "author": {
        "data": { "type": "users", "id": "9" }
      }
    }
  },
  "included": [
    {
      "type": "users",
      "id": "9",
      "attributes": {
        "name": "张三"
      }
    }
  ]
}

核心设计 ：

• data 包含主资源，必须有 type 和 id
• attributes 存放资源属性
• relationships 描述资源关联
• included 避免重复请求，一次性返回关联数据

GitHub REST API 响应设计

参考 GitHub REST API Documentation，GitHub 的响应设计注重开发者体验：

成功响应 ：

{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif"
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World"
}

错误响应 ：

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}

设计亮点 ：

• 响应包含多种 URL 格式（html_url、url）方便不同场景使用
• 错误响应包含 documentation_url 指向文档
• 使用 Link 响应头实现分页导航

Twitter/X API v2 响应设计

参考 Twitter API v2 Documentation，Twitter API v2 采用简洁的响应格式：

{
  "data": {
    "id": "1460323737035677698",
    "text": "Hello, Twitter!"
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}

设计亮点 ：

• data 包含主数据，includes 包含关联数据（类似 JSON:API）
• 支持字段选择：?tweet.fields=created_at,public_metrics
• 分页使用 next_token 和 previous_token

7.2 最佳实践总结

综合以上规范，响应结构设计应遵循以下原则：

1. 一致性优先 ：所有接口使用相同的响应结构，前端可统一封装请求层
2. 机器可读 ：错误码 + 错误原因（reason）让程序能自动处理
3. 人类友好 ：message 描述清晰，包含解决建议
4. 可追踪 ：request_id 贯穿请求全链路，便于问题定位
5. 国际化支持 ：通过 details 扩展本地化消息

7.3 data 字段设计规范

data 是响应的核心，其设计直接影响前端开发效率。

单对象 vs 列表

单对象

{
  "code": 0,
  "data": {
    "id": 123,
    "name": "张三"
  }
}

列表

{
  "code": 0,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "total": 100
    }
  }
}

列表数据包裹在 items 数组中，分页信息放在 pagination 对象

7.4 错误响应设计进阶

⚠️错误响应设计进阶

参数校验错误

{
  "code": 10001,
  "message": "参数校验失败",
  "data": {
    "errors": [
      {
        "field": "email",
        "message": "邮箱格式不正确",
        "value": "invalid-email"
      },
      {
        "field": "password",
        "message": "密码长度至少 8 位",
        "value": "123"
      }
    ]
  }
}

field出错字段名，前端可定位表单

message用户友好的错误描述

value客户端提交的值（可选）

参考链接

• Google API Design Guide - Errors
• Microsoft REST API Guidelines
• 阿里巴巴 Java 开发手册
• Heroku HTTP API Design Guide
• Stripe API - Errors
• JSON:API Specification

8. 实战：电商系统 API 设计示例

# 用户模块
GET    /v1/users                    # 获取用户列表
POST   /v1/users                    # 创建新用户
GET    /v1/users/{id}               # 获取用户详情
PUT    /v1/users/{id}               # 全量更新用户
PATCH  /v1/users/{id}               # 部分更新用户
DELETE /v1/users/{id}               # 删除用户

# 订单模块
GET    /v1/users/{id}/orders        # 获取某用户的订单
POST   /v1/orders                   # 创建订单
GET    /v1/orders/{id}              # 获取订单详情
PATCH  /v1/orders/{id}/status       # 更新订单状态

# 商品模块（复杂过滤用查询参数）
GET    /v1/products?category=phone&price_max=5000&sort=price_desc&page=1

9. 用 AI 辅助设计 API

AI 可以帮助你快速生成符合规范的 API 设计。关键在于提供清晰的上下文和约束条件。

9.1 提示词模板

你是一位资深的后端架构师，精通 RESTful API 设计。请帮我设计一套 API 接口。

## 业务背景
[描述你的业务场景，例如：电商系统、博客平台、任务管理等]

## 功能需求
[列出需要的功能模块，例如：
- 用户管理：注册、登录、个人信息
- 订单管理：创建订单、查询订单、取消订单
- 商品管理：商品列表、商品详情、搜索]

## 设计要求
1. 遵循 RESTful 规范
2. URL 使用名词复数，小写+连字符
3. 正确使用 HTTP 方法（GET/POST/PUT/PATCH/DELETE）
4. 统一的响应格式：{ code, message, data, request_id }
5. 合理的状态码使用
6. 版本控制：URL 路径方式（/v1/）

## 输出格式
请按以下格式输出：

### 接口列表
| 方法 | URL | 描述 | 请求体 | 响应体 |
|------|-----|------|--------|--------|

### 请求/响应示例
[关键接口的详细示例]

### 状态码说明
[使用的状态码及其含义]

9.2 实战示例：电商订单 API

输入提示词：

 你是一位资深的后端架构师，精通 RESTful API 设计。请帮我设计一套电商订单系统的 API 接口。

## 业务背景
一个 B2C 电商平台，用户可以浏览商品、下单购买、查看订单状态。

## 功能需求
- 订单模块：创建订单、查询订单列表、查询订单详情、取消订单、支付订单
- 购物车模块：添加商品、修改数量、删除商品、查看购物车

## 设计要求
1. 遵循 RESTful 规范
2. URL 使用名词复数，小写+连字符
3. 正确使用 HTTP 方法
4. 统一的响应格式
5. 版本控制：/v1/

AI 输出示例：

9.3 AI 辅助设计的注意事项

• "请补充每个接口的错误响应示例"
• "请考虑分页、排序、过滤参数"
• "请添加接口的权限控制说明"
• "请检查是否符合 RESTful 最佳实践"

名词速查表