构建与依赖 / 系统课时

依赖作用域详解

依赖作用域详解

Maven 的 scope 决定一个依赖在哪些类路径出现、是否参与运行,以及是否向下游项目传递。把六种作用域放到同一套编译与运行边界里看,就能避免测试库进入生产包、容器 API 被重复打包,或运行时驱动在启动后才缺失。

学习目标

  • 能区分 compile、provided、runtime、test、system 和 import 的类路径范围。
  • 能根据“编译需要、运行需要、是否由外部环境提供”选择合适的 scope。
  • 能用依赖树和有效 POM 验证最终生效的作用域与版本。

用类路径矩阵区分六种 scope

compile 是默认值;provided 表示编译时需要但运行环境负责提供;runtime 表示主代码编译不需要、运行时才需要;test 只服务测试。system 类似 provided,但 JAR 由本机路径提供;import 只用于 dependencyManagement 中导入 BOM。

scope 主代码编译 主程序运行 测试编译/运行 向下游传递 典型用途
compile 是 是 是 是 业务代码直接调用的库
provided 是 否 是 否 外部 Servlet 容器提供的 API
runtime 否 是 是 是,按运行时依赖处理 JDBC 驱动、运行时实现
test 否 否 是 否 JUnit、测试工具
system 是 否 是 否 无法从仓库获取且必须使用本地 JAR 的遗留场景
import 不适用 不适用 不适用 不作为普通依赖传递 在 dependencyManagement 导入 BOM

一个可直接套用的判断法是:主源码出现该库的类型或方法调用,通常从 compile 考虑;部署环境明确承诺提供该 API,考虑 provided;只有运行阶段通过 SPI、JDBC 等机制加载实现,考虑 runtime。

在 POM 中按职责放置依赖

下面的片段同时展示四种常用 scope,并用 JUnit BOM 演示 import。BOM 本身不会进入类路径,它只把一组受管版本合并进当前项目的 dependencyManagement。

xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.junit</groupId>
      <artifactId>junit-bom</artifactId>
      <version>5.10.2</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.14.0</version>
  </dependency>

  <dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
  </dependency>

  <dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <version>2.2.224</version>
    <scope>runtime</scope>
  </dependency>

  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>

junit-jupiter 没写版本仍能解析,是因为 junit-bom 提供了版本管理。import 只有放在 dependencyManagement 且依赖类型为 pom 时才有这个语义,不能把它当成普通运行依赖。

system 的配置语法如下;它要求 systemPath 指向实际存在的本地 JAR,因此会把构建绑定到机器文件布局,不适合作为常规依赖管理方案。

xml
<dependency>
  <groupId>com.vendor</groupId>
  <artifactId>legacy-sdk</artifactId>
  <version>1.0.0</version>
  <scope>system</scope>
  <systemPath>${project.basedir}/lib/legacy-sdk.jar</systemPath>
</dependency>

这段是片段示例,只有项目中确实存在 lib/legacy-sdk.jar 时才能解析成功。能发布到 Maven 仓库的内部库应优先发布到仓库,而不是用 system 固定本地路径。

用命令核对最终 scope

把上面的依赖片段放入一个正常的 Maven 项目后,可用一次依赖树检查四个普通依赖的最终范围。import 的 BOM 不会像普通 JAR 一样出现在运行依赖树中,这是正常现象。

bash
mvn dependency:tree -Dincludes=org.apache.commons:commons-lang3,jakarta.servlet:jakarta.servlet-api,com.h2database:h2,org.junit.jupiter:junit-jupiter

预期输出的关键行类似下面这样;树形前缀可能因依赖数量不同而变化,但每个构件末尾的 scope 应一致:

text
[INFO] +- org.apache.commons:commons-lang3:jar:3.14.0:compile
[INFO] +- jakarta.servlet:jakarta.servlet-api:jar:6.0.0:provided
[INFO] +- com.h2database:h2:jar:2.2.224:runtime
[INFO] \- org.junit.jupiter:junit-jupiter:jar:5.10.2:test
[INFO] BUILD SUCCESS

若要确认 BOM 导入后的版本管理结果,可再执行 mvn help:effective-pom -Doutput=effective-pom.xml,然后在生成的 effective-pom.xml 中搜索 junit-jupiter,应能看到由 BOM 管理后的 5.10.2 版本。

按打包边界选择 scope

最常见的错误不是 Maven 解析失败,而是依赖在错误的阶段出现。以部署到外部 Servlet 容器的 WAR 为例,jakarta.servlet-api 通常应为 provided;若写成 compile,它可能被打进应用并与容器提供的 API 重复。

错误选择 可能结果 更合适的选择
JUnit 写成 compile 测试库进入生产依赖并向下游暴露 test
容器已提供 Servlet API 仍写 compile 打包重复 API,增加类加载冲突风险 provided
JDBC 驱动写成 provided,运行环境又没提供 启动后找不到驱动实现 runtime
BOM 写在普通 dependencies 并期待“自动带入 JAR” 不会得到期望的运行库 在 dependencyManagement 用 type=pom + scope=import
业务库写成 system CI 或同事机器因路径不同而失败 发布到私有或公共 Maven 仓库

选择 scope 时只问三个问题:主代码编译时是否直接需要、应用运行时是否自己携带、依赖是否应暴露给下游。把这三个边界回答清楚,绝大多数项目只会频繁使用 compile、provided、runtime 和 test,system 与 import 则用于更特定的依赖管理场景。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

依赖作用域详解

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通