Maven 中的可选依赖详解

1. 概述

本文将深入讲解 Maven 的 <optional> 标签机制，以及如何利用它来精简项目构建产物（如 JAR、WAR 或 EAR）的依赖体积和作用范围。

如果你对 Maven 基础还不熟悉，可以先参考我们之前发布的 Maven 全面指南。

2. 什么是 `<optional>`？

在开发一个会被其他项目引用的 Maven 模块时，经常会遇到一种情况：某些依赖仅服务于该模块的部分功能，并非所有使用者都需要。

举个例子，你的项目支持多种数据导出格式 —— CSV 和 Excel。其中 Excel 导出依赖 poi-ooxml，但 CSV 不需要。如果把这个依赖直接声明为常规依赖：

✅ 所有引入你项目的模块，都会自动继承这个 poi-ooxml 依赖（即“传递性依赖”）
❌ 即使对方只用 CSV 功能，也会把庞大的 POI 库拉进来，造成 jar 包膨胀，甚至可能引发 版本冲突

理想做法是拆成多个子模块（比如 export-csv 和 export-excel），但这在实际项目中往往成本太高，维护复杂。

这时，<optional> 就派上用场了。

✅ 核心作用：标记为 <optional>true</optional> 的依赖，不会被传递到下游项目。
⚠️ 但它在当前项目内部依然可用，不影响自身功能。

换句话说：
👉 对当前项目：该依赖“存在”
👉 对引用该项目的外部项目：该依赖“不存在”，必须手动显式引入

这样既保留了功能完整性，又避免了不必要的依赖污染。

3. 如何使用 `<optional>`

只需在 pom.xml 的 <dependency> 中添加 <optional>true</optional> 即可。

示例场景

假设我们有一个通用工具库 project-with-optionals，它支持邮件发送（基于 JavaMail），但邮件功能不是核心功能。

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example.lib</groupId>
    <artifactId>project-with-optionals</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <dependencies>
        <!-- 核心依赖，正常引入 -->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.12.0</version>
        </dependency>

        <!-- 邮件功能依赖，设为可选 -->
        <dependency>
            <groupId>com.sun.mail</groupId>
            <artifactId>javax.mail</artifactId>
            <version>1.6.2</version>
            <optional>true</optional>
        </dependency>
    </dependencies>
</project>

在这个项目中，javax.mail 依然可以正常使用，代码里 import 和调用都没问题。

下游项目行为验证

现在另一个项目 main-project 依赖了 project-with-optionals：

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example.app</groupId>
    <artifactId>main-project</artifactId>
    <version>1.0.0</version>

    <dependencies>
        <dependency>
            <groupId>com.example.lib</groupId>
            <artifactId>project-with-optionals</artifactId>
            <version>0.0.1-SNAPSHOT</version>
        </dependency>
    </dependencies>
</project>

此时，在 main-project 中：

❌ 无法直接使用 javax.mail 的类（如 Session, MimeMessage），编译报错
✅ 但 commons-lang3 正常可用（它是常规依赖）

如何启用可选功能？

如果 main-project 确实需要发邮件功能，只需自己显式添加那个可选依赖：

<dependencies>
    <dependency>
        <groupId>com.example.lib</groupId>
        <artifactId>project-with-optionals</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>

    <!-- 显式引入原本可选的依赖 -->
    <dependency>
        <groupId>com.sun.mail</groupId>
        <artifactId>javax.mail</artifactId>
        <version>1.6.2</version>
    </dependency>
</dependencies>

此时功能恢复正常，且依赖关系清晰可控。

4. 总结

<optional> 是一个简单粗暴但非常实用的 Maven 特性，适用于以下场景：

✅ 某些功能属于“可插拔”组件（如多种存储后端、序列化方式）
✅ 希望减少传递性依赖带来的 jar 包膨胀
✅ 避免因传递依赖引发的 版本冲突踩坑

⚠️ 注意事项：

可选依赖对当前项目无影响，仍可正常使用
下游项目若需使用对应功能，必须自行声明依赖
不要滥用，仅用于非核心、条件性使用的依赖

本文示例代码已托管至 GitHub：https://github.com/baeldung-tutorials/maven-optional-deps-demo

Persistence

REST

Security