FastAPI的初步学习（Django用户过来的）

我一直以来是Django重度用户。它有清晰的MVC架构模式、多应用组织结构。它内置用户认证、数据库ORM、数据库迁移、管理后台、日志等功能，还有强大的社区支持。再搭配上Django REST framework (DRF) ，开发起来效率极高。主打功能强大、易于使用。

曾经也用Flask开发过提供纯API不涉及数据库操作的项目，相对Django确实简洁、灵活。但没留下什么较好的深刻印象。

最近，听说朋友在用FastAPI开发项目，主打高性能和强大的异步处理能力。而且在网上看到「Flask已死，FastAPI是未来」的说法。于是开始学习FastAPI。

纯API的FastAPI项目

看了下官方文档：https://fastapi.tiangolo.com/zh/learn/

发现搭建一个纯API的小项目，用FastAPI确实好啊。

比如一个提供固定博文展示和邮件发送的项目，目录如下。在blogs.py、emails.py中配路由写业务逻辑就行。

fastapi-pure-api-case
├── routers
│   ├── blogs.py
│   └── emails.py
├── README.md
└── main.py

涉及数据库操作的多应用FastAPI项目

想到之前写过的有近20个子应用、完全数据库增删改查、数据model经常变化要重度维护数据库迁移文件的中型Django项目。我觉得用FastAPI适合微服务，这种复杂项目实现起来应该很难吧。看了官方文档，依然摸不着头脑。

一、我尝试用Django的目录结构，搭建个多子应用的FastAPI项目。类似结构如下：

my_project/
│── alembic/
│── alembic.ini
│── users/              # 用户管理应用
│   ├── urls.py         # 路由
│   ├── serializers.py  # Pydantic 模型
│   ├── views.py        # 业务逻辑
│   ├── models.py       # SQLAlchemy 模型
│   └── utlis.py        # 应用级工具集
│
│── blogs/              # 博客应用
│── ...                 # 其他应用
│
├── core/                   # 核心基础设施
│   ├── database.py         # 数据库连接
│   ├── settings.py         # 配置管理     		  
│   └── urls.py             # 路由集中配置
│
├── utils/                  # 公共工具
│   ├── auth.py             # 认证工具
│   └── logging.py          # 日志配置
├── main.py                 # 主入口文件
└── requirements.txt        # 依赖文件

按上述目录结构搞了一天，总感觉不伦不类的。但至少弄明白了三件事：

1、FastAPI中要轻松操作数据库，要自行选择第三方ORM工具，如SQLAlchemy 。创建数据Model要用到SQLAlchemy模型。数据库操作要显式创建并引用session。

2、Pydantic模型用来数据验证、数据序列化。与ORM是完全解耦的。

3、实现数据库迁移管理，要自行选择第三方工具，如alembic.ini。

二，一些成熟的项目实践参考

在自己探索一番觉得不太行后，想着FastAPI这么火，网上应该有一些比较成熟的组织项目结构的方案。

在一些搜索后，还真找到了一些：

FastAPI 最佳实践文档：https://github.com/zhanymkanov/fastapi-best-practices

FastAPI 最佳实践文档（中文翻译）：https://gitee.com/ktianc/fastapi-best-practices

FasAPI实践之MySQL：https://github.com/fastapi-practices/fastapi_sqlalchemy_mysql

FasAPI 最佳架构文档：https://fastapi-practices.github.io/fastapi_best_architecture_docs/

FastAPI最佳架构项目示例：https://github.com/fastapi-practices/fastapi_best_architecture

看了上面的项目，并实践后。我意识到只要架构做好，FastAPI也可以类似Django用来开发中大型项目，同时保持高性能。

FastAPI与Django的选择

体验下来。FastAPI的优势在于高性能和强大的异步处理能力，但相对Django开发效率会低很多。

对性能、高并发、异步处理要求没那么高的企业级应用，选择Django还是比较合适，有20年历史，很多方面有成熟解决方案。

对于大型系统，可结合两者优势：

• Django：用户认证、内容管理、后台运营
• FastAPI：移动端API、实时数据处理、微服务接口

这种架构既能利用 Django 的开发效率，又能发挥 FastAPI 的性能优势，是大型项目的理想选择。

功能	Django 内置支持	FastAPI 需要额外集成
ORM	Django ORM (强大且易用)	SQLAlchemy/SQLModel (需学习)
管理后台	Django Admin (开箱即用)	SQLAdmin/Django Admin 移植
用户认证	完整认证系统 (Session/Auth组)	需手动实现 (JWT/OAuth2)
表单处理	Form 和 ModelForm 系统	依赖 HTML 前端框架
模板引擎	Jinja2/Django 模板语言	需单独集成
路由系统	URLconf 自动处理	需手动组织 APIRouter
国际化	完整 i18n/l10n 支持	需第三方库

实际影响：新项目启动时，Django 可节省 40-60% 的初始配置时间。

FastAPI中型项目的一些目录结构参考

my_project/
├── apps/                   # 核心应用目录（类似 Django 的 apps）
│   ├── users/              # 用户管理应用
│   │   ├── routers.py      # 路由
│   │   ├── schemas.py      # Pydantic 模型
│   │   ├── services.py     # 业务逻辑
│   │   ├── models.py       # SQLAlchemy 模型
│   │   └── dependencies.py # 应用级依赖
│   │
│   ├── products/           # 产品管理应用
│   ├── orders/             # 订单管理应用
│   └── ...                 # 其他应用
│
├── core/                   # 核心基础设施
│   ├── database.py         # 数据库连接
│   ├── config.py           # 配置管理
│   ├── middleware.py       # 中间件
│   ├── exceptions.py       # 异常处理
│   └── dependencies.py     # 全局依赖项
│
├── tests/                  # 测试目录
│   ├── unit/               # 单元测试
│   └── integration/        # 集成测试
│
├── utils/                  # 公共工具
│   ├── auth.py             # 认证工具
│   └── logging.py          # 日志配置
│
├── static/                 # 静态文件
├── templates/              # Jinja2 模板（可选）
├── alembic/                # 数据库迁移
├── main.py                 # 主入口文件
└── requirements.txt        # 依赖文件

fastapi-project
├── alembic/
├── src
│   ├── auth
│   │   ├── router.py
│   │   ├── schemas.py  # pydantic models
│   │   ├── models.py  # db models
│   │   ├── dependencies.py
│   │   ├── config.py  # local configs
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   ├── service.py
│   │   └── utils.py
│   ├── aws
│   │   ├── client.py  # client model for external service communication
│   │   ├── schemas.py
│   │   ├── config.py
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   └── utils.py
│   └── posts
│   │   ├── router.py
│   │   ├── schemas.py
│   │   ├── models.py
│   │   ├── dependencies.py
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   ├── service.py
│   │   └── utils.py
│   ├── config.py  # global configs
│   ├── models.py  # global models
│   ├── exceptions.py  # global exceptions
│   ├── pagination.py  # global module e.g. pagination
│   ├── database.py  # db connection related stuff
│   └── main.py
├── tests/
│   ├── auth
│   ├── aws
│   └── posts
├── templates/
│   └── index.html
├── requirements
│   ├── base.txt
│   ├── dev.txt
│   └── prod.txt
├── .env
├── .gitignore
├── logging.ini
└── alembic.ini

单app的结构模式

模块	java	fastapi_best_architecture
视图	controller	api
数据传输	dto	schema
业务逻辑	service + impl	service
数据访问	dao / mapper	crud
模型	entity	model