clean-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is activated, always start your first response with the 🧢 emoji.

激活此技能后，请始终以🧢表情作为你的第一条回复开头。

Clean Architecture

Clean Architecture is a set of principles from Robert C. Martin for organizing software systems so that business rules are isolated from frameworks, databases, and delivery mechanisms. The core idea is the Dependency Rule: source code dependencies must always point inward, toward higher-level policies. This produces systems that are testable without UI or database, framework-independent, and resilient to change in external concerns. This skill covers the concentric layer model, component design principles, and practical boundary-crossing patterns.

Clean Architecture是Robert C. Martin提出的一套软件系统组织原则，旨在将业务规则与框架、数据库和交付机制隔离开来。核心思想是依赖规则（Dependency Rule）：源代码依赖必须始终指向内部，即指向更高层级的策略。这能打造出无需UI或数据库即可测试、独立于框架、且能适应外部环境变化的系统。此技能涵盖同心层模型、组件设计原则以及实用的跨边界模式。

When to use this skill

何时使用此技能

Trigger this skill when the user:

Asks how to structure a new project or application
Wants to separate business logic from framework/infrastructure code
Needs to design use cases or application services
Asks about dependency direction or the Dependency Rule
Wants to refactor a monolith or tightly-coupled codebase
Asks about component cohesion, coupling, or package organization
Needs to cross architectural boundaries (e.g. use case to database)
Asks about Screaming Architecture or making intent visible in structure

Do NOT trigger this skill for:

Code-level refactoring (naming, function size, comments) - use the clean-code skill
Infrastructure/DevOps decisions (container orchestration, CI/CD pipelines)

当用户有以下需求时触发此技能：

询问如何搭建新项目或应用的结构
希望将业务逻辑与框架/基础设施代码分离
需要设计用例或应用服务
询问依赖方向或依赖规则
想要重构单体应用或耦合紧密的代码库
询问组件内聚、耦合或包组织方式
需要跨越架构边界（例如从用例到数据库）
询问Screaming Architecture或如何在结构中体现意图

请勿在以下场景触发此技能：

代码级重构（命名、函数大小、注释）- 请使用clean-code技能
基础设施/DevOps决策（容器编排、CI/CD流水线）

Key principles

核心原则

The Dependency Rule - Source code dependencies must point inward only. Nothing in an inner circle can know anything about something in an outer circle. This includes names, functions, classes, and data formats. The inner circles are policy; the outer circles are mechanisms.
Screaming Architecture - Your project structure should scream its purpose. A healthcare system's top-level folders should say
```
patients/
```
,
```
appointments/
```
,
```
prescriptions/
```
- not
```
controllers/
```
,
```
models/
```
,
```
services/
```
. The architecture should communicate the use cases, not the framework.
Policy over detail - Business rules are the most important code. They change for business reasons. Frameworks, databases, and UI are details that change for technical reasons. Protect policy from detail by making detail depend on policy, never the reverse.
Defer decisions - A good architecture lets you delay choices about frameworks, databases, and delivery mechanisms. If you must choose a database before writing business logic, the architecture has failed.
Testability as a design metric - If you can't test your business rules without a database, web server, or UI, the architecture is wrong. Use cases should be testable with plain unit tests.

依赖规则（Dependency Rule） - 源代码依赖只能指向内部。内层的任何代码都不得了解外层的任何内容，包括名称、函数、类和数据格式。内层是策略层，外层是机制层。
Screaming Architecture - 你的项目结构应清晰体现其用途。一个医疗系统的顶级文件夹应该是
```
patients/
```
、
```
appointments/
```
、
```
prescriptions/
```
，而非
```
controllers/
```
、
```
models/
```
、
```
services/
```
。架构应传达用例，而非框架信息。
策略优先于细节 - 业务规则是最重要的代码，它们会因业务原因发生变化。框架、数据库和UI是细节，会因技术原因发生变化。通过让细节依赖于策略，而非反过来，来保护策略不受细节影响。
延迟决策 - 优秀的架构允许你推迟对框架、数据库和交付机制的选择。如果你必须在编写业务逻辑前就选择数据库，那么这个架构是失败的。
可测试性作为设计指标 - 如果你无法在没有数据库、Web服务器或UI的情况下测试业务规则，那么架构存在问题。用例应能通过简单的单元测试进行验证。

Core concepts

核心概念

Clean Architecture organizes code into concentric layers, each with a distinct responsibility. From innermost to outermost:

Entities are enterprise-wide business rules. They encapsulate the most general, high-level rules that would exist even if there were no software system. An entity can be an object with methods or a set of data structures and functions. They are the least likely to change when something external changes.

Use Cases contain application-specific business rules. Each use case orchestrates the flow of data to and from entities, directing them to apply their enterprise-wide rules. Use cases don't know about the UI, database, or any external agency. They define input/output data structures (request/response models) at the boundary.

Interface Adapters convert data between the format most convenient for use cases and the format required by external agents (database, web, etc.). Controllers, presenters, gateways, and repositories live here. This layer contains no business logic - only translation.

Frameworks & Drivers is the outermost layer. Web frameworks, database drivers, HTTP clients, message queues. This is glue code that wires external tools to the interface adapters. Keep this layer thin.

See

references/layer-patterns.md

for detailed code patterns in each layer.

Clean Architecture将代码组织为同心层，每层都有明确的职责。从最内层到最外层：

**Entities（实体）**是企业级的业务规则。它们封装了最通用、最高层级的规则，即使没有软件系统，这些规则也依然存在。实体可以是带方法的对象，也可以是一组数据结构和函数。当外部环境变化时，它们是最不可能发生改变的部分。

**Use Cases（用例）**包含应用特定的业务规则。每个用例都会协调数据在实体之间的流动，指导实体应用其企业级规则。用例不了解UI、数据库或任何外部代理，它们在边界处定义输入/输出数据结构（请求/响应模型）。

**Interface Adapters（接口适配器）**在最适合用例的数据格式与外部代理（数据库、Web等）所需的数据格式之间进行转换。控制器（Controllers）、呈现器（Presenters）、网关（Gateways）和仓库（Repositories）都属于这一层。该层不包含任何业务逻辑，仅负责转换。

**Frameworks & Drivers（框架与驱动）**是最外层。包括Web框架、数据库驱动、HTTP客户端、消息队列等。这是将外部工具与接口适配器连接起来的粘合代码，应保持该层简洁。

如需了解各层的详细代码模式，请查看

references/layer-patterns.md

。

Common tasks

常见任务

Structure a new project

搭建新项目结构

Organize by domain feature, not by technical layer. Each feature module contains its own layers internally.

Before (framework-screaming):

src/
  controllers/
    UserController.ts
    OrderController.ts
  models/
    User.ts
    Order.ts
  services/
    UserService.ts
    OrderService.ts
  repositories/
    UserRepository.ts
    OrderRepository.ts

After (domain-screaming):

src/
  users/
    entities/User.ts
    usecases/CreateUser.ts
    usecases/GetUserProfile.ts
    adapters/UserController.ts
    adapters/UserRepository.ts
  orders/
    entities/Order.ts
    entities/OrderItem.ts
    usecases/PlaceOrder.ts
    usecases/CancelOrder.ts
    adapters/OrderController.ts
    adapters/OrderRepository.ts
  shared/
    entities/Money.ts
    interfaces/Repository.ts

按领域功能而非技术层进行组织。每个功能模块内部包含自己的层级。

之前（框架主导）：

src/
  controllers/
    UserController.ts
    OrderController.ts
  models/
    User.ts
    Order.ts
  services/
    UserService.ts
    OrderService.ts
  repositories/
    UserRepository.ts
    OrderRepository.ts

之后（领域主导）：

src/
  users/
    entities/User.ts
    usecases/CreateUser.ts
    usecases/GetUserProfile.ts
    adapters/UserController.ts
    adapters/UserRepository.ts
  orders/
    entities/Order.ts
    entities/OrderItem.ts
    usecases/PlaceOrder.ts
    usecases/CancelOrder.ts
    adapters/OrderController.ts
    adapters/OrderRepository.ts
  shared/
    entities/Money.ts
    interfaces/Repository.ts

Define a use case

定义用例

Each use case is a single class/function with one public method. It accepts a request model, orchestrates entities, and returns a response model.

typescript

// usecases/PlaceOrder.ts
interface PlaceOrderRequest {
  customerId: string;
  items: Array<{ productId: string; quantity: number }>;
}

interface PlaceOrderResponse {
  orderId: string;
  total: number;
}

interface OrderGateway {
  save(order: Order): Promise<void>;
}

interface ProductGateway {
  findByIds(ids: string[]): Promise<Product[]>;
}

class PlaceOrder {
  constructor(
    private orders: OrderGateway,
    private products: ProductGateway,
  ) {}

  async execute(request: PlaceOrderRequest): Promise<PlaceOrderResponse> {
    const products = await this.products.findByIds(
      request.items.map((i) => i.productId),
    );
    const order = Order.create(request.customerId, request.items, products);
    await this.orders.save(order);
    return { orderId: order.id, total: order.total.amount };
  }
}

Note:

OrderGateway

and

ProductGateway

are interfaces defined in the use case layer. The database implementation lives in the adapters layer and is injected.

每个用例是一个单独的类/函数，包含一个公共方法。它接收请求模型，协调实体，并返回响应模型。

typescript

// usecases/PlaceOrder.ts
interface PlaceOrderRequest {
  customerId: string;
  items: Array<{ productId: string; quantity: number }>;
}

interface PlaceOrderResponse {
  orderId: string;
  total: number;
}

interface OrderGateway {
  save(order: Order): Promise<void>;
}

interface ProductGateway {
  findByIds(ids: string[]): Promise<Product[]>;
}

class PlaceOrder {
  constructor(
    private orders: OrderGateway,
    private products: ProductGateway,
  ) {}

  async execute(request: PlaceOrderRequest): Promise<PlaceOrderResponse> {
    const products = await this.products.findByIds(
      request.items.map((i) => i.productId),
    );
    const order = Order.create(request.customerId, request.items, products);
    await this.orders.save(order);
    return { orderId: order.id, total: order.total.amount };
  }
}

注意：

OrderGateway

和

ProductGateway

是在用例层定义的接口。数据库实现位于适配器层，并通过依赖注入的方式传入。

Cross a boundary with Dependency Inversion

用依赖反转跨越边界

When an inner layer needs to call an outer layer (e.g. use case needs to persist data), define an interface in the inner layer and implement it in the outer layer.

Use Case layer:     defines OrderGateway (interface)
Adapter layer:      implements PostgresOrderGateway (class)
Framework layer:    wires PostgresOrderGateway into PlaceOrder via DI

typescript

// Inner: usecases/gateways/OrderGateway.ts (interface)
interface OrderGateway {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

// Outer: adapters/persistence/PostgresOrderGateway.ts (implementation)
class PostgresOrderGateway implements OrderGateway {
  constructor(private db: Pool) {}

  async save(order: Order): Promise<void> {
    await this.db.query("INSERT INTO orders ...", [order.id, order.total]);
  }

  async findById(id: string): Promise<Order | null> {
    const row = await this.db.query("SELECT * FROM orders WHERE id = $1", [id]);
    return row ? this.toEntity(row) : null;
  }
}

See

references/dependency-rule.md

and

references/boundaries.md

for more patterns.

当内层需要调用外层（例如用例需要持久化数据）时，在内层定义接口，在外层实现该接口。

用例层：     定义OrderGateway（接口）
适配器层：   实现PostgresOrderGateway（类）
框架层：     通过依赖注入将PostgresOrderGateway注入到PlaceOrder中

typescript

// 内层：usecases/gateways/OrderGateway.ts（接口）
interface OrderGateway {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

// 外层：adapters/persistence/PostgresOrderGateway.ts（实现）
class PostgresOrderGateway implements OrderGateway {
  constructor(private db: Pool) {}

  async save(order: Order): Promise<void> {
    await this.db.query("INSERT INTO orders ...", [order.id, order.total]);
  }

  async findById(id: string): Promise<Order | null> {
    const row = await this.db.query("SELECT * FROM orders WHERE id = $1", [id]);
    return row ? this.toEntity(row) : null;
  }
}

如需了解更多模式，请查看

references/dependency-rule.md

和

references/boundaries.md

。

Design an interface adapter (Controller)

设计接口适配器（控制器）

Controllers translate HTTP requests into use case request models, then translate use case responses back into HTTP responses. No business logic lives here.

typescript

// adapters/http/OrdersController.ts
class OrdersController {
  constructor(private placeOrder: PlaceOrder) {}

  async handlePost(req: Request, res: Response) {
    const request: PlaceOrderRequest = {
      customerId: req.body.customerId,
      items: req.body.items,
    };
    const result = await this.placeOrder.execute(request);
    res.status(201).json(result);
  }
}

The controller knows about HTTP. The use case does not. If you switch from Express to Fastify, only this layer changes.

控制器将HTTP请求转换为用例请求模型，然后将用例响应转换回HTTP响应。该层不包含任何业务逻辑。

typescript

// adapters/http/OrdersController.ts
class OrdersController {
  constructor(private placeOrder: PlaceOrder) {}

  async handlePost(req: Request, res: Response) {
    const request: PlaceOrderRequest = {
      customerId: req.body.customerId,
      items: req.body.items,
    };
    const result = await this.placeOrder.execute(request);
    res.status(201).json(result);
  }
}

控制器了解HTTP相关知识，而用例不了解。如果你从Express切换到Fastify，只有这一层需要修改。

Enforce the Dependency Rule

强制执行依赖规则

Use these practical enforcement strategies:

Import linting - Configure ESLint (e.g.
```
eslint-plugin-boundaries
```
) or similar tools to forbid imports from outer layers into inner layers
Package/module boundaries - In languages with module systems (Go, Java, Rust), use package visibility to enforce access
Code review checklist - Check that entities import nothing from use cases, use cases import nothing from adapters, and adapters import nothing from frameworks directly

ALLOWED:            Adapter -> UseCase -> Entity
FORBIDDEN:          Entity -> UseCase, UseCase -> Adapter, Entity -> Adapter

See

references/dependency-rule.md

for enforcement tooling by language.

使用以下实用策略来强制执行依赖规则：

导入检查 - 配置ESLint（例如
```
eslint-plugin-boundaries
```
）或类似工具，禁止从外层向内层导入代码
包/模块边界 - 在具有模块系统的语言（Go、Java、Rust）中，使用包可见性来限制访问
代码评审检查清单 - 检查实体是否不导入用例中的内容，用例是否不导入适配器中的内容，适配器是否不直接导入框架中的内容

允许：            适配器 -> 用例 -> 实体
禁止：            实体 -> 用例，用例 -> 适配器，实体 -> 适配器

如需了解各语言的强制执行工具，请查看

references/dependency-rule.md

。

Organize components

组织组件

Apply the component cohesion and coupling principles to decide what goes in the same package/module and how packages relate to each other.

Cohesion (what goes together):

REP (Reuse/Release Equivalence) - Classes released together should be reusable together
CCP (Common Closure) - Classes that change together should be packaged together
CRP (Common Reuse) - Don't force consumers to depend on things they don't use

Coupling (how packages relate):

ADP (Acyclic Dependencies) - No cycles in the package dependency graph
SDP (Stable Dependencies) - Depend in the direction of stability
SAP (Stable Abstractions) - Stable packages should be abstract

See

references/component-principles.md

for the full breakdown.

应用组件内聚和耦合原则来决定哪些内容应放在同一个包/模块中，以及包之间的关系。

内聚（哪些内容应放在一起）：

REP（重用/发布等价原则） - 一起发布的类应可一起重用
CCP（共同封闭原则） - 一起变化的类应放在同一个包中
CRP（共同重用原则） - 不要让消费者依赖他们不需要的内容

耦合（包之间的关系）：

ADP（无环依赖原则） - 包依赖图中不能存在循环
SDP（稳定依赖原则） - 依赖应指向更稳定的方向
SAP（稳定抽象原则） - 稳定的包应是抽象的

如需详细说明，请查看

references/component-principles.md

。

Anti-patterns / common mistakes

反模式/常见错误

Mistake	Why it's wrong	What to do instead
Framework coupling	Letting annotations ( `@Entity` , `@Injectable` ) leak into entities/use cases ties business rules to a framework	Keep entities as plain objects. Apply framework decorators only in the adapter/framework layer
Skipping use cases	Putting business logic in controllers makes it untestable and couples it to HTTP	Always model operations as use cases, even simple ones. They're cheap to create
Over-engineering small apps	Full Clean Architecture for a 3-endpoint CRUD API adds layers without benefit	Scale the architecture to the complexity. A simple app might only need 2 layers
Wrong dependency direction	Use cases importing from controllers, or entities depending on ORM types	Draw the dependency arrows. If any point outward, invert with an interface
Database-driven design	Starting with the schema and generating entities from it	Start with entities and use cases. The database schema is a detail that adapts to the domain
Treating layers as folders	Creating `entities/` , `usecases/` folders but not enforcing import rules	Folders aren't boundaries. Use linting, module visibility, or build tools to enforce the rule
Premature microservices	Splitting into services before understanding domain boundaries	Start as a well-structured monolith. Extract services along proven component boundaries

错误	错误原因	正确做法
框架耦合	让注解（ `@Entity` 、 `@Injectable` ）渗透到实体/用例中，将业务规则与框架绑定	保持实体为纯对象。仅在适配器/框架层应用框架注解
跳过用例	将业务逻辑放在控制器中，导致代码无法测试且与HTTP耦合	始终将操作建模为用例，即使是简单操作。创建用例的成本很低
对小型应用过度设计	为只有3个端点的CRUD API使用完整的Clean Architecture，增加不必要的层级	根据复杂度调整架构。简单应用可能只需要2层
依赖方向错误	用例导入控制器中的内容，或实体依赖ORM类型	绘制依赖箭头。如果有任何箭头指向外部，使用接口进行反转
数据库驱动的设计	从数据库模式开始，然后生成实体	从实体和用例开始。数据库模式是适应领域的细节
将层视为文件夹	创建 `entities/` 、 `usecases/` 文件夹但不强制执行导入规则	文件夹不是边界。使用检查工具、模块可见性或构建工具来执行规则
过早拆分微服务	在理解领域边界之前就将系统拆分为微服务	先从结构良好的单体应用开始。沿着已验证的组件边界提取微服务

References

参考资料

For detailed content on specific topics, read the relevant file from

references/

```
references/dependency-rule.md
```
- The Dependency Rule, enforcement strategies, and tooling by language
```
references/component-principles.md
```
- Cohesion (REP, CCP, CRP) and Coupling (ADP, SDP, SAP) with examples
```
references/layer-patterns.md
```
- Detailed code patterns for each architectural layer
```
references/boundaries.md
```
- Boundary crossing strategies, humble objects, DTOs, partial boundaries

Only load a references file if the current task requires deep detail on that topic.

如需了解特定主题的详细内容，请查看

references/

目录下的相关文件：

```
references/dependency-rule.md
```
- 依赖规则、强制执行策略以及各语言的工具支持
```
references/component-principles.md
```
- 内聚（REP、CCP、CRP）和耦合（ADP、SDP、SAP）的详细说明及示例
```
references/layer-patterns.md
```
- 各架构层的详细代码模式
```
references/boundaries.md
```
- 跨边界策略、 humble objects、DTO、部分边界

仅当当前任务需要深入了解某个主题时，才加载对应的参考资料文件。

clean-architecture

Original

Translation

Clean Architecture

Clean Architecture

When to use this skill

何时使用此技能

Key principles

核心原则

Core concepts

核心概念

Common tasks

常见任务

Structure a new project

搭建新项目结构

Define a use case

定义用例

Cross a boundary with Dependency Inversion

用依赖反转跨越边界

Design an interface adapter (Controller)

设计接口适配器（控制器）

Enforce the Dependency Rule

强制执行依赖规则

Organize components

组织组件

Anti-patterns / common mistakes

反模式/常见错误

References

参考资料

Related skills

相关技能