test-repo/docs/zh-cn/appendix/api-intro.md

# API 入门（0 基础版）

> 💡 **学习指南**：本章节无需编程基础，通过交互式演示和生动比喻带你深入理解 API 的核心概念。我们将从"餐厅点餐"这个生活场景讲起，一步步揭开 API 的神秘面纱。

<ApiQuickStartDemo />

## 0. 引言：从餐厅点餐到软件协作

想象一下，你走进一家餐厅：

1. **你**（顾客）拿着菜单，告诉服务员："我要一份宫保鸡丁，加辣。"
2. **服务员**（接口）把你的要求记下来，送到厨房。
3. **厨房**（对方的系统）根据要求做菜。
4. **服务员**把做好的菜端给你。

在这个过程中，**你不需要知道**：
- 厨房有几个厨师
- 他们用什么锅铲炒菜
- 蔬菜是从哪个市场买的
- 厨师今天心情好不好

**你只需要知道**：
- 怎么点菜（喊服务员或填单子）
- 要告诉对方什么（菜名、口味要求）
- 会得到什么（你点的菜）

**这就是 API 的本质**：它就像餐厅的**服务员**，是你和"对方的系统"之间的**桥梁**。

> **API（Application Programming Interface）** = **应用之间的"接口/入口"**：你按约定把请求交给对方，对方按约定把结果给你。

---

## 1. 核心：API 的三个关键问题

就像去餐厅点菜一样，使用 API 时你只需要搞清楚 3 个问题：

### 1.1 怎么点菜？（入口在哪里）

你首先得知道"怎么叫服务员"。在软件世界里，入口通常有两种：

- **HTTP API**：像一个"网址"，你发送网络请求过去
  - 例如：`https://api.example.com/getUser`
- **SDK/API**：像一个"函数名"，你在代码里直接调用
  - 例如：`getUserInfo(userId)`

### 1.2 要说什么？（你要填什么信息）

你不能只说"我要菜"，你得告诉服务员：
- 你要什么菜？（模型名称）
- 有什么要求？（提示词、参数）
- 你是谁？（API Key，相当于会员卡）

### 1.3 会得到什么？（成功/失败的结果）

服务员可能会端来：
- ✅ 你点的菜（成功返回的数据）
- ❌ "不好意思，这道菜卖完了"（错误提示，比如 404、500）

<ApiConceptDemo />

### 1.4 API 的核心价值：把复杂度藏起来

回到餐厅的比喻：

**餐厅**需要做的事情（实现细节）：
- 采购食材、处理库存
- 安排厨师、协调后厨
- 控制火候、调味摆盘
- 清洗餐具、打扫卫生

**顾客**完全不需要知道这些！顾客只需要：
- 看菜单点菜
- 等菜上桌
- 享用美食

**API 就像菜单和服务员**，它把"怎么做"的复杂度全部藏起来，只暴露"怎么用"的简单接口。

这就带来两个好处：
1. **简化使用**：调用者不需要理解内部实现
2. **灵活变更**：餐厅换了厨师、改了做法，但菜单不变，顾客完全无感

---

## 2. 两种常见的 API 形式

在现实世界里，你会遇到两种"点菜方式"：

### 2.1 外卖配送（HTTP API）

你不用亲自去餐厅，只需要：
1. 打开外卖 APP（找到入口：网址）
2. 选好菜品、填好地址（准备请求：参数）
3. 等外卖员送到（接收响应：数据）

**HTTP API** 就是这种方式：通过网络发送请求，等待返回结果。

**流程是这样的**：
```
你的电脑 → 发送请求 → 网络传输 → 对方服务器
                        ↓
                  处理你的请求
                        ↓
你的电脑 ← 接收结果 ← 网络传输 ← 对方服务器
```

<RequestResponseFlow />

**举个例子**：调用 AI 模型生成文本
- 你发送："帮我写一首关于春天的诗"
- 对方处理：调用大语言模型生成
- 你接收：返回生成的诗歌

### 2.2 餐堂堂食（SDK/API）

你走进餐厅，直接对服务员说：
- "来一份宫保鸡丁"

**SDK（软件开发工具包）** 就像是餐厅的"服务员"，它已经在餐厅里了，你只需要说话（调用函数），它会帮你：
- 把要求转达给厨房（内部帮你调用 HTTP API）
- 处理各种复杂细节（鉴权、重试、数据格式）
- 最后把结果整理好给你

**所以你会听到两种说法**：
- "调用这个服务的 API"（通常指 HTTP API，像外卖）
- "调用这个 SDK 的 API"（通常指函数接口，像堂食）

---

## 3. 真实世界：怎么和 AI 服务"对话"

让我们看一个真实的例子：调用 AI 模型。

**场景**：你想让 AI 帮你写一段产品文案。

### 3.1 用 HTTP API 的方式（外卖模式）

就像发外卖订单一样，你需要：

```bash
# 1. 打开外卖 APP（找到网址）
curl https://api.openai.com/v1/chat/completions

# 2. 选好菜品、填好地址（带上你的信息和要求）
--header 'Authorization: Bearer 你的API密钥'  # 你的会员卡
--header 'Content-Type: application/json'     # 说明你点的是菜单（JSON格式）

# 3. 告诉服务员你要什么（请求内容）
--data '{
  "model": "gpt-4",           # 选哪个厨师
  "messages": [               # 你的要求
    { "role": "system", "content": "你是一个营销文案专家" },
    { "role": "user", "content": "帮我为这款智能手表写一段吸引人的产品文案" }
  ]
}'

# 4. 等待配送（接收响应）
# 返回：{"choices": [{"message": {"content": "生成的文案..."}}]}
```

### 3.2 用 SDK 的方式（堂食模式）

就像走进餐厅直接点餐：

```javascript
// 安装 SDK（相当于走进餐厅）
import OpenAI from 'openai';

// 创建"服务员"（初始化客户端）
const client = new OpenAI({
  apiKey: '你的API密钥'  # 你的会员卡
});

// 直接点菜（调用函数）
const response = await client.chat.completions.create({
  model: 'gpt-4',           # 选哪个厨师
  messages: [               # 你的要求
    { role: 'system', content: '你是一个营销文案专家' },
    { role: 'user', content: '帮我为这款智能手表写一段吸引人的产品文案' }
  ]
});

// 享用美食（使用结果）
console.log(response.choices[0].message.content);
```

**看出来了吗？** SDK 的方式更简单，因为它帮你处理了很多细节！

<RealWorldApiDemo />

### 3.3 两种方式的对比

| 特点 | HTTP API（外卖） | SDK API（堂食） |
|------|------------------|-----------------|
| **使用门槛** | 需要理解网络请求、数据格式 | 只需会调用函数 |
| **灵活性** | 更灵活，任何语言都能用 | 通常限定特定语言 |
| **复杂度** | 你要处理很多细节（鉴权、错误等） | SDK 帮你处理细节 |
| **典型场景** | 跨语言调用、学习原理 | 日常开发、快速集成 |

---

## 4. 进阶：GET 和 POST 有什么区别？

> 🎯 **新手提示**：这一节可以暂时跳过。等你熟悉了基本调用，再回来了解也不迟。

<details>
<summary>点我展开：进阶内容（用人话讲）</summary>

在 HTTP API 的世界里，你会经常看到 **GET** 和 **POST** 这两个词。它们就像两种不同的"点菜方式"。

### 4.1 GET：像看菜单（只看不吃）

**特点**：
- 只是想"获取"信息，不会改变服务器状态
- 就像在餐厅看菜单，你看一遍菜单，厨房的菜不会被消耗
- **可以安全重试**：看一遍菜单没看清，再看一遍，没问题

**例子**：
- 查询用户信息：`GET /api/user/123`
- 搜索商品：`GET /api/products?keyword=手机`
- 获取文章列表：`GET /api/articles`

### 4.2 POST：像下单（会真的执行）

**特点**：
- 会"创建"或"修改"服务器上的数据
- 就像你下了单，厨房真的开始做菜了
- **不能随意重试**：下错了单，再下一遍，你就点了双份！

**例子**：
- 创建用户：`POST /api/users`（会真的创建一个新用户）
- 下单购买：`POST /api/orders`（会真的扣钱、发货）
- 发表评论：`POST /api/comments`（会真的保存一条评论）

<ApiMethodDemo />

### 4.3 还有哪些方法？（简单了解）

除了 GET 和 POST，还有：
- **PUT**：更新（替换整个资源）
- **PATCH**：打补丁（更新部分字段）
- **DELETE**：删除

**新手建议**：先学会用 GET 和 POST，其他的慢慢来。

</details>

---

## 5. 怎么读 API 文档？（像看菜单一样简单）

API 文档就像餐厅的**菜单 + 说明书**，告诉你：
- 有哪些菜可以点（提供哪些功能）
- 每道菜是什么（接口说明）
- 怎么点（怎么调用）
- 什么价格（返回什么数据）
- 有没有忌口/限量（注意事项）

<ApiDocumentDemo />

### 5.1 阅读 API 文档的 5 步法

就像看菜单点菜一样，按这个流程来：

**第 1 步：确认这道菜是不是你要的**
- 这个接口能做什么？
- 符合你的需求吗？

**第 2 步：找到"点菜入口"**
- HTTP API：网址（URL）是什么？
- SDK：函数名是什么？

**第 3 步：看看要填什么信息**
- **必填项**：就像"必须选辣度/份量"，不填不行
- **可选项**：就像"要不要加葱花"，可以不填
- **默认值**：就像"默认中辣"，你不填就按这个来

**第 4 步：看看会端上来什么**
- 成功时返回什么数据？
- 字段代表什么意思？
- 可能是空的吗？

**第 5 步：了解"餐厅规则"**
- 没钱了会怎样？（余额不足）
- 点太快会怎样？（限流/Rate Limit）
- 菜卖完了会怎样？（404 资源不存在）
- 厨房出错会怎样？（500 服务器错误）

### 5.2 常见的状态码（就像餐厅的回复）

| 状态码 | 含义 | 餐厅类比 |
|--------|------|----------|
| **200** | 成功 | "这是您的菜，请慢用" |
| **400** | 请求错误 | "您点的菜我们有，但您填的信息有问题" |
| **401** | 未授权 | "请先出示会员卡" |
| **403** | 禁止访问 | "您的会员卡等级不够，点不了这道菜" |
| **404** | 资源不存在 | "对不起，您点的菜卖完了" |
| **429** | 请求过多 | "您点太快了，请稍后再试" |
| **500** | 服务器错误 | "厨房出故障了，请稍后再试" |

---

## 6. 实战：用"模拟 API"练出手感

理论讲完了，该动手了！在真实世界里，你会用 Postman、curl 或代码去调用 API。但这里我们准备了一个"练习场"，不用担心网络问题、CORS 错误，专注于练出核心手感。

<ApiPlayground />

### 6.1 建议按顺序试试这些"场景"

就像去餐厅"踩点"一样，试试各种情况：

**场景 1：忘带会员卡**
- 把"登录/钥匙"改成"没有"
- 观察返回什么错误（通常是 401）

**场景 2：点太快被限流**
- 连续快速点击"调用"按钮
- 观察返回什么错误（通常是 429）

**场景 3：点菜信息填错了**
- 选 POST 创建用户
- 把 Body 改成非法的 JSON 格式
- 观察返回什么错误（通常是 400）

**场景 4：点的菜卖完了**
- 把用户 ID 改成 `u_404`（不存在的用户）
- 观察返回什么错误（通常是 404）

### 6.2 练习目标

通过这些练习，你要掌握：
1. **能看懂成功响应**：知道返回的数据在哪里
2. **能看懂错误提示**：知道为什么失败、怎么改
3. **有手感**：知道调用 API 的基本流程

---

## 7. 总结：记住这三句话就够了

### 7.1 API 的三种形式

| 类型 | 比喻 | 特点 |
|------|------|------|
| **HTTP API** | 外卖配送 | 通过网络调用，你发请求它回结果 |
| **SDK API** | 餐厅堂食 | 通过函数调用，它内部帮你发请求 |
| **库 API** | 自己做菜 | 本地函数，不走网络 |

### 7.2 核心记忆点

1. **API = 接口**：就像餐厅的服务员，是你和对方系统的桥梁
2. **调用三要素**：入口（网址/函数名）、参数（要告诉什么）、返回（会得到什么）
3. **学会读文档**：就像看菜单，先确认能不能用，再看怎么用

### 7.3 下一步建议

现在你已经理解了 API 的基本概念，可以去：
- 读一读真实的 API 文档（比如 OpenAI、DeepSeek 的文档）
- 用 Postman 或 curl 试试真实的 API 调用
- 在你的项目里接入第一个 API

---

## 8. 名词速查表

> 💡 **使用建议**：不用背！遇到不懂的词回来查就行。你只要会"看文档、会填参数、能看懂成功/失败"，就已经能开始用 API 了。

| 名词 | 英文 | 解释 |
|------|------|------|
| **API** | Application Programming Interface | 软件对外公开的接口/入口，像餐厅的服务员 |
| **HTTP API** | HTTP API | 通过网络调用的接口，像外卖配送 |
| **SDK** | Software Development Kit | 软件开发工具包，像餐厅的服务员（帮你处理细节） |
| **URL** | Uniform Resource Locator | 你要访问的"网址"，像餐厅的地址 |
| **参数** | Parameter | 你要告诉对方的信息，像点菜时的要求（辣度、份量） |
| **请求** | Request | 你发给对方的要求，像点菜单 |
| **响应** | Response | 对方给你的结果，像端上来的菜 |
| **状态码** | Status Code | 成功/失败的数字提示，200=成功，4xx=你错了，5xx=服务器错了 |
| **API Key** | API Key | 调用 API 的密钥，像餐厅的会员卡 |
| **限流** | Rate Limit | 限制调用频率，像餐厅说"您点太快了" |
| **GET/POST** | HTTP Methods | 请求方法，GET=获取信息（看菜单），POST=创建/修改（下单） |
| **JSON** | JavaScript Object Notation | 数据格式，像菜单上的格式（统一的排版） |
| **Header** | Header | 请求头，像点菜单上的备注栏（放会员卡等信息） |
| **Body** | Body | 请求体，像点菜单的详细内容（具体的菜品要求） |