写接口一时爽，改模型火葬场？别怕，这篇手把手带你避开所有暗礁。
📌 摘要
本文以实战为导向，从零开始搭建 FastAPI + SQLAlchemy 2.0 + Alembic 的数据库层。通过生活化比喻和踩坑案例，讲透异步引擎配置、模型定义新写法、迁移脚本生成与审核等核心环节，帮你建立一套可靠、可维护的数据库操作实践。适合所有被数据库折腾过的后端开发者。
🎯 开篇：你是不是也半夜被报警吵醒过？
“叮——” 线上服务报错了：sqlalchemy.exc.StatementError。原因？可能就是顺手改了个模型字段名，却忘了生成迁移脚本，导致生产环境表结构对不上。
这种经历，我相信不少朋友都有过。尤其是从 FastAPI + SQLAlchemy 起步的时候，异步怎么配？模型怎么写？Alembic 为什么总是识别不到变更？一个坑接一个坑。今天，咱们就来聊聊，从零到一搭一套靠谱的数据库层，顺便把我踩过的坑都给你标上警示牌。🎯
🚦 先理一下咱们要干的事
🔹 第一部分：为什么是这套组合？ 聊聊选型逻辑
🔹 第二部分：手把手搭环境 从配数据库到写第一个模型
🔹 第三部分：Alembic 接入与避坑 自动生成脚本的那些坑
🔹 第四部分：进阶思考 连接池、异步、以及工程化建议
🍽️ 一、为什么是 FastAPI + SQLAlchemy 2.0 + Alembic？
咱们可以把 API 比作一家餐厅：FastAPI 是那个手脚麻利的点餐员，能快速把客人的需求（HTTP请求）传给后厨；SQLAlchemy 就是后厨的食材管理员，负责管理所有食材（数据）的进出和记录；而 Alembic 则是食材管理员的变更日志本，每次新增食材或调整存储方式，都得在本子上记一笔，保证后厨和仓库一致。
SQLAlchemy 2.0 之后，语法更清爽了，但同时也带来了一些变化——比如必须用 Mapped 和 mapped_column，如果你还抱着 1.x 的写法，跑起来就会报错。别问我怎么知道的，我第一次升级项目时，整个 models.py 一片飘红。
🛠️ 二、从零开始搭环境（附代码，可复制）
📦 安装依赖
先装好这些包，注意版本：
pip install fastapi uvicorn sqlalchemy alembic asyncpg # asyncpg 是 PostgreSQL 异步驱动
这里多说一句：如果你用 MySQL，请装 aiomysql 或 asyncmy，千万别装错，否则异步引擎跑不起来。
🗂️ 项目结构
myproject/
├── app/
│ ├── __init__.py
│ ├── database.py # 引擎、会话配置
│ ├── models.py # SQLAlchemy 模型
│ └── main.py # FastAPI 应用
├── alembic.ini
└── alembic/ # 迁移目录
🔌 配置数据库连接（database.py）
这是最容易踩坑的地方。SQLAlchemy 2.0 推荐使用异步方式，但很多人照抄旧代码，配了个同步引擎，然后和 FastAPI 的异步路由打架。
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
from sqlalchemy.orm import DeclarativeBase
DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/dbname"
# 创建异步引擎
engine = create_async_engine(DATABASE_URL, echo=True) # echo=True 会打印SQL，开发时很有用
# 创建异步会话工厂
AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)
# 基类，所有模型都要继承它
class Base(DeclarativeBase):
pass
注意看，我用了 create_async_engine 和 async_sessionmaker，这才是异步的正确姿势。
如何从零开始搭建FastAPI+SQLAlchemy 2.0+Alembic数据库实战项目？
摘要：本文以实战为导向，从零开始搭建 FastAPI + SQLAlchemy 2.0 + Alembic 的数据库层。通过生活化比喻和踩坑案例，讲透异步引擎配置、模型定义新写法、迁移脚本生成与审核等核心环节，