スキーマのカスタム機能

GraphQL仕様に提案された複数の機能がGato GraphQLにすでに実装されているため、待つ必要はありません。

スキーマのネームスペーシング

WooCommerceとEasy Digital DownloadsというプラグインがどちらもGraphQL API向けにProduct型を実装した場合、それらの型が競合するため、両プラグインを同時にインストールすることはできません。

スキーマのネームスペーシングを使用すると、すべての型名にネームスペースを付与することでスキーマ内の競合を回避できます。これにより、型ProductはそれぞれWoo_ProductとEDD_Productになり、これらの型を同一のスキーマに追加できるようになります。

この画像は、型EventとLocationに名前の衝突を防ぐためにプレフィックスEM_が付与されたネームスペース付きスキーマを示しています。

Namespaced schema

グローバルフィールド

グローバルフィールドとは、GraphQLスキーマのすべての型からアクセスできるフィールドのことです（定義は一度だけ行われます）。

GraphQLスキーマはPost、User、Commentなどの型と、Post.title、User.name、Comment.responsesなど各型で利用可能なフィールドを公開しています。これらのフィールドはエンティティから特定のデータを取得するという意味で「データ」を扱います。

Gato GraphQLはさらに、データではなく「機能」を提供する別の種類のフィールドも提供しています。

グローバルフィールドの例をいくつか示します。

_not
_if
_equals
_isEmpty
_echo
_sprintf
_arrayItem
_arrayAddItem
_arrayUnique
その他多数

機能フィールドは、WordPress外部に保存されたデータを取得したり、取得後にデータを加工したりする際に役立ちます。フィールドの値を必要な方法で変換でき、強力なデータのインポート/エクスポート機能を提供します。

機能フィールドはPostやUserなどの特定の型ではなく、スキーマ内のすべての型に属します。そのためGato GraphQLでは、これらを「グローバルフィールド」という名称で独自の方法として扱っています。

Field to input

同一クエリ内で、フィールドの値を取得し、加工して、別のフィールドへの入力として渡すことができます。

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

コンポーザブルディレクティブ

ディレクティブの入力がフィールドの出力と異なる場合、そのディレクティブをフィールドに適用できないことがよくあります。例えば、ディレクティブ@strUpperCaseは文字列を入力として受け取るため、文字列の配列を返すUser.capabilitiesフィールドには適用できません。

コンポーザブルディレクティブを使用すると、あるディレクティブが別のディレクティブを拡張してその動作を変更したり、不足を補ったりすることができます。これにより、入力や戻り値の型を変えるためだけにフィールドやディレクティブを複製する必要がなくなり、肥大化を防ぐことができます。

このクエリでは、ディレクティブ@underEachArrayItemが文字列の配列を反復処理し、ネストされたディレクティブ@strUpperCaseを各要素に適用することで型の不一致を解消しています。

query {
  users {
    capabilities
      @underEachArrayItem
        @strUpperCase
  }
}

マルチフィールドディレクティブ

パフォーマンスの向上や用途の拡大のために、ディレクティブを（1つだけでなく）複数のフィールドに適用できます。

有効にすると、すべてのディレクティブに引数affectAdditionalFieldsUnderPosが追加され、ディレクティブを適用する追加フィールドの相対位置を指定できるようになります。

例えば、次のクエリではディレクティブ@strTranslateはフィールドcontentにのみ適用されています。

query {
  posts {
    excerpt
    content @strTranslate
  }
}

フィールドexcerptにもディレクティブ@strTranslateを適用するには、ディレクティブ引数affectAdditionalFieldsUnderPosに値[1]を追加します（1はディレクティブ@strTranslateからフィールドexcerptへの相対位置です）。

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

フィールドおよびディレクティブ単位のバージョニング

スキーマとは独立して、フィールドとディレクティブを個別にバージョン管理できます。

スキーマ全体を変更する（変更されたフィールドやディレクティブの名前を変える必要がある）のではなく、次のことができます。

同一のフィールド名またはディレクティブ名で異なる実装を保持する
セマンティックバージョニングを使用してタグの下にレガシー実装を公開する
フィールド/ディレクティブ引数versionConstraintで特定のバージョンにアクセスする

プロアクティブフィードバック

トップレベルエントリextensionsを使用して、クエリへの応答で非推奨事項や警告に関するデータを送信できます。

非推奨事項： 非推奨事項は、イントロスペクション時だけでなく、非推奨フィールドが含まれるクエリの実行時にも返されます。
警告： 警告はノンブロッキングと見なせる問題です。つまり、クエリを壊すことなく改善の余地があることを示します。

例えば、次のクエリでは2つのフィールドが同じ動的変数名"prop"でエクスポートされており、警告が生成されます。

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

レスポンスにはwarningsセクション（extensions内）と対応するメッセージが含まれます。

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

機能：