Back to Details

architecture-boundaries

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecture Boundaries

架构边界

Use this skill when

适用场景

Use this Skill for architecture design, refactoring, dependency direction, ports and adapters, infrastructure isolation, dependency injection, package boundaries, or test seam decisions.
Do not use it to justify a full architecture template for every project. For business modeling and invariants, route to ddd-lite. For a concrete failure, route to systematic-debugging.
当你需要进行架构设计、重构、依赖方向规划、Ports与Adapters设计、基础设施隔离、依赖注入、包边界定义或测试接缝决策时，使用本Skill。
不要用它来为每个项目证明完整架构模板的合理性。对于业务建模和不变量，请转向ddd-lite。对于具体故障，请转向systematic-debugging。

Governing rule

指导原则

Prefer the simplest architecture that preserves meaningful boundaries.
A meaningful boundary protects at least one real responsibility, substitution point, independent test, protocol, deployment unit, ownership boundary, or source of change. A type name alone is not evidence of a boundary.
优先选择能保留有意义边界的最简架构。
有意义的边界至少能保护一项实际职责、替换点、独立测试、协议、部署单元、所有权边界或变更源。仅靠类型名称不能证明边界的存在。

Decision sequence

决策流程

  1. State the behavior and change risk the boundary should protect.
  2. Identify the caller, capability owner, implementation, and direction of dependency.
  3. Decide whether concrete types are sufficient inside the boundary.
  4. If the boundary is real, define the smallest purposeful contract on the consumer side.
  5. Inject the implementation explicitly and assemble it at the Composition Root.
  6. Keep protocol and provider translation in an Adapter.
  7. Check that Domain and application policy do not depend on infrastructure details.
  8. Add a test seam that verifies the boundary behavior.
  9. Re-evaluate whether DDD modeling is needed; route that decision to ddd-lite.
  1. 明确边界应保护的行为和变更风险。
  2. 识别调用方、能力所有者、实现方以及依赖方向。
  3. 判断边界内部是否使用具体类型即可满足需求。
  4. 如果边界真实存在，在消费端定义最小化的目标契约。
  5. 显式注入实现，并在Composition Root处进行组装。
  6. 将协议和提供者转换逻辑保留在Adapter中。
  7. 确保领域和应用策略不依赖基础设施细节。
  8. 添加验证边界行为的测试接缝。
  9. 重新评估是否需要DDD建模；将该决策转向ddd-lite。

MUST

必须遵循（MUST）

  • Dependencies must point toward the policy or business core.
  • Domain code must not depend on database, HTTP, queue, ORM, or cloud implementations.
  • Cross-boundary contracts must express a purposeful capability.
  • Dependencies must be explicit and injectable.
  • Concrete implementations must be assembled at the Composition Root.
  • Important boundaries must have a meaningful verification seam.
  • Do not create interfaces solely to make local mocking convenient.
  • 依赖必须指向策略或业务核心。
  • 领域代码不得依赖数据库、HTTP、队列、ORM或云服务实现。
  • 跨边界契约必须表达明确的目标能力。
  • 依赖必须是显式且可注入的。
  • 具体实现必须在Composition Root处组装。
  • 重要边界必须有有意义的验证接缝。
  • 不得仅为方便本地模拟而创建接口。

SHOULD

建议遵循（SHOULD）

  • Let the consumer own a small interface when it needs a replaceable capability.
  • Keep interfaces focused on behavior rather than mirroring a concrete type.
  • Let repositories express domain capabilities instead of exposing storage CRUD.
  • Keep application services responsible for orchestration, not hidden domain invariants.
  • Let adapters translate protocols and providers without leaking them inward.
  • Migrate large systems through small vertical slices.
  • 当消费者需要可替换能力时，由消费者拥有一个小型接口。
  • 接口应聚焦于行为，而非镜像具体类型。
  • 让Repository表达领域能力，而非暴露存储的CRUD操作。
  • 让应用服务负责编排，而非隐藏领域不变量。
  • 让Adapters处理协议和提供者的转换，避免向内泄露细节。
  • 通过小型垂直切片迁移大型系统。

CONDITIONAL

条件性规则（CONDITIONAL）

Introduce an inbound port only when it protects a meaningful boundary or substitute. An HTTP handler calling an application service does not automatically require an interface.
Introduce a repository abstraction only when storage is a real change boundary, the domain needs a capability, or independent testing requires it.
Introduce an Aggregate, Domain Event, CQRS, or another DDD pattern only when its business invariant or consistency requirement is real. Route the modeling decision to ddd-lite.
仅当需要保护有意义的边界或替换点时，才引入入站端口（inbound port）。HTTP处理器调用应用服务并不一定需要接口。
仅当存储是真实的变更边界、领域需要某项能力或独立测试有需求时，才引入Repository抽象。
仅当存在真实的业务不变量或一致性需求时，才引入Aggregate、Domain Event、CQRS或其他DDD模式。建模决策请转向ddd-lite。

Anti-patterns

反模式

Reject these unless there is unusually strong evidence:
  • one interface for every struct or service;
  • an application service depending directly on a concrete database client;
  • hidden package globals for databases, clocks, or network clients;
  • constructors that create their own infrastructure;
  • ORM base types leaking into domain objects;
  • a repository that exposes every table operation without domain meaning;
  • a giant service that owns every domain rule.
Read hexagonal.md for port and adapter terminology, testing-seams.md for verification boundaries, languages/go.md for Go package and constructor guidance, and languages/cpp.md when applying the same decisions in C++.
除非有异常充分的证据，否则拒绝以下做法：
  • 为每个结构体或服务都创建一个接口；
  • 应用服务直接依赖具体的数据库客户端；
  • 数据库、时钟或网络客户端使用隐藏的包全局变量；
  • 构造函数自行创建基础设施；
  • ORM基类渗透到领域对象中；
  • Repository暴露所有无领域意义的表操作；
  • 单个巨型服务掌控所有领域规则。
阅读hexagonal.md了解Ports与Adapters术语，testing-seams.md了解验证边界，languages/go.md了解Go语言的包和构造函数指南，languages/cpp.md了解在C++中应用相同决策的方法。

Verification

验证

Before accepting a design, show:
  • the boundary and the reason it is meaningful;
  • the dependency direction;
  • the contract owner and smallest capability surface;
  • the Composition Root or injection path;
  • the adapter translation point;
  • the test or contract that proves the boundary;
  • the reason any conditional pattern was or was not introduced.
在确认设计前，需展示：
  • 边界及其有意义的原因；
  • 依赖方向；
  • 契约所有者和最小能力范围；
  • Composition Root或注入路径；
  • Adapter转换点；
  • 验证边界的测试或契约；
  • 引入或未引入条件性模式的原因。