Maven依赖核心配置解析：scope、type、optional与classifier深度指南

1. 这几个配置项不是“可选参数”，而是 Maven 依赖生命周期的控制开关

刚接触 Maven 的人常把scope、type、optional、classifier这些字段当成“填空题”——XML 里看着有空就填，填错也不报错，项目照样能编译通过。结果上线前突然发现：本地跑得好好的，测试环境却少了一个 JSON 解析器；或者打包出来的 JAR 里混进了开发用的调试工具类，被安全扫描标为高危；又或者升级某个基础组件后，整个模块编译失败，查半天才发现是exclusions漏写了一行，导致两个版本的 Guava 冲突。这些都不是偶然故障，而是对这几个字段语义理解偏差带来的必然结果。

它们根本不是“配置项”，而是 Maven 在构建生命周期中执行依赖解析、编译、测试、打包、运行这五个阶段时，用来做决策判断的元数据标签。比如scope=provided，Maven 不是在告诉你“这个依赖由容器提供”，而是在说：“请在 compile 阶段把它加进 classpath，但在 package 阶段彻底忽略它，别打进 WAR 包，也别参与传递依赖计算”。再比如optional=true，它不是“建议你不用”，而是向所有下游项目宣告：“本模块虽声明了此依赖，但不保证其存在性；若你用到本模块的某部分功能，且该功能恰好依赖此项，请你自行显式声明”。

我带过的某高校实验室项目组，曾因误将log4j-core设为runtimescope，导致单元测试阶段日志无法输出，排查三天才定位到是test阶段 classpath 里没加载进来；另一家做金融中间件的公司，在发布 SDK 时把slf4j-api标为optional=false（默认值），结果下游业务方引入后，因自身已用 Logback，被迫手动排除冲突，引发多起线上告警。这些教训背后，全是同一个问题：把语义化标签当成了装饰性属性。

真正理解它们，要从 Maven 的三座基石出发：坐标系统（GAV）、依赖图（Dependency Graph）和生命周期绑定（Lifecycle Binding）。scope控制依赖在生命周期各阶段的可见性边界；type定义构件的物理形态与用途（JAR vs TEST-JAR vs POM）；optional是模块间契约的显式声明；classifier则是对同一坐标下不同构建产物的逻辑分组。它们共同构成了一套轻量但严谨的“依赖契约语言”。接下来，我们逐层拆解每个字段的真实作用域、典型误用场景，以及如何用mvn dependency:tree等工具验证你的理解是否准确。

1.1 scope：不是“作用范围”，而是“生命周期阶段开关”

scope是 Maven 中最常被误解的字段。很多人记成“compile 代表编译期用，test 代表测试期用”，这没错，但远远不够。它的本质是控制该依赖在 Maven 生命周期各阶段是否参与 classpath 构建、是否参与传递依赖解析、是否被打包进最终产物这三个维度的组合策略。

Maven 官方定义了六种标准 scope，但实际高频使用的是四种：

关键点在于：runtime在编译期不可见，意味着你不能在.java文件里import它的类；但provided在编译期可见，却在运行期和打包期被完全剔除——这是很多初学者栽跟头的地方。例如，你写了import javax.servlet.http.HttpServletRequest;，Maven 编译能过，因为servlet-api是provided；但如果你把这个模块打成一个独立的 JAR 并试图java -jar运行，会立刻抛NoClassDefFoundError，因为servlet-api根本没被打进去，也没有被 JVM 加载。

更隐蔽的问题出在传递依赖上。假设 A 依赖 B，B 的pom.xml中声明了guava为runtimescope。那么当 A 引入 B 时，guava不会作为传递依赖出现在 A 的 classpath 中（除非 A 自己也声明了guava）。但如果你把 B 的guava改成compile，A 就会自动获得guava。这就是为什么升级第三方库时，有时会“莫名”多出一堆依赖——不是库变了，是你对scope的理解或配置变了。

实操中，我习惯用这条命令验证：

mvn dependency:tree -Dincludes=com.google.guava:guava -Dverbose

加上-Dverbose能看到每个依赖的 scope 来源（是直接声明还是传递引入），以及是否被exclusions排除。如果某依赖在compile阶段没出现，但你在代码里用了它的类，编译必然失败；如果它在runtime阶段缺失，但运行时报ClassNotFoundException，那就要检查scope是否设为了provided或test。

提示：systemscope 已被官方标记为 deprecated，它绕过仓库机制，直接引用本地路径 JAR，极易造成构建环境不一致。任何团队规范都应禁止使用。importscope 仅用于<dependencyManagement>中导入 BOM（Bill of Materials），它本身不引入任何依赖，只是统一版本号，这点后面会细讲。

1.2 type：构件类型决定 Maven 如何“对待”这个依赖

type字段常被忽略，因为它有默认值jar。但一旦你开始处理测试工具、源码包、文档包或自定义插件，type就成了关键开关。它的值不是随意写的字符串，而是对应 Maven 仓库中构件的物理文件后缀，直接决定了 Maven 下载哪个文件、用什么方式解析它。

最常见的非默认type有三个：

• test-jar：表示这是一个测试类打包的 JAR。当你想在另一个模块中复用当前模块的测试工具类（比如通用的 Mock 数据生成器）时，需这样声明：

  <dependency> <groupId>com.example</groupId> <artifactId>my-module</artifactId> <version>1.0.0</version> <type>test-jar</type> <scope>test</scope> </dependency>

  注意：type=test-jar必须配合scope=test，否则 Maven 会报错。因为test-jar本身只包含测试代码，没有业务逻辑，放在compile阶段毫无意义。

• pom：表示该依赖是一个纯 POM 文件，不包含任何 class。典型场景是引入 BOM（如spring-boot-dependencies），它只定义了一组依赖的版本号，不提供任何代码。此时type=pom是强制的，否则 Maven 会尝试下载xxx.jar并失败。

• maven-plugin：当你开发或使用 Maven 插件时，插件的坐标type就是maven-plugin。Maven 会根据此类型加载对应的 Mojo 类，而不是把它当作普通库加入 classpath。

type的深层影响在于Artifact Resolver 的行为。Maven 的依赖解析器（DefaultArtifactResolver）在下载依赖时，会拼接 URL：{repository-url}/{groupId}/{artifactId}/{version}/{artifactId}-{version}-{classifier}.{type}。如果type=jar，它找xxx-1.0.0.jar；如果type=test-jar，它找xxx-1.0.0-tests.jar。因此，type错了，下载的就是错误的文件，后续所有操作都建立在错误基础上。

我曾在一个跨平台图像处理项目中踩过坑：某算法模块提供了native-lib的 Windows/Linux/macOS 版本，分别打包为xxx-1.0.0-win64.dll、xxx-1.0.0-linux-x64.so。团队最初用classifier区分平台，但type仍为jar，导致 Maven 总是去下载不存在的xxx-1.0.0-win64.jar。后来改为type=dll（Windows）和type=so（Linux），并配合maven-nativedependencies-plugin，问题才解决。这说明type不仅是标识，更是构建流程的触发器。

注意：自定义type需要在settings.xml或项目pom.xml的<build><extensions>中声明对应的maven-extension，否则 Maven 不认识该类型。生产环境慎用自定义 type，优先考虑用classifier+ 标准type组合。

2. optional 和 classifier：一个管“要不要传下去”，一个管“同坐标下选哪个”

如果说scope和type是控制依赖的“时空权限”，那么optional和classifier就是处理依赖的“契约责任”与“物理变体”。它们解决的是同一坐标（GAV）下更精细的语义问题：当一个模块提供了多种能力，而使用者可能只用其中一部分时，如何避免强耦合？当同一套源码需要产出不同用途的二进制包时，如何让使用者精准获取？

2.1 optional：模块间松耦合的契约声明

optional=true是 Maven 实现“按需依赖”的核心机制。它的设计初衷非常明确：当一个模块（A）提供了多种可选功能，而每种功能依赖不同的第三方库时，A 不应强迫所有使用者都引入这些库，而应将选择权交给使用者。

举个真实案例：某日志框架模块log-framework-core同时支持输出到 Kafka 和 Elasticsearch。它的pom.xml这样写：

<dependencies> <!-- Kafka 支持是可选的 --> <dependency> <groupId>org.apache.kafka</groupId> <artifactId>kafka-clients</artifactId> <version>3.4.0</version> <optional>true</optional> </dependency> <!-- ES 支持也是可选的 --> <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>7.17.0</version> <optional>true</optional> </dependency> </dependencies>

此时，任何项目引入log-framework-core，默认情况下kafka-clients和es-client都不会作为传递依赖出现。只有当使用者明确需要 Kafka 功能时，才需自己添加：

<dependency> <groupId>org.apache.kafka</groupId> <artifactId>kafka-clients</artifactId> <version>3.4.0</version> </dependency>

这带来了三个关键好处：

1. 减小依赖树规模：避免无用依赖污染 classpath，降低冲突概率；
2. 提升构建速度：Maven 不用下载和解析那些永远不会用到的 JAR；
3. 明确责任归属：谁用谁负责版本兼容性。比如使用者用的是 Kafka 3.5.0，而log-framework-core声明的是 3.4.0，只要 API 兼容，就不会出问题。

但optional常被误用为“临时注释掉依赖”的手段。有人把一个必用依赖设为optional=true，以为能“先编译过去”，结果运行时报NoClassDefFoundError。这是严重错误——optional不是开关，而是契约。它意味着“此依赖对本模块的核心功能非必需”，如果删掉它模块就跑不起来，那就绝不能标optional。

验证optional是否生效，看mvn dependency:tree输出即可。如果某依赖行末尾标有(optional)，且它不在你的直接依赖列表中，说明它确实被正确隔离了。

2.2 classifier：同一坐标下的“物理分身”

classifier是 Maven 解决“一源多构”问题的方案。当同一个groupId:artifactId:version坐标需要产出多个不同用途、不同平台、不同内容的二进制包时，classifier就是它们的区分符。

它的值可以是任意字符串，但社区有约定俗成的命名：

• sources：源码包（.jar→.sources.jar）
• javadoc：API 文档包（.jar→.javadoc.jar）
• tests：测试类包（.jar→.tests.jar）
• win64,linux-x64,osx-arm64：原生库平台标识
• shaded：经过 Maven Shade Plugin 重打包的“胖 JAR”

关键规则：classifier不改变依赖的逻辑含义，只指定下载哪个物理文件。一个classifier依赖必须和主 artifact 共享相同的groupId、artifactId、version，否则 Maven 会报错。

例如，你想在 IDE 中查看 Spring Boot 的源码，只需在pom.xml中添加：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>3.2.0</version> <classifier>sources</classifier> </dependency>

Maven 就会去仓库下载spring-boot-starter-web-3.2.0-sources.jar，而不是spring-boot-starter-web-3.2.0.jar。IDE 识别到sourcesclassifier 后，自动关联源码。

更实用的场景是处理原生库。假设你开发一个音视频处理 SDK，需要为不同操作系统提供 FFmpeg 的 native 库。你可以这样组织：

my-sdk-1.0.0.jar # 主逻辑，纯 Java my-sdk-1.0.0-linux-x64.jar # Linux x64 native lib my-sdk-1.0.0-win64.jar # Windows x64 native lib my-sdk-1.0.0-osx-arm64.jar # macOS ARM64 native lib

使用者根据目标平台，在pom.xml中声明对应classifier：

<!-- Linux 环境 --> <dependency> <groupId>com.example</groupId> <artifactId>my-sdk</artifactId> <version>1.0.0</version> <classifier>linux-x64</classifier> </dependency>

这里有个重要细节：classifier依赖默认scope=compile，且参与传递依赖。这意味着，如果你的模块 A 依赖my-sdk:linux-x64，而模块 B 依赖 A，那么 B 的 classpath 中也会出现my-sdk-1.0.0-linux-x64.jar。这通常不是你想要的——B 可能运行在 Windows 上。因此，这类依赖必须配合scope=runtime或scope=provided，并在运行时通过代码动态加载，而非直接放在 classpath。

提示：classifier不能单独存在。Maven 要求必须同时指定groupId、artifactId、version和type（通常是jar）。漏掉任何一个，都会导致构建失败。IDE（如 IntelliJ）对classifier的支持很好，能自动下载并关联 sources/javadoc，但对自定义 classifier（如win64）的支持较弱，需手动配置。

3. 传递依赖：Maven 的“自动继承”机制及其双刃剑效应

传递依赖（Transitive Dependency）是 Maven 最强大也最危险的特性。它让开发者无需手动声明所有底层依赖，Maven 会自动从直接依赖的 POM 文件中读取其<dependencies>，递归构建出完整的依赖图。没有它，一个 Spring Boot 项目可能需要手动声明上百个依赖。但正因如此，它也成为版本冲突、JAR 包爆炸、类加载异常的根源。

3.1 传递依赖的解析规则：最近原则与第一声明原则

Maven 解析传递依赖时，遵循两条铁律：

1. 最近原则（Nearest Definition Wins）：当依赖图中出现同一个 GAV 的多个版本时，Maven 选择路径最短的那个。路径长度指从你的项目到该依赖的边数。

   • 你的项目 → A → B → guava-32.0.0-jre
   • 你的项目 → C → guava-31.1-jre
     由于第二条路径更短（2步 vs 3步），Maven 会选择guava-31.1-jre。

2. 第一声明原则（First Declaration Wins）：当路径长度相同时，Maven 选择在pom.xml中最先声明的那个依赖。

   • 你的项目pom.xml中：

     <dependency> <groupId>A</groupId> <artifactId>a</artifactId> <version>1.0</version> </dependency> <dependency> <groupId>B</groupId> <artifactId>b</artifactId> <version>1.0</version> </dependency>

     如果 A 和 B 都传递引入guava-31.1-jre，则 A 的声明优先，guava-31.1-jre被采纳。

这两条规则看似简单，但组合起来会产生复杂结果。例如，某次升级spring-boot-starter-web后，项目启动失败，报NoSuchMethodError。用mvn dependency:tree -Dverbose查看，发现spring-core被解析为6.0.12，而spring-beans却是6.0.10——这是典型的“路径分裂”：spring-web依赖spring-core:6.0.12，而spring-context（被其他模块引入）依赖spring-beans:6.0.10，两者路径长度相同，但spring-context在pom.xml中声明得更早，于是spring-beans被锁定为6.0.10，与spring-core:6.0.12不兼容。

3.2 用 dependencyManagement 统一版本：BOM 的正确打开方式

解决传递依赖版本混乱的终极方案，是dependencyManagement+ BOM（Bill of Materials）。BOM 是一个特殊的 POM 文件，它不包含代码，只定义一组依赖的groupId:artifactId:version映射，并将scope设为import。

Spring Boot 官方提供的spring-boot-dependencies就是典型 BOM。你在pom.xml中这样用：

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-dependencies</artifactId> <version>3.2.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

<scope>import</scope>的含义是：将此 BOM 中定义的所有依赖版本，作为当前项目的“版本仲裁依据”，但不实际引入任何依赖。之后，无论你在<dependencies>中声明spring-web、spring-jdbc还是spring-aop，只要它们的groupId在 BOM 中有定义，Maven 就会自动采用 BOM 中指定的版本，无需写<version>。

这相当于给整个依赖图装上了“交通管制系统”：dependencyManagement是红绿灯，import是信号灯控制器，而具体<dependency>声明是车辆。车辆（依赖）必须遵守红绿灯（BOM 规则），但红绿灯本身不产生车辆。

实践中，我建议所有中大型项目都建立自己的 BOM 模块。例如，某公司内部的company-bom模块，统一管理所有中间件（Redis、Kafka、ES）、基础库（Guava、Apache Commons）、监控组件（Micrometer、Prometheus）的版本。各业务线只需引入company-bom，就能确保全公司技术栈版本一致，避免“张三用 Guava 31，李四用 Guava 32”导致的集成灾难。

注意：dependencyManagement中的依赖，即使写了<version>，也不会被自动引入 classpath。它只是版本声明池。必须在<dependencies>中显式声明，才会真正下载和使用。这是新手常犯的错误——以为写了dependencyManagement就万事大吉，结果编译报package not found。

4. exclusions：精准外科手术式排除，而非粗暴的“一刀切”

当传递依赖带来冲突、冗余或安全风险时，exclusions是 Maven 提供的精准排障工具。它允许你在声明一个依赖时，明确指出“不要带进来以下这些传递依赖”。这不是删除，而是“在依赖解析过程中，将指定的 GAV 从传递路径中剪断”。

4.1 exclusions 的语法与作用域

exclusions必须嵌套在<dependency>内部，格式如下：

<dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.15.2</version> <exclusions> <exclusion> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> </exclusion> <exclusion> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> </exclusion> </exclusions> </dependency>

关键点：

• <exclusion>中只需写groupId和artifactId，不能写version。因为你要排除的是“所有版本”，而不是某个特定版本。
• exclusions的作用域是当前这一行<dependency>声明。它只影响这个依赖引入的传递依赖，不影响其他依赖。
• 被排除的依赖，不会出现在mvn dependency:tree的输出中，就像它从未被声明过一样。

4.2 何时必须用 exclusions？三个高危场景

场景一：版本冲突导致的 NoSuchMethodError这是最常见的情况。例如，你引入了net.sf.ehcache:ehcache:2.10.9，它传递引入slf4j-api:1.7.25；而你的项目又直接依赖logback-classic:1.4.11，它传递引入slf4j-api:2.0.7。Maven 根据最近原则，可能选了1.7.25，但logback的某些方法在1.7.25中不存在，运行时报错。此时，应在ehcache声明中排除slf4j-api：

<dependency> <groupId>net.sf.ehcache</groupId> <artifactId>ehcache</artifactId> <version>2.10.9</version> <exclusions> <exclusion> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> </exclusion> </exclusions> </dependency>

然后由你统一声明slf4j-api:2.0.7，确保一致性。

场景二：引入了不该有的测试依赖某些开源库（尤其是老项目）会把junit、mockito等测试依赖声明为compilescope，导致它们被传递到你的生产环境中。这不仅增大包体积，还可能因测试类被反射调用而引发安全扫描告警。例如：

<dependency> <groupId>com.some-old-lib</groupId> <artifactId>legacy-util</artifactId> <version>1.2.0</version> <exclusions> <exclusion> <groupId>junit</groupId> <artifactId>junit</artifactId> </exclusion> <exclusion> <groupId>org.mockito</groupId> <artifactId>mockito-core</artifactId> </exclusion> </exclusions> </dependency>

场景三：规避已知安全漏洞当mvn dependency:tree发现某个传递依赖存在 CVE 漏洞（如commons-collections:3.1的反序列化漏洞），而上游库尚未修复时，exclusions是最快的临时缓解手段。排除后，你需要手动引入一个已修复的替代版本（如commons-collections4:4.4），并做必要的适配。

提示：exclusions是“局部手术”，不是全局解决方案。过度使用会导致依赖图难以维护。优先考虑用dependencyManagement统一版本，其次才是exclusions。每次添加exclusions，务必在代码注释中写明原因和 CVE 编号，方便后续审计。

5. 实战排障：一次完整的依赖冲突诊断与修复过程

理论终需落地。下面以我亲身经历的一个真实排障案例，完整演示如何运用上述所有概念，从现象定位到根因，再到安全修复。

5.1 问题现象：启动即崩溃，堆栈指向一个不存在的方法

某微服务模块升级 Spring Boot 从 2.7.x 到 3.2.0 后，本地mvn spring-boot:run启动成功，但部署到测试环境后，应用启动几秒就崩溃，日志关键片段：

Caused by: java.lang.NoSuchMethodError: 'void org.springframework.core.io.support.SpringFactoriesLoader.loadFactories( java.lang.Class, java.util.function.Supplier)' at org.springframework.boot.SpringApplication.getSpringFactoriesInstances(SpringApplication.java:441)

SpringApplication.java:441调用的loadFactories方法签名是(Class, Supplier)，但实际加载的spring-core版本中，该方法只有(Class, ClassLoader)一个重载。说明spring-core版本不对。

5.2 第一步：用 dependency:tree 锁定嫌疑对象

在项目根目录执行：

mvn dependency:tree -Dincludes=org.springframework:spring-core -Dverbose > tree.log

输出精简后：

[INFO] com.example:my-service:jar:1.0.0-SNAPSHOT [INFO] \- org.springframework.boot:spring-boot-starter-web:jar:3.2.0:compile [INFO] \- org.springframework.boot:spring-boot-starter:jar:3.2.0:compile [INFO] \- org.springframework.boot:spring-boot:jar:3.2.0:compile [INFO] \- org.springframework:spring-core:jar:6.0.12:compile [INFO] com.example:my-service:jar:1.0.0-SNAPSHOT [INFO] \- com.example:common-utils:jar:2.1.0:compile [INFO] \- org.springframework:spring-core:jar:5.3.31:compile (version managed from 5.3.31)

清晰看到：spring-boot-starter-web正确引入了spring-core:6.0.12，但common-utils:2.1.0这个内部模块，却传递引入了spring-core:5.3.31。由于common-utils在pom.xml中声明得更早，且路径长度相同（都是 1），Maven 选择了5.3.31，导致6.0.12的新方法找不到。

5.3 第二步：分析 common-utils 的 pom.xml，定位问题根源

打开common-utils模块的pom.xml，发现它依赖了一个老版本的spring-cloud-starter-openfeign:3.1.5，而3.1.5的pom.xml中，spring-core的scope是compile，且未声明version，于是继承了父 POM 的5.3.31。

5.4 第三步：制定修复方案——三选一

方案一（推荐）：升级common-utils中的spring-cloud-starter-openfeign到兼容 Spring Boot 3.2.0 的版本（如4.0.4）。但4.0.4要求 JDK 17+，而common-utils还在用 JDK 8，升级成本高。

方案二：在common-utils的pom.xml中，用dependencyManagement强制spring-core为6.0.12。但common-utils是一个被广泛引用的公共模块，强行升级spring-core可能破坏其他使用者的兼容性。

方案三（本次采用）：在my-service的pom.xml中，对common-utils做exclusions，排除其传递的spring-core，然后由my-service自己声明spring-core:6.0.12（通过 Spring Boot BOM 保证）。

修改my-service/pom.xml：

<dependency> <groupId>com.example</groupId> <artifactId>common-utils</artifactId> <version>2.1.0</version> <exclusions> <exclusion> <groupId>org.springframework</groupId> <artifactId>spring-core</artifactId> </exclusion> </exclusions> </dependency>

由于spring-boot-starter-web:3.2.0已经通过 BOM 管理了spring-core:6.0.12，无需额外声明。

5.5 第四步：验证修复效果

再次执行mvn dependency:tree -Dincludes=org.springframework:spring-core，输出变为：

[INFO] com.example:my-service:jar:1.0.0-SNAPSHOT [INFO] \- org.springframework.boot:spring-boot-starter-web:jar:3.2.0:compile [INFO] \- org.springframework.boot:spring-boot-starter:jar:3.2.0:compile [INFO] \- org.springframework.boot:spring-boot:jar:3.2.0:compile [INFO] \- org.springframework:spring-core:jar:6.0.12:compile

common-utils的spring-core消失了，只剩6.0.12。重新部署，应用启动成功。

这次排障全程，scope（compile导致冲突）、exclusions（精准排除）、dependencyManagement（BOM 保证版本）三者协同，缺一不可。它印证了一个事实：Maven 的依赖管理不是黑盒，而是一套可观察、可干预、可预测的工程系统。掌握这些字段，就是掌握了构建稳定性的主动权。

6. 配置黄金法则：一份可直接抄作业的 check list

基于十年一线经验，我总结出一套 Maven 依赖配置的“防坑 checklist”。它不是教条，而是我在无数项目中用血泪换来的直觉。每次新建模块、升级依赖、引入新库前，我都会快速过一遍：

6.1 scope 使用自查表（每次声明依赖必问）

• [ ]这个依赖在编译期是否必须？
  如果代码里import了它的类，scope必须是compile（默认）或provided（容器提供）。若设为runtime或test，编译直接失败。

• [ ]这个依赖在运行期是否必须？
  如果是 JDBC 驱动、消息客户端等，scope应为runtime；如果是 Servlet API、Java EE API，scope应为provided；如果是业务逻辑库，scope应为compile。

• [ ]这个依赖是否会被打到最终产物（JAR/WAR）里？
  compile和runtime会；provided和test不会。确认打包体积和运行环境是否匹配。

• [ ]这个依赖是否应该传递给下游项目？
  compile和runtime会传递；provided、test、system不会。避免下游项目意外获得你不希望他们依赖的库。

6.2 optional 与 classifier 使用场景卡（非必要不启用）

• [ ]optional：仅当该依赖对应的功能是“可插拔”的，且模块核心逻辑不依赖它时，才设optional=true。例如：数据库驱动（H2 用于测试，MySQL 用于生产）、消息中间件（Kafka vs RabbitMQ）、监控埋点（Prometheus vs Micrometer）。如果删掉它模块就挂了，就不是optional。

• [ ]classifier：仅当同一 GAV 坐标下，存在多个物理文件，且它们用途截然不同（源码 vs 文档 vs 原生库）时，才用classifier。避免用classifier做功能分支（如pro、lite），这违反了单一职责原则，应拆分为不同artifactId。

6.3 传递依赖与 exclusions 决策树（遇到冲突时按此流程）

1. 第一步：mvn dependency:tree -Dverbose
   确认冲突依赖的完整路径、版本、scope 和来源（直接声明 or 传递引入）。

2. 第二步：检查dependencyManagement
   是否已有 BOM 管理该依赖？如果有，优先升级 BOM 版本，而非手动exclusions。

3. 第三步：评估exclusions影响
   被排除的依赖，是否被当前模块的其他部分间接使用？排除后是否会导致NoClassDefFoundError？如有，需在exclusions后手动添加该依赖的正确版本。

4. 第四步：记录与同步
   在pom.xml的exclusions块上方，用 XML 注释写明：
   `<!-- EXCLUDES: xxx due