Maven Plugins

验证：未记录

适用版本: 未记录
验证范围: 尚未登记验证记录。

本文缩写（英文全称与中文含义）

缩写	英文全称／名称	中文含义
API	Application Programming Interface	应用程序编程接口
IDE	Integrated Development Environment	集成开发环境
JDK	Java Development Kit	Java 开发工具包
POM	Project Object Model	Maven 项目对象模型

Links#

https://maven.apache.org/plugins/
https://maven.apache.org/plugins/maven-compiler-plugin/
https://maven.apache.org/surefire/maven-surefire-plugin/
https://maven.apache.org/surefire/maven-failsafe-plugin/
https://maven.apache.org/enforcer/maven-enforcer-plugin/
https://www.mojohaus.org/versions/versions-maven-plugin/
https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html
https://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html

1. Important Points#

pluginManagement 只提供版本/配置默认值；需要执行的插件仍须在适用模块的 plugins 中启用或由 lifecycle 绑定。

plugin:
    Maven 中执行任务的扩展，例如 compile、test、shade、deploy

rule:
    declare plugin versions explicitly
    put shared versions/config in pluginManagement
    enable plugin in plugins only where needed

2. Compiler#

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.13.0</version>
  <configuration>
    <release>21</release>
  </configuration>
</plugin>

3. Unit Test#

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.2.5</version>
</plugin>

surefire:
    runs unit tests in test phase

4. Integration Test#

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <version>3.2.5</version>
  <executions>
    <execution>
      <goals>
        <goal>integration-test</goal>
        <goal>verify</goal>
      </goals>
    </execution>
  </executions>
</plugin>

failsafe:
    runs integration tests and fails build at verify

5. Enforcer#

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-enforcer-plugin</artifactId>
  <version>3.5.0</version>
  <executions>
    <execution>
      <id>enforce-build</id>
      <goals>
        <goal>enforce</goal>
      </goals>
      <configuration>
        <rules>
          <requireMavenVersion>
            <version>[3.9,)</version>
          </requireMavenVersion>
          <requireJavaVersion>
            <version>[21,)</version>
          </requireJavaVersion>
        </rules>
      </configuration>
    </execution>
  </executions>
</plugin>

6. Packaging Plugins#

Plugin	Use
`maven-jar-plugin`	normal jar metadata
`maven-war-plugin`	war package
`maven-shade-plugin`	fat jar with relocated classes
`maven-assembly-plugin`	custom distribution archive
`spring-boot-maven-plugin`	Spring Boot executable jar
`maven-source-plugin`	attach source jar for library consumers
`maven-javadoc-plugin`	attach API docs jar
`maven-deploy-plugin`	deploy artifact to remote repository
`maven-gpg-plugin`	sign release artifacts
`maven-toolchains-plugin`	select build JDK

7. Dependency Tools#

./mvnw dependency:tree
./mvnw dependency:analyze
./mvnw versions:display-dependency-updates
./mvnw versions:display-plugin-updates

dependency:analyze:
    finds used undeclared and unused declared dependencies

8. Resources#

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-resources-plugin</artifactId>
  <version>3.3.1</version>
  <configuration>
    <encoding>UTF-8</encoding>
  </configuration>
</plugin>

9. Flatten POM#

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>flatten-maven-plugin</artifactId>
  <version>1.6.0</version>
</plugin>

flatten:
    publishing library 时生成更干净的 consumer POM

10. Library Source And Javadoc#

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-source-plugin</artifactId>
  <version>3.3.1</version>
  <executions>
    <execution>
      <id>attach-sources</id>
      <goals>
        <goal>jar-no-fork</goal>
      </goals>
    </execution>
  </executions>
</plugin>

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.8.0</version>
  <executions>
    <execution>
      <id>attach-javadocs</id>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

source/javadoc jars:
    useful for IDE navigation and public library publishing

11. 在命令行直接执行插件 Goal#

Maven 插件本身是 Maven 可解析的构件（通常也是 JAR），一个插件可以提供多个 goal。mvn 调用的是插件的 goal，并不能用 插件名:任意方法名 执行普通依赖 JAR 中的 Java 方法。

写法	含义	示例
`mvn <phase>`	执行生命周期阶段及其之前的阶段	`mvn verify`
`mvn <prefix>:<goal>`	直接执行一个插件 goal	`mvn dependency:tree`
`mvn <groupId>:<artifactId>:<version>:<goal>`	用完整坐标指定插件和版本	`mvn org.jacoco:jacoco-maven-plugin:0.8.12:prepare-agent`

deploy:deploy-file 中，deploy 是 maven-deploy-plugin 的前缀，deploy-file 是 goal；它与生命周期阶段 deploy 不是同一条命令。短前缀需要 Maven 能解析到对应插件。需要固定插件版本或避免前缀解析歧义时，使用完整坐标；常用版本也可在项目 POM 中统一管理。

# 直接查看依赖树，不需要先运行 package
./mvnw dependency:tree

# 命令中的阶段和 goal 按书写顺序执行
./mvnw clean dependency:tree test

# 查看插件的 goal 与参数
./mvnw help:describe -Dplugin=org.apache.maven.plugins:maven-deploy-plugin -Dgoal=deploy-file -Ddetail

命令行用 -D参数名=值 传入 goal 支持的用户属性，具体参数以该 goal 的官方文档为准。直接调用 goal 不会自动补跑完整构建生命周期；例如单独运行 jacoco:prepare-agent 只准备测试 JVM 的 agent 参数，还需要后续运行测试和生成报告。发布已有 JAR 的完整 deploy:deploy-file 示例见 Release 章节，JaCoCo 示例见 Quality And Coverage 章节。