Logo
Query-functies
Query-functiesAntwoordfout-trigger

Antwoordfout-trigger

Included in the “Power Extensions” bundle

Voeg expliciet een foutmelding toe aan de respons om het mislukken van het GraphQL-verzoek te activeren (wanneer een veld niet aan de verwachte voorwaarden voldoet).

Beschrijving

Deze module voegt velden en richtlijnen toe om fouten expliciet te activeren en waarschuwingen toe te voegen aan de GraphQL-respons.

Fouten

Het globale veld _fail en de richtlijn @fail, die een vermelding toevoegen aan de eigenschap errors in de respons, worden toegevoegd aan het GraphQL-schema.

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 kunnen ook het argument data ontvangen, om contextuele informatie in de foutrespons te bieden.

Deze schema-elementen zijn nuttig om expliciet aan te geven dat er een fout is in de uitgevoerde GraphQL-query, wanneer zo'n fout niet onder natuurlijke omstandigheden optreedt.

Vervolgens kunnen we in onze applicatie aan de clientzijde (zoals JavaScript met een headless-configuratie) controleren of de vermelding errors bestaat en op basis daarvan de GraphQL-respons verwerken of een foutmelding aan de gebruiker tonen:

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

Waarschuwingen

Het globale veld _warn en de richtlijn @warn, die een vermelding toevoegen aan de eigenschap warnings in de respons, worden toegevoegd aan het GraphQL-schema:

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 kunnen ook het argument data ontvangen, om contextuele informatie in de waarschuwingsrespons te bieden.

Deze schema-elementen zijn nuttig om aan te geven dat, hoewel de query succesvol is uitgevoerd, een bepaalde conditie niet verwacht was.

Voorbeelden

Het ophalen van een bericht met een niet-bestaand ID geeft van nature null terug. Als we deze situatie als een fout moeten behandelen, kunnen we de richtlijn @fail gebruiken:

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

In combinatie met de extensie Multiple Query Execution kunnen we dezelfde resultaten behalen met _fail (merk op dat operatie FailIfPostNotExists niet wordt uitgevoerd wanneer $postExists true is):

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
}

We kunnen _fail gebruiken om te controleren of de gebruiker met het opgegeven e-mailadres nog niet bestaat:

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

We kunnen _fail ook gebruiken om te controleren of het ophalen van gegevens van een externe API fouten heeft opgeleverd:

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