FastAPI 架构项目

一个增强的标准化 FastAPI 后端架构，具有清晰的分层、模块化、第三方集成和可扩展性功能。

项目特点

• 模块化架构：清晰的关注点分离和分层设计
• 异步支持：全面支持异步 IO 操作
• 可扩展性：插件系统支持缓存、存储、日志和队列等功能
• 安全性：内置 JWT 认证和授权机制
• 文档：自动生成的 API 文档和 OpenAPI 规范
• 测试：完整的测试套件和测试工具

技术栈

• Web 框架：FastAPI
• 数据库 ORM：SQLAlchemy 2.0+
• 数据库迁移：Alembic
• API 文档：Swagger UI / ReDoc
• 认证：JWT（JSON Web Tokens）
• 异步任务：Celery
• 缓存：Redis
• 存储：AWS S3
• 日志：Loguru
• 监控：Prometheus

项目结构

app/
├── api/ # API 层
│ ├── v1/ # API v1 版本
│ │ ├── endpoints/ # API 端点
│ │ └── router.py # API 路由配置
│ ├── dependencies.py # 依赖注入
│ ├── exceptions.py # 异常处理
│ ├── middlewares.py # 中间件
│ ├── openapi.py # OpenAPI 配置
│ └── security.py # 认证和授权
├── core/ # 核心模块
│ ├── config.py # 应用配置
│ ├── constants.py # 常量
│ ├── events.py # 应用事件
│ ├── logging.py # 日志配置
│ └── security.py # 安全工具
├── db/ # 数据库层
│ ├── base.py # 基础模型
│ ├── migrations/ # 数据库迁移
│ ├── repositories/ # 数据访问
│ ├── seeds/ # 种子数据
│ └── session.py # 数据库会话
├── domain/ # 领域层
│ ├── models/ # 领域模型
│ ├── schemas/ # 请求/响应架构
│ ├── enums.py # 枚举类型
│ └── exceptions.py # 领域异常
├── monitoring/ # 监控
│ ├── health.py # 健康检查
│ └── metrics.py # 指标监控
├── plugins/ # 插件系统
│ ├── cache/ # 缓存插件
│ ├── logging/ # 日志插件
│ ├── queue/ # 队列插件
│ └── storage/ # 存储插件
├── services/ # 服务层
│ ├── user.py # 用户服务
│ └── product.py # 产品服务
├── tasks/ # 异步任务
│ ├── celery.py # Celery 配置
│ └── jobs/ # 任务定义
└── utils/ # 工具函数
├── datetime.py # 日期工具
└── validation.py # 验证工具

快速开始

安装依赖

uv venv
source .venv/bin/activate  # Linux/Mac
# 或 
.venv\Scripts\activate     # Windows

uv pip install -r requirements.txt

环境设置

复制环境变量示例文件并填写配置：

cp .env.example .env

编辑 .env 文件，填写必要的配置信息。

数据库迁移

首次设置 Alembic (通常在项目初始化时运行一次，如果 migrations 目录已存在则无需执行):

# 如果 migrations 目录不存在
# alembic init migrations 

当你的 SQLAlchemy 模型发生改变后，自动生成新的迁移脚本:

alembic revision --autogenerate -m "你的迁移描述，例如：添加用户年龄字段" 

将数据库结构更新到最新版本:

alembic upgrade head

运行应用

uvicorn app.main:app --reload

应用将在 http://localhost:8000 上运行，API 文档可在 http://localhost:8000/api/v1/docs 访问。

Docker 运行

使用 Docker Compose 启动完整环境：

# 启动容器
docker-compose up -d

# 数据库迁移
docker-compose exec app alembic upgrade head

# 查看日志
docker-compose logs -f

# 停止容器
docker-compose down

开发指南

代码风格

项目使用 Black 和 isort 格式化代码：

black app tests
isort app tests

运行测试

运行所有测试 (通常包括单元测试和集成测试):

pytest

运行特定目录下的测试 (例如仅单元测试):

pytest tests/unit

运行标记为特定类型的测试 (需要配合 pytest.mark 使用):

pytest -m integration

运行性能测试 (需要安装 Locust):

# 确保已安装 locust: uv pip install locust
locust -f tests/performance/test_api_performance.py

部署

项目可以通过多种方式部署：

1. Docker：使用提供的 Dockerfile 和 docker-compose.yml
2. 云平台：部署到 AWS、GCP、Azure 等云平台
3. Kubernetes：使用 k8s 部署和编排

贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证 - 详情请查看 LICENSE 文件

联系方式

项目维护者 - [email protected]