【翻译】Maven 的长枪配置 pom.xml

2017-08-15

– 导读

最近一直在使用 pom.xml ，但是不知道这里面的一些配置如何使用，便有了从官方翻译一下这个文件的冲动，也便有了这篇文章的雏形，就当做是记录一下最近的状态，提升一下自己。

这篇翻译的源文来至这里：http://maven.apache.org/pom.html ，下面便开始翻译之路，有不明白之处或者翻译错误之处，请提出指正，共同进步，多谢！~

POM 目录引用

POM 4.0.0 XSD 文件和描述符参考文档

介绍说明

POM 是什么？

POM定位于“ 项目对象模型 ”，在Maven的项目中，它使用XML语言来描述，并被用pom.xml来命名来实现。在Maven的人面前，说一个项目是在哲学的意义上讲，超出了单纯的文件集合包含代码。项目包含配置文件，以及所涉及的开发人员和他们所扮演的角色，缺陷跟踪系统，组织和许可证，项目所在地的URL，项目的依赖，以及所有其他的小片段，这些代码都可以发挥代码的作用。这是一个一站式商店的所有项目有关的东西。实际上，在Maven的世界里，一个项目不包含任何代码，仅仅一个 pom.xml 。

快速浏览

下面是直接在POM项目元素下的元素列表。注意 modelVersion 包含4.0.0。这是目前唯一支持Maven 2 & 3 POM版。

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
 
  <!-- 基础信息 -->
  <groupId>...</groupId>
  <artifactId>...</artifactId>
  <version>...</version>
  <packaging>...</packaging>
  <dependencies>...</dependencies>
  <parent>...</parent>
  <dependencyManagement>...</dependencyManagement>
  <modules>...</modules>
  <properties>...</properties>
 
  <!-- 构建配置 -->
  <build>...</build>
  <reporting>...</reporting>
 
  <!-- 更多项目信息 -->
  <name>...</name>
  <description>...</description>
  <url>...</url>
  <inceptionYear>...</inceptionYear>
  <licenses>...</licenses>
  <organization>...</organization>
  <developers>...</developers>
  <contributors>...</contributors>
 
  <!-- 环境设置 -->
  <issueManagement>...</issueManagement>
  <ciManagement>...</ciManagement>
  <mailingLists>...</mailingLists>
  <scm>...</scm>
  <prerequisites>...</prerequisites>
  <repositories>...</repositories>
  <pluginRepositories>...</pluginRepositories>
  <distributionManagement>...</distributionManagement>
  <profiles>...</profiles>
</project>

基础信息

POM包含关于项目的所有必要信息，以及构建过程中要使用的插件的配置。实际上，它是“谁”、“什么”和“在哪里”的声明性表示，而构建生命周期是“何时”和“如何”。这并不是说POM不能影响整个生命周期的流动。例如，通过配置 maven-antrun-plugin 可以嵌入的Ant任务里面的POM。然而，这终究是一种基础声明。如果作为一个 build.xml 告诉Ant当它运行（程序）时正做什么，POM的配置（声明）。如果一些外部力量导致生命周期跳过Ant插件执行，它不会停止执行他们的魔术的插件。这不像一个build.xml文件，任务几乎都是队列执行。

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
 
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>my-project</artifactId>
  <version>1.0</version>
</project>

Maven 协调坐标

上面定义的POM是Maven 2和3允许的最低版本。 groupId : artifactId : version 版本所需的所有领域（显然，如果他们继承了父类更多的明确定义，groupId 和 version 不需要明确定义）。三个字段很像一个地址和一个时间戳。这标志着在仓库里的一个特定的地方，像一个Maven项目的坐标系统。

groupId：项目组织的唯一标识。例如, org.apache.maven 存在于 Maven 下面的核心分组编号。分组的 ID 不需要符号标记, 例如, junit项目。注意, 该项目包含打点 GroupID 表示没有对应的封装结构。然而，这是一个很好的实践。在一个操作系统，存储在仓库内，该 group 的行为很像java的封装结构。这些点由OS特定的目录分隔符（如UNIX中的 “/” ）替换，它从基础存储库变成相对目录结构。在例子中, 这个 org.codehaus.mojo 存在于目录 $M2_REPO/org/codehaus/mojo.
artifactId：项目名称的唯一标识. 即使 groupId 很重要, 组内的人很少会在讨论中提到的GroupID（他们往往都是ID，如 Codehaus Mojo项目组织标识：org.codehaus.mojo）。它随着 groupId 一起创建一个密钥，使得这个月项目与其他项目有区分(至少，应该是这样:) )。在仓库中，与 groupId 一起, artifactId 充分定义了生存区域. 在上面描述的项目下面，my-project 放在 $M2_REPO/org/codehaus/mojo/my-project。
version：这是命名最伤脑筋的部分。groupId:artifactId 表示一个项目却无法具体描绘我们所谈论的项目。我们希望 junit:junit 今天版本 (version 4), 或者四年前的版本 (version 2)? 总之：代码的变化，这些变化应该被记录版本，而且应该保持线上可用版本。它也在工件的存储库中使用，以分离彼此的版本。my-project version 1.0 文件保存在目录结构中 $M2_REPO/org/codehaus/mojo/my-project/1.0。

我们希望他们，在软件生命周期内，上面三个元素在一个项目中定义了一个特殊版本让Maven知道我们在处理。
packaging：现在我们有了地址结构 groupId : artifactId : version, 还有一个标准标签可以给我们一个真正完整的地址。这是项目的 artifact 类型。在我们的 POM 例子中，org.codehaus.mojo: my-project: 1.0 上面定义的将被打包为 jar 包。我们可以将打包 war 包用来声明不用的包：

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <packaging>war</packaging>
  ...
</project>

当 packaging 没有被声明时, Maven 假定 artifact 为默认: jar。有效的类型是丛角色提示（更多相关的角色说明请参照阅读）org.apache.maven.lifecycle.mapping.LifecycleMapping。当前的核心值是: pom, jar, maven-plugin, ejb, war, ear, rar, par。这些定义了针对特定包结构的每个相应的构建生命周期阶段执行的缺省目标列表。

有时候你会看到 Maven 协调打印项目 groupId : artifactId : packaging : version。

classifier：有时您可以在坐标上找到第五个元素，这就是classifier。我们将参观分类器后，但现在只要知道这些项目显示为 groupId : artifactId : packaging : classifier : version.

POM 关系

Maven的一个强大的方面是其项目的关系处理；包括依赖（和过渡依赖），继承和聚合（多模块项目）。依赖管理有一个长期的传统，它是一个复杂的混乱，除了最微不足道的项目。“jarmageddon”迅速随之而来的依存树变得大而复杂。接下来，一个系统的依赖版本不等同于开发的版本，或者由错误版本给出，或者类似命名JAR之间的冲突版本。Maven的解决了两个问题通过一个共同的本地存储库的链接项目的正确、版本和所有。

依赖性

POM的基石是它的依赖列表。大多数项目取决于他人建立和运行正确，如果所有的专家为你做的是为你管理这个列表，你已经获得了很多。Maven下载为你编译和其他目标需要的依赖关系链接。作为额外的奖励，Maven带来依赖的依赖（依靠），让你的列表仅集中在依赖你的项目需要。

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.0</version>
      <type>jar</type>
      <scope>test</scope>
      <optional>true</optional>
    </dependency>
    ...
  </dependencies>
  ...
</project>

依赖版本需求说明

1.0: “Soft” requirement on 1.0 (just a recommendation, if it matches all other ranges for the dependency)
[1.0]: “Hard” requirement on 1.0
(,1.0]: x <= 1.0
[1.2,1.3]: 1.2 <= x <= 1.3
[1.0,2.0): 1.0 <= x < 2.0
[1.5,): x >= 1.5
(,1.0],[1.2,): x <= 1.0 or x >= 1.2; multiple sets are comma-separated
(,1.1),(1.1,): this excludes 1.1 (for example if it is known not to work in combination with this library)

不包含

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <dependencies>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-embedder</artifactId>
      <version>2.0</version>
      <exclusions>
        <exclusion>
          <groupId>org.apache.maven</groupId>
          <artifactId>maven-core</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
    ...
  </dependencies>
  ...
</project>

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <dependencies>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-embedder</artifactId>
      <version>3.1.0</version>
      <exclusions>
        <exclusion>
          <groupId>*</groupId>
          <artifactId>*</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
    ...
  </dependencies>
  ...
</project>

继承

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
 
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>my-parent</artifactId>
  <version>2.0</version>
  <packaging>pom</packaging>
</project>

groupId
version
description
url
inceptionYear
organization
licenses
developers
contributors
mailingLists
scm
issueManagement
ciManagement
properties
dependencyManagement
dependencies
repositories
pluginRepositories
build
- plugin executions with matching ids
- plugin configuration
- etc.
reporting
profiles

不继承的元素:

artifactId
name
prerequisites

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
 
  <parent>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>my-parent</artifactId>
    <version>2.0</version>
    <relativePath>../my-parent</relativePath>
  </parent>
 
  <artifactId>my-project</artifactId>
</project>

超级POM

<project>
  <modelVersion>4.0.0</modelVersion>
 
  <repositories>
    <repository>
      <id>central</id>
      <name>Central Repository</name>
      <url>http://repo.maven.apache.org/maven2</url>
      <layout>default</layout>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>
 
  <pluginRepositories>
    <pluginRepository>
      <id>central</id>
      <name>Central Repository</name>
      <url>http://repo.maven.apache.org/maven2</url>
      <layout>default</layout>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <releases>
        <updatePolicy>never</updatePolicy>
      </releases>
    </pluginRepository>
  </pluginRepositories>
 
  <build>
    <directory>${project.basedir}/target</directory>
    <outputDirectory>${project.build.directory}/classes</outputDirectory>
    <finalName>${project.artifactId}-${project.version}</finalName>
    <testOutputDirectory>${project.build.directory}/test-classes</testOutputDirectory>
    <sourceDirectory>${project.basedir}/src/main/java</sourceDirectory>
    <scriptSourceDirectory>src/main/scripts</scriptSourceDirectory>
    <testSourceDirectory>${project.basedir}/src/test/java</testSourceDirectory>
    <resources>
      <resource>
        <directory>${project.basedir}/src/main/resources</directory>
      </resource>
    </resources>
    <testResources>
      <testResource>
        <directory>${project.basedir}/src/test/resources</directory>
      </testResource>
    </testResources>
    <pluginManagement>
      <!-- NOTE: These plugins will be removed from future versions of the super POM -->
      <!-- They are kept for the moment as they are very unlikely to conflict with lifecycle mappings (MNG-4453) -->
      <plugins>
        <plugin>
          <artifactId>maven-antrun-plugin</artifactId>
          <version>1.3</version>
        </plugin>
        <plugin>
          <artifactId>maven-assembly-plugin</artifactId>
          <version>2.2-beta-5</version>
        </plugin>
        <plugin>
          <artifactId>maven-dependency-plugin</artifactId>
          <version>2.1</version>
        </plugin>
        <plugin>
          <artifactId>maven-release-plugin</artifactId>
          <version>2.0</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
 
  <reporting>
    <outputDirectory>${project.build.directory}/site</outputDirectory>
  </reporting>
 
  <profiles>
    <!-- NOTE: The release profile will be removed from future versions of the super POM -->
    <profile>
      <id>release-profile</id>
 
      <activation>
        <property>
          <name>performRelease</name>
          <value>true</value>
        </property>
      </activation>
 
      <build>
        <plugins>
          <plugin>
            <inherited>true</inherited>
            <artifactId>maven-source-plugin</artifactId>
            <executions>
              <execution>
                <id>attach-sources</id>
                <goals>
                  <goal>jar</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
          <plugin>
            <inherited>true</inherited>
            <artifactId>maven-javadoc-plugin</artifactId>
            <executions>
              <execution>
                <id>attach-javadocs</id>
                <goals>
                  <goal>jar</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
          <plugin>
            <inherited>true</inherited>
            <artifactId>maven-deploy-plugin</artifactId>
            <configuration>
              <updateReleaseInfo>true</updateReleaseInfo>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>
 
</project>

依赖管理

聚合（或者多模块）

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
 
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>my-parent</artifactId>
  <version>2.0</version>
  <packaging>pom</packaging>
 
  <modules>
    <module>my-project</module>
    <module>another-project</module>
  </modules>
</project>

特性

<project>
  ...
  <properties>
    <maven.compiler.source>1.7<maven.compiler.source>
    <maven.compiler.target>1.7<maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
  </properties>
  ...
</project>

构建设置

构建

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <!-- "Project Build" contains more elements than just the BaseBuild set -->
  <build>...</build>
 
  <profiles>
    <profile>
      <!-- "Profile Build" contains a subset of "Project Build"s elements -->
      <build>...</build>
    </profile>
  </profiles>
</project>

基础构建设置

<build>
  <defaultGoal>install</defaultGoal>
  <directory>${basedir}/target</directory>
  <finalName>${artifactId}-${version}</finalName>
  <filters>
    <filter>filters/filter1.properties</filter>
  </filters>
  ...
</build>

资源

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <build>
    ...
    <resources>
      <resource>
        <targetPath>META-INF/plexus</targetPath>
        <filtering>false</filtering>
        <directory>${basedir}/src/main/plexus</directory>
        <includes>
          <include>configuration.xml</include>
        </includes>
        <excludes>
          <exclude>**/*.properties</exclude>
        </excludes>
      </resource>
    </resources>
    <testResources>
      ...
    </testResources>
    ...
  </build>
</project>

resources: is a list of resource elements that each describe what and where to include files associated with this project.
targetPath: Specifies the directory structure to place the set of resources from a build. Target path defaults to the base directory. A commonly specified target path for resources that will be packaged in a JAR is META-INF.
filtering: is true or false, denoting if filtering is to be enabled for this resource. Note, that filter *.properties files do not have to be defined for filtering to occur - resources can also use properties that are by default defined in the POM (such as ${project.version}), passed into the command line using the “-D” flag (for example, “-Dname=value”) or are explicitly defined by the properties element. Filter files were covered above.
directory: This element’s value defines where the resources are to be found. The default directory for a build is ${basedir}/src/main/resources.
includes: A set of files patterns which specify the files to include as resources under that specified directory, using * as a wildcard.
excludes: The same structure as includes, but specifies which files to ignore. In conflicts between include and exclude, exclude wins.
testResources: The testResources element block contains testResource elements. Their definitions are similar to resource elements, but are naturally used during test phases. The one difference is that the default (Super POM defined) test resource directory for a project is ${basedir}/src/test/resources. Test resources are not deployed.

插件

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <build>
    ...
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>2.6</version>
        <extensions>false</extensions>
        <inherited>true</inherited>
        <configuration>
          <classifier>test</classifier>
        </configuration>
        <dependencies>...</dependencies>
        <executions>...</executions>
      </plugin>
    </plugins>
  </build>
</project>

结束语

The Maven POM is big. However, its size is also a testament to its versatility. The ability to abstract all of the aspects of a project into a single artifact is powerful, to say the least. Gone are the days of dozens of disparate build scripts and scattered documentation concerning each individual project. Along with Maven’s other stars that make up the Maven galaxy - a well defined build lifecycle, easy to write and maintain plugins, centralized repositories, system-wide and user-based configurations, as well as the increasing number of tools to make developers’ jobs easier to maintain complex projects - the POM is the large, but bright, center.

Maven POM很大。然而，它的大小也证明了它的多功能性。至少可以说，将项目的所有方面抽象成单个工件的能力是强大的。几十个不同的构建脚本和分散的文档涉及各个项目的日子已经一去不复返了。随着Maven的其他恒星组成的星系的一个定义良好的Maven构建生命周期，易于编写和维护插件，集中库，全系统和基于用户的配置，以及越来越多的工具使开发人员的工作更容易维护的复杂项目的POM是大而明亮，中心。