FastAPI Base 项目

一个完整的FastA └── utils/ # 工具模块 ├── helpers.py # 辅助函数 ├── redis_client.py # Redis客户端

   └── responses.py   # 标准响应格式架，集成了现代Web开发的常用技术栈。

技术栈

• FastAPI - 现代、快速的Python Web框架
• fastapi-cbv (by miaokela) - 基于类的视图，提供更好的代码组织
• Tortoise ORM - 异步ORM，支持多种数据库
• Celery - 分布式任务队列，支持异步和定时任务
• Redis - 缓存和消息队列
• query-builder-tool (by miaokela) - 复杂SQL查询构建工具
• JWT - 用户认证和授权
• Docker - 容器化部署

项目结构

fastapi-base/
├── app/                    # 应用核心代码
│   ├── core/              # 核心功能
│   │   ├── deps.py        # 依赖注入
│   │   └── security.py    # 安全相关
│   ├── models/            # 数据模型
│   │   └── models.py      # Tortoise ORM模型
│   ├── schemas/           # Pydantic模式
│   │   └── schemas.py     # 数据验证模式
│   ├── views/             # 视图控制器
│   │   └── user_views.py  # 用户相关视图
│   └── utils/             # 工具模块
│       ├── helpers.py     # 辅助函数
│       ├── query_builder.py # 查询构建器
│       ├── redis_client.py  # Redis客户端
│       └── responses.py   # 标准响应格式
├── celery_app/            # Celery应用
│   ├── celery.py          # Celery配置
│   └── tasks/             # 任务模块
│       ├── email_tasks.py # 邮件任务
│       ├── user_tasks.py  # 用户任务
│       └── general_tasks.py # 通用任务
├── config/                # 配置文件
│   ├── database.py        # 数据库配置
│   └── settings.py        # 应用设置
├── main.py                # 应用入口
├── requirements.txt       # Python依赖
├── pyproject.toml         # 项目配置
├── docker-compose.yml     # Docker组合配置
├── Dockerfile             # Docker镜像配置
└── 启动脚本/
    ├── setup.sh           # 环境设置
    ├── run_dev.sh         # 开发环境启动
    ├── run_celery.sh      # Celery服务启动
    └── deploy.sh          # 生产环境部署

快速开始

1. 环境设置

# 克隆项目
git clone <repository-url>
cd fastapi-base

# 运行设置脚本
chmod +x setup.sh
./setup.sh

2. 配置环境变量

# 复制环境配置文件
cp .env.example .env

# 编辑配置文件
vim .env

3. 启动开发环境

# 启动FastAPI应用
./run_dev.sh

# 在另一个终端启动Celery Worker
./run_celery.sh worker

# 在另一个终端启动Celery Beat（可选）
./run_celery.sh beat

4. 访问应用

• API文档: http://localhost:8000/docs
• ReDoc文档: http://localhost:8000/redoc
• 健康检查: http://localhost:8000/health

Docker部署

开发环境

docker-compose up -d

生产环境

./deploy.sh

API功能

认证相关

• POST /api/v1/auth/register - 用户注册
• POST /api/v1/auth/login - 用户登录
• GET /api/v1/auth/me - 获取当前用户信息

用户管理

• GET /api/v1/users/ - 获取用户列表（管理员）
• POST /api/v1/users/ - 创建用户（管理员）
• GET /api/v1/users/{user_id} - 获取指定用户（管理员）
• PUT /api/v1/users/{user_id} - 更新用户（管理员）
• DELETE /api/v1/users/{user_id} - 删除用户（管理员）

用户资料

• GET /api/v1/profile/ - 获取当前用户资料
• PUT /api/v1/profile/ - 更新当前用户资料

任务管理

• POST /api/v1/tasks/send-email - 触发发送邮件任务
• POST /api/v1/tasks/generate-report - 触发生成报告任务
• GET /api/v1/tasks/{task_id}/status - 获取任务状态

其他功能

• GET /api/v1/cache/test - 测试Redis缓存
• GET /api/v1/reports/user-stats - 获取用户统计报告

特性说明

1. 基于类的视图 (CBV)

使用 fastapi-cbv 提供更好的代码组织：

@cbv
class UserViewSet:
    async def get_users(self):
        # 获取用户列表
        pass

2. 异步任务处理

使用Celery处理异步和定时任务：

@celery_app.task
def send_welcome_email(user_email: str):
    # 发送欢迎邮件
    pass

3. Redis缓存操作

提供完整的Redis操作接口：

# 设置缓存
await redis_client.set_value("key", "value", expire=60)

# 获取缓存
value = await redis_client.get_value("key")

4. 数据库查询

使用 Tortoise ORM 进行数据库查询：

from app.models.models import User

# 查询活跃用户
active_users = await User.filter(is_active=True).order_by('-created_at').limit(20)

# 复杂查询
users_with_profiles = await User.filter(is_active=True).prefetch_related('profile')

5. JWT认证

完整的JWT认证系统：

• 用户注册/登录
• 令牌生成和验证
• 权限控制（普通用户/管理员）

开发指南

添加新的API端点

1. 在 app/schemas/ 中定义数据模式
2. 在 app/views/ 中创建视图类
3. 在 main.py 中注册路由

添加新的Celery任务

1. 在 celery_app/tasks/ 中创建任务文件
2. 定义任务函数并使用 @celery_app.task 装饰器
3. 在需要的地方调用 task.delay() 执行任务

添加新的数据模型

1. 在 app/models/models.py 中定义Tortoise ORM模型
2. 运行数据库迁移：aerich migrate --name "add_new_model"
3. 应用迁移：aerich upgrade

监控和日志

• Flower: Celery任务监控 (http://localhost:5555)
• 日志文件: app.log
• 健康检查: /health 端点

生产环境注意事项

1. 修改 .env 中的敏感配置
2. 使用强密钥替换 SECRET_KEY
3. 配置适当的数据库连接
4. 设置反向代理（Nginx）
5. 配置SSL证书
6. 监控和日志收集

贡献

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

许可证

MIT License