支持的参数和返回类型

本页面列出了可用作后端 API 方法的路径或查询参数中的 API 参数类型的数据类型，以及可用作方法返回类型或请求正文类型的类型。

支持的路径和查询参数类型

路径和查询参数支持的类型如下：

  • java.lang.String
  • java.lang.Boolean 和 boolean
  • java.lang.Integer 和 int
  • java.lang.Long 和 long
  • java.lang.Float 和 float
  • java.lang.Double 和 double
  • java.util.Date
  • com.google.api.server.spi.types.DateAndTime
  • com.google.api.server.spi.types.SimpleDate
  • 任何 enum
  • 此处列出的任何数组或 java.util.Collection 类型。不支持其他类型的数组或集合。

要将参数指定为路径或查询参数，请使用 @Named 对参数进行注释。例如：

public Resource get(@Named("id") int id) { … }

路径参数

路径参数是 @ApiMethod 注释的 path 属性中包含的方法参数。如果未指定 path，则未使用 @Nullable 或 @DefaultValue 注释的任何参数都将自动添加到路径中作为路径参数。例如：

public Resource get(@Named("id") int id) { … }

要手动将参数添加到 path，请将参数名称用 {} 标记括起来添加到路径中。手动添加到 path 的参数不能使用 @Nullable 或 @DefaultValue 进行注释。例如：

@ApiMethod(path = "resources/{id}")
public Resource get(@Named("id") int id) { … }

查询参数

查询参数是不包含在 @ApiMethod 注释的 path 属性中的方法参数。请注意，可选参数（即使用 @Nullable或@DefaultValue注释的参数）始终不会自动添加到 path，因此如果未指定 path，则这些可选参数会自动成为查询参数。例如：

public Resource get(@Named("id") @Nullable int id) { … }

如果指定了 path，则可以通过不在 path 中包含参数来使它们成为查询参数。例如：

@ApiMethod(path = "resources")
public Resource get(@Named("id") int id) { … }

注入的类型

注入的类型是受到 Cloud Endpoints Frameworks 特殊处理的类型。如果将此类型用作方法参数，则它不会成为 API 的一部分。相反，参数将由 Endpoints Frameworks 填充。

注入的类型如下所示：

  • com.google.appengine.api.users.User
  • javax.servlet.http.HttpServletRequest
  • javax.servlet.ServletContext

实体类型

在 Endpoints Frameworks 文档中，实体类型与 Java Beans 含义相同。您定义用于 API 的类必须符合以下条件：

  • 有一个不接受参数的公共构造函数。
  • 使用 getter 和 setter 控制对私有属性的访问。 此外，每个 setter 只能接受一个参数。

通常，实体类型也实现 Serializable，但这不是使用 Endpoints Frameworks 所必需的。

请勿将 @Named 注释用于实体类型参数。

请求正文

当您在方法中传递实体类型作为参数时，实体类型中的属性将映射到请求正文中的 JSON 字段。您的方法必须只包含一个实体类型参数。例如：

public Resource set(Resource resource) { … }

您可以在一个方法中包含多个非实体类型参数和一个实体类型参数。例如：

@ApiMethod(name = "echo")
public Message echo(Message message, @Named("n") @Nullable Integer n) { … }

在上面的示例中，message 参数中的属性会被映射到请求正文中的 JSON 字段。@Nullable 注释表示 n 参数是可选的，因此它作为查询参数传递。

响应对象

方法返回值必须是以下几种类型之一：

  • 实体类型
  • 通用类型
  • CollectionResponse (com.google.api.server.spi.response.CollectionResponse) 或 CollectionResponse 的一个子类

响应对象中的 JSON 字段是由返回值中的属性映射的。

@ApiTransformer 对类型的影响

如果您使用 @ApiTransformer，则需要注意转换如何影响类型。

@ApiTransformer 和参数类型

使用 @ApiTransformer 时，生成的方法参数是否被视为参数类型取决于转换结果而不是原始类型。如果将类型转换为参数类型，则该方法参数将被视为 API 参数，并且必须使用 @Named 进行注释。

@ApiTransformer 和实体类型

同样，方法参数或返回类型是否被视为实体类型取决于转换的结果，而不是原始类型。如果某类型被转换为实体类型，则该类型可以用作返回类型，并且用作方法参数时，它不能使用 @Named 进行注释，因为该类型会被视为实体类型。

@ApiTransformer 和注入的类型

注入的类型不受 @ApiTransformer 影响。仅当方法参数的原始非转换类型是注入类型时，该方法参数才会被视为注入的类型。