本页列出了 endpoints
库提供的异常以及由 Cloud Endpoints Frameworks 支持的 HTTP 状态代码。
很多情况下,您可能想要使用常见的 HTTP 状态代码来指示用户 API 请求的成功或失败。例如,当用户尝试检索不存在的实体时,您可能希望发送 HTTP 404
状态代码,表示不存在 ID 为 entityId
的实体。
您可以通过抛出 endpoints
库提供的异常来发送常见的 HTTP 状态代码,如下所示:
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 代码:
404 的形式返回,但以下情况除外:
|
HTTP 5xx | 在客户端响应中,所有 HTTP 5xx 状态代码都会被转换为 HTTP 503 。 |
创建自定义异常类
如果您要为其他 HTTP 状态代码创建其他异常类,则需要对 com.google.api.server.spi.ServiceException
划分子类。以下代码段演示如何创建表示 HTTP 408
状态代码的异常类:
使用不受支持的 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>