Maven插件参数的用户属性是什么意思？

Question

我是一个Maven新手。 当我尝试查看任何Maven插件文档时，我总是看到以下格式的参数定义： 名称 描述 {参数名} {描述} 默认值为: ... 用户属性为: ...

对于大多数情况，我发现用户属性与参数名相同。 我想知道“用户属性”和“参数名”之间有什么区别。我认为参数名应该是指定相应插件的参数值时要使用的元素标记名称，但“用户属性”的用途是什么？

- Audison

Answer 1

注意：这是针对Maven 3的。早期版本有所不同。

简短版：

"User property"指定了可以用于设置插件参数的Maven属性的名称。 这允许从<configuration>部分之外配置插件。请注意，这仅在参数未在<configuration>部分中指定时才起作用（请参见MNG-4979-无法从命令行覆盖配置参数）。

Maven属性可以在POM的<properties>部分中设置，也可以在命令行上设置为-DmyProperty=myValue。

---

详细版

在Maven中，通常在POM中的<configuration>部分中设置插件的参数。插件文档中给出的“参数名称”是在配置设置中使用的名称。

例如，Surefire目标surefire:test具有一个参数“failIfNoSpecifiedTests”。要在POM中设置它，请使用：

<configuration>
<failIfNoSpecifiedTests>false</failIfNoSpecifiedTests>
</configuration>

然而，有时从<configuration>部分外部设置插件参数是很有用的，例如在命令行上设置插件参数或在Maven配置文件中。为了允许这样做，插件还可以声明它将从Maven属性（如果设置）中读取参数值。文档列出的这个属性就是用户属性。

failIfNoSpecifiedTests 的用户属性为 surefire.failIfNoSpecifiedTests。因此，可以使用属性 surefire.failIfNoSpecifiedTests 来代替上面的<configuration>部分。例如：

• 通过在命令行上指定 -Dsurefire.failIfNoSpecifiedTests=false
• 在POM配置文件的profile中：<properties> <surefire.failIfNoSpecifiedTests> false </surefire.failIfNoSpecifiedTests> ...

请注意，每个参数都必须由插件声明其对应的用户属性，因此并非所有参数都有用户属性。例如，参数 basedir 没有用户属性，因此不能在命令行上设置它。

---

在插件的源代码中，参数名称没有明确声明；它取自Java字段的名称。 "failIfNoSpecifiedTests" 的源代码如下：

/**
 * Set this to "true" to cause a failure if the none of the tests
 * specified in -Dtest=... are run. Defaults to "true".
 *
 * @since 2.12
 */
@Parameter( property = "surefire.failIfNoSpecifiedTests" )
private Boolean failIfNoSpecifiedTests;

你可以看到，参数名称“failIfNoSpecifiedTests”来自字段名称。注释参数“property”定义要使用的Maven属性。

- sleske

---

我想补充一下，命令行中提供的任何属性都会覆盖在 <properties /> pom 部分中定义的属性。因此，为了实现最大的灵活性，建议在 <properties /> 中指定默认用户属性值，可以在命令行上覆盖它们，而不是在 <configuration /> 部分中硬编码它们。例如，其中一个属性是 maven.compiler.source 和 maven.compiler.target。 - mucaho

@mucaho 更新编译器示例：为了最大程度的一致性，再次明确在<configuration/>中指定编译器版本，以便javadoc链接到正确的java api版本：<source>${maven.compiler.source}</source>和<target>${maven.compiler.target}</target>。 - mucaho

如果property未定义，用户属性将是什么？前缀从哪里派生？ - OrangeDog

@OrangeDog：听起来像是一个新问题。考虑到提供一些背景，将其作为一个新问题进行提问。 - sleske

@sleske，你差不多在这里回答了它，但是后来用了错误的例子。 - OrangeDog

抱歉，我不太明白你的问题。你是在指注释参数“property”吗？如果没有设置，那么就不会有“用户属性”可用于该设置，正如我所解释的那样。 - sleske

Answer 2

我想我可能已经得到了答案，但仍不能确定。答案在org.apache.maven.plugins.annotations包中的注释类型Parameter上。在此注释类型中，它定义了几个字段。其中：

1. 别名：这应该定义插件文档中的参数名称。
2. defaultValue：这定义了插件文档中每个参数指定的默认值。
3. property：这定义了用户属性。根据此字段的注释，据说可以从-D执行、设置属性或pom属性中指定此属性。
4. readonly：只读标志。
5. required：是否强制执行。

- Audison

Answer 3

它指的是属性适用的上下文。例如，有系统属性，如JVM版本、操作系统名称等，它们不是“用户属性”，因为用户不应该设置它们。请注意，这不是Maven特定的概念，而是Java处理与配置相关的各种信息的更一般的方式（即通常是进程运行的平台或上下文的特征）。 “用户属性”只是意味着用户，即运行Maven或配置Maven pom.xml的人，正在设置属性值。

- Rob

---

嗨，Robs，感谢你的回答。然而，从你的回答来看，“用户属性”应该是一个布尔值标志，指示它是否为真，但我在插件文档中看到的是一个字符串值。例如，插件tomcat7，目标deploy，它有一个参数mode，但它的用户属性是maven.tomcat.mode。 - Audison

这个答案是错误的。显然作者混淆了Maven属性和Java系统属性，可以使用System.getProperty() / System.setProperty()来操作Java系统属性。 - sleske

这种混淆是可以理解的，因为Maven属性是基于系统属性建模的；例如，所有系统属性都可以作为Maven属性使用，并且可以像系统属性一样在命令行上使用“-D”进行设置（只有对于系统属性，“-D”必须是JVM参数而不是Java参数）。 - sleske