亲手调用一次真实 API
API 是程序之间按约定交换请求和响应的入口。亲手调用一次，比背定义更容易形成直觉。
- 能读懂一份基础 API 文档并完成一次可验证调用。
- URL、方法、请求头、请求体与 JSON 响应
- 使用一个无需密钥的公开 API，记录请求与响应；再写出失败时应该如何处理。
- 完成 4.6「选择正确的前端部署方式」
FOUNDATION
必须理解
API 是程序之间按约定交换请求和响应的入口。亲手调用一次，比背定义更容易形成直觉。
API（Application Programming Interface，应用程序编程接口）是程序之间交换能力与数据的约定。看懂请求和响应后，第三方服务与自己的后端都不再是只能复制代码的黑盒。
API 像餐厅点单规则：菜单列出可点项目，订单包含菜名和要求，厨房按规则处理，再返回成功菜品或明确错误。顾客不能直接进入厨房改库存。
任务应用向 GET /api/tasks 请求任务列表，向 POST /api/tasks 发送新标题；服务器用 JSON 返回任务或错误信息。
URL、方法、请求头、请求体与 JSON 响应
一次 API 请求里，URL 告诉服务器你找什么，HTTP 方法说明想做什么，请求头带格式或身份信息，请求体则装着要提交的数据。JSON 是最常见的文本数据格式之一。
基础概念
API（Application Programming Interface，应用程序编程接口）是程序之间按约定请求能力或数据的边界。一次 HTTP API 请求由 URL、方法、请求头和可选请求体组成，响应常用 JSON 表示结构化数据。
进一步理解
URL 指向资源位置，方法表达读取或修改意图，请求头携带内容类型、认证等元信息，请求体承载要提交的数据。服务器按接口契约解析并回应。
JSON 只有字符串、数字、布尔值、null、数组和对象等数据结构，不包含 JavaScript 函数；日期通常作为约定格式的字符串传输。
前端向 `/api/tasks` 发送带标题的 JSON，请求头声明 `application/json`；服务器创建记录并返回包含 id、title、done 的 JSON。
API 不等于后端全部代码，也不等于某个 URL 字符串。它包含可调用入口及其输入、输出、错误和权限约定。
这一小节记住：调用 API 就是在明确地址上按明确格式提出请求，并按约定解释响应。
GET、POST、状态码和接口文档
GET 通常用来读取，POST 常用来创建。状态码先给出结果大类，响应正文再放真正的数据或错误细节；前端两边都要看。
基础概念
GET 通常用于读取，POST 常用于创建或触发处理。HTTP 状态码描述请求结果类别，接口文档则记录每个端点的契约、示例与限制。
进一步理解
2xx 表示请求被成功处理，4xx 表示请求、认证或目标有问题，5xx 表示服务端未按预期完成。正文继续给出数据或稳定错误信息。
`fetch` 收到 404 或 500 时仍然完成了一次 HTTP 往返，通常不会自动抛出网络异常；调用方需要检查 `response.ok` 或 status。
GET `/api/tasks/404` 可能得到 404 和 `{error:'任务不存在'}`；断网则没有 HTTP 响应，两种失败的提示与重试策略不同。
GET 与 POST 不是“有参数”和“没参数”的区别，状态码也不能由前端随意猜；要以接口文档和真实响应为准。
这一小节记住：先看文档确定契约，再同时处理成功响应、HTTP 错误和网络失败。
API Key、速率限制与费用边界
API Key 相当于服务给你的调用凭证，常常直接关联权限、次数和费用。它不能出现在公开前端，也不要提交进仓库。
基础概念
API Key 是服务识别调用项目或账户的凭证，速率限制约束一定时间内的调用量，费用边界决定使用量如何计费。三者共同限制外部 API 的使用。
进一步理解
密钥通常关联权限与账单，必须存放在服务端秘密配置。浏览器前端的源码、请求和打包变量都能被用户查看，无法安全保存通用密钥。
调用方还要处理 401/403 鉴权失败、429 限流、超时和配额耗尽，并设置预算、重试上限与监控。
任务应用由自己的后端读取第三方 AI 密钥并发起请求，前端只调用自己的受控接口；后端为每个用户限制频率。
隐藏按钮、混淆字符串或把密钥放进前端环境变量都不是保密；只要浏览器需要发送它，访问者就能取得。
这一小节记住：外部 API 不只是代码调用，还包含凭证、限流、费用与失败责任。
- 把示例地址替换成真实、无需密钥且文档明确的 API。
- 代码运行环境支持 fetch，并准备显示或记录捕获到的错误。
const response = await fetch("https://api.example.com/tasks");
if (!response.ok) {
throw new Error(`请求失败：${response.status}`);
}
const data = await response.json();fetch 只在网络层失败时直接拒绝；404、500 仍需要通过 response.ok 或 status 判断。
- fetch 发出 GET 请求并等待 HTTP 响应。
- response.ok 覆盖 200–299；404 与 500 会进入主动抛出的错误分支。
- 只有确认成功后才解析 JSON，网络层失败则由外层 catch 处理。
成功地址得到可用 JSON；错误地址产生包含真实状态码的错误；断网时出现不同的网络异常，而不是虚构状态码。
AI COLLABORATION
AI 如何参与
让 AI 根据官方文档生成最小调用示例，但密钥只放环境变量，绝不粘贴进对话或代码。
推荐协作顺序
- 1
先把官方 API 文档中的路径、方法和响应示例交给 AI。
- 2
让它只写一个最小成功调用，并逐项解释请求。
- 3
再给它一次真实失败响应，让它区分网络问题和 HTTP 错误。
我是 API 初学者。请用无需密钥的公开 API 演示一次 GET 请求，逐项解释 URL、方法、请求头、状态码和 JSON 响应。再给一个不存在资源的失败调用，说明前端应如何区分网络失败与 HTTP 错误。
一对成功与失败请求示例，代码会先检查 response.ok，再解析或显示适当错误。
人工检查清单
- 确认示例 API 当前可访问、无需秘密，且 AI 没把 404 当成 fetch 抛出的网络异常。
- 要求 AI 的示例逐项对应当前官方文档中的地址、方法、字段和错误响应。
- 亲自制造一次成功、一次 HTTP 错误和一次网络失败，核对代码确实走入不同分支。
COMMON TRAPS
常见误区
错误不是需要隐藏的失败，而是帮助你看清系统边界的证据。下面三类问题在 AI 辅助学习中最常出现。
只复制请求代码，不看文档
- 你会看到
- 接口路径、字段或版本已经变化，代码却还在猜旧格式。
- 为什么发生
- 示例代码可能针对旧版本或不同端点，脱离官方契约复制后，字段与认证方式很容易已经变化。
- 怎样纠正
- 先从官方文档确认契约，再让 AI 帮你转换成代码。
把 API Key 写进前端
- 你会看到
- 密钥随着浏览器代码一起发给所有访问者。
- 为什么发生
- 浏览器必须拿到前端代码和请求细节，因此任何放进去的通用密钥都等同于交给访问者。
- 怎样纠正
- 需要密钥的调用放在服务端，密钥存进服务端环境变量。
只处理成功响应
- 你会看到
- API 返回 404 或 429，页面仍然尝试使用不存在的数据。
- 为什么发生
- 只写成功分支会让限流、未授权和服务异常被当成有效数据继续使用，错误扩散到界面。
- 怎样纠正
- 先检查状态码，再分别处理限流、未找到和服务异常。
HANDS-ON
动手任务
使用一个无需密钥的公开 API，记录请求与响应；再写出失败时应该如何处理。
- 完成 4.6「选择正确的前端部署方式」
跟着做
- 01
选择一个无需密钥、文档清楚的公开 API。
- 02
在浏览器或工具中完成一次 GET 请求。
- 03
记录 URL、方法、状态码、内容类型和一项 JSON 字段。
- 04
请求一个不存在资源，比较响应差异。
- 05
用 fetch 写最小调用并分别显示加载、成功与错误。
能读懂一份基础 API 文档并完成一次可验证调用。
为第三方 API 增加 5 秒超时提示，并解释超时与 500 的区别。
离开本课前，自问四件事
- 一个 HTTP API 请求由哪些部分组成，它们分别表达什么？
- HTTP 404 与断网对 fetch 来说有什么不同？
- 为什么 API Key 不能放进公开前端？
- 阅读接口文档时，我至少要确认哪些契约信息？
确认完成后，会同步更新学习中心的课程学习进度。