原始碼組織

目錄

目錄結構

以下說明使用變數名稱 $CATALINA_BASE 來指稱大多數相對路徑所解析的基礎目錄。如果您尚未透過設定 CATALINA_BASE 目錄來為 Tomcat 設定多個執行個體，則 $CATALINA_BASE 會設定為 $CATALINA_HOME 的值，也就是您已安裝 Tomcat 的目錄。

本手冊的一個重要建議是將包含原始碼的目錄階層 (在本節中說明) 與包含可部署應用程式的目錄階層 (在上一節中說明) 分開。維持這種區分具有以下優點

  • 如果應用程式的「可執行」版本沒有混雜在一起，則原始碼目錄的內容會更容易管理、移動和備份。

  • 僅包含原始碼檔案的目錄上的原始碼控制會更容易管理。

  • 當部署階層是分開時，組成應用程式可安裝發行版的檔案會更容易選取。

正如我們將看到的，ant 開發工具讓建立和處理此類目錄階層幾乎毫無痛點。

用於包含應用程式原始碼的實際目錄和檔案階層可以是您喜歡的任何內容。但是，以下組織已被證明具有相當普遍的適用性，並且是下方討論的範例 build.xml 設定檔所預期的。所有這些元件都存在於應用程式的頂層專案原始碼目錄中

  • 文件/ - 應用程式的文件，採用您的開發團隊正在使用的任何格式。

  • src/ - Java 原始碼檔案，用於產生對您的應用程式獨特的 servlet、bean 和其他 Java 類別。如果您的原始碼以套件組織 (強烈建議)，則套件階層應反映為此目錄下的目錄結構。

  • web/ - 您的網站的靜態內容（HTML 頁面、JSP 頁面、JavaScript 檔案、CSS 樣式表檔案和影像），應用程式用戶端可以存取這些內容。此目錄將會是您的 Web 應用程式的文件根目錄，而且在此找到的任何子目錄結構都將會反映在存取這些檔案所需的請求 URI 中。

  • web/WEB-INF/ - 您的應用程式所需的特殊組態檔案，包括 Web 應用程式部署描述符（web.xml，定義於 Servlet 規範 中）、您已建立的客製化標籤庫的標籤庫描述符，以及您希望包含在 Web 應用程式中的其他資源檔案。即使此目錄看似是您的文件根目錄的子目錄，但 Servlet 規範禁止直接向用戶端請求提供此目錄（或其中包含的任何檔案）的內容。因此，這是儲存敏感組態資訊（例如資料庫連線使用者名稱和密碼）的好地方，但您的應用程式需要這些資訊才能順利運作。

在開發過程中，將會暫時建立兩個額外的目錄

  • build/ - 當您執行預設建置（ant）時，此目錄將會包含此應用程式的 Web 應用程式封存檔中檔案的精確映像。Tomcat 允許您以這種方式在未封裝的目錄中部署應用程式，方法是將其複製到 $CATALINA_BASE/webapps 目錄，或透過「管理員」Web 應用程式安裝它。後一種方法在開發期間非常有用，而且將會在下方說明。

  • dist/ - 當您執行 ant dist 目標時，將會建立此目錄。它將會建立 Web 應用程式的二進位發行版的精確映像，包括您已準備好的授權資訊、文件和 README 檔案。

請注意，這兩個目錄不應封存在您的原始碼控制系統中，因為它們會在開發期間視需要刪除並重新建立（從頭開始）。因此，如果您想要保留變更的永久記錄，則不應編輯這些目錄中的任何原始碼檔案，因為這些變更將會在下次執行建置時遺失。

外部依賴項

如果應用程式需要外部專案或套件的 JAR 檔案（或其他資源），您會怎麼做？一個常見的範例是，您需要在 Web 應用程式中包含 JDBC 驅動程式，才能執行。

不同的開發人員會採用不同的方法來解決這個問題。有些人會鼓勵將您依賴的 JAR 檔案副本檢查到每個需要這些 JAR 檔案的應用程式的原始程式碼控制檔案中。不過，當您在許多應用程式中使用相同的 JAR 時，這可能會造成嚴重的管理問題，特別是在需要升級到該 JAR 檔案的不同版本時。

因此，本手冊建議您不要將您依賴的套件副本儲存在應用程式的原始程式碼控制檔案中。相反地，外部依賴項應整合為建置應用程式流程的一部分。這樣一來，您隨時都可以從開發系統管理員安裝 JAR 檔案的任何位置取得適當的版本，而無需擔心每次依賴的 JAR 檔案版本變更時都必須更新應用程式。

在範例 Ant build.xml 檔案中，我們將示範如何定義建置屬性，讓您設定要複製檔案的位置，而無需在這些檔案變更時修改 build.xml。特定開發人員使用的建置屬性可以在每個應用程式基礎上自訂，或預設為儲存在開發人員家目錄中的「標準」建置屬性。

在許多情況下，您的開發系統管理員已經將所需的 JAR 檔案安裝到 Tomcat 的 lib 目錄中。如果已執行此動作，您無需採取任何動作，範例 build.xml 檔案會自動建置包含這些檔案的編譯類別路徑。

原始碼控制

如前所述，強烈建議您將構成應用程式的所有原始檔置於原始程式碼控制系統的管理之下。如果您選擇這麼做，原始階層中的每個目錄和檔案都應該註冊並儲存，但不要儲存任何產生的檔案。如果您註冊二進位格式檔案（例如影像或 JAR 函式庫），請務必將此資訊告知您的原始程式碼控制系統。

我們在上一節建議您不應將開發流程建立的 build/ 和 dist/ 目錄的內容儲存在原始程式碼控制系統中。原始程式碼控制系統通常提供忽略這些目錄的機制（Git 使用 .gitignore 檔案，Subversion 使用 svn:ignore 屬性，CVS 使用 .cvsignore 檔案，等等）。您應該設定原始程式碼控制系統忽略

  • 建置
  • 發行
  • build.properties

在此提及 build.properties 的原因會在 流程 區段說明。

針對您的原始碼控制環境的詳細說明不在本手冊的範圍內。

BUILD.XML 設定檔

我們將使用 ant 工具來管理 Java 原始碼檔案的編譯，並建立部署層級。Ant 在建置檔案的控制下運作，通常稱為 build.xml，其中定義了必要的處理步驟。此檔案儲存在原始碼層級的頂層目錄中，且應簽入您的原始碼控制系統。

與 Makefile 類似，build.xml 檔案提供多個「目標」，支援選擇性的開發活動（例如建立相關的 Javadoc 文件、清除部署主目錄，以便您可以從頭開始建置專案，或建立 Web 應用程式封存檔，以便您可以發行您的應用程式。建構良好的 build.xml 檔案將包含內部文件，說明專為開發人員設計的目標，相對於內部使用的目標。若要要求 Ant 顯示專案文件，請變更至包含 build.xml 檔案的目錄，並輸入

ant -projecthelp

為了讓您搶先開始，提供了一個 基本的 build.xml 檔案，您可以自訂並安裝在應用程式的專案原始碼目錄中。此檔案包含說明可以執行的各種目標的註解。簡而言之，通常會提供下列目標

  • clean - 此目標會刪除任何現有的 build 和 dist 目錄，以便它們可以從頭開始重建。這讓您可以保證您沒有進行原始碼修改，這會導致執行時間的問題，因為沒有重新編譯所有受影響的類別。

  • compile - 此目標用於編譯自上次編譯以來已變更的任何原始碼。產生的類別檔案會建立在 build 目錄的 WEB-INF/classes 子目錄中，這正是 Web 應用程式結構要求它們所在的位置。由於此命令在開發期間執行得很頻繁，因此通常會將它設為「預設」目標，以便簡單的 ant 命令會執行它。

  • all - 此目標是執行 clean 目標後再執行 compile 目標的捷徑。因此，它保證您會重新編譯整個應用程式，以確保您沒有不知不覺地引入任何不相容的變更。

  • javadoc - 此目標會為此 Web 應用程式中的 Java 類別建立 Javadoc API 文件。範例 build.xml 檔案假設您想要將 API 文件包含在應用程式發行版中，因此它會在 dist 目錄的子目錄中產生文件。由於您通常不需要在每次編譯時產生 Javadoc，因此此目標通常是 dist 目標的相依性，而不是 compile 目標的相依性。

  • dist - 此目標會為您的應用程式建立一個發行目錄，其中包括任何必要的說明文件、Java 類別的 Javadoc，以及一個 Web 應用程式封存 (WAR) 檔案，此檔案將傳送給想要安裝您應用程式的系統管理員。由於此目標也相依於 deploy 目標，因此 Web 應用程式封存也會擷取在部署時包含的任何外部相依性。

對於使用 Tomcat 進行 Web 應用程式的互動式開發與測試，已定義下列其他目標

  • install - 告知目前執行的 Tomcat 立即讓您正在開發的應用程式可供執行與測試。此動作不需要重新啟動 Tomcat，但它也不會在下次重新啟動 Tomcat 後被記住。

  • reload - 一旦應用程式安裝完畢，您可以繼續使用 compile 目標進行變更與重新編譯。Tomcat 會自動辨識 JSP 頁面的變更，但不會辨識 servlet 或 JavaBean 類別的變更 - 此指令會告知 Tomcat 重新啟動目前安裝的應用程式，以便辨識此類變更。

  • remove - 當您完成開發與測試活動時，您可以選擇告知 Tomcat 從服務中移除此應用程式。

使用開發與測試目標需要一些額外的單次設定，這些設定會在下一頁中說明。