Logo
Query Functions
Query FunctionsAtivador de Erros na Resposta

Ativador de Erros na Resposta

Included in the “Power Extensions” bundle

Adiciona explicitamente uma entrada de erro à resposta para provocar a falha da requisição GraphQL (sempre que um campo não atende às condições esperadas).

Descrição

Este módulo adiciona campos e directives para acionar erros explicitamente, e adicionar avisos, que serão incluídos na resposta GraphQL.

Erros

O campo global _fail e a directive @fail, que adicionam uma entrada à propriedade errors na resposta, são adicionados ao schema 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"
    )
  }
}

Ambos também podem receber o argumento data, para fornecer informações contextuais na resposta de erro.

Esses elementos do schema são úteis para indicar explicitamente que ocorreu um erro na query GraphQL executada, quando tal erro não acontece em circunstâncias naturais.

Em seguida, em nossa aplicação no lado do cliente (como JavaScript com uma configuração headless), podemos verificar se a entrada errors existe e, com base nisso, processar a resposta GraphQL ou exibir uma mensagem de erro ao usuário:

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

Avisos

O campo global _warn e a directive @warn, que adicionam uma entrada à propriedade warnings na resposta, são adicionados ao schema 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")
  }
}

Ambos também podem receber o argumento data, para fornecer informações contextuais na resposta de aviso.

Esses elementos do schema são úteis para indicar que, mesmo que a query tenha sido executada com sucesso, alguma condição não era a esperada.

Exemplos

Recuperar um post com um ID inexistente retornará naturalmente null. Se precisarmos tratar essa condição como um erro, podemos usar a 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
  }
}

Em combinação com a extensão Multiple Query Execution, podemos obter os mesmos resultados usando _fail (observe que a operação FailIfPostNotExists não é executada quando $postExists é 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
}

Podemos usar _fail para garantir que o usuário com o e-mail fornecido ainda não exista:

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

Também podemos usar _fail para verificar se a recuperação de dados de uma API externa produziu erros:

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