Niestandardowe funkcje dla schematu

Wiele funkcji zaproponowanych do specyfikacji GraphQL zostało już zaimplementowanych w Gato GraphQL, więc nie musimy czekać.

Przestrzenie nazw schematu

Jeśli wtyczki WooCommerce i Easy Digital Downloads obie zaimplementowałyby typ Product dla API GraphQL, nie moglibyśmy zainstalować obu wtyczek jednocześnie, ponieważ ich typy wchodziłyby w konflikt.

Przestrzenie nazw schematu umożliwiają unikanie konfliktów w schemacie poprzez nadanie przestrzeni nazw wszystkim nazwom typów. Dzięki temu typ Product stałby się odpowiednio Woo_Product i EDD_Product, a te typy mogłyby zostać dodane do tego samego schematu.

Ten obraz pokazuje schemat z przestrzeniami nazw, w którym do typów Event i Location dodano prefiks EM_, aby uniknąć kolizji nazw:

Schemat z przestrzeniami nazw

Pola globalne

Pola globalne to pola dostępne we wszystkich typach schematu GraphQL (definiowane tylko raz).

Schemat GraphQL udostępnia typy, takie jak Post, User i Comment, oraz pola dostępne dla każdego typu, takie jak Post.title, User.name i Comment.responses. Pola te dotyczą "danych", ponieważ pobierają określony fragment danych z encji.

Gato GraphQL oferuje dodatkowo inny rodzaj pól: te dostarczające "funkcjonalności" zamiast danych.

Kilka przykładowych pól globalnych:

_not
_if
_equals
_isEmpty
_echo
_sprintf
_arrayItem
_arrayAddItem
_arrayUnique
i wiele więcej

Pola funkcjonalne są przydatne do pobierania danych przechowywanych poza WordPress oraz do manipulowania danymi po ich pobraniu, umożliwiając przekształcenie wartości pola w dowolny wymagany sposób i zapewniając nam potężne możliwości importu/eksportu danych.

Pola funkcjonalne nie należą do konkretnego typu, takiego jak Post czy User, lecz do wszystkich typów w schemacie. Dlatego są one obsługiwane w szczególny sposób w Gato GraphQL, pod nazwą "pól globalnych".

Field to input

Pobierz wartość pola, zmanipuluj ją i przekaż jako input do innego pola — wszystko w ramach tej samej query.

query {
  posts {
    excerpt
 
    # Referencing previous field with name "excerpt"
    isEmptyExcerpt: _isEmpty(value: $__excerpt)
 
    # Referencing previous field with alias "isEmptyExcerpt"
    isNotEmptyExcerpt: _not(value: $__isEmptyExcerpt)
  }
}

Dyrektywy kompozytowe

Często dyrektywa nie może zostać zastosowana do pola, ponieważ jej input różni się od danych wyjściowych pola. Na przykład dyrektywa @strUpperCase przyjmuje string jako input, więc nie można jej zastosować do pola User.capabilities, które zwraca tablicę stringów.

Dzięki dyrektywom kompozytowym jedna dyrektywa może wzmacniać inną dyrektywę, modyfikując jej zachowanie lub wypełniając lukę. Eliminuje to potrzebę duplikowania pól lub dyrektyw tylko po to, by zmienić ich typy wejściowe lub zwracane, co zapobiega nadmiernemu rozrostowi.

W tej query dyrektywa @underEachArrayItem iteruje po tablicy stringów i stosuje zagnieżdżoną dyrektywę @strUpperCase do każdego z nich, rozwiązując niezgodność typów:

query {
  users {
    capabilities
      @underEachArrayItem
        @strUpperCase
  }
}

Dyrektywy wielopolowe

Stosuj dyrektywy do wielu pól (zamiast tylko jednego), dla lepszej wydajności i rozszerzonych przypadków użycia.

Po włączeniu do wszystkich dyrektyw dodawany jest argument affectAdditionalFieldsUnderPos, w którym można określić relatywne pozycje dodatkowych pól, do których ma być stosowana dyrektywa.

Na przykład w poniższej query dyrektywa @strTranslate jest stosowana tylko do pola content:

query {
  posts {
    excerpt
    content @strTranslate
  }
}

Pole excerpt może również otrzymać dyrektywę @strTranslate, dodając argument dyrektywy affectAdditionalFieldsUnderPos z wartością [1] (ponieważ 1 jest relatywną pozycją pola excerpt względem dyrektywy @strTranslate):

query {
  posts {
    excerpt
    content
      @strTranslate(
        affectAdditionalFieldsUnderPos: [1]
      )
  }
}

Wersjonowanie pól i dyrektyw

Wersjonuj pola i dyrektywy niezależnie od schematu.

Zamiast rozwijać cały schemat (co wymaga modyfikacji nazwy zmienionego pola lub dyrektywy), możemy:

Utrzymywać różne implementacje pod tą samą nazwą pola lub dyrektywy
Udostępniać starszą implementację pod tagiem, stosując wersjonowanie semantyczne
Uzyskiwać dostęp do konkretnej wersji za pomocą argumentu pola/dyrektywy versionConstraint

Proaktywna informacja zwrotna

Użyj wpisu najwyższego poziomu extensions, aby wysłać dane dotyczące przestarzałości i ostrzeżeń w odpowiedzi na query.

Przestarzałości: Przestarzałości są zwracane w tej samej query zawierającej przestarzałe pola, a nie tylko podczas introspekcji.
Ostrzeżenia: Ostrzeżenia to problemy, które można uznać za nieblokujące, tzn. wzbogacają query, ale jej nie przerywają.

Na przykład poniższa query eksportuje dwa pola używając tej samej nazwy zmiennej dynamicznej "prop", co generuje ostrzeżenie:

query {
  posts {
    excerpt @export(as: "prop")
    content @export(as: "prop")
  }
}

Odpowiedź będzie zawierać sekcję warnings (pod extensions) z odpowiednim komunikatem:

{
  "extensions": {
    "warnings": [
      {
        "message": "Dynamic variable with name 'props' had already been set, had its value overridden",
        "locations": [
          {
            "line": 4,
            "column": 25
          }
        ]
      }
    ]
  },
  "data": {
    "posts": {
      "excerpt": "Hello world!",
      "Content": "<p>Hello world!</p>"
    }
  }
}

Funkcja: