全栈 FastAPI 模板：快速构建现代 Web 应用的利器

full-stack-fastapi-template

full-stack-fastapi-template

项目概述

该模板基于 FastAPI（一个高性能的 Python Web 框架）构建后端，结合 React 作为前端框架，并使用 PostgreSQL 作为数据库，辅以 Docker、GitHub Actions 等现代工具，提供了从开发到部署的完整解决方案。项目遵循最佳实践，注重安全性、可维护性和开发效率，适合构建从原型到生产环境的现代化 Web 应用。

核心技术栈与特性

后端：

FastAPI：高性能 Python Web 框架，支持异步编程，自动生成交互式 API 文档。
SQLModel：基于 Pydantic 和 SQLAlchemy 的 ORM，简化数据库操作。
Pydantic：用于数据验证和设置管理，确保数据一致性。
JWT 认证：实现安全的用户身份验证。
密码哈希：默认启用安全的密码加密机制。
电子邮件密码重置：支持基于电子邮件的密码恢复功能。

前端：

React：使用 TypeScript、Vite 和现代前端技术栈（如 Hooks）构建动态界面。
Chakra UI：提供美观的 Material Design 风格组件，支持暗黑模式。
自动生成前端客户端：通过 OpenAPI 自动生成与后端 API 交互的客户端代码。

数据库：

PostgreSQL：可靠的关系型数据库，支持复杂查询和大规模数据。
Alembic：用于数据库迁移，确保模型与数据库表结构一致。

部署与开发工具：

Docker Compose：支持开发和生产环境的容器化部署。
Traefik：作为反向代理和负载均衡器，支持自动 HTTPS 证书（通过 Let's Encrypt）。
GitHub Actions：实现 CI/CD 自动化，包含测试和部署流程。
Playwright：用于端到端测试，确保前后端交互的稳定性。

其他特性：

支持 CORS（跨源资源共享），便于前后端分离开发。
包含用户管理、权限控制、数据分页等实用功能。
提供交互式 API 文档（Swagger UI 和 ReDoc）。

项目亮点

开箱即用：项目预配置了用户系统、认证授权、CRUD 操作等常见功能，开发者可以快速上手，专注于业务逻辑开发。
高性能与现代化：FastAPI 的异步支持和 React 的高效渲染确保了应用的性能优越；TypeScript 和 Vite 进一步提升了前端开发体验。
生产就绪：集成了安全机制（如 JWT、密码哈希）、自动化测试和 CI/CD 管道，适合直接用于生产环境。
灵活可定制：通过 Copier 工具支持项目生成，开发者可以根据需求调整配置；支持多环境部署（开发、测试、生产）。
完善的文档与社区支持：项目包含详细的 README 和子目录文档（backend/README.md、frontend/README.md、deployment.md 等），并由活跃的社区维护（36.2k 星，6.9k Fork）。

使用场景

快速原型开发：适合创业公司或个人开发者快速构建 MVP（最小可行产品）。
全栈应用开发：为需要前后端分离、数据库交互和现代化部署的复杂 Web 应用提供基础框架。
学习与教育：适合学习 FastAPI、React、Docker 等技术的开发者，项目结构清晰，代码注释完善。
生产环境部署：通过 Docker 和 Traefik 的集成，支持高效、安全的部署流程。

如何使用

1. 直接克隆仓库

git clone https://github.com/fastapi/full-stack-fastapi-template.git my-project
cd my-project

然后根据 development.md 配置 Docker Compose 和环境变量（如 SECRET_KEY、POSTGRES_PASSWORD 等）。

2. 使用 Copier 生成项目

pip install copier
copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust

Copier 会提示输入项目名称、密钥等配置，生成定制化的项目文件。

3. 开发与部署

本地开发：使用 docker compose watch 启动开发环境，支持代码热重载。
测试：运行 bash ./scripts/test.sh 执行后端测试，或使用 Playwright 进行端到端测试。
部署：参考 deployment.md，通过 Docker Compose 和 Traefik 实现生产环境部署。

项目结构

full-stack-fastapi-template/
├── backend/                # FastAPI 后端代码
│   ├── app/               # 核心应用代码（模型、API、CRUD）
│   ├── scripts/           # 测试和启动脚本
│   ├── Dockerfile         # 后端 Docker 配置
│   └── README.md          # 后端开发指南
├── frontend/               # React 前端代码
│   ├── src/               # 前端源代码
│   ├── Dockerfile         # 前端 Docker 配置
│   └── README.md          # 前端开发指南
├── scripts/                # 项目级脚本
├── .env                    # 环境变量配置文件
├── docker-compose.yml      # Docker Compose 配置
├── deployment.md           # 部署指南
└── development.md          # 开发指南