AI实践哪家强?来 AICon, 解锁技术前沿,探寻产业新机! 了解详情
写点什么

Maven 实战(九)——打包的技巧

  • 2011-06-20
  • 本文字数:4667 字

    阅读完需:约 15 分钟

“打包“这个词听起来比较土,比较正式的说法应该是”构建项目软件包“,具体说就是将项目中的各种文件,比如源代码、编译生成的字节码、配置文件、文档,按照规范的格式生成归档,最常见的当然就是 JAR 包和 WAR 包了,复杂点的例子是 Maven 官方下载页面的分发包,它有自定义的格式,方便用户直接解压后就在命令行使用。作为一款”打包工具“,Maven 自然有义务帮助用户创建各种各样的包,规范的 JAR 包和 WAR 包自然不再话下,略微复杂的自定义打包格式也必须支持,本文就介绍一些常用的打包案例以及相关的实现方式,除了前面提到的一些包以外,你还能看到如何生成源码包、Javadoc 包、以及从命令行可直接运行的 CLI 包。

Packaging 的含义

任何一个 Maven 项目都需要定义 POM 元素 packaging(如果不写则默认值为 jar)。顾名思义,该元素决定了项目的打包方式。实际的情形中,如果你不声明该元素,Maven 会帮你生成一个 JAR 包;如果你定义该元素的值为 war,那你会得到一个 WAR 包;如果定义其值为 POM(比如是一个父模块),那什么包都不会生成。除此之外,Maven 默认还支持一些其他的流行打包格式,例如 ejb3 和 ear。你不需要了解具体的打包细节,你所需要做的就是告诉 Maven,”我是个什么类型的项目“,这就是约定优于配置的力量。

为了更好的理解 Maven 的默认打包方式,我们不妨来看看简单的声明背后发生了什么,对一个 jar 项目执行 mvn package 操作,会看到如下的输出:

复制代码
[INFO] --- maven-jar-plugin:2.3.1:jar (default-jar) @ git-demo ---
[INFO] Building jar: /home/juven/git_juven/git-demo/target/git-demo-1.2-SNAPSHOT.jar

相比之下,对一个 war 项目执行 mvn package 操作,输出是这样的:

复制代码
[INFO] --- maven-war-plugin:2.1:war (default-war) @ webapp-demo ---
[INFO] Packaging webapp
[INFO] Assembling webapp [webapp-demo] in [/home/juven/git_juven/webapp-demo/target/webapp-demo-1.0-SNAPSHOT]
[INFO] Processing war project
[INFO] Copying webapp resources [/home/juven/git_juven/webapp-demo/src/main/webapp]
[INFO] Webapp assembled in [90 msecs]
[INFO] Building war: /home/juven/git_juven/webapp-demo/target/webapp-demo-1.0-SNAPSHOT.war

对应于同样的 package 生命周期阶段,Maven 为 jar 项目调用了 maven-jar-plugin,为 war 项目调用了 maven-war-plugin,换言之,packaging 直接影响 Maven 的构建生命周期。了解这一点非常重要,特别是当你需要自定义打包行为的时候,你就必须知道去配置哪个插件。一个常见的例子就是在打包 war 项目的时候排除某些 web 资源文件,这时就应该配置 maven-war-plugin 如下:

复制代码
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>2.1.1</version>
<configuration>
<webResources>
<resource>
<directory>src/main/webapp</directory>
<excludes>
<exclude>**/*.jpg</exclude>
</excludes>
</resource>
</webResources>
</configuration>
</plugin>

源码包和 Javadoc 包

本专栏的《坐标规划》一文中曾解释过,一个 Maven 项目只生成一个主构件,当需要生成其他附属构件的时候,就需要用上 classifier。源码包和 Javadoc 包就是附属构件的极佳例子。它们有着广泛的用途,尤其是源码包,当你使用一个第三方依赖的时候,有时候会希望在 IDE 中直接进入该依赖的源码查看其实现的细节,如果该依赖将源码包发布到了 Maven 仓库,那么像 Eclipse 就能通过 m2eclipse 插件解析下载源码包并关联到你的项目中,十分方便。由于生成源码包是极其常见的需求,因此 Maven 官方提供了一个插件来帮助用户完成这个任务:

复制代码
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>2.1.2</version>
<executions>
<execution>
<id>attach-sources</id>
<phase>verify</phase>
<goals>
<goal>jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>

类似的,生成 Javadoc 包只需要配置插件如下:

复制代码
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.7</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>

为了帮助所有 Maven 用户更方便的使用 Maven 中央库中海量的资源,中央仓库的维护者强制要求开源项目提交构件的时候同时提供源码包和 Javadoc 包。这是个很好的实践,读者也可以尝试在自己所处的公司内部实行,以促进不同项目之间的交流。

可执行 CLI 包

除了前面提到了常规 JAR 包、WAR 包,源码包和 Javadoc 包,另一种常被用到的包是在命令行可直接运行的 CLI(Command Line)包。默认 Maven 生成的 JAR 包只包含了编译生成的.class 文件和项目资源文件,而要得到一个可以直接在命令行通过 java 命令运行的 JAR 文件,还要满足两个条件:

  • JAR 包中的 /META-INF/MANIFEST.MF 元数据文件必须包含 Main-Class 信息。
  • 项目所有的依赖都必须在 Classpath 中。

Maven 有好几个插件能帮助用户完成上述任务,不过用起来最方便的还是 maven-shade-plugin ,它可以让用户配置 Main-Class 的值,然后在打包的时候将值填入 /META-INF/MANIFEST.MF 文件。关于项目的依赖,它很聪明地将依赖 JAR 文件全部解压后,再将得到的.class 文件连同当前项目的.class 文件一起合并到最终的 CLI 包中,这样,在执行 CLI JAR 文件的时候,所有需要的类就都在 Classpath 中了。下面是一个配置样例:

复制代码
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>1.4</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>com.juvenxu.mavenbook.HelloWorldCli</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>

上述例子中的,我的 Main-Class 是 com.juvenxu.mavenbook.HelloWorldCli,构建完成后,对应于一个常规的 hello-world-1.0.jar 文件,我还得到了一个 hello-world-1.0-cli.jar 文件。细心的读者可能已经注意到了,这里用的是 cli 这个 classifier。最后,我可以通过java -jar hello-world-1.0-cli.jar命令运行程序。

自定义格式包

实际的软件项目常常会有更复杂的打包需求,例如我们可能需要为客户提供一份产品的分发包,这个包不仅仅包含项目的字节码文件,还得包含依赖以及相关脚本文件以方便客户解压后就能运行,此外分发包还得包含一些必要的文档。这时项目的源码目录结构大致是这样的:

复制代码
pom.xml
src/main/java/
src/main/resources/
src/test/java/
src/test/resources/
src/main/scripts/
src/main/assembly/
README.txt

除了基本的 pom.xml 和一般 Maven 目录之外,这里还有一个 src/main/scripts/ 目录,该目录会包含一些脚本文件如 run.sh 和 run.bat,src/main/assembly/ 会包含一个 assembly.xml,这是打包的描述文件,稍后介绍,最后的 README.txt 是份简单的文档。

我们希望最终生成一个 zip 格式的分发包,它包含如下的一个结构:

复制代码
bin/
lib/
README.txt

其中 bin/ 目录包含了可执行脚本 run.sh 和 run.bat,lib/ 目录包含了项目 JAR 包和所有依赖 JAR,README.txt 就是前面提到的文档。

描述清楚需求后,我们就要搬出 Maven 最强大的打包插件: maven-assembly-plugin 。它支持各种打包文件格式,包括 zip、tar.gz、tar.bz2 等等,通过一个打包描述文件(该例中是 src/main/assembly.xml),它能够帮助用户选择具体打包哪些文件集合、依赖、模块、和甚至本地仓库文件,每个项的具体打包路径用户也能自由控制。如下就是对应上述需求的打包描述文件 src/main/assembly.xml:

复制代码
<assembly>
<id>bin</id>
<formats>
<format>zip</format>
</formats>
<dependencySets>
<dependencySet>
<useProjectArtifact>true</useProjectArtifact>
<outputDirectory>lib</outputDirectory>
</dependencySet>
</dependencySets>
<fileSets>
<fileSet>
<outputDirectory>/</outputDirectory>
<includes>
<include>README.txt</include>
</includes>
</fileSet>
<fileSet>
<directory>src/main/scripts</directory>
<outputDirectory>/bin</outputDirectory>
<includes>
<include>run.sh</include>
<include>run.bat</include>
</includes>
</fileSet>
</fileSets>
</assembly>
  • 首先这个 assembly.xml 文件的 id 对应了其最终生成文件的 classifier。
  • 其次 formats 定义打包生成的文件格式,这里是 zip。因此结合 id 我们会得到一个名为 hello-world-1.0-bin.zip 的文件。(假设 artifactId 为 hello-world,version 为 1.0)
  • dependencySets 用来定义选择依赖并定义最终打包到什么目录,这里我们声明的一个 depenencySet 默认包含所有所有依赖,而 useProjectArtifact 表示将项目本身生成的构件也包含在内,最终打包至输出包内的 lib 路径下(由 outputDirectory 指定)。
  • fileSets 允许用户通过文件或目录的粒度来控制打包。这里的第一个 fileSet 打包 README.txt 文件至包的根目录下,第二个 fileSet 则将 src/main/scripts 下的 run.sh 和 run.bat 文件打包至输出包的 bin 目录下。

打包描述文件所支持的配置远超出本文所能覆盖的范围,为了避免读者被过多细节扰乱思维,这里不再展开,读者若有需要可以去参考这份文档

最后,我们需要配置 maven-assembly-plugin 使用打包描述文件,并绑定生命周期阶段使其自动执行打包操作:

复制代码
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.2.1</version>
<configuration>
<descriptors>
<descriptor>src/main/assembly/assembly.xml</descriptor>
</descriptors>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>

运行mvn clean package之后,我们就能在 target/ 目录下得到名为 hello-world-1.0-bin.zip 的分发包了。

小结

打包是项目构建最重要的组成部分之一,本文介绍了主流 Maven 打包技巧,包括默认打包方式的原理、如何制作源码包和 Javadoc 包、如何制作命令行可运行的 CLI 包、以及进一步的,如何基于个性化需求自定义打包格式。这其中涉及了很多的 Maven 插件,当然最重要,也是最为复杂和强大的打包插件就是 maven-assembly-plugin。事实上 Maven 本身的分发包就是通过 maven-assembly-plugin 制作的,感兴趣的读者可以直接查看源码一窥究竟。

关注 IT 趋势,承载前沿、深入、有温度的内容。感兴趣的读者可以搜索 ID:laocuixiabian,或者扫描下方二维码加关注。

2011-06-20 08:38180308

评论 1 条评论

发布
用户头像
maven souece plugin,maven javadoc plugin,maven shade plugin,maven assembly plugin
2021-12-15 21:48
回复
没有更多了
发现更多内容

通过 JDBC 向 YashanDB 批量插入空间数据的标准写法

数据库砖家

数据库

根据数据表快速生成原型图的工具

执于业务

迁徙:微信鸿蒙版的长征

脑极体

AI

Uniapp开发鸿蒙应用时如何运行和调试项目

幽蓝计划

可观测性方案怎么选?SelectDB vs Elasticsearch vs ClickHouse

SelectDB

elastic 可观测性 实时数仓 Clickhouse 数据库 大数据

RAG检索实践:多路检索(PostgreSQL环境准备)

程序员架构进阶

全文检索 5月日更 大模型 PgSQL rag

从China P&E 2025 看闪迪创作者系列如何提升生产力

极客天地

最新开源 TEN VAD 与 Turn Detection 让 Voice Agent 对话更拟人 | 社区来稿

声网

《算法导论(第4版)》阅读笔记:p76-p81

codists

算法

如何在 YashanDB 备机上安全进行备份与恢复操作

数据库砖家

数据库

使用 Druid 查询 GIS 空间数据时报 read time out 的排查与规避方法

数据库砖家

数据库

华为云超节点创新算力基础设施,推动千行万业AI应用开发落地

轶天下事

一键多环境构建——用 Hvigor 玩转 HarmonyOS Next

鸿蒙魔法师

鸿蒙 HarmonyOS HarmonyOS NEXT Harmony5

YashanDB 使用 imp 导入时报 YAS-08023 的原因与处理办法

数据库砖家

数据库

Python 查询 GBK 编码的 YashanDB CLOB 字段数据被截断的原因与修复

数据库砖家

数据库

想要给软件加点功能啥的,源码是必须要有的

程序员郭顺发

打造了一个未来感十足的图书管理 App 个人页面

繁依Fanyi

全平台开源即时通讯IM聊天框架MobileIMSDK的服务端开发指南,支持鸿蒙NEXT

JackJiang

网络编程 即时通讯 IM

YashanDB 收集统计信息时报 YAS-00507 错误的处理方法

数据库砖家

数据库

我这是“小作坊”,没那么多时间为爱奉献!

程序员郭顺发

YashanDB 使用 listagg 报 YAS-02511 的原因及解决方案

数据库砖家

数据库

AARRR模型是什么,包括哪些阶段?一文弄懂PM必备的思维模型!

职场工具箱

人工智能 产品 AI 产品经理 AIGC

DevEco重大更新快来体验吧

龙儿筝

RAG创始人关于RAG Agent的10个思考(上)

Bruce Talk

AI RAG知识库

使用 JDBC 批量插入 YashanDB GIS 空间数据的示例

数据库砖家

数据库

TEN 开源超轻量 VAD 和全双工对话轮次检测模型;Stability AI 发布全新端侧音频生成模型,无版权风险丨日报

声网

RAG创始人关于RAG Agent的10个思考(下)

Bruce Talk

AI RAG知识库

Hive 初始化 YashanDB 报错 YAS-04209 的原因与处理办法

数据库砖家

数据库

《算法导论(第4版)》阅读笔记:p82-p82

codists

算法

新一代SRE:AI、可观测与未来丨暨2025第三届中国SRE大会,邀您共赴科技盛宴!

雅菲奥朗

为什么在中国开源软件赚不到钱?

雅菲奥朗

#开源

Maven实战(九)——打包的技巧_Java_许晓斌_InfoQ精选文章