FastAPI 模板项目

🚀 现代化的 FastAPI 项目模板，集成了完整的开发工具链和最佳实践

📅 创建者: Gyy
📅 创建时间: 2025年09月04日

✨ 内置功能

🔧 开发工具

• 📦 UV - 现代化的 Python 包管理器
• 🔍 Ruff - 高性能代码质量检查工具
• 🧪 Pytest - 强大的测试框架
• 📊 Coverage - 测试覆盖率分析

🔐 认证与安全

• 🔑 JWT Auth - JSON Web Token 认证
• 👨‍💼 SQLAdmin - 管理后台界面

🗄️ 数据库与ORM

• 🏗️ SQLModel / SQLAlchemy - 现代化 ORM
• 🔄 Alembic - 数据库迁移工具
• 🐘 PostgreSQL - 强大的关系型数据库

⚡ 异步任务与消息队列

• 🌿 Celery - 分布式任务队列
• 🔴 Redis - 内存数据库
• 🐰 RabbitMQ - 消息代理

🐳 容器化与部署

• 🐳 Docker - 容器化部署
• 🔄 GitHub Actions - CI/CD 自动化

🎯 API 特性

• 🐪 camelCase API 响应格式
• 📚 自动生成 API 文档

🚀 快速开始

📋 前置要求

1. 在您的机器上安装 Docker
2. 启动 Docker 服务

🛠️ 项目设置

1. 配置环境变量

   # 复制环境变量模板并填写配置
   cp .env.example .env

2. 构建镜像

   docker compose build

3. 运行数据库迁移

   docker compose run web alembic upgrade head

4. 启动服务

   # 开发模式（支持热重载）
   docker compose up --watch

5. 停止服务

   # 按 Ctrl+C 或运行以下命令
   docker compose down

📖 API 文档与管理界面

启动服务后，您可以访问以下地址：

服务	地址	描述
📋 Swagger UI	http://localhost:8000/api/v1/docs	交互式 API 文档
📚 ReDoc	http://localhost:8000/api/v1/redoc	美观的 API 文档
👨‍💼 管理后台	http://localhost:8000/admin	SQLAdmin 管理界面
🐰 RabbitMQ 管理	http://localhost:15672	消息队列管理界面 用户名/密码: fastapi/fastapi

🧪 测试

基础测试

# 运行所有测试
docker compose run web pytest

测试覆盖率

📊 生成覆盖率报告

# 运行测试并生成覆盖率数据
docker compose run web coverage run -m pytest

📋 终端报告

# 在终端查看覆盖率报告
docker compose run web coverage report

🌐 HTML 报告

# 生成 HTML 格式的覆盖率报告
docker compose run web coverage html

生成的 HTML 报告位于 /htmlcov 目录，您可以：

1. 使用 VSCode 的 Live Server 扩展
2. 访问 http://localhost:5500/htmlcov/ 查看详细的覆盖率报告

🗄️ 数据库管理

数据库迁移

# 创建新的迁移文件
docker compose run web alembic revision --autogenerate -m "描述信息"

# 执行迁移（升级到最新版本）
docker compose run web alembic upgrade head

# 回滚到基础版本
docker compose run web alembic downgrade base

# 查看迁移历史
docker compose run web alembic history

数据库操作

# 删除数据库（包括数据卷）
docker compose down -v

# 运行种子数据
docker compose run web python app/seeds.py

容器命令执行

# 在容器中执行任意命令
docker compose run web [您的命令]

🔍 代码质量

本项目使用 Ruff 进行代码格式化和质量检查：

# 检查代码质量
uv run lint

# 格式化代码
uv run format

# 自动修复代码问题
uv run lint-fix

---

📝 项目信息

• 创建者: Gyy
• 创建时间: 2025年09月04日
• 技术栈: FastAPI + SQLModel + PostgreSQL + Redis + RabbitMQ + Docker
• 开发工具: UV + Ruff + Pytest + Coverage

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

📄 许可证

本项目采用 MIT 许可证。