Maven系列 7.文檔和報告

7. 文檔和報告
文檔和報告是任何項目的關鍵方面。這對於企業和開源項目尤其如此，其中許多人協作構建項目。本章討論一些Maven的工具和插件，使得在線文檔的發佈和維護變得輕而易舉。
本章將再次使用您在前面章節中創建的gswm Java項目。 gswm項目也可以在C：\ apress \ gswm-book \ chapter7文件夾中找到。
使用現場生命週期
如第5章所討論的，Maven提供了可用於生成項目文檔的站點生命週期。讓我們從gswm目錄運行以下命令：
mvn位點

網站生命週期使用Maven的網站插件爲單個項目生成網站。一旦此命令完成，將在項目目標下創建站點文件夾。圖7-1顯示了站點文件夾的內容。

圖7-1。生成的站點文件夾
打開index.html文件以瀏覽生成的站點。您將注意到Maven使用pom.xml文件中提供的信息來生成大多數文檔。它還自動應用默認皮膚並生成相應的圖像和CSS文件。圖7-2顯示了生成的index.html文件。

圖7-2。生成的索引頁
“項目依賴項”頁面提供了有關項目的直接和傳遞依賴性的有用信息。它還提供與那些依賴關聯的許可信息，如圖7-3所示。

圖7-3。項目依賴項頁面
當您瀏覽生成的網站時，您會注意到諸如關於，郵件列表和項目許可證等頁面缺少信息。讓我們修改pom.xml文件並添加缺少的信息，如清單7-1所示。

清單7-1。帶項目信息的pom.xml文件

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">  
<modelVersion>4.0.0
</modelVersion>  
<groupId>com.apress.gswmbook
</groupId>  
<artifactId>gswm
</artifactId>  
<version>1.0.0-SNAPSHOT
</version>  
<packaging>jar
</packaging>  
<name>Getting Started with Maven
</name>  
<url>http://apress.com
</url>  
<description>    This project acts as a starter project for the Introducing Maven book (http://www.apress.com/9781484208427) published by Apress.  
</description>  
<mailingLists>    
<mailingList>      
<name>GSWM Developer List
</name>      
<subscribe>[email protected]
</subscribe>      
<unsubscribe>[email protected]
</unsubscribe>      
<post>[email protected]
</post>    
</mailingList>  
</mailingLists>

<licenses>    
<license>      
<name>Apache License, Version 2.0
</name>      
<url>http://www.apache.org/licenses/LICENSE-2.0.txt
</url>    
</license>  
</licenses>  
<!--- Developer, Dependency and Build information removed for brevity--->
</project>

看看清單7-1中的pom.xml文件的代碼，很明顯，描述元素用於提供項目描述。 mailingList元素保存郵件列表信息，許可證元素包括項目的許可證。讓我們通過運行以下命令重新生成網站：
mvn clean site
在新生成的target \ site文件夾下啓動index.html文件。圖7-4A和圖7-4B分別顯示了新的關於和項目許可證頁面。請注意，Maven使用在許可證元素中聲明的URL來下載許可證文本，並將其包括在生成的網站中。

圖7-4A。生成的關於頁面

圖7-4B。生成的項目許可證頁面

高級站點配置
在上一節中，在pom.xml文件中指定了項目信息，供Maven在站點生成期間使用。對於中等到複雜的項目，此方法將導致笨重和難以維護的pom.xml文件。此外，企業通常喜歡在生成的站點中使用他們的品牌和徽標，而不是默認的Maven外觀。爲了解決這些問題，Maven允許您在適當命名的src / site文件夾下指定網站生成的內容和配置。圖7-5顯示了簡單站點文件夾的目錄結構。

圖7-5。站點文件夾目錄結構
site.xml文件（也稱爲站點描述符）用於自定義生成的站點。我們將在一秒鐘內看這個元素。
apt文件夾包含以大致純文本（APT）格式編寫的網站內容。 APT格式允許在類似純文本的語法中創建文檔。有關APT格式的更多信息可以在Maven網站上找到（http://maven.apache.org/doxia/references/apt-format.html）。除了APT，Maven支持其他格式，如FML，Xdoc和Markdown。
Maven提供了幾種原型，允許您自動生成站點結構。因爲您將更新現有的gswm項目，所以您將使用create goal而不是generate，如下面的代碼所示。在C：\ apress \ gswm-book \ chapter7 \ gswm文件夾中運行命令：
mvn archetype：create -DarchetypeArtifactId = maven-archetype-site-simple
成功完成後，您將看到在gswm \ src下創建的站點文件夾，其中包含site.xml和apt文件夾。讓我們從將項目描述添加到index.apt開始。使用清單7-2中的代碼替換index.apt文件的內容。
清單7-2。 index.apt文件內容

----- Getting Started with Maven Starter ----- Apress ----- 10-10-2014

這個項目作爲一個初始項目爲Apress出版的介紹Maven書。有關更多信息，請訪問Apress網站https://www.apress.com。
運行mvn clean site將創建一個新的About頁面，如圖7-6所示。

圖7-6。關於包含新內容的頁面
請注意，頁面的左側導航窗格已完全消失。這是因爲Maven使用site.xml文件構造此導航，並且此site.xml文件當前缺少導航信息。
在我們查看site.xml文件中的信息之前，讓我們添加一個將作爲網站標誌的圖片。靜態資源（例如圖片和HTML文件）放在site / resources文件夾中。當Maven構建站點時，它會將resources文件夾中的資產複製到生成的站點的根目錄。從C：\ apress \ gswm-book \ chapter7文件夾複製company logo company.png，並將其放在gswm / src / site / resources / images文件夾中。
現在您可以修改site.xml文件，以便徽標和導航顯示。使用清單7-3的內容替換site.xml文件。請注意，標誌的src元素包括相對路徑images / company.png。菜單元素用於創建要在網站上顯示的不同導航鏈接。
清單7-3。 site.xml文件內容

<?xml version="1.0" encoding="ISO-8859-1"?>

<project xmlns="http://maven.apache.org/DECORATION/1.6.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.6.0 http://maven.apache.org/xsd/decoration-1.6.0.xsd"  name="Getting Started With Maven" >        
<bannerLeft>        
<name>Apress
</name>        
<src>images/company.png
</src>        
<href>http://apress.com
</href>    
</bannerLeft>        
<body>            
<links>              
<item name="Maven" href="http://maven.apache.org/"/>            
</links>            
<menu name="Project Information">            
<item name="Introduction" href="index.html"/>            
<item name="Plugin Management" href="plugin-management.html"/>            
<item name="Dependency Information" href="dependency-info.html"/>            
<item name="Source Repository" href="source-repository.html"/>            
<item name="Mailing Lists" href="mail-lists.html"/>            
<item name="Issue Tracking" href="issue-tracking.html"/>            
<item name="Continuous Integration" href="integration.html"/>            
<item name="Project Plugins" href="plugins.html"/>            
<item name="Project License" href="license.html"/>            
<item name="Project Team" href="team-list.html"/>            
<item name="Project Summary" href="project-summary.html"/>            
<item name="Dependencies" href="dependencies.html"/>        
</menu>        
<menu name="Reports">        
</menu>        
</body>

</project>

運行mvn clean site將生成帶有新徽標和導航的站點，如圖7-7所示。

圖7-7。關於帶有新徽標的頁面

生成Javadoc報告

Javadoc是記錄Java代碼的事實上的標準。它幫助開發人員瞭解類或方法的作用。 Javadoc還突出顯示了已棄用的類，方法或字段。
Maven提供了一個Javadoc插件，它使用Javadoc工具來生成Javadoc。集成Javadoc插件只需要在pom.xml文件的報告元素中聲明它，如清單7-4所示。在pom報告元素中聲明的插件在站點生成期間執行。
清單7-4。帶有Javadoc插件的pom.xml片段

<project>        
<!—Content removed for brevity--> 
<reporting>    
<plugins>      
<plugin>        
<groupId>org.apache.maven.plugins
</groupId>        
<artifactId>maven-javadoc-plugin
</artifactId>        
<version>2.10.1
</version>      
</plugin>    
</plugins>  
</reporting>
</project>

現在你已經配置了Javadoc插件，讓我們運行mvn clean site來生成Javadoc。命令成功運行後，您將注意到在gswm / target / site下創建的apidocs文件夾。雙擊apidocs下的index.html文件，您將能夠瀏覽Javadoc。圖7-8顯示了爲gswm項目生成的Javadoc。

圖7-8。生成的Javadoc頁面

生成單元測試報告
測試驅動的發展已經成爲今天企業的規範。單元測試爲開發人員提供即時反饋，並允許他們構建質量代碼。考慮到測試有多重要，Maven爲每個構建執行所有測試。任何測試失敗都會導致失敗的構建。
Maven提供了Surefire插件，爲運行由JUnit或TestNG等框架創建的測試提供了統一的接口。它還生成各種格式的執行結果，如XML和HTML。這些發佈的結果使開發人員能夠快速找到並修復損壞的測試。
Surefire插件的配置方式與pom文件的報告部分中的Javadoc插件相同。清單7-5顯示了Surefire插件配置。
清單7-5。 pom.xml片段與Surefire插件

<project>        
<!—Content removed for brevity-->  
<reporting>    
<plugins>      
<plugin>        
<groupId>org.apache.maven.plugins
</groupId>        
<artifactId>maven-surefire-report-plugin
</artifactId>        
<version>2.17
</version>      
</plugin>    
</plugins>  
</reporting>
</project>

現在Surefire已配置，讓我們通過運行mvn clean site命令來生成一個Maven站點。成功執行命令後，您將看到在gswm \ target下生成的Surefire Reports文件夾。它包含XML和TXT格式的測試執行結果。相同的信息將以HTML格式存在於sites下的surefire-report.html文件中。圖7-9顯示了gswm項目的Surefire報告。

圖7-9。生成的Surefire報告

生成代碼覆蓋率報告

代碼覆蓋率是自動化測試執行多少源代碼的度量。基本上，它提供了測試質量的指示。 Emma和Cobertura是Java的兩種流行的開源代碼覆蓋工具。
在本節中，您將使用Cobertura來測量此項目的代碼覆蓋率。配置Cobertura與其他插件類似，如清單7-6所示。
清單7-6。 pom.xml片段與Cobertura插件

<project>        
<!—Content removed for brevity-->  
<reporting>

<plugins>      
<plugin>        
<groupId>org.codehaus.mojo
</groupId>        
<artifactId>cobertura-maven-plugin
</artifactId>        
<version>2.6
</version>      
</plugin>   
</plugins>  
</reporting>
</project>

現在配置了插件，讓我們使用mvn clean site命令生成網站。成功完成命令後，Cobertura將在gswm \ target \ site下創建一個cobertura文件夾。雙擊index.html文件以啓動報告。報告應類似於圖7-10所示的報告。

圖7-10。生成Cobertura報告
生成FindBugs報告
FindBugs是一個用於檢測Java代碼中的缺陷的工具。它使用靜態分析來檢測bug模式，例如無限遞歸循環和空指針解引用。清單7-7顯示了FindBugs配置。
清單7-7。帶有FindBugs插件的pom.xml片段

<project>        
<!—Content removed for brevity-->  
<reporting>    
<plugins>      
<plugin>        
<groupId>org.codehaus.mojo
</groupId>        
<artifactId>findbugs-maven-plugin
</artifactId>        
<version>3.0.0
</version>      
</plugin>   
</plugins> 
</reporting>
</project>

生成Maven站點後，打開C：\ apress \ gswm-book \ chapter7 \ gswm \ target \ site下的findbugs.html文件，以啓動FindBugs報告。它應該類似於圖7-11所示。

圖7-11。生成的FindBugs Bug檢測器報告

總結
Maven提供的文檔和報告功能在創建可維護的質量軟件方面發揮了重要作用。本章介紹了使用站點生命週期和生成文檔所需的配置的基礎知識。您還查看了生成Javadoc，測試覆蓋率和FindBugs報告。
在下一章中，我們將解釋如何將Maven與Nexus和SVN集成。您還將瞭解Maven的發佈過程。

Maven系列 7.文檔和報告

《Python進階》學習筆記

Leetcode 3161. 物塊放置查詢

leetcode 60 排列序列

一個docker容器暴露多個端口

微服務實踐之使用 Visual Studio 2022 調試Dapr 應用程序

wpf附加屬性理解 WPF附加屬性

Maven系列 4.Maven項目基礎

Maven系列 8.Maven發佈

Maven系列 6.Maven原型

Maven系列 5.Maven生命週期

PHP中的類型：不要擔心，要快樂

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結