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

Cloud Endpoints Frameworks 支援在 API 回應中使用 HTTP 狀態碼子集。下表說明支援的狀態碼。

建立自己的例外狀況類別

如果您想為其他 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 的用戶端程式庫造成意外後果。如要使用不支援的錯誤代碼，請按照上一節所述建立自己的例外狀況類別，並將新的 servlet 初始化參數 enableExceptionCompatibility 新增至 EndpointsServlet：

  <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>