Maven - 通过开发插件了解 Maven

谁借莪１个温暖的怀抱￠ 2022-06-10 07:25 202阅读 0赞

# Maven - 通过开发插件了解 Maven #

如果单纯看 Maven 的一些介绍或者用法，可能在看的时候知道了，过段时间可能就忘了。如果对 Maven 了解比较少，在使用过程中就可能会遇到很多坑，因此本文通过开发简单插件了解相关的多种信息，本文大部分内容来自官方文档。

官方文档：

> [https://maven.apache.org/guides/plugin/guide-java-plugin-development.html][https_maven.apache.org_guides_plugin_guide-java-plugin-development.html]

## 命名要求 ##

为了后面使用插件更方便，或者你使用其他人插件遇到问题的时候，都可以先看看，这个插件的名字是否符合要求。

通常第三方插件命名要求为：`<yourplugin>-maven-plugin`

Maven 官方的插件命名为：`maven-<yourplugin>-plugin`，也就是 maven 和 yourplugin 位置不同，虽然这两种命名方式在后续使用都很方便，但是特别要注意，**使用这个命名模式是侵犯 Apache Maven商标的。**

## 开始你的第一个插件 ##

修改下面命令中具体的参数值，注意命名要求，在一行中执行：

mvn archetype:generate \
      -DgroupId=sample.plugin \
      -DartifactId=hello-maven-plugin \
      -DarchetypeGroupId=org.apache.maven.archetypes \
      -DarchetypeArtifactId=maven-archetype-plugin

例如我这里执行的：

mvn archetype:generate -DgroupId=tk.mybatis -DartifactId=mybatis-maven-plugin -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-plugin

命令执行后，会下载一些相关的pom和jar，部分日志如下：

[INFO] Using property: groupId = tk.mybatis
    [INFO] Using property: artifactId = mybatis-maven-plugin
    Define value for property 'version' 1.0-SNAPSHOT: :
    [INFO] Using property: package = tk.mybatis
    Confirm properties configuration:
    groupId: tk.mybatis
    artifactId: mybatis-maven-plugin
    version: 1.0-SNAPSHOT
    package: tk.mybatis
     Y: : y
    [INFO] ----------------------------------------------------------------------------
    [INFO] Using following parameters for creating project from Archetype: maven-archetype-plugin:1.2
    [INFO] ----------------------------------------------------------------------------
    [INFO] Parameter: groupId, Value: tk.mybatis
    [INFO] Parameter: artifactId, Value: mybatis-maven-plugin
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: tk.mybatis
    [INFO] Parameter: packageInPathFormat, Value: tk/mybatis
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] Parameter: package, Value: tk.mybatis
    [INFO] Parameter: groupId, Value: tk.mybatis
    [INFO] Parameter: artifactId, Value: mybatis-maven-plugin
    [INFO] Project created from Archetype in dir: F:\Liu\Git\plugin\mybatis-maven-plugin
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 16.113 s
    [INFO] Finished at: 2017-08-07T21:48:41+08:00
    [INFO] Final Memory: 14M/182M
    [INFO] ------------------------------------------------------------------------

此时我们得到了下面结构的一个项目：

mybatis-maven-plugin
        │  pom.xml
        │
        └─src
            ├─it
            │  │  settings.xml
            │  │
            │  └─simple-it
            │          pom.xml
            │          verify.groovy
            │
            └─main
                └─java
                    └─tk
                        └─mybatis
                                MyMojo.java

将这个项目导入到你常用的IDE中，例如IDEA（或Eclipse）。

### 一个简单的 Mojo ###

使用上面方式创建后，会自动生成一个简单的 Mojo，代码如下：

/** * Goal which touches a timestamp file. * * @deprecated Don't use! */
    @Mojo(name = "touch", defaultPhase = LifecyclePhase.PROCESS_SOURCES)
    public class MyMojo extends AbstractMojo { 
        /** * Location of the file. */
        @Parameter(defaultValue = "${project.build.directory}",
                property = "outputDir", required = true)
        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
                    }
                }
            }
        }
    }

`@Mojo` 注解中 `name` 属性定义的就是 goal。`defaultPhase` 定义了 goal 执行的阶段。

在打包插件前，我们需要特别注意 pom.xml 中的插件配置，在 maven-plugin-plugin 中：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-plugin-plugin</artifactId>
    <version>3.2</version>
    <configuration>
      <goalPrefix>mybatis-maven-plugin</goalPrefix>
      <skipErrorNoDescriptorsFound>true</skipErrorNoDescriptorsFound>
    </configuration>
    <executions>
      <execution>
        <id>mojo-descriptor</id>
        <goals>
          <goal>descriptor</goal>
        </goals>
      </execution>
      <execution>
        <id>help-goal</id>
        <goals>
          <goal>helpmojo</goal>
        </goals>
      </execution>
    </executions>
    </plugin>

自动生成的配置中，有一个属性 `goalPrefix`，这个属性用于配置插件的缩写名，默认情况下，符合前面命名要求的时候，不配置 `goalPrefix` 时，这里的默认值是 `mybatis`，由于自动生成了这个属性，导致缩写名不符合我们想要的结果了，所以这里可以去掉这个属性，或者直接将值改为 `mybatis`。

该插件 goal 中的 `descriptor` 可以根据文档注释生成相关的文档信息。`helpmojo` 可以自动给当前的插件生成一个名为 `help` 的 goal，配合这俩 goal 可以自动生成插件的文档信息。

使用 `mvn install` 将插件打包到本地仓库，然后在对应的 groupId 目录下面会有 maven-metadata-local.xml 文件，其中的内容为：

<?xml version="1.0" encoding="UTF-8"?>
    <metadata>
      <plugins>
        <plugin>
          <name>mybatis-maven-plugin Maven Plugin</name>
          <prefix>mybatis</prefix>
          <artifactId>mybatis-maven-plugin</artifactId>
        </plugin>
      </plugins>
    </metadata>

### 执行 Mojo ###

想要执行插件，就需要在 build > plugins 中配置 plugin，在一个 maven 项目中配置如下：

<plugin>
        <groupId>tk.mybatis</groupId>
        <artifactId>mybatis-maven-plugin</artifactId>
        <version>1.0-SNAPSHOT</version>
    </plugin>

添加插件后，想要执行，还需要使用下面的命令：

`mvn groupId:artifactId:version:goal`

针对上面这个插件，执行的命令如下：

`mvn tk.mybatis:mybatis-maven-plugin:1.0-SNAPSHOT:touch`

### 缩短命令 ###

上面命令需要输入挺长的内容，需要手动输入时不方便，我们可以通过下面几种方式来缩短输入的命令。

1.  省略版本号，当没有版本号时，maven 会使用最新版本的插件执行。
2.  提前给插件配置一个缩写的前缀，如 `mvn mybatis:touch`，如果你插件符合前面要求的命名规则，那么插件直接就支持（注意上面提到的 `goalPrefix`）。
3.  你还可以在 settings.xml 中配置 pluginGroups ，这样在命令中就可以省略 `groupId` 部分，**另外就是使用其他第三方插件时，可能会下载不下来其他 groupId 的插件，配置这个也能解决**。
    
        <pluginGroups>
         <pluginGroup>tk.mybatis</pluginGroup>
        </pluginGroups>

### 将 Mojo 附加到项目构建的生命周期中 ###

像上面那样添加 `<plugin>` 后，只是可以通过命令方式调用了，如果想要在执行 clean,install,package 等阶段时自动执行插件，就需要通过下面的方式将插件附加到某个生命周期上。

<plugin>
        <groupId>tk.mybatis</groupId>
        <artifactId>mybatis-maven-plugin</artifactId>
        <version>1.1</version>
        <executions>
            <execution>
                <goals>
                    <goal>touch</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

定义 Mojo 的时候设置了默认的阶段，想要修改绑定的阶段可以在 execution 中绑定：

<execution>
      <phase>install</phase>
      <goals>
        <goal>touch</goal>
      </goals>
    </execution>

这样修改以后，只有在 install 阶段才会触发这个插件的执行。

插件中配置的属性，可以通过在`<plugin>`下面添加 `configuration` 进行配置，例如：

同时还可以在执行的时候，通过`-D`进行设置，例如：

`mvn mybatis:touch -DoutputDir=f:\`

**注意：**  
1. 前一种 `configuration`优先级高于 `-D` 方式。  
2. 这里的 `outputDir` 是前面代码中 `@Parameter` 注解配置的 `property` 属性。

通过上面这个简单的插件，我们应该能了解 maven 内部和插件的一些简单信息，如果你需要更多有关Maven的文档，可以查看下面的链接。

插件开发：

[https://maven.apache.org/guides/plugin/guide-java-plugin-development.html][https_maven.apache.org_guides_plugin_guide-java-plugin-development.html]

[https://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html][https_maven.apache.org_guides_introduction_introduction-to-plugin-prefix-mapping.html]

插件配置：

[https://maven.apache.org/guides/mini/guide-configuring-plugins.html][https_maven.apache.org_guides_mini_guide-configuring-plugins.html]

生命周期：

[https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html][https_maven.apache.org_guides_introduction_introduction-to-the-lifecycle.html]

项目源码：

> 链接：[http://pan.baidu.com/s/1o8eD4FK][http_pan.baidu.com_s_1o8eD4FK] 密码：upxw

[https_maven.apache.org_guides_plugin_guide-java-plugin-development.html]: https://maven.apache.org/guides/plugin/guide-java-plugin-development.html
[https_maven.apache.org_guides_introduction_introduction-to-plugin-prefix-mapping.html]: https://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html
[https_maven.apache.org_guides_mini_guide-configuring-plugins.html]: https://maven.apache.org/guides/mini/guide-configuring-plugins.html
[https_maven.apache.org_guides_introduction_introduction-to-the-lifecycle.html]: https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html
[http_pan.baidu.com_s_1o8eD4FK]: http://pan.baidu.com/s/1o8eD4FK