本頁說明如何使用 Apache Maven 管理 Cloud Endpoints Frameworks API 的 App Engine 專案。Apache Maven 是軟體專案管理與理解工具,可用來建構網路應用程式封存 (WAR) 檔案以部署至 App Engine。Google 提供 Maven 3.3.9 以上版本支援的外掛程式和 Maven Archetypes。
Maven 會從 App Engine SDK 下載 Java 程式庫。您可以使用 Maven 在本機上測試您的應用程式,並將其部署至 App Engine。
事前準備
- 使用 Google Cloud Platform 主控台建立並設定您的 GCP 專案:
- 選取或建立新的 GCP 專案。
- 如果您需要為專案建立 App Engine 應用程式,請按照系統提示,選取要放置 App Engine 應用程式的地區。
- 下載並安裝 Cloud SDK,然後初始化
gcloud
指令列工具。如果您已安裝
gcloud
指令列工具,並想將其設為使用與初始化時不同的 GCP 專案 ID,請參閱管理 Cloud SDK 設定一文。 - 安裝 Cloud SDK
app-engine-java
元件:gcloud components install app-engine-java
附註:為確保您有最新版本的 Java 適用 Cloud SDK,請執行
gcloud components update
。 - 如果您沒有 Java,請下載、安裝並進行設定。
- 在您專案的
pom.xml
中設定 Java 編譯器標記,指定 Java 8 位元組程式碼: - 您必須已安裝 Apache Maven 3.3.9 以上版本。如要判斷您的 Maven 版本,請執行以下指令:
mvn -v
- 如果您未安裝適當的 Maven 版本:
將 App Engine Maven 外掛程式新增至現有的專案 (選用)
如要在現有的 Maven 專案中使用 App Engine Maven 外掛程式,請將以下內容新增至專案 pom.xml
檔案的 plugins
區段中:
<plugin>
<groupId>com.google.cloud.tools</groupId>
<artifactId>appengine-maven-plugin</artifactId>
<version>2.0.0</version>
</plugin>
選擇 App Engine 的原型
Maven Archetypes 可讓使用者利用範本建立 Maven 專案。這些範本涵蓋一些常見的情境。App Engine 利用這項 Maven 功能,在 Maven Central 提供了一些有用的 App Engine 原型。請選取適合您應用程式的 App Engine 原型:
應用程式類型 | 成果 | 說明 |
---|---|---|
App Engine 適用的 Endpoints Frameworks | endpoints-skeleton-archetype |
產生全新、空白、適用於 App Engine 的 Endpoints Frameworks 後端 API 專案,包含您的類別和資源所需的檔案和目錄。 |
App Engine 適用的 Endpoints Frameworks | hello-endpoints-archetype |
產生 App Engine 適用的入門用 Endpoints Frameworks 後端 API 專案,可直接用來建構和執行。 |
使用 Maven 建立新的專案
在專案建立期間,Maven 會提示您提供專案的 groupId
、artifactId
、version
和 package
。
字詞 | 意義 |
---|---|
groupId |
Maven 中的命名空間,可追蹤您的成果。當使用者在他們的 Maven 專案中使用您的專案時,groupId 將做為最終指定的依存性屬性。 |
artifactId |
您的專案在 Maven 中的名稱。當您專案的使用者在自己的 Maven 專案中依賴您的專案時,也會指定該名稱。 |
version |
您要用來產生專案的初始 Maven 版本。建議您在 version 後面加上 -SNAPSHOT ,這樣做可在 Maven 版本外掛程式中針對開發中的版本提供支援。請參閱 Maven 指南進一步瞭解如何使用版本外掛程式。 |
package |
在產生期間建立的 Java 套件。 |
建立新的 Endpoints Frameworks 應用程式
本節說明如何建立新的 Endpoints Frameworks 2.0 版專案。
hello-endpoints-archetype
提供外掛程式的使用範例,包括 App Engine Maven 外掛程式和 Endpoints Frameworks Maven 外掛程式。
hello-endpoints-archetype
會使用 Endpoints Frameworks 2.0 版產生範例 Greetings API,同時會做為將 Endpoints Frameworks 1.0 版應用程式遷移至 Endpoints Frameworks 2.0 版的範例。
使用原型產生的 README.md
可以提供遷移發生處的資訊。
如何建立 App Engine 適用的 Endpoints Frameworks 後端 API 的原型專案:
將目錄變更為要建構專案的目錄。
執行以下 Maven 指令:
mvn archetype:generate -Dgoogle-cloud-project=[YOUR-PROJECT-ID] -Dappengine-plugin=2.0.0 -Dendpoints-frameworks=2.0.7 -Dendpoints-plugin=1.0.0 -Dappengine-sdk=1.9.76 -Dfilter=com.google.appengine.archetypes:
其中:
-Dgoogle-cloud-project
要設為您的專案 ID。-Dappengine-plugin
要設為最新版本的 App Engine Maven 外掛程式。-Dendpoints-frameworks
要設為最新版本的 App Engine 適用 Endpoints Frameworks Maven 依附元件。-Dendpoints-plugin
要設為最新版本的 App Engine 適用 Endpoints Frameworks Maven 外掛程式。
提供與
hello-endpoints-archetype
對應的號碼。從隨即顯示的可用原型版本清單中,選取最新版本。
當系統提示您
Define value for property 'groupId'
時,請為您的應用程式提供命名空間,例如,提供com.example.helloendpoints
值。當系統提示您
Define value for property 'artifactId'
時,請提供專案名稱,例如,提供helloendpoints
值。當系統提示您
Define value for property 'version'
時,請接受預設值。當系統提示您
Define value for property 'package'
時,請接受預設值。系統提示您確認選擇時,請輸入
Y
接受預設值。等待專案產生完畢,然後將目錄變更為新的專案目錄,例如
helloendpoints/
。建構專案。
mvn clean package
等待專案建構完成。專案成功完成時,您會看到如下的訊息:
[INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 4.062 s [INFO] Finished at: 2017-02-28T00:28:03-08:00 [INFO] Final Memory: 27M/485M [INFO] ------------------------------------------------------------------------
如要在本機進行測試並將專案部署至 App Engine 標準環境,請參閱管理、測試和部署 Maven 專案一文。
此外,您也可以使用 Endpoints Frameworks Maven 外掛程式為 Greeting API 產生 Java 用戶端程式庫:
mvn endpoints-framework:clientLibs
以下是 Greetings API 的基本專案配置圖:
README.md
包含與產生的範例相關的資訊。Greetings.java
包含範例 Greetings API 的 API 定義。Constants.java
包含範例 Greetings API 中使用的常數。HelloGreeting.java
包含一個容器,用來裝載透過範例 Greetings API 接收和傳送的訊息。index.html
包含用來呼叫後端 Greetings API 的簡單 UI。base.js
包含 UI 發出後端要求所需的 JavaScript。- 產生
build.gradle
後,該範例也將支援 Gradle,且README.md
中會提供更多有關這項功能的資訊。
編譯和建構您的應用程式
如何建構使用 Maven App Engine 原型建立的應用程式:
變更至專案的主目錄,例如
guestbook/
。執行 Maven:
mvn clean package
等待專案建構完成。專案成功完成時,您會看到如下的訊息:
BUILD SUCCESS Total time: 10.724s Finished at: 2016-08-04T16:18:24-07:00 Final Memory: 24M/213M
使用開發伺服器測試您的應用程式
在開發階段,您隨時可執行 App Engine Maven 外掛程式,在開發伺服器中執行和測試您的應用程式。
如何測試您的 App Engine 適用 Endpoints Frameworks 應用程式:
如果您尚未建構應用程式,請先進行建構作業:
mvn clean package
在本機執行範例:
mvn appengine:run
等待伺服器啟動。當伺服器完全啟動且應用程式開始執行時,您會看到如下的訊息:
[INFO] GCLOUD: INFO ### devappserver2.py:764] Skipping SDK update check. [INFO] GCLOUD: INFO ### api_server.py:268] Starting API server at: http://localhost:34199 [INFO] GCLOUD: INFO ### dispatcher.py:199] Starting module "default" running at: http://localhost:8080 [INFO] GCLOUD: INFO ### admin_server.py:116] Starting admin server at: http://localhost:8000 [INFO] GCLOUD: ### com.google.appengine.tools.development.SystemPropertiesManager setSystemProperties
使用瀏覽器前往
http://localhost:8080/
存取應用程式。按下
Control+C
鍵關閉應用程式和開發伺服器。
指定用於本機測試的通訊埠
在本機開發伺服器中執行您的應用程式時,預設通訊埠為 8080
。您可以透過修改 appengine-maven-plugin
的外掛程式項目來變更此預設值。例如,您可以在應用程式目錄的 pom.xml
檔案中指定通訊埠和位址:
<plugins>
<plugin>
<groupId>com.google.cloud.tools</groupId>
<artifactId>appengine-maven-plugin</artifactId>
<version>2.0.0</version>
<configuration>
<devserver.host>0.0.0.0</devserver.host>
<devserver.port>8181</devserver.port>
</configuration>
</plugin>
</plugins>
在此範例中,<devserver.port>
會將通訊埠設定為 8181
而非預設值,並指定 0.0.0.0
位址,這代表開發伺服器會接聽來自本機網路的要求。
前置字串 devserver
為選用項目,您可以改用 <port>8181</port>
。
在開發伺服器上偵錯
如要對在本機上執行的應用程式進行偵錯,請在外掛程式設定中設定 jvmFlags
,以在基礎 JVM 上啟用偵錯功能,例如:
<configuration>
<jvmFlags>
<jvmFlag>-Xdebug</jvmFlag>
<jvmFlag>-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005</jvmFlag>
</jvmFlags>
</configuration>
部署應用程式
如何部署您的應用程式:
mvn appengine:deploy
appengine:deploy
目標和 App Engine Maven 外掛程式中的所有其他目標都具有您可以使用的關聯參數。如需目標和參數的完整清單,請參閱 App Engine Maven 外掛程式的目標和參數一文。
後續步驟
- 探索 App Engine Maven 外掛程式程式碼,並在 GitHub 上回報問題。
- 參閱 App Engine Maven 的目標和參數一文,瞭解如何指定目標的參數。
- 探索 Endpoints Frameworks Maven 外掛程式程式碼,並在 GitHub 上回報問題。
- 參閱 Cloud Endpoints Frameworks Maven 外掛程式一文,瞭解如何指定目標的參數。