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文件

  
4.0.0
  
com.apress.gswmbook
  
gswm
  
1.0.0-SNAPSHOT
  
jar
  
Getting Started with Maven
  
http://apress.com
  
    This project acts as a starter project for the Introducing Maven book (http://www.apress.com/9781484208427) published by Apress.  
  
    
      
GSWM Developer List
      
[email protected]
      
[email protected]
      
[email protected]
    
  


    
      
Apache License, Version 2.0
      
http://www.apache.org/licenses/LICENSE-2.0.txt
    
  
  

看看清单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文件内容

        
        
Apress
        
images/company.png
        
http://apress.com
    
        
            
              
            
            
            
            
            
            
            
            
            
            
            
            
            
            
        
        
        
        

运行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片段

        
 
    
      
        
org.apache.maven.plugins
        
maven-javadoc-plugin
        
2.10.1
      
    
  

现在你已经配置了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插件

        
  
    
      
        
org.apache.maven.plugins
        
maven-surefire-report-plugin
        
2.17
      
    
  

现在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插件

        
  


      
        
org.codehaus.mojo
        
cobertura-maven-plugin
        
2.6
      
   
  

现在配置了插件，让我们使用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片段

        
  
    
      
        
org.codehaus.mojo
        
findbugs-maven-plugin
        
3.0.0
      
   
 

生成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的发布过程。