Directives: ディレクティブ

Those are called directives and are the primary way to add functionality to your GraphQL schema.

これまでの章を読み終わっていれば、もうスキーマ定義の基本に慣れているかと思います。

スキーマ定義の中に@paginateや@rules、あるいは@hasMany などの不思議な追加定義を見たことがあるかと思います。 これらは directive (ディレクティブ)と呼ばれ、GraphQLスキーマに機能を追加するための主な仕組みです。

定義

ディレクティブは常に@で始まり、その後に一意な名前が続きます。これらはGraphQLスキーマの指定した箇所で使用することができます。

下記の例にあるディレクティブ@upperCaseは、フィールドの定義で使用すると、結果を大文字にすることができます。

directive @upperCase on FIELD_DEFINITION

type Query {
  hello: String @upperCase
}

ディレクティブは、より柔軟に使用できるように引数を定義することもできます。 ディレクティブの位置指定(FIELD_DEFINITION | ARGUMENT_DEFINITION)に応じて、複数の場所で使用することができます。

directive @append(text: String) on FIELD_DEFINITION | ARGUMENT_DEFINITION

type Query {
  sayFriendly: String @append(text: ", please.")
  shout(phrase: String @append(text: "!")): String
}

使い方

Lighthouseには、すぐに利用できる組み込みのスキーマディレクティブがたくさん用意されており、スキーマから簡単に利用できます。

以下の例は非常に込み入ってますが、ディレクティブがどのような機能を持つかを理解するのに役立つと思います。

type Query {
  "投稿のリストを返すクエリ"
  posts(

    "データに完全一致のフィルター(=)をかける"
    postedAt: Date @eq

    "指定された複数のトピックのいずれかにマッチする投稿のみを表示する"
    topics: [String!] @in(key: "topic")

    "タイトルでLIKE検索する"
    title: String @where(operator: "%LIKE%")
  ): [Post!]!
    # ページネーションされたリストとして返す
    @paginate
    # 認証を要求する
    @guard(with: "api")
}

利用可能なディレクティブの完全なリストは、 [ディレクティブのAPI reference] (../api-reference/directives.md) を参照してください。

独自のディレクティブを実装することは、スキーマに再利用可能な機能を追加する素晴らしい方法です。詳細は、どのように独自のディレクティブを実装するかから学んでください。