使用 Apache Maven 和 App Engine 插件(基于 Cloud SDK)

本页面介绍如何使用 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。

前期准备

  1. 使用 Google Cloud Console 创建并设置 Cloud 项目:

    转到 App Engine

    1. 选择或创建新的 Cloud 项目。
    2. 如果您需要为项目创建 App Engine 应用,请按照提示选择要放置 App Engine 应用的区域
  2. 下载并安装 Cloud SDK,然后初始化 gcloud 命令行工具。

    如果您已安装 gcloud 命令行工具,并且想要将其设置为使用其他 Cloud 项目 ID 而非初始化时设置的 Cloud 项目 ID,请参阅管理 Cloud SDK 配置

  3. 安装 Cloud SDK app-engine-java 组件:
    gcloud components install app-engine-java

    注意:要确保安装了最新的 Java 版 Cloud SDK,请运行 gcloud components update

  4. 如果您没有安装 Java,请下载 Java,然后进行安装和配置。
  5. 在项目的 pom.xml 中设置 Java 编译器标志,以指定 Java 8 字节代码:
    <properties>
          <maven.compiler.source>1.8</maven.compiler.source>
          <maven.compiler.target>1.8</maven.compiler.target>
        </properties>
  6. 您必须已安装 Apache Maven 3.3.9 或更高版本。 要确定您的 Maven 版本,请运行以下命令:
     mvn -v
  7. 如果您尚未安装相应版本的 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.2.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 会提示您提供项目的 groupIdartifactIdversionpackage

术语 含义
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 原型项目,请执行以下操作:

  1. 将目录切换到要用于构建项目的目录。

  2. 运行以下 Maven 命令:

    mvn archetype:generate -Dgoogle-cloud-project=[YOUR-PROJECT-ID] -Dappengine-plugin=2.2.0 -Dendpoints-frameworks=2.0.7 -Dendpoints-plugin=1.0.0 -Dappengine-sdk=1.9.80 -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 插件。
  3. 提供与 hello-endpoints-archetype 对应的数字。

  4. 从显示的可用原型版本列表中选择最新版本。

  5. 当系统提示 Define value for property 'groupId' 时,提供应用的命名空间;例如,提供值 com.example.helloendpoints

  6. 当系统提示 Define value for property 'artifactId' 时,提供项目名称;例如,提供值 helloendpoints

  7. 当系统提示 Define value for property 'version' 时,接受默认值。

  8. 当系统提示 Define value for property 'package' 时,接受默认值。

  9. 当系统提示您确认选择时,通过输入 Y 接受默认值。

  10. 等待项目生成过程完成。然后,将目录切换至新的项目目录,例如,helloendpoints/

  11. 构建项目。

    mvn clean package
        
  12. 等待项目构建。项目成功构建后,系统将显示如下消息:

    [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] ------------------------------------------------------------------------
        
  13. 要在本地测试项目并将其部署到 App Engine 标准环境,请查看管理、测试和部署 Maven 项目

  14. 此外,您可以使用 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 原型创建的应用,请执行以下操作:

  1. 切换到您的项目的主目录,例如 guestbook/

  2. 运行 Maven:

    mvn clean package
        
  3. 等待项目构建。项目成功构建后,系统将显示如下消息:

    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 应用,请执行以下操作:

  1. 构建应用(如果您尚未执行此操作):

    mvn clean package
        
  2. 在本地运行示例:

    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
        
  3. 使用浏览器转到 http://localhost:8080/ 以访问您的应用。

  4. Control+C 关闭应用和开发服务器。

指定本地测试的端口

当您在本地开发服务器中运行自己的应用时,默认端口为 8080。您可以通过修改 appengine-maven-plugin 的插件条目来更改此默认端口。例如,您可以在应用目录的 pom.xml 文件中指定端口和地址:

<plugins>
   <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>2.2.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 插件目标和参数

后续步骤