feat: 更新附录文档及对应交互组件

2026-02-23 12:09:47 +08:00
parent 1062e2e16f
commit 6e13832d97
29 changed files with 13338 additions and 389 deletions
@@ -1,179 +1,35 @@
-# API 入门
+# API 入门：从零理解"程序之间的对话"

-::: tip 🎯 学习目标
-阅读完本节后，你将能够：
- 理解 API 的本质概念和设计哲学
- 区分不同类型的 API（函数 API、操作系统 API、Web API）
- 掌握 HTTP 方法的语义和使用场景
- 学会阅读和使用 API 文档
- 理解 HTTP 调用与 SDK 调用的区别
+::: tip 🎯 核心问题
+**什么是 API?** 这就像问:餐厅的菜单怎么设计,客人一看就懂?服务员怎么记单,不会出错?API 解决的就是"程序之间如何对话"的问题。你写代码的第一天就在用 API,只是你可能没意识到。
 :::

 ---

-## 1. 从一个按钮开始
+## 0. 新手常见的三个困惑

-<ApiQuickStartDemo />
+**困惑一:API 是很高深的东西吗?**

-👆 看见了吗？点击按钮，几百毫秒后，服务器返回了当前时间。
-
-这个过程，就是一次完整的 **API 调用**。虽然简单，但它包含了 API 交互的所有核心要素：
-
-| 阶段 | 发生了什么 |
-|------|-----------|
-| **请求** | 客户端向服务器发送 "给我当前时间" 的请求 |
-| **处理** | 服务器接收请求，查询系统时间 |
-| **响应** | 服务器将时间数据返回给客户端 |
-
-这就像你去便利店买水——你说"来瓶可乐"，店员给你一瓶可乐。你问一句，他给一笔。
-
-**API（Application Programming Interface，应用程序编程接口）**，本质上就是一种"对话约定"：一方提出请求，另一方给出响应。
-
---
-
-## 2. API 的三种形态
-
-很多人一提到 API，就觉得这是很高深的东西。其实，你写代码的第一天就在用 API 了。
-
-### 2.1 函数 API：最基础的形态
-
-<FunctionApiDemo />
-
-当你调用 `len("hello")` 时，你就在使用 Python 提供的一个 API。你不需要知道 `len()` 内部是怎么数字符串长度的——是用 C 实现的还是用 Python 实现的？是遍历计数还是直接读取长度字段？这些细节都被隐藏了。
-
-**API 的核心价值：把复杂的东西藏起来，只给你一个简单的用法。**
-
-再看一个更贴近实际的例子：
+很多人一听到 API,就觉得是高级工程师才能理解的概念。其实你早就用过 API 了:

 ```python
-# 你写这行代码
-response = requests.get("https://api.example.com/users")
-
-# 背后发生了什么？
-# 1. DNS 解析：把域名转成 IP 地址
-# 2. TCP 连接：建立网络通道
-# 3. TLS 握手：加密通信
-# 4. HTTP 请求：发送数据包
-# 5. 等待响应：接收服务器返回
-# 6. 解析数据：把字节流转成 Python 对象
+len("hello")        # 这就是 Python 提供的 API
+open("file.txt")    # 这也是 API
+requests.get(url)   # 这还是 API
 ```

-如果你要自己处理这 6 步，每次请求都要写几百行代码。但 `requests.get()` 把这些都封装好了，你只需要一行代码。
+**困惑二:Web API 和普通 API 有什么区别?**

-### 2.2 操作系统 API：让程序能"碰"硬件
+| 类型 | 调用对象 | 通信方式 | 典型场景 |
+| :--- | :--- | :--- | :--- |
+| **函数 API** | 本地代码 | 函数调用 | `len()`, `open()` |
+| **操作系统 API** | 操作系统 | 系统调用 | 读写文件、创建进程 |
+| **Web API** | 远程服务器 | HTTP 请求 | 调用 AI 模型、获取天气 |

-当你在电脑上打开一个文件：
+**困惑三:我该用 HTTP 还是 SDK?**

 ```python
-with open("file.txt", "r") as f:
-    content = f.read()
-```
-
-这行代码背后，Python 调用了**操作系统的 API**。
-
-| 操作系统 | API 名称 | 作用 |
-|---------|---------|------|
-| Windows | Win32 API | 文件操作、窗口管理、进程控制 |
-| Linux | POSIX API | 系统调用、进程通信、设备访问 |
-| macOS | Cocoa API | 图形界面、文件系统、网络 |
-
-没有操作系统 API，你的 Python 代码就是一堆文字，根本动不了硬盘里的文件、显示不了窗口、连不上网络。
-
-### 2.3 Web API：跨越网络的"超能力"
-
-最后，才是大多数人熟知的 Web API：
-
-```python
-import requests
-
-response = requests.post(
-    "https://api.deepseek.com/v1/chat/completions",
-    headers={"Authorization": "Bearer sk-xxx"},
-    json={
-        "model": "deepseek-chat",
-        "messages": [{"role": "user", "content": "你好"}]
-    }
-)
-```
-
-这行代码做了什么？它让你的程序穿越互联网，调用了千里之外 DeepSeek 服务器上的 AI 模型。就像你打了个越洋电话，让大洋彼岸的厨师帮你做了一道菜。
-
-**Web API 的神奇之处：让"调用别人的超级电脑"变得像调用本地函数一样简单。**
-
---
-
-## 3. API 的统一结构
-
-无论哪种 API，结构都一样。就像插头和插座，怎么变都离不开三样东西：
-
-<ApiConceptDemo />
-
-| 要素 | 函数 API | Web API |
-|------|---------|---------|
-| **地址/名称** | `len()` | `https://api.example.com/users` |
-| **输入/参数** | `"hello"` | `{"name": "张三"}` |
-| **输出/返回** | `5` | `{"id": 1, "name": "张三"}` |
-
-理解了这个统一结构，你就掌握了 API 的本质。无论是调用一个 Python 函数，还是请求一个远程服务器，思路都是一样的：
-
-1. **找到入口**（函数名或 URL）
-2. **传入参数**（按要求的格式）
-3. **处理返回**（按约定的结构解析）
-
---
-
-## 4. HTTP 方法：你是在"问"还是在"做"？
-
-调用 Web API 时，你需要告诉服务器你想做什么。这就是 HTTP 方法的由来。
-
-想象你去一家餐厅：
-
-| 场景 | 现实中你会怎么说？ | 对应的 HTTP 方法 |
-|------|-------------------|-----------------|
-| 你想知道今天有什么菜 | "服务员，菜单给我看看" | **GET** - 纯"问"，不改数据 |
-| 你想点一份宫保鸡丁 | "给我来份宫保鸡丁" | **POST** - "做"件事，创建数据 |
-| 你想换一道菜 | "把宫保鸡丁改成糖醋里脊" | **PUT** - 替换数据 |
-| 你想改口味 | "宫保鸡丁不要放花生" | **PATCH** - 部分修改 |
-| 你不想要了 | "算了，那道菜不要了" | **DELETE** - 删除数据 |
-
-<ApiMethodDemo />
-
-::: warning 关于幂等性
-**幂等性**是一个重要概念：多次执行结果是否相同？
-
- **GET**：查询 10 次和查询 1 次，结果一样 → 幂等
- **DELETE**：删除 10 次和删除 1 次，结果一样 → 幂等
- **POST**：下单 10 次，可能创建 10 个订单 → 不幂等
-
-实际开发中，POST 操作通常需要用唯一 ID 来防止重复处理。
-:::
-
---
-
-## 5. HTTP vs SDK：自己跑腿还是让管家代办？
-
-在 AI 编程教程中，你会经常看到两种调用方式：**HTTP** 和 **SDK**。它们的区别就像"自己跑腿"和"让管家代办"。
-
-<RealWorldApiDemo />
-
-### 5.1 HTTP API：自己跑腿
-
-这是最原始的方式。你需要：
-
-1. **找到网址**（Base URL + Endpoint）
-2. **准备请求头**（Authorization、Content-Type）
-3. **构造请求体**（JSON 格式的参数）
-4. **发送请求**（处理网络错误、超时）
-5. **解析响应**（把 JSON 转成可用的数据）
-
-所有编程语言都能用，但你需要处理很多细节。
-
-### 5.2 SDK：让管家代办
-
-SDK（Software Development Kit）就像是 API 提供方派给你的专属管家：
-
-```python
-# HTTP 方式：自己处理所有细节
+# HTTP 方式:自己处理所有细节
 import requests
 response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
@@ -182,7 +38,7 @@ response = requests.post(
 )
 result = response.json()["choices"][0]["message"]["content"]

-# SDK 方式：管家帮你处理
+# SDK 方式:管家帮你处理
 from openai import OpenAI
 client = OpenAI(api_key="sk-xxx")
 response = client.chat.completions.create(
@@ -192,94 +48,219 @@ response = client.chat.completions.create(
 result = response.choices[0].message.content
 ```

-SDK 自动处理了：鉴权、请求格式、错误处理、重试逻辑、响应解析。
+---

-::: tip 建议
-**能用 SDK 就用 SDK**，把麻烦事留给库，把时间留给自己。
+## 1. API 的本质:插头与插座
+
+**API**(Application Programming Interface,应用程序编程接口)就是"程序之间对话的约定"。
+
+### 1.1 用电器来类比
+
+| 概念 | 电器类比 | API 对应 |
+| :--- | :--- | :--- |
+| **接口** | 插座形状 | 函数签名 / URL |
+| **输入** | 电流输入 | 函数参数 / 请求体 |
+| **输出** | 电器工作 | 返回值 / 响应体 |
+
+### 1.2 三种 API 形态对比
+
+<ApiTypesComparison />
+
+---
+
+## 2. 一次完整的 API 调用
+
+👇 **动手试试看**:点击下方按钮,观察一次完整的 API 请求-响应流程:
+
+<ApiRequestDemo />
+
+### 2.1 API 调用的四个阶段
+
+| 阶段 | 发生了什么 | 电器类比 |
+| :--- | :--- | :--- |
+| **请求** | 客户端向服务器发送请求 | 按下开关 |
+| **传输** | 请求通过网络传输到服务器 | 电流通过电线 |
+| **处理** | 服务器处理请求并返回数据 | 电器开始工作 |
+| **响应** | 客户端接收并处理返回结果 | 灯泡发光 |
+
+### 2.2 餐厅类比
+
+| 餐厅角色 | API 对应 | 说明 |
+| :--- | :--- | :--- |
+| **菜单** | API 文档 | 告诉你有哪些"菜"可以点 |
+| **服务员** | HTTP 协议 | 标准化的"对话方式" |
+| **后厨** | 服务端 | 按"订单"处理请求 |
+| **上菜** | 响应 | 把结果返回给"客人" |
+
+---
+
+## 3. HTTP 方法:你是在"问"还是在"做"?
+
+调用 Web API 时,你需要告诉服务器你想做什么。这就是 HTTP 方法的由来。
+
+### 3.1 用餐厅点餐来理解
+
+| 场景 | 现实中你会怎么说? | 对应的 HTTP 方法 |
+| :--- | :--- | :--- |
+| 你想知道今天有什么菜 | "服务员,菜单给我看看" | **GET** - 纯"问",不改数据 |
+| 你想点一份宫保鸡丁 | "给我来份宫保鸡丁" | **POST** - "做"件事,创建数据 |
+| 你想换一道菜 | "把宫保鸡丁改成糖醋里脊" | **PUT** - 替换数据 |
+| 你想改口味 | "宫保鸡丁不要放花生" | **PATCH** - 部分修改 |
+| 你不想要了 | "算了,那道菜不要了" | **DELETE** - 删除数据 |
+
+<HttpMethodsDemo />
+
+::: warning 关于幂等性
+**幂等性**:多次执行结果是否相同?
+
+- **幂等的操作**(GET/PUT/DELETE):点 10 次和点 1 次,结果一样
+- **不幂等的操作**(POST):点 10 次,可能创建 10 个订单
+
+**解决方案**:POST 操作用唯一 ID 校验,避免重复处理。
+:::
+
+### 3.2 HTTP 方法速查表
+
+| 方法 | 用途 | 幂等性 | 安全性 | 典型场景 |
+| :--- | :--- | :--- | :--- | :--- |
+| **GET** | 获取资源 | 是 | 是 | 查询列表、查看详情 |
+| **POST** | 创建资源 | 否 | 否 | 新增用户、提交订单 |
+| **PUT** | 全量更新 | 是 | 否 | 替换整个用户资料 |
+| **PATCH** | 部分更新 | 否 | 否 | 只修改昵称 |
+| **DELETE** | 删除资源 | 是 | 否 | 删除用户、取消订单 |
+
+---
+
+## 4. HTTP 状态码:服务器在告诉你什么?
+
+服务器回复时,会先返回一个状态码,告诉你请求是否成功。
+
+### 4.1 状态码分类
+
+<StatusCodeCategories />
+
+### 4.2 常见状态码详解
+
+| 状态码 | 含义 | 典型场景 | 客户端处理 |
+| :--- | :--- | :--- | :--- |
+| **200 OK** | 成功 | 请求正常处理 | 展示数据 |
+| **201 Created** | 创建成功 | POST 请求成功创建资源 | 跳转到新资源 |
+| **400 Bad Request** | 请求格式错误 | 参数缺失或格式不对 | 检查参数 |
+| **401 Unauthorized** | 未认证 | 没有提供有效的 API Key | 引导用户登录 |
+| **403 Forbidden** | 无权限 | API Key 没有访问该资源的权限 | 提示权限不足 |
+| **404 Not Found** | 不存在 | 请求的地址或资源不存在 | 检查 URL |
+| **429 Too Many Requests** | 请求过多 | 超过了速率限制 | 稍后重试 |
+| **500 Internal Server Error** | 服务器错误 | 服务端出了问题 | 提示用户稍后重试 |
+
+👇 **动手试试看**:点击下方按钮,了解常见状态码的含义:
+
+<StatusCodeDemo />
+
+---
+
+## 5. HTTP vs SDK:自己跑腿还是让管家代办?
+
+### 5.1 两种调用方式对比
+
+| | 🏃 **HTTP API** | 🤵 **SDK** |
+| :--- | :--- | :--- |
+| **比喻** | 自己跑腿 | 管家代办 |
+| **优点** | ✓ 所有语言都能用<br>✓ 完全控制请求细节<br>✓ 无需额外依赖 | ✓ 代码简洁易读<br>✓ 自动处理鉴权<br>✓ 内置错误重试 |
+| **缺点** | ✗ 需要处理所有细节<br>✗ 代码冗长易出错 | ✗ 需要安装依赖<br>✗ 可能有版本问题 |
+| **代码示例** | `requests.post(url, json=..., headers={...})` | `client.chat.completions.create(...)` |
+
+### 5.2 如何选择?
+
+| 场景 | 推荐方式 | 原因 |
+| :--- | :--- | :--- |
+| **快速开发** | SDK | 自动处理鉴权、错误、重试 |
+| **学习原理** | HTTP | 理解底层机制 |
+| **不支持的语言** | HTTP | 任何语言都能用 |
+| **需要定制** | HTTP | 灵活控制每个细节 |
+
+::: tip 💡 建议
+**能用 SDK 就用 SDK**,把麻烦事留给库,把时间留给自己。
 :::

 ---

-## 6. 如何阅读 API 文档？
+## 6. 如何阅读 API 文档?

-API 文档就像说明书和菜单的结合体。你不需要从头读到尾，只需要学会"查字典"。
-
-打开任何一个 API 文档（比如 OpenAI 或 DeepSeek），你只需要找这几样东西：
-
-<ApiDocumentDemo />
+API 文档就像说明书和菜单的结合体。你不需要从头读到尾,只需要学会"查字典"。

 ### 6.1 文档阅读清单

+打开任何一个 API 文档(比如 OpenAI 或 DeepSeek),你只需要找这几样东西:
+
+<ApiDocumentDemo />
+
 | 项目 | 说明 | 示例 |
-|------|------|------|
+| :--- | :--- | :--- |
 | **Base URL** | API 的根地址 | `https://api.deepseek.com` |
 | **Authentication** | 如何证明身份 | `Authorization: Bearer sk-xxx` |
 | **Endpoints** | 具体的接口列表 | `/v1/chat/completions` |
-| **Parameters** | 必填/可选参数 | `model`（必填）、`temperature`（可选） |
+| **Parameters** | 必填/可选参数 | `model`(必填)、`temperature`(可选) |
 | **Response** | 返回数据结构 | `{"choices": [...]}` |

-### 6.2 常见状态码
+### 6.2 阅读文档的步骤

-服务器回复时，会先返回一个状态码，告诉你请求是否成功：
-
-| 状态码 | 含义 | 常见原因 |
-|--------|------|---------|
-| **200 OK** | 成功 | 请求正常处理 |
-| **201 Created** | 创建成功 | POST 请求成功创建资源 |
-| **400 Bad Request** | 请求格式错误 | 参数缺失或格式不对 |
-| **401 Unauthorized** | 未认证 | 没有提供有效的 API Key |
-| **403 Forbidden** | 无权限 | API Key 没有访问该资源的权限 |
-| **404 Not Found** | 不存在 | 请求的地址或资源不存在 |
-| **429 Too Many Requests** | 请求过多 | 超过了速率限制 |
-| **500 Internal Server Error** | 服务器错误 | 服务端出了问题 |
+1. **找到 Base URL** - 这是所有请求的前缀
+2. **看懂认证方式** - API Key 放在 Header 还是 Query?
+3. **找到需要的 Endpoint** - 你要调用的具体接口
+4. **查看请求参数** - 哪些必填?哪些可选?
+5. **理解返回格式** - 数据是如何组织的?

 ---

-## 7. 动手练习
+## 7. 动手练习:模拟 API 调用

-光说不练假把式。这里有个模拟 API，你可以随便填参数、随便改地址，看看会发生什么。
+光说不练假把式。这里有个模拟 API,你可以随便填参数、随便改地址,看看会发生什么。

 <ApiPlayground />

-试着触发以下场景：
- ✅ **成功请求**：填入正确的 Endpoint 和 API Key
- ❌ **401 错误**：不填 API Key，看看服务器怎么拒绝你
- ❌ **404 错误**：填一个不存在的地址
+试着触发以下场景:
+- ✅ **成功请求**:填入正确的 Endpoint 和 API Key
+- ❌ **401 错误**:不填 API Key,看看服务器怎么拒绝你
+- ❌ **404 错误**:填一个不存在的地址

 ---

 ## 8. 小结

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

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

 ---

 ## 名词速查表

 | 名词 | 全称 | 解释 |
-|------|------|------|
-| **API** | Application Programming Interface | 应用程序编程接口，定义了软件之间如何交互 |
-| **Web API** | - | 基于 HTTP 协议的 API，用于网络通信 |
-| **Endpoint** | - | 端点，API 的具体地址 |
+| :--- | :--- | :--- |
+| **API** | Application Programming Interface | 应用程序编程接口,定义了软件之间如何交互 |
+| **Web API** | - | 基于 HTTP 协议的 API,用于网络通信 |
+| **Endpoint** | - | 端点,API 的具体地址 |
 | **HTTP** | HyperText Transfer Protocol | Web API 使用的通信协议 |
 | **GET** | - | 获取资源的方法 |
 | **POST** | - | 提交数据的方法 |
-| **SDK** | Software Development Kit | 软件开发工具包，封装了底层 API 调用 |
+| **SDK** | Software Development Kit | 软件开发工具包,封装了底层 API 调用 |
 | **URL** | Uniform Resource Locator | API 的网络地址 |
 | **JSON** | JavaScript Object Notation | 常用的数据格式 |
 | **Authentication** | - | 验证身份的过程 |
 | **Status Code** | - | HTTP 响应中的状态码 |
 | **Request** | - | 请求 |
 | **Response** | - | 响应 |
-| **Header** | - | HTTP 头，包含元信息 |
+| **Header** | - | HTTP 头,包含元信息 |
 | **Payload** | - | 请求或响应的实际数据 |
 | **Rate Limit** | - | 速率限制 |
-| **Idempotent** | - | 幂等，多次执行结果相同 |
+| **Idempotent** | - | 幂等,多次执行结果相同 |
+| **REST** | Representational State Transfer | 一种 API 架构风格 |
+| **RPC** | Remote Procedure Call | 远程过程调用 |
+| **GraphQL** | - | 一种查询语言 API |
+| **gRPC** | - | Google 开发的高性能 RPC 框架 |