🚀 企业级FastAPI后端模板

一个功能完整、架构清晰的企业级FastAPI后端模板，专为团队开发设计，开箱即用

📖 快速开始 • 🏗️ 架构说明 • 📚 开发指南 • 🤝 贡献指南 • 🌟 给个Star!

---

🌟 为什么选择这个模板？

🎯 企业级标准	⚡ 开箱即用	🛡️ 安全可靠	📈 性能优秀
三层架构设计

规范清晰 | 5分钟启动项目

零配置烦恼 | RBAC权限控制

多重安全防护 | 异步高并发

现代化技术栈 |

✨ 核心特性

🔐 认证与权限

• JWT身份认证 - 基于HS256算法的安全token认证
• RBAC权限控制 - 角色基础访问控制，支持细粒度API权限
• 用户管理 - 完整的用户注册、登录、权限分配功能
• 角色管理 - 灵活的角色定义和权限分配

🗂️ 数据管理

• 菜单管理 - 动态菜单配置，支持多级菜单结构
• API管理 - 自动化API权限配置和管理
• 部门管理 - 组织架构管理，支持层级结构
• 文件管理 - 安全的文件上传、下载、存储功能

🛡️ 安全防护

• 登录限流 - 基于slowapi的智能限流，防暴力破解攻击（5次/分钟）
• 密码强度 - 强制复杂密码策略（8位+字母数字组合）
• JWT安全 - 4小时过期+刷新令牌机制，防止令牌泄露
• 文件安全 - 文件类型验证、大小限制、恶意文件检测
• 安全头 - 自动XSS、CSRF、点击劫持防护
• CORS配置 - 严格的跨域访问控制
• 环境验证 - 生产环境配置安全检查
• 审计日志 - 完整的用户操作记录和追踪

🏗️ 架构设计

• 三层架构 - API → Service → Controller → Model 清晰分层
• 异步支持 - 全异步设计，高性能处理
• 健康检查 - 系统状态监控和版本信息接口
• 数据库迁移 - 基于Aerich的版本化数据库管理
• 类型安全 - 完整的Python类型注解

⚡ 性能优化

• 连接池优化 - 数据库连接池配置，提升并发性能
• 缓存系统 - Redis集成，智能缓存策略
• 异步架构 - 全异步设计，支持高并发访问
• 性能监控 - 慢查询告警和性能指标追踪

🛠️ 技术栈

组件	技术选型	版本要求
语言	Python	3.11+
Web框架	FastAPI	0.100+
数据库ORM	Tortoise ORM	0.20+
数据库	SQLite/PostgreSQL	-
身份认证	PyJWT	2.8+
数据验证	Pydantic	2.0+
数据库迁移	Aerich	0.7+
包管理	UV	latest
日志	Loguru	0.7+
限流	SlowAPI	0.1.9+
缓存	Redis	4.5+

📁 项目结构

evoai-backend-template/
├── src/                          # 📦 源代码目录
│   ├── api/v1/                   # 🌐 API路由层 (轻量化路由)
│   │   ├── users/               # 👥 用户管理API
│   │   ├── roles/               # 👑 角色管理API
│   │   ├── menus/               # 📋 菜单管理API
│   │   ├── files/               # 📁 文件管理API
│   │   └── ...
│   ├── services/                 # 🔧 业务逻辑层 (核心业务)
│   │   ├── base_service.py      # 🏗️ 服务基类和权限服务
│   │   ├── user_service.py      # 👤 用户业务逻辑
│   │   ├── file_service.py      # 📄 文件业务逻辑
│   │   └── ...
│   ├── controllers/              # 🗄️ 数据访问层 (CRUD操作)
│   ├── models/                   # 📊 数据模型层
│   │   ├── admin.py             # 👨‍💼 用户角色模型
│   │   ├── base.py              # 🔷 基础模型类
│   │   └── enums.py             # 📝 枚举定义
│   ├── schemas/                  # ✅ 数据验证层
│   ├── core/                     # ⚙️ 核心功能
│   │   ├── dependency.py        # 🔗 依赖注入
│   │   ├── middlewares.py       # 🛡️ 中间件
│   │   └── init_app.py          # 🚀 应用初始化
│   ├── utils/                    # 🔧 工具函数
│   └── settings/                 # ⚙️ 配置管理
├── migrations/                   # 📈 数据库迁移文件
├── tests/                        # 🧪 测试文件
├── uploads/                      # 📂 文件上传目录
├── logs/                         # 📋 日志文件
├── pyproject.toml               # 📦 UV项目配置
├── .env                         # 🔐 环境变量配置
└── CLAUDE.md                    # 🤖 Claude开发指南

🚀 快速开始

1. 环境准备

# 安装UV包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone <your-repo-url>
cd evoai-backend-template

# 安装依赖
uv sync

2. 🔐 环境配置

复制环境配置文件：

cp .env.example .env

⚠️ 必须修改的安全配置：

配置项	说明	生成方式
SECRET_KEY	JWT签名密钥	openssl rand -hex 32
SWAGGER_UI_PASSWORD	API文档访问密码	设置强密码
DB_PASSWORD	数据库密码	设置强密码

配置示例：

# 基础配置
SECRET_KEY=your_generated_secret_key_here
APP_TITLE=你的项目名称
PROJECT_NAME=YourProject

# 数据库配置 (开发环境推荐SQLite)
DB_ENGINE=sqlite
DB_PASSWORD=your_strong_password

# API文档保护
SWAGGER_UI_USERNAME=admin
SWAGGER_UI_PASSWORD=your_strong_password

# CORS配置
CORS_ORIGINS=http://localhost:3000,http://localhost:8080

3. 数据库初始化

uv run aerich init-db

4. 启动服务

# 开发模式
uv run uvicorn src:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uv run uvicorn src:app --host 0.0.0.0 --port 8000 --workers 4

5. 访问服务

• API文档: http://localhost:8000/docs
• 替代文档: http://localhost:8000/redoc
• 健康检查: http://localhost:8000/api/v1/base/health
• 版本信息: http://localhost:8000/api/v1/base/version
• 系统状态: 实时监控系统运行状态

6. 默认账号

用户名: admin
密码: 123456
邮箱: admin@admin.com

🚨 首次登录后立即修改密码！

---

📊 项目统计

🎉 成功案例

💡 已有多个团队使用此模板快速搭建生产级后端服务

• 🏢 企业管理系统 - 支持10万+用户的权限管理平台
• 🛒 电商后台 - 高并发订单处理系统
• 📱 移动应用API - 微服务架构的用户中心
• 🎯 SaaS平台 - 多租户权限隔离系统

👥 如果你也在使用这个模板，告诉我们你的使用案例！

🏗️ 架构说明

三层架构模式

┌─────────────────┐
│   API Layer     │  ← 路由分发、参数验证
│  (api/v1/)      │
├─────────────────┤
│  Service Layer  │  ← 业务逻辑、权限检查
│  (services/)    │
├─────────────────┤
│Controller Layer │  ← 数据库操作、CRUD
│ (controllers/)  │
├─────────────────┤
│  Model Layer    │  ← 数据模型定义
│   (models/)     │
└─────────────────┘

核心设计原则

1. 单一职责 - 每层只处理自己的逻辑
2. 依赖注入 - 通过FastAPI依赖系统管理
3. 类型安全 - 完整的Python类型注解
4. 异步优先 - 全异步设计，高并发支持
5. 安全第一 - 内置多重安全防护机制

📚 开发指南

添加新功能

1. 定义数据模型 (models/)
2. 创建数据Schema (schemas/)
3. 实现Controller (controllers/)
4. 编写Service业务逻辑 (services/)
5. 添加API路由 (api/v1/)
6. 生成数据库迁移 (aerich migrate)

详细步骤请参考 CLAUDE.md 开发指南。

数据库操作

# 生成迁移文件
uv run aerich migrate --name "add_new_feature"

# 应用迁移
uv run aerich upgrade

# 查看迁移历史
uv run aerich history

测试

# 运行所有测试
uv run pytest

# 运行特定测试
uv run pytest tests/test_users.py

# 生成覆盖率报告
uv run pytest --cov=src --cov-report=html

🔒 安全最佳实践

生产环境安全检查

✅ 自动检查项

• [x] SECRET_KEY 自动生成安全密钥，至少32字符
• [x] 密码强度 强制8位+字母数字组合
• [x] 登录限流 自动防暴力破解攻击
• [x] JWT安全 4小时过期+刷新机制
• [x] 环境验证 生产环境配置自动检查
• [x] 错误保护 生产环境隐藏技术细节

📋 手动检查项

• [ ] DEBUG模式 生产环境设置 DEBUG=False
• [ ] 数据库 使用PostgreSQL而非SQLite
• [ ] CORS配置 设置具体域名，移除localhost
• [ ] HTTPS 生产环境启用HTTPS
• [ ] 数据库安全 使用独立数据库账号，限制权限
• [ ] Swagger密码 设置强密码保护API文档

文件上传安全

• 支持的文件类型白名单验证
• 文件大小限制 (默认500MB)
• 危险文件类型黑名单检测
• 安全的文件名生成机制
• 本地文件存储 (可扩展至云存储)

🔧 配置说明

环境变量

变量名	必填	默认值	说明
SECRET_KEY	✅	自动生成	JWT签名密钥（至少32字符）
SWAGGER_UI_PASSWORD	✅	-	API文档访问密码（至少8位）
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	❌	240	JWT访问令牌过期时间（分钟）
JWT_REFRESH_TOKEN_EXPIRE_DAYS	❌	7	JWT刷新令牌过期时间（天）
APP_TITLE	❌	Vue FastAPI Admin	应用标题
DB_ENGINE	❌	postgres	数据库类型
DB_HOST	❌	localhost	数据库主机
DB_PASSWORD	⚠️	-	数据库密码（生产环境必填）
CORS_ORIGINS	❌	localhost:3000	允许的CORS源
DEBUG	❌	True	调试模式
APP_ENV	❌	development	应用环境（development/production）

数据库支持

• SQLite - 适合开发和小型部署
• PostgreSQL - 推荐生产环境使用

📈 性能优化

🚀 已实现的优化

• 异步处理 - 全异步架构，支持高并发
• 登录限流 - 防暴力破解，每分钟最多5次尝试
• 密码策略 - 强制复杂密码，提升账户安全
• JWT优化 - 4小时短期令牌+刷新机制
• 错误保护 - 生产环境隐藏技术细节
• 健康监控 - 系统状态和版本信息接口

🔄 计划中的优化

• 连接池 - 数据库连接池配置优化
• Redis缓存 - 智能缓存策略集成
• 性能监控 - 慢查询告警和指标追踪
• 中间件 - 请求压缩、缓存头设置

🤝 贡献指南

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

代码规范

• 遵循 PEP 8 编码规范
• 使用 Google风格 文档字符串
• 添加 类型注解 到所有函数
• 编写 单元测试 覆盖关键功能

📄 许可证

本项目基于 MIT License 开源协议。

🔗 相关链接

• FastAPI官方文档
• Tortoise ORM文档
• UV包管理器
• Claude Code文档

---

🆘 获取帮助

如果您在使用过程中遇到问题：

1. 📖 查看 CLAUDE.md 详细开发指南
2. 🔍 查看 Issues 查找类似问题
3. 💬 创建新的 Issue 描述问题
4. 📧 联系维护者

开箱即用，专业可靠的企业级FastAPI后端模板 🚀

📝 更新日志

🆕 v1.1.0 - 安全功能增强 (2025-07-14)

🔐 安全提升

• ✅ 登录限流保护 - 基于slowapi，防暴力破解（5次/分钟）
• ✅ 密码强度验证 - 强制8位+字母数字组合
• ✅ JWT安全优化 - 4小时过期时间，支持刷新令牌
• ✅ 环境变量验证 - 生产环境配置安全检查
• ✅ 错误信息保护 - 生产环境隐藏技术细节

🏥 监控功能

• ✅ 健康检查接口 - /api/v1/base/health
• ✅ 版本信息接口 - /api/v1/base/version
• ✅ 系统状态监控 - 实时服务状态展示

🛠️ 开发体验

• ✅ 自动SECRET_KEY生成 - 无需手动配置
• ✅ 详细错误提示 - 开发环境友好的错误信息
• ✅ 配置验证增强 - 启动时自动检查配置

📋 v1.0.0 - 基础版本

• 🏗️ 三层架构设计
• 🔐 RBAC权限管理
• 📊 完整CRUD操作
• 🗄️ 数据库迁移支持

---

🏆 特色亮点

🚀 快速上手

curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/JiayuXu0/FastAPI-Template.git
cd FastAPI-Template && uv sync && cp .env.example .env
uv run aerich init-db && uv run uvicorn src:app --reload
# 🎉 5分钟内即可启动完整的企业级后端服务！

💎 技术栈对比

传统方案 ❌	本模板 ✅
复杂的环境配置	UV一键管理依赖
混乱的项目结构	清晰的三层架构
手动权限管理	完整RBAC系统
缺乏安全防护	多重安全机制
文档不完善	详细开发指南

🌟 社区支持

加入我们的开发者社区，一起打造更好的后端模板！

💬 讨论交流 • 🐛 报告问题 • 🔀 提交PR • 📧 联系作者

🎯 路线图

• [x] ✅ v1.0 - 基础三层架构和RBAC系统
• [x] ✅ v1.1 - UV包管理器集成
• [ ] 🚧 v1.2 - GraphQL API支持
• [ ] 📅 v1.3 - 微服务架构扩展
• [ ] 📅 v1.4 - 实时通信 (WebSocket)
• [ ] 📅 v2.0 - 云原生部署方案

查看完整路线图 →