阅读原文：大模型辅助编写接口代码与接口文档

一、本章核心学习目标

• 理解 API 接口的核心作用，掌握前后端分离的架构思维

• 学会用大模型搭建标准化的 Node.js 后端工程，规范项目结构

• 掌握给大模型提供上下文的方法，引导 AI 生成健壮的业务接口代码

• 学会让 AI 自动生成 OpenAPI 接口文档，降低团队协作成本

• 掌握用 AI 生成测试配置和单元测试，为代码质量兜底

• 了解后端接口开发的行业最佳实践，保证接口的安全性和规范性

---

二、为什么我们需要 API 接口？

在前后端架构中，API 接口是连接前端和数据库的核心调度员，就像餐厅的服务员：

• 前端（客户端）：餐厅的菜单和点餐桌，用户在这里提出需求

• 数据库：餐厅的后厨仓库，存放所有数据和资源

• 后端 API 接口：服务员，用户不能直接访问数据库（安全 + 秩序问题），通过 API 传递请求，经过校验、处理后返回结果

通过 API 接口，我们实现了前后端分离：

• 前端只关心页面渲染

• 后端专注于业务逻辑、数据处理与安全防护

---

三、项目架构设计与初始化

清晰的项目结构是 AI 写出好代码的前提，不能把所有代码堆在一个文件里。

2.1 常见的 API 工程结构

标准化的 Node.js 后端架构，方便维护和扩展：

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

2.2 借助 AI 完成工程初始化

不用手动 npm init 装依赖，直接把结构需求告诉大模型，AI 会帮你搭建完整的项目骨架：

帮我搭建一个 Node.js 后端项目，要能连接 Supabase 数据库，结构清晰一点，方便以后维护。

运行 AI 返回的命令，就能快速得到一个具备企业级雏形的后端应用。

---

四、核心实战：大模型辅助接口开发

AI 写的代码质量，完全取决于你给的上下文，大模型不怕需求复杂，最怕需求模糊。

3.1 赋予大模型完整上下文

写接口前，一定要给 AI 提供完整的信息：

1. 数据库字段定义（Schema）

2. 具体的业务约束条件

3. 错误处理的要求

高质量提示词模板

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

3.2 审查大模型生成的代码

通过这种方式生成的代码，会自动拆分职责，包含完整的错误处理：

// 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];
};

和模糊需求生成的面条式代码相比，质量天差地别。

---

五、解放双手：自动生成接口文档

没有文档的 API 就是盲盒，前端无法猜测参数和返回值。业界通用的是 OpenAPI（原 Swagger） 规范。

过去手写 Swagger 文档非常痛苦，现在可以直接把接口代码丢给 AI：

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

AI 会自动生成规范的文档，还能帮你补全字段说明和 Mock 数据，极大降低团队沟通成本。

---

六、保驾护航：生成测试代码与 Postman 集合

代码写完后，用 AI 帮你完成测试环节，保证代码质量。

4.1 生成 Postman / Apifox 测试配置

不用手动填 URL、Header、请求体，直接让 AI 生成可导入的配置：

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

把生成的 JSON 文件拖入 Postman，就能得到一套开箱即用的测试面板。

4.2 编写自动化单元测试

对于严谨的项目，可以让 AI 用 Jest 等框架编写单元测试，对核心逻辑做边界测试，比如：

• 传入负数价格时，校验是否生效

• 缺少必填参数时，错误提示是否正常

---

七、后端接口必知的最佳实践

即使有 AI 协助，你也要审核这些核心准则，保证接口的规范性：

5.1 RESTful 规范

• 正确：URL 用名词代表资源，GET /api/users、POST /api/users，动词用 HTTP Method 体现

• 错误：POST /api/getUser、POST /api/createUser，把动词写进 URL 里

5.2 规范的 HTTP 状态码

• 200/201：请求成功 / 资源创建成功

• 400：参数错误、缺少必填项

• 401/403：未登录 / 无权操作

• 404：资源不存在

• 500：服务端错误，绝对不要把报错栈直接暴露给前端，有安全隐患

5.3 安全原则

永远不信任用户的输入，前端的校验可以绕过，所有核心参数校验必须在后端再做一次。

---

六、本章总结

通过这一章，你从 “打字员” 变成了系统设计师和架构指挥官：

1. 理解了 API 接口和前后端分离的核心架构思维

2. 学会了通过提供完整上下文，大幅提升 AI 生成服务端代码的质量

3. 把文档编写、测试用例构建这些繁琐工作，交给 AI 自动化完成

4. 打通了从前端请求到底层数据库的完整数据流，完成了后端服务的闭环

下一步，就可以学习把本地的后端服务部署到公网，让全世界的用户都能访问你的产品了。