一、起源
1.1 依赖方向失控的三种表现
结构问题不会立刻导致故障,而是以三种方式持续消耗维护成本:
| 表现 | 具体形态 | 后果 |
|---|---|---|
| 循环依赖 | 模块 A 调用 B,B 又调用 A;类之间形成环 | 无法单独理解与测试任一模块,改动影响不可预测 |
| 跨层调用 | 接口层直接访问数据访问层,领域层调用外部服务 | 业务规则绕过编排,事务与校验被跳过 |
| 共享可变状态 | 多个模块直接读写同一个全局对象或静态集合 | 一处修改影响多处,问题难以复现 |
三者的共同点是把"依赖"从显式变隐式:不通过接口声明协作关系,而是通过直接引用与共享状态耦合。
1.2 架构风格要回答的问题
架构风格的作用不是规定目录名称,而是回答三个问题:
- 哪些代码可以依赖哪些代码,方向如何。
- 业务规则放在哪一层,依赖什么、不依赖什么。
- 外部世界的变化(数据库、消息、第三方接口)如何被隔离,不渗透进业务规则。
三个问题的答案共同决定:能否在不启动数据库与网络的情况下测试业务规则,以及更换外部组件时的影响范围。
1.3 取舍
| 选择 | 获得 | 付出 |
|---|---|---|
| 严格边界 | 业务规则可独立测试、外部组件可替换、影响范围可控 | 接口与转换代码增加,初学者上手需要理解分层意图 |
| 宽松结构 | 开发速度快、样板代码少 | 规则散落、改动影响扩散、测试需要真实依赖 |
边界的收益随团队规模与系统寿命上升:个人短期项目收益有限,多人长期维护的系统边界成本可摊销。
二、原理
2.1 分层架构
分层架构把代码按职责纵向切分,依赖方向自上而下:
用户接口层(协议转换、参数校验、响应组装)
|
v
应用层(用例编排、事务边界、权限校验)
|
v
领域层(业务规则、不变式、状态流转)
|
v
基础设施层(持久化、消息、外部系统适配)
存在的问题是最后一层:领域层通常不直接调用基础设施层,而是需要被基础设施层依赖(仓储实现依赖领域接口)。因此单纯的分层无法表达领域与基础设施之间的真实依赖方向,需要通过依赖倒置把"领域定义接口、基础设施实现接口"这一关系显式化。
2.2 端口与适配器
端口与适配器(六边形架构)把边界表达为"端口加适配器":
| 概念 | 含义 | 举例 |
|---|---|---|
| 驱动端口 | 外部请求进入应用的入口接口 | 用例接口、命令行入口 |
| 驱动适配器 | 把外部协议转换为端口调用 | HTTP 控制器、消息监听器 |
| 被动端口 | 应用对外部能力的需求接口 | 仓储、第三方服务接口 |
| 被动适配器 | 用具体技术实现被动端口 | 数据库实现、HTTP 客户端实现 |
核心思想是:应用核心只依赖端口(接口),适配器是换掉不影响核心的插件。测试时可以为主端口提供内存实现,为被动端口提供替身,因此业务规则可以在没有数据库与网络的环境下测试。
2.3 整洁架构与洋葱架构
整洁架构用同心圆表达同类思想:
| 层次(由内向外) | 内容 | 依赖 |
|---|---|---|
| 实体 | 企业级业务规则 | 不依赖任何外层 |
| 用例 | 应用级业务流程编排 | 可依赖实体 |
| 接口适配器 | 控制器、展示器、网关 | 可依赖用例 |
| 框架与驱动 | 数据库、Web 框架、工具 | 可依赖内层,被内层通过接口使用 |
依赖规则只有一条:依赖方向由外向内,内层不得引用外层的任何名称。跨越边界时通过接口与数据传递对象完成,不允许内层直接使用外层的类型。
洋葱架构与整洁架构在结构上等价,区别是用领域模型作为最内层,强调领域模型的中心位置。三者在工程实践中通常混用同一套落地方式,差异主要体现在术语。
2.4 三者对比
| 维度 | 分层 | 端口与适配器 | 整洁与洋葱 |
|---|---|---|---|
| 组织维度 | 按技术职责纵向切分 | 以应用核心为中心,外部为插件 | 同心圆,依赖向内 |
| 边界的表达 | 层与层之间 | 端口加适配器 | 同心圆边界加接口 |
| 外部依赖的处理 | 基础设施层承担 | 适配器承担 | 外层承担 |
| 主要优点 | 直观、易理解、与框架习惯一致 | 可替换性强、测试友好 | 依赖规则明确、业务规则集中 |
| 主要风险 | 领域与基础设施的依赖方向表述不清 | 端口划分过细导致接口爆炸 | 概念层次多,容易流于形式 |
| 适用 | 业务规则简单的系统 | 外部依赖多、需要替换或模拟的场景 | 业务规则复杂、需要长期演进的核心系统 |
共同点比差异更重要:三者都要求业务规则不依赖框架、外部依赖通过接口反转、依赖方向单向。选择哪种形式,对最终代码结构的影响远小于是否真正执行了依赖规则。
2.5 依赖倒置在模块边界的落地
依赖倒置在结构上的落地方式是"接口与实现分属不同模块":
domain : 定义 OrderRepository 接口、领域对象
infrastructure : 实现 OrderRepository(依赖 domain)
application : 依赖 domain,调用仓储接口
interfaces : 依赖 application,调用用例
四条规则:
- 接口所在模块由"谁使用"决定,而不是由"谁实现"决定。仓储接口被应用与领域使用,因此放在它们可依赖的内层。
- 实现模块依赖接口模块,因此基础设施层处于外层,编译期依赖方向与运行期调用方向相反,这正是倒置的含义。
- 数据传输对象跨越边界时需要转换,不允许外层类型进入内层;转换位置在适配器或装配器中。
- 框架注解只允许出现在外层与装配位置,领域对象中不出现持久化与事务注解(这一点与聚合的实现约束一致,见 领域驱动设计落地)。
2.6 分包策略:按技术分层还是按业务能力
| 策略 | 结构 | 优点 | 缺点 |
|---|---|---|---|
| 按技术分层 | controller、service、repository 各一个顶层包 | 与框架约定一致,上手快 | 一个业务改动需要跨多个包,包内聚性低,随规模增长边界模糊 |
| 按业务能力 | order、payment、inventory 各一个顶层包,包内再分层 | 业务改动集中在一个包内,边界清晰,便于拆分 | 需要先确定能力边界,公共代码归属需要约定 |
演进路径通常是:中小规模时按技术分层足够;当同一层中出现互不相关的大批类(例如 service 包下有几十个服务且彼此无关)时,改为先按业务能力分包,再在包内分层。
包内分层的深度应保持克制:每增加一层就增加一次转换与一次跳转,三层以上且中间层只是转发时,应考虑合并。
2.7 边界手段:包可见性与模块系统
| 手段 | 能力 | 限制 |
|---|---|---|
| 包可见性 | 同一包内的类默认可见,跨包必须通过公开接口 | 仅在同一模块内有效,无法约束子包之间的依赖 |
| 构建模块 | 通过多模块工程把可见性提升到模块级 | 需要维护模块声明与依赖关系,构建配置复杂度上升 |
| 模块系统 | 语言级模块声明,显式导出包并声明依赖 | 引入成本高,与部分类库的自动模块机制存在摩擦 |
| 架构测试 | 用测试断言表达依赖规则 | 属于事后检查,违反时在测试阶段失败而非编译期失败 |
组合使用是常态:用包可见性隐藏实现细节,用架构测试守住跨包与跨模块的依赖方向,在核心边界处才引入构建模块或模块系统。
2.8 边界的成本与过度设计识别
过度设计的信号:
- 接口只有一个实现且短期内不会有第二个实现,接口存在的唯一理由是"架构要求"。
- 转换层只是字段逐一赋值,两侧类型结构完全一致。
- 分层的每一层都在转发调用,没有任何逻辑。
- 边界划分与团队沟通边界不一致,需要频繁跨团队修改。
判断标准是"这条边界是否会被跨越"。会被替换的外部依赖、会变化的第三方接口、需要独立测试的业务规则值得设边界;稳定且唯一的实现不必为形式设接口。
三、实现
3.1 业务能力优先的包结构
com.example.shop
├── order # 一个业务能力一个顶层包
│ ├── interfaces
│ │ ├── OrderController.java
│ │ └── OrderAssembler.java # 内外对象转换
│ ├── application
│ │ ├── OrderApplicationService.java # 用例编排、事务边界
│ │ └── command
│ ├── domain
│ │ ├── model
│ │ ├── event
│ │ ├── repository
│ │ │ └── OrderRepository.java # 接口定义在领域层
│ │ └── service
│ └── infrastructure
│ ├── persistence
│ │ ├── OrderRepositoryImpl.java
│ │ └── OrderPO.java
│ └── messaging
├── payment
├── inventory
└── shared # 跨能力共用的最小集合
├── domain # 共享的值对象与基础类型
└── infrastructure
约定要点:
shared只放真正被多个能力共用的内容,避免演化成新的"技术分层"垃圾包。- 能力之间通过应用层接口或领域事件协作,不允许直接访问对方的内层包。
- 每个能力内部的四层结构保持一致,便于人员流动与代码定位。
3.2 用架构测试表达依赖规则
class ArchitectureTest {
// 领域层不得依赖基础设施层与框架
@ArchTest
static final ArchRule domain_should_not_depend_on_infrastructure =
noClasses().that().resideInAPackage("..domain..")
.should().dependOnClassesThat()
.resideInAnyPackage("..infrastructure..", "..interfaces..",
"org.springframework..", "jakarta.persistence..");
// 接口层不得直接访问基础设施层
@ArchTest
static final ArchRule interfaces_should_not_access_infrastructure =
noClasses().that().resideInAPackage("..interfaces..")
.should().dependOnClassesThat().resideInAPackage("..infrastructure..");
// 仓储接口必须位于领域层,实现必须位于基础设施层
@ArchTest
static final ArchRule repository_location =
classes().that().haveSimpleNameEndingWith("Repository")
.and().areInterfaces()
.should().resideInAPackage("..domain..");
// 业务能力之间不得直接互相依赖内层
@ArchTest
static final ArchRule slices_should_be_free_of_cycles =
slices().matching("com.example.shop.(*)..").should().beFreeOfCycles();
}
<!-- 在构建中执行:违反规则时构建失败,使依赖方向成为可验证的约束 -->
<plugin>
<groupId>com.tngtech.archunit</groupId>
<artifactId>archunit-maven-plugin</artifactId>
<executions>
<execution>
<phase>test</phase>
<goals><goal>test</goal></goals>
</execution>
</executions>
</plugin>
要点:架构测试的价值在于把"口头约定"变成可执行的断言,且失败信息会直接指出违反的类。规则应从最关键的几条开始(领域层不依赖框架、无循环依赖),避免一次性引入大量规则导致难以推进。
3.3 循环依赖的识别与拆解
# 识别模块间的依赖与环:以 Maven 为例
mvn -q dependency:tree -Dincludes=com.example
# 用依赖分析工具查找循环,或直接由架构测试的 beFreeOfCycles 断言暴露
mvn -q test -Dtest=ArchitectureTest
四种拆解手段按优先级排列:
| 手段 | 做法 | 适用 |
|---|---|---|
| 提取共同依赖 | 把双方共用的概念下沉到更内层或独立模块 | 环由共享的模型或工具类引起 |
| 依赖倒置 | 调用方定义接口,被调用方实现,反转编译期依赖 | 环由"双向业务协作"引起 |
| 事件解耦 | 一方只发布事件,另一方订阅,不直接调用 | 环由"通知类调用"引起,且可以接受最终一致 |
| 合并职责 | 承认两个模块本属同一职责,合并为一个 | 环由边界划分错误引起 |
判定顺序是先看是否属于划分错误(合并),再看能否下沉(提取),最后才用接口或事件反转依赖。用接口强行维持一个逻辑上不成立的边界,会让结构长期处于别扭状态。
3.4 端口与适配器的落位
// 被动端口:定义在领域层,表达"应用需要什么能力"
public interface PaymentGateway {
PaymentResult charge(PaymentRequest request);
}
// 被动适配器:实现在基础设施层,表达"如何用具体技术实现"
@Repository
public class StripePaymentAdapter implements PaymentGateway {
private final StripeClient client;
@Override
public PaymentResult charge(PaymentRequest request) {
StripeResponse response = client.charge(toStripeRequest(request));
return toPaymentResult(response); // 外部类型不越过边界
}
}
// 驱动端口与适配器:控制器调用用例接口,用例实现在应用层
public interface PayOrderUseCase { // 驱动端口
void pay(PayCommand command);
}
@RestController
public class OrderController { // 驱动适配器
private final PayOrderUseCase payOrderUseCase;
@PostMapping("/orders/{id}/pay")
public void pay(@PathVariable String id) {
payOrderUseCase.pay(new PayCommand(id));
}
}
要点:外部系统的请求与响应类型只在适配器中出现,越过边界前必须转换为本地概念,否则第三方接口变更会直接传播到业务代码。
3.5 边界验证
# 1. 架构测试:依赖方向与循环
mvn -q test -Dtest=ArchitectureTest
# 2. 检查领域层是否出现框架类型(编译期依赖的旁证)
grep -rInE 'jakarta\.persistence|org\.springframework\.(stereotype|transaction|web)' \
src/main/java/com/example/shop/order/domain/ || echo "领域层无框架依赖"
# 3. 检查跨能力直接引用(除应用层接口与共享包)
grep -rInE 'com\.example\.shop\.(payment|inventory)\.(domain|infrastructure|interfaces)' \
src/main/java/com/example/shop/order/ || echo "无跨能力内层引用"
# 4. 只测试业务规则,不启动容器与数据库(验证边界是否真实存在)
mvn -q test -Dtest='*DomainTest'
第四条验证最直接:如果单元测试必须启动 Spring 上下文或连接数据库才能验证业务规则,说明边界并未真正建立。
3.6 常见问题对照
| 现象 | 常见原因 | 处置 |
|---|---|---|
| 修改一处需要改动多个包 | 采用按技术分层且内聚性低 | 改为按业务能力分包,包内再分层 |
| 领域测试必须启动 Spring | 领域对象依赖框架或直接依赖仓储实现 | 分离持久化对象,仓储接口下沉到领域层 |
| 接口只有一个实现 | 为形式引入的接口 | 去掉不必要的接口,仅在有替换或隔离需求时保留 |
| 模块间出现编译期环 | 双向业务协作或共享模型未下沉 | 按 3.3 的四种手段依次判定 |
| 架构测试频繁失败且被忽略 | 规则一次引入过多,或规则与现状差距过大 | 先固化关键规则,对存量代码逐步收敛 |
| 转换层只是字段复制 | 内外类型结构一致且无隔离需求 | 合并类型,取消转换层 |
| 端口数量爆炸 | 端口按方法而非按能力划分 | 按能力聚合接口,减少端口数量 |
| 共享包不断膨胀 | 未约束投入共享包的门槛 | 约定只有被两个以上能力使用且语义一致的内容才可下沉 |
| 子包可见性无法约束 | 包可见性作用域仅限同一包 | 用架构测试或构建模块补充约束 |
| 更换外部组件时改动范围大 | 外部类型越过边界进入业务代码 | 引入适配器并完成类型转换 |
四、总结
- 结构问题以循环依赖、跨层调用、共享可变状态三种形式持续消耗维护成本,根因是依赖关系未被显式声明。
- 架构风格要回答三个问题:依赖方向、业务规则的归属与依赖范围、外部变化如何被隔离。
- 分层架构直观但无法清楚表达领域与基础设施之间的真实依赖方向,需要依赖倒置把它显式化。
- 端口与适配器以"应用核心加可替换插件"表达边界,收益是外部依赖可替换、业务规则可在无数据库与网络的环境下测试。
- 整洁架构与洋葱架构的依赖规则只有一条:依赖由外向内,内层不得引用外层名称,跨边界通过接口与传递对象完成。
- 三种风格的共同点比差异更重要:业务规则不依赖框架、外部依赖通过接口反转、依赖方向单向。
- 依赖倒置的落地方式是接口与实现分属不同模块,接口归"使用者"所在的模块,由此产生编译期依赖与运行期调用方向相反的效果。
- 分包策略随规模从按技术分层演进到按业务能力分包,判定信号是同一层中出现大量互不相关的类。
- 边界手段中包可见性能力有限,架构测试是最实用的约束方式,构建模块与模块系统用于核心边界。
- 边界的价值取决于它是否会被跨越,稳定且唯一的实现不必为了形式引入接口与转换层。