GAE Java11环境中<app-engine-apis>元素识别失败求助

问题背景 #

2024年1月Java8停止支持前，我把运行很久的Google App Engine（GAE）Java8项目迁到Java11+标准环境，需要保留Datastore、Blobstore和Task Queues这些遗留捆绑服务。按照谷歌教程在app-engine.web.xml里加了<app-engine-apis>true</app-engine-apis>来启用App Engine API Jar，但用Android Studio的Gradle插件构建部署时，直接抛出异常：com.google.apphosting.utils.config.AppEngineConfigException: Unrecognized element <app-engine-apis>，部署失败，旧功能也没法保留。

环境与配置信息 #

环境参数 #

• Android Studio Giraffe 2022.3.1 Patch 4
• Gradle 7.4.2
• GAE标准环境
• Objectify 5

Gradle构建文件（build.gradle） #

apply plugin: 'java'
apply plugin: 'war'
apply plugin: 'com.google.cloud.tools.appengine'
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.1.0'
        classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.4.2'
    }
}

repositories {
    google()
    mavenCentral()
}

appengine {
    deploy {
        version = "GCLOUD_CONFIG"
        projectId = "GCLOUD_CONFIG"
    }
}

sourceCompatibility = JavaVersion.VERSION_11
targetCompatibility = JavaVersion.VERSION_11
dependencies {
    implementation (group: 'com.google.appengine', name: 'appengine-api-1.0-sdk', version: '2.0.0')
    implementation 'com.google.endpoints:endpoints-framework:2.2.2'
    implementation ('com.google.http-client:google-http-client-gson:1.40.1') {
        exclude (group: 'httpclient', module: 'httpclient')
    }
    implementation 'javax.inject:javax.inject:1'
    implementation 'javax.servlet:servlet-api:3.0-alpha-1'
    implementation 'javax.activation:javax.activation-api:1.2.0'
    implementation ('com.google.firebase:firebase-admin:8.1.0') {
        exclude (group: 'com.google.guava')
    }
    implementation 'com.google.guava:guava:31.0.1-jre'
    implementation (group: 'com.google.appengine.tools', name: 'appengine-gcs-client', version: '0.8.2')
    implementation 'com.googlecode.objectify:objectify:5.1.25'
    implementation "com.stripe:stripe-java:20.90.0"
}

app-engine.web.xml配置 #

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <application>my-fashion-project</application>
    <version>1</version>
    <runtime>java11</runtime>
    <app-engine-apis>true</app-engine-apis>   <!-- 引发异常的行 -->
    <threadsafe>true</threadsafe>
    <url-stream-handler>urlfetch</url-stream-handler>
<system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/logging.properties" />
    </system-properties>
<sessions-enabled>
        true
    </sessions-enabled>
<resource-files>
        <include path="/**.json" />
    </resource-files>
<automatic-scaling>
        <min-instances>1</min-instances>
   </automatic-scaling>
</app-engine-web-app>

web.xml配置 #

<?xml version="1.0" encoding="utf-8"?><web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
    <app-engine-apis>true</app-engine-apis>
<filter>
        <filter-name>ObjectifyFilter</filter-name>
        <filter-class>com.googlecode.objectify.ObjectifyFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>ObjectifyFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
<servlet>
        <servlet-name>EndpointsServlet</servlet-name>
        <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
        <init-param>
            <param-name>services</param-name>
            <param-value>
                com.myfashionserver.entities.MemberEndpoint,
                ............ (实体端点列表已省略) ............
            </param-value>
        </init-param>
    </servlet>
<servlet-mapping>
............ (Servlet映射列表已省略) ............
<security-constraint>
        <web-resource-collection>
            <web-resource-name>queue</web-resource-name>
            <url-pattern>/queue/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>admin</role-name>
        </auth-constraint>
    </security-constraint>
    <welcome-file-list>
        <welcome-file>blog.html</welcome-file>
    </welcome-file-list>
</web-app>

异常日志 #

com.google.apphosting.utils.config.AppEngineConfigException: Unrecognized element <app-engine-apis>

解决方案 #

1. 删除web.xml中的无效元素 #

<app-engine-apis>是app-engine-web.xml的专属配置，绝对不能放在web.xml里，直接删掉web.xml里的这一行：

<app-engine-apis>true</app-engine-apis>

2. 升级App Engine Gradle插件版本 #

你用的appengine-gradle-plugin:2.4.2版本太老，不支持Java11环境下的<app-engine-apis>元素。把插件版本升级到4.0.0及以上（建议用最新稳定版）：
修改buildscript中的依赖：

classpath 'com.google.cloud.tools:appengine-gradle-plugin:4.0.0'

3. 确认依赖配置有效 #

appengine-api-1.0-sdk:2.0.0版本是适配Java11的，当前依赖配置没问题，不用修改。

4. 清理后重新部署 #

• 执行Gradle的clean任务清理旧构建文件
• 重新运行appengineDeploy任务部署项目

关键说明 #

• Java11+的GAE标准环境中，<app-engine-apis>元素仅在app-engine-web.xml中有效，web.xml不识别该元素，这是引发异常的核心原因。
• 旧版本Gradle插件对Java11环境的兼容性差，升级插件是解决配置识别问题的必要步骤。

内容的提问来源于stack exchange，提问作者stylesom