delorex/test-repo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update docs and configurations

Browse Source
This commit is contained in:
sanbuphy
2026-01-19 23:45:08 +08:00
parent 08da622964
commit 6806f05deb
29 changed files with 4038 additions and 1846 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh-cn/appendix/api-intro.md
+86 -252
View File
@@ -1,314 +1,148 @@
# API 入门：软件世界的"服务员"
# API 入门（0 基础版）
> 💡 **学习指南**：本章节无需编程基础，通过交互式演示带你深入了解 API（应用程序接口）。我们将从最基础的"什么是 API"讲起，到如何阅读 API 文档，再到实际调用 API。
> 💡 **学习指南**：这是写给 0 基础新手的。你先记住一句话：**API 就是“别的软件给你用的按钮/入口”**。你按它的规则“提交信息”，它按规则“把结果给你”。
<ApiQuickStartDemo />
## 0. 引言：无处不在的"桥梁"
---
你用微信登录第三方 APP 时，是谁在幕后传递信息？
你在淘宝查询物流时，是谁帮你连接快递公司的数据？
你用 AI 写代码时，是谁把你的需求传给大模型？
## 0. 引言：你真正依赖的不是“服务器”，而是“接口”
这背后都有一个功臣：**API (Application Programming Interface)**。
当你说“我要调一下接口”，你其实是在说：
如果软件是"餐厅"，那 API 就是"服务员"。
你需要什么（数据、功能），告诉服务员（调用 API），服务员会去厨房（服务器）取来，端到你面前（返回结果）。
> 我希望<strong>按某种约定</strong>把输入交给对方系统，然后<strong>按约定</strong>拿到输出（成功或失败）。
### 0.1 为什么需要 API？
这份“约定”就是 API。
想象一下，如果没有服务员（API）：
你可以先把 API 当成一句大白话：
- ❌ 每个顾客都要自己冲进厨房找菜
- ❌ 厨房会被搞乱，效率极低
- ❌ 顾客需要知道厨房怎么运作
有了服务员（API）：
- ✅ 顾客只需看菜单（API 文档）点餐
- ✅ 服务员传递订单，厨房专注做菜
- ✅ 顾客不需要知道厨房怎么运作
**关键点**：API 让不同软件之间能够"对话"，而不需要了解对方的内部实现。
> API = 别的软件给你用的“入口”：你按它说的来，它把结果给你。
---
## 1. 第一步：理解 API 的本质
## 1. 什么是 API？（新手版一句话）
### 1.1 什么是 API？
**API** 可以翻译成：**应用之间的“接口/入口”**。
**API (Application Programming Interface)** = 应用程序编程接口。
对新手来说，你只要先记住 3 件事（够用了）：
翻译成人话：**软件之间的"约定"和"服务员"**。
- **Application（应用）**：两个不同的软件系统（如你的 APP 和微信服务器）
- **Programming（编程）**：通过代码来交互
- **Interface（接口）**：双方约定的"沟通方式"
1. **怎么用它**（入口是什么：一个网址 / 一个函数名）
2. **要填什么**（你要告诉它哪些信息）
3. **会得到什么**（成功给你什么；失败会怎么提示）
<ApiConceptDemo />
**关键点**：API 定义了：
- 你可以请求什么（有哪些功能）
- 怎么请求（格式、参数）
- 会返回什么（数据结构）
### 1.1 API 不等于“实现”
### 1.2 API 的类型
API 只描述“怎么用”，不描述“怎么做”。
API 有很多种形式，最常见的有：
比如一个“获取用户信息”的 API，调用方需要知道：
| 类型 | 例子 | 说明 |
| :--- | :--- | :--- |
| **Web API** | REST API、GraphQL | 通过 HTTP 协议调用，最常见 |
| **库 API** | React、Vue | 代码库提供的函数接口 |
| **系统 API** | 文件系统 API | 操作系统提供的功能接口 |
- 你要带用户 id 吗？
- 你要不要带 Token？
- 成功返回什么字段？
- 用户不存在会返回什么错误？
本教程重点讲解 **Web API**，因为它最常用，也最容易理解。
但调用方不需要知道：
- 用户表怎么设计
- 服务拆成几个微服务
- 缓存怎么做
把实现细节藏起来，让双方能**各做各的**，这就是 API 的价值。
---
## 2. API 是怎么工作的？
## 2. 为什么 HTTP 调用可以叫 API？
### 2.1 请求-响应模型
因为用“网址发请求”本身就像按一个按钮：你把信息发过去，对方把结果回给你。（这类通常就叫 HTTP API）
API 的工作原理就像"点餐-上菜"：
1. **发起请求**：你告诉服务员要什么（调用 API）
2. **处理请求**：服务员去厨房传达（服务器处理）
3. **返回结果**：服务员把菜端上来（返回数据）
你不用记复杂的术语，先看流程就够了：**发过去 → 对方处理 → 回给你**。
<RequestResponseFlow />
### 2.2 HTTP 方法：四种基本操作
在 Web API 中，我们使用 HTTP 方法来表达不同的操作：
| 方法 | 作用 | 类比 |
| :--- | :--- | :--- |
| **GET** | 获取数据 | "给我看看菜单" |
| **POST** | 创建数据 | "我要点这道菜" |
| **PUT** | 更新数据 | "把这道菜换成辣的" |
| **DELETE** | 删除数据 | "取消这道菜" |
<ApiMethodDemo />
**关键点**：REST API 遵循"统一接口"原则，用这四种方法就能完成所有操作。
一句话总结：HTTP API 就是“用网址去叫别人做事”。
---
## 3. 认识 API 文档
## 3. 为什么 SDK 的调用接口也叫 API？
### 3.1 什么是 API 文档？
因为 SDK 本质上也是一个“工具包/库”。它对外公开的函数/方法，本来就可以叫 API（入口）。
API 文档就像**餐厅的菜单**，它告诉你：
同时，很多 SDK 会在背后帮你调用 HTTP API（还会顺便帮你处理：加“钥匙”、失败重试、把数据整理成好用的样子），所以大家会同时说：
- 📋 **有哪些菜可以点**（API 提供哪些功能）
- 💰 **每个菜的名字和价格**（接口地址、参数）
- 📝 **菜的详细说明**（返回数据格式）
- ⚠️ **注意事项**（限制条件、错误码）
<ApiDocumentDemo />
### 3.2 API 文档的组成
一个完整的 API 文档通常包含：
#### 1️⃣ 基本信息
```
接口地址：https://api.example.com/users
请求方法：GET
功能说明：获取用户列表
```
#### 2️⃣ 请求参数
```
参数名 类型 必填 说明
page number 否 页码，默认 1
limit number 否 每页数量，默认 20
```
#### 3️⃣ 返回示例
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": 1,
"name": "张三",
"email": "zhangsan@example.com"
}
]
}
```
#### 4️⃣ 错误码说明
```
400 - 参数错误
401 - 未授权
404 - 资源不存在
500 - 服务器错误
```
---
## 4. 实战：如何使用 API？
### 4.1 阅读文档的步骤
拿到一个新的 API，按以下步骤操作：
**第 1 步：找到文档入口**
- 通常在官网的 "Developers" 或 "API" 板块
- 常见的文档平台：Swagger、Apiary、Readme.io
**第 2 步：理解接口功能**
- 看接口名称和说明，判断是否是你需要的功能
- 注意请求方法（GET/POST/PUT/DELETE）
**第 3 步：查看请求参数**
- 必填参数：一定要提供
- 可选参数：根据需要提供
- 参数类型：字符串、数字、布尔值
**第 4 步：看返回示例**
- 了解成功时的返回格式
- 查看错误时的返回格式
**第 5 步：尝试调用**
- 可以用在线工具（如 Postman、curl）
- 或者在代码中调用
<ApiPlayground />
### 4.2 真实案例：调用天气 API
让我们调用一个真实的天气 API 来查询北京的天气。
- “这个服务的 API”（通常指 HTTP 接口）
- “这个 SDK 的 API”（通常指库里的函数接口）
<RealWorldApiDemo />
**代码示例**：
---
```javascript
// 使用 JavaScript 调用 API
fetch('https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=Beijing')
.then(response => response.json())
.then(data => {
console.log('北京天气：', data.current.temp_c, '°C');
console.log('天气状况：', data.current.condition.text);
})
.catch(error => {
console.error('出错了：', error);
});
```
## 4. （选读）GET/POST 这些词到底在说什么？
```python
# 使用 Python 调用 API
import requests
新手可以先跳过这一节：你只要先学会“看文档、会调用”就够用了。
response = requests.get('https://api.weatherapi.com/v1/current.json', params={
'key': 'YOUR_KEY',
'q': 'Beijing'
})
<details>
<summary>点我展开：进阶一点点（但我尽量讲人话）</summary>
data = response.json()
print(f"北京天气：{data['current']['temp_c']}°C")
print(f"天气状况：{data['current']['condition']['text']}")
```
<ApiMethodDemo />
这节想讲的只有一件事：有些请求“重试很安全”（比如 GET），有些“重试可能出事”（比如创建接口）。
</details>
---
## 5. 常见问题与最佳实践
## 5. 怎么读 API 文档？（先看能不能用，再看怎么用）
### 5.1 为什么我的 API 调用失败了？
API 文档可以当成“菜单 + 说明书”：
常见错误：
<ApiDocumentDemo />
| 错误码 | 原因 | 解决方案 |
| :--- | :--- | :--- |
| **400** | 参数错误 | 检查参数名、类型、格式 |
| **401** | 未授权 | 检查 API Key 是否正确 |
| **404** | 接口不存在 | 确认 URL 是否正确 |
| **429** | 请求过于频繁 | 降低请求频率或联系提供方 |
| **500** | 服务器错误 | 稍后重试或联系技术支持 |
### 5.1 阅读 API 文档的 5 步
### 5.2 最佳实践
✅ **使用 API 时要注意**：
1. **阅读文档**：不要猜测，仔细看文档
2. **处理错误**：不要假设调用总是成功
3. **控制频率**：避免被限流（Rate Limit）
4. **保护密钥**：不要把 API Key 写在公开代码里
5. **缓存数据**：相同数据不要重复请求
❌ **常见错误**：
- 不看文档就盲目调用
- 不处理错误响应
- 密钥泄露到 GitHub
- 无限重试导致被封禁
1. **确认能力**：这个接口是不是你要的（做什么）
2. **确认怎么用**：网址/函数名 + 需要填什么
3. **确认参数**：必填/可选/默认值/类型
4. **确认返回**：字段含义、是否可能为空
5. **确认边界**：失败会怎样、太频繁会不会被拒绝
---
## 6. 总结与进阶
## 6. 实战：用“模拟 API”练出手感
恭喜你！现在你已经掌握了 API 的基础知识。
真实世界里你会用 Postman/curl/代码去调 API；这里我们用一个“不会被 CORS/网络干扰”的练习场，把核心手感练出来。
### 6.1 核心知识点回顾
<ApiPlayground />
- ✅ API 是软件之间的"服务员"和"桥梁"
- ✅ API 工作原理：请求 → 处理 → 响应
- ✅ HTTP 方法：GET（查）、POST（增）、PUT（改）、DELETE（删）
- ✅ API 文档包含：接口地址、参数、返回格式、错误码
- ✅ 调用 API 的五步法：找文档 → 理解功能 → 查参数 → 看示例 → 尝试调用
建议你按顺序试这几件事：
### 6.2 学习路线
1. **入门**（今天）
- 理解 API 的概念
- 会阅读简单的 API 文档
- 能用工具（Postman）调用 API
2. **进阶**（1 周）
- 在代码中调用 API
- 处理认证（API Key、OAuth）
- 处理分页、过滤等高级功能
3. **深入**（持续）
- 学习 GraphQL（REST 的替代方案）
- 设计自己的 API
- API 性能优化和安全
### 6.3 推荐资源
- **练习平台**：
- [JSONPlaceholder](https://jsonplaceholder.typicode.com/) - 假数据 API，用于练习
- [Public APIs](https://publicapis.dev/) - 收录了大量免费 API
- **文档工具**：
- [Postman](https://www.postman.com/) - API 调试工具
- [Swagger Editor](https://editor.swagger.io/) - API 文档编辑器
- **学习资料**：
- [REST API Tutorial](https://restfulapi.net/)
- [MDN Web API 文档](https://developer.mozilla.org/zh-CN/docs/Web/API)
1. 把 “登录/钥匙” 改成“没有” → 看看失败会怎么提示
2. 连续点击“调用” → 看看“太频繁会被拒绝”的提示
3. 选 POST 创建用户，把 Body 改成非法 JSON → 观察 400
4. 把用户 id 改成 `u_404` → 观察 404（资源不存在）
---
## 7. 名词速查表
## 7. 总结：一句话把三种“API”说清楚
| 名词 | 英文 | 解释 |
| :--- | :--- | :--- |
| **API** | Application Programming Interface | 应用程序编程接口，软件之间的"服务员" |
| **HTTP** | HyperText Transfer Protocol | 超文本传输协议，Web API 的基础 |
| **REST** | Representational State Transfer | 一种 API 设计风格，最常见 |
| **GET** | - | HTTP 方法，用于获取数据 |
| **POST** | - | HTTP 方法，用于创建数据 |
| **PUT** | - | HTTP 方法，用于更新数据 |
| **DELETE** | - | HTTP 方法，用于删除数据 |
| **Endpoint** | - | 接口地址，如 /users |
| **Request** | - | 请求，客户端发给服务器 |
| **Response** | - | 响应，服务器返回给客户端 |
| **JSON** | JavaScript Object Notation | 一种数据格式，API 常用 |
| **Authentication** | - | 认证，验证你是谁 |
| **Rate Limit** | - | 限流，控制请求频率 |
- **HTTP API**：通过网络调用（你发请求，它回结果）
- **SDK API**：通过库函数调用（你调函数，它内部帮你发请求）
- **库 API**：本地函数接口（不走网络）
它们共同点只有一个：**把“怎么用”写清楚**。
---
## 8. 名词速查表
> 不想背词也没关系：你只要会“看文档、会填参数、能看懂成功/失败”，就已经能开始用 API 了。
| 名词 | 英文 | 解释 |
| :--------- | :-------------------------------- | :---------------------------------------- |
| API | Application Programming Interface | 软件对外公开的接口/入口 |
| URL/地址 | - | 你要访问的“网址/路径” |
| 参数 | - | 你要告诉对方的信息（例如：id、页码） |
| 返回 | - | 对方给你的结果（数据或错误提示） |
| 状态码 | - | 成功/失败的数字提示（例如：200 表示成功） |
| Rate Limit | - | 限流/配额（常见 429） |