为什么 FastAPI 后端要走 Clean Architecture?fastapi-clean-example 项目架构全解析
为什么 FastAPI 后端要走 Clean Architecture?fastapi-clean-example 项目架构全解析
如果你正在用 FastAPI 开发生产级后端,大概率会经历这样的困境:业务逻辑散落在路由函数里、数据库细节渗透到每一层、换个 ORM 就要重写一半代码。fastapi-clean-example 就是一个用 FastAPI 落地 Clean Architecture(整洁架构)的实战示例项目——零有状态全局变量(依赖注入)、低耦合(依赖倒置)、战术 DDD、CQRS、规范的事务管理(UoW),还内置了会话认证与上下文 RBAC 权限体系,是学习 FastAPI 后端架构设计的绝佳参照。
下面这篇文章带你从零理解:它为什么这样分层、一个请求是如何穿过每一层的,以及普通项目能直接抄走哪些做法。
一、它解决什么问题:FastAPI 后端的 4 个典型坑
先看看"不设计"时常见的代码结构:
| 常见做法 | 带来的问题 |
|---|---|
路由函数里直接写业务逻辑 + await session.execute(...) |
换一个入口(CLI、gRPC)业务逻辑就得重写 |
| 用全局单例管理数据库引擎、Redis 客户端 | 无法替换、无法测试、并发下难隔离 |
权限判断用一堆 if user.role == "admin" 散落在各处 |
规则重复、难以审计,改一处漏一处 |
异常直接 raise HTTPException |
业务错误和 HTTP 协议耦合,非 HTTP 场景没法复用 |
fastapi-clean-example 的解法可以概括为一句话:业务核心(core)不知道 FastAPI 的存在,FastAPI 也不知道数据库的实现细节,两边靠"接口(端口)+ 适配(适配器)"对话。
二、一眼看懂:四层目录结构 🗂️
项目源码全部位于 src/app/,分为 4 层,依赖方向永远由外向内:
app/
├── main/ # 启动层:组装依赖、加载配置、挂中间件(只依赖别人)
├── inbound/ # 入站适配:HTTP 路由、错误码映射、Cookie 中间件
├── core/ # 业务核心:命令、查询、实体、值对象、权限规则(不依赖任何外层)
└── outbound/ # 出站适配:SQLAlchemy 持久化、bcrypt、JWT 会话等
- main:src/app/main/run.py 是应用工厂
make_app(),负责加载配置、创建 dishka 依赖注入容器、挂载路由与全局异常处理器,是"组装一切"的地方。 - inbound:HTTP 请求进来后的第一站,只负责"翻译"——把 HTTP 请求转成业务 Request,把业务响应/异常翻译成 HTTP 状态码。
- core:项目的灵魂。命令、查询、领域服务、权限规则全在这里,禁止 import 任何外层模块。
- outbound:所有"和外部世界打交道"的东西——PostgreSQL(SQLAlchemy + Alembic)、bcrypt 密码哈希、JWT 签发。
这套分层不是口头约定,而是写死在 pyproject.toml 的 import-linter 契约里的:
[[tool.importlinter.contracts]]
id = "clean-architecture"
name = "inner must not import outer"
type = "layers"
layers = ["(main)", "inbound", "outbound", "core"]
只要有人不小心在 core 里 import 了 SQLAlchemy,CI 的依赖检查会直接失败——架构纪律交给工具,而不是靠自觉。
三、请求之旅:一条"创建用户"请求如何穿过四层 🚀
以最核心的 POST /users 为例,完整链路是:
1️⃣ inbound:路由只做三件事
src/app/inbound/http/users/create_user.py 中的路由函数没有任何业务逻辑:
- 接收
CreateUserRequest,通过 DI 拿到CreateUser交互器并执行; - 用
error_map声明"哪种业务异常对应哪个 HTTP 状态码",如UsernameAlreadyExistsError → 409、AuthorizationError → 403; - 出错时记录日志(
on_error=log_info)。
错误码到 HTTP 状态的映射规则集中在 src/app/inbound/http/errors/,比如 503 的统一文案定义在 rules.py——每个路由独立声明自己的错误契约,这就是"per-route error handling"的含义。
2️⃣ core:命令交互器编排业务
src/app/core/commands/create_user.py 的 CreateUser.execute() 完整体现了"用例编排":
- 取出当前用户,调用
authorize(CanManageRole(), ...)做上下文权限校验; - 把裸字符串包装成值对象
Username、RawPassword——校验规则只存在于值对象内部(例如用户名长度、字符集规则见 src/app/core/common/value_objects/username.py); - 领域服务
UserService完成密码哈希与实体构造; - 通过端口
UserTxStorage.add()暂存、Flusher.flush()触发数据库唯一性检查、TransactionManager.commit()提交事务(即 UoW 三部曲); - 返回
CreateUserResponse,全程无 FastAPI、无 SQLAlchemy。
3️⃣ outbound:端口由适配器实现
core 只声明"我需要一个 UserTxStorage",这个 Protocol 定义在 src/app/core/commands/ports/user_tx_storage.py。真正实现藏在 src/app/outbound/adapters/sqla_user_tx_storage.py——它把 SQLAlchemyError 统一转译成领域异常 StorageError,数据库方言细节就此被隔离。
💡 想验证"数据库可替换"?把
SqlaUserTxStorage换成基于 Mongo 的实现,core 目录一行都不用改。这就是依赖倒置(DIP)。
四、CQRS:命令与查询的读写分离 📖
项目在 core 层把"写"和"读"拆成了两个互不依赖的包:
- commands/:src/app/core/commands/ ——
create_user、activate_user、grant_admin等写操作,需要事务与权限管理,端口强调"Transactional: commit required"。 - queries/:src/app/core/queries/ —— 如 list_users.py,只做只读查询,自带分页(offset_pagination.py)与排序(sorting.py)支撑工具。
- common/:实体(user.py)、值对象、领域服务、权限体系,命令与查询共享。
import-linter 里专门有三条 forbidden 契约,强制 commands 与 queries 互不 import、common 不 import 两者——读写路径从此可以独立演进:查询侧未来换 Redis 缓存、甚至换搜索引擎,都不影响写路径。
五、权限体系:上下文 RBAC 是怎么设计的 🔐
很多项目的权限判断是 if role in (...) 的硬编码。fastapi-clean-example 把权限抽象成了"可组合的谓词":
- Permission:src/app/core/common/authorization/permissions.py 中每个权限是一个小类,
is_satisfied_by(context)返回布尔值,如CanManageSelf(自己管自己)、CanManageSubordinate(上级管下级)、CanManageRole(能否授予某角色)。 - 角色层级:role_hierarchy.py 用一张映射表声明
super_admin → admin/user、admin → user的管理关系,规则集中在一个文件,全局可审计。 - 组合权限:composite.py 支持 AND/OR 组合多个 Permission,满足"上下文 RBAC"(判断依据是"谁在对谁做什么",而不是静态角色)。
- 调用侧非常干净:一行
authorize(CanManageRole(), context=RoleManagementContext(subject=..., target_role=...)),不满足就抛出AuthorizationError,最终由 inbound 层映射成 403。
六、依赖注入:消灭一切有状态全局变量 🧩
项目用 dishka 作为 DI 容器,所有依赖的生命周期由作用域(Scope)声明:
- APP 级:数据库引擎、bcrypt 线程池——应用启动时创建一次,关闭时优雅释放;
- REQUEST 级:数据库会话、当前用户上下文——每请求一份,天然隔离并发。
依赖的组装集中在 src/app/main/ioc/:provider_registry.py 汇总核心与出站 Provider,outbound.py 里能看到引擎连接池参数、bcrypt 线程池(ThreadPoolExecutor + 信号量限流)的完整装配。
这带来两个直接收益:
- 测试零成本替换:
make_app(*di_providers)支持传入覆盖 Provider,集成测试(tests/integration/with_infra/)可以注入任意测试基础设施; - 无全局变量:不再需要"启动时初始化 engine 全局单例"这类隐式依赖,容器就是唯一的依赖来源。
七、质量护栏:这套架构如何被"锁住" 🛡️
架构设计最怕腐化。项目的工程化护栏相当完整(配置见 pyproject.toml,常用命令见 Makefile):
| 工具 | 用途 |
|---|---|
import-linter |
强制分层契约:inner 不得 import outer;CQRS 读写隔离 |
mypy --strict |
全项目严格类型检查(含 pydantic/SQLAlchemy 插件) |
ruff |
60+ 条 lint 规则,禁止 TYPE_CHECKING(用重构解决循环导入而非掩盖) |
pytest |
分层测试:unit / integration(no_infra / with_infra) / smoke / sanity |
deptry / pip-audit |
依赖健康度与漏洞扫描 |
分层测试结构也值得借鉴:unit 只测 core(纯逻辑,无数据库);integration/no_infra 验证组装正确性;integration/with_infra(如 test_create_user.py)跑真实 PostgreSQL 全链路。
八、快速上手:如何运行这个项目 🏃
环境要求 Python 3.13,使用 uv 管理依赖,推荐 Docker 一键启动:
git clone https://gitcode.com/gh_mirrors/fas/fastapi-clean-example
cd fastapi-clean-example
# Docker 方式:拉取并启动(含数据库)
make upd
# 本地方式
uv sync
source .venv/bin/activate
alembic upgrade head # 执行数据库迁移(Alembic 脚本见 src/app/outbound/persistence_sqla/alembic/versions/)
uvicorn app.main.run:make_app --host 0.0.0.0 --port 8000 --reload
环境变量模板参考 env.example;跑完测试 make check,停止 make down。打开 /docs 即可看到完整的 OpenAPI 文档。
九、总结:哪些模式可以直接搬进你的项目?
- 分层 + 依赖方向约束:哪怕项目不大,"core 不 import 外层"这条规则加上 import-linter 检查,成本极低收益极高;
- 值对象封装校验:把
Username这类规则收拢成不可变对象,消灭散落的if len(name) > 20; - per-route error map:每个路由显式声明异常→状态码映射,告别全局
try/except大杂烩; - Permission 谓词 + 角色层级表:权限规则集中、可组合、可审计;
- DI 容器管理生命周期:告别全局变量,测试时任意替换实现。
Clean Architecture 对小型 CRUD 项目或许偏重,但只要你的 FastAPI 后端要长期演进、多人协作,fastapi-clean-example 展示的这套"分层 + 端口适配 + CQRS + DI"组合,就是值得对标的工程基线。🎯