构建与依赖 / 系统课时
使用 help:describe 查看插件
使用 help:describe 查看插件
遇到陌生 Maven 插件时,不必先猜参数名或翻网页。help:describe 可以直接从插件描述信息中列出目标、参数、默认值和用户属性;指定 goal 与 detail 后,还能把输出收缩到某一个目标,适合排查“这个参数到底能不能这样配”。
学习目标
- 用插件前缀或完整坐标查看插件包含哪些目标。
- 用
-Dgoal与-Ddetail查看单个目标的可配置参数和默认值。 - 固定插件版本并把帮助结果输出到文件,避免不同环境解析到不同版本。
先查看插件有哪些目标
先查询 Maven Help Plugin 自己。-Dplugin 支持插件前缀,也支持 groupId:artifactId 或 groupId:artifactId:version;为了让结果可复现,这里直接指定版本 3.5.2。
mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin:3.5.2预期输出(关键片段):
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。
mvn help:describe -Dplugin=org.apache.maven.plugins:maven-help-plugin:3.5.2 -Dgoal=describe -Ddetail预期输出(关键片段):
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 坐标。
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预期输出(关键片段):
Version: 3.5.2
help:describe
Available parameters:这种写法虽然更长,但能同时固定“执行帮助命令的插件版本”和“被查询插件的版本”。当 CI、教学文档或团队成员使用不同 Maven 版本时,优先用完整坐标更容易复现同一份帮助信息。
把帮助结果输出到文件
参数很多时,终端里翻找不方便,可以用 -Doutput 把结果写到文件。下面查询 Maven Enforcer Plugin 3.6.3 的 enforce goal,并保存为 plugin-help.txt。
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预期输出(控制台关键结果):
[INFO] BUILD SUCCESS随后打开 plugin-help.txt,应能找到 enforcer:enforce、Available parameters 等内容。真实项目里可以把目标插件版本替换成 POM 中实际使用的版本;如果帮助信息与网上文章冲突,以当前构建使用版本的 help:describe 输出为准。