用途:在构建或初始化 FastAPI + React + MongoDB(FARM 栈)应用时使用,提供整套开发模式与项目脚手架约定。
主要能力与结构:给出标准项目结构,包含 main.py(带 lifespan 的 FastAPI 入口)、requirements.txt、pyproject.toml、.env.example、Dockerfile(python:3.13-alpine)、docker-compose.yml(MongoDB + 后端,可选前端)、Makefile,以及 config/、models/、routes/、services/、utils/、tests/、client/、client_build/ 目录。
命名约定:每个领域按 {domain}_models.py、{domain}_services.py、{domain}routes.py、test{domain}.py 组织,新增功能时依次创建模型 → 服务 → 路由。
配置:双层优先级,环境变量(用 python-dotenv 读取,优先级最高)加 YAML 回退(config/secrets.yml 仅供本地开发,需 git 忽略,只提交 secrets.yml.example)。MongoDB 连接支持本地、带认证和 Atlas(mongodb+srv)写法,MONGODB_URL 可覆盖全部 YAML 解析。
数据层:使用 Motor 异步客户端,路由中不使用同步 PyMongo;返回时需把 ObjectId 转成字符串 id。模型采用 Pydantic v2 三层结构(Base → Create → Response),使用 model_config = {} 而非 class Config:。
路由与入口:使用 APIRouter、response_model 与状态码,路由以 /api/v1 前缀挂载,提供 /health 检查;生产环境将 client_build 以 StaticFiles 挂载。CORS 来源从环境变量读取。
Docker:基于 Alpine,使用非 root 用户,docker-compose 含 MongoDB 8+ 持久卷、后端热重载与共享网络,环境变量从 .env 流入 compose 与容器。
依赖与测试:列出 fastapi、uvicorn[standard]、motor、pydantic[email]、PyYAML、python-dotenv、passlib[bcrypt]、python-multipart 等最小版本;开发依赖含 pytest、httpx、ruff、coverage,测试目标覆盖率 80% 以上。
限制:版本号为 2026 年初的最小值,需查 PyPI 最新稳定版;未提供具体收费、价格或平台信息。反模式清单提示避免在路由写业务逻辑、硬编码 CORS、提交 secrets.yml 等。