用 Cursor 一个项目同时生成 React 前端与 FastAPI 后端：目录结构与约束式需求模板

约 6 分钟 · 3236 字 · 4 views
用 Cursor 一个项目同时生成 React 前端与 FastAPI 后端：目录结构与约束式需求模板

用 Cursor 一个项目同时生成 React 前端与 FastAPI 后端：目录结构与约束式需求模板

导读：这篇文章讲的是用 Cursor 这类 AI 编程工具时，把 React 前端与 FastAPI 后端放进同一个项目里生成代码的做法，核心方法是一套 backend/ + frontend/ 并列的目录结构，加上把技术栈、目录树、接口约定（如 /api/v1/...）写进需求的"约束式需求模板"。核心结论是"全景可见比物理隔离更重要"——约定在需求里写清一次落地，能显著减少接口与页面对不齐的返工。适合用 AI 编程工具做全栈项目、关心 AI 生成代码质量可控性的开发者和面试官。

分类：AI编程 ｜ 标签：Cursor、AI编程、React、FastAPI

为什么前后端放进同一个项目

过去写 Web 应用，习惯把前端仓库和后端仓库分开管理。但如果你打算用 Cursor 这类 AI 编程工具来"生成代码"，把前后端放在同一个项目里往往效率更高，原因很朴素：

  • AI 的上下文是连续的：同一个项目里，AI 生成后端接口时能看到前端页面怎么写的，生成前端页面时能看到接口怎么定义的，前后端不会"各说各话"。
  • 约定一次写清，全局生效：接口路径风格、返回结构、字段命名这类约定，在一份需求里定义一次，AI 就能在整个项目里保持一致。
  • 接口与页面天然对齐：工程实践中最常见的返工，就是接口和页面对不上——字段少了、路径错了、返回结构变了。放在一个项目里，AI 更容易按"一页一接口"的对应关系生成代码。
  • 目录即约束：清晰的目录结构本身就是在告诉 AI"文件该放哪里、职责怎么划分"，AI 定位文件、复用组件都比跨仓库时可靠得多。

一句话：对 AI 编程而言，"全景可见"比"物理隔离"更重要。

推荐的目录结构

以一个"大模型测试平台"项目为例——它需要在同一个项目里同时包含前端和后端代码。推荐采用 backend/ 与 frontend/ 并列的布局：

项目根目录/
├── backend/                     # FastAPI 后端
│   ├── app/
│   │   ├── main.py              # FastAPI 启动文件
│   │   ├── routers/             # 接口路由，按模块拆分
│   │   ├── models/              # SQLAlchemy ORM 模型
│   │   ├── schemas/             # Pydantic schema
│   │   └── services/            # 业务逻辑
│   └── tests/                   # 后端单元测试
└── frontend/                    # React 前端
    └── src/
        ├── pages/               # 主要页面：模型管理、用例管理、测试计划、测试报告
        ├── components/          # 通用组件
        ├── services/api.ts      # 封装 axios，统一调用 FastAPI 接口
        ├── store/               # 全局状态管理，可用 Zustand/Redux
        └── App.tsx

这个结构的几个关键点：

  • 后端按"职责"分层：路由（routers/）只做接口定义，模型（models/）管数据库结构，schema 管数据校验，业务逻辑收敛到 services/。层与层之间边界清楚，AI 生成代码时不容易写串。
  • 前端按"页面 + 能力"组织：pages/ 对应一个个具体页面，通用能力（组件、接口封装、状态管理）单独抽出，避免同一段逻辑在每个页面里重复生成。
  • API 层独立封装：前端不直接散落写 axios 调用，而是统一收敛到 services/api.ts，AI 生成页面时只要"复用 api.ts 里的函数"，接口路径就不会满项目乱飘。
  • 便利条件：如果确定会使用 TypeScript、Dockerfile、README 等，也可以一并写进目录要求里（原文的技术栈中包括 Docker 支持，可据此在根目录预设 Dockerfile 位置），让 AI 一次生成完整骨架。

技术栈方面，这套方案的原型是：后端 FastAPI + Python，前端 React + Ant Design，数据库 MySQL；评估与可视化可选 DeepEval、Chart.js / Plotly；部署支持 Docker。这些都可以根据你的实际项目替换，但目录结构本身值得保留——它是让 AI 听话生成的关键。

约束式需求模板：把"约定"写进需求，而不是只描述功能

同样一句话需求，ChatGPT 风格的"帮我做一个测试平台"和一段结构化的需求描述，AI 生成的结果质量差距极大。所谓"约束式需求描述"，就是把技术栈、目录位置、接口约定、权限边界、页面与接口的对应关系这些"约束"显式写出来，让 AI 第一次就生成正确，而不是生成完再来回改。

下面这个模板就是一次实践的结构，可以直接套用：

## 项目概述
这是一个大模型测试平台项目，需要在同一个项目里包含前后端代码。

## 技术栈
- 后端：FastAPI + Python
- 前端：React + Ant Design
- 数据库：MySQL
- 评估框架：DeepEval
- 可视化：Chart.js 或 Plotly
- 部署：Docker 支持

## 目录结构要求
/backend
  ├── app/main.py        # FastAPI 启动文件
  ├── app/routers/       # 接口路由，按模块拆分
  ├── app/models/        # SQLAlchemy ORM 模型
  ├── app/schemas/       # Pydantic schema
  ├── app/services/      # 业务逻辑
  └── tests/             # 后端单元测试
/frontend
  ├── src/pages/         # 主要页面：模型管理、用例管理、测试计划、测试报告
  ├── src/components/    # 通用组件
  ├── src/services/api.ts   # 封装 axios，统一调用 FastAPI 接口
  ├── src/store/         # 全局状态管理，可用 Zustand/Redux
  └── src/App.tsx

## 接口与页面约定
- FastAPI 提供 REST API，接口返回 JSON。
- 前端 React 页面通过 axios 调用 FastAPI 接口。
- 前后端接口风格统一，路径建议：/api/v1/...
- 保持接口与前端页面一一对应。

## 页面与模块清单
- 用例管理：增删改查、导入导出
- 模型管理：配置模型、版本管理
- 测试计划：创建、执行、对比
- 测试报告：可视化图表 + 导出功能

模板里每一块的分工都很明确：

  • 项目概述：一句话说明"一个项目、包含前后端"，让 AI 不会把前后端拆成两个工程去生成。
  • 技术栈：写死每一层用什么，避免 AI 擅自选型（比如莫名给你换个状态管理库或 ORM）。
  • 目录结构：直接给出目标树，AI 生成文件时照此落位，生成后你核对目录是否符合预期即可。
  • 接口与页面约定：接口风格（/api/v1/...）、调用方式（axios）、返回格式（JSON）写清楚，这是前后端对齐的"宪法"。
  • 页面与模块清单：把每个页面要覆盖的能力点列全，AI 生成页面时不会漏功能，也方便你逐项验收。

注意事项

  • 权限约束要单独写：如果系统有角色体系，务必在需求里写明确，例如"支持用户角色（管理员/测试工程师/观察员），前端页面需根据权限控制操作按钮的显示"。权限这类横切需求，不显式声明，AI 几乎必然遗漏。
  • 页面和接口要"一一对应"地列：光是说"功能要完整"没用，把每个页面的功能点（增删改查、导入导出……）逐项列出来，AI 才知道该给每个页面配哪些接口，验收时也清楚。
  • 约束别写到窒息：目录、接口约定这些"契约"要写死，但页面细节可以留白让 AI 发挥，否则生成结果会呆板且每次返工迭代成本高。
  • 生成后先检查目录与约定，再检查功能：AI 生成完成后，第一件事是核对目录结构是否符合需求树、接口路径是否是 /api/v1/...，这些"契约项"不对，后面功能再对也要推倒重来。
  • 接口约定省不掉的理由：前后端分仓库时，接口约定通常靠接口文档维系；放在一个项目里，约定写在需求里、AI 一次性落实，文档维护成本反而更低。

用这种方法，一个 Cursor 项目一次就能生成前后端可运行的全栈骨架；剩下的工作，就从"改接口"变成了"验收约定是否落地"。

📌 相关阅读