组件依赖地狱？尝试用ArchUnit守护项目架构边界

好，深夜十一点，你刚把 `UserService` 里的一个公共方法签名改掉，准备美美地下班。结果第二天一早，持续集成流水线红灯亮起，三个下游服务无一幸免地编译失败。你顺着报错信息溯源，发现调用方竟然是三个月前离职同事留下的“核心业务组件”。你盯着依赖关系图，发现 `common-utils` 被五十个模块同时引用，而 `order-service` 居然反向依赖了 `user-service` 的 DAO 层。

这画面是不是很熟悉？架构腐化从来不是一夜之间发生的，它始于每一次“先这样吧，后续再重构”的妥协。当我们还在依靠 Code Review 里那句“注意别乱引用啊”来维系秩序时，依赖地狱已经在悄悄挖坑了。

架构规则，应该像单元测试一样被自动执行

我们需要一种机制，把架构约束变成代码仓库里可执行、可验证的自动化测试。在 JVM 生态里，`ArchUnit` 就是为此而生的利器。它是一个轻量级的测试库，能够扫描字节码并分析包、类、方法之间的依赖关系，允许我们用纯 Java 代码描述架构规则，并在 CI 中一键验证。

它不是那种需要大动干戈引入的重型框架，恰恰相反，它只是 JUnit 的一个扩展。你完全可以把它当作一个普通测试类来写，例如：

@RunWith(ArchUnitRunner.class)
@AnalyzeClasses(packages = "com.example.project")
public class ArchitectureRuleTest {

    @ArchTest
    public static final ArchRule layeredArchitecture_should_be_respected =
        layeredArchitecture()
            .consideringAllDependencies()
            .layer("Controller").definedBy("..controller..")
            .layer("Service").definedBy("..service..")
            .layer("Persistence").definedBy("..repository..")
            .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
            .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
            .whereLayer("Persistence").mayOnlyBeAccessedByLayers("Service");

    @ArchTest
    public static final ArchRule service_should_not_depend_on_web_layer =
        noClasses()
            .that().resideInAPackage("..service..")
            .should().dependOnClassesThat()
            .resideInAnyPackage("..controller..", "..config..");
}

上面这两条规则，分别从分层约束和依赖方向两个维度进行锁定。从此以后，如果有人试图从 `Controller` 直接注入 `Repository`，或者从 `Service` 里调用 `Controller` 的类，测试就会直接失败，而且会精确指出是哪个类、哪一行触犯了哪条规则。

从“物理隔离”到“逻辑守护”

很多团队做过模块化，把代码拆进不同的 Maven/Gradle 模块里，试图用物理边界来限制依赖。但物理隔离往往拦不住 `import` 时的手滑——`service` 模块的 `pom.xml` 里一旦多写了一个依赖项，边界就形同虚设了。

ArchUnit 的价值恰恰在于，它在逻辑层面划出了真正的红线。比如最经典的“循环依赖”检查：

@ArchTest
public static final ArchRule no_cycles_between_packages =
    slices().matching("com.example.(*)..").should().beFreeOfCycles();

还有针对敏感资源的保护：

@ArchTest
public static final ArchRule domain_should_not_use_orm =
    noClasses()
        .that().resideInAPackage("..domain..")
        .should().dependOnClassesThat()
        .resideInAnyPackage("..mybatis..", "..hibernate..", "..jpa..");

我们甚至可以对某些“god class”指定专属管制：

@ArchTest
public static final ArchRule utils_should_only_be_used_by_facade =
    classes()
        .that().haveSimpleName("CommonUtils")
        .should().onlyBeAccessed()
        .byAnyPackage("..facade..", "..adapter..");

当这些规则进入代码仓库，它就成了一面自动运转的哨塔。新来的同学不熟悉历史背景？没关系，跑一遍测试就知道了。老员工想走捷径绕过架构？在你写下 import 的时候，测试就会跳出来说“此路不通”。

让规则循序渐进，而不是一刀切

推行 ArchUnit 时，最忌讳的就是理想主义地直接对存量系统启用全部规则。如果你的项目已经处于“依赖地狱”的中后期，第一次跑测试可能会抛出上百个错误——这不是规则的问题，而是历史债的问题。

正确的姿势是：先针对新增代码立规矩，再逐步修复存量债务。

你可以利用 `ArchRule` 的 `because()` 方法描述规则意图，同时在规则中加入 `as()` 指定别名，更方便定位问题。对于某些确需豁免的旧代码，可以通过 `ignoreDependency()` 或自定义谓词进行白名单管理，但每一条豁免都必须附带充分理由和负责人信息。

这种渐进式策略的意义在于，它让团队在不阻塞业务迭代的前提下，逐步走向一个清晰可维护的架构形态。毕竟架构治理的目的不是为了考试得高分，而是为了降低生产环境中的认知负载和变更风险。

结语

软件架构的崩坏往往不是某次重构失败造成的，而是无数次“就这一次”的侥幸累积而成的。ArchUnit 带来的不是万能解药，而是一种工程纪律的可落地形式——把架构愿景沉淀成自动化测试，让依赖于人的口头共识变成机器强制执行的标准。

人类很容易健忘，但测试不会。趁着依赖地狱还没吞没你的代码库，写第一条 ArchUnit 规则吧，就从禁止某个讨厌的包被随意引用开始。你未来的维护者会感谢你的。