如何避免0到1阶段使用FastAPI、PostgreSQL和Tortoise ORM的常见坑？

你是不是也经历过这种纠结：想用 FastAPI 写个带数据库的项目，却在 SQLAlchemy 和 Tortoise ORM 之间反复横跳？ 欢迎新老朋友👋！作为一名在代码堆里摸爬滚打多年的全栈程序媛，今天咱们就聊聊 FastAPI + PostgreSQL + Tortoise ORM 这套组合拳。我会把我自己踩过的坑、修复的数据迁移事故，全都摊开来跟你讲。这不是官方文档的复述，而是一份可以直接拿来用的「避坑实战笔记」。

---

🎯 本文能帮你解决什么？ ✅ 快速搭好 FastAPI + PostgreSQL 的项目骨架 ✅ 搞懂 Tortoise ORM 的模型定义和关系用法（附代码片段） ✅ 用 Aerich 优雅地管理数据库迁移，不再手动改表 ✅ 整合 Jinja2 模板，让 ORM 查询结果直接渲染到前端 ✅ 总结 5 个最容易翻车的坑，附解决方案 📌 主要内容脉络 🔸 为什么要选 Tortoise ORM？——异步世界里的「翻译官」 🔸 环境搭建与配置——别在第一步就摔跤 🔸 模型定义与关系——像搭积木一样建表 - 字段类型避坑指南 - 一对多、多对多实战 🔸 数据迁移 Aerich——数据库的「版本控制」 - 初始化、变更、回滚全流程 🔸 模板渲染——把数据变成页面 🔸 常见问题 & 急救包 ⚙️ 第一部分：为什么是 Tortoise ORM？ 你可能会问：FastAPI 官方文档里推荐用 SQLAlchemy 啊，为什么偏要用 Tortoise？ 说实话，复杂大型项目还是老老实实配 SQLAlchemy + 异步驱动，它毕竟经过了时间的沉淀，够稳。但对于新手新项目或快速原型来说，就有点像穿着皮鞋跑步——能跑，但别扭。直到我发现了 Tortoise ORM，它简直就是为异步 Python 而生的。你可以把它想象成一个「实时翻译官」，你写 Python 对象，它自动翻译成 SQL，而且全程异步非阻塞，跟 FastAPI 的 async/await 天生一对。 💡 核心优势：类 Django ORM 的语法（上手快）、全异步支持、自带分页和信号，最关键的是——配合 Aerich 做迁移，比 Alembic 在异步环境下的配置简单太多了！ 🔧 第二部分：搭建项目骨架（含配置代码） 好，咱们先来搭环境。假设你已经有了 Python 3.8+ 和 PostgreSQL 实例。 # 安装依赖 pip install fastapi uvicorn[standard] tortoise-orm[asyncpg] aerich asyncpg tomlkit jinja2 这里提醒一句：如果你偶尔要跑一些同步脚本，或者用一些依赖 psycopg2 的工具（比如某些数据库管理 GUI），那装个 psycopg2-binary 也无妨。记得用 binary 版本，别给自己找编译的麻烦 😉，千万别学我当初偷懒，直接用 psycopg2 而不是 psycopg2-binary，结果部署到 Linux 上编译报错……用 binary 版本省心很多。