二十个组件互相依赖、review 拦不住:我把分层写进 19 个 pom,并用两条 Maven 机制否掉了 BOM 拆分(二十七)

Source

组件库被第七个服务引用后,依赖方向只剩自觉,一次 optional 失效就把审计模块拖进认证体系。我把五层规则写进 19 个模块 pom,让违规在构建期失败,并用两条机制否掉了 BOM 拆分提案。

一、痛点:真正让我动手的不是「依赖乱」,是一个被迫拆出来的模块

1.1 现象:optional 没能让依赖变可选

fate-audit-core 一开始想把 fate-auth 当可选能力:有认证上下文就记真实操作人,没有就记 anonymous。于是 pom 里写了 <optional>true</optional>。

结果是引入审计的服务全被拖进了认证体系:只要一个审计日志的服务,被迫接受会话、JWT 那一整套。原因很朴素——本模块代码里直接 import 了 fate-auth 的认证用户类型。optional 只影响这条依赖会不会传递出去,不影响本模块能不能编译;你 import 了它,它就是你编译期的硬依赖。

最后的修法不是改作用域,是把适配器拆成独立模块 fate-audit-auth,fate-audit-core 不再 import fate-auth 的任何类,两者之间没有回边。这段经过就在 fate/ARCHITECTURE.md:98-101 的注释里,fate-audit-core/pom.xml:21-23 还留着一句「禁止 L1(fate-cache)/ L2(fate-tracing)反向依赖本模块」。

第二类现象更常见,可以精确复现:只要有人在 fate-core 里加一行 fate-gateway-core(比如想复用网关里那个 filter 的工具方法),任何只引了 fate-core 的 worker 服务,跑 mvn dependency:tree -Dincludes=io.projectreactor.netty 都会多出一整棵 reactor-netty / spring-webflux。复现条件就八个字:下级模块引用了上级模块。改一行 XML 就能造出来。这条依赖不会让任何模块编译失败,只会在下游的依赖树里悄悄长大。

第三类是「引入成本不可预估」:业务方要用分布式锁,文档说引 fate-lock,但 fate-lock 往下依赖 fate-core,fate-core 里既有 Web 工具又有加密工具,最后到底带不带 Web,只能跑一遍 dependency:tree 才知道——而这本该是看一眼层号就能回答的问题。这种不可预估最后会变成两种行为:业务方要么全量引入、反正说不清,要么干脆不用、回去自己写一个。

1.2 机制

Maven 在解析阶段就把整张依赖图算清楚了,但「这条边允不允许」没有任何内建规则:optional / provided 管的是「传不传出去」,不是「允不允许写进来」。依赖方向因此是一条只靠人守的约定,而人会换岗,换岗的人也不会去读上一任的评审记录。这也是为什么 mvn dependency:tree 只能当诊断工具:它告诉你图上有什么,不告诉你哪些边是错的,更不负责在下一次改动时叫停。

用一张图把「optional 为什么拦不住」画清楚:

optional=true

代码里 import 认证用户类型

只影响是否传递出去

fate-audit-core
声明 optional 依赖

fate-auth

编译期硬依赖

引入审计的服务
被迫接受会话 / JWT

不解决编译期依赖

看图要点:optional 只作用在「传不传出去」这条虚线上,而真正把认证体系拖进来的是实线——代码里的 import。两条线不是一回事,所以改作用域永远修不好这个问题。

1.3 我最初的三个错误做法

第一个是加 code review 检查项:diff 里多一行 <dependency> 就驳回。失败在可见性——评审者要判断这行的影响,得在脑子里跑一遍传递闭包,而影响面横跨 20 个模块,谁也看不全;更糟的是一行依赖长得太像噪音,漏看毫无代价,而后果要在下一次发版、某个服务多出三十个坐标时才浮现。

第二个是「规则放根 pom,一处维护」。写完当天构建全红:根 pom 里的 execution 会被所有子模块继承,L0 那条「禁止一切 fate-*」直接判死了 L1 依赖 core 这种完全合法的边。往下只能退成所有模块的交集,也就是什么都不禁。这类误伤比漏放行更难查,因为它看起来像规则写错了,其实是装配位置错了——两种错误在日志里长得一模一样,只有 execution id 能区分。

第三个是写文档和 pom 注释。文档不会让构建失败。证据就在仓库里:ARCHITECTURE.md:136-137 写着「除 fate-tracing-agent 外,全部 18 个组件模块均已接入」,而实际带 enforce-fate-layer-L* 的 pom 是 19 个。文档写完的当天就开始漂,而漂移没有任何告警。


二、问题拆解:把「不能这么依赖」拆成五个能判定的问题

拆成五个而不是一个「架构要清晰」,是因为失败路径本来就有两条:一条是有人想引入一个组件,卡在版本对齐;一条是有人想改一个模块的依赖,卡在方向判定。混在一起谈,结论就只能是一句没法执行的口号。五个问题的顺序也有讲究:前三个决定「怎么拦」,后两个决定「拦之前先想清楚什么不能一起改」。

子问题 约束 现成方案为什么不够 判定标准
层级怎么划 20 个模块要被业务方按需组合 按包名归类、按 jar 大小归类,都判不出方向 任意两个模块的依赖方向能用层号大小一句话判定
谁来拦 不能误伤合法的同层、向下依赖 code review 靠人,漏看没有代价 违规即 BUILD FAILURE,失败信息指到具体坐标
规则放哪 每个模块的合法集合都不一样 放根 pom 一处维护,只能写最松的交集 每个 pom 的禁止清单等于它不该依赖的模块全集
版本谁对齐 24 条内部模块 + 40 条第三方要一处改 各模块自己写版本,一次升级改 20 处 业务方 pom 里不出现任何 fate 模块的 version
BOM 要不要分层 有人担心 core 与 web 混装 直觉上拆开更干净,没人验证过机制 拆分必须在 Maven 机制上成立,而不只是看起来干净

前四个子问题是「把约定变成构建失败」,第五个是「别在验证机制之前动版本入口」。一个是加法,一个是必须先算清的减法——减法做错的代价比不做更大:加法最坏是漏放行一条依赖,减法做错是把整套版本对齐能力弄丢。

判定标准那一列是事后补的,但它决定了后面所有取舍:一条标准如果只能说成「看起来更清楚」,那它是偏好,而偏好没法在 review 里达成一致。所以每条我都尽量写成可观察的事件:层号能比大小、违规能让构建失败、失败日志里有坐标、业务 pom 里有没有 version。这些都能被第三个人独立验证,不需要我在场解释。

第五个问题最容易被跳过,因为答案通常是「不拆」;而把「为什么不拆」写成两条机制事实,比写成一句直觉难得多,也值钱得多:否掉一个提案要靠机制,不靠语气。


五个子问题之间的推进关系,可以这样看:

机制上不成立

不能这么依赖

加法:把约定变成构建失败

减法:先算清什么不能一起改

层级怎么划

谁来拦

规则放哪

版本谁对齐

BOM 要不要分层

可判定的规则

否掉拆分提案

构建期失败 + 单一版本入口

看图要点:左边四问是加法,产出「可判定的规则」;右边一问是减法,产出「否掉提案」。减法做错的代价比不做更大,所以它必须排在加法之后、动手之前。

三、实现

3.1 整体结构

允许

import 只注入版本
不产生依赖边

Application 层
4 个 demo

L3 高级能力
9 个模块

L2 业务能力
5 个模块

L1 横切能力
4 个模块

L0 基础
fate-core

fate-bom
只给版本

看图要点:

  1. 箭头方向就是允许的依赖方向,任何一条向上的边都会在构建期被 enforcer 击落。
  2. L3 可以跨层直接依赖 L0、L1,不是「只能依赖相邻下一层」——把这理解成逐层,就会给 L3 写出一堆没必要的规则。
  3. 底部那条带 fate-bom 的虚线不在依赖图里,它只是版本注入,这也是后面否掉拆分提案的关键。

3.2 逐子问题实现

3.2.1 层级怎么划:四层加一个内核
层 定位 允许依赖 真实模块数
L0 基础内核 无任何 fate 依赖 1(fate-core)
L1 横切能力 L0 4(cache / crypto / lock / response)
L2 业务能力 L0、L1 5(session / tracing / sql-log / desensitize / scheduler-core)
L3 高级能力 L0、L1、L2 9(auth / audit-core / audit-auth / gateway-core / websocket-core / logging / captcha / mybatis-plus / ssh)
Application 组装与示例 全部 4 个 demo + tracing-agent

规则表则是它的反面,写的是每个层禁止什么:

层级 禁止依赖
L0 任何 fate-*
L1 L2 / L3 / Application
L2 L3 / Application
L3 Application
Application 无禁止

这五条不是设计文档里的口号,是 19 个 pom 里逐一写死的清单。分发一下就能看出分层不是凭感觉排的:L0 只被写「禁止一切」,L3 只被写「禁止 Application」,越往上禁得越少,规则也越短。这张表还有一个容易被忽略的性质:它只禁止方向,不禁止数量——L3 依赖全部 9 个下层模块也合法,这本就是组件库该有的样子。

3.2.2 规则写进各模块自己的 pom

19 个模块各有一段,形制完全一致。下面这段取自 fate-gateway-core/pom.xml:108-124,是最短的一段(L3 只需要禁 Application):

<execution>
    <id>enforce-fate-layer-L3</id>
    <goals><goal>enforce</goal></goals>
    <configuration>
        <rules>
            <bannedDependencies>
                <excludes>
                    <exclude>cn.com.jiaxing.fate:fate-gateway-demo</exclude>
                    <exclude>cn.com.jiaxing.fate:fate-scheduler-demo</exclude>
                    <exclude>cn.com.jiaxing.fate:fate-websocket-demo</exclude>
                    <exclude>cn.com.jiaxing.fate:fate-audit-demo</exclude>
                    <exclude>cn.com.jiaxing.fate:fate-tracing-agent</exclude>
                </excludes>
            </bannedDependencies>
        </rules>
    </configuration>
</execution>

为什么不能放根 pom:根 pom 里的 execution 是全量继承的,没有「只对某些模块生效」这种写法。而 19 个模块的合法集合本来就不同——L0 要禁掉除自己以外的全部,L3 只需要禁 Application。放一处只能写交集,交集就是空规则。

所以根 pom 里关于 enforcer 只剩三行版本声明(fate/pom.xml:616-620,插件版本 3.5.0),一条 execution 都没有。父 POM 负责对齐版本,子 POM 负责声明身份,这是这套方案里我唯一坚持的分工。19 段规则之间有大量重复(L0 那段最长,有 21 条 exclude;L3 只有 5 条),但这里的重复是优点:每段都能独立读懂,改一个模块不会牵连别的模块。

3.2.3 execution id 统一成 enforce-fate-layer-L{0…3}

19 个 id 的分布是 L0 一个、L1 四个、L2 五个、L3 九个,与上一节的模块数严格对应。统一命名的收益不在写的时候,在坏的时候:

[WARNING] Rule 0: org.apache.maven.plugins.enforcer.BannedDependencies failed with message:
Found Banned Dependency: cn.com.jiaxing.fate:fate-session:jar:1.6.0-SNAPSHOT
Use 'mvn dependency:tree' to locate the source of the banned dependencies.
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-enforcer-plugin:3.5.0:enforce
  (enforce-fate-layer-L1) on project fate-cache: Some Enforcer rules have failed.

看到 (enforce-fate-layer-L1) 就知道是哪个模块、哪一层违规,不用翻 pom。它还顺手把「谁违规」和「规则在哪」写在了一起,新人不必先读完架构文档才能定位:id 里的层号直接对上 3.2.1 的表,报错的模块名直接对上目录。这条纪律也顺手防住了一个静默故障:同一个 pom 里复制出两段同名 execution,后者会覆盖前者,等于规则少了一半,构建照样绿。

3.2.4 BOM 只有一个版本入口

24 条内部模块坐标、40 条第三方坐标,全部只写在根 pom 的 dependencyManagement 里,共 64 条:

<dependencyManagement>
    <dependencies>
        <!-- 24 条 fate 条目 + 40 条第三方,版本只在这里写一次 -->
        <dependency>
            <groupId>cn.com.jiaxing.fate</groupId>
            <artifactId>fate-core</artifactId>
            <version>${project.version}</version>
        </dependency>
        <dependency>
            <groupId>cn.com.jiaxing.fate</groupId>
            <artifactId>fate-response</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

fate-bom 这个模块本身只有 55 行,没有一条自己的 dependencyManagement——它的 parent 就是 fate-parent,版本清单靠继承拿到。业务方在 dependencyManagement 里 import 它之后,引任何 fate-* 组件都不用再写 version。

这样做的代价是 fate-bom 自己「没有内容」,看起来像个空壳。但正是这个空壳,让升级只需要动一处:Spring Boot 版本往上走时,改的是父 POM 里的属性,19 个模块的 pom 一行都不用碰。

3.2.5 被否掉的拆分提案

有人提了个很合理的建议:既然 L0/L1 是「无 Web」的,L3 里 gateway、websocket 才涉及 Web,那把 BOM 拆成 fate-bom-core 和 fate-bom-web 两份,业务方按需引入,不是更干净?

我按机制验了一遍,两步就否掉了。

提案
拆成 core / web 两份 BOM

事实一
dependencyManagement
继承并合并

事实二
只声明版本
不传递依赖

子 BOM 仍携带
全量清单

不继承 parent 才能裁
要复制 40 个第三方版本

worker 根本不会被
带上 Web 依赖

拆分要解决的问题
并不存在

回退
单一 BOM + enforcer

看图要点:

  1. 左边一路打的是「能不能拆」,右边一路打的是「拆了有没有用」,两条都得走完才算否掉。
  2. 右路的结论最反直觉:BOM 里出现 fate-auth 条目,不会让引用方多一条依赖边,所以你担心的「被迫带 Web」根本没发生过。
  3. 左路才是真成本:想裁减就必须脱离父 POM,代价是 40 个第三方版本要在每份子 BOM 里复制一遍。

两条机制事实写清楚就是:

  • dependencyManagement 是继承并合并的。子 BOM 只要以 fate-parent 为 parent,就无法删掉父 POM 已声明的条目,拆出来的子 BOM 实际仍携带全量清单。
  • dependencyManagement 只声明版本,不传递依赖。BOM 里有 fate-auth 的条目,不代表引用方引入了 fate-auth,更不代表引入了 Spring Web。

这个提案的动机并不荒谬,它想解决的是「一个 jar 同时带着两套运行时的代码」。但在 Maven 里,这个问题从来不该由 BOM 层回答:BOM 是一张版本表,它连一条依赖边都不产生。

如果为了「能裁减」而不继承 fate-parent,40 个第三方版本就要在每份子 BOM 里复制,改漏风险反而放大。结论原话我留在了 fate-bom/pom.xml:25-53 的注释和 ARCHITECTURE.md 第 5.1 节:分层带来的收益接近零,成本却是版本对齐能力倒退。这个方案在演进记录里的状态是「已废弃」。回头看,它最大的价值不是被采纳,而是逼我把这两条机制写进 pom 注释——后来再有人提同样的想法,我只要指一下那 28 行注释。

3.2.6 真正让 worker 不带 Web 的,是 provided 与条件装配

既然不靠 BOM 分层,那「按需引入」靠什么?靠各模块 pom 里对 Web 依赖的作用域,以及自动配置的条件装配。fate-core 与 fate-response 里,spring-webmvc、spring-webflux、jakarta.servlet-api 全是 provided;fate-gateway-core 里则是 <optional>true</optional>——两者都不传递,只是写法不同。

@Configuration(proxyBeanMethods = false)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
@ConditionalOnClass(name = "jakarta.servlet.Servlet")
static class ServletResponseConfiguration {
    
      
    // servlet-api 是 provided,不能直接引用 Servlet 类型,
    // 所以条件判断只能写类名字符串,缺类时整段配置不生效
    @Bean
    @ConditionalOnMissingBean
    public GlobalExceptionHandler globalExceptionHandler(ResponseProperties properties) {
    
      
        return new GlobalExceptionHandler(properties);
    }
}

@Configuration(proxyBeanMethods = false)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.REACTIVE)
@ConditionalOnClass(name = "org.springframework.web.reactive.DispatcherHandler")
static class ReactiveResponseConfiguration {
    
      
    // 同一个 jar 要同时跑在 MVC 与 WebFlux 上,条件装配是唯一不引入硬依赖的写法
    @Bean
    @ConditionalOnMissingBean
    public ReactiveGlobalExceptionHandler reactiveGlobalExceptionHandler(
            ResponseProperties properties, ObjectMapper objectMapper) {
    
      
        return new ReactiveGlobalExceptionHandler(properties, objectMapper);
    }
}

这段代码来自 fate-response 的 ResponseAutoConfiguration。注意它反过来给分层立了个边界:provided 不是免费的。同一个 pom 里 jakarta.validation-api 就必须是 compile(注释里写着原因:改成 provided 后启动直接抛 NoClassDefFoundError: jakarta/validation/ConstraintViolationException),因为框架要按类型加载它。能不能 provided,取决于这个类型会不会被编译期或运行期按类型解析。 只按「是不是 Web 依赖」来判断,一定会在某个 API 上踩坑。三条机制合起来才算「按需引入」:作用域管传递,条件装配管缺失,enforcer 管方向。

把「按需引入」的三条机制串起来,就是下面这张图:

管传递

管缺失

管方向

业务方引入 fate-* 组件

作用域
provided / optional

条件装配
@ConditionalOnClass / OnWebApplication

enforcer
禁止反向依赖

worker 不带 Web

缺类时整段配置不生效
而不是启动失败

看图要点:三条机制各管一件事,缺一条都不成立——作用域管传递、条件装配管缺失、enforcer 管方向。provided 不是免费的,能不能 provided 取决于这个类型会不会被按类型解析。

3.3 为什么是这个粒度

层级数和规则形式我都试过别的选项,最后留下的这套,每个选择都有一个「不选更简单那个」的理由:

候选粒度 为什么没选
三层(core / 业务 / 应用) 20 个模块里 L1 的 4 个、L2 的 5 个会挤成一层,方向判不出来
八层、按 DDD 分层 记不住;超过五层就没人能在 review 时心算出方向
白名单 allowlist bannedDependencies 只支持黑名单;白名单要枚举 19 个坐标,新增一个模块得改 19 个 pom
父 POM 的 profile 控制 profile 按构建环境激活,而层级是模块固有属性,两回事
每层一份 BOM 见 3.2.5,Maven 机制不支持裁减

层数还有一个来自评审的约束:一个人能凭空判断方向的层数,就是他能在 review 时不出错的层数。我试过按 DDD 分八九层,结果是每次 review 都要打开图对一遍。

黑名单这个选择值得单独说:它的成本结构是「新增模块时,需要人到 19 个 pom 里各补一行 exclude」。这确实是持续成本,我接受它,因为它是一次性、可见、可 grep 的,而且漏了会在下一次有人反向依赖时暴露。白名单的成本反过来:每加一个模块改 19 处,漏一处就是误放行,且永远不会有人发现。规则越短也越容易被 review 确认——L3 那五条 exclude 扫一眼就知道对不对,写成「允许依赖 L0、L1、L2 的所有坐标」没人会逐个数。

规则粒度还有一个反向验证:把五层规则拿给没参与设计的人看,他应该能在不查图的情况下判断「A 能不能依赖 B」。做不到就说明层没划完,而不是规则写漏了。

至于为什么是 19 而不是 25:4 个 demo 属于 Application 层,「无禁止」本身就是规则;fate-tracing-agent 只依赖 opentelemetry-javaagent(runtime),没有任何 fate-* 坐标,给它写规则是空转。反过来,如果某个模块将来开始依赖同层模块,规则要跟着改的也只有它自己那一段。


四、权衡、边界与坑

4.1 取舍表

决策 选择 备选 代价与边界
依赖约束 enforcer 黑名单,写在各模块 pom code review / ArchUnit 新增模块要人工补 exclude,漏了不报
层级 五层(四层加内核) 三层、按 DDD 分 少了表达力弱,多了记不住
版本管理 单一 BOM,继承父 POM 拆两份 BOM 版本层面无法区分「有无 Web」
Web 依赖控制 provided / optional + 条件装配 拆 BOM 隔离 缺类靠条件装配兜住,写错就启动失败

4.2 三个坑

坑一:规则放根 pom,全量误伤。 现象是加 L0 规则后 19 个模块齐红。定位:失败信息里的 execution id 是 enforce-fate-layer-L0,报错模块却是 fate-auth——规则来自继承而非本模块。修法:根 pom 只留 pluginManagement 的版本,execution 全部下沉。

坑二:exclude 只写 artifactId,规则静默失效。 现象是要禁 fate-session,违规依赖照样通过。定位:exclude 匹配的是 groupId:artifactId。修法:一律写全坐标 cn.com.jiaxing.fate:fate-xxx。

坑三:把规则写进 pluginManagement。 现象是模块 pom 里加了规则,故意引违规依赖仍然绿。定位:pluginManagement 只提供默认配置,不产生 execution。修法:模块自己在 <build><plugins> 里声明插件并给 id。

三个坑的共同点,是「规则看起来生效了,其实没有」:

全量继承

匹配 groupId:artifactId

只提供默认配置

规则没生效

坑一:规则放根 pom

坑二:exclude 只写 artifactId

坑三:规则写进 pluginManagement

19 个模块齐红
误伤合法依赖

违规依赖照样通过
静默失效

不产生 execution
构建仍然绿

修法:execution 下沉到各模块 pom

看图要点:三个坑的失败方向不同——坑一是误伤(红得太多),坑二、坑三是漏放(绿得可疑)。前者靠 execution id 定位,后者只能靠「故意引一条违规依赖」来验证规则是否真的在跑。

4.3 什么时候不该用

模块少于五个、依赖本来就是直线时,五层和 19 段规则都是纯负担,一张 README 够。需要按客户交付不同产物时(比如 SDK 不含 Web),分层也帮不上忙,那属于打包问题,用 maven-assembly 或独立仓库。团队没有 CI 时,enforcer 只是「反正我会 -DskipTests 顺便 -Denforcer.skip」的摆设——规则的价值来自「构建必须过」。

4.4 防不住什么

反射、SPI、字符串类名一律防不住:Class.forName("cn.com.jiaxing.fate.auth.core.AuthenticatedUserHolder") 里没有依赖坐标,enforcer 看不见。

optional 失效也防不住:像 1.1 节那样 import 了可选依赖的类,编译能过、规则不报——依赖确实声明了。

demo 被误用于生产也防不住:Application 层「无禁止」,只能靠文档。

规则本身也可能有洞。L0 那 21 条 exclude 是逐个模块手写的:L1 的 4 个、L2 的 5 个、L3 的 8 个和 4 个 demo 都在,但后拆出来的 fate-audit-auth 没列——它明明是 L3 模块,一旦有人让 core 反向依赖它,就拦不住;fate-tracing-agent 也没列,它目前不依赖任何 fate 模块,规则不会被触发。清单是人维护的,就会漏。


五、可以直接抄走的清单

  1. 把层级判定写成一句话:方向能用层号比大小,否则层没划完。
  2. 把 enforcer 规则写进各模块自己的 pom,根 pom 只留版本。
  3. exclude 一律写全坐标 groupId:artifactId。
  4. 统一 execution id 为 enforce-fate-layer-L{n},让失败日志自己说出层号。
  5. 把「新增模块要补 19 处 exclude」写进新增模块清单。
  6. 只留一个 BOM,业务方一律 import,业务 pom 不写 version。
  7. 想让能力「按需引入」,用 provided / optional 加 @ConditionalOnClass,别拆 BOM。
  8. 没有依赖的模块(如 agent)别加规则,空转只会让人以为覆盖了。