设置开发环境

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

您可以使用使用 Apache Maven 和 App Engine 插件(基于 Cloud SDK)中所述的 endpoints-skeleton-archetypehello-endpoints-archetype 创建新的 Endpoints Frameworks 2.0 版项目。

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

准备工作

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册新帐号

  2. 在 Cloud Console 的项目选择器页面上,选择或创建 Cloud 项目。

    转到项目选择器页面

  3. 确保您的 Google Cloud 项目已启用结算功能。 了解如何确认您的项目已启用结算功能

  4. 记下 Google Cloud 项目 ID,稍后需要用到。

安装和配置所需的软件

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

    Maven

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

    Gradle

  3. 下载并初始化 Cloud SDK
  4. 运行以下命令:
    1. 确保 Cloud SDK 有权访问您在 Google Cloud 上的数据和服务:
      gcloud auth login
    2. 使用应用默认凭据:
      gcloud auth application-default login
    3. 安装 Cloud SDK app-engine-java 组件:
      gcloud components install app-engine-java
    4. 更新为 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 管理这些项目,请参阅管理 Cloud SDK 配置

    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/
        

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

    Endpoints Frameworks 框架示例布局

    • 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.1</version>
        </dependency>
        <dependency>
            <groupId>com.google.appengine</groupId>
            <artifactId>appengine-api-1.0-sdk</artifactId>
            <version>1.9.79</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>

应用插件

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

<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.2.3</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.2.0</version>
                <configuration>
                    <!-- deploy configuration -->
                </configuration>
            </plugin>
            <plugin>
                <groupId>com.google.cloud.tools</groupId>
                <artifactId>endpoints-framework-maven-plugin</artifactId>
                <version>2.0.1</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>

Gradle

插件依赖项

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

buildscript {
      repositories {
        mavenCentral()
      }

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

应用插件

在 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.0.9'
        compile 'com.google.appengine:appengine-api-1.0-sdk:1.9.59'

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

为您的服务定义主机名

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.0.1</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>

后续步骤