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

# API 入门（0 基础版）

> 💡 **学习指南**：这是写给 0 基础新手的。你先记住一句话：**API 就是“别的软件给你用的按钮/入口”**。你按它的规则“提交信息”，它按规则“把结果给你”。

<ApiQuickStartDemo />

---

## 0. 引言：你真正依赖的不是“服务器”，而是“接口”

当你说“我要调一下接口”，你其实是在说：

> 我希望<strong>按某种约定</strong>把输入交给对方系统，然后<strong>按约定</strong>拿到输出（成功或失败）。

这份“约定”就是 API。

你可以先把 API 当成一句大白话：

> API = 别的软件给你用的“入口”：你按它说的来，它把结果给你。

---

## 1. 什么是 API？（新手版一句话）

**API** 可以翻译成：**应用之间的“接口/入口”**。

对新手来说，你只要先记住 3 件事（够用了）：

1. **怎么用它**（入口是什么：一个网址 / 一个函数名）
2. **要填什么**（你要告诉它哪些信息）
3. **会得到什么**（成功给你什么；失败会怎么提示）

<ApiConceptDemo />

### 1.1 API 不等于“实现”

API 只描述“怎么用”，不描述“怎么做”。

比如一个“获取用户信息”的 API，调用方需要知道：

- 你要带用户 id 吗？
- 你要不要带 Token？
- 成功返回什么字段？
- 用户不存在会返回什么错误？

但调用方不需要知道：

- 用户表怎么设计
- 服务拆成几个微服务
- 缓存怎么做

把实现细节藏起来，让双方能**各做各的**，这就是 API 的价值。

---

## 2. 为什么 HTTP 调用可以叫 API？

因为用“网址发请求”本身就像按一个按钮：你把信息发过去，对方把结果回给你。（这类通常就叫 HTTP API）

你不用记复杂的术语，先看流程就够了：**发过去 → 对方处理 → 回给你**。

<RequestResponseFlow />

一句话总结：HTTP API 就是“用网址去叫别人做事”。

---

## 3. 为什么 SDK 的调用接口也叫 API？

因为 SDK 本质上也是一个“工具包/库”。它对外公开的函数/方法，本来就可以叫 API（入口）。

同时，很多 SDK 会在背后帮你调用 HTTP API（还会顺便帮你处理：加“钥匙”、失败重试、把数据整理成好用的样子），所以大家会同时说：

- “这个服务的 API”（通常指 HTTP 接口）
- “这个 SDK 的 API”（通常指库里的函数接口）

<RealWorldApiDemo />

---

## 4. （选读）GET/POST 这些词到底在说什么？

新手可以先跳过这一节：你只要先学会“看文档、会调用”就够用了。

<details>
<summary>点我展开：进阶一点点（但我尽量讲人话）</summary>

<ApiMethodDemo />

这节想讲的只有一件事：有些请求“重试很安全”（比如 GET），有些“重试可能出事”（比如创建接口）。

</details>

---

## 5. 怎么读 API 文档？（先看能不能用，再看怎么用）

API 文档可以当成“菜单 + 说明书”：

<ApiDocumentDemo />

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

1. **确认能力**：这个接口是不是你要的（做什么）
2. **确认怎么用**：网址/函数名 + 需要填什么
3. **确认参数**：必填/可选/默认值/类型
4. **确认返回**：字段含义、是否可能为空
5. **确认边界**：失败会怎样、太频繁会不会被拒绝

---

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

真实世界里你会用 Postman/curl/代码去调 API；这里我们用一个“不会被 CORS/网络干扰”的练习场，把核心手感练出来。

<ApiPlayground />

建议你按顺序试这几件事：

1. 把 “登录/钥匙” 改成“没有” → 看看失败会怎么提示
2. 连续点击“调用” → 看看“太频繁会被拒绝”的提示
3. 选 POST 创建用户，把 Body 改成非法 JSON → 观察 400
4. 把用户 id 改成 `u_404` → 观察 404（资源不存在）

---

## 7. 总结：一句话把三种“API”说清楚

- **HTTP API**：通过网络调用（你发请求，它回结果）
- **SDK API**：通过库函数调用（你调函数，它内部帮你发请求）
- **库 API**：本地函数接口（不走网络）

它们共同点只有一个：**把“怎么用”写清楚**。

---

## 8. 名词速查表

> 不想背词也没关系：你只要会“看文档、会填参数、能看懂成功/失败”，就已经能开始用 API 了。

| 名词       | 英文                              | 解释                                      |
| :--------- | :-------------------------------- | :---------------------------------------- |
| API        | Application Programming Interface | 软件对外公开的接口/入口                   |
| URL/地址   | -                                 | 你要访问的“网址/路径”                     |
| 参数       | -                                 | 你要告诉对方的信息（例如：id、页码）      |
| 返回       | -                                 | 对方给你的结果（数据或错误提示）          |
| 状态码     | -                                 | 成功/失败的数字提示（例如：200 表示成功） |
| Rate Limit | -                                 | 限流/配额（常见 429）                     |