设置开发环境

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

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

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

准备工作

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. 记下 Google Cloud 项目 ID，因为以后需要它。

安装和配置所需的软件

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

   Maven

   1. 下载 Apache Maven 3.3.9 或更高版本
   2. 为您的本地开发环境安装并配置 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 定义了将 API 部署到 使用 Java 8 的 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 的必需类。
• 您需要使用 App Engine 标准 API SDK (appengine-api-sdk) 将项目部署到 App Engine 标准环境。
• 构建 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。
• 详细了解支持的参数和返回类型。