亲手调用一次真实 API
API 是程序之间约定好的请求入口。一次调用要同时看地址、方法、请求材料、状态码和响应正文。
- 完成一次公开 API 的成功调用和一次失败调用，并能根据请求与响应证据说明差别。
- URL、方法、请求头、请求体与 JSON 响应
- 验证亲手调用一次真实 API后，应当完成一次公开 API 的成功调用和一次失败调用，并能根据请求与响应证据说明差别，并保留状态码、响应结构、进程输出和前后端同一次请求作为可重复检查的依据。
- 完成 4.7「选择正确的前端部署方式」
FOUNDATION
必须理解
API（Application Programming Interface，应用程序编程接口）是程序之间交换能力与数据的约定。看懂请求和响应后，第三方服务与自己的后端都不再是只能复制代码的黑盒。
本课依次讲清URL、方法、请求头、请求体与 JSON 响应、GET、POST、状态码和接口文档和API Key、速率限制与费用边界，最后通过“用 fetch 写最小调用并分别显示加载、成功与错误”检查学习结果。
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();阅读亲手调用一次真实 API示例时，fetch 只在网络层失败时直接拒绝；404、500 仍需要通过 response.ok 或 status 判断。
- fetch 发出 GET 请求并等待 HTTP 响应。
- response.ok 覆盖 200 到 299；404 与 500 会进入主动抛出的错误分支。
- 只有确认成功后才解析 JSON，网络层失败则由外层 catch 处理。
成功地址得到可用 JSON；错误地址产生包含真实状态码的错误；断网时出现不同的网络异常，而不是虚构状态码。
AI COLLABORATION
AI 如何参与
在亲手调用一次真实 API这一课，AI 负责根据真实材料解释URL、方法、请求头、请求体与 JSON 响应并指出遗漏，学习者负责控制范围、执行修改和核对状态码、响应结构、进程输出和前后端同一次请求。
推荐协作顺序
- 1
先把官方 API 文档中的路径、方法和响应示例交给 AI。
- 2
让它只写一个最小成功调用，并逐项解释请求。
- 3
再给它一次真实失败响应，让它区分网络问题和 HTTP 错误。
以下是官方接口说明和我的最小需求。请只使用文档中出现的地址、方法和字段生成调用示例，同时处理超时与非成功状态。不要索取或展示任何密钥。最后列出我应在 Network 中核对的项目。
一对成功与失败请求示例，代码会先检查 response.ok，再解析或显示适当错误；亲手调用一次真实 API的人工验收必须回到真实页面、请求、终端、测试或数据结果，不能用 AI 的文字说明代替。
人工检查清单
- 确认示例 API 当前可访问、无需秘密，且 AI 没把 404 当成 fetch 抛出的网络异常。
- 要求 AI 的示例逐项对应当前官方文档中的地址、方法、字段和错误响应。
- 亲自制造一次成功、一次 HTTP 错误和一次网络失败，核对代码确实走入不同分支。
COMMON TRAPS
常见误区
下面三类问题会让任务看似完成，却经不起刷新、错误输入或真实环境检查。先看现象，再找原因和修正方法。
把密钥写进前端
- 你会看到
- 浏览器源码和请求中能看到凭证
- 为什么发生
- 浏览器必须下载并执行前端代码，所以其中的密钥对访问者完全可见。
- 怎样纠正
- 由受保护后端持有并调用
只处理成功响应
- 你会看到
- 错误正文被当作正常数据使用
- 为什么发生
- 网络正常不代表业务成功，错误状态和错误正文需要走独立分支。
- 怎样纠正
- 先检查网络和状态，再解析业务数据
脱离官方文档猜字段
- 你会看到
- 请求格式看似合理却持续失败
- 为什么发生
- 接口字段、认证方式和版本规则由提供方定义，名字相似并不能保证兼容。
- 怎样纠正
- 以当前官方说明和真实响应为准
HANDS-ON
动手任务
完成一次公开 API 的成功调用和一次失败调用，并能根据请求与响应证据说明差别。
- 完成 4.7「选择正确的前端部署方式」
跟着做
- 01
选择一个无需密钥、文档清楚的公开 API。
- 02
在浏览器或工具中完成一次 GET 请求。
- 03
记录 URL、方法、状态码、内容类型和一项 JSON 字段。
- 04
请求一个不存在资源，比较响应差异。
- 05
用 fetch 写最小调用并分别显示加载、成功与错误。
完成一次公开 API 的成功调用和一次失败调用，并能根据请求与响应证据说明差别。
为第三方 API 增加 5 秒超时提示，并解释超时与 500 的区别。
离开本课前，自问四件事
- 一个 HTTP API 请求由哪些部分组成，它们分别表达什么？
- HTTP 404 与断网对 fetch 来说有什么不同？
- 为什么 API Key 不能放进公开前端？
- 阅读接口文档时，我至少要确认哪些契约信息？
确认完成后，会同步更新学习中心的课程学习进度。