clean-architecture

整洁架构最佳实践

设计可维护、可测试软件系统的整洁架构原则综合指南。基于 Robert C. Martin 的《Clean Architecture: A Craftsman's Guide to Software Structure and Design》。包含 8 个类别中的 42 条规则，并按架构影响排序。

适用场景

在以下情况下参考这些指南：

• 设计新的软件系统或模块
• 规划各层之间的依赖关系
• 定义业务逻辑与基础设施之间的边界
• 审查代码中的架构违规
• 重构耦合系统，使其结构更加清晰

按优先级划分的规则类别

优先级	类别	影响	前缀
1	依赖方向	严重	dep-
2	实体设计	严重	entity-
3	用例隔离	高	usecase-
4	组件内聚性	高	comp-
5	边界定义	中高	bound-
6	接口适配器	中	adapt-
7	框架隔离	中	frame-
8	测试架构	低至中	test-

快速参考

1. 依赖方向（严重）

• dep-inward-only - 源代码依赖只能指向内层
• dep-interface-ownership - 接口应属于客户端，而非实现者
• dep-no-framework-imports - 避免在内层导入框架
• dep-data-crossing-boundaries - 使用简单数据结构跨越边界
• dep-acyclic-dependencies - 消除组件之间的循环依赖
• dep-stable-abstractions - 依赖稳定抽象，而非易变的具体实现

2. 实体设计（严重）

• entity-pure-business-rules - 实体只包含企业业务规则
• entity-no-persistence-awareness - 实体不得了解自身如何持久化
• entity-encapsulate-invariants - 在实体内部封装业务不变量
• entity-value-objects - 使用值对象表示领域概念
• entity-rich-not-anemic - 构建丰富的领域模型，而非贫血的数据结构

3. 用例隔离（高）

• usecase-single-responsibility - 每个用例只有一个变更理由
• usecase-input-output-ports - 为用例定义输入端口和输出端口
• usecase-orchestrates-not-implements - 用例负责编排实体，而非实现业务规则
• usecase-no-presentation-logic - 用例不得包含表示逻辑
• usecase-explicit-dependencies - 在构造函数中显式声明所有依赖
• usecase-transaction-boundary - 由用例定义事务边界

4. 组件内聚性（高）

• comp-screaming-architecture - 结构应彰显领域，而非框架
• comp-common-closure - 将一起变更的类归为一组
• comp-common-reuse - 避免迫使客户端依赖未使用的代码
• comp-reuse-release-equivalence - 将组件作为内聚单元发布
• comp-stable-dependencies - 沿着稳定性方向建立依赖

5. 边界定义（中高）

• bound-humble-object - 在架构边界使用简单对象
• bound-partial-boundaries - 完全分离为时过早时，使用部分边界
• bound-boundary-cost-awareness - 权衡边界成本与认知不足的成本
• bound-main-component - 将 main 视为应用程序的插件
• bound-defer-decisions - 延后框架和数据库决策
• bound-service-internal-architecture - 服务必须具备内部整洁架构

6. 接口适配器（中）

• adapt-controller-thin - 保持控制器精简
• adapt-presenter-formats - Presenter 为视图格式化数据
• adapt-gateway-abstraction - Gateway 隐藏外部系统细节
• adapt-mapper-translation - 使用 Mapper 在各层之间转换数据
• adapt-anti-corruption-layer - 为外部系统构建防腐层

7. 框架隔离（中）

• frame-domain-purity - 领域层不依赖任何框架
• frame-orm-in-infrastructure - 将 ORM 的使用限制在基础设施层
• frame-web-in-infrastructure - Web 框架相关事项应留在接口层
• frame-di-container-edge - 依赖注入容器应位于边界
• frame-logging-abstraction - 通过领域接口抽象日志记录

8. 测试架构（低至中）

• test-tests-are-architecture - 测试是系统架构的一部分
• test-testable-design - 从一开始就为可测试性而设计
• test-layer-isolation - 隔离测试每一层
• test-boundary-verification - 通过测试验证架构边界

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息