大模型辅助编写接口代码与接口文档

在之前的课程中，我们学习了如何使用 Figma 等工具完成 UI 设计稿、如何借助 AI 快速生成前端静态页面，以及如何利用 Supabase 构建数据库并实现初步的用户身份验证。现在，一个自然而然的问题摆在了面前：前端页面中那些动感十足的按钮点击后，究竟是如何把数据悄无声息地存进 Supabase 的？当我们需要执行更复杂的业务逻辑（如并发支付、定时推送、数据敏感处理）时，直接让前端连接数据库是安全的吗？

这就引出了现代 Web 开发架构中至关重要的一环——后端 API 接口。

相比于过去纯手工敲出成百上千行的后端路由、控制器与参数校验逻辑，如今我们完全可以借助大模型的强大代码生成能力，将繁杂的基础代码交由 AI 编写。在本节课中，我们将跳出“AI 写的又虚又泛”的怪圈，以真实的业务场景为依托，向你展示如何通过高质量的提示词（Prompt）引导大模型写出健壮、符合行业规范的 Node.js 后端接口，并自动完成接口文档与测试用例的生成。

💡 前置知识
在学习本节之前，建议你先了解以下内容：
从数据库到 Supabase - 了解数据库和数据模型的概念。
Git 和 GitHub 工作流 - 熟悉如何在项目开发中进行版本控制。
什么是终端/命令行 - 项目初始化与启动离不开基础的命令操作。

你将学到

什么是 API 接口：理解前后端通信的桥梁与 RESTful 设计规范。
大模型赋能服务构建：如何通过结构化的 Prompt 让 AI 帮你搭建 Node.js + Express 基础工程。
接口逻辑开发：引导大模型生成包含严谨业务校验、对接 Supabase 数据库的 CRUD（增删改查）接口。
自动化接口文档：让大模型根据代码逆向生成跨团队协作标配的 OpenAPI/Swagger 文档。
测试与联调闭环：利用大模型生成 Postman 测试合集与 Jest 单元测试用例，为代码质量兜底。

1. 为什么我们需要 API 接口？

在传统的理解中，前端是“看得到的部分”，数据库是“存东西的仓库”。但这中间缺少了一个调度员。如果你把整个应用想象成一家餐厅：

前端（客户端） 是餐厅的菜单和点餐桌，客人在这里浏览菜品并提出需求。
数据库（Supabase 等） 是餐厅的后厨仓库，里面存放着所有的食材和账本。
后端 API 接口 就是餐厅的服务员。客人不能直接冲进后厨拿食材（不仅混乱，而且容易引发安全问题），而是需要把“点单诉求”（HTTP Request）告诉服务员。服务员进行核对（参数校验、权限鉴权）后，去后厨调取对应的内容，再将“做好的菜”（HTTP Response，通常是 JSON 格式的数据）端回给客人。

通过 API 接口，我们实现了明确的前后端分离：前端只关心页面如何渲染，后端只专注于业务逻辑、数据处理与安全防护。

2. 项目架构设计与初始化

一个结构清晰的项目骨架，是大模型能写出好代码的先决条件。我们在让 AI 写代码前，自己心里必须对工程结构有个底。

2.1 常见的 API 工程结构

即使是使用大模型生成代码，我们也绝不能把所有代码都塞进一个 server.js 文件中。一个易于维护的 Node.js 后端架构通常如下所示：

text

my-api-project/
├── .env                  # 敏感环境变量（如 API Keys、数据库连接串）
├── server.js             # 项目入口（服务器启动、全局中间件注册）
├── package.json          # 依赖管理文件
├── src/
│   ├── routes/           # 路由层：定义 URL 路径与请求方法
│   ├── controllers/      # 控制器层：处理业务请求参数，调用服务并返回响应
│   ├── services/         # 服务层：封装数据库交互和核心业务逻辑
│   └── middlewares/      # 中间件：登录鉴权、错误全局捕获
└── docs/                 # API 文档存放目录

2.2 借助 AI 完成工程初始化

与其手动 npm init 并一个个安装依赖，不如直接将上述规范以 Prompt 的形式喂给大模型：

🗣️ 给大模型的提示词（Prompt 示例）： "帮我搭建一个 Node.js 后端项目，要能连接 Supabase 数据库，结构清晰一点，方便以后维护。"

运行 AI 返回的代码后，你就能在 localhost:3000 获得一个具备企业级雏形的后端应用了。

3. 核心实战：大模型辅助接口开发

这是本章节最核心的部分。大模型写出的代码往往容易存在“逻辑漏洞”或“表面敷衍”，原因在于开发者给的上下文不足。大模型不怕需求复杂，最怕需求模糊。

以我们在数据库章节中提到的 menu_items (菜单表) 的新增接口为例，看如何写出一份高质量的 Prompt。

3.1 赋予大模型完整上下文

在请求 AI 写接口之前，一定要提供数据库字段定义（Schema）和具体的约束条件。

🗣️ 高质量提示词（Prompt）模板： "帮我写一个新增菜单的接口，菜单有商品名、价格、分类（汉堡、小食、饮料）、是否上架这几个信息。商品名和价格必须填，价格不能是负数。用户输入不对的时候要提示错误。"

3.2 审查大模型生成的代码

大模型生成的代码通常会像下面这样清晰地拆分了职责：

javascript

// services/menuService.js
const { createClient } = require('@supabase/supabase-js');
const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY);

exports.createMenuItem = async (menuData) => {
    // 调用 Supabase SDK 将数据推入表内
    const { data, error } = await supabase
        .from('menu_items')
        .insert([menuData])
        .select();

    if (error) throw new Error(`数据库插入失败: ${error.message}`);
    return data[0];
};

你可以发现，通过这种方式生成的代码，不仅结构合理，而且将 Supabase 的初始化、错误捕获以及异常处理都考虑在内，这与简单要求“写个新增接口”得到的面条式代码（Spaghetti Code）有着天壤之别。

4. 解放双手：自动生成接口文档

对于开发团队而言，没有文档的 API 就是一个盲盒。前端工程师无法猜测你需要传入什么参数，也不能预测会返回什么结构。业界最通用的 API 描述规范是 OpenAPI (此前也称 Swagger)。

过去，手写 YAML 或者 JSON 格式的 Swagger 文档极其痛苦且容易出错。现在，这也成了大模型最擅长的领域。

你可以直接选中你刚才写的 routes 和 controllers 代码，然后丢给大模型：

🗣️ 生成文档的提示词： "帮我根据上面的代码生成一份接口文档，要写清楚每个参数是什么意思、返回什么数据，方便前端同事对接。"

在这个过程中，你甚至可以要求 AI 补全字段的说明（Description）和 Mock 数据（如 price_cents: 1200 代表 12 美元），极大地降低了沟通成本。

5. 保驾护航：生成测试代码与 Postman 集合

代码写好、文档出炉，还差最后一步：验证代码到底能不能跑通。

5.1 生成 Postman / Apifox 测试配置

在接口开发中，我们通常使用 Postman 这样的可视化工具来模拟前端发送 HTTP 请求。如果不使用大模型，你需要手动填入 URL、逐个添加 Header（请求头）以及拼接 JSON 请求体。

你只需向 AI 发送指令：

"帮我把这份接口文档转成 Postman 可以导入的格式，要包含正常请求和错误请求的例子。"

拿到 JSON 文本后，保存为 menu_api.json 并拖入 Postman，你瞬间就获得了一套开箱即用的测试点击面板。

5.2 编写自动化单元测试

如果你追求更严谨的工程质量，可以让大模型帮你使用 Jest 等测试框架编写单元测试（Unit Tests），对核心业务逻辑进行边界测试（比如传入负数价格时，数据库层的校验是否生效）。

6. 后端接口必知的最佳实践

即使有 AI 的协助，作为整个系统的“把关人”，你依然需要了解并审核以下这些核心准则：

RESTful 规范的路径命名：
- 好的设计：GET /api/users（获取用户列表）、POST /api/users（创建用户）。URL 应该代表“资源”的名词。
- 错误的设计：POST /api/getUser 或 POST /api/createUser。动词应该交由 HTTP Method (GET/POST/PUT/DELETE) 来体现。
规范的 HTTP 状态码：
- 200/201：请求成功 / 资源创建成功。
- 400：Bad Request，前端传参格式错误、少传了必填项。
- 401/403：Unauthorized / Forbidden，用户未登录或无权操作。
- 404：NotFound，资源不存在。
- 500：Server Error，后端代码报错或数据库挂了，绝对尽量避免将报错调用栈直接暴露给前端（会有安全隐患）。
永远不信任用户的输入：前端的输入可能是伪造的，所有核心参数校验必须在后端接口中再做一次。

7. 总结

通过本章节的学习，你实现了开发视角的真正转变：你不再是被困在语法和标点符号中的“打字员”，而是上升成为了系统设计师和架构指挥官。你已经掌握了：

API 接口与前后端分离的核心系统思维。
如何通过提供上下文与分层结构理念，大幅提高大模型生成服务端代码的质量。
把繁琐的文档编写和测试用例构建，巧妙地转化为 AI 擅长的自动化任务。
结合此前学过的 Supabase 知识，打通了从客户端请求到底层数据库更新的完整数据流。

💡 下一步

当你的数据流和后端服务都准备就绪后，它目前还只能在你的本地电脑上“自娱自乐”。在接下来的章节中，我们将学习如何把这套辛辛苦苦建立的服务部署（Deploy）到公网服务器上，让你的产品能被全世界的用户访问。

大模型辅助编写接口代码与接口文档 ​

你将学到 ​

1. 为什么我们需要 API 接口？ ​

2. 项目架构设计与初始化 ​

2.1 常见的 API 工程结构 ​

2.2 借助 AI 完成工程初始化 ​

3. 核心实战：大模型辅助接口开发 ​

3.1 赋予大模型完整上下文 ​

3.2 审查大模型生成的代码 ​

4. 解放双手：自动生成接口文档 ​

5. 保驾护航：生成测试代码与 Postman 集合 ​

5.1 生成 Postman / Apifox 测试配置 ​

5.2 编写自动化单元测试 ​

6. 后端接口必知的最佳实践 ​

7. 总结 ​