构建与依赖 / 系统课时
依赖作用域详解
依赖作用域详解
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。
<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,因此会把构建绑定到机器文件布局,不适合作为常规依赖管理方案。
<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 一样出现在运行依赖树中,这是正常现象。
mvn dependency:tree -Dincludes=org.apache.commons:commons-lang3,jakarta.servlet:jakarta.servlet-api,com.h2database:h2,org.junit.jupiter:junit-jupiter预期输出的关键行类似下面这样;树形前缀可能因依赖数量不同而变化,但每个构件末尾的 scope 应一致:
[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 则用于更特定的依赖管理场景。