Maven：编写Maven组件

一、编写Maven插件步骤 
在这里，我们就一个小的项目案例为大家演示一下如何一步一步编写Maven插件。该案例实现的功能是，统计Maven项目各个源代码目录下面文件的数量，以及它们加起来共多少代码。 
1.创建maven-plugin项目：插件本身也是Maven项目，特殊的地方在于它packaging必须是maven-plugin；使用maven-archetype-plugin快速创建一个Maven项目。 

C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources>mvn archetype:generate [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building Maven Stub Project (No POM) 1 [INFO] ------------------------------------------------------------------------ [INFO] [INFO] >>> maven-archetype-plugin:2.4:generate (default-cli) > generate-sources@ standalone-pom >>> [INFO] [INFO] <<< maven-archetype-plugin:2.4:generate (default-cli) < generate-sources@ standalone-pom <<< [INFO] [INFO] --- maven-archetype-plugin:2.4:generate (default-cli) @ standalone-pom --- [INFO] Generating project in Interactive mode ... ...  1713: remote -> us.fatehi:schemacrawler-archetype-plugin-dbconnector (-) 1714: remote -> us.fatehi:schemacrawler-archetype-plugin-lint (-) Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): 876: maven-archetype-plugin Choose archetype: 1: remote -> org.apache.maven.archetypes:maven-archetype-plugin (An archetype which contains a sample Maven plugin.) 2: remote -> org.apache.maven.archetypes:maven-archetype-plugin-site (An archetype which contains a sample Maven plugin site. This archetype can be layered upon  an existing Maven plugin project.) Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1 Choose org.apache.maven.archetypes:maven-archetype-plugin version: 1: 1.0 2: 1.1 3: 1.2 Choose a number: 3: 3 Define value for property 'groupId': : com.chengxiang.maven Define value for property 'artifactId': : maven-plugin Define value for property 'version':  1.0-SNAPSHOT: : Define value for property 'package':  com.chengxiang.maven: : maven-plugin Confirm properties configuration: groupId: com.chengxiang.maven artifactId: maven-plugin version: 1.0-SNAPSHOT package: maven-plugin  Y: : Y [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating project from Archetype: maven-archetype-plugin:1.2 [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: groupId, Value: com.chengxiang.maven [INFO] Parameter: artifactId, Value: maven-plugin [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: maven-plugin [INFO] Parameter: packageInPathFormat, Value: maven-plugin [INFO] Parameter: package, Value: maven-plugin [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: groupId, Value: com.chengxiang.maven [INFO] Parameter: artifactId, Value: maven-plugin [INFO] project created from Archetype in dir: C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\maven-plugin [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 02:31 min [INFO] Finished at: 2016-10-16T23:39:06+08:00 [INFO] Final Memory: 14M/172M [INFO] ------------------------------------------------------------------------

2.为插件编写目标、配置点和目标行为，处理相关错误日志：每个插件都包含一个或者多个目标，故必须提供一个或者多个继承AbstractMojo类；可视具体情况提供可配置的参数；根据具体目标实现execute()方法逻辑； 

/**  * CountMojo：每个插件的目标类都需要继承AbstractMojo，并实现execute()方法  * Created by chengxiang.peng on 2016/10/17.  * "@goal"：标注来写明自己的目标名称  * @goal count  */ public class CountMojo extends AbstractMojo {     //默认统计Java,xml和properties文件     private static final String[] INCLUDES_DEFAULT = {"java", "xml", "properties"};      /**      * "expression"：从系统属性读取这几个字段；"@readonly"：不允许用户进行配置      * 项目基础目录      * @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;     /**      * "@parameter"：使用该插件的时候，可以配置该参数      * 计算的代码行数的类型范围      * @parameter      */     private String[] includes;     public void execute() throws MojoExecutionException {         //如果没有配置类型范围，则使用默认的类型范围         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) {             //异常转译，将IO异常转换成Mojo定义的异常抛出             throw new MojoExecutionException("Unable to count lines of code.", e);         }     }     /**      * 统计指定目录下文件的代码行数      * @param dir 统计的指定目录      * @throws IOException 不处理IO异常，抛出给外部处理      */     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);         }         //输出统计结果：AbstractMojo的getLog()方法返回日志对象，输出Maven日志         String path = dir.getAbsolutePath().substring(basedir.getAbsolutePath().length());         getLog().info(path + ": " + lines + " lines of code in " + collected.size() + " files");     }     /**      * 遍历查找目标目录了中指定类型的文件，并保存在集合中      * @param collected 指定类型文件集合      * @param file 目标目录      */     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);             }         }     }     /**     * 统计指定文件的代码行数      * @param file 统计目标文件      * @return 代码行数      * @throws IOException 不处理IO异常，抛出给外部处理      */     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;     } }

3.上传和测试插件：适用mvn clean install命令，将编写完成的插件，上传在本地库中，然后在实际运行该插件验证其行为； 

C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin>mvn clean install [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building mavenplugin Maven Plugin 1.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ mavenplugin --- [INFO] Deleting C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin\target [INFO] [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ mavenplugin --- [INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] skip non existing resourceDirectory C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin\src\main\resources [INFO] [INFO] --- maven-compiler-plugin:3.1:compile (default-compile) @ mavenplugin --- [INFO] Changes detected - recompiling the module! [INFO] Compiling 1 source file to C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin\target\classes [INFO] [INFO] --- maven-plugin-plugin:3.2:descriptor (default-descriptor) @ mavenplugin --- [INFO] Using 'UTF-8' encoding to read mojo metadata. [INFO] Applying mojo extractor for language: java //Maven版本升级，@parameter expression="${property}"写法过时，可升级按照说明更新写法 [WARNING] mavenplugin.CountMojo#basedir: [WARNING]   The syntax [WARNING]     @parameter expression="${property}" [WARNING]   is deprecated, please use [WARNING]     @parameter property="property" [WARNING]   instead. [WARNING] mavenplugin.CountMojo#resources: [WARNING]   The syntax [WARNING]     @parameter expression="${property}" [WARNING]   is deprecated, please use [WARNING]     @parameter property="property" [WARNING]   instead. [WARNING] mavenplugin.CountMojo#sourceDirectory: [WARNING]   The syntax [WARNING]     @parameter expression="${property}" [WARNING]   is deprecated, please use [WARNING]     @parameter property="property" [WARNING]   instead. [WARNING] mavenplugin.CountMojo#testResources: [WARNING]   The syntax [WARNING]     @parameter expression="${property}" [WARNING]   is deprecated, please use [WARNING]     @parameter property="property" [WARNING]   instead. [WARNING] mavenplugin.CountMojo#testSourceDirectory: [WARNING]   The syntax [WARNING]     @parameter expression="${property}" [WARNING]   is deprecated, please use [WARNING]     @parameter property="property" [WARNING]   instead. [INFO] Mojo extractor for language: java found 1 mojo descriptors. [INFO] Applying mojo extractor for language: bsh [INFO] Mojo extractor for language: bsh found 0 mojo descriptors. [INFO] Applying mojo extractor for language: java-annotations [INFO] Mojo extractor for language: java-annotations found 0 mojo descriptors. [INFO] [INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ mavenplugin --- [INFO] Using 'UTF-8' encoding to copy filtered resources. [INFO] skip non existing resourceDirectory C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin\src\test\resources [INFO] [INFO] --- maven-compiler-plugin:3.1:testCompile (default-testCompile) @ mavenplugin --- [INFO] No sources to compile [INFO] [INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ mavenplugin --- [INFO] No tests to run. [INFO] [INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ mavenplugin --- [INFO] Building jar: C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin\target\mavenplugin-1.0-SNAPSHOT.jar [INFO] [INFO] --- maven-plugin-plugin:3.2:addPluginArtifactMetadata (default-addPluginArtifactMetadata) @ mavenplugin --- [INFO] //插件构建完毕后，上传到本地仓库后 [INFO] --- maven-install-plugin:2.4:install (default-install) @ mavenplugin --- [INFO] Installing C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin\target\mavenplugin-1.0-SNAPSHOT.jar to C:\Users\chengxiang.peng.QUNARSERVERS\.m2\repository\com\chengxiang\mavenplugin\1.0-SNAPSHOT\mavenplugin-1.0-SNAPSHOT.jar [INFO] Installing C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin\pom.xml to C:\Users\chengxiang.peng.QUNARSERVERS\.m2\repository\com\chengxiang\mavenplugin\1.0-SNAPSHOT\mavenplugin-1.0-SNAPSHOT.pom [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3.798 s [INFO] Finished at: 2016-10-17T17:54:56+08:00 [INFO] Final Memory: 20M/171M [INFO] ------------------------------------------------------------------------ 

在当前的项目目录下，执行编写插件的目标； 

C:\Users\chengxiang.peng.QUNARSERVERS\MavenSources\mavenplugin>mvn com.chengxiang:mavenplugin:1.0-SNAPSHOT:count [INFO] Scanning for projects... Downloading: http://svn.corp.qunar.com:8081/nexus/content/groups/public/com/chengxiang/mavenplugin/1.0-SNAPSHOT/maven-metadata.xml Downloading: http://l-digging7.wap.cn8.qunar.com:8086/content/repositories/thirdparty/com/chengxiang/mavenplugin/1.0-SNAPSHOT/maven-metadata.xml [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building mavenplugin Maven Plugin 1.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] //插件输出结果 [INFO] --- mavenplugin:1.0-SNAPSHOT:count (default-cli) @ mavenplugin --- [INFO] \src\main\java: 165 lines of code in 1 files [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 1.472 s [INFO] Finished at: 2016-10-17T18:17:31+08:00 [INFO] Final Memory: 7M/155M [INFO] ------------------------------------------------------------------------

二、Mojo标注

标注 

说明 

备注 

@goal<name> 

目标名称 

唯一必须声明；命令调用、POM配置插件时候使用； 

@phase<phase> 

目标绑定的生命周期阶段 

默认至Default阶段 

@requiresDependencyResolution<scope> 

运行目标前必须解析所有指定范围的依赖 

如maven-surefire-plugin的test带有@requiresDependencyResolution test标识在执行测试之前，所有测试范围的依赖都必须解析 

@requiresProject<true/false> 

目标是否必须在一个Maven项目中运行 

默认true，如maven-help-plugin的system目标，显示系统属性和环境变量，不需要实际项目 

@requiresDirectInvocation<true/false> 

目标只能通过命令调用 

默认为false，如果视图在POM中将其绑定到生命周期阶段，Maven就会报错 

@requiresOnline<true/false> 

是否要求Maven必须在线状态 

默认false 

@requiresReport<true/false> 

是否要求项目报告已经生成 

默认false 

@aggregator 

当在多模块项目运行时，标识䯮只会在顶层模块运行 

如maven-javadoc-plugin的aggregator-jar使用了该标注，多模块时只会在顶层项目生成一个聚合的javadoc文档 

@execute goal="<goal>" 

在运行目标前先让maven运行另外一个目标 

如果是本插件的目标，则直接使用目标名称，否则使用“prefix:goal”形式 

@execute phase="<phase>" 

在运行目标运行一个并行的生命周期，到指定的阶段为止。 

如maven-dependency-plugin的analyze使用了标注@execute phase="test-compile"，当执行dependency:analyze的时候，会首先执行default生命周期至test-compile阶段 

@execute lifecycle="<lifecycle>" phase="<phase>" 

运行目标之前先运行一个自定义的生命周期，到指定的阶段为止。 

如maven-surefire-report-plugin插件report目标，标注了@execute phase="test" lifecycle="surefire"，表示运行这个自定义的surefire生命周期至test阶段 

三、Mojo参数 
Maven支持种类多样的Mojo参数，如下： 
1.boolean(包括boolean和Boolean): 

/** *@parameter */ private boolean sampleBoolean; 配置： <sampleBoolean>true</sampleBoolean> 

2.int（包括Integer、long、Long、short、Short、byte、Byte）： 

/** *@parameter */ private int sampleInt; 配置： <sampleInt>8</sampleInt> 

3.float（包括Float、double、Double）： 

/** *@parameter */ private int sampleFloat; 配置： <sampleFloat>8.8</sampleFloat> 

4.String（包括StringBuffer、char、Character）： 

/** *@parameter */ private String sampleString; 配置： <sampleString>8</sampleString> 

5.Date（格式为yyy-MM-dd HH:mm:ss Sa） 

/** *@parameter */ private Date sampleDate; 配置： <sampleDate>2010-06-06 3:14:55.1 PM</sampleDate> 

6.File 

/** *@parameter */ private File sampleFile; 配置： <sampleFile>c:\tmp</sampleFile> 

7.URL 

/** *@parameter */ private URL sampleURL; 配置： <sampleURL>http://www.qunar.com</sampleURL> 

8.数组 

/** *@parameter */ private String[] includes; 配置： <includes>     <include>java</include>     <include>sql</include> </includes> 

9.Collection（任何实现Collection接口的类，如ArrayList和HashSet） 

/** *@parameter */ private List includes; 配置： <includes>     <include>java</include>     <include>sql</include> </includes>

10.Map 

/** *@parameter */ private Map sampleMap; 配置： <sampleMap>     <key>value1</key>     <key>value2</key> </sampleMap> 

11.Properties 

/** *@parameter */ private Properties sampleProperties; 配置： <sampleProperties>     <samplePropertie>         <name>p_name_1</name>         <value>p_value_1</value>     </samplePropertie>     <samplePropertie>         <name>p_name_2</name>         <value>p_value_2</value>     </samplePropertie> </sampleProperties> 

12.@parameter alias="<aliasName>" 
可以为任何Mojo参数使用别名，如： 

/** *@parameter alias="uid" */ private String uniqueIndentity; 配置： <uid>user_1</uid> 

13.@parameter expression="${aSystemProperty}" 
使用系统表达式对Mojo参数进行赋值，则无法在命令行直接配置，如： 

/** *@parameter expression="${maven.test.skip}" */ private boolean skip; 

14.@parameter defaultValue="aValue/${anExpression}" 
为用户设置的Mojo参数提供一个默认值，如： 

/** *@parameter defaultValue="true" */ private boolean sampleBoolean; 

15.@readonly 
Mojo参数是只读的，无法对其进行配置； 
16.required 
Mojo参数是必须的，没有配置该Mojo参数且没有默认值，Maven就会报错； 
四、错误处理和日志 
AbstractMojo实现Mojo接口，execute()方法定义如下： 
void execute() throws MojoExecutionException,MojoFailureException; 
    1.MojoExecutionException：显示“BUILD FAILURE”错误信息，表示Mojo运行时发现了预期的错误； 
    2.MojoFailureException：显示“BUILD ERROR”错误信息，表示Mojo运行时发现了未预期的错误； 
上述两种异常能够在Mojo执行出错的时候提供一定信息，但这往往是不够的。用户在编写插件的时候还应该提供足够的日志信息：AbstractMojo提供了一个getLog()方法，用户可以使用 
    1.debug：调试级别日志，默认不会输出，可以在执行mvn命令使用-X参数打开，帮助程序员了解插件具体运行状态，尽量详细； 
    2.info：消息级别日志，默认输出，简洁，了解插件重要运行状态； 
    3.warn：警告级别日志，插件运行时遇到了一些问题或错误，会导致运行失败，应该尽快修复； 
    4.error:错误级别日志，插件运行的遇到了一些问题或错误，导致Mojo无法继续运行，使用该级别日志提供详细的错误； 
上述级别的日志都提供了一个方法，以debug为例，分别为： 
    void debug(CharSequence content); 
    void debug(CharSequence content,Throwable error); 
    void debug(Throwable error); 
 

新技术，新未来！欢迎大家关注“1024工场”微信服务号，时刻关注我们的最新的技术讯息！（甭客气！尽情的扫描或者长按！）