概要

Maven的一个很好的功能就是能以很小代价创建一个内部技术站点。 Maven 2 继承了这项功能并带来了一个新的更强大的生成站点内容的功能。这篇文章将带你一步一步创建一个好的Maven站点.

团队交流是项目的一个基本部分。花费时间在查找项目的技术信息上可能是代价不菲并且令人沮丧的。明显地, 拥有自己专用的web站点对每个IT项目有利的。

Maven站点生成器就是为此而生。以微小的努力，你就能有拥有一个专业水准、低维护成本、快速运行的web站点。Maven让你生成项目的一站式信息中心， 包括：
#一般项目信息，诸如源码库, 缺陷追踪, 团队成员等
#单元测试报告及测试覆盖率报告
#使用Checkstyle和PMD对代码进行自动审查
#配置和版本信息
#依赖关系
#Javadocs
#源代码的HTML形式，建立索引和可交叉查考
#更多

Maven站点被频繁地使用在开源项目中 (在资源列表有一些例子)。一个典型的项目站点包含：项目信息，大部分来自文件pom.xml；一些生成的报表(单元测试， Javadocs， Checkstyle 代码审查等等)； 还有一项目相关的事物内容。
在这篇文章里，我们将带领你如何在很短的时间内建立起一个Maven站点并使之运行。 注意: 此教程所使用的源码可在资源列表中下载。

环节1: 项目信息部分

对于一个新进人员，可能会把你的Maven站点当作了解项目的第一站。并且希望在项目信息页面上了解到你这个项目组织的大概面貌。Web站点的这一部分全部使用来自文件pom.xml的信息。一个缺省的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/maven-v400.xsd>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.javaworld.hotels</groupId>
  <artifactId>HotelWeb</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>Maven Quick Start Archetype</name>
  <url>http://maven.apache.org</url>

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project> 

现在你可能想要添加你的项目的一些细节。所有的区域都是可选的，但你应该把项目有关的信息尽可能多的放上去。接下来的几节将讨论一些有用的项目。
项目名称与描述
添加合适的项目名，描述，站点URL。这个会出现在项目的主页上，所以不要过于吝啬:

   ...
   <name>Hotel Database tutorial application</name>
   <url>http://your.project.url</url>
   <description>Write a few paragraphs to say what your project is about.</description> 

问题追踪
现在加入项目的问题管理系统(Bugzilla, Jira, Scarab,或任何你喜欢的问题管理系统)的名称和URL，使用issueManagement标签:

   ...
   <issueManagement>
      <system>Bugzilla</system>
      <url>https://bugzilla.wakaleo.com/</url>
   </issueManagement> 

持续集成
如果你的项目使用了某种持续集成工具，诸如CruiseControl或者Continuum，你可以使用ciManagement标签提供它的细节，如下所示。 (如果你还有用过持续集成，现在就可以考虑使用一个) Maven 2 可与Continuum很好的集成：你可以只提供如下的pom.xml文件就能把Maven2项目安装到Continuum服务器上。

   ...
   <ciManagement>
      <system>Continuum</system>
      <url>http://integrationserver.wakaleo.com/continuum</url>
      <notifiers>
         <notifier>
            <type>mail</type>
            <address>duke@wakaleo.com</address>
         </notifier>
      </notifiers>
   </ciManagement>

项目团队
人们总是希望知道自己和谁一起工作，特别是近年来，一个项目团队的成员可能来自不同的组织和洲。在developers部分, 列出了团队成员的一些细节。timezone 字段对那些国际性团队是又用处的，这个字段显示相对于格林尼治标准时间或伦敦时间的时差，从而可以知道团队成员所在地的时间。举个例子，纽约时间是-5, 巴黎是+1, 而悉尼是+10.

   ...
   <developers>
      <developer>
         <id>duke</id>
         <name>Duke Java</name>
         <email>duke@wakaleo.com</email>
         <roles>
            <role>Project Manager</role>
            <role>Architect</role>
         </roles>
         <organization>Acme.com</organization>
         <timezone>-5</timezone>
       </developer>         
   </developers>

邮件列表
如果项目使用了邮件列表, 那就在mailingLists页面进行描述它们。一个典型的邮件列表的配置看起来像这样:

   ...
   <mailingLists>
     <mailingList>
       <name>HotelDatabase project mailing list</name>
       <subscribe>dev-subscribe@wakaleo.com</subscribe>
       <unsubscribe>dev-unsubscribe@wakaleo.com</unsubscribe>
      <post>dev@wakaleo.com</post>
      <archive>http://mail-archives.wakaleo.com/modmbox/dev/</archive>
     </mailingList>
   </mailingLists> 

代码库
项目的另一个重要部分就是代码库. scm标签允许你配置你的代码库，为Maven web站点和其它插件使用。如果你正在使用CVS或Subversion， source repository页面同样能给如何使用代码库的详细的、工具相关的指令。这里是一个典型SCM(software configuration management)的配置例子:

   ...
   <scm>
      <connection>scm:svn:http://svn.wakaleo.com/hoteldatabase/</connection>
      <developerConnection>scm:svn:http://svn.wakaleo.com/hoteldatabase/</developerConnection>
      <url>http://svn.wakaleo.com/viewcvs.cgi/hoteldatabase/</url>
   </scm> 

现在你可以试验你的Maven！生成站点的命令是：mvn site。
你发站点在生成在target/site里. 看一下project information连接，你应该可以找到所有你刚才添加的信息(见 Figure 1)!


Figure 1. 新的Maven2项目站点中的项目信息区域

环节 2: 添加报表

Maven也提供大量的有关自动报表生成的插件。在Maven2里，报表生成非常简单：你只要在pom.xml文件的尾部的reporting 部分，添加你需要的报表的插件。

Javadocs
大多数情况下，你会以发布的类的Javadoc作为开始。 这个只要在pom.xml文件的reporting 部分添加javadoc插件。在这同时，你可以添加jxr插件，它将会生成源代码的一个有索引和交叉查考的HTML版本：

  <reporting>
    <plugins>
      <plugin>
        <artifactId>maven-javadoc-plugin</artifactId>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>jxr-maven-plugin</artifactId>
      </plugin>      
    </plugins>
  </reporting>

单元测试报表
为尽可能多的代码编写单元测试是极度提倡的。Maven在build构建过程中完全整合了单元测试—默认情况下, 每一次构建都会运行所有的单元测试。把测试结果发布给大家看是很有益处的，它鼓励开发人员去修正任何失败的单元测试。
surefire插件运行所有的单元测试，然后生成一个详细报表：

  <reporting>
    <plugins>
      ...
      <plugin>
        <artifactId>maven-surefire-plugin</artifactId>
      </plugin>
    </plugins>
  </reporting>

测试覆盖率
测试覆盖率可以很好的显示你的单元测试的质量如何。它简单的告诉你有多少代码被单元测试运行到了，而这能给你检测测试质量的好主意。在某些项目内，要求所有的类的测试覆盖达到一定的百分比。诸如Clover (一种强健商业测试覆盖工具) 或者 Cobertura (一种流行开源工具，用来替代Maven 1的JCoverage插件)的工具能生成测试覆盖报表。Clover有经过证实的能力来对庞大项目执行测试覆盖，而其它一些工具却并不总能胜任。Figure 2展示一个Clover测试覆盖报表。


Figure 2. Clover生成的测试覆盖报表

到目前为止，Maven2只有Clover插件可用，而Cobertura插件在这篇文章撰写的时候还在开发当中。
为添加Clover报表到你的Maven站点只需在reporting部分加maven-clover-plug-in插件：

  <reporting>
    <plugins>
      ...
      <plugin>
        <artifactId>maven-clover-plugin</artifactId>
      </plugin>
    </plugins>
  </reporting>

代码分析
自动代码分析有助于提高代码质量和鼓励良好的编码习惯。Checkstyle运行多而广的测试以检查是否符合强制的代码标准和最佳实践。PMD更多的专注于语义上的错误和潜在的bug。 两者都能提供有用的信息，虽然你可能不得不进行调整 (尤其是Checkstyle) 以只获得对你的项目有意义的错误。

有时，你会需要传递参数给插件。在Maven2中，你可以通过使用configuration 标签来做到这一点，它会把这些参数值注入到插件里。在pmd插件中, 设置targetjdk参数为1.5以便 PMD能够处理Java 1.5的源代码。你也能制定其它的参数，诸如被执行的规则、输出格式和代码上超链接是否需要被生成：

  <reporting>
    <plugins>
      ...
      <plugin>
         <groupId>org.apache.maven.plugins</groupId>

         <artifactId>maven-pmd-plugin</artifactId>
         <configuration>
            <targetjdk>1.5</targetjdk>
            <rulesets>
               <ruleset>/rulesets/basic.xml</ruleset>
               <ruleset>/rulesets/controversial.xml</ruleset>
            </rulesets>
            <format>xml</format>
            <linkXref>true</linkXref>
            <sourceEncoding>utf-8</sourceEncoding>

            <minimumTokens>100</minimumTokens>
         </configuration>
      </plugin>
    </plugins>
  </reporting>

更改与配置管理
在任何的项目里，文档的更改是很重要的。Maven 2提供几个有用的功能使得事情变得简单些。
changes-maven-plugin插件使用一种特别的XML文件(src/changes/changes.xml) 来记录每次发布的版本和更改。 这个文件看起来像这样：

<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
   <properties>
      <title>Hotel Database tutorial application</title>
      <author email="duke@wakaleo.com>Duke Java</author>
   </properties>
   <body>
      <release version="current" description="Current work version>    
           <action dev="Duke Java" type="add>
               A new cool feature.
           </action>         
         </release>
      <release version="1.0.1" date="2005-11-18" description="Release fix>   
           <action dev="Duke Java" type="add>
               Added a cool feature.
           </action>                      
           <action dev="Duke Java" type="fix" issue="1254>
               Fixed a nasty bug.
           </action>        
           <action dev="Duke Java" type="delete>
               Removed a feature that nobody liked.
           </action>        
         </release>         
   </body>
</document>

在这里，你列出每个版本及其相关说明：新的功能或进展(增加)， bug修正 (修改)，或去掉一些东西 (删除)。你应该详细描述修改信息，是谁做了改动、有什么问题被提出来。使用这个文件来给出一个清楚的、易读的更改和版本的历史记录。
现在添加changes插件到 Maven 2报表中:

  <reporting>
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>changes-maven-plugin</artifactId>
      </plugin>
    <plugins>
  </reporting>

图3 显示一个正式的更改报表的例子


图 3. 一个真实的更改报表

另一个更面向开发的选项是使用SCM库来记录更改信息。changelog插件会生成一个更漂亮的报表，指出有什么文件被谁更改了：

  <reporting>
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>changelog-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </reporting>

最后，如果你使用@todo标签来提醒你需要完成的事情(这是一个很好的习惯)， taglist报表 会生成一个包含所有标注上@todo或TODO的项目的列表:

  <reporting>
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>taglist-maven-plugin</artifactId>
      </plugin>
    <plugins>
  </reporting>

增加特别的站点内容
你也可以把你自己的内容加入到站点里去。你可以加入FAQ页面、技术文档、任何你想得到的东西。
站点内容存放在src/site目录，并被组织成三个主要的目录，如下所示：
- src/
   + site/
      + apt/
      |  + vision-statement.apt
      |     ...
      |
      + fml/
      |  + faq.fml
      |     ...
      |
      + xdoc/
      |  + best-practices.xml
      |     ...
      |
      + site.xml

你必须写一个站点描述符（在site.xml中）来定义站点布局及导航。这个文件简单的描述出现在站点上的栏目。在我们这个简单的例子中，这个文件有如下形式：

<?xml version="1.0" encoding="ISO-8859-1"?>
<site>
  <bannerLeft>
    <name>Hotel Database</name>
    <src>http://maven.apache.org/images/apache-maven-project.png</src>
    <href>http://maven.apache.org/</href>
  </bannerLeft>
  <bannerRight>
    <src>http://maven.apache.org/images/maven-small.gif</src>
  </bannerRight>
  <body>
    <links>
      <item name="Maven" href="http://maven.apache.org/"/>
      <item name="Apache" href="http://www.apache.org/"/>
    </links>

    <menu name="The Hotel Database project>
      <item name="Vision Statement" href="/vision-statement.html"/>
      <item name="Best Practices" href="/best-practices.html"/>
      <item name="FAQs" href="/faqs.html"/>
    </menu>

    ${reports}

  </body>
</site>

支持的文件格式
可以加入各种格式的站点内容。传统的Maven文档格式是XDoc，一种针对站点内容的具有松散结构，用途广泛的XML格式。XDoc文件存放在xdoc目录. XDoc 类似XHTML 及广为人知的HTML。下面是一个简单的例子：

   <document> 
     <properties> 
       <author email="user@company.com> The Wakaleo Team< /author> 
       <title> The Hotel Database Vision Statement< /title> 
     </properties> 
     <body> 

       <section name="Introduction"> 
         <p> 
         This application demonstrates Maven 2 site generation functionalities. One of the nicer features of Maven is the ability to create an internal technical web site 
         at very little cost. Maven 2 extends this functionality, and gives you powerful new ways 
         to generate site content...
         </p> 

          <subsection name="Team Communication"> 

            <! --Team communication is an essential part of any project. And wasting 
     time looking for technical project information can be costly and frustrating. Clearly,
    any IT project will benefit from having its own dedicated technical web site. Some
    useful things it provides are:
         <ul>
           <li>Online javadoc</li>
          <li>Quality assurance</li>
           <ul>
             <li>Static code audits with Checkstyle or PMD
             <li>Unit test reports</li>
            </ul>
           </ul>
            </p> 
          </subsection> 
       </section> 
     </body> 
   </document>

Maven 2引入了一种新的格式APT (almost plain text，几乎无格式文本)，它被设计用来更方便的编写技术站点的内容。APT格式是一种类似wiki的文本格式，擅长于编写具有简单结构的文档或对简单文本的格式化与排版。APT文件(*.apt) 放在apt目录里. 对APT格式的详细说明可见资源列表。下面是一个简单的例子：

-----
The Hotel Database Vision Statement
-----
The Wakaleo Team
-----
January 2006

Introduction

One of the nicer features of Maven is the ability to create an internal technical web site 
at very little cost. Maven 2 extends this functionality, and gives you powerful new ways 
to generate site content...

* Sub-section title

Team communication is an essential part of any project. And wasting time looking for technical
project information can be costly and frustrating. Clearly, any IT project will benifit from 
having its own dedicated technical web site...

* Item 1

* Item 2

   * Item 2.1
   
   * Item 2.2

所有这些文档会生成类似如图 4 所示的页面。


图 4. 局部站点内容

fml目录放的是FAQ的东西，文件都是采用FML格式. FML格式一种XML格式，转为FAQ页面特别设计的。下面是一个简单的例子：

<?xml version="1.0"?> 
<faqs title="About the Hotel Database application"> 

  <part id="about"> 
    <faq> 
      <question> This is a very frequent question</question> 
      <answer> 
        <p> 
          Thank you for asking that question, here is the answer...
        </p> 
      </answer> 
    </faq> 

    <faq> 
      <question> Here is another question?< /question> 
      <answer> 
        <p> 
          This is the answer to this question...
        </p> 
      </answer> 
    </faq> 
  </part> 
</faqs>

生成的页面如图 5 所示。

图 5. 一个简单的FAQ页面例子

其它格式，如DocBook，在写这篇文章的时候也在开发当中。

部署你的站点
为了部署你的站点，首先你要在pom.xml里定义相应的地址来告诉Maven要部署到哪里，如下：

<distributionManagement> 
  <site> 
    <id> website</id> 
    <url> scp://www.mycompany.com/www/docs/project/</url> 
  </site> 
</distributionManagement> 

现在你可以运行mvn site-deploy来部署站点了。
使用scp(目前只接受这种方法)拷贝站点到目标位置从而让每个人都能看到。

站点生成与持续集成
你应该多长时间更新一次站点？ 这通常取决于个人和团队的喜好。别忘了站点生成过程是比较占CPU的。一个真实的大项目的站点生成在一台繁忙的服务器上需要花费10或者15分钟. 所以如果你每个五分钟运行一次站点生成，系统管理员就很可能非常懊恼了。通常，一天一次或两次已经足够了。

总结

在这篇文章里，我们介绍了一步步建立Maven2 web站点的基本要点。Maven 2站点生成是非常强大和灵活的，提供很多有用的立竿见影的标准技术报表；通过一些简单的初始化工作就能完成很多工作。在传统的XDoc和FML格式之外, APT格式提供了一种新的，方便的途径去编写特别的技术内容。在Maven2里，站点生成的速度也变快了不少。 总之，虽然一些报表还在开发当中，但Maven 2的站点生成功能还是非常值得研究的。

关于作者
John Ferguson Smart自1991年开始涉足IT 行业，从1999年开始涉及J2EE开发。他擅长于J2EE架构和开发和IT项目管理，包括一些境外项目管理。他在开源java技术领域有广泛的经验。他为全球政府和商业的许多大规模J2EE项目（包括国际和境外团队）工作过，也写过J2EE领域的技术文章。可以在http://www.jroller.com/page/wakaleo找到他的技术。

资源列表
#下载文章附带的源代码:
http://www.javaworld.com/javaworld/jw-02-2006/maven/jw-0227-maven.zip
#Maven网站:
http://maven.apache.org
#一个典型的用Maven生成的项目站点:
http://db.apache.org/torque/releases/torque-3.1/index.html
#另一个Maven生成的项目站点:
http://boss.bekk.no/boss/middlegen/
#Bugzilla问题追踪系统:
https://bugzilla.mozilla.org
#JIRA问题管理系统 (商业软件):
http://www.atlassian.com/software/jira
#Scarab 问题管理系统:
http://scarab.tigris.org
#CruiseControl持续集成工具:
http://cruisecontrol.sourceforge.net/
#Continuum持续集成工具:
http://maven.apache.org/continuum/
#Clover测试覆盖工具 (商业软件:
http://www.cenqua.com/clover/
#Cobertura测试覆盖工具:
http://cobertura.sourceforge.net/
#Checkstyle 代码分析工具:
http://checkstyle.sourceforge.net/
#PMD代码分析工具:
http://pmd.sourceforge.net/
#Codehaus Mojo 库:
http://mojo.codehaus.org/
#APT文本格式入门:
http://maven.apache.org/guides/mini/guide-apt-format.html