例外狀況與 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 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>