项目
文本分析 API
提交文本后返回 summary、keywords、length，并保存历史记录。
产出物一个可运行的 FastAPI 文本分析服务。
Checklist
阶段任务
- 创建 Python 虚拟环境并固定依赖文件
- 安装 FastAPI、Uvicorn、Pydantic 和 SQLAlchemy 或 SQLModel
- 定义 GET、POST 接口并理解路径参数、查询参数和请求体
- 使用 Pydantic 定义请求模型、响应模型和字段校验
- 理解 Depends 依赖注入的基本用途
- 使用 SQLite 保存分析历史并拆分数据库初始化逻辑
- 理解 settings 配置、环境变量、日志和异常处理
- 为接口编写 pytest 或 TestClient 测试
- 了解后台任务 BackgroundTasks 和异步调用的适用场景
- 访问 /docs 自动文档并用 curl 或 Apifox 调试
- 整理 FastAPI 项目目录和前端调用方式
- 了解 FastAPI 部署时 Uvicorn、Gunicorn、systemd、Docker 的关系
Labs
建议练习
API
历史记录接口
为文本分析服务增加历史列表和历史详情接口，支持分页和不存在记录的 404 响应。
产出物GET /history 和 GET /history/{id}。
API
前端调用 FastAPI
写一个简单前端页面，输入文本后调用 /analyze，并把历史列表渲染出来。
产出物一个能验证 CORS、loading、错误提示的前端联调页面。
API
FastAPI 接口测试
使用 TestClient 或 pytest 为 /analyze 和 /history 编写成功、参数错误、资源不存在的测试。
产出物至少 3 个可运行的接口测试。
自动化
后台任务认知
为文本分析结果增加一个模拟异步通知或日志写入任务，理解 BackgroundTasks 不适合承载重型队列的边界。
产出物一个后台任务示例和适用场景说明。
Daily Plan
每日安排
Day 1
环境、启动与第一个接口
把 Python 后端服务真正跑起来，理解 FastAPI 应用、路由函数和 Uvicorn 的关系。
- 创建 venv 虚拟环境并安装 fastapi、uvicorn
- 编写 main.py，提供 GET /health 和 GET /version
- 使用 uvicorn main:app --reload 启动服务
- 打开 /docs，观察接口文档如何自动生成
当天产出一个可访问 /health 和 /docs 的 FastAPI 最小服务。
Day 2
请求体、响应模型与校验
用 Pydantic 把接口输入输出变成明确契约，而不是任意 dict。
- 定义 AnalyzeRequest，包含 text 字段和长度校验
- 定义 AnalyzeResponse，包含 summary、keywords、length
- 实现 POST /analyze，并返回模拟分析结果
- 用错误参数测试 422 校验响应
当天产出一个具备请求校验和响应模型的 POST /analyze 接口。
Day 3
保存历史记录
理解 API 服务如何把一次请求的结果保存到数据库，先用 SQLite 降低环境成本。
- 创建 analysis_history 表或 SQLModel 模型
- 在 /analyze 成功后写入 text、summary、keywords、created_at
- 实现 GET /history，支持 page 和 pageSize
- 实现 GET /history/{id}，处理不存在时的 404
当天产出文本分析历史可以写入数据库并分页查询。
Day 4
项目分层与依赖注入
把 main.py 里的代码拆开，让 AI 以后能按文件修改，而不是把所有逻辑塞在一起。
- 拆分 app/main.py、routers/analyze.py、schemas.py、database.py、services/analyzer.py
- 用 Depends 注入数据库会话或服务对象
- 整理统一响应格式和异常处理
- 添加 settings.py 管理环境变量和日志配置
- 让 AI Review 拆分后的目录职责
当天产出一份适合继续扩展的 FastAPI 目录结构。
Day 5
前端联调与小结
从前端视角验证 FastAPI 接口，整理 Python 后端适合承担的场景。
- 用 fetch 或 axios 调用 /analyze 和 /history
- 检查 CORS、状态码、错误响应和 loading 处理
- 使用 TestClient 或 pytest 为 /analyze 写成功和失败测试
- 记录安装、启动、测试和常见报错命令
- 总结 FastAPI 与 Express 在路由、模型、服务层上的对应关系
当天产出一份 FastAPI 接口联调笔记和可复用提示词。
Knowledge
知识点解释
FastAPI 写 API 很快，类型提示和自动文档对 AI 协作也很友好。它尤其适合 AI 工具、脚本服务、数据处理接口和内部轻量服务。
Pydantic
用于定义数据模型和自动校验请求参数，也能生成接口文档中的 schema。
前端类比：类似 TypeScript 类型加运行时表单校验。
Uvicorn
运行 FastAPI 应用的 ASGI 服务器，开发时常用 --reload 自动重启。
前端类比：类似 Vite dev server 或 Node 服务启动器。
虚拟环境
为每个 Python 项目隔离依赖，避免全局包互相影响。
前端类比：类似每个项目有自己的 node_modules。
Depends
FastAPI 的依赖注入机制，常用来提供数据库会话、当前用户、配置或服务对象。
前端类比：类似在组件里统一注入 store、request client 或上下文对象。
自动接口文档
FastAPI 会根据路由和 Pydantic 模型生成 OpenAPI 文档，默认可在 /docs 查看。
前端类比：类似类型定义自动变成可调试的接口说明。
Settings 配置
集中管理端口、数据库 URL、密钥、环境名等配置，避免散落在代码里。
前端类比：类似前端用 env 文件和配置模块区分开发、测试、生产。
TestClient
FastAPI 测试工具，可以在测试里直接请求接口并断言响应。
前端类比：类似用测试工具模拟浏览器请求组件或页面。
BackgroundTasks
FastAPI 内置的轻量后台任务能力，适合请求返回后做简单收尾工作，不适合复杂队列。
前端类比：类似提交后异步做一点清理，但不是完整任务调度系统。
常见坑点
- 不要把 Python 包都装到全局环境
- 接口模型和数据库模型不要混在一起不加区分
- AI 生成 Python 代码后，要确认依赖版本和启动命令
- 部署时不要只用开发命令裸跑，至少需要进程管理
- Pydantic v1 和 v2 写法有差异，复制代码前要确认版本
- async def 不代表所有数据库和第三方调用都自动变快，要看依赖是否支持异步
- BackgroundTasks 不适合长时间、可重试、可靠性要求高的任务
- 不要把 .env、API Key 和数据库密码提交到仓库
Prompts
AI 协作提示词
生成 FastAPI 服务
请使用 Python FastAPI 写一个文本分析 API。要求提供 POST /analyze 接口，接收 text 字段，返回 summary、keywords、length，使用 Pydantic 定义请求和响应模型，使用 SQLite 保存分析历史，提供 GET /history 查询历史，给出安装命令、启动命令和接口测试示例。我是前端开发，请解释 FastAPI 中路由、模型、依赖分别对应什么职责。拆分 FastAPI 项目结构
下面是一个都写在 main.py 里的 FastAPI 服务。请帮我重构成适合继续扩展的目录结构，至少包含 routers、schemas、services、database、config。请先说明每个文件职责，再输出改造步骤，并提醒我需要同步修改的 import 和启动命令。FastAPI 联调排错
我的前端调用 FastAPI 接口失败。请求地址【填写】，方法【填写】，请求体【填写】，浏览器报错【填写】，FastAPI 日志【填写】。请判断是 CORS、参数校验、路由路径、服务未启动还是后端异常，并给出排查顺序。FastAPI 测试与部署 Review
请 Review 下面的 FastAPI 项目。请重点检查目录分层、Pydantic 模型、依赖注入、数据库会话关闭、异常处理、CORS、日志、测试覆盖、环境变量和部署启动命令是否合理。请按上线前必须修复和后续优化分组。Acceptance
验收标准
- 能运行 FastAPI 服务并访问 /docs
- 能写一个 POST 接口并完成参数校验
- 能把分析历史保存到 SQLite 并查询
- 能拆分路由、模型、服务和数据库文件
- 能为 FastAPI 接口写基础测试
- 能说明 Settings、日志、部署命令和进程管理的关系
- 知道 Python 后端适合 AI 工具、脚本服务和轻量 API
Resources
推荐资源
FastAPI 入门、请求模型和部署说明。
学习数据模型和校验。
FastAPI 作者维护的轻量 ORM 方案，适合入门练习。
Progress