迁移到基于 Cloud SDK 的 Maven 插件

如果您使用的是基于 Java App Engine SDK 的插件 (com.google.appengine.appengine-maven),并且想要改为使用新的 Cloud SDK,请迁移到基于 Cloud SDK 的插件 (com.google.cloud.tools.appengine-maven)。

基于 Cloud SDK 的插件的优势

升级到新插件可以获享下列优势:

  • 使用与所有其他基于 Cloud SDK 的命令相同的身份验证凭据,这些凭据是通过标准 gcloud auth login 流程生成的。

  • 支持 App Engine 柔性环境。

  • 在标准 Cloud SDK 更新流程中自动更新本地开发服务器。

  • 支持独立于您的服务来部署 App Engine 服务(Cron、队列、DoS 和调度)配置。

显著差异

在迁移之前,请注意以下显著差异:

Cloud SDK 依赖项
除了 Java 之外,旧插件在运行时不需要任何特定的本地环境依赖项,但新插件要求您安装 Cloud SDK。
不生成 Endpoints 发现文档
新插件不会生成 Endpoints 发现文档,该功能由单独的插件提供。运行 Endpoints 后端的操作不再要求在构建步骤中生成此文件,因为服务器现在会在运行时生成它。只有当您需要为 iOS 或 Android 等操作系统生成客户端库时,才应该用到新插件。如需详细了解新插件,请查看迁移到适用于 App Engine 的 Endpoints Frameworks 指南。
不再支持 EAR 文件格式
新插件不再支持使用 EAR 文件格式同时运行和部署多项服务。
新的部署命令
旧插件通过调用 appcfg 命令来部署应用,而新插件使用新的 gcloud CLI 来进行部署。
不再包含 JPA/JDO Datanucleus 增强任务
新插件不支持任何类型的 Datanucleus 增强功能。如果您的项目使用旧插件中支持的 Datanucleus JDO 或 JPA 增强功能,则必须在迁移时单独配置第三方 Datanucleus(JDO 说明JPA 说明)Maven 插件。

支持使用 XML 配置文件,但不支持 YAML。

迁移到新插件

要迁移到新插件,请执行以下操作:

  1. 将基于 Cloud SDK 的插件添加到您的 pom.xml 文件中。

    <build>
        <plugins>
           [...]
              <plugin>
                <groupId>com.google.cloud.tools</groupId>
                <artifactId>appengine-maven-plugin</artifactId>
                <version>2.2.0</version>
                <configuration>
                    <projectId>your-project-ID-goes-here</projectId>
                    <version>1</version>
                </configuration>
            </plugin>
           [...]
        </plugins>
    </build>
    
  2. 在插件配置中指定目标 Google Cloud 项目 ID 以及服务和版本。新工具会忽略 appengine-web.xml 文件中的应用和版本元素。

  3. 通过运行和部署应用来测试新配置,步骤如下:

    1. 使用插件的完全限定名称来运行应用:

        mvn com.google.cloud.tools:appengine-maven-plugin:run
      
    2. 使用插件的完全限定名称来部署应用:

        mvn com.google.cloud.tools:appengine-maven-plugin:deploy
      

      如果您的 pom.xml 中仍包含旧的 appengine 插件,请务必给插件目标调用设置命名空间。

如果您具有自定义程度更高的配置,则应该在新插件中找到等效的暂存、本地运行和部署标志

验证一切都如预期正常工作后,请从 pom.xml 中移除 com.google.appengine appengine-maven-plugin,并从 appengine-web.xml 文件中移除应用和版本元素。

您现在可以使用缩短的表示法来调用新插件的目标:

mvn package appengine:deploy

迁移基于 EAR 的多服务配置

使用新插件,您无需将服务聚合到 EAR 包中。 相反,如果您要在本地测试服务,则可以单独运行每项服务,或采取一些额外步骤通过一个命令来运行多项服务。当您准备好部署服务时,可以单独部署这些服务,也可以根据项目的组织方式使用单个命令部署所有服务。

如需在本地运行多项服务,请使用您要运行的服务列表更新 appengine-maven-plugin。如果您的服务共享父级 POM,则可以将此列表添加到父级 POM 中的 appengine-maven-plugin。否则,请将列表添加到默认服务的 POM 中的 appengine-maven-plugin

要将服务列表添加到 appengine-maven-plugin,请执行以下操作:

  1. 为 EAR 软件包的 application.xml 中的每个 context-root,将 service 元素添加到 appengine-maven-plugin

    在每个 service 元素中,指定包含服务的爆炸式 WAR 的 target 子目录。

    例如:

    <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>appengine-maven-plugin</artifactId>
        <version>2.2.0</version>
        <configuration>
            <deploy.projectId>your-project-name</deploy.projectId>
            <deploy.version>your-project-version</deploy.version>
            <services>
                <!-- for each service in your EARs application.xml -->
                <service>
                    ${project.parent.basedir}/service-name/target/service-name-${project.version}
                </service>
                <service>
                    ${project.parent.basedir}/another-service/target/another-service-${project.version}
                </service>
            </services>
        </configuration>
    </plugin>
    

    如果您的目录结构如下所示:

     ~/my-ear/default-service/
     ~/my-ear/another-service/
    

    service 元素中的路径名称需要按以下方式呈现:

     <service>~/my-ear/default-service/target/default-service-1.0-SNAPSHOT</service>
     <service>~/my-ear/another-service/target/another-service-1.0-SNAPSHOT</service>
    
  2. 通过从默认服务目录运行以下命令来确认新配置是否有效:

    mvn package appengine:run
    
  3. 验证您的默认服务是否在本地运行所有服务后,请完全移除您的 EAR 包。

如果项目的根目录仅包含您的服务,您可以使用一个 mvn appengine:deploy 命令部署所有这些服务。您必须先将 appengine-maven-plugin 添加到父级 pom.xml 文件中。当您运行 mvn appengine:deploy 时,该命令会遍历每个项目的服务以查找其配置文件,然后部署每项服务。

基于 App Engine SDK 的 Maven 命令与基于 Cloud SDK 的 Maven 命令

下表展示了调用 Maven 插件的不同方式,具体取决于您使用的是基于 App Engine SDK 的 Maven 插件还是基于 Cloud SDK 的 Maven 插件。

操作 基于 App Engine SDK 基于 Cloud SDK
在本地运行应用 appengine:devserver appengine:run
部署新的应用、版本或服务。 appengine:update appengine:deployappengine:deployAll
设置默认的应用版本。 appengine:set_default_version gcloud app services set-trafficgcloud app versions migrate
更新应用 Cron 作业。 appengine:update_cron appengine:deployCron
更新应用调度配置。 appengine:update_dispatch appengine:deployDispatch
更新应用 DoS 防护配置。 appengine:update_dos appengine:deployDos
更新应用任务队列定义。 appengine:update_queues appengine:deployQueue
更新 Datastore 索引。 appengine:update_indexes appengine:deployIndex
删除应用中未使用的索引 appengine:vacuum_indexes gcloud datastore cleanup-indexes
启动指定的版本。 appengine:start_module_version gcloud app versions start
停止指定的版本。 appengine:stop_module_version gcloud app versions stop
回滚正在进行的更新。 appengine:rollback
请注意,您还可以将流量迁移回旧版本
gcloud app versions startgcloud app versions stop 或者使用 gcloud app services set-traffic 迁移回旧版本。