阅读中文版本

Clean Architecture

Clean architecture enforces a dependency rule in which inner entities and use cases know nothing of outer delivery and persistence mechanisms.

Definition

Clean architecture is a set of concentric boundaries, from entities and use cases to interface adapters and frameworks, governed by the rule that source dependencies point only inward.

It is used to keep core business rules stable while delivery mechanisms and data stores change around them. Compared to simpler alternatives, this concept fits best when the trade-off it represents is the one the system actually cares about.

When to use it

A common use case is applying it at the boundary where the cost of getting it wrong is highest, and the scenario usually involves a concrete guarantee the system must uphold. Unlike an ad hoc approach, it makes that guarantee explicit, reviewable, and testable.

How it works

The dependency rule constrains source code imports, not the runtime call direction, so an outer layer may call an inner one while the inner layer never references outer types.

Crossing a boundary inward is done through data structures and interfaces the inner layer owns, keeping details such as SQL or HTTP out of the core.

Trade-offs and alternatives

Applied dogmatically it can add ceremony for little benefit in small applications, so the boundary worth drawing is the one that changes most often. The main drawback is the extra complexity it introduces, so the benefit should clearly outweigh that cost before a team adopts it.

Common misconceptions

A persistent misconception is that clean architecture mandates a specific number of projects. Another is that the dependency rule applies to runtime calls as well as source imports. For example, an engineer who assumes otherwise may design around a guarantee that does not actually exist, which only becomes obvious under load or failure.

Anti-patterns to avoid

Two recurring anti-patterns are to letting a use case import a framework-specific request object and to requiring the domain to know how a response is serialised. Both tend to surface as hard-to-debug production issues rather than obvious test failures. Related concepts include Domain-Driven Design, Bounded Context, Aggregate Root.