告别打包烦恼：用Maven Assembly Plugin为Flink作业生成“胖JAR”的正确姿势

在Flink项目的实际开发中，依赖管理和打包环节往往是开发者最容易踩坑的地方。想象一下这样的场景：你精心编写的Flink作业在本地测试一切正常，但上传到集群后却频频抛出NoClassDefFoundError或MethodNotFound异常；或者打包后的JAR文件体积膨胀到几百MB，导致上传和部署效率低下。这些问题背后，往往隐藏着对Flink依赖管理和打包机制理解不足的根源。

本文将深入剖析使用Maven Assembly Plugin创建"uber-jar"（俗称"胖JAR"）的最佳实践，特别针对Flink项目中常见的依赖冲突、包体积过大等问题提供系统化解决方案。不同于基础教程中简单的配置示例，我们会从Flink运行时环境的特性出发，解析provided作用域的关键价值，并针对不同依赖类型（核心API、Connector、自定义库）给出差异化的POM配置策略。

1. Flink项目依赖管理的特殊性

1.1 为什么Flink需要特殊对待依赖

Flink运行时环境已经内置了大量核心依赖（如flink-core、flink-streaming-java等），这些依赖在集群所有节点上已经存在。如果将这些依赖再次打包进作业JAR，不仅会导致：

  • JAR文件体积膨胀：一个简单的WordCount程序打包后可能从几十KB变成上百MB
  • 依赖冲突风险：当打包版本与集群版本不一致时，可能引发难以调试的兼容性问题
<!-- 典型的问题配置：将Flink核心依赖打包进最终JAR -->
<dependency>
    <groupId>org.apache.flink</groupId>
    <artifactId>flink-streaming-java_2.12</artifactId>
    <version>1.15.2</version>
    <!-- 缺少scope声明 -->
</dependency>

1.2 provided作用域的核心价值

Maven的provided作用域明确告知：该依赖在编译和测试时需要，但不应打包进最终产物，因为运行环境会提供。这对Flink项目尤为重要：

作用域 编译期 测试期 运行时 打包包含 适用场景
compile ✓ ✓ ✓ ✓ 项目自有代码、非Flink第三方库
provided ✓ ✓ ✗ ✗ Flink核心API、Connector等集群已有依赖
runtime ✗ ✓ ✓ ✓ 需要动态加载的库 
<!-- 正确的配置方式 -->
<dependency>
    <groupId>org.apache.flink</groupId>
    <artifactId>flink-table-planner_2.12</artifactId>
    <version>1.15.2</version>
    <scope>provided</scope>  <!-- 关键配置 -->
</dependency>

注意：Flink 1.15+版本中，flink-table-planner需要特别注意作用域设置，因其在客户端和集群端的加载机制有特殊要求

2. Maven Assembly Plugin深度配置

2.1 基础胖JAR配置

最基本的Assembly配置只需指定主类和依赖包含策略：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.4.2</version>
    <configuration>
        <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
        <archive>
            <manifest>
                <mainClass>com.your.package.MainClass</mainClass>
            </manifest>
        </archive>
        <appendAssemblyId>false</appendAssemblyId>
    </configuration>
    <executions>
        <execution>
            <id>make-assembly</id>
            <phase>package</phase>
            <goals>
                <goal>single</goal>
            </goals>
        </execution>
    </executions>
</plugin>

执行mvn clean package后，会在target目录生成包含所有依赖的胖JAR。但这种简单配置存在明显问题：

  • 会包含本应设为provided的Flink核心依赖
  • 无法处理资源文件的冲突合并
  • 缺少对依赖排除的精细控制

2.2 进阶配置：依赖过滤与排除

通过dependencySets配置可以实现精细化的依赖控制：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-assembly-plugin</artifactId>
    <version>3.4.2</version>
    <configuration>
        <descriptors>
            <descriptor>src/assembly/custom.xml</descriptor>
        </descriptors>
    </configuration>
</plugin>

对应的src/assembly/custom.xml文件：

<assembly>
    <id>flink-optimized</id>
    <formats>
        <format>jar</format>
    </formats>
    <includeBaseDirectory>false</includeBaseDirectory>
    <dependencySets>
        <dependencySet>
            <outputDirectory>/</outputDirectory>
            <useProjectArtifact>true</useProjectArtifact>
            <unpack>true</unpack>
            <scope>runtime</scope>  <!-- 只包含runtime作用域依赖 -->
            <excludes>
                <exclude>org.apache.flink:*</exclude>  <!-- 显式排除Flink相关依赖 -->
                <exclude>org.slf4j:slf4j-log4j12</exclude> <!-- 避免日志冲突 -->
            </excludes>
        </dependencySet>
    </dependencySets>
    <fileSets>
        <fileSet>
            <directory>${project.build.outputDirectory}</directory>
            <outputDirectory>/</outputDirectory>
        </fileSet>
    </fileSets>
</assembly>

这种配置方式相比基础配置有以下优势：

  1. 精确控制包含哪些作用域的依赖
  2. 支持通过通配符排除特定组织的依赖
  3. 可以单独处理资源文件和类文件
  4. 支持多模块项目的特殊需求

3. 不同依赖类型的处理策略

3.1 Flink核心API依赖

所有Flink官方提供的核心组件都应设为provided：

<dependencies>
    <!-- 核心API -->
    <dependency>
        <groupId>org.apache.flink</groupId>
        <artifactId>flink-java</artifactId>
        <version>${flink.version}</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.apache.flink</groupId>
        <artifactId>flink-streaming-java_${scala.binary.version}</artifactId>
        <version>${flink.version}</version>
        <scope>provided</scope>
    </dependency>
    
    <!-- Table API -->
    <dependency>
        <groupId>org.apache.flink</groupId>
        <artifactId>flink-table-api-java-bridge_${scala.binary.version}</artifactId>
        <version>${flink.version}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

3.2 Connector依赖处理

Connector的处理需要区分情况：

  • Flink官方Connector：部分需要provided，部分需要打包
  • 第三方Connector：通常需要打包
<!-- Kafka Connector需要打包 -->
<dependency>
    <groupId>org.apache.flink</groupId>
    <artifactId>flink-connector-kafka_${scala.binary.version}</artifactId>
    <version>${flink.version}</version>
    <!-- 不设provided，因为集群不默认提供 -->
</dependency>

<!-- JDBC Connector通常需要打包 -->
<dependency>
    <groupId>org.apache.flink</groupId>
    <artifactId>flink-connector-jdbc_${scala.binary.version}</artifactId>
    <version>${flink.version}</version>
</dependency>

<!-- 第三方Elasticsearch Connector -->
<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>7.15.0</version>
</dependency>

经验法则：如果Connector不在Flink lib目录下（如$FLINK_HOME/lib/flink-connector-*），就需要打包进JAR

3.3 用户自定义依赖

项目特有的工具库、本地开发的扩展组件等必须打包：

<!-- 项目自有工具库 -->
<dependency>
    <groupId>com.your.company</groupId>
    <artifactId>data-process-utils</artifactId>
    <version>1.0.0</version>
    <!-- 默认compile作用域 -->
</dependency>

<!-- 第三方工具库 -->
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>31.1-jre</version>
</dependency>

对于可能引起冲突的依赖（如不同版本的Jackson），建议：

  1. 使用maven-shade-plugin的重定位(relocation)功能
  2. 或在Flink集群上统一依赖版本

4. 高级技巧与问题排查

4.1 依赖冲突排查工具

当遇到NoSuchMethodError或ClassNotFoundException时，可以使用：

# 查看JAR中实际包含的依赖
mvn dependency:tree

# 查看最终打包内容
jar tf target/your-app.jar | grep 'class/to/check'

# 使用Flink自带工具检查
./bin/flink run -m yarn-cluster -yd target/your-app.jar

4.2 资源文件冲突解决

当多个依赖包含相同资源文件（如META-INF/services）时，可以配置：

<dependencySet>
    <unpack>true</unpack>
    <unpackOptions>
        <excludes>
            <exclude>META-INF/*.SF</exclude>
            <exclude>META-INF/*.DSA</exclude>
            <exclude>META-INF/*.RSA</exclude>
        </excludes>
    </unpackOptions>
    <useStrictFiltering>true</useStrictFiltering>
</dependencySet>

4.3 多模块项目打包

对于多模块项目，推荐结构：

parent-project/
├── pom.xml
├── core-module/       # 公共代码
├── job-module/        # 作业入口
└── connectors/        # 自定义Connector

在作业模块中配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <configuration>
                <descriptorRefs>
                    <descriptorRef>jar-with-dependencies</descriptorRef>
                </descriptorRefs>
                <archive>
                    <manifest>
                        <mainClass>com.your.Main</mainClass>
                        <addClasspath>true</addClasspath>
                        <classpathPrefix>libs/</classpathPrefix>
                    </manifest>
                </archive>
            </configuration>
        </plugin>
    </plugins>
</build>

4.4 性能优化技巧

  1. 缩小JAR体积：

    • 使用maven-dependency-plugin排除不需要的传递依赖
    <exclusions>
    <exclusion>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-log4j12</artifactId>
    </exclusion>
</exclusions>

  2. 加速上传：

    • 先上传到HDFS，再通过hdfs路径提交
    hdfs dfs -put your-app.jar /flink/jars/
./bin/flink run -m yarn-cluster hdfs:///flink/jars/your-app.jar

  3. 类加载隔离：

    • 对于特殊依赖，考虑使用ChildFirstClassLoader
    env.enableChangelogStateBackend(true);
env.configure(new Configuration().set(
    PipelineOptions.CLASS_LOADER_RESOLVE_ORDER, 
    "child-first"
));

在实际项目中，我曾遇到一个典型问题：作业在IDE中运行正常，但提交到YARN集群后报NoClassDefFoundError。排查发现是因为一个间接依赖的Jackson版本与Flink内置版本冲突。最终通过maven-shade-plugin重命名了冲突包路径才解决：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <relocations>
                    <relocation>
                        <pattern>com.fasterxml.jackson</pattern>
                        <shadedPattern>shaded.jackson</shadedPattern>
                    </relocation>
                </relocations>
            </configuration>
        </execution>
    </executions>
</plugin>
Logo
亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

avatar 亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

avatar 亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

avatar 亚马逊云科技技术品牌专区