编写代码并为其添加注释

本页面介绍如何设计 Cloud Endpoints Frameworks 代码的结构并为其添加注释。如需查看所有受支持的注释的完整列表,请参阅注释

准备工作

  1. 设置您的开发环境
  2. 克隆 Endpoints Frameworks 框架示例:

     git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
    
  3. Endpoints Framework 框架示例位于:

     cd appengine-java8/endpoints-v2-skeleton/
    

为帮助说明注释的工作原理,本文档使用 endpoints-v2-backend 示例来显示注释和其他代码,您必须将注释和代码添加到 endpoints-v2-skeleton 示例才能完成构建。最后,修改后的 endpoints-v2-skeleton 示例的行为与 endpoints-v2-backend 示例相同,后者用于 App Engine 上的 Endpoints Frameworks 使用入门

创建代码和为代码添加注释

要为代码添加注释,请执行以下操作:

  1. 将目录更改为项目的 Java 源目录,例如:src/main/java/com/example/skeleton
  2. 创建一个名为 Message.java 并包含以下代码的 JavaBean 类文件:
    public class Message {
    
      private String message;
    
      public String getMessage() {
        return this.message;
      }
    
      public void setMessage(String message) {
        this.message = message;
      }
    }
  3. 修改框架示例中包含的 MyApi.java 文件。将 @Api 定义注释更改为以下内容:
    @Api(
        name = "echo",
        version = "v1",
        namespace =
        @ApiNamespace(
            ownerDomain = "echo.example.com",
            ownerName = "echo.example.com",
            packagePath = ""
        ),
        // ...
    )

    version = "v1" 属性指定了示例 API 的版本。您输入的值将成为 API 网址中路径的一部分。如需详细了解版本,请参阅处理 API 版本控制

  4. 将以下 echo 方法添加为您的第一个 API 端点,并将 doEcho 帮助程序方法添加到您的 MyApi.java
    @ApiMethod(name = "echo")
    public Message echo(Message message, @Named("n") @Nullable Integer n) {
      return doEcho(message, n);
    }
    private Message doEcho(Message message, Integer n) {
      if (n != null && n >= 0) {
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < n; i++) {
          if (i > 0) {
            sb.append(" ");
          }
          sb.append(message.getMessage());
        }
        message.setMessage(sb.toString());
      }
      return message;
    }
  5. Echo.java 复制所有导入项并将其粘贴到 MyApi.java 中。
  6. Maven

    构建项目:

    mvn clean package

    Gradle

    构建项目:

    gradle clean build

注释基础知识

后端 API 中有三种常用的注释:

  • @Api,包含后端 API 的配置详细信息。
  • @ApiMethod,标记属于后端 API 的类方法。当您生成客户端库和发现文档时,未使用 @ApiMethod 进行标记的方法不包括在内。@ApiMethod 注释也可用于替换特定方法的 API 配置。
  • @Named,除非参数是实体类型,否则必须将此注释添加到传递给服务器端方法的所有参数。

如需查看所有 Endpoints Frameworks 注释的完整列表,请参阅注释和语法

后续步骤