阅读完本节后，你将会收获：
- 掌握 API 集成的完整流程
- 理解 SDK 与直接 HTTP 请求的区别
- 学会安全地管理 API 密钥
- 掌握常见错误处理方法
- 了解限流和超时的处理策略
集成外部 API 是扩展应用能力的常见方式，如接入 AI 能力、地图服务等。
就像你需要身份证才能入住酒店一样，使用 API 也需要证明你的身份。这个身份证明就是 API Key。
获取 API Key 的过程通常很简单：
API Key 就像你的银行卡密码——一旦泄露，别人就能冒充你使用服务，甚至花光你的额度。所以：
拿到 API Key 后，你需要决定如何调用 API。有两种方式：SDK 和 直接 HTTP 请求。
| 方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| SDK | 官方封装、类型完善、文档齐全 | 需要安装依赖 | 大多数情况 |
| HTTP 请求 | 无依赖、轻量 | 需要手写协议处理 | 简单调用或无 SDK |
什么是 SDK？
SDK（Software Development Kit，软件开发工具包）是官方提供的封装库。它把你需要手动处理的底层操作（如 HTTP 请求、JSON 序列化、错误处理、超时重试等）都封装成简单的函数调用。你只需要调用 generateText() 这样的方法，SDK 内部会帮你完成所有复杂的网络交互。
官方 SDK 自带完善的 TypeScript 类型定义。这相当于给 AI 提供了一份详细的"代码地图"——它能准确知道有哪些功能、参数怎么填、返回值是什么。这比让 AI 仅凭 HTTP 文档推断参数和返回值更精确。
对于 AI 应用，推荐使用 Vercel AI SDK。它提供 @ai-sdk/openai-compatible 包，专门用于对接实现 OpenAI API 格式的服务商。由于 OpenAI 的 API 设计已成为行业事实标准，大多数模型服务商（包括国内）都选择兼容其接口格式——在请求结构、响应字段、鉴权方式等方面保持一致。这意味着开发者只需学习一套 API 规范，修改 baseURL、API Key 和模型名称即可调用全球主流大模型，无需为每个模型学习不同的 SDK。
你拿到了 API Key，现在需要把它安全地存放在代码中。直接把 Key 写在代码里是大忌——任何能看到代码的人都能拿走它。
正确的做法是使用环境变量：
# .env 文件
AI_API_KEY=sk-xxx # API 密钥
AI_BASE_URL=https://api.openai.com/v1 # API 基础地址
AI_MODEL=your-model-name # 模型名称（如 gpt-4o-mini、glm-4-plus 等）环境变量就像是代码和密钥之间的"防火墙"：
.env 文件不提交到 GitNext.js 项目中，.env.local 文件用于存储本地开发的环境变量。部署到生产环境时，在部署平台的设置中配置相同的环境变量即可。
配置好 SDK 和 API Key 后，你可能会迫不及待地想开始写业务功能。但等等——先写一个最简单的测试。
为什么？因为如果你直接写复杂功能，一旦出问题，你不知道是配置错了、Key 无效了、还是代码逻辑有问题。而一个最简单的测试，只需要验证一件事：我能连上 API 吗？
这个测试代码只需要做一件事：调用一次 API，看能否收到返回结果。如果成功了，说明你的配置是正确的，可以继续开发。如果失败了，AI 能根据错误信息帮你快速定位问题。
配置好 SDK 和 API Key 后，不要急着写业务功能，先写一个最简单的测试：
// 测试 API 连接
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';
// 创建客户端实例
const client = createOpenAICompatible({
name: 'my-provider',
apiKey: process.env.AI_API_KEY,
baseURL: process.env.AI_BASE_URL,
});
async function testConnection() {
const { text } = await generateText({
model: client.chatModel(process.env.AI_MODEL!), // 从环境变量读取模型名称
prompt: '你好，请回复"连接成功"',
});
console.log(text);
}
testConnection();测试要点：
createOpenAICompatible 创建客户端，传入 apiKey 和 baseURLgenerateText 发送简单的测试消息chatModel() 中填入模型名称（从环境变量读取或硬编码）如果测试成功，说明：
如果测试失败，AI 会根据错误信息帮你排查：
等测试通过了，不要急着继续开发。先把 API 的官方文档保存下来，方便后续查阅。
为什么？因为下次你让 AI 写相关功能时，如果直接把官方文档喂给它，它就能精准地写出调用代码。否则你可能需要反复解释各种参数和细节。
推荐做法：
文档存放位置建议：
docs/
├── api-references/
│ ├── openai-api.md # 官方文档存档
│ ├── aliyun-qwen-api.md # 官方文档存档
│ └── my-cheatsheet.md # 个人整理的速查表速查表示例（my-cheatsheet.md）：
# API 速查表
## 环境变量
- AI_API_KEY
- AI_BASE_URL
- AI_MODEL
## 官方文档链接
- [OpenAI API](https://platform.openai.com/docs)
- [阿里云通义千问](https://help.aliyun.com/zh/model-studio/)官方文档包含完整的参数说明、错误码定义、使用限制等信息。自己重写一份容易遗漏细节，直接保存原版最可靠。当需要 AI 帮你写代码时，把这些文档作为上下文提供给它，生成的代码更准确。
基础打好了，现在可以开始写业务功能了。告诉 AI 你想实现什么功能，把刚才归档的 API 文档一起提供给它，它就能写出准确的调用代码。
不要在循环中频繁调用 API：
合理使用缓存，相同的数据可以存起来重复使用。
flowchart TD
A[获取 API Key] --> B[选择技术路线<br/>SDK 或 HTTP]
B --> C[配置环境变量]
C --> D[编写最小测试]
D --> E{测试成功?}
E -->|否| F[排查问题]
F --> D
E -->|是| G[归档参考文档]
G --> H[开发业务功能]
style E fill:#fff3e0
style H fill:#e8f5e9使用外部 API 确实很方便，但有一个重要的风险你需要知道：不要过度依赖单一 API。
服务可能关闭或涨价。 提供 API 的公司可能随时停止服务、改变定价策略，或者大幅降低免费额度。如果你的业务完全建立在某个 API 之上，一旦这个 API 没了，你的应用也可能跟着瘫痪。
API 可能发生变化。 即使服务还在，API 本身的接口也可能变化。今天返回的是 user_name，明天可能变成 userName。这种看似微小的变化就可能导致你的应用崩溃。
应对策略：
理解了 API 集成后，接下来学习如何编写项目说明书。