《Maven官方文件》外掛程式配置引導
阿新 • • 發佈：2018-12-23
原文地址 譯者:carvendy
介紹
外掛程式配置引導
1.通用配置
1.幫助目標
2.配置引數
1.匹配簡單物件
2.匹配複雜物件
3.匹配集合物件
1.匹配Lists
2.匹配Maps
3.匹配Poperties
2.配置構建外掛
1.使用 <executions>標籤
2.使用 <dependencies>標籤
3.使用 <inherited>標籤
3.配置報表外掛
1.使用 <reporting>標籤 對比 <build>標籤
2.使用 <reportSets>標籤
3.使用 ＜inherited＞標籤
介紹
在Maven，有構建和報表外掛：
- 構建外掛：在構建的時候執行，應該配置在<build/>標籤裡。
- 報表外掛：在生成網站時候執行，應該配置在<reporting/>標籤裡。
所有外掛至少需要的資訊： groupId ,artifactId 和 verion。
重要筆記：推薦定義每個版本外掛，來確保構建過程中可重用性。好的實踐就是在構建過程中指定它們到<build><pluginManagement/></build>節點內（通常，你會定義一個<pluginManagement/>的節點在父級的pom中）。對於報表外掛，你應該指定每個版本外掛到<reporting><plugins/></reporting>節點 （當然在<build><pluginManagement/></build>節點也是可以的）。
通用配置
maven外掛（構建和報表）配置在指定的<configuration>節點，<configuration>的子節點對映到了欄位，設定項，包括小咒語（記住一個外掛程式包括一個或多個Mojo,每個Mojo匹配一個目標）。舉個例子，我們有一個執行查詢特定URL、指定超時時間和一些選項的Mojo。這個Mojo看起來會像這樣：/**
* @goal query
*/
public class MyQueryMojo extends AbstractMojo {
/**
* @parameter expression="${query.url}"
*/
private String url;
/**
* @parameter default-value="60"
*/
private int timeout;
/**
* @parameter
*/
private String[] options;
public void execute() throws MojoExecutionException {
}
}
<project>... <build> <plugins> <plugin> <artifactId>maven-myquery-plugin</artifactId> <version>1.0</version> <configuration> <url>http://www.foobar.com/query</url> <timeout>10</timeout> <options> <option>one</option> <option>two</option> <option>three</option> </options> </configuration> </plugin> </plugins> </build> ... </project>當你看到這些節點配置與Mojo的欄位相匹配。配置機制中採取了類似於XStream的工作方式來匹配物件。所以從例子上你可以看到直接匹配的url節點和url欄位,timeout節點和欄位，options節點和欄位。這個匹配機制可以通過欄位的型別檢查來處理陣列，和確定是否合適匹配。
對於mojos預期被執行可以直接通過命令列，他們的引數提供配置的方式來替換pom中<configuration>的專案。這些外掛文件為了引數可以列到配置檔案的表示式中。在mojo之上，引數url與表示式${query.url}關聯起來了，意味著可以通過化工系統屬性指定query.url的值，如下：
mvn myquery:query -Dquery.url=http://maven.apache.org注意，系統屬性的名稱不一定引數的名稱匹配的mojo。雖然這是一個相當常見的做法，你會經常注意到外掛，採用了一些字首的系統屬性，以避免與其他系統屬性的名稱衝突。雖然很少，也有外掛引數，（如歷史原因）採用的系統屬性，這是完全無關的引數名。所以一定要仔細看看外掛文件。
幫助指令
最新的maven外掛通常有幫助目標在命令列中描述外掛，有引數型別和型別。例如，理解一下javadoc 目標,你就需要執行：- mvn javadoc:help -Ddetail -Dgoal=javadoc
配置引數
匹配簡單物件
匹配簡單型別，例如Boolean 或 Integer 這很簡單。在<configuration> 節點裡看是這樣的:<configuration> <myString>a string</myString> <myBoolean>true</myBoolean> <myInteger>10</myInteger> <myDouble>1.0</myDouble> <myFile>c:\temp</myFile> <myURL>http://maven.apache.org</myURL> </configuration>
配置複雜物件
匹配複雜型別在Maven當中也是相當直接的，讓我們，看一下小例子設定一個Person物件，在<configuration> 節點裡看是這樣的：<configuration> <myString>a string</myString> <myBoolean>true</myBoolean> <myInteger>10</myInteger> <myDouble>1.0</myDouble> <myFile>c:\temp</myFile> <myURL>http://maven.apache.org</myURL> </configuration>匹配複雜物件的規則如下： 一定要有私有欄位與節點對應。所以在我們的案例中，在mojo裡person節點一定匹配person物件的欄位。 物件例項化物件一定要和mojo在同一個包下。所以你的mojo在com.mycompany.mojo.query包中 匹配機制在包中找一個名叫person的物件。正如你是看到的機制 首字母為大寫的節點名字，然後去找這個物件例項化。 如果你希望例項化的這個物件在不同的包裡，有複雜的名字和你必須指定用implementation屬性，如下：
<configuration> <person> <firstName>Jason</firstName> <lastName>van Zyl</lastName> </person> </configuration></pre> </div> <div>
匹配集合型別
配置匹配機制很容易處理很多集合，現在就讓我們來看看例子吧：匹配Lists
匹配lists的工作就像匹配陣列一樣，你有一個list的節點就會匹配一個List。你需要的配置如下：public class MyAnimalMojo extends AbstractMojo{
/**
* @parameter
*/
private List animals;
public void execute() throws MojoExecutionException{
...
}
}
當你定義了一個animals的欄位，你的外掛程式配置如下：
<project>... <build> <plugins> <plugin> <artifactId>maven-myanimal-plugin</artifactId> <version>1.0</version> <configuration> <animals> <animal>cat</animal> <animal>dog</animal> <animal>aardvark</animal> </animals> </configuration> </plugin> </plugins> </build> ... </project>在每一個animals列出相應的欄位。不像陣列，集合不是指定成分型別。為了得到list各個專案的型別，策略使用如下： 1. 如果xml節點包含 implementation屬性，已經在使用了。 2.如果xml節點包含 一個”.”，試著用一個有資格的類名。 3.試著xml標籤（首字母大寫）作為一個類，配置一個相同包下面的物件。 4.如果節點沒有子節點，假定它是String型別。否則，配置失敗。
Mapping Maps
在相同的方式下，你可以定義map如下:/** * My Map. * * @parameter */ private Map myMap;
<configuration> <myMap> <key1>value1</key1> <key2>value2</key2> </myMap> </configuration>
Mapping Properties
Properties配置如下：/** * My Properties. * * @parameter */ private Properties myProperties;
<configuration> <myProperties> <property> <name>propertyName1</name> <value>propertyValue1</value> <property> <property> <name>propertyName2</name> <value>propertyValue2</value> <property> </myProperties> </configuration>
配置構建外掛
配置構建外掛只能在<build>節點使用<executions>標籤
你可以使用<executions>標籤配置一個mojo。mojos 在構建週期實踐中最常用到。使用MyQueryMojo作為一個例子，你可以看到一些如下：<project>... <build> <plugins> <plugin> <artifactId>maven-myquery-plugin</artifactId> <version>1.0</version> <executions> <execution> <id>execution1</id> <phase>test</phase> <configuration> <url>http://www.foo.com/query</url> <timeout>10</timeout> <options> <option>one</option> <option>two</option> <option>three</option> </options> </configuration> <goals> <goal>query</goal> </goals> </execution> <execution> <id>execution2</id> <configuration> <url>http://www.bar.com/query</url> <timeout>15</timeout> <options> <option>four</option> <option>five</option> <option>six</option> </options> </configuration> <goals> <goal>query</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ... </project>首先配置執行id “execution1” 配置繫結在測試周期。第二個執行沒有一個階段節點，你覺得它會執行什麼呢？好，指令都有一個預設繫結的階段作為依據。如果指令有一個繫結階段那麼它就會在這個節點執行。但是如果指令沒有繫結任何週期那麼它講不會在構建週期執行。 筆記中的pom中所有執行外掛的id都必須是唯一的，其實他們不必唯一因為通過poms的繼承分層。執行外掛同樣的id在不同的pom中匯被合併。相同的應用執行外掛可以被定義在profiles中。 如果我們配置多個執行外掛在不同的週期？你認為它會怎麼執行？讓我們再一次來看看pom的例子，但是我們應該繫結execution2到一個階段。
<project> ... <build> <plugins> <plugin> ... <executions> <execution> <id>execution1</id> <phase>test</phase> ... </execution> <execution> <id>execution2</id> <phase>install</phase> <configuration> <url>http://www.bar.com/query</url> <timeout>15</timeout> <options> <option>four</option> <option>five</option> <option>six</option> </options> </configuration> <goals> <goal>query</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ... </project>如果多個執行繫結不同的階段，mojo會在不同階段執行一次。意思就是，execution1 將會在測試階段執行，而execution2 會在build階段執行。 現在，讓我們看另外一個mojo的例子，看一下預設的繫結的階段。
/**
* @goal query
* @phase package
*/
public class MyBindedQueryMojo extends AbstractMojo {
/**
* @parameter expression="${query.url}";
*/
private String url;
/**
* @parameter default-value="60"
*/
private int timeout;
/**
* @parameter
*/
privateString[] options;
public void execute() throws MojoExecutionException {
}
}
從上面這個mojo的例子看，MyBindedQueryMojo 的預設週期是package階段（看看@phares 註解）。但是如果我們想執行這個mojo在安裝階段而不是package階段,我們應該使用<execution>下的<phase>表情 重新繫結mojo到一個新的週期。
<project> ... <build> <plugins> <plugin> <artifactId>maven-myquery-plugin</artifactId> <version>1.0</version> <executions> <execution> <id>execution1</id> <phase>install</phase> <configuration> <url>http://www.bar.com/query</url> <timeout>15</timeout> <options> <option>four</option> <option>five</option> <option>six</option> </options> </configuration> <goals> <goal>query</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ... </project>現在，MyBindedQueryMojo 預設週期已經被重寫成 install階段了 筆記：<executions>節點中的配置和外面的executions節點以外的元素不同，因為它們不能從命令中呼叫執行，因為它們是要呼叫了生命週期才會執行。所以你配置executions節點以外的元素可以外掛完全呼叫。自從Maven 3.3.1 不是這樣的情況了，你可以指定命令為外掛指定執行的命令。因此，你想執行上面這個外掛，指定execution1的配置可以通過命令列，你可以執行這個：
</div> <div>mvn myqyeryplugin:<a href="mailto:[email protected]">[email protected]</a></div> <div>
使用 <dependencies> 標籤
你可以配置 外掛的依賴庫，通常是由一些最新的依賴版本。 例子，Maven Antrun Plugin 版本 1.2 是由 Ant 版本 1.6.5 ，如果你想是由最新的Ant版本來執行外掛，你需要加dependencies 節點如下：<project> ... <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-antrun-plugin</artifactId> <version>1.2</version> ... <dependencies> <dependency> <groupId>org.apache.ant</groupId> <artifactId>ant</artifactId> <version>1.7.1</version> </dependency> <dependency> <groupId>org.apache.ant</groupId> <artifactId>ant-launcher</artifactId> <version>1.7.1</version> </dependency> </dependencies> </plugin> </plugins> </build> ... </project>
在構建外掛中使用 <inherited>標籤
預設，外掛配置應該傳播到子專案的pom裡，所以要打破繼承，你就需要使用<inherited>標籤：<project> ... <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-antrun-plugin</artifactId> <version>1.2</version> <inherited>false</inherited> ... </plugin> </plugins> </build> ... </project>
配置報表外掛
通過 配置報表外掛在 <reporting>節點。使用<reporting>標籤和<build>標籤
在pom中配置報表外掛在 <reporting>標籤 或者<build>標籤，是不一樣的行為。 mvn site 它只能將引數定義在configuration 節點的每一個指定在<reportying>標籤中報表外掛。例如，site 總是忽略了在<build>中每個外掛在configuration 節點指定的一些引數。 mvn aplugin:areportgoal 它會首先將引數定義在configuration 節點的每一個指定在<reportying>標籤中報表外掛；如果找不到，它將會查詢在build的每個外掛的配置中定義的引數。使用<reportSets>標籤
你可以使用<reportSets>標籤配置一個報表外掛。在執行mvn site，通常用於可以選擇性的生成報表。通過下面的配置你可以生成專案的團隊報表。<project> ... <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-project-info-reports-plugin</artifactId> <version>2.1.2</version> <reportSets> <reportSet> <reports> <report>project-team</report> </reports> </reportSet> </reportSets> </plugin> </plugins> </reporting> ... </project>筆記： 1. 執行所有報表，你需要使用：
<reportSets> <reportSet> <reports/> </reportSet> </reportSets>2.參考任意一個外掛的文件（例如 plugin-info.html）你會了解更多可用的外掛。
在報表外掛中使用 <inherited> 標籤
與構建外掛類似，打破繼承，你可以使用<inherited>標籤<project> ... <reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-project-info-reports-plugin</artifactId> <version>2.1.2</version> <inherited>false</inherited> </plugin> </plugins> </reporting> ... </project> <div>
