企业官网建设流程全解析

• 文档
• 教程
• Vibe Coding
• 示例工程

本文是 vibe-vibe 开源教程"开发基础"章节的第 4.7 节。外部 API 是扩展应用能力的标准手段——接入 AI 对话、地图、支付、短信等能力，都不需要从零实现，而是通过 API 与成熟服务通信。读完本文，你将掌握一条完整的 API 集成工作流：获取凭证 → 选择 SDK 或 HTTP 路线 → 配置环境变量 → 编写最小测试 → 归档参考文档 → 开发业务功能，并学会用 Vercel AI SDK 对接 OpenAI 兼容格式的大模型、安全地管理 API Key，以及处理限流、超时、认证失败等常见错误。

API 集成概述

现代软件开发的美妙之处在于：你不需要从零开始构建一切。无论你想做什么——让 AI 对话、显示地图、处理支付——都有现成的服务愿意为你做这些脏活累活。你只需要通过API与它们对话。

**API（Application Programming Interface，应用程序接口）**就是应用程序之间交流的语言。过去，两个软件要"对话"需要复杂的协议和专门的对接开发；现在，大多数服务都提供了标准化的 API，你只需要按照它们约定的格式发送请求，就能得到想要的结果。

为什么 API 如此重要？

想象你想做一个旅游应用：在地图上标注景点、显示当地天气、处理用户支付。在 API 出现之前，你必须自己搭建地图服务器、雇佣气象学家、对接银行系统。现在呢？调用地图服务 API、调用天气服务 API、调用支付服务 API——你只需要关注自己的核心业务逻辑，剩下的交给专业人士。

这不仅是效率问题，更是可能性问题。API 让个人开发者也能做出以前只有大公司才能做出的产品。你可以把不同服务的数据和能力像搭积木一样组合起来，创造出全新的东西。

异步通信与数据格式

现代 Web 应用使用AJAX（Asynchronous JavaScript and XML）技术与服务器交换数据——你在淘宝搜索商品时，页面不会整个刷新，搜索结果直接出现在下方，这就是 AJAX 在工作。用户操作后，JavaScript 在后台发送请求，服务器返回数据，页面局部更新而无需刷新。这种异步方式让交互更流畅。

API 通常返回JSON格式的数据（详见 4.6 配置文件格式）。JSON 是纯数据结构，任何编程语言都能解析，前端可以灵活地将其渲染成任意样式。

常见的 API 能力

现代 API 生态已经非常丰富，从基础的数据存储到前沿的 AI 多模态能力，都有成熟的服务可用：

API 集成六步法

完整的 API 集成遵循六个固定步骤：获取凭证 → 选择技术路线 → 配置环境变量 → 编写最小测试 → 归档参考文档 → 开发业务功能。下面逐一展开。

第一步：获取凭证

就像你需要身份证才能入住酒店一样，使用 API 也需要证明你的身份。这个身份证明就是API Key。

获取 API Key 的过程通常很简单：

1. 找到官方开放平台或开发者文档
2. 注册开发者账号
3. 创建应用或项目（填写一些基本信息）
4. 生成 API Key

::: warning 安全第一

API Key 就像你的银行卡密码——一旦泄露，别人就能冒充你使用服务，甚至花光你的额度。所以：

• 不要提交到 Git 仓库
• 不要写在前端代码中（用户能看到）
• 不要发布在公开场合

:::

第二步：选择技术路线

拿到 API Key 后，你需要决定如何调用 API。有两种方式：SDK和直接 HTTP 请求。

什么是 SDK？

SDK（Software Development Kit，软件开发工具包）是官方提供的封装库。它把你需要手动处理的底层操作（如 HTTP 请求、JSON 序列化、错误处理、超时重试等）都封装成简单的函数调用。你只需要调用generateText()这样的方法，SDK 内部会帮你完成所有复杂的网络交互。

::: tip 为什么优先使用 SDK？

官方 SDK 自带完善的 TypeScript 类型定义。这相当于给 AI 提供了一份详细的"代码地图"——它能准确知道有哪些功能、参数怎么填、返回值是什么。这比让 AI 仅凭 HTTP 文档推断参数和返回值更精确。

:::

针对 AI 应用：推荐 Vercel AI SDK。它提供@ai-sdk/openai-compatible包，专门用于对接实现 OpenAI API 格式的服务商。由于 OpenAI 的 API 设计已成为行业事实标准，大多数模型服务商（包括国内）都选择兼容其接口格式——在请求结构、响应字段、鉴权方式等方面保持一致。这意味着开发者只需学习一套 API 规范，修改baseURL、API Key 和模型名称即可调用全球主流大模型，无需为每个模型学习不同的 SDK。本教程的技术栈章节也将 Vercel AI SDK 列为 AI 集成的推荐方案。

第三步：配置环境变量

你拿到了 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文件不提交到 Git
• 不同环境使用不同密钥

::: tip .env 文件

Next.js 项目中，.env.local文件用于存储本地开发的环境变量。部署到生产环境时，在部署平台的设置中配置相同的环境变量即可。

:::

仓库中的实际证据：本仓库的 demo 项目正是这样做的——demos/demo-01-todo/src/db/index.ts 通过process.env.DATABASE_URL读取数据库连接串，如果环境变量未设置还会主动抛出错误：

if (!process.env.DATABASE_URL) { throw new Error('DATABASE_URL 环境变量未设置') } const sql = neon(process.env.DATABASE_URL)

process.env就是 Node.js 的"系统设置"，它会自动读取.env文件里的所有键值对。更完整的密钥管理实践（.gitignore屏蔽清单、Server 与 Client 边界）可参考本教程的 8.1 密钥管理与环境变量。

第四步：编写最小测试

配置好 SDK 和 API Key 后，不要急着写业务功能，先写一个最简单的测试。

为什么？因为如果你直接写复杂功能，一旦出问题，你不知道是配置错了、Key 无效了、还是代码逻辑有问题。而一个最简单的测试，只需要验证一件事：我能连上 API 吗？

// 测试 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和baseURL
• 使用generateText发送简单的测试消息
• chatModel()中填入模型名称（从环境变量读取或硬编码）
• 如果能收到回复，说明配置正确

如果测试成功，说明：

• API Key 有效
• 网络连接正常
• SDK 配置正确

如果测试失败，AI 会根据错误信息帮你排查：

• Key 填错了？
• 网络不通？
• SDK 版本冲突？
• 额度用完了？

第五步：归档参考文档

等测试通过了，不要急着继续开发。先把 API 的官方文档保存下来，方便后续查阅。

为什么？因为下次你让 AI 写相关功能时，如果直接把官方文档喂给它，它就能精准地写出调用代码。否则你可能需要反复解释各种参数和细节。

推荐做法：

1. 保存官方文档：将官方文档的关键页面保存为 Markdown 文件（可以使用浏览器插件如 "MarkDownload" 或手动复制）
2. 提取常用代码：把最常用的调用示例整理成速查表

文档存放位置建议：

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 官方文档 - 阿里云通义千问官方文档

::: tip 为什么保存官方文档？

官方文档包含完整的参数说明、错误码定义、使用限制等信息。自己重写一份容易遗漏细节，直接保存原版最可靠。当需要 AI 帮你写代码时，把这些文档作为上下文提供给它，生成的代码更准确。

:::

第六步：业务功能开发

基础打好了，现在可以开始写业务功能了。告诉 AI 你想实现什么功能，把刚才归档的 API 文档一起提供给它，它就能写出准确的调用代码。

::: tip 避免频繁调用

不要在循环中频繁调用 API：

• 既消耗 API 额度
• 又容易触发限流
• 响应速度慢

合理使用缓存，相同的数据可以存起来重复使用。

:::

仓库源码佐证：一次真实的前后端 API 集成

vibe-vibe 仓库中的 demo 项目完整演示了"后端提供 API → 前端调用 API"的全过程，可作为六步法中"开发业务功能"环节的落地范例。

后端 API 路由：demos/demo-01-todo/src/app/api/todos/route.ts 实现了 RESTful 风格的读取与创建接口——GET支持按category、status参数过滤查询，POST用 Zod 校验请求体（src/lib/validation.ts），校验失败返回400，创建成功返回201 Created：

// R - Read（查）：获取待办，支持分类和状态过滤 export async function GET(request: NextRequest) { // ...解析 category / status 查询参数，拼接查询条件 return Response.json(result) } // C - Create（增）：添加一条待办 export async function POST(request: Request) { const body = await request.json() const parsed = createTodoSchema.safeParse(body) if (!parsed.success) { return Response.json({ error: parsed.error.issues[0].message }, { status: 400 }) } // ... return Response.json(newTodo[0], { status: 201 }) }

单条资源路由 demos/demo-01-todo/src/app/api/todos/[id]/route.ts 则实现了PATCH（切换完成状态，返回404表示未找到）与DELETE（成功返回204 No Content）——这正好呼应 4.4 API 与 HTTP 基础 中讲的状态码速记规律：2xx成功、4xx客户端错误。

前端调用：demos/demo-01-todo/src/lib/queries.ts 展示了使用fetch调用后端 API 的完整模式，并结合 TanStack Query 实现乐观更新——提交后先立即在界面上更新，请求失败时再回滚（onError恢复旧数据、onSettled重新拉取）：

mutationFn: async (data: { title: string; category?: string; dueDate?: string }) => { const res = await fetch('/api/todos', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data), }) if (!res.ok) throw new Error('添加失败') return res.json() as Promise<Todo> }

API 测试：demos/demo-01-todo/tests/todos.test.ts 用 Vitest 直接对路由处理函数做单元测试——通过vi.mock模拟数据库层，验证GET返回 200、POST创建成功返回 201、空标题/缺字段返回 400。这正是"先写最小测试"思路在自建 API 上的延伸：测试先行，确认接口契约无误后再继续迭代。

常见错误处理

限流（Rate Limit）

大多数 API 都有调用频率限制，超过会返回429 Too Many Requests。

处理方法：

• 添加重试逻辑（等一会儿再试）
• 使用队列控制请求频率
• 分析是否可以优化调用逻辑

超时处理

API 如果迟迟不响应，程序会卡住。

处理方法：

• 设置超时时间
• 添加超时后的降级逻辑
• 显示友好的错误提示

认证失败

API Key 过期或无效会返回401 Unauthorized。

处理方法：

• 检查 API Key 是否正确
• 确认 Key 没有过期
• 检查是否有足够的调用额度

API 集成流程图

安全最佳实践

::: tip 前端不能直接调用敏感 API

你用小程序点外卖时，小程序不会把商家后台的密码发到你手机上——你的订单先发给小程序自己的服务器，服务器再拿着密钥去跟商家系统对接。这就是"后端代理"的工作方式。

不要在前端代码中直接调用需要 API Key 的接口。API Key 会被所有人看到，可能被滥用。

正确做法：后端接收前端请求，后端使用 API Key 调用外部 API，然后将结果返回给前端。

:::

这条原则与 4.5 前后端分离概念 中的核心表格完全一致：服务器端代码才能访问环境变量，而客户端（浏览器）代码只能访问页面 DOM 和有限设备信息。所以凡是需要密钥的外部 API 调用，必须放在服务器端（如 Next.js 的 API Routes 或服务端组件）执行。

API 依赖的风险

使用外部 API 确实很方便，但有一个重要的风险你需要知道：不要过度依赖单一 API。

服务可能关闭或涨价。提供 API 的公司可能随时停止服务、改变定价策略，或者大幅降低免费额度。如果你的业务完全建立在某个 API 之上，一旦这个 API 没了，你的应用也可能跟着瘫痪。

API 可能发生变化。即使服务还在，API 本身的接口也可能变化。今天返回的是user_name，明天可能变成userName。这种看似微小的变化就可能导致你的应用崩溃。

应对策略：

• 保留备选方案：如果可能，了解有哪些类似的 API 可用
• 抽象封装：把 API 调用封装成自己的函数（就像你在 App 里切换支付方式——从微信支付换成支付宝，结账流程不变，只是底层换了支付渠道），这样即使换 API，修改一处即可
• 缓存重要数据：不要每次都去请求 API，把结果存起来，减少依赖
• 监控 API 健康度：定期检查 API 是否正常响应

常见问题

Q1: 免费 API 额度用完了怎么办？

大多数 API 提供商都有付费计划。评估项目用量，选择合适的套餐。如果只是学习，可以申请教育或开发者优惠。

Q2: 如何测试 API 而不消耗额度？

使用 Mock 数据或测试环境。很多 API 提供商提供测试模式，返回假数据但不计费。

Q3: SDK 版本冲突怎么办？

使用 AI 帮忙解决。告诉它具体的错误信息和依赖版本，它会给出兼容的版本组合或替代方案。

Q4: 多个环境（开发/生产）如何管理 API Key？

使用不同的环境变量文件。Next.js 支持.env.local（本地）、.env.production（生产）等多环境配置。相应地在.gitignore中屏蔽所有敏感环境变量文件（参考 8.1 密钥管理与环境变量）。

Q5: 国内 API 和国际 API 该如何选择？

根据你的用户群体和业务需求：

• 服务国内用户：优先选择国内 API，网络延迟更低，合规性更好
• 服务海外用户：选择国际 API，全球节点覆盖更好
• AI 能力：国内外各有优势，可以对比效果和价格后选择
• 存储/短信等基础服务：国内服务商通常更便宜、响应更快

Q6: 国内大模型 API 兼容 OpenAI 格式吗？

是的，大多数国内大模型 API 都提供 OpenAI 兼容模式。使用兼容模式时，你只需要修改baseURL、API Key 和模型名称，其他代码基本不用改。具体配置请查阅各服务商的官方文档。

本节核心要点

• ✅ API 集成遵循六步法：获取凭证 → 选择路线 → 配置变量 → 测试 → 归档 → 开发
• ✅ 优先使用官方 SDK，类型定义让 AI 更准确
• ✅ API Key 必须存储在环境变量中
• ✅ 先写最小测试，验证通过后再开发业务功能
• ✅ 注意限流、超时、认证失败等常见错误
• ✅ 敏感 API 必须通过后端调用，不能暴露在前端

理解了 API 集成后，接下来学习如何编写项目说明书。

相关内容

• 前置：4.4 API 与 HTTP 基础
• 前置：4.5 前后端分离概念
• 前置：4.6 配置文件格式
• 详见：4.8 项目说明书结构

• 文档
• 教程
• Vibe Coding
• 示例工程