# FastAPIStart

**Repository Path**: jijie0418/fastapi-start

## Basic Information

- **Project Name**: FastAPIStart
- **Description**: 快速开始的FastAPI脚手架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-12-13
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastAPI 高效开发脚手架 (FastAPI QuickStart)

基于 FastAPI 的现代化、高性能后端开发脚手架。集成异步数据库操作、Redis 缓存管理、JWT 认证、MinIO 对象存储、Celery 任务队列以及完善的限流和日志机制。

## 🚀 核心特性

### 高性能异步架构
- 基于 FastAPI 和 Python 3.12+ 的异步特性
- 异步 MySQL 数据库操作 (SQLAlchemy 2.0 + aiomysql)
- 异步 Redis 客户端，支持连接池管理

### 完善的认证系统
- JWT 认证，支持用户注册、登录、权限校验
- Token 自动刷新机制
- Token 黑名单支持（登出时将 Token 加入黑名单）
- 邮箱验证功能

### 强大的缓存机制
- 支持异步和同步 Redis 客户端
- 连接池管理，自动重连
- 声明式缓存装饰器
- 缓存规则校验和自动清除
- 多级缓存键管理

### 数据库集成与迁移
- 使用 SQLAlchemy 2.0+ 实现异步数据库操作
- 集成 Alembic，支持结构化的数据库版本管理与迁移
- 数据库连接池配置优化

### 文件管理
- 支持本地存储与 MinIO 对象存储无缝切换
- 内置文件类型校验和大小限制
- 预签名 URL 生成
- 支持批量上传

### 安全与限流
- **三层限流架构**：
  - 全局 IP 限流（基于 Redis 滑动窗口）
  - 端点精细限流（SlowAPI 装饰器）
  - 自定义限流中间件
- 自动注入 Security Headers (XSS, Clickjacking 防护)
- CORS 跨域保护

### 异步后台任务
- Celery 任务队列支持
- 定时任务调度（Celery Beat）
- 示例：每小时检查未验证用户并清理

### 工程化实践
- **自动路由注册**：模块化开发，无需手动添加路由
- **标准响应格式**：统一的 API 响应结构 (StdResp)
- **集中化配置**：基于 pydantic-settings 的环境变量管理
- **完善的测试**：单元测试、集成测试、E2E 测试
- **Docker 部署友好**：Docker Compose、Nginx 配置及 Makefile

## 🛠️ 技术栈

| 分类 | 技术 |
|------|------|
| 框架 | FastAPI |
| 数据库 | MySQL (SQLAlchemy 2.0 + aiomysql) |
| 缓存 | Redis (redis-py) |
| 对象存储 | MinIO / 本地存储 |
| 认证 | JWT (python-jose) |
| 后台任务 | Celery |
| 日志 | Loguru |
| 限流 | SlowAPI |
| 依赖管理 | uv / pip |

## 📂 项目结构

```
fastapi_code/
├── app/                        # 核心代码目录
│   ├── auth/                   # 认证模块
│   │   ├── depends.py          # 认证依赖注入
│   │   ├── exceptions.py       # 认证异常
│   │   ├── models.py           # 用户数据模型
│   │   ├── repository.py       # 用户数据访问层
│   │   ├── router.py           # 认证API路由
│   │   ├── schemas.py          # 请求/响应Pydantic模型
│   │   ├── schemas_res.py      # 响应模型
│   │   └── service.py          # 认证业务逻辑
│   ├── core/                   # 核心组件
│   │   ├── database/           # 数据库配置
│   │   │   ├── base.py         # 基础模型类
│   │   │   └── database.py     # 数据库连接和会话
│   │   ├── exceptions/         # 异常处理
│   │   │   ├── base_exceptions.py
│   │   │   └── exception_handler.py
│   │   └── redis/              # Redis客户端和缓存管理
│   │       ├── async_client.py # 异步Redis客户端
│   │       ├── client.py       # 同步Redis客户端
│   │       ├── config.py       # Redis配置
│   │       ├── decorators.py   # 缓存装饰器
│   │       ├── manager.py      # 缓存键规则管理
│   │       ├── pool.py         # 连接池管理
│   │       └── signals.py      # SQLAlchemy事件信号
│   ├── files/                  # 文件管理模块
│   │   ├── depends.py          # 文件服务依赖
│   │   ├── exceptions.py       # 文件异常
│   │   ├── router.py           # 文件API路由
│   │   ├── schemas.py          # 请求模型
│   │   ├── schemas_res.py      # 响应模型
│   │   ├── service.py          # 文件业务逻辑
│   │   └── validators.py       # 文件校验
│   ├── middleware/             # 中间件
│   │   ├── cors.py             # CORS配置
│   │   ├── rate_limit.py       # 全局IP限流中间件
│   │   └── security.py         # 安全响应头
│   ├── tasks/                  # Celery异步任务
│   │   ├── celery_app.py       # Celery应用配置
│   │   ├── email_task.py       # 邮件发送任务
│   │   └── user_tasks.py       # 用户相关定时任务
│   ├── utils/                  # 工具类
│   │   ├── base_request.py     # 请求基类
│   │   ├── base_response.py    # 统一响应格式
│   │   ├── init_db.py          # 数据库初始化
│   │   ├── limiter.py          # SlowAPI限流配置
│   │   ├── logger.py           # 日志配置
│   │   ├── minio_service.py    # MinIO服务
│   │   ├── pagination.py       # 分页工具
│   │   ├── rate_limit_config.py # 限流配置
│   │   ├── register_router.py  # 自动路由注册
│   │   ├── security.py         # JWT安全工具
│   │   └── tasks.py            # 背景任务示例
│   └── examples/               # 示例代码
├── config/                     # 配置文件目录
│   └── settings.py             # 应用配置（pydantic-settings）
├── docker/                     # Docker相关配置
│   ├── mysql/init.sql          # MySQL初始化脚本
│   └── nginx/nginx.conf        # Nginx配置
├── docs/                       # 项目文档
├── tests/                      # 测试用例
│   ├── conftest.py             # pytest配置
│   ├── unit/                   # 单元测试
│   ├── integration/            # 集成测试
│   └── e2e/                    # 端到端测试
├── .env.example                # 环境变量模板
├── docker-compose.yml          # 容器编排配置
├── Dockerfile                  # 镜像构建文件
├── Makefile                    # 开发命令快捷入口
├── pyproject.toml              # 项目依赖配置
└── main.py                     # 应用入口文件
```

## 🏁 快速开始

### 环境要求

- Python 3.12+
- Redis
- MySQL 8.0+（可选，本地开发可使用 SQLite）

### 1. 安装依赖

```bash
make install
# 或
uv sync
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件配置数据库、Redis等信息
```

### 3. 启动服务

**本地开发：**
```bash
make dev
# 或
uvicorn main:app --host 127.0.0.1 --port 8000 --reload
```

**Docker 部署：**
```bash
make build
make up
```

### 4. 访问接口文档

- **Swagger UI**: http://127.0.0.1:8000/docs
- **ReDoc**: http://127.0.0.1:8000/redoc
- **健康检查**: http://127.0.0.1:8000/health

## 📚 API 接口文档

### 认证模块 (`/api/v1/auth`)

| 接口 | 方法 | 描述 | 认证 |
|------|------|------|------|
| `/auth/register` | POST | 用户注册 | 否 |
| `/auth/login` | POST | 用户登录 | 否 |
| `/auth/logout` | POST | 用户登出 | 是 |
| `/auth/me` | GET | 获取当前用户信息 | 是 |
| `/auth/verify-email` | GET | 验证邮箱 | 否 |
| `/auth/users` | GET | 获取用户列表 | 是 |
| `/auth/users/{user_id}` | GET | 获取指定用户信息 | 是 |

### 文件模块 (`/api/v1/files`)

| 接口 | 方法 | 描述 | 认证 |
|------|------|------|------|
| `/files/upload` | POST | 上传单个文件 | 是 |
| `/files/upload/multiple` | POST | 上传多个文件 | 是 |
| `/files/download/{path}` | GET | 下载文件 | 是 |
| `/files/delete/{path}` | DELETE | 删除文件 | 是 |
| `/files/presigned-url/{path}` | GET | 获取预签名URL | 是 |

### 响应格式

所有 API 响应遵循统一的 `StdResp` 格式：

```json
{
  "code": 200,
  "msg": "success",
  "data": { }
}
```

### 示例请求

```bash
# 用户注册
curl -X POST "http://127.0.0.1:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "email": "test@example.com", "password": "Password123"}'

# 用户登录
curl -X POST "http://127.0.0.1:8000/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "password": "Password123"}'

# 获取当前用户信息
curl -X GET "http://127.0.0.1:8000/api/v1/auth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 上传文件
curl -X POST "http://127.0.0.1:8000/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/file.jpg"
```

## 🧪 测试

### 运行所有测试

```bash
pytest
```

### 运行特定类型测试

```bash
pytest tests/unit/        # 单元测试
pytest tests/integration/ # 集成测试
pytest tests/e2e/         # E2E测试
```

### Docker 内运行测试

```bash
make test
```

## ⚙️ 配置说明

### 环境变量

主要配置项（`.env` 文件）：

```env
# 数据库配置
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=password
MYSQL_DATABASE=fastapi_db

# JWT配置
SECRET_KEY=your-secret-key-at-least-32-characters
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# MinIO配置
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
BUCKET_NAME=fastapi

# Celery配置
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0
```

### 数据库迁移

```bash
# 创建新迁移
alembic revision --autogenerate -m "描述信息"

# 应用迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1
```

## 🏗️ 项目架构

### 分层架构

```
┌─────────────────────────────────────┐
│        API Layer (Router)           │
│         处理HTTP请求和响应            │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│       Service Layer (Service)       │
│           业务逻辑处理                │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│     Repository Layer (Repository)   │
│         数据访问和持久化              │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│      Database Layer (SQLAlchemy)    │
│            数据库操作                │
└─────────────────────────────────────┘
```

### 缓存架构

```
┌─────────────────────────────────────────────────────────────┐
│                      缓存策略                                │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: 全局 IP 限流                                      │
│  - RateLimitMiddleware（Redis 滑动窗口算法）                 │
│  - 默认：200/分钟/IP                                        │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: 端点精细限流                                      │
│  - SlowAPI @limiter.limit() 装饰器                          │
│  - 注册: 30/分钟, 登录: 10/分钟                             │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: 数据缓存                                          │
│  - @cache 装饰器                                            │
│  - 连接池管理，自动重连                                      │
│  - 缓存键规则管理，支持标签批量清除                          │
└─────────────────────────────────────────────────────────────┘
```

## 🐳 Docker 部署

### 服务说明

| 服务 | 端口 | 描述 |
|------|------|------|
| app | 8000 | FastAPI 应用 |
| mysql | 3306 | MySQL 数据库 |
| redis | 6379 | Redis 缓存 |
| minio | 9000/9001 | MinIO 对象存储/控制台 |
| nginx | 80/443 | 反向代理 |

### 启动服务

```bash
# 构建并启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 清理资源
make clean
```

### 生产环境部署

```bash
# 修改 .env 中的生产配置
# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d
```

## 🔧 Makefile 命令

| 命令 | 描述 |
|------|------|
| `make install` | 安装依赖 |
| `make run` | 直接运行应用 |
| `make dev` | 热重载开发模式 |
| `make test-local` | 本地运行测试 |
| `make build` | 构建 Docker 镜像 |
| `make up` | 启动 Docker 服务 |
| `make down` | 停止 Docker 服务 |
| `make logs` | 查看服务日志 |
| `make test` | Docker 内运行测试 |
| `make clean` | 清理 Docker 资源 |
| `make celery-worker` | 启动 Celery Worker |
| `make celery-beat` | 启动 Celery Beat |

## 🔐 安全说明

### 认证流程

1. 用户注册 → 系统发送验证邮件
2. 用户点击邮件链接验证邮箱
3. 用户登录获取 JWT Token
4. 后续请求携带 Token：`Authorization: Bearer <token>`
5. Token 过期或登出后失效

### 安全特性

- 密码 bcrypt 加密存储
- JWT Token 自动过期
- Token 黑名单机制
- 多层请求速率限制
- CORS 跨域保护
- 安全响应头注入

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证。

## 🙏 致谢

- [FastAPI](https://fastapi.tiangolo.com/)
- [SQLAlchemy](https://www.sqlalchemy.org/)
- [Redis](https://redis.io/)
- [MinIO](https://min.io/)
- [Celery](https://docs.celeryq.dev/)