Maven外掛開發教程

御狐神發表於2022-01-10
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作為專案模板；

    建立專案1

  • Idea中輸入專案名稱，點選確認；

    建立專案2

  • 最後一步，點選Finish按鈕，完成專案的建立；

    建立專案3

通過以上步驟，我們建立了一個空的Maven外掛專案，這個專案目前沒有任何程式碼。

外掛專案分析

通過上述步驟，我們建立好了一個空的Maven專案，專案的目錄如下所示：

![建立專案4]maven-plug-step4-2022-01-10-10-29-59

自動生成的專案POM檔案內容如下所示，其中有以下幾點比較關鍵：

  1. packaging：普通Java專案的packaging是jar/war/pom，但是Maven外掛專案的packaging是maven-plugin；
  2. maven-plugin-api：Maven外掛專案依賴了maven-plugin-api包，這是Maven外掛專案必須依賴的核心包；
<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>org.demo.test</groupId>
  <artifactId>demo-test-maven-plug</artifactId>
  <packaging>maven-plugin</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>demo-test-maven-plug Maven Mojo</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-plugin-api</artifactId>
      <version>2.0</version>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

自動生成的專案中還包含一個Java檔案，內容如下所示，這個Java檔案有幾個特點：

  1. 生成的類繼承了AbstractMojo，這裡是Maven外掛的規範要求，Maven外掛必須要繼承AbstractMojo並抽象的execute方法；
  2. 類與方法上有一些Tag，如@goal。Tag和註解不同，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如下所示：

<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>org.demo.test</groupId>
    <artifactId>demo-test-maven-plugin</artifactId>
    <packaging>maven-plugin</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>demo-test-maven-plug Maven Mojo</name>
    <url>http://maven.apache.org</url>

    <dependencies>
        <dependency>
            <groupId>org.apache.maven</groupId>
            <artifactId>maven-plugin-api</artifactId>
            <version>3.8.3</version>
        </dependency>
        <dependency>
            <groupId>org.apache.maven.plugin-tools</groupId>
            <artifactId>maven-plugin-annotations</artifactId>
            <version>3.6.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-plugin-plugin</artifactId>
                <version>3.6.1</version>
            </plugin>
        </plugins>
    </build>
</project>

新增自定義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：goal1和goal2，接下來，我們把外掛專案編譯併發布，編譯和釋出的步驟此處不做詳細介紹。

專案編譯釋出好之後，我們在另外一個專案的POM中引入該外掛：

    <build>
        <plugins>
            <plugin>
                <groupId>org.demo.test</groupId>
                <artifactId>demo-test-maven-plugin</artifactId>
                <version>1.0-SNAPSHOT</version>
            </plugin>
        </plugins>
    </build>
  • 在專案的命令列執行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 = "<goal-name>",
       aggregator = <false|true>, 
       configurator = "<role hint>",
       // 執行策略
       executionStrategy = "<once-per-session|always>",
       inheritByDefault = <true|false>,
       // 例項化策略
       instantiationStrategy = InstantiationStrategy.<strategy>,
       // 如果使用者沒有在POM中明確設定此Mojo繫結到的phase，那麼繫結一個MojoExecution到那個phase
       defaultPhase = LifecyclePhase.<phase>,
       requiresDependencyResolution = ResolutionScope.<scope>,
       requiresDependencyCollection = ResolutionScope.<scope>,
       // 提示此Mojo需要被直接呼叫（而非繫結到生命週期階段）
       requiresDirectInvocation = <false|true>,
       // 提示此Mojo不能在離線模式下執行
       requiresOnline = <false|true>,
       // 提示此Mojo必須在一個Maven專案內執行
       requiresProject = <true|false>,
       // 提示此Mojo是否執行緒安全，執行緒安全的Mojo支援在並行構建中被併發的呼叫
       threadSafe = <false|true> ) // (since Maven 3.0)
 
// 何時執行此Mojo
@Execute( goal = "<goal-name>",           // 如果提供goal，則隔離執行此Mojo
          phase = LifecyclePhase.<phase>, // 在此生命週期階段自動執行此Mojo
          lifecycle = "<lifecycle-id>" )  // 在此生命週期中執行此Mojo
public class MyMojo
    extends AbstractMojo
{
    
    @Parameter( name = "parameter",
                // 在POM中可使用別名來配置引數
                alias = "myAlias",
                property = "a.property",
                defaultValue = "an expression, possibly with ${variables}",
                readonly = <false|true>,
                required = <false|true> )
    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 外掛開發實戰

本文最先發布至微信公眾號，版權所有，禁止轉載！

相關文章