异常和 HTTP 状态代码

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

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

message = 'No entity with the id "%s" exists.' % entity_id
raise endpoints.NotFoundException(message)

Endpoints Frameworks 提供的异常

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

异常 对应的 HTTP 状态代码
endpoints.BadRequestException HTTP 400
endpoints.UnauthorizedException HTTP 401
endpoints.ForbiddenException HTTP 403
endpoints.NotFoundException HTTP 404
endpoints.InternalServerErrorException HTTP 500

受支持的 HTTP 状态代码

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

HTTP 状态代码 支持
HTTP 2xx 如果 API 方法成功返回，则 Endpoints Frameworks 通常会显示 HTTP 200。
如果 API 方法响应类型为 VoidMessage 或 API 方法的返回值为 None，则系统会将 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 状态代码创建其他异常类，可以通过创建 endpoints.ServiceException 子类来实现。以下代码段演示了如何创建表示 HTTP 409 状态代码的异常类：

import endpoints
import httplib

class ConflictException(endpoints.ServiceException):
  """Conflict exception that is mapped to a 409 response."""
  http_status = httplib.CONFLICT