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

API 入门（0 基础版）

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

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）

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

回到餐厅的比喻：

餐厅需要做的事情（实现细节）：

• 采购食材、处理库存
• 安排厨师、协调后厨
• 控制火候、调味摆盘
• 清洗餐具、打扫卫生

顾客完全不需要知道这些！顾客只需要：

• 看菜单点菜
• 等菜上桌
• 享用美食

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

这就带来两个好处：

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

---

2. 两种常见的 API 形式

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

2.1 外卖配送（HTTP API）

你不用亲自去餐厅，只需要：

1. 打开外卖 APP（找到入口：网址）
2. 选好菜品、填好地址（准备请求：参数）
3. 等外卖员送到（接收响应：数据）

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

流程是这样的：

你的电脑 → 发送请求 → 网络传输 → 对方服务器
                        ↓
                  处理你的请求
                        ↓
你的电脑 ← 接收结果 ← 网络传输 ← 对方服务器

举个例子：调用 AI 模型生成文本

• 你发送："帮我写一首关于春天的诗"
• 对方处理：调用大语言模型生成
• 你接收：返回生成的诗歌

2.2 餐堂堂食（SDK/API）

你走进餐厅，直接对服务员说：

• "来一份宫保鸡丁"

SDK（软件开发工具包） 就像是餐厅的"服务员"，它已经在餐厅里了，你只需要说话（调用函数），它会帮你：

• 把要求转达给厨房（内部帮你调用 HTTP API）
• 处理各种复杂细节（鉴权、重试、数据格式）
• 最后把结果整理好给你

所以你会听到两种说法：

• "调用这个服务的 API"（通常指 HTTP API，像外卖）
• "调用这个 SDK 的 API"（通常指函数接口，像堂食）

---

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

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

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

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

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

# 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 的方式（堂食模式）

就像走进餐厅直接点餐：

// 安装 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 的方式更简单，因为它帮你处理了很多细节！

3.3 两种方式的对比

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

---

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

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

点我展开：进阶内容（用人话讲）

在 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（会真的保存一条评论）

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

除了 GET 和 POST，还有：

• PUT：更新（替换整个资源）
• PATCH：打补丁（更新部分字段）
• DELETE：删除

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

---

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

API 文档就像餐厅的菜单 + 说明书，告诉你：

• 有哪些菜可以点（提供哪些功能）
• 每道菜是什么（接口说明）
• 怎么点（怎么调用）
• 什么价格（返回什么数据）
• 有没有忌口/限量（注意事项）

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 错误，专注于练出核心手感。

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	请求体，像点菜单的详细内容（具体的菜品要求）