FastAPI工程化实践：模板选型、生态扩展与项目结构

FastAPI 的官方文档写得足够好，照着 Tutorial 半小时就能跑出能用的接口。但真正把 FastAPI 用到项目里时，第一道坎往往不是语法，而是工程化：项目结构怎么组织？配置怎么管理？数据库 session 怎么注入和回收？这些问题官方刻意不给标准答案（这正是它区别于 Django 的设计哲学），结果就是十个人写出来的 FastAPI 项目十个样。

这篇文章整理我在搭建 FastAPI 项目时参考过的模板、扩展和最佳实践，以及选型过程中的一些取舍，希望能给同样踩过坑的人一些参考。

先想清楚：你需要什么样的项目模板

FastAPI 的项目模板大致分两派，选错了后面会很别扭。

全栈派：把前端 + 后端 + 部署一整套打包给你。代表是官方的 full-stack-fastapi-template（FastAPI 作者亲自维护），包含 SQLModel + PostgreSQL + React + Docker Compose + CI，甚至连用户注册、密码找回都写好了。如果你要做一个完整的 Web 产品，这是最好的起点；但如果你只是要一个纯后端 API 服务，它就显得过重——前端、Traefik 配置这些都要自己动手删。

骨架派：只给你后端的分层结构和基础封装，剩下的自己搭。我收集并对比过的几个：

模板	特点	适合谁
fastapi-skeleton	分层清晰的项目骨架	想要干净结构、自己掌控依赖的人
fast-api-template	代码接口设计值得参考	想学习 RESTful 接口组织方式的人
fastapi-starter	内置配置管理、统一错误处理、统一返回结构	快速起内部项目
fastapi_tortoise_mysql	Tortoise ORM + MySQL 组合	不在 SQLAlchemy 阵营的人

我的经验是：先把官方全栈模板完整跑一遍，理解它的分层思路（api / core / models / crud / services）和依赖注入的用法，然后再决定是裁剪它还是选一个轻量骨架。直接上手轻量骨架，往往因为缺少参照系，分不清哪些封装是必要的、哪些是过度设计。

生态扩展：哪些值得引入

fastapi-sqla：SQLAlchemy 集成

自己封装 SQLAlchemy 的 session 管理不算难，但有几个细节容易踩坑：请求结束后的 session 回收、测试时的事务回滚、分页查询。fastapi-sqla 把这些都处理好了，支持 asyncio、SQLModel 和 pytest，可用于生产环境：

from fastapi import FastAPI
from fastapi_sqla import SqlaSession, setup

app = FastAPI()
setup(app)

@app.get("/users")
def list_users(session: SqlaSession):
    ...  # session 开箱即用，请求结束自动回收

注入即用的 SqlaSession 比自己写 Depends(get_db) 再手动 try/finally 省心不少。

fastapi-crudrouter：CRUD 路由生成

给定模型，自动生成一整套增删改查路由：

from fastapi import FastAPI
from pydantic import BaseModel
from fastapi_crudrouter import MemoryCRUDRouter as CRUDRouter

class Potato(BaseModel):
    id: int
    color: str
    mass: float

app = FastAPI()
app.include_router(CRUDRouter(schema=Potato))

我对它的定位是原型期神器：验证想法、给前端先供接口的时候非常好用。但业务复杂之后，自定义查询条件、权限校验、联表查询这些需求一上来，自动生成的路由反而成了束缚，终究要回到手写路由。所以用它时要有心理预期：它是脚手架，不是承重墙。

SQLAlchemy-file：模型文件附件

把文件作为字段直接挂在 SQLAlchemy 模型上，存储后端可以是本地磁盘、Amazon S3、Google Storage 等（基于 Apache Libcloud）。适合”模型带附件”这类场景，比如文章封面图、订单附件，比自己在模型里存一个 url 字符串、再手动管理上传和删除要优雅得多。

最佳实践：值得反复读的两个资源

fastapi-best-practices

作者在生产环境用了多年 FastAPI 后的经验总结，是我读过的 FastAPI 工程化资料里质量最高的一份。几条我印象最深的原则：

按领域划分项目结构（posts/、users/ 各自成包，模型、路由、schema 内聚在里面），而不是按技术分层堆出几个大目录
IO 操作必须用异步路由：在 async 路由里写同步阻塞调用（比如 requests、time.sleep）会卡住整个事件循环，这是新手最常犯、也最隐蔽的错误
配置统一走 Pydantic Settings，不要让 os.getenv 散落各处
数据库 session 等资源的创建与回收交给依赖注入，业务函数只管声明需要什么

FastAPI 框架系列文章

如果刚接触 FastAPI，这个系列文章把基础讲得比较细，适合入门阶段配合官方文档一起看。

总结：我的默认组合

经过几轮项目折腾，我现在起 FastAPI 项目的默认姿势是：

以官方全栈模板的分层思路为蓝本（纯 API 项目就砍掉前端部分）
ORM 用 SQLAlchemy 2.x + Alembic 做迁移，session 管理交给 fastapi-sqla
配置用 pydantic-settings 集中管理
原型阶段可以用 fastapi-crudrouter 快速供接口，业务稳定后逐步替换为手写路由
项目结构拿不准时，回头翻 fastapi-best-practices

模板解决的是”从 0 到 1”的速度，最佳实践解决的是”从 1 到 100”的可维护性，两者都值得花点时间。