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

本頁說明如何使用 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 專案：

前往 App Engine
1. 選取或建立新的 GCP 專案。
2. 如果您需要為專案建立 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 位元組程式碼：

<properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
</properties>

您必須已安裝 Apache Maven 3.3.9 以上版本。如要判斷您的 Maven 版本，請執行以下指令：
```
 mvn -v
```
如果您未安裝適當的 Maven 版本：
1. 從 Maven 網站下載 Maven 3.3.9 以上版本。
2. 在您的本機電腦上安裝 Maven。
  附註：Linux 使用者可能需要下載 Maven，而非使用 apt-get install。

將 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 外掛程式。
附註：App Engine 適用的 Endpoints Frameworks 原型包含 Gradle 支援，並會使用每個依附元件的最新版本。
提供與 hello-endpoints-archetype 對應的號碼。

附註：如要建立空白專案，其中包含所需目錄結構和適用於您類別的檔案，請提供與 endpoints-skeleton-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 的基本專案配置圖：

Maven 專案配置

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 外掛程式一文，瞭解如何指定目標的參數。

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

上次更新：六月 21, 2019。