Logo
Query Functions
Query FunctionsDéclencheur d'Erreurs dans la Réponse

Déclencheur d'Erreurs dans la Réponse

Included in the “Power Extensions” bundle

Ajoute explicitement une entrée d'erreur à la réponse pour provoquer l'échec de la requête GraphQL (lorsqu'un champ ne remplit pas les conditions attendues).

Description

Ce module ajoute des champs et des directives pour déclencher explicitement des erreurs, et ajouter des avertissements, qui seront inclus dans la réponse GraphQL.

Erreurs

Le champ global _fail et la directive @fail, qui ajoutent une entrée à la propriété errors dans la réponse, sont ajoutés au schéma GraphQL.

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"
    )
  }
}

Tous deux peuvent également recevoir l'argument data, pour fournir des informations contextuelles dans la réponse d'erreur.

Ces éléments de schéma sont utiles pour indiquer explicitement qu'il y a une erreur dans la requête GraphQL exécutée, lorsque cette erreur ne se produit pas dans des circonstances naturelles.

Ensuite, dans notre application côté client (comme JavaScript avec une configuration headless), nous pouvons vérifier si l'entrée errors existe et, en fonction de cela, traiter la réponse GraphQL ou afficher un message d'erreur à l'utilisateur :

/**
 * 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
  // ...
}

Avertissements

Le champ global _warn et la directive @warn, qui ajoutent une entrée à la propriété warnings dans la réponse, sont ajoutés au schéma GraphQL :

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")
  }
}

Tous deux peuvent également recevoir l'argument data, pour fournir des informations contextuelles dans la réponse d'avertissement.

Ces éléments de schéma sont utiles pour indiquer que, même si la requête s'est exécutée avec succès, une condition n'était pas celle attendue.

Exemples

Récupérer un article avec un ID inexistant retournera naturellement null. Si nous devons traiter cette condition comme une erreur, nous pouvons utiliser la directive @fail :

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

En combinaison avec l'extension Multiple Query Execution, nous pouvons obtenir les mêmes résultats en utilisant _fail (notez que l'opération FailIfPostNotExists ne s'exécute pas lorsque $postExists est true) :

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
}

Nous pouvons utiliser _fail pour nous assurer que l'utilisateur avec l'adresse e-mail donnée n'existe pas encore :

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")
{
  # ...
}

Nous pouvons également utiliser _fail pour vérifier si la récupération de données depuis une API externe a produit des erreurs :

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"
    }
  )
}