FastAPI + Cursor AI 工作流：从需求到部署的完整实践

这篇文章记录我用 Cursor AI 开发一个 FastAPI 项目的完整过程，从项目初始化到生产部署。每一步展示如何把 AI 融入实际编码流程，而不是空洞的「用 AI 写代码」。

项目需求

目标：一个人力资源管理的小工具后端，核心功能：

• 员工 CRUD（增删改查）
• 部门管理
• 基于角色的权限控制
• REST API + OpenAPI 文档

Step 1：Cursor 初始化项目结构

用 Cursor Composer 创建项目骨架：

1创建 src/ 目录结构：2- src/main.py        FastAPI 入口3- src/models/        Pydantic 模型4- src/routers/       API 路由5- src/db.py          数据库连接6- src/config.py      环境变量配置7- requirements.txt   依赖8- .env.example       环境变量模板9 10使用 FastAPI + SQLAlchemy + PostgreSQL，异步写法。

Cursor 会生成完整的目录结构和基础文件。生成后我需要确认的是：

1. Pydantic 版本（v1 还是 v2）
2. SQLAlchemy 是同步还是异步
3. 数据库连接字符串是否从环境变量读取

Step 2：设计数据模型

先写 Pydantic models 和 SQLAlchemy models，然后让 AI 检查一致性：

1检查 models/employee.py 和 schemas/employee.py 的一致性：2- 所有字段是否有对应的 Pydantic 验证3- Optional 字段是否正确标注4- 枚举类型是否统一

这个检查 prompt 很有价值，能发现手动写容易忽略的不一致问题。

Step 3：路由开发的 AI 加速

写 CRUD 路由时，Cursor 的补全质量很高，但需要注意两点：

1. 让 AI 生成后手动确认逻辑

1@router.get("/employees/{emp_id}", response_model=EmployeeResponse)2async def get_employee(emp_id: int, db: Session = Depends(get_db)):3    # Cursor 补全这里，但我需要确认是否有权限检查

AI 生成的代码逻辑正确，但权限控制需要我根据业务补充。

2. 用 Inline Ask 解释陌生代码

遇到不熟悉的库或写法时，选中代码按 Cmd/Ctrl + / 问 AI：

1这段 SQLAlchemy 查询的性能如何？需要加索引吗？

Step 3：数据库迁移

用 Alembic 做数据库迁移是 FastAPI 项目的标准做法。Cursor 能帮写 migration 文件：

1为 employees 表创建一个 migration：2添加 employment_date, salary, position 字段3如果 salary 字段已存在则跳过

AI 会生成完整的 migration 文件，我只需要确认文件名和迁移逻辑。

Step 4：Docker + Railway 部署

Railway 部署 FastAPI 项目的优势是「零配置」，但需要正确的 Dockerfile：

1FROM python:3.11-slim2 3WORKDIR /app4COPY requirements.txt .5RUN pip install --no-cache-dir -r requirements.txt6 7COPY . .8 9# 生产环境用 gunicorn10CMD ["gunicorn", "-k", "uvicorn.workers.UvicornWorker", "-b", "0.0.0.0:8000", "src.main:app"]

Railway 的优势：

• 自动检测 Python 项目并配置 build
• PostgreSQL addon 一键创建
• 环境变量在 UI 配置，无需写死在代码里

部署后访问 your-app.railway.app/docs 查看自动生成的 OpenAPI 文档。

Step 5：Cursor AI 辅助调试

生产环境出问题时的调试流程：

1. 查看日志定位错误

Railway 的日志是结构化的，搜索 ERROR 或 exception 快速定位：

1处理用户创建请求时出现 validation error2Expected date format: YYYY-MM-DD, got: 05/01/2024

2. 用 Cursor 分析错误

把错误日志复制到 Cursor Composer：

1这是 Railway 部署的 FastAPI 应用报错日志：2[ERROR] validation error ...3请分析可能的原因并给出修复方案

AI 能根据具体的错误上下文给出比搜索引擎更精准的建议。

完整的 AI 辅助编码流程

1. 需求 → 项目骨架：Cursor Composer 生成目录结构和基础文件
2. 数据模型设计：AI 生成 Pydantic + SQLAlchemy models，我检查一致性
3. 路由开发：Cursor 补全 CRUD 逻辑，我补充业务逻辑和权限控制
4. 数据库迁移：AI 生成 migration 文件，我确认迁移逻辑
5. 部署：手动写 Dockerfile，Railway 自动构建
6. 调试：日志定位 + AI 分析错误原因

总结

Cursor 在 FastAPI 开发中的最佳作用是「减少重复性编码」——CRUD、migration、基础配置这些机械性的工作交给 AI，精力集中在业务逻辑和架构设计上。

关键原则：AI 生成 → 我审查 → 确认 → 下一项。不要让 AI 替你做决策，但可以让 AI 替你执行。