一、起源

  • 代码复用从复制源码演进为按坐标引用之后,构件的来源出现三种边界:项目内部、公司内部、公司外部。
  • 三种边界的发布节奏、可信程度与故障影响范围不同,混用会带来两类问题:
    • 内部模块被当成外部依赖使用,改动后必须执行 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 入门:定位、环境与项目结构。

四、总结

  1. 一方库是同工程模块,由 reactor 直接解析,版本取 ${project.version},跨工程使用前需 install。
  2. 二方库是公司内部共享构件,走私服,联调使用 SNAPSHOT,上线使用不可变的 Release。
  3. 三方库是外部构件,引用前确认坐标、许可证与漏洞状态,版本通过 BOM 统一。
  4. 三类库的边界会随组织与发布方式变化,引用方式与治理手段需要同步调整。