|
概要 Maven的一個(gè)很好的功能就是能以很小代價(jià)創(chuàng)建一個(gè)內(nèi)部技術(shù)站點(diǎn)。 Maven 2 繼承了這項(xiàng)功能并帶來(lái)了一個(gè)新的更強(qiáng)大的生成站點(diǎn)內(nèi)容的功能。這篇文章將帶你一步一步創(chuàng)建一個(gè)好的Maven站點(diǎn). 團(tuán)隊(duì)交流是項(xiàng)目的一個(gè)基本部分?;ㄙM(fèi)時(shí)間在查找項(xiàng)目的技術(shù)信息上可能是代價(jià)不菲并且令人沮喪的。明顯地, 擁有自己專(zhuān)用的web站點(diǎn)對(duì)每個(gè)IT項(xiàng)目有利的。 Maven站點(diǎn)生成器就是為此而生。以微小的努力,你就能有擁有一個(gè)專(zhuān)業(yè)水準(zhǔn)、低維護(hù)成本、快速運(yùn)行的web站點(diǎn)。Maven讓你生成項(xiàng)目的一站式信息中心, 包括: #一般項(xiàng)目信息,諸如源碼庫(kù), 缺陷追蹤, 團(tuán)隊(duì)成員等 #單元測(cè)試報(bào)告及測(cè)試覆蓋率報(bào)告 #使用Checkstyle和PMD對(duì)代碼進(jìn)行自動(dòng)審查 #配置和版本信息 #依賴關(guān)系 #Javadocs #源代碼的HTML形式,建立索引和可交叉查考 #更多 Maven站點(diǎn)被頻繁地使用在開(kāi)源項(xiàng)目中 (在資源列表有一些例子)。一個(gè)典型的項(xiàng)目站點(diǎn)包含:項(xiàng)目信息,大部分來(lái)自文件pom.xml;一些生成的報(bào)表(單元測(cè)試, Javadocs, Checkstyle 代碼審查等等); 還有一項(xiàng)目相關(guān)的事物內(nèi)容。 在這篇文章里,我們將帶領(lǐng)你如何在很短的時(shí)間內(nèi)建立起一個(gè)Maven站點(diǎn)并使之運(yùn)行。 注意: 此教程所使用的源碼可在資源列表中下載。 環(huán)節(jié)1: 項(xiàng)目信息部分 對(duì)于一個(gè)新進(jìn)人員,可能會(huì)把你的Maven站點(diǎn)當(dāng)作了解項(xiàng)目的第一站。并且希望在項(xiàng)目信息頁(yè)面上了解到你這個(gè)項(xiàng)目組織的大概面貌。Web站點(diǎn)的這一部分全部使用來(lái)自文件pom.xml的信息。一個(gè)缺省的pom.xml大概看起來(lái)像這樣: <project xmlns="http://maven./POM/4.0.0" xmlns:xsi="http://www./2001/XMLSchema-instance" 現(xiàn)在你可能想要添加你的項(xiàng)目的一些細(xì)節(jié)。所有的區(qū)域都是可選的,但你應(yīng)該把項(xiàng)目有關(guān)的信息盡可能多的放上去。接下來(lái)的幾節(jié)將討論一些有用的項(xiàng)目。 項(xiàng)目名稱(chēng)與描述 添加合適的項(xiàng)目名,描述,站點(diǎn)URL。這個(gè)會(huì)出現(xiàn)在項(xiàng)目的主頁(yè)上,所以不要過(guò)于吝嗇: ... 問(wèn)題追蹤 現(xiàn)在加入項(xiàng)目的問(wèn)題管理系統(tǒng)(Bugzilla, Jira, Scarab,或任何你喜歡的問(wèn)題管理系統(tǒng))的名稱(chēng)和URL,使用issueManagement標(biāo)簽: ... 持續(xù)集成 如果你的項(xiàng)目使用了某種持續(xù)集成工具,諸如CruiseControl或者Continuum,你可以使用ciManagement標(biāo)簽提供它的細(xì)節(jié),如下所示。 (如果你還有用過(guò)持續(xù)集成,現(xiàn)在就可以考慮使用一個(gè)) Maven 2 可與Continuum很好的集成:你可以只提供如下的pom.xml文件就能把Maven2項(xiàng)目安裝到Continuum服務(wù)器上。 ... 項(xiàng)目團(tuán)隊(duì) 人們總是希望知道自己和誰(shuí)一起工作,特別是近年來(lái),一個(gè)項(xiàng)目團(tuán)隊(duì)的成員可能來(lái)自不同的組織和洲。在developers部分, 列出了團(tuán)隊(duì)成員的一些細(xì)節(jié)。timezone 字段對(duì)那些國(guó)際性團(tuán)隊(duì)是又用處的,這個(gè)字段顯示相對(duì)于格林尼治標(biāo)準(zhǔn)時(shí)間或倫敦時(shí)間的時(shí)差,從而可以知道團(tuán)隊(duì)成員所在地的時(shí)間。舉個(gè)例子,紐約時(shí)間是-5, 巴黎是+1, 而悉尼是+10. ... 郵件列表 如果項(xiàng)目使用了郵件列表, 那就在mailingLists頁(yè)面進(jìn)行描述它們。一個(gè)典型的郵件列表的配置看起來(lái)像這樣: ... 代碼庫(kù) 項(xiàng)目的另一個(gè)重要部分就是代碼庫(kù). scm標(biāo)簽允許你配置你的代碼庫(kù),為Maven web站點(diǎn)和其它插件使用。如果你正在使用CVS或Subversion, source repository頁(yè)面同樣能給如何使用代碼庫(kù)的詳細(xì)的、工具相關(guān)的指令。這里是一個(gè)典型SCM(software configuration management)的配置例子: ... 現(xiàn)在你可以試驗(yàn)?zāi)愕腗aven!生成站點(diǎn)的命令是:mvn site。 你發(fā)站點(diǎn)在生成在target/site里. 看一下project information連接,你應(yīng)該可以找到所有你剛才添加的信息(見(jiàn) Figure 1)! ![]() Figure 1. 新的Maven2項(xiàng)目站點(diǎn)中的項(xiàng)目信息區(qū)域 環(huán)節(jié) 2: 添加報(bào)表 Maven也提供大量的有關(guān)自動(dòng)報(bào)表生成的插件。在Maven2里,報(bào)表生成非常簡(jiǎn)單:你只要在pom.xml文件的尾部的reporting 部分,添加你需要的報(bào)表的插件。 Javadocs 大多數(shù)情況下,你會(huì)以發(fā)布的類(lèi)的Javadoc作為開(kāi)始。 這個(gè)只要在pom.xml文件的reporting 部分添加javadoc插件。在這同時(shí),你可以添加jxr插件,它將會(huì)生成源代碼的一個(gè)有索引和交叉查考的HTML版本: <reporting> 單元測(cè)試報(bào)表 為盡可能多的代碼編寫(xiě)單元測(cè)試是極度提倡的。Maven在build構(gòu)建過(guò)程中完全整合了單元測(cè)試—默認(rèn)情況下, 每一次構(gòu)建都會(huì)運(yùn)行所有的單元測(cè)試。把測(cè)試結(jié)果發(fā)布給大家看是很有益處的,它鼓勵(lì)開(kāi)發(fā)人員去修正任何失敗的單元測(cè)試。 surefire插件運(yùn)行所有的單元測(cè)試,然后生成一個(gè)詳細(xì)報(bào)表: <reporting> 測(cè)試覆蓋率 測(cè)試覆蓋率可以很好的顯示你的單元測(cè)試的質(zhì)量如何。它簡(jiǎn)單的告訴你有多少代碼被單元測(cè)試運(yùn)行到了,而這能給你檢測(cè)測(cè)試質(zhì)量的好主意。在某些項(xiàng)目?jī)?nèi),要求所有的類(lèi)的測(cè)試覆蓋達(dá)到一定的百分比。諸如Clover (一種強(qiáng)健商業(yè)測(cè)試覆蓋工具) 或者 Cobertura (一種流行開(kāi)源工具,用來(lái)替代Maven 1的JCoverage插件)的工具能生成測(cè)試覆蓋報(bào)表。Clover有經(jīng)過(guò)證實(shí)的能力來(lái)對(duì)龐大項(xiàng)目執(zhí)行測(cè)試覆蓋,而其它一些工具卻并不總能勝任。Figure 2展示一個(gè)Clover測(cè)試覆蓋報(bào)表。 ![]() Figure 2. Clover生成的測(cè)試覆蓋報(bào)表 到目前為止,Maven2只有Clover插件可用,而Cobertura插件在這篇文章撰寫(xiě)的時(shí)候還在開(kāi)發(fā)當(dāng)中。 為添加Clover報(bào)表到你的Maven站點(diǎn)只需在reporting部分加maven-clover-plug-in插件: <reporting> 代碼分析 自動(dòng)代碼分析有助于提高代碼質(zhì)量和鼓勵(lì)良好的編碼習(xí)慣。Checkstyle運(yùn)行多而廣的測(cè)試以檢查是否符合強(qiáng)制的代碼標(biāo)準(zhǔn)和最佳實(shí)踐。PMD更多的專(zhuān)注于語(yǔ)義上的錯(cuò)誤和潛在的bug。 兩者都能提供有用的信息,雖然你可能不得不進(jìn)行調(diào)整 (尤其是Checkstyle) 以只獲得對(duì)你的項(xiàng)目有意義的錯(cuò)誤。 有時(shí),你會(huì)需要傳遞參數(shù)給插件。在Maven2中,你可以通過(guò)使用configuration 標(biāo)簽來(lái)做到這一點(diǎn),它會(huì)把這些參數(shù)值注入到插件里。在pmd插件中, 設(shè)置targetjdk參數(shù)為1.5以便 PMD能夠處理Java 1.5的源代碼。你也能制定其它的參數(shù),諸如被執(zhí)行的規(guī)則、輸出格式和代碼上超鏈接是否需要被生成: <reporting> 更改與配置管理 在任何的項(xiàng)目里,文檔的更改是很重要的。Maven 2提供幾個(gè)有用的功能使得事情變得簡(jiǎn)單些。 changes-maven-plugin插件使用一種特別的XML文件(src/changes/changes.xml) 來(lái)記錄每次發(fā)布的版本和更改。 這個(gè)文件看起來(lái)像這樣: <?xml version="1.0" encoding="ISO-8859-1"?> 在這里,你列出每個(gè)版本及其相關(guān)說(shuō)明:新的功能或進(jìn)展(增加), bug修正 (修改),或去掉一些東西 (刪除)。你應(yīng)該詳細(xì)描述修改信息,是誰(shuí)做了改動(dòng)、有什么問(wèn)題被提出來(lái)。使用這個(gè)文件來(lái)給出一個(gè)清楚的、易讀的更改和版本的歷史記錄。 現(xiàn)在添加changes插件到 Maven 2報(bào)表中: <reporting> 圖3 顯示一個(gè)正式的更改報(bào)表的例子 圖 3. 一個(gè)真實(shí)的更改報(bào)表 另一個(gè)更面向開(kāi)發(fā)的選項(xiàng)是使用SCM庫(kù)來(lái)記錄更改信息。changelog插件會(huì)生成一個(gè)更漂亮的報(bào)表,指出有什么文件被誰(shuí)更改了: <reporting> 最后,如果你使用@todo標(biāo)簽來(lái)提醒你需要完成的事情(這是一個(gè)很好的習(xí)慣), taglist報(bào)表 會(huì)生成一個(gè)包含所有標(biāo)注上@todo或TODO的項(xiàng)目的列表: <reporting> 增加特別的站點(diǎn)內(nèi)容 你也可以把你自己的內(nèi)容加入到站點(diǎn)里去。你可以加入FAQ頁(yè)面、技術(shù)文檔、任何你想得到的東西。 站點(diǎn)內(nèi)容存放在src/site目錄,并被組織成三個(gè)主要的目錄,如下所示: - src/ + site/ + apt/ | + vision-statement.apt | ... | + fml/ | + faq.fml | ... | + xdoc/ | + best-practices.xml | ... | + site.xml 你必須寫(xiě)一個(gè)站點(diǎn)描述符(在site.xml中)來(lái)定義站點(diǎn)布局及導(dǎo)航。這個(gè)文件簡(jiǎn)單的描述出現(xiàn)在站點(diǎn)上的欄目。在我們這個(gè)簡(jiǎn)單的例子中,這個(gè)文件有如下形式: <?xml version="1.0" encoding="ISO-8859-1"?> 支持的文件格式 可以加入各種格式的站點(diǎn)內(nèi)容。傳統(tǒng)的Maven文檔格式是XDoc,一種針對(duì)站點(diǎn)內(nèi)容的具有松散結(jié)構(gòu),用途廣泛的XML格式。XDoc文件存放在xdoc目錄. XDoc 類(lèi)似XHTML 及廣為人知的HTML。下面是一個(gè)簡(jiǎn)單的例子: <document> Maven 2引入了一種新的格式APT (almost plain text,幾乎無(wú)格式文本),它被設(shè)計(jì)用來(lái)更方便的編寫(xiě)技術(shù)站點(diǎn)的內(nèi)容。APT格式是一種類(lèi)似wiki的文本格式,擅長(zhǎng)于編寫(xiě)具有簡(jiǎn)單結(jié)構(gòu)的文檔或?qū)?jiǎn)單文本的格式化與排版。APT文件(*.apt) 放在apt目錄里. 對(duì)APT格式的詳細(xì)說(shuō)明可見(jiàn)資源列表。下面是一個(gè)簡(jiǎn)單的例子: ----- 所有這些文檔會(huì)生成類(lèi)似如圖 4 所示的頁(yè)面。 ![]() 圖 4. 局部站點(diǎn)內(nèi)容 fml目錄放的是FAQ的東西,文件都是采用FML格式. FML格式一種XML格式,轉(zhuǎn)為FAQ頁(yè)面特別設(shè)計(jì)的。下面是一個(gè)簡(jiǎn)單的例子: <?xml version="1.0"?> 生成的頁(yè)面如圖 5 所示。 ![]() 圖 5. 一個(gè)簡(jiǎn)單的FAQ頁(yè)面例子 其它格式,如DocBook,在寫(xiě)這篇文章的時(shí)候也在開(kāi)發(fā)當(dāng)中。 部署你的站點(diǎn) 為了部署你的站點(diǎn),首先你要在pom.xml里定義相應(yīng)的地址來(lái)告訴Maven要部署到哪里,如下: <distributionManagement> 現(xiàn)在你可以運(yùn)行mvn site-deploy來(lái)部署站點(diǎn)了。 使用scp(目前只接受這種方法)拷貝站點(diǎn)到目標(biāo)位置從而讓每個(gè)人都能看到。 站點(diǎn)生成與持續(xù)集成 你應(yīng)該多長(zhǎng)時(shí)間更新一次站點(diǎn)? 這通常取決于個(gè)人和團(tuán)隊(duì)的喜好。別忘了站點(diǎn)生成過(guò)程是比較占CPU的。一個(gè)真實(shí)的大項(xiàng)目的站點(diǎn)生成在一臺(tái)繁忙的服務(wù)器上需要花費(fèi)10或者15分鐘. 所以如果你每個(gè)五分鐘運(yùn)行一次站點(diǎn)生成,系統(tǒng)管理員就很可能非常懊惱了。通常,一天一次或兩次已經(jīng)足夠了。 總結(jié) 在這篇文章里,我們介紹了一步步建立Maven2 web站點(diǎn)的基本要點(diǎn)。Maven 2站點(diǎn)生成是非常強(qiáng)大和靈活的,提供很多有用的立竿見(jiàn)影的標(biāo)準(zhǔn)技術(shù)報(bào)表;通過(guò)一些簡(jiǎn)單的初始化工作就能完成很多工作。在傳統(tǒng)的XDoc和FML格式之外, APT格式提供了一種新的,方便的途徑去編寫(xiě)特別的技術(shù)內(nèi)容。在Maven2里,站點(diǎn)生成的速度也變快了不少。 總之,雖然一些報(bào)表還在開(kāi)發(fā)當(dāng)中,但Maven 2的站點(diǎn)生成功能還是非常值得研究的。 關(guān)于作者 John Ferguson Smart自1991年開(kāi)始涉足IT 行業(yè),從1999年開(kāi)始涉及J2EE開(kāi)發(fā)。他擅長(zhǎng)于J2EE架構(gòu)和開(kāi)發(fā)和IT項(xiàng)目管理,包括一些境外項(xiàng)目管理。他在開(kāi)源java技術(shù)領(lǐng)域有廣泛的經(jīng)驗(yàn)。他為全球政府和商業(yè)的許多大規(guī)模J2EE項(xiàng)目(包括國(guó)際和境外團(tuán)隊(duì))工作過(guò),也寫(xiě)過(guò)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. #一個(gè)典型的用Maven生成的項(xiàng)目站點(diǎn): http://db./torque/releases/torque-3.1/index.html #另一個(gè)Maven生成的項(xiàng)目站點(diǎn): http://boss./boss/middlegen/ #Bugzilla問(wèn)題追蹤系統(tǒng): https://bugzilla.mozilla.org #JIRA問(wèn)題管理系統(tǒng) (商業(yè)軟件): http://www./software/jira #Scarab 問(wèn)題管理系統(tǒng): http://scarab. #CruiseControl持續(xù)集成工具: http://cruisecontrol./ #Continuum持續(xù)集成工具: http://maven./continuum/ #Clover測(cè)試覆蓋工具 (商業(yè)軟件: http://www./clover/ #Cobertura測(cè)試覆蓋工具: http://cobertura./ #Checkstyle 代碼分析工具: http://checkstyle./ #PMD代碼分析工具: http://pmd./ #Codehaus Mojo 庫(kù): http://mojo./ #APT文本格式入門(mén): http://maven./guides/mini/guide-apt-format.html |
|
|
來(lái)自: chanvy > 《我的圖書(shū)館》