Fejlhåndtering

I denne artikel:


Attention   

 

Introduktion

Når der opstår fejl, svarer API'et med detaljeret information omkring hvad der gik galt, samt hvilken del af forespørgslen der forårsagede fejlen. Et fejl response kan høre under en af følgende to kategorier: Interne fejl og valideringsfejl.

Uanset typen af fejl, vil svaret altid være struktureret på samme måde, og indeholde en message post som beskriver fejlen, samt en category post som beskriver fejltypen, og en locations post som beskriver hvilket sted i forespørgslen fejlen opstod. Ligeledes suppleres med path, som viser stien til forespørgslen eller mutationen i den pågældende request som skabte fejlen –dette kan være nyttigt hvis flere forespørgsler eller mutationer er samlet i én request.

 

Fejl under afvikling af mutationer

Hvis der opstår fejl under en mutation, annulleres alle ændringer som udføres af den pågældende request. Derfor vil, uanset grunden til fejlen, alle data forblive uændret, som hvis mutationen slet ikke var blevet eksekveret. Dette sikrer integriteten af dine data, og gør systemets aktuelle tilstand gennemskuelig på alle tidspunkter.

 

Interne fejl

Opstår en serverfejl, vil du blive præsenteret for en fejl i stil med følgende:


{
  "errors": [
    {
      "message": "Internal server error",
      "category": "internal",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "orders"
      ]
    }
  ],
  "data": []
}

 

Valideringsfejl

En anden type fejl er valideringsfejl. Denne fejltype opstår hvis de supplerede data er ugyldige. Følgende eksempel demonstrerer dette ved, at forsøge at oprette en side inde i en mappe der ikke eksisterer:

POST


mutation {
  pageCreate(input: {folderId: 123, type: text}) {
    id
  }
}

Endpoint:
{shop_domain}.mywebshop.io/api/graphql

Response


{
  "errors": [
    {
      "message": "The given data was invalid.",
      "category": "graphql",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "pageCreate"
      ],
      "validation": {
        "input.folderId": [
          "validation.exists"
        ]
      }
    }
  ],
  "data": []
}

I tilfælde af valideringsfejl, vil errors posten i det returnerede response også indeholde en validation sektion, som opregner alle valideringsfejl indekseret ud fra stien til de ugyldige data i inputtet.

 

Valideringsfejl V2

Fremover vil vi konvertere alle eksisterende valideringsfejl, så hver valideringsfejl vises i den kontekst hvor fejlen opstod. Vi opnår dette ved at indkapsle outputtet fra en mutation i et "payload" objekt, som indeholder de tidligere returnerede data fra mutationen, sammen med et array af fejl som opstod under mutationen. For at muliggøre en overgangsperiode, hvor bagudkompatabiliteten opretholdes, vil den nye version af disse mutationer tilføjes endelsen V2. Så, i stedet for en mutation, f.eks. pageCreate der returnerer et Page objekt, vil den (i fremtiden) returnere et PageCreatePayload objekt. Den nye struktur for pageCreateV2 mutationen vil derfor se således ud:


     mutation pageCreateV2(input: PageCreateInput!): PageCreateV2Payload!
    

-hvor payload har følgende struktur:


    type PageCreateV2Payload {
         data: Page
         errors: [PageTreeClientError!]!
    }
    

Til gengæld indeholder hver PageTreeClientError følgende:


    type PageTreeClientError {
        field: [String!]!
        message: String!
        code: PageTreeClientErrorCode!
    }
    

Bemærk at payload har et nullable data felt. Derfor, hvis en mutation var forventet at returnere et non-null objekt, er dette objekt nu ikke længere påkrævet i output. Som udvikler kunne du derfor bruge data feltet til at kontrollere, om alt gik som forventet. Det tilrådes imidlertid, at du i stedet benytter errors feltet, da nogle mutationer muligvis allerede muliggør et null return. Fremover vil det altid være tilfældet, at hvis errors feltet er en tom liste, så er der ikke opstået nogen valideringsfejl under mutationen.

På baggrund af eksemplet ovenfor, ved hjælp af den nye struktur, vil det se således ud:

POST {your_shop}.mywebshop.io/api/graphql


        
    mutation {
        pageCreateV2(input: {folderId: 123, type: "text"}) {
            data {
              id
            }
            errors {
              field
              message
              code
            }
        }
    }
    

Response


        
    {
        "pageCreateV2": {
          "data": null,
          "errors": [
            {
               "field": [
                  "pageCreateV2",
                  "input",
                  "folderId",
                ],
                "message": "No folder with id '123' exists.",
                "code": "ENTITY_NOT_FOUND"
                }
            ]
        }
    }
    

Med denne forbedrede struktur, vil det nu være mulight at få mere information om hvad der gik galt. Derudover, ved at benytte det maskinlæsbare code felt er det muligt for udviklere at benytte lokalisering til at forbedre feedback til klienter.