ANT十五大最佳實(shí)踐
作者：Eric M. Burke, coauthor of Java Extreme Programming Cookbook
原文：http://www.onjava.com/pub/a/onjava/2003/12/17/ant_bestpractices.html
譯者：徐彤MSN:xt121@hotmail.com
在Ant出現(xiàn)之前，構(gòu)建和部署Java應(yīng)用需要使用包括特定平臺的腳本、Make文件、各種版本的IDE甚至手工操作的“大雜燴”?，F(xiàn)在，幾乎所有的開源Java項(xiàng)目都在使用Ant，大多數(shù)公司的內(nèi)部項(xiàng)目也在使用Ant。Ant在這些項(xiàng)目中的廣泛使用自然導(dǎo)致了讀者對一整套Ant最佳實(shí)踐的迫切需求。
本文總結(jié)了我喜愛的Ant技巧或最佳實(shí)踐，多數(shù)是從我親身經(jīng)歷的項(xiàng)目錯誤或我聽說的其他人經(jīng)歷的 “恐怖”故事中得到靈感的。比如，有人告訴我有個項(xiàng)目把XDoclet 生成的代碼放入帶有鎖定文件功能的版本控制工具中。當(dāng)開發(fā)者修改源代碼時，他必須記住手工檢出（Check out）并鎖定所有將要重新生成的文件。然后，手工運(yùn)行代碼生成器，只到這時他才能夠讓Ant編譯代碼，這一方法還存在如下一些問題：
- 生成的代碼無法存儲在版本控制系統(tǒng)中。
- Ant（本案例中是Xdoclet）應(yīng)該自動確定下一次構(gòu)建涉及的源文件，而不應(yīng)由程序員手工確定。
- Ant的構(gòu)建文件應(yīng)該定義好正確的任務(wù)依賴關(guān)系，這樣程序員就不必為了完成構(gòu)建而不得不按照特定順序調(diào)用任務(wù)。
當(dāng)我開始一個新項(xiàng)目時，我首先編寫Ant構(gòu)建文件。Ant文件明確地定義構(gòu)建的過程，并被團(tuán)隊(duì)中的每個程序員使用。本文所列的技巧基于這樣的假定：Ant構(gòu)建文件是一個必須仔細(xì)編寫的重要文件，它應(yīng)在版本控制系統(tǒng)中得到維護(hù)，并被定期進(jìn)行重構(gòu)。下面是我的十五大Ant最佳實(shí)踐。
1. 采用一致的編碼規(guī)范
Ant用戶有的喜歡有的痛恨其構(gòu)建文件的XML語法。與其跳進(jìn)這一令人迷惑的爭論中，不如讓我們先看一些能保持XML構(gòu)建文件簡潔的方法。
首先也是最重要的，花費(fèi)時間格式化你的XML讓它看上去很清晰。不論XML是否美觀，Ant都可以工作。但是丑陋的XML很難令人讀懂。倘若你在任務(wù)之間留出空行，有規(guī)則的縮進(jìn)，每行文字不超過90列左右，那么XML令人驚訝地易讀。再加上使用能夠高亮XML語法的優(yōu)秀編輯器或IDE工具，你就不會有閱讀的麻煩。
同樣，精選含意明確、容易讀懂的詞匯來命名任務(wù)和屬性。比如，dir.reports就比rpts好。特定的編碼規(guī)范并不重要，只要拿出一套規(guī)范并堅(jiān)持使用就行。
2. 將build.xml放在項(xiàng)目根目錄中
Ant構(gòu)建文件build.xml可以放在任何位置，但是放在項(xiàng)目頂級目錄中可以保持項(xiàng)目簡潔。這是最常用的規(guī)范，開發(fā)者能夠在頂級目錄中找到預(yù)期的build.xml。把構(gòu)建文件放在根目錄中，也能夠使人容易了解項(xiàng)目目錄樹中不同目錄之間的邏輯關(guān)系。以下是一個典型的項(xiàng)目目錄層次：
[root dir]
| build.xml
+--src
+--lib (包含第三方 JAR包)
+--build (由 build任務(wù)生成)
+--dist (由 build任務(wù)生成)
當(dāng)build.xml在頂級目錄時，假設(shè)你處于項(xiàng)目某個子目錄中，只要輸入：ant -find compile 命令，不需要改變工作目錄就能夠以命令行方式編譯代碼。參數(shù)-find告訴Ant尋找存在于上級目錄中的build.xml并執(zhí)行。
3. 使用單一的構(gòu)建文件
有人喜歡將一個大項(xiàng)目分解成幾個小的構(gòu)建文件，每個構(gòu)建文件分擔(dān)整個構(gòu)建過程的一小部分工作。這確實(shí)是看法不同的問題，但是應(yīng)該認(rèn)識到，將構(gòu)建文件分割會增加對整體構(gòu)建過程的理解難度。要注意在單一構(gòu)建文件能夠清楚表現(xiàn)構(gòu)建層次的情況下不要過工程化(over-engineer)。
即使你把項(xiàng)目劃分為多個構(gòu)建文件，也應(yīng)使程序員能夠在項(xiàng)目根目錄下找到核心build.xml。盡管該文件只是將實(shí)際構(gòu)建工作委派給下級構(gòu)建文件，也應(yīng)保證該文件可用。
4. 提供良好的幫助說明
應(yīng)盡量使構(gòu)建文件自文檔化。增加任務(wù)描述是最簡單的方法。當(dāng)你輸入ant -projecthelp時，你就可以看到帶有描述的任務(wù)清單。比如，你可以這樣定義任務(wù)：
<target name="compile"
description="Compiles code, output goes to the build dir.">
最簡單的規(guī)則是把所有你想讓程序員通過命令行就可以調(diào)用的任務(wù)都加上描述。對于一般用來執(zhí)行中間處理過程的內(nèi)部任務(wù)，比如生成代碼或建立輸出目錄等，就無法使用描述屬性。
這時，可以通過在構(gòu)建文件中加入XML注釋來處理?；蛘邔ｉT定義一個help任務(wù)，當(dāng)程序員輸入ant help時來顯示詳細(xì)的使用說明。
<target name="help" description="Display detailed usage information">
<echo>Detailed help...</echo></target>
5. 提供清除任務(wù)
每個構(gòu)建文件都應(yīng)包含一個清除任務(wù)，用來刪除所有生成的文件和目錄，使系統(tǒng)回到構(gòu)建文件執(zhí)行前的初始狀態(tài)。執(zhí)行清空任務(wù)后還存在的文件都應(yīng)處在版本控制系統(tǒng)的管理之下。比如：
<target name="clean"
description="Destroys all generated files and dirs.">
<delete dir="${dir.build}"/>
<delete dir="${dir.dist}"/>
</target>
除非是在產(chǎn)生整個系統(tǒng)版本的特殊任務(wù)中，否則不要自動調(diào)用clean任務(wù)。當(dāng)程序員僅僅執(zhí)行編譯任務(wù)或其他任務(wù)時，他們不需要構(gòu)建文件事先執(zhí)行既令人討厭又沒有必要的清空任務(wù)。要相信程序員能夠確定何時需要清空所有文件。
6. 使用ANT管理任務(wù)從屬關(guān)系
假設(shè)你的應(yīng)用由Swing GUI組件、Web界面、EJB層和公共應(yīng)用代碼組成。在大型系統(tǒng)中，你需要清晰地定義每個Java包屬于系統(tǒng)的哪一層。否則任何一點(diǎn)修改都要被迫重新編譯成百上千個文件。糟糕的任務(wù)從屬關(guān)系管理會導(dǎo)致過度復(fù)雜而脆弱的系統(tǒng)。改變GUI面板的設(shè)計(jì)不應(yīng)造成Servlet和EJB的重編譯。
當(dāng)系統(tǒng)變得龐大后，稍不注意就可能將依賴于客戶端的代碼引入到服務(wù)端。這是因?yàn)榈湫偷腎DE項(xiàng)目文件編譯任何文件都使用單一的classpath。而Ant能讓你更有效地控制構(gòu)建活動。
設(shè)計(jì)你的Ant構(gòu)建文件編譯大型項(xiàng)目的步驟：首先，編譯公共應(yīng)用代碼，將編譯結(jié)果打成JAR包文件。然后，編譯上一層的項(xiàng)目代碼，編譯時依靠第一步產(chǎn)生的JAR文件。不斷重復(fù)這一過程，直到最高層的代碼編譯完成。
分步構(gòu)建強(qiáng)化了任務(wù)從屬關(guān)系管理。如果你工作在底層Java框架上，偶然引用到高層的GUI模板組件，這時代碼不需要編譯。這是由于構(gòu)建文件在編譯底層框架時在源路徑中沒有包含高層GUI面板組件的代碼。
7. 定義并重用文件路徑
如果文件路徑在一個地方一次性集中定義，并在整個構(gòu)建文件中得到重用，那么構(gòu)建文件更易于理解。以下是這樣做的一個例子：
<project name="sample" default="compile" basedir=".">
<path id="classpath.common">
<pathelement location="${jdom.jar.withpath}"/>
...etc </path>
<path id="classpath.client">
<pathelement location="${guistuff.jar.withpath}"/>
<pathelement location="${another.jar.withpath}"/>
<!-- reuse the common classpath -->
<path refid="classpath.common"/>
</path>
<target name="compile.common" depends="prepare">
<javac destdir="${dir.build}" srcdir="${dir.src}">
<classpath refid="classpath.common"/>
<include name="com/oreilly/common/**"/>
</javac>
</target>
</project>
當(dāng)項(xiàng)目不斷增長構(gòu)建日益復(fù)雜時，這一技術(shù)越發(fā)體現(xiàn)出其價值。你可能需要為編譯不同層次的應(yīng)用定義各自的文件路徑，比如運(yùn)行單元測試的、運(yùn)行應(yīng)用程序的、運(yùn)行Xdoclet的、生成JavaDocs的等等不同路徑。這種組件化路徑定義的方法比為每個任務(wù)單獨(dú)定義路徑要優(yōu)越得多。否則，很容易丟失任務(wù)從屬關(guān)系的軌跡。
8. 定義恰當(dāng)?shù)娜蝿?wù)從屬關(guān)系
假設(shè)dist任務(wù)從屬于jar任務(wù)，那么哪個任務(wù)從屬于compile任務(wù)哪個任務(wù)從屬于prepare任務(wù)呢？Ant構(gòu)建文件最終定義了任務(wù)的從屬關(guān)系圖，它必須被仔細(xì)地定義和維護(hù)。
應(yīng)該定期檢查任務(wù)的從屬關(guān)系以保證構(gòu)建工作得到正確執(zhí)行。大的構(gòu)建文件隨著時間推移趨向于增加更多的任務(wù)，所以到最后可能由于不必要的從屬關(guān)系導(dǎo)致構(gòu)建工作非常困難。比如，你可能發(fā)現(xiàn)在程序員只需編譯一些沒有使用EJB的GUI代碼時又重新生成了EJB代碼。
以“優(yōu)化”的名義忽略任務(wù)的從屬關(guān)系是另一種常見的錯誤。這種錯誤迫使程序員為了得到恰當(dāng)?shù)慕Y(jié)果必須記住并按照特定的順序調(diào)用一串任務(wù)。更好的做法是：提供描述清晰的公共任務(wù)，這些任務(wù)包含正確的任務(wù)從屬關(guān)系；另外提供一套“專家”任務(wù)讓你能夠手工執(zhí)行個別的構(gòu)建步驟，這些任務(wù)不提供完整的構(gòu)建過程，但是讓那些專家用戶在快速而惱人的編碼期間能夠跳過某些步驟。
9.使用屬性
任何需要配置或可能發(fā)生變化的信息都應(yīng)作為Ant屬性定義下來。對于在構(gòu)建文件中多次出現(xiàn)的值也同樣處理。屬性既可以在構(gòu)建文件頭部定義，也可以為了更好的靈活性而在單獨(dú)的屬性文件中定義。以下是在構(gòu)建文件中定義屬性的樣式：
<project name="sample" default="compile" basedir=".">
<property name="dir.build" value="build"/>
<property name="dir.src" value="src"/>
<property name="jdom.home" value="../java-tools/jdom-b8"/>
<property name="jdom.jar" value="jdom.jar"/>
<property name="jdom.jar.withpath"
value="${jdom.home}/build/${jdom.jar}"/>
etc...
</project>
或者你可以使用屬性文件：
<project name="sample" default="compile" basedir=".">
<property file="sample.properties"/>
etc...
</project>
在屬性文件 sample.properties中:
dir.build=build
dir.src=src
jdom.home=../java-tools/jdom-b8
jdom.jar=jdom.jarjdom.jar.withpath=${jdom.home}/build/${jdom.jar}
用一個獨(dú)立的文件定義屬性是有好處的，它可以清晰地定義構(gòu)建中的可配置部分。另外，在開發(fā)者工作在不同操作系統(tǒng)的情況下，你可以在不同的平臺上提供該文件的不同版本。
10. 保持構(gòu)建過程獨(dú)立
為了最大限度的擴(kuò)展性，不要應(yīng)用外部路徑和庫文件。最重要的是不要依賴于程序員的CLASSPATH設(shè)置。取而代之的是，在構(gòu)建文件中使用相對路徑并定義自己的路徑。如果你引用了絕對路徑如C:\java\tools，其他開發(fā)者未必使用與你相同的目錄結(jié)構(gòu)，所以就無法使用你的構(gòu)建文件。
如果你部署開放源碼項(xiàng)目，應(yīng)該提供包含編譯代碼所需的所有JAR文件的發(fā)行版本。當(dāng)然，這是在遵守許可協(xié)議的基礎(chǔ)上。對于內(nèi)部項(xiàng)目，相關(guān)的JAR文件都應(yīng)在版本控制系統(tǒng)的管理中，并撿出（check out）到大家都知道的位置。
當(dāng)你必須引用外部路徑時，應(yīng)將路徑定義為屬性。使程序員能夠用適合他們自己的機(jī)器環(huán)境的參數(shù)重載這些屬性。你也可以使用以下語法引用環(huán)境變量：
<property environment="env"/>
<property name="dir.jboss" value="${env.JBOSS_HOME}"/>
11. 使用版本控制系統(tǒng)
構(gòu)建文件是一個重要的制品，應(yīng)該像代碼一樣進(jìn)行版本控制。當(dāng)你標(biāo)記你的代碼時，也應(yīng)用同樣的標(biāo)簽標(biāo)記構(gòu)建文件。這樣當(dāng)你需要回溯到舊版本并進(jìn)行構(gòu)建時，能夠使用相應(yīng)版本的構(gòu)建文件。
除構(gòu)建文件之外，你還應(yīng)在版本控制中維護(hù)第三方JAR文件。同樣，這使你能夠重新構(gòu)建舊版本的軟件。這也能夠更容易保證所有開發(fā)者擁有一致的JAR文件，因?yàn)樗麄兌际峭瑯?gòu)建文件一起從版本控制系統(tǒng)中撿出的。
通常應(yīng)避免在版本控制系統(tǒng)中存放構(gòu)建成果。倘若你的源代碼很好地得到了版本控制，那么通過構(gòu)建過程你能夠重新生成任何版本的產(chǎn)品。
12. 把Ant作為“最小公分母”
假設(shè)你的開發(fā)團(tuán)隊(duì)使用IDE工具，當(dāng)程序員通過點(diǎn)擊圖標(biāo)就能夠構(gòu)建整個應(yīng)用時為什么還要為Ant而煩惱呢？
IDE的問題是一個關(guān)于團(tuán)隊(duì)一致性和重現(xiàn)性的問題。幾乎所有的IDE設(shè)計(jì)初衷都是為了提高程序員的個人生產(chǎn)率，而不是開發(fā)團(tuán)隊(duì)的持續(xù)構(gòu)建。典型的IDE要求每個程序員定義自己的項(xiàng)目文件。程序員可能擁有不同的目錄結(jié)構(gòu)，可能使用不同版本的庫文件，還可能工作在不同的平臺上。這將導(dǎo)致出現(xiàn)這種情況：在Bob那里運(yùn)行良好的代碼，到Sally那里就無法運(yùn)行。
不管你的開發(fā)團(tuán)隊(duì)使用何種IDE，一定要建立所有程序員都能夠使用的Ant構(gòu)建文件。要建立一個程序員在將新代碼提交版本控制系統(tǒng)前必須執(zhí)行Ant構(gòu)建文件的規(guī)則。這將確保代碼是經(jīng)過同一個Ant構(gòu)建文件構(gòu)建的。當(dāng)出現(xiàn)問題時，要使用項(xiàng)目標(biāo)準(zhǔn)的Ant構(gòu)建文件，而不是通過某個IDE來執(zhí)行一個干凈的構(gòu)建。
程序員可以自由選擇任何他們習(xí)慣使用的IDE工具或編輯器。但是Ant應(yīng)作為公共基線以保證代碼永遠(yuǎn)是可構(gòu)建的。
13. 使用zipfileset屬性
人們經(jīng)常使用Ant產(chǎn)生WAR、JAR、ZIP和 EAR文件。這些文件通常都要求有一個特定的內(nèi)部目錄結(jié)構(gòu)，但其往往與你的源代碼和編譯環(huán)境的目錄結(jié)構(gòu)不匹配。
一個最常用的方法是寫一個Ant任務(wù)，按照期望的目錄結(jié)構(gòu)把一大堆文件拷貝到臨時目錄中，然后生成壓縮文件。這不是最有效的方法。使用zipfileset屬性是更好的解決方案。它讓你從任何位置選擇文件，然后把它們按照不同目錄結(jié)構(gòu)放進(jìn)壓縮文件中。以下是一個例子：
<ear earfile="${dir.dist.server}/payroll.ear"
appxml="${dir.resources}/application.xml">
<fileset dir="${dir.build}" includes="commonServer.jar"/>
<fileset dir="${dir.build}">
<include name="payroll-ejb.jar"/>
</fileset>
<zipfileset dir="${dir.build}" prefix="lib">
<include name="hr.jar"/>
<include name="billing.jar"/>
</zipfileset>
<fileset dir=".">
<include name="lib/jdom.jar"/>
<include name="lib/log4j.jar"/>
<include name="lib/ojdbc14.jar"/>
</fileset>
<zipfileset dir="${dir.generated.src}" prefix="META-INF">
<include name="jboss-app.xml"/>
</zipfileset>
</ear>
在這個例子中，所有JAR文件都放在EAR文件包的lib目錄中。hr.jar和billing.jar是從構(gòu)建目錄拷貝過來的。因此我們使用zipfileset屬性把它們移動到EAR文件包內(nèi)部的lib目錄。prefix屬性指定了其在EAR文件中的目標(biāo)路徑。
14. 測試Clean任務(wù)
假設(shè)你的構(gòu)建文件中有clean和compile的任務(wù)，執(zhí)行以下的測試。第一步，執(zhí)行ant clean；第二步，執(zhí)行ant compile；第三步，再執(zhí)行ant compile。第三步應(yīng)該不作任何事情。如果文件再次被編譯，說明你的構(gòu)建文件有問題。
構(gòu)建文件應(yīng)該只在與輸出文件相關(guān)聯(lián)的輸入文件發(fā)生變化時執(zhí)行任務(wù)。一個構(gòu)建文件在不必執(zhí)行諸如編譯、拷貝或其他工作任務(wù)的時候執(zhí)行這些任務(wù)是低效的。當(dāng)項(xiàng)目規(guī)模增長時，即使是小的低效工作也會成為大的問題。
15. 避免特定平臺的Ant封裝
不管什么原因，有人喜歡用簡單的、名稱叫做compile之類的批文件或腳本裝載他們的產(chǎn)品。當(dāng)你去看腳本的內(nèi)容你會發(fā)現(xiàn)以下內(nèi)容：
ant compile
其實(shí)開發(fā)人員都很熟悉Ant，并且完全能夠自己鍵入ant compile。請不要僅僅為了調(diào)用Ant而使用特定平臺的腳本。這只會使其他人在首次使用你的腳本時增加學(xué)習(xí)和理解的煩擾。除此之外，你不可能提供適用于每個操作系統(tǒng)的腳本，這是真正煩擾其他用戶的地方。
總結(jié)
太多的公司依靠手工方法和特別程序來編譯代碼和生成軟件發(fā)布版本。那些不使用Ant或類似工具定義構(gòu)建過程的開發(fā)團(tuán)隊(duì)，花費(fèi)了太多的時間來捕捉代碼編譯過程中出現(xiàn)的問題：在某些開發(fā)者那里編譯成功的代碼，到另一些開發(fā)者那里卻失敗了。
生成并維護(hù)構(gòu)建腳本不是一項(xiàng)富有魅力的工作，但卻是一項(xiàng)必需的工作。一個好的Ant構(gòu)建文件將使你能夠集中到更喜歡的工作——寫代碼中去！
參考
不得窺道門，不得悟佛門，不得入窄門，實(shí)乃破門。