使用 Apache Maven 和 App Engine 插件（基于 Google Cloud CLI）

本页面介绍如何使用 Apache Maven 管理用于 Cloud Endpoints Frameworks API 的 App Engine 项目。 Apache Maven 是一款软件项目管理和理解工具，该工具能够构建用于部署到 App Engine 的 Web 应用归档 (WAR) 文件。Google 提供的插件和 Maven 原型适用于 Maven 3.3.9 或更高版本。

Maven 会从 App Engine SDK 下载 Java 库。您可以使用 Maven 在本地测试应用，并将其部署到 App Engine。

前期准备

使用 Google Cloud 控制台创建和设置 Google Cloud 项目：

转到 App Engine
1. 选择或创建新的 Google Cloud 项目。
2. 如果您需要为项目创建 App Engine 应用，请按照提示选择要放置 App Engine 应用的区域。
下载并安装 gcloud CLI，然后初始化 Google Cloud CLI。
如果您已安装 Google Cloud CLI，并希望将其设置为使用其他 Google Cloud 项目 ID，而不是初始化时设置的 Google Cloud 项目 ID，请参阅管理 gcloud CLI 配置。
安装 gcloud CLI app-engine-java 组件：
```
gcloud components install app-engine-java
```
注意：为确保您使用的是最新版本的 Java 版 gcloud CLI，请运行 gcloud components update。
如果您没有安装 Java，请下载 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.7.0</version>
</plugin>

选择 App Engine 原型

通过 Maven 原型，用户可使用涵盖常见场景的模板来创建 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 后端 API 项目生成一个入门级 Endpoints Frameworks，以备构建和运行之用。

使用 Maven 创建新项目

在项目创建期间，Maven 会提示您提供项目的 groupId、artifactId、version 和 package。

术语	含义
`groupId`	Maven 中用于跟踪工件的命名空间。如果用户在自己的 Maven 项目中使用您的项目，则他们将需要为相关依赖项指定此属性。
`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.7.0 -Dendpoints-frameworks=2.1.0 -Dendpoints-plugin=1.0.2 -Dappengine-sdk=1.9.98 -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 的简单界面。
base.js 包含在界面中发起后端请求所需的 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.7.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

App Engine Maven 插件中的 appengine:deploy 目标和其他所有目标都具有可供您使用的关联参数。如需查看目标和参数的完整列表，请参阅 App Engine Maven 插件目标和参数。

后续步骤

在 GitHub 上探索 App Engine Maven 插件代码并报告问题。
参阅 App Engine Maven 目标和参数，了解如何为目标指定参数。
在 GitHub 上探索 Endpoints Framework Maven 插件代码并报告问题。
参阅 Cloud Endpoints Frameworks Maven 插件，了解如何为目标指定参数。