java maven-assembly-plugin：如何使用 appendAssemblyId

maven-assembly-plugin: How to use appendAssemblyId

提问by lanoxx

I have a multi-module Maven project and in one module I want to create two artifacts during the build:

我有一个多模块 Maven 项目，在一个模块中，我想在构建过程中创建两个工件：

• The main artifact which is a jar library that some of the other modules will depend on.
• An executable jar file that executes some helper functions. No other modules depends on this and its only intended for the user to run it manually in certain situations.

• 主要工件是一些其他模块将依赖的 jar 库。
• 执行一些辅助函数的可执行 jar 文件。没有其他模块依赖于此，它仅用于用户在某些情况下手动运行它。

Here is the code that I use to configure the maven-assembly-pluginplugin:

这是我用来配置maven-assembly-plugin插件的代码：

<plugin>
    <artifactId>
        maven-assembly-plugin
    </artifactId>
    <version>2.4</version>
    <executions>
      <execution>
        <id>dist-assembly</id>
        <phase>package</phase>
        <goals>
          <goal>single</goal>
        </goals>

        <configuration>
          <finalName>bso</finalName>
          <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>
          </descriptorRefs>
          <finalName>helper-${project.version}</finalName>
          <appendAssemblyId>false</appendAssemblyId>
          <archive>
            <manifest>
              <mainClass>HelperMain<mainClass>
            </manifest>
          </archive>
        </configuration>

      </execution>
    </executions>
  </plugin>

I am setting appendAssemblyIdto falsebecause otherwise -jar-with-dependencieswill be appended to the final name and I do not see the need for it. Omitting it gives a cleaner and easier to use file name.

我设置appendAssemblyId为false因为否则-jar-with-dependencies将附加到最终名称，我认为不需要它。省略它可以使文件名更清晰、更易于使用。

When I run mvn integration-testthen I receive the following warnings:

当我运行时，mvn integration-test我收到以下警告：

[WARNING] Configuration options: 'appendAssemblyId' is set to false, and 'classifier' is missing. Instead of attaching the assembly file: [...]/target/helper-5.0.0-SNAPSHOT.jar, it will become the file for main project artifact.

NOTE: If multiple descriptors or descriptor-formats are provided for this project, the value of this file will be non-deterministic!

[WARNING] Replacing pre-existing project main-artifact file: [...]/target/my.module-5.0.0-SNAPSHOT.jar with assembly file: [...]/target/helper-5.0.0-SNAPSHOT.jar

[警告] 配置选项：'appendAssemblyId' 设置为 false，并且缺少 'classifier'。而不是附加程序集文件：[...]/target/helper-5.0.0-SNAPSHOT.jar，它将成为主项目工件的文件。

注意：如果为此项目提供了多个描述符或描述符格式，则此文件的值将是不确定的！

[警告] 将预先存在的项目主工件文件：[...]/target/my.module-5.0.0-SNAPSHOT.jar 替换为程序集文件：[...]/target/helper-5.0.0-快照文件

There are two things which irritate me:

有两件事让我很恼火：

1. Despite the fact that the warning claims it will replace my.module-5.0.0-SNAPSHOT.jar with helper-5.0.0-SNAPSHOT.jar it does not actually do so and when the build has finished both files still have different sizes.

2. Why does the warning about replacing the artifact appear at all?

3. It seems that classifieris deprecated why does the warning ask me to use it?

1. 尽管警告声称它将用 helper-5.0.0-SNAPSHOT.jar 替换 my.module-5.0.0-SNAPSHOT.jar 它实际上并没有这样做，并且当构建完成时，两个文件仍然具有不同的大小。

2. 为什么会出现更换神器的警告？

3. 似乎classifier已弃用为什么警告要求我使用它？

回答by Tunaki

That is because you are mis-interpreting the warnings.

那是因为您误解了警告。

---

---

Let's recap. A Maven project that is not of type pomwill always produce, by default, what is called a main artifact. For a JAR, this artifact is the result of packaging the compiled sources into a JAR; for a WAR, it is the result of building the web-application.

让我们回顾一下。pom默认情况下，非类型的 Maven 项目将始终生成所谓的主工件。对于 JAR，这个工件是将编译好的源代码打包成 JAR 的结果；对于 WAR，它是构建 Web 应用程序的结果。

What is important to remember is that this artifact is attachedto the project: this terminology is useful when the project is installed (with mvn install), deployed (with mvn deploy) or released (with the maven-release-plugin). Attachedmeans that this artifact will be installed / deployed / released when the project is. Not all files generated during a Maven build (basically, everything under the targetfolder) are; only the files that were attached. As such, you can very well create a lot of files under targetbut have a single installed artifact.

重要的是要记住这个工件是附加到项目的：这个术语在项目安装（使用mvn install）、部署（使用mvn deploy）或发布（使用maven-release-plugin）时很有用。附加意味着这个工件将在项目时安装/部署/发布。并非所有在 Maven 构建期间生成的文件（基本上，target文件夹下的所有内容）都是；只有附加的文件。因此，您可以很好地创建许多文件，target但只有一个已安装的工件。

Alongside this main artifact, you may want your build to produce other artifacts to install or deploy. That's the concept of additional or secondary attached artifacts. The main examples are the Javadoc or the sources: typically when a project is released, its Javadoc and its sources also are. And that is where the notion classifierkicks in.

除了这个主要工件，您可能希望您的构建生成其他工件以进行安装或部署。这就是附加或次要附加工件的概念。主要的例子是 Javadoc 或源代码：通常当一个项目发布时，它的 Javadoc 和它的源代码也是。这就是这个概念的classifier用武之地。

In a Maven repository, each and every file has to follow the same naming convention: artifactId-version(-classifier).type. Every secondary artifact will have the same GAV (group id, artifact id, version) as the main artifact so if you want to put inside a Maven repo 1 main artifact and 1 attached artifact (like it would be the case for a main JAR along with its JAR Javadoc and JAR sources), you need some way to distinguish them. Which is what the classifieris for: distinguish secondary artifacts from the main artifact.

在 Maven 存储库中，每个文件都必须遵循相同的命名约定：artifactId-version(-classifier).type. 每个次要工件都将具有与主工件相同的 GAV（组 ID、工件 ID、版本），因此如果您想将 1 个主工件和 1 个附加工件放入 Maven 存储库中（就像主 JAR 的情况一样）与它的 JAR Javadoc 和 JAR 源），您需要一些方法来区分它们。这是什么classifier：区分次要工件和主要工件。

---

---

Let's go back to your example now. Your Maven project, which is of jarpackaging, will produce by default a main JAR artifact called my.module-5.0.0-SNAPSHOT.jar; still by default, this main JAR is attached to the project (and ready to be installed / deployed). Now you're configuring the maven-assembly-pluginto create a new JAR artifact (called helper-5.0.0-SNAPSHOT.jarbut it really doesn't matter). The Assembly Plugin, by default, attaches to the project the artifact it produces. So you end up with 2 attached artifacts

现在让我们回到你的例子。您的 Maven 项目是jar打包的，默认情况下会生成一个名为my.module-5.0.0-SNAPSHOT.jar;的主要 JAR 工件；默认情况下，这个主 JAR 附加到项目（并准备安装/部署）。现在您正在配置maven-assembly-plugin以创建一个新的 JAR 工件（已调用，helper-5.0.0-SNAPSHOT.jar但实际上并不重要）。默认情况下，Assembly Plugin将它生成的工件附加到项目中。所以你最终得到了 2 个附加的工件

1. having the same artifact id of my.module; the fact that the file on disk inside the targetfolder is named helperfor one is irrelevant, only the GAV coordinates matter
2. having the same version of 5.0.0-SNAPSHOT
3. having the same packaging of JAR

1. 具有相同的工件 ID my.module；文件target夹内磁盘上的文件以helper一个命名这一事实无关紧要，只有 GAV 坐标很重要
2. 具有相同的版本 5.0.0-SNAPSHOT
3. 具有相同的 JAR 包装

and no classifier to distinguish them. This is what raises the warning: you end up attaching to the project a secondary artifact that effectively replaces the main one, simply because it has the same coordinates. So the result is:

并且没有分类器来区分它们。这就是发出警告的原因：您最终将一个次要工件附加到项目中，该工件有效地替换了主要工件，仅仅因为它具有相同的坐标。所以结果是：

1. Both files having different names on disk inside target, but that is irrelevant because
2. Both share the same coordinates so only 1 will survive.

1. 这两个文件在内部磁盘上的名称不同target，但这无关紧要，因为
2. 两者共享相同的坐标，因此只有 1 会存活。

It is the one produced by the Assembly Plugin that will win the conflict, and replace the attached main artifact.

它是由 Assembly Plugin 产生的将赢得冲突，并替换附加的主要工件。

If you want to convince yourself of all that, run mvn clean installon the project and check your local repo. You will notice that only the jar-with-dependenciesartifact will be installed. The other one (the main artifact) went poof.

如果您想说服自己，请运行mvn clean install该项目并检查您的本地存储库。您会注意到只会jar-with-dependencies安装工件。另一个（主要神器）失败了。

You can also configure a <distributionManagement>:

您还可以配置一个<distributionManagement>：

<distributionManagement>
    <repository>
        <id>local-repo-test</id>
        <url>file://...</url>
    </repository>
</distributionManagement>

and invoke mvn clean deploy. You can then check that the only deployed artifact will be the jar-with-dependencies.

并调用mvn clean deploy. 然后，您可以检查唯一部署的工件是jar-with-dependencies.

---

---

Final note: Yes, the classifierparameter of the Assembly Plugin is deprecated, because you should just use the assembly id as classifier.

最后说明：是的，classifier不推荐使用 Assembly Plugin的参数，因为您应该只使用程序集 ID 作为分类器。