一、起源

1.1 依赖方向失控的三种表现

结构问题不会立刻导致故障,而是以三种方式持续消耗维护成本:

表现 具体形态 后果
循环依赖 模块 A 调用 B,B 又调用 A;类之间形成环 无法单独理解与测试任一模块,改动影响不可预测
跨层调用 接口层直接访问数据访问层,领域层调用外部服务 业务规则绕过编排,事务与校验被跳过
共享可变状态 多个模块直接读写同一个全局对象或静态集合 一处修改影响多处,问题难以复现

三者的共同点是把"依赖"从显式变隐式:不通过接口声明协作关系,而是通过直接引用与共享状态耦合。

1.2 架构风格要回答的问题

架构风格的作用不是规定目录名称,而是回答三个问题:

  1. 哪些代码可以依赖哪些代码,方向如何。
  2. 业务规则放在哪一层,依赖什么、不依赖什么。
  3. 外部世界的变化(数据库、消息、第三方接口)如何被隔离,不渗透进业务规则。

三个问题的答案共同决定:能否在不启动数据库与网络的情况下测试业务规则,以及更换外部组件时的影响范围。

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,调用用例

四条规则:

  1. 接口所在模块由"谁使用"决定,而不是由"谁实现"决定。仓储接口被应用与领域使用,因此放在它们可依赖的内层。
  2. 实现模块依赖接口模块,因此基础设施层处于外层,编译期依赖方向与运行期调用方向相反,这正是倒置的含义。
  3. 数据传输对象跨越边界时需要转换,不允许外层类型进入内层;转换位置在适配器或装配器中。
  4. 框架注解只允许出现在外层与装配位置,领域对象中不出现持久化与事务注解(这一点与聚合的实现约束一致,见 领域驱动设计落地)。

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 的四种手段依次判定
架构测试频繁失败且被忽略 规则一次引入过多,或规则与现状差距过大 先固化关键规则,对存量代码逐步收敛
转换层只是字段复制 内外类型结构一致且无隔离需求 合并类型,取消转换层
端口数量爆炸 端口按方法而非按能力划分 按能力聚合接口,减少端口数量
共享包不断膨胀 未约束投入共享包的门槛 约定只有被两个以上能力使用且语义一致的内容才可下沉
子包可见性无法约束 包可见性作用域仅限同一包 用架构测试或构建模块补充约束
更换外部组件时改动范围大 外部类型越过边界进入业务代码 引入适配器并完成类型转换

四、总结

  1. 结构问题以循环依赖、跨层调用、共享可变状态三种形式持续消耗维护成本,根因是依赖关系未被显式声明。
  2. 架构风格要回答三个问题:依赖方向、业务规则的归属与依赖范围、外部变化如何被隔离。
  3. 分层架构直观但无法清楚表达领域与基础设施之间的真实依赖方向,需要依赖倒置把它显式化。
  4. 端口与适配器以"应用核心加可替换插件"表达边界,收益是外部依赖可替换、业务规则可在无数据库与网络的环境下测试。
  5. 整洁架构与洋葱架构的依赖规则只有一条:依赖由外向内,内层不得引用外层名称,跨边界通过接口与传递对象完成。
  6. 三种风格的共同点比差异更重要:业务规则不依赖框架、外部依赖通过接口反转、依赖方向单向。
  7. 依赖倒置的落地方式是接口与实现分属不同模块,接口归"使用者"所在的模块,由此产生编译期依赖与运行期调用方向相反的效果。
  8. 分包策略随规模从按技术分层演进到按业务能力分包,判定信号是同一层中出现大量互不相关的类。
  9. 边界手段中包可见性能力有限,架构测试是最实用的约束方式,构建模块与模块系统用于核心边界。
  10. 边界的价值取决于它是否会被跨越,稳定且唯一的实现不必为了形式引入接口与转换层。