如何在几分鐘内构建一个可用的 FastAPI 后端骨架

每次启动新的 FastAPI 项目时，我都陷入了土拨鼠之日。我需要重新设置目录结构、连接数据库、编写迁移文件、配置环境变量、构建 Dockerfile，以及配置 linter。在第一个真正的端点出现之前，很容易把整个晚上都浪费在这些例行公事上。

当然，你可以从之前的仓库复制结构。但它通常会有一堆旧的工作区、不必要的依赖和过时的库。搜索结果中的现成模板也很难完全符合需求，因为作者选择了 TortoiseORM 但你需要 SQLAlchemy 2.0，或者他们塞入了重量级的 Celery 而不是轻量级队列。

开发者 s3rius 的 FastAPI-template 仓库用不同的方式解决了这个问题。它不仅仅是一个静态模板，而是一个灵活的交互式项目生成器。

构造函数而非僵化模板

这个项目像终端问卷一样运作。你通过 pip、uv 或 Docker 启动工具，回答几十个问题，然后获得根据你需求定制的现成代码库。

生成器的主要优势在于灵活性。大多数模板都强制使用特定技术栈，但在这里你可以自己组装所需的组件集合。

选择你喜欢的数据库和 ORM

该工具不依赖单一库，而是支持多种流行的数据处理选项：

• SQLAlchemy 2.0 配合异步引擎
• TortoiseORM 配合 Aerich 迁移生成
• Piccolo ORM
• Ormar
• Beanie（用于 MongoDB）
• 原生 psycopg 驱动（无 ORM）

如果你根本不需要数据库，可以选择无数据存储选项。在这种情况下，代码不会有不必要的依赖和冗余的配置文件。

REST 或 GraphQL

默认情况下，生成器构建带有自动 Swagger 文档的经典 REST API。但如果你的前端更喜欢通过 GraphQL 工作，生成器会基于 Strawberry 库设置包装器。无需手动配置 schema 和类型即可开始。

后台任务和队列

模板作者添加了 Taskiq（一个现代的 Python 异步任务管理器）的集成，而不是笨重的 Celery。它完美契合 FastAPI 的整体异步架构。作为消息代理，你可以在生成过程中选择 Redis、RabbitMQ 或 Kafka。

开箱即用的监控和日志

模板已经内置了通常需要从单独文章中手动配置的现成集成：

• Prometheus 指标收集
• OpenTelemetry 追踪
• Sentry 错误发送
• Loguru 结构化日志

所有这些选项都通过简单的标志或交互菜单中的选择来切换。

快速开始

要运行该工具，你需要在机器上安装 Git、Python 和快速包管理器 uv。

生成器通过 pip 安装：

python3 -m pip install fastapi_template
fastapi_template

启动后，控制台中会出现分步问卷。你选择项目名称、所需的 DBMS、认证类型（JWT 或通过 fastapi-users 的 cookie）、CI/CD 格式（GitHub Actions 或 GitLab CI）以及附加服务。

生成器完成后，进入创建的文件夹并启动环境：

cd my_awesome_project
docker-compose up --build

如果你不想在本地安装包，可以通过 Docker 一行命令运行生成器：

docker run --rm -it -v "$(pwd):/projects" ghcr.io/s3rius/fastapi_template

通过 CLI 标志生成

如果你在公司中设置自动化微服务创建，可以禁用交互模式。该工具通过命令行参数接受所有参数：

fastapi_template \
  --name billing_service \
  --api-type rest \
  --db postgresql \
  --orm sqlalchemy \
  --migrations \
  --redis \
  --taskiq \
  --prometheus \
  --ci github \
  --quiet

此调用将创建一个已配置好的服务，包含 SQLAlchemy、Alembic 迁移、Taskiq 后台任务、指标和 GitHub pipeline，终端中不会有一个问题。

生成的项目内部有什么

生成的代码在结构上令人惊喜。没有把所有东西塞进一个文件的混乱 main.py。

架构被划分为逻辑层：

• web/api：按版本前缀和模块划分的路由
• db：数据库连接、模型和迁移配置
• services：业务逻辑和外部服务客户端
• settings.py：基于 pydantic-settings 的类型化设置

项目立即包含对基本结构覆盖率约 90% 的 pytest 测试、配置好的带有 linter 的 pre-commit，以及包含所有选定服务的现成 docker-compose.yml。你不需要为本地开发单独启动 Redis 或 PostgreSQL。

谁会发现这个项目有用

生成器非常适合两种场景。

第一种情况是快速启动个人项目和 MVP。当你想在周末测试一个假设时，不想花半天时间在样板代码上。

第二种情况是团队中的微服务标准化。你可以将此模板作为基础或使用其 CLI 接口，以便公司中的新服务按照单一标准创建，并已配置好遥测和测试。

如果你用 Python 编写并经常启动新的 FastAPI 后端，一定要收藏这个仓库。它会在开始时节省大量时间和精力。