Logo
Query Functions
Query FunctionsAntwort-Fehler-Auslöser

Antwort-Fehler-Auslöser

Included in the “Power Extensions” bundle

Fügt der Antwort explizit einen Fehlereintrag hinzu, um das Fehlschlagen der GraphQL-Anfrage auszulösen (wenn ein Feld die erwarteten Bedingungen nicht erfüllt).

Beschreibung

Dieses Modul fügt dem GraphQL-Schema Felder und Direktiven hinzu, um Fehler explizit auszulösen und Warnungen zur GraphQL-Antwort hinzuzufügen.

Fehler

Das globale Feld _fail und die Direktive @fail, die einen Eintrag zur Eigenschaft errors in der Antwort hinzufügen, werden dem GraphQL-Schema hinzugefügt.

query {
  _fail(message: "Some error")
  
  posts {
    featuredImage @fail(
      # condition: IS_NULL, \<= This is the default value
      message: "The post does not have a featured image"
    ) {
      id
      src
    }
  }
  
  users {
    name @fail(
      condition: IS_EMPTY,
      message: "The retrieved user does not have a name"
    )
  }
}

Beide können auch das Argument data empfangen, um kontextbezogene Informationen in der Fehlerantwort bereitzustellen.

Diese Schema-Elemente sind nützlich, um explizit anzuzeigen, dass in der ausgeführten GraphQL-Abfrage ein Fehler aufgetreten ist, wenn dieser Fehler nicht unter natürlichen Umständen auftritt.

Anschließend können wir in unserer Anwendung auf der Client-Seite (z. B. JavaScript mit einem Headless-Setup) prüfen, ob der Eintrag errors vorhanden ist, und darauf basierend entweder die GraphQL-Antwort verarbeiten oder dem Benutzer eine Fehlermeldung anzeigen:

/**
 * If the response contains error(s), return a concatenated error message
 *
 * @param {Object} response A response object from the GraphQL server
 * @return {string|null} The error message or nothing
 */
const maybeGetErrorMessage = (response) => {
  if (response.errors && response.errors.length) {
    return sprintf(
      __(`The API produced the following error(s): "%s"`, 'gato-graphql'),
      response.errors.map(error => error.message).join( __('", "') )
    );
  }
  return null;
}
 
const maybeErrorMessage = maybeGetErrorMessage(response);
if (maybeErrorMessage) {
  // Show error to the user
  // ...
} else {
  // Process response
  // ...
}

Warnungen

Das globale Feld _warn und die Direktive @warn, die einen Eintrag zur Eigenschaft warnings in der Antwort hinzufügen, werden dem GraphQL-Schema hinzugefügt:

query {
  _warn(message: "Some warning")
  
  posts {
    id
    featuredImage {
      id
      src
    }
    doesNotHaveFeaturedImage: _isNull(value: $__featuredImage)
      @passOnwards(as: "doesNotHaveFeaturedImage")
      @if(condition: $doesNotHaveFeaturedImage)
        @warn(message: "The post does not have a featured image")
  }
}

Beide können auch das Argument data empfangen, um kontextbezogene Informationen in der Warnantwort bereitzustellen.

Diese Schema-Elemente sind nützlich, um anzuzeigen, dass eine Bedingung nicht erwartet wurde, obwohl die Abfrage erfolgreich ausgeführt wurde.

Beispiele

Das Abrufen eines Beitrags mit einer nicht vorhandenen ID gibt natürlicherweise null zurück. Wenn wir diese Bedingung als Fehler behandeln müssen, können wir die Direktive @fail verwenden:

query GetPost($id: ID!) {
  post(by:{id: $id})
    @fail(
      message: "There is no post with the provided ID"
      data: {
        id: $id
      }
    )
  {
    id
    title
  }
}

In Kombination mit der Erweiterung Multiple Query Execution können wir dieselben Ergebnisse mit _fail erzielen (beachte, dass die Operation FailIfPostNotExists nicht ausgeführt wird, wenn $postExists gleich true ist):

query GetPost($id: ID!) {
  post(by:{id: $id}) {
    id
    title
  }
  _notNull(value: $__post) @export(as: "postExists")
}
 
query FailIfPostNotExists($id: ID!)
  @skip(if: $postExists)
  @depends(on: "GetPost")
{
  errorMessage: _sprintf(
    string: "There is no post with ID '%s'",
    values: [$id]
  ) @remove
  _fail(
    message: $__errorMessage
    data: {
      id: $id
    }
  ) @remove
}

Wir können _fail verwenden, um sicherzustellen, dass der Benutzer mit der angegebenen E-Mail-Adresse noch nicht existiert:

query EnsureUserDoesNotExist($userEmail: Email!) {
  user( by: { email: $userEmail } ) {
    _fail(
      message: "User with given email already exists"
      data: {
        email: $userEmail
      }
    )
  }
}
 
mutation CreateUser($userData: JSONObject!)
  @depends(on: "EnsureUserDoesNotExist")
{
  # ...
}

Wir können _fail auch verwenden, um zu prüfen, ob das Abrufen von Daten aus einer externen API Fehler erzeugt hat:

query ConnectToExternalGraphQLAPI($endpoint: String!, $query: String!) {
  externalData: _sendGraphQLHTTPRequest(
    input: {
      endpoint: $endpoint
      query: $query
    }
  ) @export(as: "externalData")
  _propertyIsSetInJSONObject(
    object: $__externalData
    by: {
      key: "errors"
    }
  ) @export(as: "endpointHasErrors")
}
 
query FailIfExternalAPIHasErrors($endpoint: String!)
  @include(if: $endpointHasErrors)
  @depends(on: "ConnectToExternalGraphQLAPI")
{
  errorMessage: _sprintf(
    string: "Connecting to endpoint %s produced errors",
    values: [$endpoint]
  ) @remove
  data: _objectProperty(
    object: $externalData,
    by: {
      key: "errors"
    }
  ) @remove
  _fail(
    message: $__errorMessage
    data: {
      endpoint: $endpoint
      endpointData: $__data
    }
  ) @remove
}
 
query GetExternalAPIData
  @skip(if: $endpointHasErrors)
  @depends(on: "ConnectToExternalGraphQLAPI")
{
  data: _objectProperty(
    object: $externalData,
    by: {
      key: "data"
    }
  )
}