设置开发环境

本页面介绍如何设置开发环境，以便使用适用于 App Engine 标准环境的 Cloud Endpoints Frameworks 构建和部署后端 API。本页面使用 Endpoints Frameworks 2.0 版框架代码示例来说明入门所需的基本软件和组件。

您可以使用使用 Apache Maven 和 App Engine 插件（基于 Google Cloud CLI）中所述的 endpoints-skeleton-archetype 或 hello-endpoints-archetype 创建新的 Endpoints Frameworks 2.0 版项目。

若想更好地了解使用 Endpoints Frameworks 部署示例 API 所需的步骤，请参阅《使用入门：在 App Engine 上使用 Endpoints Frameworks》教程。

准备工作

1. 登录您的 Google Cloud 账号。如果您是 Google Cloud 新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

2. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

3. 确保您的 Google Cloud 项目已启用结算功能。

4. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

5. 确保您的 Google Cloud 项目已启用结算功能。

6. 记下 Google Cloud 项目 ID，因为稍后您会用到该信息。

安装和配置所需的软件

1. 如果您尚未安装 Java 8，请从 Oracle 网站下载并安装 Java Development Kit (JDK)。
2. 安装 Maven 或 Gradle：

   Maven

   1. 下载 Apache Maven 3.3.9 或更高版本
   2. 为您的本地开发环境安装并configure Maven。

   Gradle

   • 安装 Gradle。
3. 下载并初始化 Google Cloud CLI。
4. 运行以下命令：
   1. 确保 gcloud CLI 有权访问您在 Google Cloud 上的数据和服务：

      gcloud auth login

   2. 使用应用默认凭据：

      gcloud auth application-default login

   3. 安装 Google Cloud SDK app-engine-java 组件：

      gcloud components install app-engine-java

   4. 更新为 Google Cloud SDK 和所有组件的最新版本：

      gcloud components update

5. 创建 App Engine 应用：
   1. 将默认项目设置为您的 Google Cloud 项目 ID：

      gcloud config set project YOUR_PROJECT_ID

      将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。如果您有其他 Google Cloud 项目，并且想用 gcloud 管理这些项目，请参阅管理 gcloud CLI 配置。

   2. 选择要在其中创建 App Engine 应用的区域。请参阅 App Engine 位置查看区域列表。
   3. 创建 App Engine 应用。将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID，并将 YOUR_REGION 替换为您要在其中创建 App Engine 应用的区域。

        gcloud app create \
        --project=YOUR_PROJECT_ID \
        --region=YOUR_REGION
      

获取 Endpoints Frameworks 框架示例

Endpoints Frameworks 2.0 版框架示例包含 Maven 和 Gradle 所需的构建脚本。该示例还包含开始创建第一个 API 所需的文件。

1. 将示例代码库克隆到您的本地机器：

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples
   

2. 切换到包含 Endpoints Frameworks 框架示例的目录：

    cd java-docs-samples/appengine-java8/endpoints-v2-skeleton/
   

   该示例使用以下目录结构：

   

   • MyApi.java 包含一个空类，您可使用此空类开始编写 API。如需示例代码帮助入门，请参阅 echo 示例。

   • web.xml 是用于配置 Servlet 的标准文件。

   • appengine-web.xml 定义了使用 Java 8 将 API 部署到 App Engine 标准环境所需的信息。

   • pom.xml 包含 Maven 用来构建项目并将 API 部署到 App Engine 的项目和配置信息。

   • build.gradle 包含 Gradle 用来构建项目并将 API 部署到 App Engine 的项目和配置信息。

配置构建文件

本部分介绍示例代码中包含的 Maven pom.xml 和 Gradle build.gradle 文件。您可以随时使用构建文件来开始创建 API，但需要输入您的 Google Cloud 项目 ID 以用作主机名。

关于最低配置

本部分介绍构建文件中所需的最低配置。

Maven

最低依赖项

下面显示了开始操作时 pom.xml 中必需的最低依赖项：

<dependencies>
  <!-- Compile/runtime dependencies -->
  <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.2</version>
  </dependency>
  <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>2.0.23</version>
  </dependency>
  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <type>jar</type>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>javax.inject</groupId>
    <artifactId>javax.inject</artifactId>
    <version>1</version>
  </dependency>
</dependencies>

• endpoints-framework 依赖项包含用于创建 API 的必需类。
• 您需要 <atrack-type="tasks" l10n-attrs-original-order="href,track-type,track-name,track-metadata-position" l10n-encrypted-href="8uk1g2YxVmQFExiHWQoDVLU3uURKQq2GHK/Q1ZkBJNo=" track-metadata-position="body" track-name="internalLink">App Engine Standard API SDK (appengine-api-sdk) 才能将您的项目部署到 App Engine 标准环境。</atrack-type="tasks">
• 构建 Servlet 需要使用标准 javax.servlet 软件包。
• 支持依赖项注入需要使用标准 javax.inject 软件包。

应用插件

应用以下插件以启用它们：

<build>
  <!-- for hot reload of the web application-->
  <outputDirectory>${project.build.directory}/${project.build.finalName}/WEB-INF/classes</outputDirectory>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <version>3.4.0</version>
      <configuration>
        <webResources>
          <resources>
            <directory>${basedir}/src/main/webapp/WEB-INF</directory>
            <filtering>true</filtering>
            <targetPath>WEB-INF</targetPath>
          </resources>
        </webResources>
      </configuration>
    </plugin>
    <plugin>
      <groupId>com.google.cloud.tools</groupId>
      <artifactId>appengine-maven-plugin</artifactId>
      <version>2.5.0</version>
      <configuration>
        <!-- deploy configuration -->
        <projectId>GCLOUD_CONFIG</projectId>
        <version>GCLOUD_CONFIG</version>
      </configuration>
    </plugin>
    <plugin>
      <groupId>com.google.cloud.tools</groupId>
      <artifactId>endpoints-framework-maven-plugin</artifactId>
      <version>2.1.0</version>
      <configuration>
        <!-- plugin configuration -->
        <!--
        You must replace YOUR_PROJECT_ID with your
        Google Cloud Project Id
      -->
        <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
      </configuration>
    </plugin>
  </plugins>
</build>

• maven-war-plugin 扩展 java 插件以支持组合 Web 应用。
• 在 App Engine 上运行 API 需要使用 appengine-maven-plugin。
• endpoints-framework-maven-plugin 提供用于构建 Endpoints Frameworks 项目的任务和配置。

Gradle

插件依赖项

以下代码显示了构建 API 所需的插件：

buildscript {
  repositories {
    mavenCentral()
  }

  dependencies {
    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.1.0'
    classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.5.0'
  }
}

• Endpoints Frameworks Gradle 插件用于生成 OpenAPI 文档以及生成客户端库。
• 将项目部署到 App Engine 需要 App Engine Gradle 插件。

应用插件

在 Gradle 构建脚本中应用以下插件以启用它们：

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

• java 插件可为项目添加特定于 Java 的编译和构建步骤。
• war 扩展 java 插件以支持组合 Web 应用。
• endpoints-framework-server 插件可为 Endpoints Frameworks Gradle 插件提供服务器端支持。
• 要在 App Engine 上运行 API，必须使用 appengine 插件。

项目依赖项

项目使用以下依赖项：

dependencies {
    compile 'com.google.endpoints:endpoints-framework:2.2.2'
    compile 'com.google.appengine:appengine-api-1.0-sdk:2.0.23'

    compile 'javax.inject:javax.inject:1'
    compileOnly 'javax.servlet:javax.servlet-api:3.1.0'
}

• endpoints-framework 依赖项包含用于创建 API 的必需类。
• 将项目部署到 App Engine 标准环境需要使用 App Engine 标准 API SDK (appengine-api-sdk)。
• 构建 Servlet 需要使用标准 javax.servlet 软件包。
• 支持依赖项注入需要使用标准 javax.inject 软件包。

为您的服务定义主机名

Endpoints Frameworks 使用符合 DNS 规范的名称来唯一地识别服务。由于 Google Cloud 项目 ID 必须保持全局唯一，因此建议您将 Google Cloud 项目 ID 用作 API 服务名称的一部分。

您必须将 Google Cloud 项目 ID 添加到构建文件中，以配置服务的主机名。主机名应采用以下格式：

YOUR_PROJECT_ID.appspot.com

将 API 部署到 App Engine 时，系统会自动创建名称格式为 YOUR_PROJECT_ID.appspot.com 的 DNS 条目。主机名既是 Cloud Endpoints 服务的名称，也是您用于向 API 发送请求的域名。

Maven

<plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>endpoints-framework-maven-plugin</artifactId>
  <version>2.1.0</version>
  <configuration>
    <!-- plugin configuration -->
    <!--
    You must replace YOUR_PROJECT_ID with your
    Google Cloud Project Id
  -->
    <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
  </configuration>
</plugin>

在 hostname 字段中，将 YOUR_PROJECT_ID 替换为您的 Google Cloud 项目 ID。

Gradle

// You must replace YOUR_PROJECT_ID with your Google Cloud Project Id
def projectId = 'YOUR_PROJECT_ID'

endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "${projectId}.appspot.com"
}

将变量 projectID 设置为您的 Google Cloud 项目 ID。例如：def projectId = 'example-project-12345'

配置 Endpoints Servlet

Endpoints Servlet 会处理传入请求，并将这些请求转发到 App Engine 上运行的后端服务。为了实现由 Endpoints 管理您的 API，您必须使用 Endpoints Servlet。

如需详细了解 web.xml，请参见部署描述符：web.xml。

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <!-- Wrap the backend with Endpoints Frameworks v2. -->
    <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.example.skeleton.MyApi</param-value>
        </init-param>
    </servlet>
    <!-- Route API method requests to the backend. -->
    <servlet-mapping>
        <servlet-name>EndpointsServlet</servlet-name>
        <url-pattern>/_ah/api/*</url-pattern>
    </servlet-mapping>
</web-app>

配置 App Engine 部署

在部署 API 时，appengine-web.xml 文件用于定义 App Engine 标准环境配置。如需了解详情，请参见 appengine-web.xml 参考文档。

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <runtime>java8</runtime>
    <threadsafe>true</threadsafe>

    <system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
    </system-properties>
</appengine-web-app>

后续步骤

• 编写后端 API 代码并为其添加注释。
• 详细了解注释。
• 添加 API 管理。
• 部署并测试您的 API。
• 详细了解支持的参数和返回类型。