如何让AI生成API接口

后端 API 是产品的骨架。数据怎么流转、权限怎么校验、错误怎么返回——这些决策决定了前后端协作的效率。用 AI 快速搭好骨架，你只需要把精力留给业务逻辑的判断。

1. AI 生成 API 的完整流程

AI 生成 API 接口不是「写一句 Prompt 就出代码」那么简单。一个可控的流程至少包含五个阶段：

1. 需求描述：用结构化格式定义路由、方法、参数、响应和错误码
2. 路由设计：确定资源命名、URL 层级、HTTP 方法映射
3. 代码生成：通过 Cursor、Claude Code 等工具生成骨架代码
4. 测试验证：对生成的接口做正向、反向和边界测试
5. 文档输出：生成 OpenAPI 规范或交互式文档

每个阶段之间是迭代关系——测试发现问题就回到代码生成阶段，文档中发现遗漏就补充需求描述。AI 在每一步都能提供帮助，但前提是你给的输入足够清晰。

2. API 需求描述的标准格式

AI 生成 API 代码的质量，直接取决于你的需求描述质量。模糊的自然语言会导致生成「能用但不贴合项目」的代码，而结构化的描述能产出开箱即用的接口。

2.1 需求描述模板

2.2 一个好的需求描述示例

路由：POST /api/projects/:projectId/members
路径参数：projectId (string)
请求体：{
  userId: string (必填)
  role: "admin" | "editor" | "viewer" (必填，默认 viewer)
}
响应 200：{ id, userId, role, joinedAt }
错误：
  - 400: userId 格式错误 或 role 值非法
  - 404: projectId 不存在
  - 409: 用户已是项目成员
认证：Bearer Token，当前用户需为项目 admin

这种格式对 AI 来说是「可直接翻译」的输入——路由对应 Controller 方法，请求体对应 DTO 校验，错误码对应异常处理分支。

3. 不同 API 类型的 Prompt 策略

API 的类型不同，Prompt 策略也不同。以下对比四种常见场景：

3.1 CRUD 接口的 Prompt 模板

请为「文章 Article」资源生成 RESTful CRUD 接口：

资源字段：
- title: string (必填，1-200 字符)
- content: string (必填，Markdown 格式)
- status: "draft" | "published" | "archived" (默认 draft)
- tags: string[] (可选)
- authorId: string (必填，关联 User)

要求：
- 使用软删除（isDeleted 字段）
- 列表接口支持分页（page, limit）和按 status 筛选
- 列表默认按 createdAt 降序排列
- 创建和更新时校验 title 长度和 status 枚举值
- 所有接口需要认证，删除和更新需验证作者权限

技术栈：Node.js + Express + Prisma + PostgreSQL

3.2 认证接口的 Prompt 模板

请生成用户认证模块的 API 接口：

1. POST /api/auth/register
   请求体：{ email, password, name }
   响应：{ user: { id, email, name }, token }
   校验：email 格式、password 最少 8 位含大小写和数字

2. POST /api/auth/login
   请求体：{ email, password }
   响应：{ user, token, refreshToken }

3. POST /api/auth/refresh
   请求体：{ refreshToken }
   响应：{ token, refreshToken }

安全要求：
- 密码用 bcrypt 加密（salt rounds = 12）
- JWT access token 有效期 15 分钟
- refresh token 有效期 7 天，用后轮换
- 登录失败 5 次后锁定账号 15 分钟
- 所有错误不暴露具体原因（如「邮箱或密码错误」）

3.3 文件上传和第三方集成的关键差异

文件上传类接口的 Prompt 必须覆盖存储策略（本地磁盘 / S3 / CDN），否则 AI 默认写到本地 uploads/ 目录，生产环境会遇到扩展性问题。第三方集成类接口则需要明确超时和重试策略——AI 生成的代码通常只覆盖「成功路径」，不会主动处理第三方服务超时、限流或返回异常格式的情况。

4. 错误处理：AI 最容易忽略的部分

AI 生成的 API 代码有一个共性问题：错误处理不完整。它会写好正常返回的逻辑，但对异常路径的处理往往只有一行 catch (e) { return error }。你需要显式要求以下内容：

4.1 错误处理清单

4.2 在 Prompt 中加入错误处理要求

不要只说「加上错误处理」，而是列出具体的错误场景：

错误处理要求：
1. 参数校验失败：返回 400，包含每个字段的错误详情
   格式：{ error: "VALIDATION_ERROR", details: [{ field: "email", message: "格式不正确" }] }
2. 资源不存在：返回 404，不暴露查询条件
3. 权限不足：返回 403，不说明具体缺少什么权限
4. 服务器内部错误：返回 500，记录日志但不暴露内部信息
5. 数据库唯一约束冲突：返回 409，提示「已存在」
6. 所有错误响应格式统一：{ error: string, message: string, details?: any }

这种写法让 AI 无法「自由发挥」，生成的错误处理代码直接可用。

5. API 文档自动生成

代码写完之后，文档是最后一环。手动写文档容易和代码脱节，让 AI 从代码生成文档可以保证一致性。

5.1 文档生成的三种路径

5.2 用 AI 生成 OpenAPI 文档的 Prompt

请根据以下接口代码生成 OpenAPI 3.0 格式的文档：

要求：
1. 每个接口包含 summary 和 description
2. 所有参数和请求体字段加 description 和 example
3. 列出所有可能的响应状态码（200/400/401/403/404/409/500）
4. 标注需要认证的接口（securitySchemes: BearerAuth）
5. 按资源分组（tags）
6. 输出 YAML 格式

输出路径：docs/openapi.yaml

5.3 文档与代码同步的策略

文档最怕的是和代码不一致。推荐的做法是在代码中直接使用注解（TypeScript 用 JSDoc + TSOA，Java 用 Swagger 注解），这样每次代码变更时文档自动更新。如果项目已有存量代码没有注解，可以让 AI 一次性扫描代码库生成初始文档，然后在 CI 中加入检查：每次构建时验证 OpenAPI 文件是否需要更新。

请在 CI 流程中加入 API 文档一致性检查：
1. 运行 tsoa spec 生成最新的 openapi.yaml
2. 对比生成的文件和 git 中的文件是否有差异
3. 有差异则 CI 失败，提示开发者重新生成文档

6. 实战案例

6.1 案例一：AI 生成 SaaS 项目的完整后台 API

背景：一个内容管理 SaaS 需要后台 API，涉及用户、项目、内容、权限四个模块，约 40 个接口。

过程：

第一步，先让 AI 生成数据模型和迁移文件。Prompt 中给出了四个实体的字段定义和关联关系：

请基于以下数据模型生成 Prisma schema 和迁移文件：

User: id, email, name, role(admin/editor/viewer), createdAt, updatedAt
Project: id, name, description, ownerId, createdAt, updatedAt
Content: id, title, body, status(draft/published), projectId, authorId, createdAt, updatedAt
ProjectMember: projectId, userId, role(admin/editor/viewer), joinedAt

关联关系：
- User 1:N Project (ownerId)
- Project 1:N Content
- Project N:M User (通过 ProjectMember)

第二步，逐模块生成 CRUD 接口。每次只生成一个模块，避免上下文过长导致质量下降。关键技巧是在每个模块的 Prompt 中引用第一步生成的 schema，让 AI 知道数据结构。

第三步，补充错误处理和权限校验。这一步单独做，因为 AI 在第一步生成代码时通常不会主动加这些逻辑。

第四步，生成 OpenAPI 文档。将四个模块的 Controller 文件一起给 AI，要求生成统一的文档。

结果：40 个接口在约 4 小时内完成骨架生成，后续花了 2 小时手动调整业务逻辑细节。相比纯手写，效率提升约 3 倍。

经验教训：

• 一次只生成一个模块的代码，上下文太长会导致 AI 遗漏字段
• 权限校验不要依赖 AI 的默认实现，必须明确指定规则
• 生成的迁移文件要在本地跑一遍，确认索引和约束正确

6.2 案例二：AI 生成 OAuth 第三方登录接口

背景：产品需要支持 Google 和 GitHub 的 OAuth 登录。

过程：

请生成 OAuth 登录模块的 API 接口，支持 Google 和 GitHub：

1. GET /api/auth/oauth/:provider
   - provider: "google" | "github"
   - 重定向到对应 OAuth 授权页面

2. GET /api/auth/oauth/:provider/callback
   - 处理 OAuth 回调，用 code 换取 access_token
   - 用 access_token 获取用户信息
   - 如果用户不存在则自动注册
   - 如果用户已存在则直接登录
   - 返回 JWT token

要求：
- Google OAuth 使用 openid + email + profile scope
- GitHub OAuth 使用 user:email scope
- Token 存储在环境变量中（GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET 等）
- 回调 URL 从环境变量读取（OAUTH_CALLBACK_URL）
- OAuth 失败时重定向到前端错误页面，不在后端返回错误 JSON
- 自动注册时需要处理邮箱已被其他方式注册的情况（合并账号）
- 记录第三方登录的 provider 和 providerId 到数据库

AI 生成了完整的 OAuth 流程代码，包括 redirect、callback、token exchange、用户查找/创建。但有几个地方需要手动修正：

• Google 的 token 刷新逻辑需要额外处理（AI 只生成了首次获取）
• 邮箱验证状态的合并逻辑需要手动补充（如果 OAuth 邮箱已验证但本地未验证，应自动标记为已验证）
• CSRF state 参数需要加强（AI 默认用简单随机字符串，生产环境建议用加密 session）

7. AI 生成 API 的检查清单

在将 AI 生成的 API 代码投入生产之前，逐项检查以下内容：

7.1 路由设计检查

• 路由命名遵循 RESTful 规范（名词复数、小写、无动词）
• URL 层级不超过 3 层（避免 /api/a/:id/b/:id/c/:id）
• HTTP 方法语义正确（GET 无副作用、PUT 全量更新、PATCH 部分更新）
• 列表接口统一支持分页（page + limit 或 cursor）

7.2 请求/响应检查

• 所有输入参数有类型校验和必填校验
• 枚举值有范围校验（不能传入未定义的值）
• 响应体字段与文档一致（不多不少）
• 敏感字段（密码、Token）不出现在响应中

7.3 错误处理检查

• 有统一的错误响应格式（{ error, message, details? }）
• 参数错误返回 400，包含字段级错误详情
• 未认证返回 401，未授权返回 403
• 资源不存在返回 404，重复创建返回 409
• 服务器错误返回 500，不暴露堆栈信息

7.4 安全检查

• 所有写操作需要认证
• 权限校验在 Controller 层完成，不依赖前端
• SQL 查询使用参数化（不拼接字符串）
• 文件上传有 MIME 类型白名单和大小限制
• Rate limiting 已配置（防止暴力破解和滥用）

7.5 文档检查

• OpenAPI 文档与代码一致
• 每个接口有 summary 和 description
• 请求/响应示例已填充（不是空 schema）
• 认证方式已在文档中声明
• 错误码列表完整

8. 工具选择对比

选择建议：如果项目已经有完整的技术栈和规范，用 Cursor 或 Claude Code 更合适——它们能读取项目上下文，生成符合既有风格的代码。如果是从零开始快速验证想法，v0 或 bolt.new 可以更快出原型。

9. 常见问题与应对

Q：AI 生成的 API 代码安全性够吗？

不够。AI 生成的代码通常是「功能正确但安全薄弱」的状态。它不会主动加 Rate Limiting、不会做输入消毒、不会处理 CORS 配置。这些必须在 Prompt 中显式要求，或者在代码审查时逐项补充。

Q：生成的接口性能有问题怎么办？

AI 默认不写数据库索引。如果你的列表接口涉及排序或筛选字段，需要在 Prompt 中补充索引要求。另外 AI 不会主动处理 N+1 查询问题——如果你的数据模型有关联关系，需要明确要求使用 include 或 join 避免逐条查询。

Q：如何处理 AI 生成代码和项目已有代码风格不一致的问题？

在项目根目录放一个 .cursorrules 或 CLAUDE.md 文件，写明技术栈、代码风格、目录结构和命名规范。AI 会读取这些文件并尽量遵循。如果效果不理想，给 AI 一两个现有接口的代码作为「参考样本」，比纯文字描述更有效。

Q：前后端接口对不上怎么办？

让 AI 先生成 OpenAPI 文档，前端基于文档写 mock 数据，后端基于文档实现接口。双方都按文档开发，联调时自然对齐。如果中间需要改接口，先改文档，再改代码。

10. 总结

AI 生成 API 接口的核心价值不是「完全替代手写」，而是把重复性的路由定义、参数校验、错误处理、文档编写这些「必须做但不费脑子」的工作自动化。你需要把精力放在 AI 做不好的事情上——业务规则判断、权限模型设计、安全策略制定。

关键原则：

• 输入越结构化，输出越可控——不要写一句话的 Prompt，用需求模板
• 分模块生成，不要一次全生成——上下文越长，质量越差
• 错误处理必须显式要求——AI 不会主动帮你处理边界情况
• 文档和代码必须同步——不同步的文档比没有文档更糟糕
• 安全是人工审查的事——AI 生成的安全代码不能直接信任

参考资料

1. Datawhale Easy-Vibe 教程：大模型辅助编写接口代码与接口文档 — 系统化教程，覆盖从项目架构到接口文档的完整流程
2. 用 AI 自动生成 API 接口代码的方法 - 知乎专栏 — 国内实践总结，包含 FastAPI、Express 等框架的 Prompt 模板
3. Cursor vs. Claude for FastAPI Development - TestDriven.io — 对比测试 Cursor 和 Claude 在 API 开发中的表现差异
4. Automate API Development Workflow with Bruno and Cursor AI — 用 Bruno + Cursor 自动化 API 测试和文档的工作流
5. AI-Powered API Test Generation: Cursor, Claude, and the One Rule - Medium — AI 驱动 API 测试生成的方法论和质量控制策略
6. API 文档自动生成的实用工具与实战指南 - TRAE — OpenAPI / Swagger / SpringDoc 的实战对比和最佳实践
7. Apifox 生成代码帮助文档 — Apifox 平台的代码生成和文档导出功能
8. Anthropic Academy: Claude API Development Guide — Claude API 官方开发指南和最佳实践