本页面介绍了如何安装捆绑服务并将其与适用于 App Engine 标准环境的最新支持的 Java 版本搭配使用。应用可以通过 App Engine API JAR 访问捆绑服务。
须知事项
请参阅您可以在最新支持的 Java 版本中调用的旧版捆绑服务 API 列表。
本页面要求您的应用运行 Java 11 或更高版本。如需将您的应用从第一代运行时迁移到第二代运行时,请查看 Java 8 和 Java 11+ 之间的区别以及迁移注意事项部分。
如果您使用的是旧版捆绑服务并且想要升级到 Java 21,请参阅升级现有应用以详细了解配置选项。
安装 App Engine API JAR
如需在受支持的最新 Java 应用中使用旧版捆绑服务,您必须使用 appengine-web.xml
文件(而不是 app.yaml
文件)来配置您的应用。
以下示例演示了如何针对 EE10 上的版本 21 及更高版本(默认)、EE8 上的版本 21 和版本 17 及更低版本在 appengine-web.xml
中添加配置设置。如需在默认配置上使用受支持的最新版本,您必须更新应用 servlet 和依赖项以包含 Jakarta
命名空间。如需详细了解配置选项,请参阅升级现有应用。
根据 Java 版本在 appengine-web.xml
文件中添加以下设置:
v21 及更高版本 (EE10)
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java21</runtime> <!-- or another supported version -->
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
v21 (EE8)
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java21</runtime>
<system-properties> <!-- run your apps on EE8 -->
<property name="appengine.use.EE8" value="true"/>
</system-properties>
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
v17 及更低版本
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<runtime>java17</runtime> <!-- or another supported version -->
<app-engine-apis>true</app-engine-apis>
</appengine-web-app>
如需将旧版捆绑服务指定为依赖项,请在 pom.xml
文件中添加以下行:
<dependency>
<groupId>com.google.appengine</groupId>
<artifactId>appengine-api-1.0-sdk</artifactId>
<version>2.0.4</version> <!-- or later-->
</dependency>
如果您的应用使用 web.xml
文件,您必须添加 <app-engine-apis>
元素并将其设置为 true
:
<app-engine-apis>true</app-engine-apis>
如需部署 Java 21 应用,请在已编译的预演 Web 应用上运行 mvn appengine:deploy
命令或 gcloud app deploy ~/my_app/WEB-INF/appengine-web.xml
命令。
Java 21 使用的默认入口点
在启动 Web 应用的 JVM 时,Java 21 应用可以从额外的用户配置受益。
用于启动 JVM 的默认入口点由 App Engine Buildpack 生成。从本质上讲,这相当于在 appengine-web.xml
文件中定义此入口点。例如:
java --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED -showversion -Xms32M -Xmx204M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com/google/apphosting/runtime/JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime
我们不建议更改此默认入口点,因为内存设置是根据实例类型(F1、F2、F4)和可用内存计算的。
默认情况下,我们使用 --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED
打开一些必要的 JDK API。
入口点特性
第二代 Java 版本的入口点可通过在 appengine-web.xml
配置文件中添加的用户定义环境变量进行自定义。
下表列出了可用于启用/停用/配置功能的环境变量以及默认值:
环境变量 | 说明 | 类型 | 默认 |
---|---|---|---|
CPROF_ENABLE |
Stackdriver Profiler | 布尔值 | false |
GAE_MEMORY_MB |
可用内存 | 大小 | 由 App Engine 或 /proc/meminfo -400M 设置 |
HEAP_SIZE_RATIO |
堆内存 | 百分比 | 80 |
HEAP_SIZE_MB |
可用堆 | 大小 | ${GAE_MEMORY_MB} 的 ${HEAP_SIZE_RATIO} % |
JAVA_HEAP_OPTS |
JVM 堆参数 | JVM 参数 | -Xms${HEAP_SIZE_MB}M -Xmx${HEAP_SIZE_MB}M |
JAVA_GC_OPTS |
JVM GC 参数 | JVM 参数 | -XX:+UseG1GC plus 配置 |
JAVA_USER_OPTS |
JVM 其他参数 | JVM 参数 | |
JAVA_OPTS |
JVM 参数 | JVM 参数 | 如下所示 |
如果未明确设置,则 JAVA_OPTS
默认设为:
JAVA_OPTS:=-showversion \
$JAVA_HEAP_OPTS \
$JAVA_GC_OPTS \
$JAVA_USER_OPTS
当 CPROF_ENABLE
为 true 时,默认入口点将 PROFILER_AGENT
添加为:
-agentpath:/opt/cprof/profiler_java_agent.so=--logtostderr
例如,如果您的应用代码需要更多 -add-opens
标志,您可以使用 appengine-web.xml
文件中定义的 JAVA_USER_OPTS
环境变量:
<env-variables>
<env-var name="JAVA_USER_OPTS" value="--add-opens java.base/java.util=ALL-UNNAMED" />
</env-variables>
迁移注意事项
如果您要迁移到第二代 Java 运行时,并且应用使用旧版捆绑服务,则应注意以下事项:
- 如需在第二代 Java 应用中测试旧版捆绑服务功能,您可以使用本地开发服务器。
- 与 Java 8 运行时不同,第二代 Java 运行时在实例内存中包含 JVM。如果您在日志中看到与内存相关的错误,请考虑在
appengine-web.xml
文件中增加实例类大小。 - 如果应用尝试调用第二代 Java 运行时未启用的 API,则会收到
com.google.apphosting.api.ApiProxy$FeatureNotEnabledException
错误。 - 在第二代 Java 运行时中,假定所有应用都是线程安全的。升级到 Java 11+ 运行时时,您必须移除
app.yaml
或appengine-web.xml
文件中的threadsafe
元素。
示例 (Datastore)
如需查看如何使用 Datastore 模式的 Firestore (Datastore) 的示例,请参阅 GitHub 中适用于 Java 11 的旧版捆绑服务的代码示例。