sanbuphy
149 lines
5.2 KiB
Markdown
149 lines
5.2 KiB
Markdown
# 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） |
|