构建与依赖 / 系统课时

使用 help:describe 查看插件

使用 help:describe 查看插件

遇到陌生 Maven 插件时,不必先猜参数名或翻网页。help:describe 可以直接从插件描述信息中列出目标、参数、默认值和用户属性;指定 goal 与 detail 后,还能把输出收缩到某一个目标,适合排查“这个参数到底能不能这样配”。

学习目标

  • 用插件前缀或完整坐标查看插件包含哪些目标。
  • 用 -Dgoal 与 -Ddetail 查看单个目标的可配置参数和默认值。
  • 固定插件版本并把帮助结果输出到文件,避免不同环境解析到不同版本。

先查看插件有哪些目标

先查询 Maven Help Plugin 自己。-Dplugin 支持插件前缀,也支持 groupId:artifactId 或 groupId:artifactId:version;为了让结果可复现,这里直接指定版本 3.5.2。

bash
mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin:3.5.2

预期输出(关键片段):

text
Group Id: org.apache.maven.plugins
Artifact Id: maven-help-plugin
Version: 3.5.2
Goal Prefix: help

继续向下会看到该插件的各个 goal,例如 help:describe、help:effective-pom 和 help:evaluate。如果只是想确认“插件能做什么”,先跑这一层就够了,不必一开始就输出所有参数。

针对单个目标展开参数

要查 describe 这个 goal 能接收哪些参数,加上 -Dgoal=describe -Ddetail。detail 是布尔参数,不写时默认是 false。

bash
mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin:3.5.2 -Dgoal=describe -Ddetail

预期输出(关键片段):

text
help:describe

Available parameters:

detail (Default: false)
  User property: detail

goal
  User property: goal

排查配置时重点看三类信息:参数名决定 POM 中 <configuration> 的元素名,User property 决定能否用 -D属性名=值 从命令行传入,Default 则告诉你未配置时 Maven 会采用什么值。没有显示默认值的参数,不要自行假设存在默认值。

用完整坐标避免版本歧义

mvn help:describe ... 中的 help 是插件前缀,执行哪个 Help Plugin 版本仍受当前 Maven 环境和项目插件管理影响。如果团队文档需要完全可复现,可以把执行 Help Plugin 本身也写成完整 goal 坐标。

bash
mvn org.apache.maven.plugins:maven-help-plugin:3.5.2:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin:3.5.2 -Dgoal=describe -Ddetail

预期输出(关键片段):

text
Version: 3.5.2
help:describe
Available parameters:

这种写法虽然更长,但能同时固定“执行帮助命令的插件版本”和“被查询插件的版本”。当 CI、教学文档或团队成员使用不同 Maven 版本时,优先用完整坐标更容易复现同一份帮助信息。

把帮助结果输出到文件

参数很多时,终端里翻找不方便,可以用 -Doutput 把结果写到文件。下面查询 Maven Enforcer Plugin 3.6.3 的 enforce goal,并保存为 plugin-help.txt。

bash
mvn org.apache.maven.plugins:maven-help-plugin:3.5.2:describe -Dplugin=org.apache.maven.plugins:maven-enforcer-plugin:3.6.3 -Dgoal=enforce -Ddetail -Doutput=plugin-help.txt

预期输出(控制台关键结果):

text
[INFO] BUILD SUCCESS

随后打开 plugin-help.txt,应能找到 enforcer:enforce、Available parameters 等内容。真实项目里可以把目标插件版本替换成 POM 中实际使用的版本;如果帮助信息与网上文章冲突,以当前构建使用版本的 help:describe 输出为准。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 help:describe 查看插件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通