Maven插件开发教程

Maven是一个一个优秀的项目管理开源框架,其插件机制为其功能扩展提供了非常大的便捷性。大多数情况下,我们不需要自己开发Maven插件,因为Maven本身提供了很多便捷的官方插件。但是对于某些特殊场景和特殊需求,开发一个自定义的Maven插件能大大提高开发效率。本文以一个简单的例子,展示如何创建一个自定义的Maven插件。

Maven插件开发

本文会以一个自制的Maven插件为例,展示如何使用Idea从0开始构建自制的Maven插件。

Maven插件目标

Maven本质是一个插件执行框架,所有的工作都是通过插件完成的。包括常见的命令如install/clean/deploy/compiler这些命令,其实底层都是一个一个的Maven插件的执行结果。

插件目标:开发一个自制的Maven插件,插件名称叫demo-test-maven-plugin,该插件包含两个Goal:

  1. goal1:执行命令mvn demo-test:goal1,控制台输出This is goal1.
  2. goal2:执行命令mvn demo-test:goal2,向控制台输出This is goal2.

插件项目命名

在开发Maven插件之前,第一件事是确定插件项目名称。Maven插件有特定的命名规范,命名规范分为两种类型:

  • 官方插件项目命名规范:maven-xxx-plugin,其中插件名为xxx,在Maven中可以使用命令mvn xxx调用插件;
  • 自定义插件项目命名规范:xxx-maven-plugin,其中插件名为xxx,在Maven中可以使用命令mvn xxx调用插件;

我们的插件是自定义插件,插件名为demo-test,所以插件的项目名称为demo-test-maven-plugin

建立插件项目

确定好建立的项目名称为demo-test-maven-plug之后,我们就可以去实际创建一个项目。本节以Idea作为工具,介绍如何建立一个Maven插件项目。

  • Idea中新建Maven项目,并选择org.apache.maven.archetypes:maven-archetype-mojo作为项目模板;

    Maven插件开发教程_第1张图片

  • Idea中输入项目名称,点击确认;

    Maven插件开发教程_第2张图片

  • 最后一步,点击Finish按钮,完成项目的创建;

    Maven插件开发教程_第3张图片

通过以上步骤,我们创建了一个空的Maven插件项目,这个项目目前没有任何代码。

插件项目分析

通过上述步骤,我们创建好了一个空的Maven项目,项目的目录如下所示:

![创建项目4]Maven插件开发教程_第4张图片

自动生成的项目POM文件内容如下所示,其中有以下几点比较关键:

  1. packaging:普通Java项目的packaging是jar/war/pom,但是Maven插件项目的packaging是maven-plugin;
  2. maven-plugin-api:Maven插件项目依赖了maven-plugin-api包,这是Maven插件项目必须依赖的核心包;

  4.0.0
  org.demo.test
  demo-test-maven-plug
  maven-plugin
  1.0-SNAPSHOT
  demo-test-maven-plug Maven Mojo
  http://maven.apache.org
  
    
      org.apache.maven
      maven-plugin-api
      2.0
    
    
      junit
      junit
      3.8.1
      test
    
  

自动生成的项目中还包含一个Java文件,内容如下所示,这个Java文件有几个特点:

  1. 生成的类继承了AbstractMojo,这里是Maven插件的规范要求,Maven插件必须要继承AbstractMojo并抽象的execute方法;
  2. 类与方法上有一些Tag,如@goalTag和注解不同,Tag会出现在相关文档中;
  3. Tag @goal的作用是指定插件的命名,如命令mvn clean中,clean就是@goal;
  4. Tag @phase的作用是绑定插件执行的生成周期,如clean周期,那么在执行mvn clean时会自动触发插件;
  5. Tag @parameter用来指定插件的参数。
Tag机制有很多问题,如没有语法报错等,Maven为什么会使用Tag而不是注解呢呢?这是因为Java早期不支持注解,JDK1.5才开始添加注解功能。Maven开发之初没有注解,所以只能使用Tag来代替,新版本的Maven中已经可以使用注解来代替Tag。
package org.demo.test;

import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;

import java.io.File;
import java.io.FileWriter;
import java.io.IOException;

/**
 * Goal which touches a timestamp file.
 *
 * @goal touch
 * 
 * @phase process-sources
 */
public class MyMojo
    extends AbstractMojo
{
    /**
     * Location of the file.
     * @parameter expression="${project.build.directory}"
     * @required
     */
    private File outputDirectory;

    public void execute()
        throws MojoExecutionException
    {
        File f = outputDirectory;

        if ( !f.exists() )
        {
            f.mkdirs();
        }

        File touch = new File( f, "touch.txt" );

        FileWriter w = null;
        try
        {
            w = new FileWriter( touch );

            w.write( "touch.txt" );
        }
        catch ( IOException e )
        {
            throw new MojoExecutionException( "Error creating file " + touch, e );
        }
        finally
        {
            if ( w != null )
            {
                try
                {
                    w.close();
                }
                catch ( IOException e )
                {
                    // ignore
                }
            }
        }
    }
}

修改项目POM

默认的POM版本比较老,功能缺失,所以在开发之前需要修改自动生成项目中的POM:

  1. 升级maven-plugin-api包版本到3.8.3。自动生成POM的版本是低版本的2.0;
  2. 添加maven-plugin-annotations依赖,这个包内包含了Maven相关的注解,可以取代Tag;
  3. 添加maven-plugin-plugin插件依赖,这个包可以使插件支持JDK1.8以上的版本;

修改之后的POM如下所示:


    4.0.0
    org.demo.test
    demo-test-maven-plugin
    maven-plugin
    1.0-SNAPSHOT
    demo-test-maven-plug Maven Mojo
    http://maven.apache.org

    
        
            org.apache.maven
            maven-plugin-api
            3.8.3
        
        
            org.apache.maven.plugin-tools
            maven-plugin-annotations
            3.6.1
        
    

    
        
            
                org.apache.maven.plugins
                maven-plugin-plugin
                3.6.1
            
        
    

添加自定义Mojo

开篇说过,本文项目中的插件需要两个goal:

  1. goal1:执行命令mvn demo-test:goal1,控制台输出This is goal1.
  2. goal2:执行命令mvn demo-test:goal2,向控制台输出This is goal2.

在Maven插件开发中,goal和Mojo类对应,所以我们也需要实现两个Mojo类,如下所示,和默认生成的Mojo类不同:

  1. @Mojo注解:定义插件相关的信息,如name表示goal的名称;
  2. @Parameter注解:指定插件运行时使用的参数,name是参数名,defaultValue是默认值;
@Mojo(name = "goal1")
public class Goal1Mojo extends AbstractMojo {

    @Parameter(name = "name", defaultValue = "test")
    private String name;

    public void execute() {
        getLog().info("This is goal1.");
    }
}

@Mojo(name = "goal2")
public class Goal2Mojo extends AbstractMojo {

    @Parameter(name = "name", defaultValue = "test")
    private String name;

    public void execute() {
        getLog().info("This is goal2.");
    }
}

插件的使用

通过上面的步骤,我们简单实现了一个Maven插件,插件的名称是demo-test,插件包含两个Goal:goal1goal2,接下来,我们把插件项目编译并发布,编译和发布的步骤此处不做详细介绍。

项目编译发布好之后,我们在另外一个项目的POM中引入该插件:

    
        
            
                org.demo.test
                demo-test-maven-plugin
                1.0-SNAPSHOT
            
        
    
  • 在项目的命令行执行mvn demo-test:goal1,可以看到以下输出:
[INFO] Scanning for projects...
[INFO] 
[INFO] ---------------------< com.example:javafx-spring >----------------------
[INFO] Building javafx-spring 0.0.1-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- demo-test-maven-plugin:1.0-SNAPSHOT:goal1 (default-cli) @ javafx-spring ---
[INFO] This is goal1.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.470 s
[INFO] Finished at: 2021-11-18T17:55:11+08:00
[INFO] ------------------------------------------------------------------------
  • 在项目的命令行执行mvn demo-test:goal2,可以看到以下输出:
[INFO] Scanning for projects...
[INFO] 
[INFO] ---------------------< com.example:javafx-spring >----------------------
[INFO] Building javafx-spring 0.0.1-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- demo-test-maven-plugin:1.0-SNAPSHOT:goal2 (default-cli) @ javafx-spring ---
[INFO] This is goal2.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  0.540 s
[INFO] Finished at: 2021-11-18T17:57:46+08:00
[INFO] ------------------------------------------------------------------------

至此,我们的Maven插件已经开发完成,达到最开始设定的目的。

附录1:Maven注解详解

import org.apache.maven.execution.MavenSession;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecution;
import org.apache.maven.plugin.descriptor.PluginDescriptor;
import org.apache.maven.plugins.annotations.Component;
import org.apache.maven.plugins.annotations.Execute;
import org.apache.maven.plugins.annotations.InstantiationStrategy;
import org.apache.maven.plugins.annotations.LifecyclePhase;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import org.apache.maven.plugins.annotations.ResolutionScope;
import org.apache.maven.project.MavenProject;
import org.apache.maven.settings.Settings;
 
       // 此Mojo对应的目标的名称
@Mojo( name = "",
       aggregator = , 
       configurator = "",
       // 执行策略
       executionStrategy = "",
       inheritByDefault = ,
       // 实例化策略
       instantiationStrategy = InstantiationStrategy.,
       // 如果用户没有在POM中明确设置此Mojo绑定到的phase,那么绑定一个MojoExecution到那个phase
       defaultPhase = LifecyclePhase.,
       requiresDependencyResolution = ResolutionScope.,
       requiresDependencyCollection = ResolutionScope.,
       // 提示此Mojo需要被直接调用(而非绑定到生命周期阶段)
       requiresDirectInvocation = ,
       // 提示此Mojo不能在离线模式下运行
       requiresOnline = ,
       // 提示此Mojo必须在一个Maven项目内运行
       requiresProject = ,
       // 提示此Mojo是否线程安全,线程安全的Mojo支持在并行构建中被并发的调用
       threadSafe =  ) // (since Maven 3.0)
 
// 何时执行此Mojo
@Execute( goal = "",           // 如果提供goal,则隔离执行此Mojo
          phase = LifecyclePhase., // 在此生命周期阶段自动执行此Mojo
          lifecycle = "" )  // 在此生命周期中执行此Mojo
public class MyMojo
    extends AbstractMojo
{
    
    @Parameter( name = "parameter",
                // 在POM中可使用别名来配置参数
                alias = "myAlias",
                property = "a.property",
                defaultValue = "an expression, possibly with ${variables}",
                readonly = ,
                required =  )
    private String parameter;
 
    @Component( role = MyComponentExtension.class,
                hint = "..." )
    private MyComponent component;
 
 
    @Parameter( defaultValue = "${session}", readonly = true )
    private MavenSession session;
 
    @Parameter( defaultValue = "${project}", readonly = true )
    private MavenProject project;
 
    @Parameter( defaultValue = "${mojoExecution}", readonly = true )
    private MojoExecution mojo;
 
    @Parameter( defaultValue = "${plugin}", readonly = true )
    private PluginDescriptor plugin;
 
    @Parameter( defaultValue = "${settings}", readonly = true )
    private Settings settings;
 
    @Parameter( defaultValue = "${project.basedir}", readonly = true )
    private File basedir;
 
    @Parameter( defaultValue = "${project.build.directory}", readonly = true )
    private File target;
 
    public void execute()
    {
    }
}

qrcode_for_gh_83670e17bbd7_344-2021-09-04-10-55-16

参考文章

【Maven】maven 插件开发实战

本文最先发布至微信公众号,版权所有,禁止转载!

你可能感兴趣的