optional 让依赖对下游项目“可选”，即当前项目正常使用，但不传递给依赖本项目的其他模块；它仅影响 maven 依赖传递，不影响本项目编译与运行时 classpath。
dependency 的 optional 到底让谁“可选”？
optional 不是给当前项目“可选引入”，而是告诉 Maven：这个依赖不传递给下游项目。也就是说，你项目里用了它，但别人依赖你时，默认不会拉取它——哪怕你在自己项目里用得再深，对调用方来说它就像没存在过。
常见错误现象：
- A 项目声明了
optional=true的guava，B 项目依赖 A 后发现Splitter找不到类 - 本地编译运行正常，但打包成 jar 供其他模块使用时，运行时报
NoClassDefFoundError
使用场景很明确：只在当前模块内部做工具性支持，不希望暴露实现细节或强绑定版本。比如测试辅助类、桥接适配器、特定环境下的 fallback 实现。
关键点：
- optional 只影响 Maven 的依赖传递行为，不影响编译和运行时本项目的 classpath
- 它和 scope（如 test 或 provided）作用维度不同，可以共存，但语义不重叠
- 如果你希望下游也用到该依赖，就别设 optional；如果只是“我用，但不替别人决定”，才加
怎么写才不被 IDE 或构建搞懵？
Maven 解析 optional 是静态的，靠 pom.xml 的 XML 结构判断，IDE（如 IntelliJ）会据此调整自动导入和依赖提示——但有时缓存滞后，导致明明写了 optional=true，却还在“External Libraries”里看到它。
实操建议：
- 检查
optional必须是布尔值：<optional>true</optional>，不能写成<optional></optional>或<optional>TRUE</optional> - 修改后执行
mvn clean compile，再刷新 IDEA 的 Maven 工具窗口（不是单纯 reload project） - 验证是否生效：在另一个空项目中添加对你模块的依赖，然后运行
mvn dependency:tree -Dverbose，确认那个依赖没出现在树里
optional 和 scope=runtime/provided 有什么区别？
三者控制的是不同阶段的依赖可见性：
-
scope=provided：编译期需要，运行时不打包（如 Servlet API），容器已提供 -
scope=runtime：编译不需要，运行需要（如 JDBC 驱动） -
optional=true：本项目无论编译还是运行都照常用，但不传染给依赖你的项目
容易踩的坑：
- 把
optional当成scope=provided用，结果运行时报错——因为optional不影响本项目的 classpath - 在父 POM 的
dependencyManagement中设置optional，这是无效的：Maven 忽略该位置的optional字段
什么时候不该用 optional？
如果你的模块提供了公共 API，而这个 API 的方法签名里直接引用了某依赖的类型（比如返回值是 com.fasterxml.jackson.databind.JsonNode），那这个依赖就不能标 optional。下游项目即使不主动用 Jackson，只要调用你的方法，就必须有它，否则连字节码加载都失败。
另外注意兼容性影响：
- Java 9+ 的模块系统（JPMS）不识别
optional，它只看requires声明 - Gradle 从 7.4 开始默认禁用传递依赖，行为类似
optional，但逻辑更细粒度，不要以为迁移到 Gradle 就能照搬 Maven 的 optional 策略
真正难的是判断“这个依赖到底算不算实现细节”。很多团队加 optional 只是因为“暂时没想清楚”，结果后来发现接口泄漏了，又得改版本号、发 breaking change。
