Files

T

sanbuphy 506585c15c docs(extra2): rewrite api documentation with clearer explanations and examples

Restructure the API documentation to use more intuitive analogies and practical examples. Focus on explaining core concepts like request/response cycles and real-world API usage patterns. Simplify technical details while maintaining accuracy, and add concrete code examples for both Python and JavaScript implementations.

Update the roadmap in README.md to reflect current priorities and reorder tasks based on feedback.

2026-01-01 02:32:31 +08:00

9.8 KiB

Raw Blame History

扩展知识 2 - API 开发手册：从核心逻辑到 AI 场景集成

随着数字化进程的加速，我们每天都在与成百上千个软件系统打交道。但对于初学者来说，一个始终绕不开的困惑是：这些看起来互不相干的应用，到底是怎么“对话”的？ 为什么我在这个 App 里点一下，另一个 App 就能立刻做出反应？

面对这种困惑，最直观的做法或许是“临时抱佛脚”：遇到需求再搜索具体的函数调用或者是网络协议，对照文档进行处理。看到图片需求就想到图像生成，碰到文本任务就找来大模型，再在海量接口中货比三家。然而，把零散的接口堆在一起，与在应用开发中系统性地规划、选型和组合 API 能力，是两件截然不同的事情。仅靠临时查资料与经验判断，会带来认知碎片化、方案设计随意、接口复用困难等一系列严峻挑战。

为了解决这些痛点，本篇手册以“API 核心逻辑”为整理思路。在这本手册里，我们想做的不是堆名词，而是帮你快速搞清楚三件事：“这件事可以用什么 API 做？它的本质逻辑是什么？接下来该怎么安全地调用它？” 通过从生活类比到代码实践的系统梳理，我们将为你揭开 API 的神秘面纱，帮你建立起从“逻辑认知”到“场景映射”再到“代码实现”的完整链路。

由于 内容较多 ，你可以在实践过程中遇到场景不知道如何选型的问题再查阅手册寻找参考；推荐你根据具体应用方向，让 AI 参考该手册，给出可参考的模型选型建议、方案 API 调用建议即可。

如果你只想了解对应的类别，不想看具体内容，只需要看每个大章节的初始段内容即可，例如 1 、2 的内容，但不需要看 5.1 或者 5.2 的代码细节。

推荐本手册只在需要时查阅对应部分或只浏览一级目录部分，若有兴趣再浏览全文。

之后更新会在每个章节部分，推荐可尝试使用的模型 API 服务地址。

本节课你将学到

核心概念映射：通过“电源插座”与“餐厅点餐”等经典类比，建立对 API 请求与响应循环的直观理解。
现实场景解析：了解天气、地图、社交登录及大语言模型等主流 API 的工作原理，掌握从“功能”到“接口”的映射方法。
代码实践与安全：掌握 Python 环境下 AI API 的调用方式，并理解前端开发中后端代理等安全工程实践的重要性。

完成本手册的学习后，你将对主流 API 能力建立起入门级的系统化认知，不仅知道“市面上有哪些接口、常配哪些产品”，更能理解它们在整体架构中的位置和相互关系。知道在面对具体业务需求时，如何快速定位所需能力、做出有依据的选型，为构建 AI 应用体系打下坚实基础。

1. 什么是 API？—— 从墙上的插座说起

API 的全称是 Application Programming Interface（应用程序编程接口），听起来很硬核，但我们可以把它想象成你墙上的电源插座。

当你把手机充电器插进插座时，你并不需要知道远处的发电厂是在烧煤还是在用风力发电，也不需要理解复杂的电网是怎么把电输送到你家的。对你来说，电厂就是一个“黑盒子”。你唯一关心的就是这个插座：只要你的插头尺寸对得上（符合标准），一插进去，电就来了。

在这个例子中，你的手机就是“客户端”（程序），发电厂是“服务器”（另一个服务），而墙上的插座就是 API。它是一个预先定义好的、标准的“连接点”。它把复杂的内部逻辑屏蔽在墙后面，只给你留下一个简单的接口，让你能轻而易举地获取原本非常复杂的功能或数据。

2. 为什么 API 如此重要？

正因为有了这些“插座”，现代技术的创新才变得如此迅速。开发者不需要从头去研究如何发电（比如画地图、写支付系统），只需要调用现成的 API，就能像搭积木一样快速构建出功能强大的应用。这不仅节省了巨大的开发成本，还让自动化成了可能——比如让系统自动处理重复性工作，同步数据或发送通知，把人类从琐碎的劳动中解放出来。同时，API 还充当了安全守门人的角色，确保只有合法的插头（请求）才能接通，让企业可以放心地使用第三方提供的尖端服务。

3. API 是如何工作的？

如果说电源插座是解释“接口”概念的基础版，那 API 的实际运作动态更像是在餐厅点餐。

在这个比喻中，你（客户端）坐下看菜单，决定了要吃什么。这时候，服务员（API）走了过来，记下你的需求，然后转身跑向厨房（服务器）。厨房里的大厨根据订单开始忙碌，做出一盘精美的菜肴。最后，服务员再次现身，把食物端到你面前。

在这个过程中，API 请求就像是你的订单。它包含了你想访问的“端点”（菜名）、你想做的动作（是获取数据还是提交信息）以及具体的参数（比如只要伦敦的天气）。而 API 响应 则是服务员带回的结果，其中包含了告诉你是否成功的“状态码”（比如 200 代表大功告成）以及你真正想要的“响应体”数据。

4. 现实世界的例子：我们身边的“服务窗口”

API 无处不在，在后台默默工作。

天气预报 API 它就像一个专门提供气象信息的窗口。你的天气应用向它发送坐标和密钥，它就回传一串 JSON 数据。

一个简单的“请求”示例：
- Endpoint: /current-weather
- Parameters: city=London & apiKey=your_access_key

“响应”（回传的数据）：

{
  "city": "London",
  "temperature": "15°C",
  "condition": "Cloudy",
  "humidity": "70%"
}

应用拿到这些数据后，再把它们漂亮地展示在你的手机屏幕上。

地图服务 API 不管是外卖平台还是打车软件，它们本身并不生产地图。它们通过调用高德或 Google Maps 的 API，就能获得精准的路线规划和导航功能。

一个简单的“请求”示例：
- Endpoint: /directions
- Parameters: origin=Eiffel Tower & destination=Louvre Museum & mode=driving

“响应”（回传的数据）：

{
  "total_distance": "4.5 kilometers",
  "estimated_time": "15 minutes",
  "route_steps": [
    "1. Head east on Champ de Mars...",
    "2. Turn left onto Quai Branly...",
    "..."
  ]
}

通过这些数据，应用就能在地图上绘制路线并提供导航指令。

社交媒体登录 API 当你点击“使用 Google 登录"时，购物应用会问 Google API：“这个用户是谁？”Google 验证后告诉应用：“他是 John Doe”。这样，你不用输入密码就能安全登录。

大语言模型 API（AI 的超级大脑） 这是目前最火的“万能插座”。你传过去一段话，它就能回传一段有逻辑的回复。开发者不需要自己训练大模型，只需要接通 OpenAI 或 DeepSeek 的 API，就能让自己的应用瞬间变聪明。

5. 在代码中，API 长什么样？

当你真正开始动手写代码时，会遇到一些技术名词。别担心，你不需要现在就记住所有细节，只需要看看它们在代码里是怎么“呼吸”的。

5.1 Python 中的 AI 调用

在 Python 中调用 OpenAI 的 API 非常直观。你可以通过设置 base_url 来指定服务器地址。

import openai

openai.api_key = "YOUR_OPENAI_API_KEY"
# 如果使用第三方代理或 DeepSeek 等兼容接口，可以修改 base_url
# openai.base_url = "https://api.deepseek.com/v1/"

response = openai.ChatCompletion.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "你是一个得力的助手。"},
        {"role": "user", "content": "你好，怎么使用 API？"}
    ]
)

print(response.choices[0].message["content"])

许多模型（如 DeepSeek）都兼容 OpenAI 的格式。你只需要更换 API 密钥和地址，就能无缝切换。

5.2 前端开发中的安全实践

如果你在做网页，切记不要在浏览器代码里直接写 API 密钥，否则会被人偷走。通常的做法是写一个后端代理，让服务器去替你完成调用。

// 后端 Node.js 示例
const express = require("express");
const axios = require("axios");
const app = express();
app.use(express.json());

app.post("/api/chat", async (req, res) => {
  try {
    const response = await axios.post(
      "https://api.openai.com/v1/chat/completions",
      {
        model: "gpt-3.5-turbo",
        messages: [{ role: "user", content: req.body.message }]
      },
      {
        headers: { "Authorization": `Bearer ${process.env.OPENAI_API_KEY}` }
      }
    );
    res.json({ reply: response.data.choices[0].message.content });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3001, () => console.log("服务器运行在 3001 端口"));

你可以使用 curl 命令来测试这个接口：

curl -X POST http://localhost:3001/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"你好，请问你是谁？"}'

6. 开启你的 API 之旅

API 是现代数字世界的基石。通过理解“请求与响应”这个简单的逻辑，你已经迈出了通往软件开发广阔世界的第一步。在接下来的 Z.ai 探索中，我们将亲手尝试这些调用，感受 AI API 的魅力。

参考资料

Postman: What is an API?

9.8 KiB Raw Blame History Unescape Escape