一、起源
- 代码复用从复制源码演进为按坐标引用之后,构件的来源出现三种边界:项目内部、公司内部、公司外部。
- 三种边界的发布节奏、可信程度与故障影响范围不同,混用会带来两类问题:
- 内部模块被当成外部依赖使用,改动后必须执行
mvn install 才对其他工程生效,构建结果依赖本地仓库状态。
- 外部构件被随意升级,缺少版本收敛与安全审查,运行期出现方法签名不兼容。
- 按来源分层的目的,是给每一层匹配不同的引用方式、版本策略与治理手段。
二、原理
2.1 划分依据
| 维度 | 一方库 | 二方库 | 三方库 |
| 来源 | 同一工程或同一代码库内的模块 | 公司内部其他团队 | 外部组织或商业厂商 |
| 解析方式 | reactor 内直接解析,或本地仓库 | 私服(Nexus、Artifactory) | 中央仓库、镜像或商业仓库 |
| 版本节奏 | 跟随父 POM 的 ${project.version} | 联调用 SNAPSHOT,上线用 Release | 跟随社区或厂商版本 |
| 主要风险 | 模块边界混乱、循环依赖 | 接口不兼容、快照未更新 | 漏洞、许可、版本冲突 |
| 治理重点 | 依赖方向与模块粒度 | 发布流程与兼容性约定 | 版本收敛与安全审查 |
2.2 一方库
- 指同一工程内的模块依赖。父工程通过
<modules> 聚合,子模块之间以坐标互相引用,版本通常统一为 ${project.version}。
- 同一次 reactor 构建中,模块依赖直接由 reactor 解析,不需要先安装到本地仓库。
- 单独构建某个子模块、或在另一个独立工程中引用该模块时,才会走本地仓库解析,此时必须先执行
mvn install。
- 边界判定:只要源码与引用方在同一个代码库、同一次构建中,就属于一方库;一旦拆分为独立仓库并独立发布,即转为二方库。
2.3 二方库
- 指公司内部其他团队发布的共享构件,通常部署到私服,供多个业务工程复用。
- 存在两种版本形态:
- SNAPSHOT:可变版本,名称形如
1.4.0-SNAPSHOT,重复部署会覆盖,适合联调阶段。
- Release:不可变版本,名称形如
1.4.0,发布后不应再次覆盖,适合生产使用。
- 主要风险来自跨团队协作:接口删除或改签名、依赖传递带入了使用方不需要的构件、快照长期未更新导致联调结果不一致。
- 治理手段:接口变更遵循兼容性约定,发布前执行兼容性检查,正式版本禁止依赖 SNAPSHOT。
2.4 三方库
- 指外部组织提供的开源或商业构件,来源为中央仓库、镜像站或厂商提供的仓库。
- 引用前需要确认三件事:坐标与版本是否稳定存在、许可证是否允许当前使用方式、是否存在已知漏洞。
- 版本管理通常通过 BOM(
<type>pom</type> + <scope>import</scope>)统一,避免同一技术栈出现多个版本。
- 无法直接修改源码,出现缺陷时可选的处理方式是升级版本、用
exclusions 排除问题传递依赖,或自行维护内部补丁版本。
2.5 边界会移动
- 一方库拆分为独立仓库并对外提供,转为二方库。
- 二方库被外部客户使用,或公司整体对外提供,转为三方库视角的治理方式。
- 三方库被采购后由内部团队二次封装,对业务方表现为二方库,底层仍是三方库。
- 边界变化后需要同步调整版本策略、发布流程与审查手段,而不是沿用原来的引用方式。
三、实现
3.1 一方库引用
<dependency>
<groupId>com.example</groupId>
<artifactId>order-common</artifactId>
<version>${project.version}</version>
</dependency>
3.2 二方库引用
<dependency>
<groupId>com.example</groupId>
<artifactId>user-api</artifactId>
<version>1.4.0-SNAPSHOT</version>
</dependency>
3.3 三方库引用
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>3.2.5</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
import 只作用于 <dependencyManagement>,用于引入整套版本清单,不会真正引入依赖。
- 子模块声明依赖时省略
<version>,由 BOM 提供版本。
3.4 使用原则
- 禁止使用
systemPath:路径依赖不可移植,换机器或换构建环境即失败。
- 一方库保持单向依赖,避免模块之间循环引用导致 reactor 无法排序。
- 二方库的正式版本不依赖 SNAPSHOT,否则其他环境的构建结果不可复现。
- 三方库版本统一进入父 POM 的
<dependencyManagement>,不在子模块散落版本号。
- 不直接使用传递依赖带入的构件,凡是代码中直接引用的类,都显式声明依赖。
- 引用前的环境与目录约定见 Maven 入门:定位、环境与项目结构。
四、总结
- 一方库是同工程模块,由 reactor 直接解析,版本取
${project.version},跨工程使用前需 install。
- 二方库是公司内部共享构件,走私服,联调使用 SNAPSHOT,上线使用不可变的 Release。
- 三方库是外部构件,引用前确认坐标、许可证与漏洞状态,版本通过 BOM 统一。
- 三类库的边界会随组织与发布方式变化,引用方式与治理手段需要同步调整。