sanbuphy
5.2 KiB
API 入门（0 基础版）
💡 学习指南：这是写给 0 基础新手的。你先记住一句话：API 就是“别的软件给你用的按钮/入口”。你按它的规则“提交信息”，它按规则“把结果给你”。
0. 引言：你真正依赖的不是“服务器”，而是“接口”
当你说“我要调一下接口”，你其实是在说：
我希望按某种约定把输入交给对方系统，然后按约定拿到输出（成功或失败）。
这份“约定”就是 API。
你可以先把 API 当成一句大白话：
API = 别的软件给你用的“入口”：你按它说的来，它把结果给你。
1. 什么是 API？（新手版一句话）
API 可以翻译成：应用之间的“接口/入口”。
对新手来说，你只要先记住 3 件事（够用了）：
- 怎么用它（入口是什么：一个网址 / 一个函数名）
- 要填什么（你要告诉它哪些信息）
- 会得到什么（成功给你什么；失败会怎么提示）
1.1 API 不等于“实现”
API 只描述“怎么用”，不描述“怎么做”。
比如一个“获取用户信息”的 API，调用方需要知道：
- 你要带用户 id 吗？
- 你要不要带 Token？
- 成功返回什么字段？
- 用户不存在会返回什么错误？
但调用方不需要知道：
- 用户表怎么设计
- 服务拆成几个微服务
- 缓存怎么做
把实现细节藏起来，让双方能各做各的，这就是 API 的价值。
2. 为什么 HTTP 调用可以叫 API？
因为用“网址发请求”本身就像按一个按钮：你把信息发过去，对方把结果回给你。（这类通常就叫 HTTP API）
你不用记复杂的术语，先看流程就够了：发过去 → 对方处理 → 回给你。
一句话总结：HTTP API 就是“用网址去叫别人做事”。
3. 为什么 SDK 的调用接口也叫 API？
因为 SDK 本质上也是一个“工具包/库”。它对外公开的函数/方法，本来就可以叫 API（入口）。
同时，很多 SDK 会在背后帮你调用 HTTP API（还会顺便帮你处理：加“钥匙”、失败重试、把数据整理成好用的样子），所以大家会同时说：
- “这个服务的 API”（通常指 HTTP 接口）
- “这个 SDK 的 API”（通常指库里的函数接口）
4. （选读）GET/POST 这些词到底在说什么？
新手可以先跳过这一节：你只要先学会“看文档、会调用”就够用了。
点我展开：进阶一点点（但我尽量讲人话）
这节想讲的只有一件事：有些请求“重试很安全”（比如 GET），有些“重试可能出事”（比如创建接口）。
5. 怎么读 API 文档？（先看能不能用，再看怎么用）
API 文档可以当成“菜单 + 说明书”：
5.1 阅读 API 文档的 5 步
- 确认能力：这个接口是不是你要的（做什么）
- 确认怎么用：网址/函数名 + 需要填什么
- 确认参数：必填/可选/默认值/类型
- 确认返回：字段含义、是否可能为空
- 确认边界：失败会怎样、太频繁会不会被拒绝
6. 实战：用“模拟 API”练出手感
真实世界里你会用 Postman/curl/代码去调 API；这里我们用一个“不会被 CORS/网络干扰”的练习场，把核心手感练出来。
建议你按顺序试这几件事：
- 把 “登录/钥匙” 改成“没有” → 看看失败会怎么提示
- 连续点击“调用” → 看看“太频繁会被拒绝”的提示
- 选 POST 创建用户，把 Body 改成非法 JSON → 观察 400
- 把用户 id 改成
u_404→ 观察 404（资源不存在）
7. 总结：一句话把三种“API”说清楚
- HTTP API：通过网络调用（你发请求，它回结果）
- SDK API：通过库函数调用（你调函数，它内部帮你发请求）
- 库 API：本地函数接口（不走网络）
它们共同点只有一个：把“怎么用”写清楚。
8. 名词速查表
不想背词也没关系：你只要会“看文档、会填参数、能看懂成功/失败”，就已经能开始用 API 了。
| 名词 | 英文 | 解释 |
|---|---|---|
| API | Application Programming Interface | 软件对外公开的接口/入口 |
| URL/地址 | - | 你要访问的“网址/路径” |
| 参数 | - | 你要告诉对方的信息（例如：id、页码） |
| 返回 | - | 对方给你的结果（数据或错误提示） |
| 状态码 | - | 成功/失败的数字提示（例如：200 表示成功） |
| Rate Limit | - | 限流/配额（常见 429） |