使用 Apache Maven 和 App Engine 外掛程式 (以 App Engine SDK 為基礎)

本頁說明如何使用 Apache Maven 這個軟體專案管理和全方位工具來管理 App Engine 專案。這項工具能夠建構 WAR 檔案以部署至 App Engine 中。Google 提供 Maven 3.5 隨附的外掛程式與 Maven Archetypes。

使用 Maven 時,您不需要從 App Engine SDK 手動下載 Java 程式庫。必要時,Maven 會自動下載適當的程式庫。您也可以使用 Maven 在本機測試應用程式,並將應用程式部署至實際工作環境中的 App Engine。

設定 Maven

設定 Java

  1. 如果您沒有 Java,請下載、安裝並進行設定。
  2. pom.xml 中設定編譯器標記,指定 Java 7 位元組程式碼或 Java 8 位元組程式碼。請參閱下面分頁以瞭解相關設定。請注意,App Engine Java 7 執行階段需要 Java 7 位元組程式碼。

安裝 Maven 3.5

如要確認是否已安裝 Maven,以及安裝的版本為何,請叫用以下指令:

 mvn -v

如果您未安裝適當的 Maven 版本:

  1. 從 Maven 網站下載 Maven 3.5。
  2. 在您的本機電腦上安裝 Maven 3.5。

設定及驗證您的 GCP 專案

您需要設定 GCP 專案並安裝 App Engine SDK:

  1. 使用 Google Cloud Platform 主控台建立並設定您的 GCP 專案:

    前往 App Engine

    1. 選取或建立新的 GCP 專案。
    2. 如果您需要為專案建立 App Engine 應用程式,系統會提示您選取要讓 App Engine 應用程式位在哪個地區
    3. 在專案中建立 App Engine 應用程式之後,系統會開啟「Dashboard」(資訊主頁)
  2. 安裝 Java 適用的 App Engine SDK 並將目錄新增至您的路徑

使用 Maven

將 App Engine 外掛程式新增至現有的專案 (選用)

如要將 Google App Engine Maven 外掛程式新增至現有 Maven 專案,請將以下內容新增至專案 pom.xml 檔案的 plugins 區段中:

<plugin>
   <groupId>com.google.appengine</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>1.9.76</version>
</plugin>

選擇原型

Maven Archetypes 可讓使用者使用範本來建立 Maven 專案。這些範本涵蓋一些常見的情境。App Engine 利用這項 Maven 功能在 Maven Central 提供一些有用的 App Engine 原型。請選取適合您應用程式的 App Engine 原型:

應用程式類型 成果 說明
App Engine 應用程式 guestbook-archetype 產生完整且可以開始執行及測試的留言板示範範例。
App Engine 應用程式 appengine-skeleton-archetype 產生全新、空白的 App Engine 專案,包含您的類別和資源所需的檔案和目錄。

建立新專案

在專案建立期間,Maven 會提示您提供專案的 groupIdartifactIdversionpackage

字詞 意義
groupId Maven 中的命名空間,可追蹤您的成果。當使用者在他們的 Maven 專案中使用您的專案時,groupId 將做為最終指定的依存性屬性。
artifactId 您的專案在 Maven 中的名稱。當您專案的使用者在自己的 Maven 專案中依賴您時,也會指定該名稱。
version 您要專案產生的初始 Maven 版本。建議您在 version 後面加上 -SNAPSHOT,這樣做可協助辨識在 Maven 版本外掛程式中正在開發的版本。詳情請參閱 Maven 指南的「使用版本外掛程式」一文。
package 在產生期間建立的 Java 套件。

以下程序說明如何使用 App Engine Maven 原型來建立 App Engine 應用程式。

如要建立 App Engine 應用程式:

  1. 將目錄變更為要建構專案的目錄。

  2. 叫用以下 Maven 指令:

     mvn archetype:generate -Dappengine-version=1.9.76 -Djava8=true -DCloudSDK_Tooling=false -Dapplication-id=your-app-id -Dfilter=com.google.appengine.archetypes:
    

    -Dappengine-version 設定為 Java 適用的 App Engine SDK 的最新版本,並將 application-id 設定為 GCP 專案的 ID。

    設定 -Djava8=false 以在 Java 7 執行階段中部署專案。

    設定 -Djava8=true 以在 Java 8 執行階段中部署專案。

    設定 -DCloudSDK_Tooling=false 以使用 Java 適用的 App Engine SDK 工具。

  3. 系統提示您選擇原型時,請針對 App Engine 架構原型選擇值 2。 這樣會建立包含所需目錄結構與檔案的空白專案。

  4. 系統提示輸入版本時,請按 ENTER 來選取預設的最新版本。

  5. 系統提示您 Define value for property 'groupId' 時,請為您的應用程式提供所需命名空間,例如 com.mycompany.myapp

  6. 系統提示您 Define value for property 'artifactId' 時,請提供專案名稱,例如 myapp

  7. 系統提示您 Define value for property 'version' 時,請接受預設值。

  8. 系統提示您 Define value for property 'package' 時,請提供您的偏好套件名稱 (或接受預設值)。產生的 Java 檔案會使用您在這裡指定的套件名稱。

  9. 系統提示您確認選擇時,請接受預設值 (Y)。

  10. 等待專案完成建立必要的目錄和檔案,然後前往新的專案目錄,例如 myapp/

    專案成功完成時,您將會看到類似以下內容的訊息:

    [INFO] --------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] --------------------------------------------------
    [INFO] Total time: 1:16.656s
    [INFO] Finished at: 2017-06-04T16:18:24-07:00
    [INFO] Final Memory: 16M/228M
    [INFO] --------------------------------------------------
    
  11. 開始為自己的應用程式類別編寫程式碼前,請先確認基本專案配置及必要的專案檔案是否完成:在您建立專案所在的目錄中會有一個名為 myapp 的子目錄,其中包含 pom.xml 檔案、src/main/java 子目錄與 src/main/webapp/WEB-INF 子目錄:

    Maven 專案配置

    • 建議您將自己的應用程式 Java 類別新增至 src/main/java/...
    • 建議您使用 src/main/webapp/WEB-INF/appengine-web.xml 檔案設定應用程式
    • 建議您使用 src/main/webapp/WEB-INF/web.xml 檔案設定應用程式部署
  12. 建立應用程式 Java 類別並將這些類別新增至 src/main/java/.../ 詳情請參閱在 App Engine 上建立應用程式一文

  13. 新增您要提供給應用程式使用者的 UI。詳情請參閱處理表單資料一文。

  14. 您用來建立專案的成果已為您完成基本 src/main/webapp/WEB-INF/appengine-web.xml 設定。但是,如要進行更進一步的設定,可能需要編輯這個檔案。詳情請參閱使用 appengine-web.xml 設定

  15. 編輯 src/main/webapp/WEB-INF/web.xml 檔案,將網址對應至您的應用程式處理常式、指定驗證、篩選器等。這會在部署作業描述元中詳細說明。

管理 Maven 專案

編譯和建構專案

如何建構使用 Maven App Engine 原型建立的應用程式:

  1. 將目錄變更至專案的主目錄,例如 guestbook/
  2. 叫用 Maven:

    mvn clean package
    
  3. 等待專案建構完成。專案成功完成時,您將會看到類似以下內容的訊息:

    BUILD SUCCESS
     Total time: 10.724s
     Finished at: Thur Jul 04 14:50:06 PST 2017
     Final Memory: 24M/213M
    
  4. 您也可以選擇使用以下程序來測試應用程式。

使用開發伺服器測試您的應用程式

在開發階段,您可以透過叫用 App Engine Maven 外掛程式,隨時在開發伺服器中執行和測試您的應用程式。程序會因建立專案所用的成果而略有不同。

如何測試應用程式:

  1. 如果您尚未建構應用程式 (mvn clean package),請先建構應用程式。

  2. 將目錄變更至專案的頂層目錄 (例如 myapp),並叫用 Maven:

    mvn appengine:devserver
    

    等待伺服器啟動。伺服器完全啟動且您的應用程式正在執行時,您會看到類似以下內容的訊息:

    Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
    INFO: The server is running at http://localhost:8080/
    Aug 24, 2017 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
    INFO: The admin console is running at http://localhost:8080/_ah/admin
    
  3. 使用瀏覽器造訪 http://localhost:8080/ 以存取應用程式。

  4. 在您啟動應用程式與開發伺服器所在的 Windows/Linux 終端機視窗中按下 Control+C 鍵,或在 Mac 中按下 CMD+C 鍵,關閉應用程式與開發伺服器。

指定用於本機測試的通訊埠

在本機開發伺服器中執行應用程式時,預設通訊埠為 8080。您可以修改 appengine-maven-plugin 的外掛程式項目 (如果外掛程式項目不存在,也可以新增一個外掛程式項目),來變更此預設值。例如,我們可在主應用程式目錄 pom.xml 檔案 (myapp/pom.xml) 的 <plugins> 內,於下列 <plugin> 項目中指定通訊埠與位址:

 <plugin>
     <groupId>com.google.appengine</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>1.9.76</version>
     <configuration>
         <enableJarClasses>false</enableJarClasses>
         <port>8181</port>
         <address>0.0.0.0</address>
     </configuration>
 </plugin>

請注意,<port> 會如圖所示將這裡的通訊埠設定為 8181,並指定 0.0.0.0 位址,這代表開發伺服器將會接聽來自本機網路的要求。

部署您的應用程式

請參閱部署應用程式指南。

參考資料:可用目標

將 App Engine Maven 外掛程式新增至專案的 pom.xml 檔案之後,便可達成數項 App Engine 特定 Maven 目標。如要查看所有可用目標,請叫用以下指令:

 mvn help:describe -Dplugin=appengine

App Engine Maven 外掛程式目標可以分類成開發伺服器目標、應用程式與專案管理目標,以及端點目標。

開發伺服器目標

開發伺服器目標如下:

appengine:devserver

這個指令可以執行 App Engine 開發伺服器。當伺服器正在執行時,會持續檢查確認 appengine-web.xml 是否已變更。若已變更,伺服器會對應用程式執行熱重載。這表示您不需要因為變更了 appengine-web.xml 而停止應用程式後再重新啟動應用程式。可用參數如下:

  • <fullScanSeconds>
  • <address>
  • <disableUpdateCheck>
  • <jvmFlags>
  • <port>
  • <server>

例如,如要在偵錯模式下於通訊埠 8000 啟用執行伺服器,而不在開始階段暫停使用,您可以使用下列標記:

<jvmFlags>
  <jvmFlag>-Xdebug</jvmFlag>
  <jvmFlag>-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n</jvmFlag>
</jvmFlags>

根據預設,<fullScanSeconds> 標記設定為 5 秒,這表示伺服器會每 5 秒檢查一次網路應用程式檔案的變更,並自動重新載入應用程式。這對於支援「在儲存時編譯」功能的 IDE (例如 NetBeans) 而言很實用。如要使用這項功能,您必須設定 <build> 區段:

<build>
   <outputDirectory>target/${project.artifactId}-${project.version}/WEB-INF/classes</outputDirectory>
   <plugins>
      ....
   </plugins>
</build>
appengine:devserver_start

這個指令會針對開發伺服器執行非同步啟動,然後返回指令列。當此目標執行時,除了 Maven 會持續處理目標,並在伺服器啟動並執行後結束以外,所有行為都與 devserver 目標相同。

appengine:devserver_stop

這個指令會停止開發伺服器。您必須使用 appengine:devserver_start 啟動開發伺服器才能使用。

應用程式管理目標

應用程式與專案管理的目標已列在下表中:

目標 說明 對應的 gcloud 指令
appengine:backends_stop 這個指令會依照 pom.xml 檔案中的設定,停止在通訊埠接聽的任何執行中開發伺服器。這個目標可搭配 devserver_start 指令使用,配合 Maven 外掛程式執行整合測試。
appengine:backends_configure 設定指定的後端。
appengine:backends_delete 刪除指定的後端。
appengine:backends_rollback 復原之前正在進行的更新。
appengine:backends_start 啟動指定的後端。
appengine:backends_update 更新指定的後端或 (如未指定後端) 所有後端。
appengine:enhance 這個指令會執行 App Engine Datanucleus JDO 強化工具。
appengine:rollback 復原進行中的更新。 gcloud app versions startgcloud app versions stop
appengine:set_default_version 設定預設應用程式版本。 gcloud app services set-traffic
appengine:update 建立或更新應用程式版本。 gcloud app deploy
appengine:update_cron 更新應用程式 Cron 工作。 gcloud app deploy
appengine:update_dispatch 更新應用程式分派設定。 gcloud app deploy
appengine:update_dos 更新應用程式 DoS 保護設定。 gcloud app deploy
appengine:update_indexes 更新應用程式索引。 gcloud datastore create-indexes [INDEX_YAML]
appengine:update_queues 更新應用程式工作佇列定義。 gcloud app deploy
appengine:vacuum_indexes 從應用程式中刪除未使用的索引。 gcloud datastore cleanup-indexes [INDEX_YAML]
appengine:start_module_version 啟動指定的模組版本。 gcloud app versions start
appengine:stop_module_version 停止指定的模組版本 gcloud app versions stop

疑難排解上傳錯誤

如果使用更新目標,您的更新嘗試可能會失敗,並顯示類似以下內容的訊息:404 Not Found This application does not exist (app_id=u'your-app-ID')。 如果您有多個 Google 帳戶,並且正在使用錯誤的帳戶執行更新,就會發生這個錯誤。

如要解決這個問題,請將目錄變更為 ~,找到 .appcfg_oauth2_tokens_java 檔案,並重新命名這個檔案。然後重新嘗試更新。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Java 適用的 App Engine 標準環境