Maven · 编写 Maven 插件
前面文章已经讲过,Maven 的任何行为都是由插件完成的,包括项目的清理、编译、 测试以及打包等操作都有其对应的Maven 插件。每个插件拥有一个或者多个目标,用户可 以直接从命令行运行这些插件目标,或者选择将目标绑定到Maven 的生命周期。
大量的 Maven 插件可以从 Aapche 和 Codehaus 获得,这里的近百个插件几乎能够满足所有Maven 项目的需要。除此之外,还有很多 Maven 插件分布在 Googlecode 、Sourceforge、 Github 等项目托管服务中。因此,当你发现自己有特殊需要的时候,首先应该搜索一下看是否已经有现成的插件可供使用。例如,如果想要配置Maven 自动为所有Java 文件的头部添加许可证声明,那么可以通过关键字 maven plugin license 找到 maven-license-plugin, 这个托管在 Googlecode 上的项目完全能够满足我的需求。
在一些非常情况下(几率低于1%), 你有非常特殊的需求,并且无法找到现成的插件 可供使用,那么就只能自己编写 Maven 插件了。编写 Maven 插件并不是特别复杂,本文将 详细介绍如何一步步编写能够满足自己需要的 Maven 插件。
1️⃣ 编写 Maven 插件的一般步骤
为了能让大家对编写 Maven 插件的方法和过程有一个总体的认识,下面先简要介绍一下编写 Maven 插件的主要步骤。
- 创建一个 maven-plugin 项目:插件本身也是Maven项目,特殊的地方在于它的 packaging 必须是 maven-plugin, 用户可以使用 maven-archetype-plugin 快速创建一个 Maven 插件项目。
- 为插件编写目标:每个插件都必须包含一个或者多个目标, Maven 称之为 Mojo ( 与 POJO对应,后者指 Plain Old Java Object, 这里指 Maven Old Java Object)。编写插件的时候 必须提供一个或者多个继承自 AhstractMojo 的类。
- 为目标提供配置点:大部分Maven 插件及其目标都是可配置的,因此在编写Mojo的 时候需要注意提供可配置的参数。
- 编写代码实现目标行为:根据实际的需要实现 Mojo。
- 错误处理及日志:当Mojo发生异常时,根据情况控制Maven 的运行状态。在代码中 编写必要的日志以便为用户提供足够的信息。
- 测试插件:编写自动化的测试代码测试行为,然后再实际运行插件以验证其行为。
2️⃣ 案例:编写一个用于代码行统计的 Maven 插件
为了便于大家实践,下面将详细演示如何实际编写一个简单的用于代码行统计的 Maven 插件。使用该插件,用户可以了解到 Maven 项目中各个源代码目录下文件的数量,以及它们加起来共有多少代码行。不过,有些朋友强烈反对使用代码行来考核程序员,因为大家都知道,代码的数量并不能真正反映一个程序员的价值。
要创建一个 Maven插件项目,首先使用 maven-archetype-plugin 命令:
$mvn archetype:generate
然后选择:
maven-archetype-plugin (An archetype which contains a sample Maven plugin.)
输入Maven坐标等信息之后, 一个 Maven插件项目就创建好了。打开项目的 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/maven-v4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.xiaoshan.mvnbook</groupId>
<artifactId>maven-loc-plugin</artifactId>
<packaging>maven-plugin</packaging>
<version>0.0.1-SNAPSHOT</version>
<name>Maven LOC Plugin</name>
<url>http://www.xiaoshan.com/</url>
<properties>
<maven.version>3.0</maven.version>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-plugin-api</artifactId>
<version>${maven.version}</version>
</dependency>
</dependencies>
</project>
Maven 插件项目的 POM 有两个特殊的地方:
- 1)它的 packaging必须为 maven-plugin, 这种特殊的打包类型能控制 Maven 为其在生命周期阶段绑定插件处理相关的目标,例如在 compile阶段, Maven需要为插件项目构建一个特殊插件描述符文件。
- 2)从上述代码中可以看到一个 artifactld 为 maven-plugin-api的依赖,该依赖中包含了 插件开发所必需的类,例如稍后会看到的 AbstractMojo。需要注意的是,代码中 并没有使用默认 Archetype 生成的 maven-plugin-api 版本,而是升级到了3.0,这样做的目的是与Maven 的版本保持一致。
插件项目创建好之后,下一步是为插件编写目标。使用Archetype 生成的插件项目包含 了一个名为MyMojo的 Java 文件,我们将其删除,然后自己创建一个 CountMojo,如代码所示。
/**
* Goal which counts lines of code of a project
* @goal count
*/
public class CountMojo extends AbstractMojo {
private static final String[] INCLUDES_DEFAULT ={"java","xml","properties"};
/**
* @parameter expression="${project.basedir}"
* @required
* @readonly
*/
private File basedir;
/**
* @parameter expression="${project.build.sourceDirectory}"
* @required
* @readonly
*/
private File sourceDirectory;
/**
* parameter expression="${project.build.testSourceDirectory}"
* @required
* @readonly
*/
private File testSourceDirectory;
/**
* @parameter expression="${project.build.resources}"
* @required
* @readonly
*/
private List<Resource> resources;
/**
* @parameter expression="${project.build.testResources}"
* @required
* @readonly
*/
private List<Resource> testResources;
/**
*The file types which will be included for counting
*@parameter
*/
private string[] includes;
public void execute() throws NojoExecutionException{
if(includes ==null || includes.length ==0){
includes =INCLUDES_DEFAULT;
}
try{
countDir(sourceDirectory);
countDir(testSourceDirectory);
for(Resource resource : resources){
countDir(new File(resource.getDirectory()));
}
for(Resource resource : testResources){
countDir(new File(resource.getDirectory()));
}
}
catch(IOException e){
throw new MojoExecutionException("Unable to count lines of code.",e);
}
}
}
首先,每个插件目标类,或者说Mojo, 都必须继承 AbstractMojo 并实现 execute() 方法,只有这样Maven 才能识别该插件目标,并执行 execute() 方法中的行为。其次,由于历史原因,上述CountMojo类使用了Java1.4 风格的标注(将标注写在注释中), 这里要关注的是@goal, 任何一个 Mojo都必须使用该标注写明自己的目标名称,有了目标定义之后, 我们才能在项目中配置该插件目标,或者在命令行调用之。例如:
$mvn com.xiaoshan.mvnbook :maven-loc-plugin:0.0.1-SNAPSHOT:count
创建一个Mojo 所必要的工作就是这三项:继承 AbstractMojo、实现 execute() 提供@goal 标注。
下一步是为插件提供配置点。我们希望该插件默认统计所有Java、XML, 方法、以及 properties 文件 , 但是允许用户配置包含哪些类型的文件。 代码中的 includes 字段就是用来为用户提供该配置点的,它的类型为String 数组,并且使用了@parameter 参数表示用户可以在使用该插件的时候在POM 中配置该字段,如代码:
<plugin>
<groupId>com.xiaoshan.mvnbook</groupId>
<artifactId>maven-1oc-plugin</artifactId>
<version>0.0.1-SNAPSHOT</version>
<configuration>
<includes>
<include>java</include>
<include>sql</include>
</includes>
</configuration>
</executions>
</plugin>
代码配置了 CountMojo统计Java 和 SQL 文件,而不是默认的 Java 、XML 和Properties。
代码中还包含了 basedir 、sourceDirectory 、testSourceDirectory 等字段,它们都使用了@parameter 标注,但同时关键字 expression 表示从系统属性读取这几个字段的值。
${project.basedir} 、${project.build.sourceDirectory}、${project.build.testSourceDirectory}
等表达式读者应该已经熟悉,它们分别表示了项目的基础目录、主代码目录和测试代码目录 。 @readonly 标注表示不允许用户对其进行配置,因为对于一个项目来说,这几个目录位置都是固定的。
了解这些简单的配置点之后,下一步就该实现插件的具体行为了。从前面代码的 execute() 方法中大家能看到这样一些信息:如果用户没有配置 includes 则就是用默认的统计包含配置,然后再分别统计项目主代码目录、测试代码目录、主资源目录,以及测试资源目录。这里涉及一个 countDir()
方法,其具体实现如代码所示。
private void countDir(File dir) throws IOException{
if(!dir.exists()) {
return;
}
List<File> collected =new ArrayList<File>();
collectFiles(collected,dir);
int lines =0;
for(File sourceFile:collected){
lines +=countLine(sourceFile );
}
String path =dir.getAbsolutePath().substring(basedir.getAbsolutePath().length());
getLog().info(path+":"+lines+"lines of code in"+collected.size()+"files");
}
private void collectFiles(List<File> collected,File file)
{
if(file.isFile()){
for(String include:includes){
if(file.getName().endsWith("."+include)){
collected.add(file);
break;
}
}
}
else{
for(File sub:file.listFiles()){
collectFiles(collected,sub);
}
}
}
private int countLine(File file) throws IOException {
BufferedReader reader =new BufferedReader(new FileReader(file));
int line =0;
try {
while(reader.ready())
{
reader.readLine();
line++;
}
}
finally {
reader.close();
}
return line;
}
这里简单解释一下上述三个方法: collectFiles() 方法用来递归地收集一个目录下所有应当被统计的文件,countLine()方法用来统计单个文件的行数,而 countDir()则借助上述两个方法统计某一目录下共有多少文件被统计,以及这些文件共包含了多少代码行。
代码中的execute() 方法包含了简单的异常处理,代码行统计的时候由于涉及了文件操作,因此可能会抛出 IOException。当捕获到 IOException 的时候,使用 MojoExecutationException 对其简单包装后再抛出,Maven 执行插件目标的时候如果遇到 MojoExecutationException, 就会在命令行显示 “BUILD ERROR” 信息。
代码中的 countDir() 方法的最后一行使用了AbstractMojo 的 getLog() 方法, 该方法返回一个类似于Log4j的日志对象,可以用来将输出日志到Maven 命令行。这里使用了 info 级别的日志告诉用户某个路径下有多少文件被统计,共包含了多少代码行,因此在使用该插件的时候可以看到如下的 Maven 输出:
[INFO]---maven-loc-plugin:0.0.1-SNAPSHOT:count(default)@app ---
[INFO]\src\main\java:13 lines of code in 1 files
[INFO]\src\test\java:38 lines of code in 1 files
使用 mvn clean install 命令将该插件项目构建并安装到本地仓库后,就能使用它统计 Maven 项目的代码行了。如下所示:
$mvn com.xiaoshan.mvnbook:maven-loc-plugin:0.0.1-SNAPSHOT:count
[INFO]Scanning for projects...
[INFO]
[INFO]--------------------------------------------------------------
[INFO]Building Account Captcha 1.0.0-SNAPSHOT
[INFO]--------------------------------------------------------------
[INFO]
[INFO]---maven-loc-plugin:0.0.1-SNAPSHOT:count(default-cli) @account-captcha
[INFO]\src\main\java:179 lines of code in 4 files
[INFO]\src\test\java:112 lines of code in 2 files
[INFO]\src\main\resources:11 lines of code in 1 files
[INFO]\src\test\resources:0 lines of code in 0 files
[INFO]--------------------------------------------------------------
[INFO]BUILD SUCCESS
[INFO]--------------------------------------------------------------
[INFO]Total time:0.423s
[INFO]Finished at:Sat Jun 0516:28:35 CST 2023
[INFO]Final Memory:1M/4M
[INFO]--------------------------------------------------------------
如果嫌命令行太长太复杂,可以将该插件的 groupld 添加到 settings.xml 中。如下所示:
<settings>
<pluginGroups>
<pluginGroup>com.xiaoshan.mvnbook</pluginGroup>
</pluginGroups>
</settings>
现在 Maven 命令行就可以简化成:
$mvn loc:count
3️⃣ Mojo 标注
每个Mojo 都必须使用 @Goal 标注来注明其目标名称,否则 Maven 将无法识别该目标。 Mojo 的标注不仅限于@Goal, 以下是一些可以用来控制 Mojo 行为的标注。
@goal <name>
这是唯一必须声明的标注,当用户使用命令行调用插件,或者在 POM 中配置插件的时候,都需要使用该目标名称。@phase <phase>
默认将该目标绑定至 Default生命周期的某个阶段,这样在配置使用该插件目标的时候 就不需要声明 phase 。 例如 ,maven-surefire-plugin 的 test 目标就带有 @phase test 标注。@requiresDependencyResolution <scope>
表示在运行该 Mojo 之前必须解析所有指定范围的依赖。例如,maven-surefire-plugin 的 test 目标带有@requiresDependencyResolution test 标注,表示在执行测试之前,所有测试范围 的依赖必须得到解析。这里可用的依赖范围有 compile、test 和 runtime, 默认值为 runtime。@requiresProject <true/false>
表示该目标是否必须在一个 Maven 项目中运行,默认为true 。大部分插件目标都需要依赖一个项目才能执行,但有一些例外。例如 maven-help-plugin 的 system目标,它用来显示系统属性和环境变量信息,不需要实际项目,因此使用了@requiresProject false 标注。另外, maven-archetype-plugin 的 generate 目标也是一个很好的例子。@requiresDirectInvocation <true/false>
当值为 true的时候,该目标就只能通过命令行直接调用,如果试图在 POM 中将其绑定到生命周期阶段 ,Maven 就会报错,默认 值 为false 。 如果你希望编写的插件只能在命令行 独立运行,就应当使用该标注。@requiresOnline <true/false>
表示是否要求 Maven 必须是在线状态,默认值是false。@requiresReport <true/false>
表示是否要求项目报告已经生成,默认值是 false。@aggregator
当 Mojo 在多模块项目上运行时,使用该标注表示该目标只会在顶层模块运行。例如 maven-javadoc-plugin 的 aggregator-jar 使用了 @aggregator 标注,它不会为多模块项目的每个模块生成Javadoc, 而是在顶层项目生成一个已经聚合的 Javadoc 文档。@execute goal=“<goal>”
在运行该目标之前先让Maven 运行另外一个目标,如果是本插件的目标,则直接使用 目标名称,否则使用“prefix;goal”的形式,即注明目标前缀。例如, maven-pmd-plugin 是一个使用 PMD来分析项目源码的工具,它包含 pmd 和 check 等目标,其中 pmd 用来生成 报告,而check 用来验证报告。由于check 是依赖于 pmd 生成的内容的,因此可以看到它使用了标注@ execute goul=“pmd”。@execute phase=“<phase>”
在运行该目标之前让Maven 先运行一个并行的生命周期,到指定的阶段为止。例如 maven-dependency-plugin 的 analyze 使用了标注@execute phase =“test-compile”,因此当用户在 命令行执行 dependeney:analyze 的时候, Maven 会首先执行 default 生命周期所有至 test- compile 的阶段@execute lifecycle=“<Hifecycle>” phase=“<phase>”
在运行该目标之前让Maven先运行一个自定义的生命周期,到指定的阶段为止。例如 maven-surefire-report-plugin 这个用来生成测试报告的插件,它有一个report 目标,标注了@execute phase=“test” lifecycle=“surefire”,表示运行这个自定义的 surefire 声明周期至 test 阶段。自定义生命周期的配置文件位于 src/main/resources/META-INF/maven/lifecycle.xml。 内容如代码所示。
<lifecycles>
<lifecycle>
<id>surefire</id>
<phases>
<phase>
<id>test</id>
<configuration>
<testFailureIgnore>true</testFailureIgnore>
</configuration>
</phase>
</phases>
</lifecycle>
</lifecycles>
4️⃣ Mojo 参数
正如在代码中所看到的那样,我们可以使用@ parameter 将 Mojo的某个字段 标注为可配置的参数,即 Mojo参数。事实上几乎每个 Mojo 都有一个或者多个 Mojo 参数, 通过配置这些参数,Maven用户可以自定义插件的行为。
Maven 支持种类多样的 Mojo 参数,包括单值的 boolean、int、foat、String、Date、File 和 URL, 多值的数组、Collection、Map、Properties 等。
-
boolean (包括 boolean 和 Boolean)
/** *@parameter */ private boolean sampleBoolean
对应的配置如下:
<sampleBoolean>true</sampleBoolean>
-
int ( 包 括 Integer 、long 、Long 、short 、Short 、byte 、Byte)
/** *@parameter */ private int sampleInt
对应的配置如下:
<sampleInt>8</sampleInt>
-
float ( 包 括 Float 、double 、Double)
/** *@parameter */ private float sampleFloat
对应的配置如下:
<gampleFloat>8.8</sampleFloat>
-
String ( 包 括 StringBuffer 、char 、Character)
/** *@parameter */ private String sampleString
对应的配置如下:
<sampleString>Hello World</samplestring>
-
Date (格式为 yyyy-MM-dd HH:mm:sa.Sa或者 yyyy-MM-dd HH:mm:ssa)
/** *@parameter */ private Date sampleDate
对应的配置如下:
<sampleDate>2010-06-063:14:55.1 PM</sampleDate>
或者
<sampleDate>2010-06-063:14:55PM</sampleDate>
-
File
/** *@parameter */ private File sampleFile
对应的配置如下:
<sampleFile>c:\tmp</sampleFile>
-
URL
/** *@parameter */ private URL sampleURL
对应的配置如下:
<sample=URL>http://www.xiaoshan.com/</sampleURL>
-
数组
/** *@parameter */ private String[] includes
对应的配置如下:
<includes> <include>java</include> <include>sql</include> </includes>
-
Collection ( 任何实现 Collection 接口的类 , 如 ArrayList 和 HashSet)
/** *@parameter */ private List includeg
对应的配置如下:
<includes> <include>java</include> <include>sql</include> </includes>
-
Map
/** *@parameter */ private Map sampleMap
对应的配置如下:
<sampleMap> <key1>value1</key2> <key1>value2</key2> </sampleMap>
-
Properties
/** *@parameter */ private Properties sampleProperties
对应的配置如下:
<sampleProperties> <property> <name>P_name_1</name> <value>p_value_1</value> </property> <property> <name>p_name_2</name> <value>p_value_2</value> </property> </sampleProperties>
一个简单的@parameter 标注就能让用户配置各种类型的 Mojo 字段,不过在此基础上, 用户还能为@ parameter 标注提供一些额外的属性,进一步自定义 Mojo 参数。
-
@parameter alias=“<aliasName>”
使用alias, 用户就可以为Mojo参数使用别名,当Mojo字段名称太长或者可读性不强 时,这个别名就非常有用。例如:/** *@parameter alias="uid" */ private String uniqueIdentity
对应的配置如下:
<uid>xiaoshan</uid>
-
@parameter expression=“${aSystemProperty}”
使用系统属性表达式对 Mojo参数进行赋值,这是非常有用的特性。配置了@parameter 的expression之后,用户可以在命令行配置该Mojo参数。例如,maven-surefire-plugin 的 test 目标有如下源码:/** *@parameter expression="${maven.test.skip}" */ private boolean skip;
用户可以在POM 中配置skip 参数,同时也可以直接在命令行使用-Dmaven.test.skip=true 来跳过测试。如果 Mojo 参数没有提供 expresion, 那就意味着该参数无法在命令行直接配置。还需要注意的是, Mojo 参数的名称和 expresion 名称不一定相同。
-
@parameter default-value="aValue/ ${anExpresion} "
如果用户没有配置该Mojo 参数,就为其提供一个默认值。该值可以是一个简单字面量 如 “true”、“hello”或者“1.5”,也可以是一个表达式,以方便使用POM 的某个元素。
例如,下面代码中的参数 sampleBoolean 默认值为 true:/** *@parameter defaultValue="true" */ private boolean sampleBoolean
第二节中有如下代码:
/** *@parameter expression="${project.build.sourceDirectory}" *@required *@readonly */ private File sourceDirectory;
表示默认使用 POM 元 素
<project><build><sourceDirectory>
的 值 。 除了 @parameter 标注外,还看到可以为Mojo 参数使用 @readonly 和 @required 标注。 -
@readonly
表示该Mojo 参数是只读的,如果使用了该标注,用户就无法对其进行配置。通常在应用 POM 元素内容的时候,我们不希望用户干涉。 -
@required
表示该Mojo 参数是必须的,如果使用了该标注,但是用户没有配置该Mojo 参数且其没有默认值 ,Maven 就会报错。
5️⃣ 错误处理和日志
如果大家看一下 Maven 的源码,会发现 AbstractMojo 实 现 了 Mojo 接 口 ,execute() 方法正是在这个接口中定义的。具体代码如下:
void execute() throws MojoExecutionException,MojoFailureException;
这个方法可以抛出两种异常,分别是MojoExecutionException 和 MojoFailureException。
如果 Maven 执行插件目标的时候遇到 MojoFailureException, 就会显示 “BUILD FAILURE” 的错误信息,这种异常表示 Mojo 在运行时发现了预期的错误。例如 maven-surefire-plugin 运行后若发现有失败的测试就会抛出该异常。
如果Maven 执行插件目标的时候遇到 MojoExecutationException, 就会显示“BUILD ERROR” 的错误信息。这种异常表示 Mojo 在运行时发现了未预期的错误,例如代码中我们不知道代码行统计插件何时会遇到 IOExceptiom, 这个时候只能将其嵌套进 MojoExecutationException 后再抛出。
上述两种异常能够在 Mojo执行出错的时候提供一定的信息,但这往往是不够的,用户在 编写插件的时候还应该提供足够的日志信息,AbstractMojo 提供了一个 getlog()方法,用户可 以使用该方法获得一个 Log 对象。该对象支持四种级别的日志方法,它们从低到高分别为:
debug: 调试级别的日志
。Maven 默认不会输出该级别的日志,不过用户可以在执行 mvn 命令的时候使用 -X 参数开启调试日志,该级别的日志是用来帮助程序员了解 插件具体运行状态的,因此应该尽量详细。需要注意的是,不要指望你的用户会主 动去看该级别的日志。info: 消息级别的日志
。Maven 默认会输出该级别的日志,该级别的日志应该足够简 洁,帮助用户了解插件重要的运行状态。例如,maven-compiler-plugin 会使用该级别 的日志告诉用户源代码编译的目标目录。warn: 警告级别的日志
。当插件运行的时候遇到了一些问题或错误,不过这类问题
不会导致运行失败的时候,就应该使用该级别的日志警告用户尽快修复。error: 错误级别的日志
。当插件运行的时候遇到了 一 些问题或错误,并且这类 问 题 导 致 Mojo 无法继续运行 , 就应该使用该级别的日志提供详细的错误信息。
上述每个级别的日志都提供了三个方法。以 debug 为例,它们分别为:
- void debug(CharSequence content);
- void debug(CharSequence content,Throwable error);
- void debug(Throwable error);
用户在编写插件的时候,应该根据实际情况选择适应的方法。基本的原则是,如 果有异常出现,就应该尽量使用适宜的日志方法将异常堆栈记录下来,方便将来的问 题分析。
如果使用过Log4j 之类的日志框架,就应该不会对Maven 日志支持感到陌生,日志不是 一 个 Maven 插件的核心代码,但是为了方便使用和调试,完整的插件应该具备足够丰富的 日志代码。
6️⃣ 测试 Maven 插件
编写 Maven 插件的最后一步是对其进行测试,单元测试较之于一般的Maven 项目无异, 可以参考本系列前面的文章。手动测试 Maven 插件也是一种做法,读者可以将插件安装到本地仓库后,再找个项目测试该插件。本节要介绍的并非上述两种读者已经十分熟悉的测试方法, 而是如何编写自动化的集成测试代码来验证 Maven 插件的行为。
读者可以想象一下,既然是集成测试,那么就一定需要一个实际的Maven 项目,配置
该项日使用插件,然后在该项目上运行 Maven 构建,最后再验证该构建成功与否,可能还需要检查构建的输出。
既然有数以千计的 Maven 插件,那么很可能已经有很多人遇到过上述的需求,因此 Maven 社区有一个用来帮助插件集成测试的插件,它就是 maven-invoker-plugin 。 该插件能 够用来在一组项目上执行 Maven, 并检查每个项目的构建是否成功,最后,它还可以执行 BeanShell 或者 Groovy 脚本来验证项目构建的输出。
BeanShell 和 Groovy 都是基于JVM 平台的脚本语言,读者可以访问http://www.bean- shell.org/和 http://groovy.codehaus.org/以了解更多的信息。本章下面的内容会用到少许的 Groovy 代码,不过这些代码十分简单,很容易理解。
回顾一下前面的代码行统计插件,可以使用Archetype 创建一个最简单的 Maven 项目, 然后在该项目中配置 maven-loc-plugin。如果一切正常,就应该能够看到如下的 Maven 构建 输出:
[INFO]\src\main\java:13 lines of code in 1 files
[INFO]\src\test\java: 38 lines of code in 1 files
为了验证这一行为,先配置 maven-loc-plugin 的 POM使用 maven-invoker-plugin, 如代码所示。
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-invoker-plugin</artifactId>
<version>1.5</version>
<configuration>
<projectsDirectory>src/it</projectsDirectory>
<goals>
<goal>install</goal>
</goals>
<postBuildHookScript>validate.groovy</postBuildHookScript>
</configuration>
<executions>
<execution>
<id>integration-test</id>
<goals>
<goal>install</goal>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>
代码中maven-invoker-plugin 有三项配置。首先 projectDirectory 用来配置测试 项目的目录,也就是说在src/it目录下存放要测试的 Maven 项目源码;其次 goals 表示在测试项目上要运行的Maven 目标,这里的配置就表示maven-invoker-plugin 会在 src/it 目录下 的各个Maven项目中运行mvn install命令;最后的 postBuildHookScript 表示在测试完成后要 运行的验证脚本,这里是一个groovy 文件。
从代码中我们还看到,maven-invoker-plugin 的两个目标 install 和 run 被绑定 到了integration-test生命周期阶段。这里的 install 目标用来将当前的插件构建并安装到仓库 中供测试项目使用,run 目标则会执行定义好的 mvn命令并运行验证脚本。
当然仅仅该配置还不够,src/it 目录下必须有一个或者多个供测试的 Maven项目,我们 可以使用 maven-archetype-quickstart 创建一个项目并修改POM 使用mvn-loc-plugin, 如代码所示。该测试项目的其余代码不再赘述。
<project xmlns="http://maven.apache,org/PON/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/maven-v4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.xiaoshan</groupId>
<artifactId>app</artifactId>
<packaging>jar</packaging>
<version>1.0-SNAPSHOT</version>
<name>app</name>
<url>http://maven.apache.org</url>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactid>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>com.xiaoshan.mvnbook</groupId>
<artifactId>maven-loc-plugin</artifactId>
<version>0.0.1-SNAPSHOT</version>
<executions>
<execution>
<goals>
<goal>count</goal>
</goals>
<phase>verify</phase>
</execution>
</executiong>
</plugin>
</plugins>
</build>
</project>
上面代码就是一个最简单的 POM, 然后配置 maven-loc-plugin 的 count 目标绑定到了verify 生命周期阶段。
测试项目准备好了,现在要准备的是与该项目对应的验证脚本文件,即 validate.groovy,它应该位于 src/it/app 目录下(即上述测试项目的根目录), 内容如下代码所示。
def file =new File(basedir,'build.log')
def countNain = false
def countTest =false
file.eachLine {
if(it =~ /src.main.java:13 lines of code in 1 files/)
countMain =true
if(it =~ /src.test.java:38 lines of code in 1 files/)
countTest =true
}
if(!countMain)
throw new RuntimeException("incorrect src/main/java count info");
if(!countTest)
throw new RuntimeException("Incorrect src/test/java count info");
这段Groovy 代码做的事情很简单。它首先读取 app 项目目录下的 build.log 文件,当maven-invoker-plugin 构建测试项目的时候,会把mvn 输出保存到项目下 的 build.log 文件中。因此,可以解析该日志文件来验证 maven-loc-plugin 是否输出了正确的代码行信息。
上述 Groovy 代码首先假设没有找到正确的主代码统计信息和测试代码统计信息,然后 它逐行遍历日志文件,紧接着使用正则表达式检查寻找要检查的内容(两个斜杠//中间的内容是正则表达式,而=~表示寻找该正则表达式匹配的内容),如果找到期望的输出, 就 将 countMain 和 countTest 置为true 。 最后,如果这两个变量的值有 false, 就抛出对应的异常信息。
Maven 会首先在测试项目 app 上运行 mvn install 命令,如果运行成功,则再执行 validate.groovy 脚本。只有脚本运行通过且没有异常,集成测试才算成功。
现在在 maven-loc-plugin 下运行 mvn clean install, 就能看到如下的输出:
[INFO]---maven-invoker-plugin:1.5:install (integration-test)@maven-loc-plugin---
[INFO]Installing D:\ws-maven-book\maven-loc-plugin\pom.xm1 to D:\java \repository\com\xiaoshan\mvnbook\maven-loc-plugin\0.0.1-SNAPSHOT\maven-loc-plugin-0.0.1-SNAPSHOT.pom
[INFO]Installing D:\ws-maven-book\maven-loc-plugin\target\maven-loc-plugin- 0.0.1-SNAPSHOT.jar to D:\java\repository\com\xiaoshan\mvnbook\maven-1oc-plugin\0.0.1-SNAPSHOT\maven-loc-plugin-0.0.1-SNAPSHOT.jar
[INFO]
[INFO]---maven-invoker-plugin:1.5:run(integration-test)@maven-loc-plugin ---
[WARNING] Filtering of parent/child POMs is not supported without cloning the projects
[INFO] Building:app\pom.xml
[INFO]..SUCCESS (3.4 s)
[INFO]-------------------------------------------------
[INFO]Build Summary:
[INFO]Passed:1, Failed:0, Errora:0, Skipped:0
[INFO]-------------------------------------------------
从输出中可以看到 maven-invoker-plugin 的 install 目标将当前项目maven-loc-plugin 安装至本地仓库,然后它的 run 目标构建测试项目app, 并最后报告运行结果。
至此,所有 Maven 插件集成测试的步骤就都完成了。
上述样例只涉及了 maven-invoker-plugin 的很少一部分配置点,用户还可以配置:
debug (boolean)
: 是否在构建测试项目的时候开启 debug 输出。settingsFile(File)
: 执行集成测试所使用的 settings.xml, 默认为本机环境settings.xml。localRepositoryPath(File)
: 执行集成测试所使用的本地仓库,默认就是本机环境仓库。preBuildHookScript (String)
: 构建测试项目之前运行的 BeanShell或 Groovy 脚本。postBuildHookScript(String)
: 构建测试项目之后运行的 BeanShell 或 Groovy 脚本。
要了解更多的配置点,或者查看更多的样例。读者可以访问 maven-invoker-plugin 的站点:http://maven.apache.org/plugins/maven-invoker-plugin/
。
🌾 总结
Maven 社区提供了成百上千的插件供用户使用,这些插件能够满足绝大部分用户的需求。然而,在极少数的情况下,用户还是需要编写 Maven 插件来满足自己非常特殊的需求。 编写 Maven 插件的一般步骤包括创建一个插件项目、编写Mojo 、为 Mojo提供配置点、实现 Mojo 行为、处理错误、记录日志和测试插件等。本章实现了一个简单的代码行统计插件, 并逐步展示了上述步骤。用户在编写自己插件的时候,还可以参考本章描述的各种 Mojo标注 、Mojo 参数、异常类型和日志接口。最后介绍了如何使用maven-invoker-plugin 实现插件的自动化集成测试。