test-repo/docs/zh-cn/appendix/4-server-and-backend/api-intro.md

API 入门

👆 看见了吗？点一下按钮，230 毫秒后，一句格言就回来了。

这个过程，就是 API 调用。

---

说白了，API 就是"问一句，拿一笔"

你可能觉得"调用 API"是很高大上的操作。

其实吧，就像你去便利店买水——你说"来瓶可乐"，店员给你一瓶可乐。你问一句，他给一笔。

API 也是一样：

1. 你问（发送请求）
2. 别人答（服务器处理）
3. 你拿到（返回结果）

只不过这次，你问的不是店员，而是一台远在千里之外的电脑。

---

但 API 远不止"网络接口"

一提到 API，很多人觉得这是很高深的东西，离自己很远。

其实吧，你写代码的第一天就在用 API 了，只是你不知道而已。

函数，就是最基础的 API

length = len("hello")

len() 这个东西，你觉得它是什么？

它是个函数，没错。但同时，它也是 Python 给你留的一个 API。

什么意思呢？你不需要知道 len() 内部是怎么数字符串长度的，你不需要知道它是用 C 写的还是用 Python 写的，你只需要知道一件事——把字符串给我，我告诉你多长。

这就叫 API：我把复杂的东西藏起来，只给你一个简单的用法。

再看一个：

my_list = []
my_list.append("item")

append() 也是 API。背后可能是内存分配、指针移动、容量扩容...但你不用关心这些。你只需要说"给我加上去"，它就帮你搞定。

操作系统 API：让你的程序能"碰"硬件

当你在电脑上打开一个文件：

with open("file.txt", "r") as f:
    content = f.read()

这行代码背后，Python 其实在调用操作系统的 API。

Windows 有 Win32 API，Linux 有 POSIX API，macOS 有 Cocoa API。这些 API 是干嘛的？让程序能真正操作硬件——读写硬盘、显示窗口、播放声音。

没有操作系统 API，你的 Python 代码就是一堆文字，根本动不了硬盘里的文件。

第三方库的 API：站在巨人的肩膀上

当你用 NumPy 做矩阵运算：

import numpy as np
matrix = np.array([[1, 2], [3, 4]])
result = np.dot(matrix, matrix)

np.dot() 就是 NumPy 给你留的 API。背后可能是经过优化的 C++ 代码、多线程计算、SIMD 指令...但你只需要知道一件事——给我两个矩阵，我还你一个乘积。

这就是 API 的魅力：把别人的能力，变成你的能力。

Web API：跨越网络的"超能力"

最后，才是大多数人熟知的 Web API：

import requests

response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx"},
    json={"model": "deepseek-chat", "messages": [{"role": "user", "content": "你好"}]}
)

这行代码做了什么？

它让你的程序穿越互联网，调用了千里之外 DeepSeek 服务器上的 AI 模型。就像你打了个越洋电话，让大洋彼岸的厨师帮你做了一道菜。

Web API 的神奇之处就在于：它让"调用别人的超级电脑"变得像调用本地函数一样简单。

---

无论哪种 API，结构都一样

说了这么多，你可能发现了——不管哪种 API，它们的结构都是一样的。

就像插头和插座，怎么变都离不开三样东西：

要素	函数 API 的例子	Web API 的例子
地址/名称	len()	https://api.example.com/users
输入/参数	"hello"	{"name": "张三"}
输出/返回	5	{"id": 1}

---

调用服务器：你是在"问"还是在"做"？

好，现在你知道调用 API 需要地址和参数。

但还有个问题没说：你跟服务器说话的方式，不止一种。

什么意思？

想象你去一家餐厅：

场景	现实中你会怎么说？	对应的 API 方式
你想知道今天有什么菜	"服务员，菜单给我看看"	GET - 纯"问"，不改数据
你想点一份宫保鸡丁	"给我来份宫保鸡丁"	POST - "做"件事
你想换一道菜	"把宫保鸡丁改成糖醋里脊"	PUT - 替换数据
你不想要了	"算了，那道菜不要了"	DELETE - 删除数据

这就是 HTTP 方法的来历：不同的动词，对应不同的操作。

但最常用的就两个：GET 和 POST。其他的先不用管。

---

HTTP vs SDK：自己跑腿还是让管家代办？

既然教程的重点是 AI 编程，我们就重点讲讲 Web API——这是你和 AI 模型打交道的主要方式。

你在教程里经常会看到两种调用方式：HTTP 和 SDK。很多人会被绕晕，其实很简单，就是**"自己跑腿"和"让管家代办"**的区别。

HTTP API：自己跑腿

这是最原始的方式。就像你自己去餐厅，从头开始点菜。

所有编程语言都能用，甚至你在浏览器地址栏里敲一行字也是一种 HTTP 请求。

SDK：让管家代办

SDK (Software Development Kit) 就像是餐厅派给你的专属管家。

你不需要自己填单子、贴邮票。你只需要跟管家说"来份宫保鸡丁"，管家会自己在后台帮你填单子、发请求、处理报错。

能用 SDK 就用 SDK，把麻烦事留给别人，把时间留给自己。

怎么看 API 文档？

文档就像说明书和菜单的结合体。你不需要从头读到尾，只需要学会查字典。

打开任何一个 API 文档（比如 OpenAI 或 DeepSeek），你只需要找这几样东西：

1. Base URL：根地址（餐厅在哪？）
2. Authentication：怎么证明你是会员？（通常是 Authorization: Bearer sk-...）
3. Endpoints：具体的接口列表
   • /v1/chat/completions -> 对话（最常用的）
   • /v1/images/generations -> 画图
4. Parameters：必填项有哪些？

常见的"餐厅黑话"（状态码）

服务员（API）回复你的时候，通常会先喊一个数字代码：

状态码	含义
200 OK	成功了
400 Bad Request	你填错了
401 Unauthorized	没权限
404 Not Found	地址错了
429 Too Many Requests	你点太快了
500 Internal Server Error	对方服务器崩了

---

练手场：弄坏它也没关系

光说不练假把式。这里有个模拟 API，你可以随便填参数、随便改地址，看看会发生什么。

试着触发一下 401（假装没带钱）或者 404（瞎填地址）。

---

总结

别把 API 想得太复杂。在 AI 编程的时代，你只需要记住这几件事：

1. API 就是传声筒，帮你把话传给 AI 模型
2. 你早就用过 API了，从 len() 到 open()
3. Web API 是超能力，让你调用千里之外的超级电脑
4. SDK 是好管家，能用管家就别自己跑腿
5. 看文档找三样：地址、密钥、参数

这就够了。剩下的，交给 IDE 去写吧。

---

名词速查表 (Glossary)

名词	全称	解释
API	Application Programming Interface	应用程序编程接口，定义了软件之间如何交互
Web API	-	基于 HTTP 协议的 API，用于网络通信
Endpoint	-	端点，API 的具体地址
HTTP	HyperText Transfer Protocol	Web API 使用的通信协议
GET	-	获取资源的方法
POST	-	提交数据的方法
SDK	Software Development Kit	软件开发工具包，封装了底层 API 调用
URL	Uniform Resource Locator	API 的网络地址
JSON	JavaScript Object Notation	常用的数据格式
Authentication	-	验证身份的过程
Status Code	-	HTTP 响应中的状态码
Request	-	请求
Response	-	响应
Header	-	HTTP 头，包含元信息
Payload	-	请求或响应的实际数据
Rate Limit	-	速率限制