异常和 HTTP 状态代码

本页列出了 endpoints 库提供的异常以及由 Cloud Endpoints Frameworks 支持的 HTTP 状态代码。

很多情况下，您可能想要使用常见的 HTTP 状态代码来指示用户 API 请求的成功或失败。例如，当用户尝试检索不存在的实体时，您可能希望发送 HTTP 404 状态代码，表示不存在 ID 为 entityId 的实体。

您可以通过抛出 endpoints 库提供的异常来发送常见的 HTTP 状态代码，如下所示：

throw new NotFoundException(user.getEmail());

Endpoints Frameworks 提供的异常

Endpoints Frameworks 提供了以下异常，这些异常与特定的 HTTP 状态代码相对应：

异常 对应的 HTTP 状态代码
com.google.api.server.spi.response.BadRequestException HTTP 400
com.google.api.server.spi.response.UnauthorizedException HTTP 401
com.google.api.server.spi.response.ForbiddenException HTTP 403
com.google.api.server.spi.response.NotFoundException HTTP 404
com.google.api.server.spi.response.ConflictException HTTP 409
com.google.api.server.spi.response.InternalServerErrorException HTTP 500
com.google.api.server.spi.response.ServiceUnavailableException HTTP 503

受支持的 HTTP 状态代码

Cloud Endpoints Frameworks 支持在 API 响应中使用部分 HTTP 状态代码。下表介绍了受支持的代码。

HTTP 状态代码 支持
HTTP 2xx 如果 API 方法成功返回，则 Endpoints Frameworks 通常会显示 HTTP 200。
如果 API 方法响应类型为 void 或 API 方法的返回值为 null，则系统会将 HTTP 状态代码设置为 HTTP 204。
HTTP 3xx 不支持 HTTP 3xx 代码。使用任何 HTTP 3xx 代码将导致 HTTP 404 响应。
HTTP 4xx 仅支持以下 HTTP 4xx 代码：
  • 400
  • 401
  • 403
  • 404
  • 409
  • 410
  • 412
  • 413
任何其他 HTTP 4xx 代码都将以错误 404 的形式返回，但以下情况除外：
  • 405 返回为 501
  • 408 返回为 503
HTTP 5xx 在客户端响应中，所有 HTTP 5xx 状态代码都会被转换为 HTTP 503。

创建自定义异常类

如果您要为其他 HTTP 状态代码创建其他异常类，则需要对 com.google.api.server.spi.ServiceException 划分子类。以下代码段演示如何创建表示 HTTP 408 状态代码的异常类：

import com.google.api.server.spi.ServiceException;

// Exceptions must inherit from ServiceException
public class RequestTimeoutException extends ServiceException {
  public RequestTimeoutException(String message) {
    super(408, message);
  }
}

使用不受支持的 HTTP 状态代码

您可以使用不在前述受支持列表中的 HTTP 状态代码。请注意，这样做可能会给访问该 API 的客户端库带来意外后果。要使用不受支持的错误代码，请参照上一部分内容创建您自己的异常类，并向 EndpointsServlet 添加新的 servlet 初始化参数 enableExceptionCompatibility：

  <servlet>
    <servlet-name>com.google.api.server.spi.EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
      <param-name>services</param-name>
      <param-value>...</param-value>
    </init-param>
    <init-param>
      <param-name>enableExceptionCompatibility</param-name>
      <param-value>true</param-value>
    </init-param>
  </servlet>