FastAPI Best Architecture (fba) 学习指南

一套基于 FastAPI 的企业级后端架构，遵循「三层架构」设计，支持 Python 3.12+。本学习指南旨在帮助你由浅入深、循序渐进地掌握 fba 框架。
📊 本指南每章都配有 Mermaid 流程图，在 GitHub、Typora、VS Code、Obsidian 中可直接渲染查看。

一、这是什么？

fba（FastAPI Best Architecture） 是一个基于 FastAPI 的开源后端架构模板。它不只是教你"怎么写一个接口"，而是把真实团队协作中会遇到的通用问题——分层、权限、日志、缓存、部署、可维护性——都提前帮你搭好。

用一句话概括：它是一套"开箱即用"的企业级 FastAPI 项目骨架，让你把精力花在业务上，而不是重复搭架子上。

二、技术栈速览

技术	作用	一句话解释
FastAPI	Web 框架	处理 HTTP 请求，性能高、自带交互式文档
SQLAlchemy 2.0	ORM	用 Python 类操作数据库，不用手写 SQL
Pydantic v2	数据校验	自动校验请求/响应数据格式
PostgreSQL / MySQL	数据库	持久化存储数据
Redis	缓存/内存库	加速访问、存 token、限流计数等
Celery	异步任务	处理耗时的后台任务（发邮件、报表等）
Docker	容器部署	一键打包部署，环境一致

三、整体学习路线图

四、学习路线总览

学习分为 四个阶段，每个阶段都有明确的学习目标和对应章节，建议按顺序阅读，每读完一章在进度表中打勾。

阶段一：入门基础（先跑起来）

目标：理解 fba 是什么、能干什么，把项目成功启动起来，看懂整体结构。

阶段二：核心开发（学会写接口）

目标：掌握"一条业务从数据库到接口"的完整开发流程，能独立开发一个增删改查模块。

阶段三：进阶能力（掌握企业级特性）

目标：掌握配置、认证权限、缓存、异步任务等企业级必备能力。

阶段四：工程化与部署（落地到生产）

目标：掌握插件、代码生成、AI 辅助开发、容器化部署和可观测性，能交付生产级项目。

五、进度跟踪表

建议打印或复制到你的笔记里，每完成一章打个勾 ✅

章节	主题	状态
01	框架概览	☐
02	快速开始	☐
03	项目结构	☐
04	三层架构	☐
05	数据模型 Model	☐
06	数据校验 Schema	☐
07	路由 Router	☐
08	Service 与 CRUD	☐
09	统一响应与异常	☐
10	会话与事务	☐
11	配置系统	☐
12	认证与权限	☐
13	缓存系统	☐
14	异步任务 Celery	☐
15	时区与国际化	☐
16	插件系统	☐
17	代码生成器	☐
18	AI 辅助开发	☐
19	部署与可观测性	☐
20	实战与回顾	☐

六、使用建议

先跑起来，再抠细节：第 1-2 章先让项目启动，后面遇到具体模块再回头查。
动手写代码：每一章都配有示例，建议跟着敲一遍，而不是只看。
结合流程图理解：每章的 Mermaid 图是"骨架"，先看图建立整体认知，再读细节。
结合官方文档：本指南是"通俗导读"，深入学习某个特性时，可对照官方文档的对应章节。
善用 AI 工具：fba 官方提供了 skills 和 LLMs.txt，能让 Claude Code、Cursor 等 AI 直接读懂项目规范（见第 18 章）。

每章的统一结构

每个章节都遵循统一结构，方便自学：

学习目标 → 核心概念（含流程图）→ 代码示例 → 常见疑问（FAQ）→ 关键要点回顾

官方文档：https://docs.fba.wu-clan.cc/fastapi_best_architecture_docs/ 项目仓库：https://github.com/fastapi-practices/fastapi-best-architecture

FastAPI Best Architecture (fba) 学习指南 ​

一、这是什么？ ​

二、技术栈速览 ​

三、整体学习路线图 ​

四、学习路线总览 ​

阶段一：入门基础（先跑起来） ​

阶段二：核心开发（学会写接口） ​

阶段三：进阶能力（掌握企业级特性） ​

阶段四：工程化与部署（落地到生产） ​

五、进度跟踪表 ​

六、使用建议 ​

每章的统一结构 ​