clean-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clean Architecture Best Practices

Clean Architecture最佳实践

Comprehensive guide to Clean Architecture principles for designing maintainable, testable software systems. Based on Robert C. Martin's "Clean Architecture: A Craftsman's Guide to Software Structure and Design." Contains 42 rules across 8 categories, prioritized by architectural impact.

本指南全面介绍了用于设计可维护、可测试软件系统的Clean Architecture原则，基于Robert C. Martin所著的《Clean Architecture: A Craftsman's Guide to Software Structure and Design》。包含8个类别共42条规则，按架构影响优先级排序。

When to Apply

适用场景

Reference these guidelines when:

Designing new software systems or modules
Structuring dependencies between layers
Defining boundaries between business logic and infrastructure
Reviewing code for architectural violations
Refactoring coupled systems toward cleaner structure

在以下场景中可参考这些指南：

设计新的软件系统或模块时
规划各层之间的依赖结构时
定义业务逻辑与基础设施之间的边界时
审查代码是否存在架构违规情况时
重构耦合系统以实现更清晰的结构时

Rule Categories by Priority

按优先级划分的规则类别


dep-
entity-
usecase-
comp-
bound-
adapt-
frame-
test-

Priority	Category	Impact	Prefix
1	Dependency Direction	CRITICAL	`dep-`
2	Entity Design	CRITICAL	`entity-`
3	Use Case Isolation	HIGH	`usecase-`
4	Component Cohesion	HIGH	`comp-`
5	Boundary Definition	MEDIUM-HIGH	`bound-`
6	Interface Adapters	MEDIUM	`adapt-`
7	Framework Isolation	MEDIUM	`frame-`
8	Testing Architecture	LOW-MEDIUM	`test-`


dep-
entity-
usecase-
comp-
bound-
adapt-
frame-
test-

优先级	类别	影响级别	前缀
1	Dependency Direction	CRITICAL	`dep-`
2	Entity Design	CRITICAL	`entity-`
3	Use Case Isolation	HIGH	`usecase-`
4	Component Cohesion	HIGH	`comp-`
5	Boundary Definition	MEDIUM-HIGH	`bound-`
6	Interface Adapters	MEDIUM	`adapt-`
7	Framework Isolation	MEDIUM	`frame-`
8	Testing Architecture	LOW-MEDIUM	`test-`

Quick Reference

快速参考

1. Dependency Direction (CRITICAL)

```
dep-inward-only
```
- Source dependencies point inward only
```
dep-interface-ownership
```
- Interfaces belong to clients not implementers
```
dep-no-framework-imports
```
- Avoid framework imports in inner layers
```
dep-data-crossing-boundaries
```
- Use simple data structures across boundaries
```
dep-acyclic-dependencies
```
- Eliminate cyclic dependencies between components
```
dep-stable-abstractions
```
- Depend on stable abstractions not volatile concretions

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

2. Entity Design (CRITICAL)

```
entity-pure-business-rules
```
- Entities contain only enterprise business rules
```
entity-no-persistence-awareness
```
- Entities must not know how they are persisted
```
entity-encapsulate-invariants
```
- Encapsulate business invariants within entities
```
entity-value-objects
```
- Use value objects for domain concepts
```
entity-rich-not-anemic
```
- Build rich domain models not anemic data structures

```
entity-pure-business-rules
```
- 实体仅包含企业级业务规则
```
entity-no-persistence-awareness
```
- 实体不得知晓自身的持久化方式
```
entity-encapsulate-invariants
```
- 在实体中封装业务不变量
```
entity-value-objects
```
- 对领域概念使用值对象
```
entity-rich-not-anemic
```
- 构建富领域模型而非贫血数据结构

3. Use Case Isolation (HIGH)

```
usecase-single-responsibility
```
- Each use case has one reason to change
```
usecase-input-output-ports
```
- Define input and output ports for use cases
```
usecase-orchestrates-not-implements
```
- Use cases orchestrate entities not implement business rules
```
usecase-no-presentation-logic
```
- Use cases must not contain presentation logic
```
usecase-explicit-dependencies
```
- Declare all dependencies explicitly in constructor
```
usecase-transaction-boundary
```
- Use case defines the transaction boundary

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

4. Component Cohesion (HIGH)

```
comp-screaming-architecture
```
- Structure should scream the domain not the framework
```
comp-common-closure
```
- Group classes that change together
```
comp-common-reuse
```
- Avoid forcing clients to depend on unused code
```
comp-reuse-release-equivalence
```
- Release components as cohesive units
```
comp-stable-dependencies
```
- Depend in the direction of stability

```
comp-screaming-architecture
```
- 架构结构应突出领域而非框架
```
comp-common-closure
```
- 将同时变更的类归为一组
```
comp-common-reuse
```
- 避免强制客户端依赖未使用的代码
```
comp-reuse-release-equivalence
```
- 以内聚单元的形式发布组件
```
comp-stable-dependencies
```
- 朝稳定性方向依赖

5. Boundary Definition (MEDIUM-HIGH)

```
bound-humble-object
```
- Use humble objects at architectural boundaries
```
bound-partial-boundaries
```
- Use partial boundaries when full separation is premature
```
bound-boundary-cost-awareness
```
- Weigh boundary cost against ignorance cost
```
bound-main-component
```
- Treat main as a plugin to the application
```
bound-defer-decisions
```
- Defer framework and database decisions
```
bound-service-internal-architecture
```
- Services must have internal clean architecture

```
bound-humble-object
```
- 在架构边界处使用简单对象（Humble Object）
```
bound-partial-boundaries
```
- 当完全分离为时尚早时，使用部分边界
```
bound-boundary-cost-awareness
```
- 权衡边界成本与无知成本
```
bound-main-component
```
- 将main视为应用的插件
```
bound-defer-decisions
```
- 推迟框架和数据库相关决策
```
bound-service-internal-architecture
```
- 服务必须具备内部整洁架构

6. Interface Adapters (MEDIUM)

```
adapt-controller-thin
```
- Keep controllers thin
```
adapt-presenter-formats
```
- Presenters format data for the view
```
adapt-gateway-abstraction
```
- Gateways hide external system details
```
adapt-mapper-translation
```
- Use mappers to translate between layers
```
adapt-anti-corruption-layer
```
- Build anti-corruption layers for external systems

```
adapt-controller-thin
```
- 保持控制器轻量化
```
adapt-presenter-formats
```
- 由展示器（Presenter）为视图格式化数据
```
adapt-gateway-abstraction
```
- 网关隐藏外部系统细节
```
adapt-mapper-translation
```
- 使用映射器在各层间转换数据
```
adapt-anti-corruption-layer
```
- 为外部系统构建防腐层（Anti-Corruption Layer）

7. Framework Isolation (MEDIUM)

```
frame-domain-purity
```
- Domain layer has zero framework dependencies
```
frame-orm-in-infrastructure
```
- Keep ORM usage in infrastructure layer
```
frame-web-in-infrastructure
```
- Web framework concerns stay in interface layer
```
frame-di-container-edge
```
- Dependency injection containers live at the edge
```
frame-logging-abstraction
```
- Abstract logging behind domain interfaces

```
frame-domain-purity
```
- 领域层无任何框架依赖
```
frame-orm-in-infrastructure
```
- 将ORM使用限制在基础设施层
```
frame-web-in-infrastructure
```
- Web框架相关逻辑仅存于接口层
```
frame-di-container-edge
```
- 依赖注入容器位于系统边缘
```
frame-logging-abstraction
```
- 基于领域接口抽象日志功能

8. Testing Architecture (LOW-MEDIUM)

```
test-tests-are-architecture
```
- Tests are part of the system architecture
```
test-testable-design
```
- Design for testability from the start
```
test-layer-isolation
```
- Test each layer in isolation
```
test-boundary-verification
```
- Verify architectural boundaries with tests

```
test-tests-are-architecture
```
- 测试是系统架构的一部分
```
test-testable-design
```
- 从设计初期就考虑可测试性
```
test-layer-isolation
```
- 独立测试每一层
```
test-boundary-verification
```
- 用测试验证架构边界

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件以获取详细说明和代码示例：

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

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

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