有效利用Maven2的站點生成功能

chanvy 2008-11-15

展開全文

概要

Maven的一個很好的功能就是能以很小代價創(chuàng)建一個內(nèi)部技術(shù)站點。 Maven 2 繼承了這項功能并帶來了一個新的更強大的生成站點內(nèi)容的功能。這篇文章將帶你一步一步創(chuàng)建一個好的Maven站點.

團(tuán)隊交流是項目的一個基本部分?；ㄙM時間在查找項目的技術(shù)信息上可能是代價不菲并且令人沮喪的。明顯地, 擁有自己專用的web站點對每個IT項目有利的。

Maven站點生成器就是為此而生。以微小的努力，你就能有擁有一個專業(yè)水準(zhǔn)、低維護(hù)成本、快速運行的web站點。Maven讓你生成項目的一站式信息中心，包括：
#一般項目信息，諸如源碼庫, 缺陷追蹤, 團(tuán)隊成員等
#單元測試報告及測試覆蓋率報告
#使用Checkstyle和PMD對代碼進(jìn)行自動審查
#配置和版本信息
#依賴關(guān)系
#Javadocs
#源代碼的HTML形式，建立索引和可交叉查考
#更多

Maven站點被頻繁地使用在開源項目中 (在資源列表有一些例子)。一個典型的項目站點包含：項目信息，大部分來自文件pom.xml；一些生成的報表(單元測試， Javadocs， Checkstyle 代碼審查等等)；還有一項目相關(guān)的事物內(nèi)容。
在這篇文章里，我們將帶領(lǐng)你如何在很短的時間內(nèi)建立起一個Maven站點并使之運行。注意: 此教程所使用的源碼可在資源列表中下載。

環(huán)節(jié)1: 項目信息部分

對于一個新進(jìn)人員，可能會把你的Maven站點當(dāng)作了解項目的第一站。并且希望在項目信息頁面上了解到你這個項目組織的大概面貌。Web站點的這一部分全部使用來自文件pom.xml的信息。一個缺省的pom.xml大概看起來像這樣:

<project xmlns="http://maven./POM/4.0.0" xmlns:xsi="http://www./2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven./POM/4.0.0 http://maven./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.</url>

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

現(xiàn)在你可能想要添加你的項目的一些細(xì)節(jié)。所有的區(qū)域都是可選的，但你應(yīng)該把項目有關(guān)的信息盡可能多的放上去。接下來的幾節(jié)將討論一些有用的項目。
項目名稱與描述
添加合適的項目名，描述，站點URL。這個會出現(xiàn)在項目的主頁上，所以不要過于吝嗇:

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

問題追蹤
現(xiàn)在加入項目的問題管理系統(tǒng)(Bugzilla, Jira, Scarab,或任何你喜歡的問題管理系統(tǒng))的名稱和URL，使用issueManagement標(biāo)簽:

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

持續(xù)集成
如果你的項目使用了某種持續(xù)集成工具，諸如CruiseControl或者Continuum，你可以使用ciManagement標(biāo)簽提供它的細(xì)節(jié)，如下所示。 (如果你還有用過持續(xù)集成，現(xiàn)在就可以考慮使用一個) Maven 2 可與Continuum很好的集成：你可以只提供如下的pom.xml文件就能把Maven2項目安裝到Continuum服務(wù)器上。

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

項目團(tuán)隊
人們總是希望知道自己和誰一起工作，特別是近年來，一個項目團(tuán)隊的成員可能來自不同的組織和洲。在developers部分, 列出了團(tuán)隊成員的一些細(xì)節(jié)。timezone 字段對那些國際性團(tuán)隊是又用處的，這個字段顯示相對于格林尼治標(biāo)準(zhǔn)時間或倫敦時間的時差，從而可以知道團(tuán)隊成員所在地的時間。舉個例子，紐約時間是-5, 巴黎是+1, 而悉尼是+10.

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

郵件列表
如果項目使用了郵件列表, 那就在mailingLists頁面進(jìn)行描述它們。一個典型的郵件列表的配置看起來像這樣:

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

代碼庫
項目的另一個重要部分就是代碼庫. scm標(biāo)簽允許你配置你的代碼庫，為Maven web站點和其它插件使用。如果你正在使用CVS或Subversion， source repository頁面同樣能給如何使用代碼庫的詳細(xì)的、工具相關(guān)的指令。這里是一個典型SCM(software configuration management)的配置例子:

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

現(xiàn)在你可以試驗?zāi)愕腗aven！生成站點的命令是：mvn site。
你發(fā)站點在生成在target/site里. 看一下project information連接，你應(yīng)該可以找到所有你剛才添加的信息(見 Figure 1)!

Figure 1. 新的Maven2項目站點中的項目信息區(qū)域

環(huán)節(jié) 2: 添加報表

Maven也提供大量的有關(guān)自動報表生成的插件。在Maven2里，報表生成非常簡單：你只要在pom.xml文件的尾部的reporting 部分，添加你需要的報表的插件。

Javadocs
大多數(shù)情況下，你會以發(fā)布的類的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構(gòu)建過程中完全整合了單元測試—默認(rèn)情況下, 每一次構(gòu)建都會運行所有的單元測試。把測試結(jié)果發(fā)布給大家看是很有益處的，它鼓勵開發(fā)人員去修正任何失敗的單元測試。
surefire插件運行所有的單元測試，然后生成一個詳細(xì)報表：

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

測試覆蓋率
測試覆蓋率可以很好的顯示你的單元測試的質(zhì)量如何。它簡單的告訴你有多少代碼被單元測試運行到了，而這能給你檢測測試質(zhì)量的好主意。在某些項目內(nèi)，要求所有的類的測試覆蓋達(dá)到一定的百分比。諸如Clover (一種強健商業(yè)測試覆蓋工具) 或者 Cobertura (一種流行開源工具，用來替代Maven 1的JCoverage插件)的工具能生成測試覆蓋報表。Clover有經(jīng)過證實的能力來對龐大項目執(zhí)行測試覆蓋，而其它一些工具卻并不總能勝任。Figure 2展示一個Clover測試覆蓋報表。

Figure 2. Clover生成的測試覆蓋報表

到目前為止，Maven2只有Clover插件可用，而Cobertura插件在這篇文章撰寫的時候還在開發(fā)當(dāng)中。
為添加Clover報表到你的Maven站點只需在reporting部分加maven-clover-plug-in插件：

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

代碼分析
自動代碼分析有助于提高代碼質(zhì)量和鼓勵良好的編碼習(xí)慣。Checkstyle運行多而廣的測試以檢查是否符合強制的代碼標(biāo)準(zhǔn)和最佳實踐。PMD更多的專注于語義上的錯誤和潛在的bug。兩者都能提供有用的信息，雖然你可能不得不進(jìn)行調(diào)整 (尤其是Checkstyle) 以只獲得對你的項目有意義的錯誤。

有時，你會需要傳遞參數(shù)給插件。在Maven2中，你可以通過使用configuration 標(biāo)簽來做到這一點，它會把這些參數(shù)值注入到插件里。在pmd插件中, 設(shè)置targetjdk參數(shù)為1.5以便 PMD能夠處理Java 1.5的源代碼。你也能制定其它的參數(shù)，諸如被執(zhí)行的規(guī)則、輸出格式和代碼上超鏈接是否需要被生成：

  <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) 來記錄每次發(fā)布的版本和更改。這個文件看起來像這樣：

<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
   <properties>
      <title>Hotel Database tutorial application</title>
      <author email="duke@>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>

在這里，你列出每個版本及其相關(guān)說明：新的功能或進(jìn)展(增加)， bug修正 (修改)，或去掉一些東西 (刪除)。你應(yīng)該詳細(xì)描述修改信息，是誰做了改動、有什么問題被提出來。使用這個文件來給出一個清楚的、易讀的更改和版本的歷史記錄。
現(xiàn)在添加changes插件到 Maven 2報表中:

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

圖3 顯示一個正式的更改報表的例子

圖 3. 一個真實的更改報表

另一個更面向開發(fā)的選項是使用SCM庫來記錄更改信息。changelog插件會生成一個更漂亮的報表，指出有什么文件被誰更改了：

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

最后，如果你使用@todo標(biāo)簽來提醒你需要完成的事情(這是一個很好的習(xí)慣)， taglist報表會生成一個包含所有標(biāo)注上@todo或TODO的項目的列表:

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

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

支持的文件格式
可以加入各種格式的站點內(nèi)容。傳統(tǒng)的Maven文檔格式是XDoc，一種針對站點內(nèi)容的具有松散結(jié)構(gòu)，用途廣泛的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，幾乎無格式文本)，它被設(shè)計用來更方便的編寫技術(shù)站點的內(nèi)容。APT格式是一種類似wiki的文本格式，擅長于編寫具有簡單結(jié)構(gòu)的文檔或?qū)唵挝谋镜母袷交c排版。APT文件(*.apt) 放在apt目錄里. 對APT格式的詳細(xì)說明可見資源列表。下面是一個簡單的例子：

-----
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. 局部站點內(nèi)容

fml目錄放的是FAQ的東西，文件都是采用FML格式. FML格式一種XML格式，轉(zhuǎn)為FAQ頁面特別設(shè)計的。下面是一個簡單的例子：

<?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，在寫這篇文章的時候也在開發(fā)當(dāng)中。

部署你的站點
為了部署你的站點，首先你要在pom.xml里定義相應(yīng)的地址來告訴Maven要部署到哪里，如下：

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

現(xiàn)在你可以運行mvn site-deploy來部署站點了。
使用scp(目前只接受這種方法)拷貝站點到目標(biāo)位置從而讓每個人都能看到。

站點生成與持續(xù)集成
你應(yīng)該多長時間更新一次站點？這通常取決于個人和團(tuán)隊的喜好。別忘了站點生成過程是比較占CPU的。一個真實的大項目的站點生成在一臺繁忙的服務(wù)器上需要花費10或者15分鐘. 所以如果你每個五分鐘運行一次站點生成，系統(tǒng)管理員就很可能非常懊惱了。通常，一天一次或兩次已經(jīng)足夠了。

總結(jié)

在這篇文章里，我們介紹了一步步建立Maven2 web站點的基本要點。Maven 2站點生成是非常強大和靈活的，提供很多有用的立竿見影的標(biāo)準(zhǔn)技術(shù)報表；通過一些簡單的初始化工作就能完成很多工作。在傳統(tǒng)的XDoc和FML格式之外, APT格式提供了一種新的，方便的途徑去編寫特別的技術(shù)內(nèi)容。在Maven2里，站點生成的速度也變快了不少。總之，雖然一些報表還在開發(fā)當(dāng)中，但Maven 2的站點生成功能還是非常值得研究的。

關(guān)于作者
John Ferguson Smart自1991年開始涉足IT 行業(yè)，從1999年開始涉及J2EE開發(fā)。他擅長于J2EE架構(gòu)和開發(fā)和IT項目管理，包括一些境外項目管理。他在開源java技術(shù)領(lǐng)域有廣泛的經(jīng)驗。他為全球政府和商業(yè)的許多大規(guī)模J2EE項目（包括國際和境外團(tuán)隊）工作過，也寫過J2EE領(lǐng)域的技術(shù)文章。可以在http://www./page/wakaleo找到他的技術(shù)。

資源列表
#下載文章附帶的源代碼:
http://www./javaworld/jw-02-2006/maven/jw-0227-maven.zip
#Maven網(wǎng)站:
http://maven.
#一個典型的用Maven生成的項目站點:
http://db./torque/releases/torque-3.1/index.html
#另一個Maven生成的項目站點:
http://boss./boss/middlegen/
#Bugzilla問題追蹤系統(tǒng):
https://bugzilla.mozilla.org
#JIRA問題管理系統(tǒng) (商業(yè)軟件):
http://www./software/jira
#Scarab 問題管理系統(tǒng):
http://scarab.
#CruiseControl持續(xù)集成工具:
http://cruisecontrol./
#Continuum持續(xù)集成工具:
http://maven./continuum/
#Clover測試覆蓋工具 (商業(yè)軟件:
http://www./clover/
#Cobertura測試覆蓋工具:
http://cobertura./
#Checkstyle 代碼分析工具:
http://checkstyle./
#PMD代碼分析工具:
http://pmd./
#Codehaus Mojo 庫:
http://mojo./
#APT文本格式入門:
http://maven./guides/mini/guide-apt-format.html