Maven 打包、制作源码包、制作Javadoc包、制作命令行可运行的 CLI 包、自定义打包

打包概念

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

---

Packaging 的含义

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

---

打包 war 项目的时候排除某些 web 资源文件：

<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 文件，还要满足两个条件：
1、JAR 包中的 /META-INF/MANIFEST.MF 元数据文件必须包含 Main-Class 信息。
2、项目所有的依赖都必须在 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 制作的。