Maven Document翻译——Maven入门指南(上篇)

在业余时间对Maven的文档做了一个翻译,由于本人的水平有限,可能会有一些出入,欢迎指正。 这个指南意欲为第一次使用Maven的人做参考,同时也是作为一个常见用例的指南。对于第一次使用的人,推荐按这个指南的步骤去学习,对于比较熟悉Maven的人来说,这个指南尽量为目前的需求提供一个快速的解决方案。以下的教程是假设读者已经下载Maven并将Maven本地安装的前提下,如果没有进行次步,请点击这个链接下载和安装下载并安装。 好了,现在你应该已经安装了Maven,我们即将开始。在我们介绍例子之前,我们先会简介的介绍一下什么是Maven、Maven怎样帮助你做日常工作以及与团队协作。当然,Maven对于小项目很有效,但是Maven同样能够很有效的使团队成员聚焦于项目的更重要的部分,基础架构的建立完全可以交给Maven.


什么是Maven?

大致一看,Maven貌似有很多东西,但是简单来说,Maven是对于模型化创建项目基础结构的一种尝试,通过一种清晰的并且拥有最佳实践效果的目录来提高生产率和项目的可读性。Maven是一款项目管理和理解项目的工具,通过以下方式来管理项目:

  • 构建
  • 帮助文档
  • 报告
  • 依赖
  • 软件配置管理
  • 发行
  • 发布 如果你想知道更多关于Maven的背景知识,你可以查阅Maven的哲学以及Maven的历史。接下来开始讲述如何让用户受益于Maven。



Mavne如何使我的开发流程受益?

Maven有助于你项目的构建过程,Maven通过使用标准约定和惯例来加速你的开发周期,同时有助于提高你的项目开发的成功率。 现在我们概述了一些关于Maven的历史和目的,让我们通过几个实际的例子来帮助你使用Maven!


我如何初始化Maven?

Maven的默认配置通常都很高效,但是如果你需要改变缓存位置,或通过HTTP代理使用Maven,你需要创建配置文件,具体请看Maven配置指南


我如何建立第一个Maven项目?

我们将要开始创建你的第一个Maven项目!为了创建我们第一个Maven项目,我们需要利用Maven的archetype插件。archetype被定义为原始的类型或者模型,是从所有拥有相似成分的东西抽象出来的。在Maven中,archetype是一个项目模板,包含了一些针对用户需求生成的一些上线的Maven项目的特性。现在我们将要展示archetype插件如何工作,但是如果你想知道更多的关于archetype的信息,请看Archetypes介绍。 开始创建你的第一个项目,为了创建最简单的Maven项目,请执行如下命令:

mvn -B archetype:generate \
  -DarchetypeGroupId=org.apache.maven.archetypes \
  -DgroupId=com.mycompany.app \
  -DartifactId=my-app

一旦你执行了这条命令,你将会发现一些事情会发生。首先你会注意到一个名称为my-app的目录被创建为一个新的项目,冰鞋这个目录包含一个名称为pom.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>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>Maven Quick Start Archetype</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.11</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>
  • pom.xml包含此项目的项目对象模型(POM).POM是Maven的最小工作单元,这个很重要,需要记住,因为Maven所有的围绕关于项目概念的东西是项目式的,简单来说,POM包含了所有关于你的项目重要的信息片段,而且基本上是以一站式服务的形式来找到所有关于你的项目的的东西。明白POM是很重要的,新手推荐看一下POM简介。 上边pom文件描述的是一个很简单的POM,但是仍然展现出了每个POM的关键元素,因此让我们通过他们来了解POM的要点:
  • project:这是所有Maven的pom.xml的顶层元素
  • modelVersion:这个元素表明当前POM所使用什么版本的对象模型。这个版本号很少发生改变,为了确保使用的稳定性,这是强制的,有但也是很少就是当Maven开发人员觉得有必要改变模型的时候。
  • groupId:这个元素代表创建这个项目的组织或小组的唯一标识。这个groupId是一个项目的关键标识符,很典型的做法是基于你组织的经过完全认证的域名。比如org.apache.maven.plugins是所有Maven插件的指定groupId。
  • artifactId:这个元素代表着个项目生成的初级artifact的唯一基名。一个项目的初级artifact通常都是一个jar文件。二级artifacts比如源码包经常会使用artifactId作为他们最终名称的一部分。一个Mavne生成的典型的artifact应该有类似-.的命名模式。(例如myapp-1.0.jar)
  • packaging:这个元素代表打包类型,比如jar,war,ear等等。这不仅意味artifact生成文件是jar,war或者ear,而且指出在构建过程中使用的特定的生命周期。(生命周期这个主题我们将会在指南的接下来进行讲述。现在,只需记住一个项目的打包类型可以在定制的构建生命周期当中发挥作用).packaging元素的默认值是jar,因此你在大多数项目中没有必要去指定。
  • version:这个元素代表项目生成的artifact的版本。Maven的版本管理对你大有帮助并且你经常在版本号中看到SNAPSHOT,这表明这个项目还处于开发的阶段,我们将会讨论snapshots的使用以及在本指南中其有何进一步功用。
  • name:这个元素代表项目的显示名称,经常在Maven生成文档的使用被用到。
  • description:这个元素提供了为你的项目提供了一个基本的描述。这个也经常在Maven生成文档时候被用到。 对于适合在POM中使用的元素的完全参考,请参考POM参考,现在让我们返回到项目。 在通过archetype生成你的第一个项目后,你会注意到如下的目录结构被创建了:
  • my-app
    |-- pom.xml
    `-- src
      |-- main
      |   `-- java
      |       `-- com
      |           `-- mycompany
      |               `-- app
      |                   `-- App.java
      `-- test
          `-- java
              `-- com
                  `-- mycompany
                      `-- app
                          `-- AppTest.java
    


正如你看到的,这个项目拥有一个POM和一个你的应用源码的源码目录树以及一个你的测试代码的源码目录树。这个是Maven项目的标准布局(应用源码在${basedir}/src/main/java中,测试代码在${basedir}/src/test/java,${basedir}代表包含pom.xml文件的目录)。 如果你准备创建一个maven项目,这中目录结构是我们推荐使用的。这是一个Maven的约定,想要了解更多,你可以阅读标准目录布局介绍。 现在我们拥有一个POM,一些应用源码,一些测试代码,你有可能会问…


我如何编译应用源码?

将目录改变到pom.xml所在的目录并且执行如下的命令来编译你的应用源码:

mvn compile

在执行了这条命令后你应该看到如下的输出:

[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Quick Start Archetype
[INFO]    task-segment: [compile]
[INFO] ----------------------------------------------------------------------------
[INFO] artifact org.apache.maven.plugins:maven-resources-plugin: \
  checking for updates from central
...
[INFO] artifact org.apache.maven.plugins:maven-compiler-plugin: \
  checking for updates from central
...
[INFO] [resources:resources]
...
[INFO] [compiler:compile]
Compiling 1 source file to <dir>/my-app/target/classes
[INFO] ----------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ----------------------------------------------------------------------------
[INFO] Total time: 3 minutes 54 seconds
[INFO] Finished at: Fri Sep 23 15:48:34 GMT-05:00 2005
[INFO] Final Memory: 2M/6M
[INFO] ----------------------------------------------------------------------------

第一次你执行这个命令,Maven将会下载执行此命令的所有的插件和相关的依赖。初始安装Maven,这个过程将会需要一段时间来完成(从上面的输出来看,这将会需要大约4分钟)。如果你再次执行这个命令,Maven会拥有它所有的需要的,因此它不会下载任何新的东西,并且会很快的执行这条命令。

正如你从输出中可以看到的,编译后的class文件将会被放在${basedir}/target/classes,这是Maven的另外一个通常的约定。因此,如果你的观察很敏锐,你会发现利用通常的约定,POM篇幅很小,你不用很明确的告诉Maven你的源码在哪里,应该向什么地方输出。通过利用通常的Maven约定,你花费很小的力气可以获得很多的便利!


我如何编译测试源码并且做单元测试?

现在你成功的编译了你的应用源码并且现在你需要做一些单元测试,这些测试代码需要编译和执行(因为每个程序员总是编写和执行他们的单元测试) 执行 如下的命令:

mvn test

执行这条命令,你应该看到如下的输出:

[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Quick Start Archetype
[INFO]    task-segment: [test]
[INFO] ----------------------------------------------------------------------------
[INFO] artifact org.apache.maven.plugins:maven-surefire-plugin: \
  checking for updates from central
...
[INFO] [resources:resources]
[INFO] [compiler:compile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [resources:testResources]
[INFO] [compiler:testCompile]
Compiling 1 source file to C:\Test\Maven2\test\my-app\target\test-classes
...
[INFO] [surefire:test]
[INFO] Setting reports dir: C:\Test\Maven2\test\my-app\target/surefire-reports

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
[surefire] Running com.mycompany.app.AppTest
[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0 sec

Results :
[surefire] Tests run: 1, Failures: 0, Errors: 0

[INFO] ----------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ----------------------------------------------------------------------------
[INFO] Total time: 15 seconds
[INFO] Finished at: Thu Oct 06 08:12:17 MDT 2005
[INFO] Final Memory: 2M/8M
[INFO] ----------------------------------------------------------------------------

一些需要注意的是: -Maven这次下载了更多的依赖,这些事执行测试需要的依赖和插件,但是对于已经存在的是不会下载的(本地仓库) -在编译和执行测试之前,Maven编译主要的代码(所有的class文件都是最新的,只要我们在编译以后不改变任何东西) 如果你简单的想编译你的测试代码(并不去执行),你可以执行如下命令:

mvn test-compile

现在你可以编译你的应用源码,编译你的测试代码,并且执行测试,你想继续下一步,你将会问…


我如何创建一个jar文件并且将之安装到我的本地仓库?

创建一个jar文件很简单,执行如下命令就可以了:

mvn package

如果你看一下你项目的POM你就会发现packaging元素是被设置为jar的。这就是为什么Maven知道去生成一个jar文件的原因了。你查看一下${basedir}/target目录你就会看到生成的jar文件。 现在你将想去安装你生成的artifact(jar文件)到你的本地仓库(${user.home/.m2/repository是默认位置)。想了解更到关于仓库的信息,你可以查看仓库介绍,接着让我们继续安装我们的artifact执行如下的命令:

mvn install

执行命令后你应该看到如下的输出:

[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Quick Start Archetype
[INFO]    task-segment: [install]
[INFO] ----------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] [compiler:compile]
Compiling 1 source file to <dir>/my-app/target/classes
[INFO] [resources:testResources]
[INFO] [compiler:testCompile]
Compiling 1 source file to <dir>/my-app/target/test-classes
[INFO] [surefire:test]
[INFO] Setting reports dir: <dir>/my-app/target/surefire-reports

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
[surefire] Running com.mycompany.app.AppTest
[surefire] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.001 sec

Results :
[surefire] Tests run: 1, Failures: 0, Errors: 0

[INFO] [jar:jar]
[INFO] Building jar: <dir>/my-app/target/my-app-1.0-SNAPSHOT.jar
[INFO] [install:install]
[INFO] Installing <dir>/my-app/target/my-app-1.0-SNAPSHOT.jar to \
   <local-repository>/com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.jar
[INFO] ----------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ----------------------------------------------------------------------------
[INFO] Total time: 5 seconds
[INFO] Finished at: Tue Oct 04 13:20:32 GMT-05:00 2005
[INFO] Final Memory: 3M/8M
[INFO] ----------------------------------------------------------------------------

注意surefire插件(用于执行测试)通过特定的文件命名约定去寻找测试代码。默认的命名规则如下: **/*Test.java **/Test*.java **/*TestCase.java 但是默认的不包括如下: **/Abstract*Test.java **/Abstract*TestCase.java 你已经走了初始化、构建、测试、打包和安装整个流程,这是Maven项目的典型过程。如果你已经注意的话,这就是大部分项目利用Maven来做的工作。所有你能够做的都在这个18行的文件中即项目模型或POM。如果你了解利用Ant创建相同功能的文件,你会发现篇幅一般是POM的两倍。Maven可以给你提供更多的功能而且不用更多的设置。利用Ant得到更多的功能,你必须注意各种容易错的条件。 什么东西还是你可以免费得到的呢?这里有很多的Maven插件。我们这里提及一个插件,它是Maven的一个重要特性之一。POM中不用任何多余的设置,可以为你的项目生成一个站点。你可能会想去定制化你的Maven站点,但是假如你想很快为你的项目提供一个基本信息的介绍,那么可以执行如下的命令:

mvn site

这里也有很多独立的功能可以去执行,例如:

mvn clean

这个命令将会删除target目录和其中的所有构建数据,就类似开始的样子. 可能你想为项目生成一个intellij idea的描述?

mvn idea:idea

这样就可以运行在IDEA中,这将会更新设置,而不是恢复成最开始的样子。 如果你使用Eclipse IDE,只需:

mvn eclipse:eclipse

注意:许多类似的Maven1.0目标还存在,比如jar:jar,但是他们的结果可能和你所期望的是不一样的,现在jar:jar不会重新编译源码,它只会简单的利用target/classes来创建jar文件,会假设所有的东西在之前已经做了,比如说编译。


什么是SNAPSHOT版本?

注意pom.xml中版本号的值会带有-SNAPSHOT的后缀。

<project xmlns="http://maven.apache.org/POM/4.0.0"
  ...
  <groupId>...</groupId>
  <artifactId>my-app</artifactId>
  ...
  <version>1.0-SNAPSHOT</version>
  <name>Maven Quick Start Archetype</name>
  ...

SNAPSHOT指开发分支的最新的代码,无法保证代码是稳定的或者不会改变的。相反的,release版本的代码是不会改变的。 换句话说,SNAPSHOT版本是release之前的开发版本。 在发布过程中,版本例如x.y-SNAPSHOT会变成x.y。发布过程经常会增量开发版本为x.(y+1)-SNAPSHOT。比如:版本号1.0-SNAPSHOT的发布版本为1.0,并且新的开发版本为1.1-SNAPSHOT




网易云新用户大礼包:https://www.163yun.com/gift

本文来自网易实践者社区,经作者范鹏程授权发布。