整洁架构

学习目标

• 能解释“整洁架构”如何把实体、用例、接口适配器和框架驱动器按政策层级组织，并让所有源码依赖只指向更内层
• 能逐项定位 实体、用例、接口适配器、框架与驱动器、依赖规则、跨边界通信，并说明每个概念在当前来源边界内承担什么责任
• 能按 接收外部请求 → 转换输入数据 → 执行应用用例 → 调用输出端口 → 适配外部呈现 推演“无 Web 测试”，检查“跨圆环依赖向内，内层不知道外层名称；边界数据只包含内层可以理解的简单结构”
• 能注入“用圆环数量做形式检查，却让实体注解 ORM、用例接收 HTTP Request 并返回数据库 Row”，依据源码依赖图、用例端口、边界 DTO、无框架测试、数据库和界面替换结果定位越界、撤销并用同一情境重放

为什么从“按政策的抽象层级决定边界，而不是按技术目录分组；所有外部机制通过适配器服务内层用例”开始

把实体、用例、接口适配器和框架驱动器按政策层级组织，并让所有源码依赖只指向更内层。本页先画责任和依赖，再沿具体情境执行决策，最后主动制造一个边界违规；这种顺序把术语变成可以验证、推翻和恢复的设计合同。

“整洁架构”不是技术采购建议。它处理的是规则放在哪里、模型在哪个语境内成立、哪些变化可以被隔离，以及团队如何判断一条边界已经被穿透。最终功能可运行，只能证明快乐路径存在，不能证明结构允许安全演进。

来源、版次与课程边界

四层名称、独立性目标、Dependency Rule 与跨边界通信均可在作者原始文章中核对；本页不把图形圆环数量当成原书强制模板。

本专题不是某一本既有书的中文版，也不是把多位作者的文章拼成“原著章节”。课程主干分别取自 Eric Evans 的领域驱动设计体系与 Robert C. Martin 的整洁架构体系；CQRS、事件溯源和六边形架构始终标为扩展。以下链接承担不同事实责任：

• Pearson: Clean Architecture：核对 Robert C. Martin、第一版、2017 年与正式目录范围
• Robert C. Martin: The Clean Architecture：核对独立性目标、四层、依赖规则、跨边界控制流与简单边界数据

本页采用独立中文重写。能从公开全文或授权摘要核对的定义才作为来源事实；项目情境、交互实验、取舍表和练习答案均为本站教学设计。

核心概念与可观察责任

实体

封装企业范围内最通用、最关键的业务规则；外部应用改变时，实体规则应尽量保持稳定。 在“无 Web 测试”中，观察重点是跨圆环依赖向内，内层不知道外层名称；边界数据只包含内层可以理解的简单结构。

用例

实现应用特定业务规则，编排实体完成用户目标；界面和数据库变化不应改变用例的业务意图。 在“数据库迁移”中，观察重点是源码依赖图、用例端口、边界 DTO、无框架测试、数据库和界面替换结果。

接口适配器

在内外层方便使用的数据形状之间转换，例如 Controller、Presenter 与 Gateway，不把外层格式泄漏到内层。 在“无 Web 测试”中，观察重点是跨圆环依赖向内，内层不知道外层名称；边界数据只包含内层可以理解的简单结构。

框架与驱动器

Web 框架、数据库、设备和外部服务位于最外层，是可替换工具；系统核心不应围绕它们塑形。 在“数据库迁移”中，观察重点是源码依赖图、用例端口、边界 DTO、无框架测试、数据库和界面替换结果。

依赖规则

源码依赖只能指向内层，内层不能提及外层声明的名称；这条规则比图中画几圈更重要。 在“无 Web 测试”中，观察重点是跨圆环依赖向内，内层不知道外层名称；边界数据只包含内层可以理解的简单结构。

跨边界通信

控制流越过边界时可借助依赖倒置，参数使用简单数据结构，避免把外层框架对象带入用例与实体。 在“数据库迁移”中，观察重点是源码依赖图、用例端口、边界 DTO、无框架测试、数据库和界面替换结果。

一条可执行的设计判断

本页采用以下判断链：按政策的抽象层级决定边界，而不是按技术目录分组；所有外部机制通过适配器服务内层用例。正常情况下必须持续保持“跨圆环依赖向内，内层不知道外层名称；边界数据只包含内层可以理解的简单结构”；反例“用圆环数量做形式检查，却让实体注解 ORM、用例接收 HTTP Request 并返回数据库 Row”只改变一个关键条件，便于定位因果。

观察项	本页合同
最小正常情境	不启动 HTTP Server，直接执行创建订单用例
边界或迁移情境	从 SQL Gateway 切换到内存 Gateway
必须保持	跨圆环依赖向内，内层不知道外层名称；边界数据只包含内层可以理解的简单结构
首要违规	用圆环数量做形式检查，却让实体注解 ORM、用例接收 HTTP Request 并返回数据库 Row
验收证据	源码依赖图、用例端口、边界 DTO、无框架测试、数据库和界面替换结果

先预测，再操作三个本页实验

⚡分步1 / 3

1. 1
2. 2
3. 3

实验一：边界与模型地图

操作前先预测“无 Web 测试”里哪一侧拥有规则、哪一侧只是技术或协作细节。切换概念和情境后，检查“按政策的抽象层级决定边界，而不是按技术目录分组；所有外部机制通过适配器服务内层用例”是否仍能解释三块区域的责任。

Boundary model

整洁架构：边界与责任地图

把实体、用例、接口适配器和框架驱动器按政策层级组织，并让所有源码依赖只指向更内层

切换最小情境

无 Web 测试数据库迁移

定位正式概念

实体用例接口适配器框架与驱动器依赖规则跨边界通信

architecturedomaindesign-05 · 当前观察

实体：不启动 HTTP Server，直接执行创建订单用例

区域 1实体与用例

企业政策和应用政策位于内层

↓

区域 2接口适配器

转换控制流与数据形状

↓

区域 3框架与驱动器

可替换的界面、数据库和设备

情境验收

输入端口接收简单请求模型，实体和用例独立完成规则

上一步重置播放下一步

易错边界与取舍

练习与答案

练习

问题 1：概念—边界—证据对照。 完成以下逐项核对：

1. 实体：写出它所在的边界、允许的依赖方向、一个最小反例和一份可观察证据。
2. 用例：写出它所在的边界、允许的依赖方向、一个最小反例和一份可观察证据。
3. 接口适配器：写出它所在的边界、允许的依赖方向、一个最小反例和一份可观察证据。
4. 框架与驱动器：写出它所在的边界、允许的依赖方向、一个最小反例和一份可观察证据。
5. 依赖规则：写出它所在的边界、允许的依赖方向、一个最小反例和一份可观察证据。
6. 跨边界通信：写出它所在的边界、允许的依赖方向、一个最小反例和一份可观察证据。

查看答案

对每个概念先确定它属于业务政策、模型协作还是外部技术，再画允许的依赖方向。用“不启动 HTTP Server，直接执行创建订单用例”建立正常基线，用“用圆环数量做形式检查，却让实体注解 ORM、用例接收 HTTP Request 并返回数据库 Row”作为单一反例，最后从源码依赖图、用例端口、边界 DTO、无框架测试、数据库和界面替换结果中找第一处不一致。

问题 2：最小情境推演。 怎样验证“无 Web 测试”没有靠最终功能碰巧通过？

查看答案

按 接收外部请求 → 转换输入数据 → 执行应用用例 → 调用输出端口 → 适配外部呈现 保存每步状态，预期结果是“输入端口接收简单请求模型，实体和用例独立完成规则”。最终输出之外，还要逐步确认“跨圆环依赖向内，内层不知道外层名称；边界数据只包含内层可以理解的简单结构”；任一中间状态越界都应拒绝当前设计。

问题 3：替代方案与恢复。 注入“用圆环数量做形式检查，却让实体注解 ORM、用例接收 HTTP Request 并返回数据库 Row”后，怎样比较修复与更简单方案？

查看答案

先保留故障前的源码依赖图、用例端口、边界 DTO、无框架测试、数据库和界面替换结果，再记录首个越界位置。分别实施最小修复和删除多余模式的方案，用同一个“从 SQL Gateway 切换到内存 Gateway”重放；选择仍满足“实体和用例不变，接口适配器替换且合同测试继续通过”且依赖更少的方案。

本页小结

• 整洁架构的核心判断是：按政策的抽象层级决定边界，而不是按技术目录分组；所有外部机制通过适配器服务内层用例。
• 正常路径以“输入端口接收简单请求模型，实体和用例独立完成规则”验收，不能只检查接口返回成功。
• 边界路径以“实体和用例不变，接口适配器替换且合同测试继续通过”验收，并保存源码依赖图、用例端口、边界 DTO、无框架测试、数据库和界面替换结果。
• 如果“用圆环数量做形式检查，却让实体注解 ORM、用例接收 HTTP Request 并返回数据库 Row”仍可静默通过，说明边界只是图示，没有成为可执行约束。