开篇词
该指南将引导你使用 Maven 构建简单的 Java 项目。
你将创建的应用
你将借助 Maven 构建一个简单的应用。
你将需要的工具
- 大概 15 分钟左右;
- 你最喜欢的文本编辑器或集成开发环境(IDE)
- JDK 8 或更高版本;
如何完成这个指南
像大多数的 Spring 入门指南一样,你可以从头开始并完成每个步骤,也可以绕过你已经熟悉的基本设置步骤。如论哪种方式,你最终都有可以工作的代码。
- 要从头开始,移步至设置项目;
- 要跳过基础,执行以下操作:
待一切就绪后,可以检查一下 gs-maven/complete
目录中的代码。
设置项目
首先,为 Maven 设置一个 Java 项目。为了将注意力集中在 Maven 上,先使该项目尽可能的简单。
创建目录结构
在选择的项目目录中,创建以下自目录结构;例如,在 Linux 系统上使用 mkdir -p src/main/java/hello
:
└── src
└── main
└── java
└── hello
在 src/main/java/hello
目录中,我们可以创建 Java 类。为简单起见以及与该指南的其余部分保持一致,Spring 建议创建两个类:HelloWorld.java
和 Greeter.java
。
src/main/java/hello/HelloWorld.java
package hello;
public class HelloWorld {
public static void main(String[] args) {
Greeter greeter = new Greeter();
System.out.println(greeter.sayHello());
}
}
src/main/java/hello/Greeter.java
package hello;
public class Greeter {
public String sayHello() {
return "Hello world!";
}
}
安装 Maven
现在我们有了可以使用 Maven 来构建的项目,我们开始安装 Maven。
我们可以从 https://maven.apache.org/download.cgi 来获取。仅需二进制文件即可,因此请查找 apache-maven-{version}-bin.zip 或 apache-maven-{version}-bin.tar.gz 所对应的链接。
将文件解压缩,并将 bin 目录添加至环境变量中。
要测试 Maven 的安装,请在命令行运行 mvn
:
mvn -v
如果一切顺利,我们会看到以下消息:
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T16:41:47+00:00)
Maven home: /home/dsyer/Programs/apache-maven
Java version: 1.8.0_152, vendor: Azul Systems, Inc.
Java home: /home/dsyer/.sdkman/candidates/java/8u152-zulu/jre
Default locale: en_GB, platform encoding: UTF-8
OS name: "linux", version: "4.15.0-36-generic", arch: "amd64", family: "unix"
我们现在已经安装了 Maven。
提示:我们可能考虑用 Maven Wrapper 来确保开发人员之间使用的 Maven 版本为一致的。从 Spring Initializr 下载的项目都包含包装器。它在跟路径下是一个
mvnw
脚本,用以代替mvn
命令。
定义一个简单的 Maven 构建
现在已经安装了 Maven,我们需要创建一个 Maven 项目定义。Maven 项目是使用名为 pom.xml 的 XML 文件来进行定义的。除了其他一些信息,该文件还提供了项目的名称、版本以及对外部库的依赖关系。
在项目的根目录创建一个名为 pom.xml 的文件(即 src
目录旁边),其内容为:
<?xml version="1.0" encoding="UTF-8"?>
<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.springframework</groupId>
<artifactId>gs-maven</artifactId>
<packaging>jar</packaging>
<version>0.1.0</version>
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>2.1</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<transformers>
<transformer
implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>hello.HelloWorld</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
除了可选的 <packaging>
元素外,这是构建 Java 项目所需的最简单的 pom.xml 文件。它包含以下项目配置信息:
<modelVersion>
:POM 模型版本(始终为 4.0.0);<groupId>
:项目所属的组或组织。通常表示为反向域名;<artifactId>
:要赋予项目的库工件的名称(例如,其 JAR 或 WAR 文件的名称);<version>
:正在构建的项目的版本;<packaging>
:如何打包项目。使用 “jar” 来打包为 JAR,这是默认选项。使用 “war” 来打包为 WAR 文件。
在选择版本控制方案时,Spring 建议使用语义版本控制方法。
至此,我们已经定义了一个最小但功能强大的 Maven 项目。
构建 Java 代码
Maven 现在准备构建该项目。我们现在可以使用 Maven 执行几个构建生命周期目标,包括编译项目代码、创建库包(例如 JAR 文件)以及将将库安装至本地 Maven 依赖库中。
要尝试构建,请在命令行中发出以下命令:
mvn compile
这将运行 Maven,告诉它执行编译目标。完成后,我们应该在 target/classes 目录中找到已编译的 .class 文件。
由于我们一般不会直接分发或使用 .class 文件,所以我们可能需要运行打包目标:
mvn package
打包目标将编译 Java 弟阿玛,运行任何测试,最后将在目标目录内将代码打包成 JAR 文件。JAR 文件的名称将基于项目的 <artifactIs>
和 <version>
。例如,那之前最小的 pom.xml 文件来说,那 JAR 文件将命名为 gs-maven-0.1.0.jar。
要执行 JAR 文件,请运行:
java -jar target/gs-maven-0.1.0.jar
如果我们将
<packaging>
的值从 “jar” 改为 “war”,那结果将是目标目录内有一个 WAR 文件,而不是 JAR 文件。
Maven 还维护本地机器的依赖仓库(通常在主目录中的 .m2/repository 目录中),以快速访问项目依赖。如果要将项目的 JAR 文件安装至本地仓库中,则应调用 install
目标:
mvn install
install 目标将编译、测试以及打包项目代码,随后将其复制至本地依赖仓库中,以供另一个项目将其引入依赖项中。
说到依赖,现在是时候在 Maven 构建中声明依赖了。
声明依赖
该 Hello World 示例是完全无依赖的,没有任何的依赖。二大多数的应用都依赖于第三方库来处理常见的以及/或复杂的功能实现。
例如,假设除了输出 “Hello World!” 外,我们希望该应用还能打印当前日期。我们可以使用 Java 库中自带的日期和时间工具,也可以使用 Joda Time 库来使事情变得更有趣。
首先,将 HelloWorld.java 改成:
package hello;
import org.joda.time.LocalTime;
public class HelloWorld {
public static void main(String[] args) {
LocalTime currentTime = new LocalTime();
System.out.println("The current local time is: " + currentTime);
Greeter greeter = new Greeter();
System.out.println(greeter.sayHello());
}
}
在这里,HelloWorld
借助 Joda Time 的 LocalTime
类来获取并打印当前时间。
如果我们现在运行 mvn compile
来构建项目,构建将会失败,因为我们还未在构建中将 Joda Time 声明为编译时依赖。我们可以将其加入 pom.xml 文件(在 <poject>
元素内)中来解决该问题:
<dependencies>
<dependency>
<groupId>joda-time</groupId>
<artifactId>joda-time</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
该 XML 块声明了项目的依赖列表。它为 Joda Time 库声明了依赖关系。在 <dependency
元素内,依赖关系由以下三个元素来协作:
<groupId>
:依赖关系所属的组或组织;<artifactId>
:所需的库;<version>
:所需的特定版本的库。
默认情况下,所有依赖的范围都属于 compile
依赖。它们应该在编译时可用(如果我们正在构建 WAR 文件,包括在 WAR 的/WEB-INF/libs 文件夹中)。我们可以给 <scope>
元素指定以下的范围:
provided
:编译项目代码所需的依赖,但将在运行时由运行该代码的容器(例如 Java Servlet API)提供;test
:用于编译和运行测试的依赖,但对于构建或运行项目的运行时代码则不是必须的。
现在,我们运行 mvn compile
或 mvn package
的话,Maven 应该会从 Maven 仓库中解析 Joda Time 的依赖,并成功构建该项目。
编写一个测试
首先将 JUnit 依赖加入 pom.xml 的测试范围内:
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.12</version>
<scope>test</scope>
</dependency>
然后创建一个测试用例:
src/test/java/hello/GreeterTest.java
package hello;
import static org.hamcrest.CoreMatchers.containsString;
import static org.junit.Assert.*;
import org.junit.Test;
public class GreeterTest {
private Greeter greeter = new Greeter();
@Test
public void greeterSaysHello() {
assertThat(greeter.sayHello(), containsString("Hello"));
}
}
Maven 使用一个名为 “surefire” 的插件来运行单元测试。该插件的默认配置是编译并运行 src/test/java
中所名称与 *Test
匹配的类。我们可以这样在命令行上运行测试:
mvn test
或只使用上面已经显示的 mvn install
不受(又一个生命周期定义,其中 “test” 作为 “install” 的一个阶段)。
以下是完整的 pom.xml
文件:
pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<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.springframework</groupId>
<artifactId>gs-maven</artifactId>
<packaging>jar</packaging>
<version>0.1.0</version>
<properties>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
<dependencies>
<!-- tag::joda[] -->
<dependency>
<groupId>joda-time</groupId>
<artifactId>joda-time</artifactId>
<version>2.9.2</version>
</dependency>
<!-- end::joda[] -->
<!-- tag::junit[] -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.12</version>
<scope>test</scope>
</dependency>
<!-- end::junit[] -->
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>2.1</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<mainClass>hello.HelloWorld</mainClass>
</transformer>
</transformers>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
完整的 pom.xml 文件用到了 Maven Shade 插件,以使 JAR 文件可执行化。该指南的重点是学会使用 Maven,而不是使用该特定的插件。
概述
恭喜你!我们创建了一个简单而有效的 Maven 构建文件,用于构建 Java 项目。
参见
以下指南也可能会有所帮助:
想看指南的其他内容?请访问该指南的所属专栏:《Spring 官方指南》