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

本页面介绍了如何使用 Apache Maven(一个软件项目管理和理解工具)管理 App Engine 项目。它能够构建用于部署到 App Engine 中的 WAR 文件。Google 提供了一个插件和 Maven 3.5 中附带的 Maven 原型。

当您使用 Maven 时,不需要从 App Engine SDK 中手动下载 Java 库。Maven 会在必要时自动下载相应的库。您还可以使用 Maven 在本地测试应用,并将应用部署到正式版 App Engine。

设置 Maven

配置 Java

  1. 如果您没有 Java,请下载、安装和配置 Java。
  2. pom.xml 中设置编译器标志,以指定 Java 8 字节码。
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

安装 Maven 3.5

要确定是否安装了 Maven 以及您使用的是哪个版本,请调用以下命令:

 mvn -v

如果您没有安装相应版本的 Maven,请执行以下操作:

  1. 从 Maven 网站下载 Maven 3.5。
  2. 在本地机器上安装 Maven 3.5。

设置并验证 Cloud 项目

您需要设置 Cloud 项目并安装 App Engine SDK:

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

    转到 App Engine

    1. 选择或创建新的 Cloud 项目。
    2. 如果您需要为项目创建 App Engine 应用,系统会提示您选择要放置 App Engine 应用的区域
    3. 当您在项目中创建 App Engine 应用后,信息中心会打开。
  2. 安装 Java 版 App Engine SDK,并将目录 添加到 PATH 中。

使用 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.88</version>
</plugin>

选择原型

Maven 原型允许用户使用涵盖常见场景的模板创建 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 项目中使用您的项目,那么他们最终将需要为相关依赖项指定此属性。
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.88 -Djava8=true -DCloudSDK_Tooling=false -Dapplication-id=your-app-id -Dfilter=com.google.appengine.archetypes:
    

    -Dappengine-version 设置为最新版本的 Java 版 App Engine SDK,并将 application-id 设置为您的 Cloud 项目 ID。

    设置 -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 项目布局

    • 您将向 src/main/java/... 添加自己的应用 Java 类
    • 您将使用文件 src/main/webapp/WEB-INF/appengine-web.xml 配置应用
    • 您将使用文件 src/main/webapp/WEB-INF/web.xml 配置应用部署
  12. 创建您的应用 Java 类,并将其添加到 src/main/java/.../ 如需了解详情,请参阅在 App Engine 上构建应用

  13. 添加您要为应用用户提供的界面。如需了解详情,请参阅处理表单数据

  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.88</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

执行开发服务器的异步启动,然后返回到命令行。当此目标运行时,行为与 devserver 目标完全相同,但以下情况除外:Maven 继续处理目标,并在服务器启动并运行后退出。

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 的文件并重命名。然后再次尝试更新。