delorex/test-repo

Fork 0

Files

T

sanbuphy 7d86ba9504 feat: add interactive demos for AI history, Auth design, and Git intro

2026-01-19 11:25:10 +08:00

8.9 KiB

Raw Blame History

API 入门：软件世界的"服务员"

💡 学习指南：本章节无需编程基础，通过交互式演示带你深入了解 API（应用程序接口）。我们将从最基础的"什么是 API"讲起，到如何阅读 API 文档，再到实际调用 API。

0. 引言：无处不在的"桥梁"

你用微信登录第三方 APP 时，是谁在幕后传递信息？你在淘宝查询物流时，是谁帮你连接快递公司的数据？你用 AI 写代码时，是谁把你的需求传给大模型？

这背后都有一个功臣：API (Application Programming Interface)。

如果软件是"餐厅"，那 API 就是"服务员"。你需要什么（数据、功能），告诉服务员（调用 API），服务员会去厨房（服务器）取来，端到你面前（返回结果）。

0.1 为什么需要 API？

想象一下，如果没有服务员（API）：

❌ 每个顾客都要自己冲进厨房找菜
❌ 厨房会被搞乱，效率极低
❌ 顾客需要知道厨房怎么运作

有了服务员（API）：

✅ 顾客只需看菜单（API 文档）点餐
✅ 服务员传递订单，厨房专注做菜
✅ 顾客不需要知道厨房怎么运作

关键点：API 让不同软件之间能够"对话"，而不需要了解对方的内部实现。

1. 第一步：理解 API 的本质

1.1 什么是 API？

API (Application Programming Interface) = 应用程序编程接口。

翻译成人话：软件之间的"约定"和"服务员"。

Application（应用）：两个不同的软件系统（如你的 APP 和微信服务器）
Programming（编程）：通过代码来交互
Interface（接口）：双方约定的"沟通方式"

关键点：API 定义了：

你可以请求什么（有哪些功能）
怎么请求（格式、参数）
会返回什么（数据结构）

1.2 API 的类型

API 有很多种形式，最常见的有：

类型	例子	说明
Web API	REST API、GraphQL	通过 HTTP 协议调用，最常见
库 API	React、Vue	代码库提供的函数接口
系统 API	文件系统 API	操作系统提供的功能接口

本教程重点讲解 Web API，因为它最常用，也最容易理解。

2. API 是怎么工作的？

2.1 请求-响应模型

API 的工作原理就像"点餐-上菜"：

发起请求：你告诉服务员要什么（调用 API）
处理请求：服务员去厨房传达（服务器处理）
返回结果：服务员把菜端上来（返回数据）

2.2 HTTP 方法：四种基本操作

在 Web API 中，我们使用 HTTP 方法来表达不同的操作：

方法	作用	类比
GET	获取数据	"给我看看菜单"
POST	创建数据	"我要点这道菜"
PUT	更新数据	"把这道菜换成辣的"
DELETE	删除数据	"取消这道菜"

关键点：REST API 遵循"统一接口"原则，用这四种方法就能完成所有操作。

3. 认识 API 文档

3.1 什么是 API 文档？

API 文档就像餐厅的菜单，它告诉你：

📋 有哪些菜可以点（API 提供哪些功能）
💰 每个菜的名字和价格（接口地址、参数）
📝 菜的详细说明（返回数据格式）
⚠️ 注意事项（限制条件、错误码）

3.2 API 文档的组成

一个完整的 API 文档通常包含：

1️⃣ 基本信息

接口地址：https://api.example.com/users
请求方法：GET
功能说明：获取用户列表

2️⃣ 请求参数

参数名    类型    必填    说明
page      number  否      页码，默认 1
limit     number  否      每页数量，默认 20

3️⃣ 返回示例

{
  "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）
或者在代码中调用

4.2 真实案例：调用天气 API

让我们调用一个真实的天气 API 来查询北京的天气。

代码示例：

// 使用 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);
  });

# 使用 Python 调用 API
import requests

response = requests.get('https://api.weatherapi.com/v1/current.json', params={
    'key': 'YOUR_KEY',
    'q': 'Beijing'
})

data = response.json()
print(f"北京天气：{data['current']['temp_c']}°C")
print(f"天气状况：{data['current']['condition']['text']}")

5. 常见问题与最佳实践

5.1 为什么我的 API 调用失败了？

常见错误：

错误码	原因	解决方案
400	参数错误	检查参数名、类型、格式
401	未授权	检查 API Key 是否正确
404	接口不存在	确认 URL 是否正确
429	请求过于频繁	降低请求频率或联系提供方
500	服务器错误	稍后重试或联系技术支持

5.2 最佳实践

✅ 使用 API 时要注意：

阅读文档：不要猜测，仔细看文档
处理错误：不要假设调用总是成功
控制频率：避免被限流（Rate Limit）
保护密钥：不要把 API Key 写在公开代码里
缓存数据：相同数据不要重复请求

❌ 常见错误：

不看文档就盲目调用
不处理错误响应
密钥泄露到 GitHub
无限重试导致被封禁

6. 总结与进阶

恭喜你！现在你已经掌握了 API 的基础知识。

6.1 核心知识点回顾

✅ API 是软件之间的"服务员"和"桥梁"
✅ API 工作原理：请求 → 处理 → 响应
✅ HTTP 方法：GET（查）、POST（增）、PUT（改）、DELETE（删）
✅ API 文档包含：接口地址、参数、返回格式、错误码
✅ 调用 API 的五步法：找文档 → 理解功能 → 查参数 → 看示例 → 尝试调用

6.2 学习路线

入门（今天）
- 理解 API 的概念
- 会阅读简单的 API 文档
- 能用工具（Postman）调用 API
进阶（1 周）
- 在代码中调用 API
- 处理认证（API Key、OAuth）
- 处理分页、过滤等高级功能
深入（持续）
- 学习 GraphQL（REST 的替代方案）
- 设计自己的 API
- API 性能优化和安全

6.3 推荐资源

练习平台：
- JSONPlaceholder - 假数据 API，用于练习
- Public APIs - 收录了大量免费 API
文档工具：
- Postman - API 调试工具
- Swagger Editor - API 文档编辑器
学习资料：
- REST API Tutorial
- MDN Web API 文档

7. 名词速查表

名词	英文	解释
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	-	限流，控制请求频率

8.9 KiB Raw Blame History Unescape Escape