【Maven】maven 插件開發實戰

時間 2020-03-31

標籤 Maven maven 插件開發實戰欄目 Maven 简体版

原文原文鏈接

<a name="lkFfi"></a>html

前言

衆所周知，maven 實質上是一個插件執行框架，全部的工做都是經過插件完成的。包括咱們平常使用到的相似 install、clean、deploy、compiler。。。這些命令，其實底層都是一個一個的 maven 插件。 java

<a name="Vqcuo"></a>git

如何開發本身的插件

<a name="YXV79"></a>github

1. maven 插件的命名規範

在寫一個項目以前，第一件事就是肯定一個名稱。maven 插件也不例外。它有着本身的一套命名規範。可是規範很簡單，一句話就能夠歸納，**官方插件命名的格式爲 maven-xxx-plugin,非官方的插件命名爲 xxx-maven-plugin 。**是否是以爲很眼熟，沒錯，spring boot starter 的命名也有相似的規範。 好的，咱們的第一個 maven 插件項目就叫 demo-maven-plugin 吧。 spring

<a name="GiT3p"></a>express

2. 建立項目

名稱起好了，下一步就是建立這個項目。若是你使用 idea 的話，那麼建立十分的便捷，按以下步驟便可： apache

<a name="KUkrj"></a>api

2.1 選擇 org.apache.maven.archetypes:maven-archetype-mojo 爲骨架建立項目

安全

選擇建立新項目
選擇經過 maven 建立
勾選 Create from archetype 經過項目骨架建立
選擇 org.apache.maven.archetypes:maven-archetype-mojo
點擊下一步

<a name="C6Bwv"></a>session

2.2 輸入在第一步起的項目名

點擊 Next

2.3 點擊 Finish 完成項目建立

2.4 分析項目文件

項目結構

能夠看到生成的項目就是咱們最最多見的 maven 項目的結構，生成的文件也不多，一個 pom.xml 文件，一個 MyMojo 文件，簡單介紹一下這兩個文件

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>cn.coder4j.study.example</groupId>
  <artifactId>demo-maven-plugin</artifactId>
  <packaging>maven-plugin</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>demo-mavne-plugin 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>

首先生成的項目 pom.xml 中，自動依賴了兩個項目，一個是 maven-plugin-api ，這個是開發 maven 插件必須依賴的核心包。另外一個是單元測試時使用的 junit 包。這兩個沒什麼要注意的，真正要注意的是這個項目的 packaging，一般我遇到的 packaging 都是 jar、war、pom，這裏比較特殊是 maven-plugin。

MyMojo.java

package cn.coder4j.study.example;

/*
 * Copyright 2001-2005 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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
                }
            }
        }
    }
}

首先生成的類繼承了 AbstractMojo 這個抽象類，這裏是 maven 插件的規範要求，maven 插件必需要繼承 AbstractMojo 並實現他的 execute 方法。 另外能夠看到類與方法使用了不少 tag。注意是 tag 而不是註解，註解是直接標記的，而 tag 是在文檔註釋裏面的。 其中 @goal 這個 tag 的做用是指定插件的命名，好比咱們經常使用的 mvn clean，這個 clean 就是他的 @goal 。 而 @phase 是綁定插件執行的生成周期，好比你綁定在 clean 這個週期，那你在執行 clean 的時候會自動觸發你的插件。 @parameter 用來指定插件的參數。 小朋友你是否有不少問號？tag 這個東西寫在文檔註釋裏面的東西，方即是方便可是容易寫錯呀，寫錯沒有語法報錯，寫對時候也沒有語法提示，爲何不直接用註解的形式呢？緣由是 java 的註解是 jdk1.5 以後纔有的，而實現 maven 的時候尚未這種語法。因此要一條路走到黑，一直背這個歷史包袱嗎？固然不是，後面咱們會說解決辦法。另外，這種寫法雖然不推薦使用了，可是有些 maven 的經典插件因爲完成時間比較早，熟悉這些 tag 對於理解代碼也有幫助。

3. 開發插件

3.1 代碼未動，依賴先行 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>cn.coder4j.study.example</groupId>
  <artifactId>demo-maven-plugin</artifactId>
  <packaging>maven-plugin</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>demo-mavne-plugin Maven Mojo</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-plugin-api</artifactId>
      <version>3.5.2</version>
    </dependency>
    <dependency>
      <groupId>org.apache.maven.plugin-tools</groupId>
      <artifactId>maven-plugin-annotations</artifactId>
      <version>3.5.2</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>

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

相較於默認的 pom.xml 文件，咱們作了以下幾個變更：

升級 maven-plugin-api 的插件版本到 3.5.2 。原生的 2.0 實在是太老了。
添加 maven-plugin-annotations 這個依賴，還記得上面說的 tag 的事嗎？有了這個依賴就能夠直接使用註解了
添加 maven-plugin-plugin 插件依賴，添加這個依賴主要是爲了在 jdk1.8 能編譯經過，不然會報錯

3.2 DemoMojo.java

/*
 *
 *  * *
 *  *  * blog.coder4j.cn
 *  *  * Copyright (C) 2016-2020 All Rights Reserved.
 *  *
 *
 */
package cn.coder4j.study.example;

import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;

/**
 * @author buhao
 * @version DemoMojo.java, v 0.1 2020-03-30 22:51 buhao
 */
@Mojo(name = "hello")
public class DemoMojo extends AbstractMojo {

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

    public void execute() throws MojoExecutionException, MojoFailureException {
        getLog().info("hello " + name);
    }
}

首先，同生成的類同樣，咱們的類必須繼承 AbstractMojo 並實現他的 execute 方法，而 execute 方法其實就是這個插件的入口類。 示例代碼中有兩個很重要的註解，一個是 @Mojo ，它主要用來定義插件相關的信息至關於上面說的 @goal ，其中 name 屬性用來指定這個插件名稱，同 clean 相似。 另一個重要註解 @Parameter ，則是用來指定插件運行時使用的參數，其中 name 是參數名，defaultValue 顧名思義是默認值，也就是在用戶沒有設置的時候使用的值。 詳細的插件及做用以下：

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()
    {
    }
}

回到示例上了，咱們這個插件做用很簡單，根據配置輸出 hello xxx，若是沒有配置就輸出 hello kiwi。咱們在寫插件時，固然不會這樣寫，可是經過這個 demo，你就掌握了 maven 插件的大部分知識，能夠本身作一些頗有趣的插件。

4. 使用插件

首先上面咱們的代碼寫完了，必需要 Install 一下，不然別的項目沒法直接依賴，若是你還想給其它人使用，那還需上傳到 maven 倉庫。

4.1 依賴插件

<build>
        <plugins>
            <plugin>
                <groupId>cn.coder4j.study.example</groupId>
                <artifactId>demo-maven-plugin</artifactId>
                <version>1.0-SNAPSHOT</version>
            </plugin>
        </plugins>
    </build>

在咱們想使用插件的項目中，添加如上配置，其中 plugin 中使用咱們插件的 GAV 信息。

4.2 啓動插件

若是上面配置的都正確，那麼在 idea 右側的 Maven 中，你配置的項目的 Plugins 下會多了一個 demo（具體根據你插件項目的名稱），而 demo 裏面會有一個 demo:hello，其中這個 demo 對應你插件項目的名稱，而 hello 對應你插件的名稱也就是 @Mojo 中的 name 。 好的，咱們雙擊一下，demo:hello ，會輸出以下日誌： 這樣，咱們的第一個 Maven 插件就行了。

4.3 配置參數

可能你還記得，咱們在寫 DemoMojo 的時候還指定了一個 name 屬性，而且爲它指定了一個 Parameter，這個如何使用。只要在依賴的插件下面添加 configuration 標籤就能夠了。

<build>
        <plugins>
            <plugin>
                <groupId>cn.coder4j.study.example</groupId>
                <artifactId>demo-maven-plugin</artifactId>
                <version>1.0-SNAPSHOT</version>
                <configuration>
                    <name>tom</name>
                </configuration>
            </plugin>
        </plugins>
    </build>

其中 configuration 標籤內的標籤，對應你定義的參數名稱，並且 idea 還有語法提示，很 nice。 好的，咱們再運行一下，結果以下： 好的，大功告成。