为什么 FastAPI 后端要走 Clean Architecture?fastapi-clean-example 项目架构全解析

原创2026-11-19 09:07:1372 阅读

为什么 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() 完整体现了"用例编排":

  1. 取出当前用户,调用 authorize(CanManageRole(), ...) 做上下文权限校验;
  2. 把裸字符串包装成值对象 Username、RawPassword——校验规则只存在于值对象内部(例如用户名长度、字符集规则见 src/app/core/common/value_objects/username.py);
  3. 领域服务 UserService 完成密码哈希与实体构造;
  4. 通过端口 UserTxStorage.add() 暂存、Flusher.flush() 触发数据库唯一性检查、TransactionManager.commit() 提交事务(即 UoW 三部曲);
  5. 返回 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 层把"写"和"读"拆成了两个互不依赖的包:

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 + 信号量限流)的完整装配。

这带来两个直接收益:

  1. 测试零成本替换:make_app(*di_providers) 支持传入覆盖 Provider,集成测试(tests/integration/with_infra/)可以注入任意测试基础设施;
  2. 无全局变量:不再需要"启动时初始化 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 文档。

九、总结:哪些模式可以直接搬进你的项目?

  1. 分层 + 依赖方向约束:哪怕项目不大,"core 不 import 外层"这条规则加上 import-linter 检查,成本极低收益极高;
  2. 值对象封装校验:把 Username 这类规则收拢成不可变对象,消灭散落的 if len(name) > 20;
  3. per-route error map:每个路由显式声明异常→状态码映射,告别全局 try/except 大杂烩;
  4. Permission 谓词 + 角色层级表:权限规则集中、可组合、可审计;
  5. DI 容器管理生命周期:告别全局变量,测试时任意替换实现。

Clean Architecture 对小型 CRUD 项目或许偏重,但只要你的 FastAPI 后端要长期演进、多人协作,fastapi-clean-example 展示的这套"分层 + 端口适配 + CQRS + DI"组合,就是值得对标的工程基线。🎯

登录后查看全文
fastapi-clean-example