あなたのドメインのためのtypesafe契約としてGraphical!

@ nexus/schemaとtypescriptを用いた安全なGraphSQLスキーマの構築
このポストでは、@ nexus/schemaを使用してtypesafe graphqlスキーマを構築する方法について説明します.私は、読者がGraphqlと通じる親しみがあると仮定します.Graphqlの基礎を学ぶことに興味があるなら、Graphqlのホームページを見てくださいhttps://graphql.org/learn/ .

動機
過去にGraphical JSに基づいて型セーフなGraphSQLの実装を書くとき、開発者は常にすべてのリゾルバ自体に適切な型を供給するのに十分注意しなければなりませんでした.正しい型を提供することは、しばしば誤りがちでしたあなたはどちらかを消費し、生産リゾルバからの一般的なタイプのエクスポートを参照したり、すべての消費を追跡し、それが変更された場合、タイプに関連するレゾルバを生成するために細心の注意を払う必要がありますネクサス/スキーマは、これは主に過去のことをしようとしています新しいタイプのコンストラクターがバニラGraphSQL JS型コンストラクターをラップして、開発者にいくつかの型インポートを供給できるようにすることで、スキーマを実行するときに@ nexus/schemaによってスクリプトのアーティファクトを生成できます.これによって、スキーマを使用してテストしなければならない前に、ほとんどの型のエラーを確認できます.

マケケケラ
Makeschema機能は、一緒にすべてを結び、@ nexus/schemaの魔法を作ります.適切な型のアーティファクトを生成するために、この関数は正しい構成を与えられる必要があります.これはスキーマによって使用されるすべての型への参照を含みます.

export const schema = makeSchema({
  types: [...schemaTypes, ...scalars],
  outputs: {
    schema: path.resolve('./src/generated/schema.graphql'),
    // where to save the schema declaration artifact
    typegen: path.resolve('./src/generated/typings.ts'),
    // where to save the typescript schema definitions artifact
  },
});

ここでは、スキーマで使用されているすべての型を使用して設定を提供し、どこでSDLスキーマアーティファクトとタイプスクリプトのアーティファクトを出力する場所で@ nexus/スキーマを指示すると、これらの生成されたファイルは、あなたのGitリポジトリには理想的に含まれていないはずです.
スキーマ構成では、スキーマのコンテキスト型を見つける場所についてもいくつか設定を行う必要があります.

export const schema = makeSchema({
  ...,
  typegenAutoConfig: {
    sources: [
      {
        source: path.resolve(__dirname, './context.ts'),
        // this points to where the RequestContext type can be imported from
        alias: 'ctx',
        // the alias the module containing the RequestContext type is given in the schema typings artifact
      },
    ],
    contextType: 'ctx.RequestContext',
    // the path to the RequestContext in the typings artifact
  },
});

これは@ nexus/schemaにファイル'.コンテキスト.を実行するファイルに配置されますmakeSchema 関数呼び出しと呼ばれるモジュールからエクスポートされた型を使用するRequestContext スキーマ内のすべてのリゾルバのコンテキストパラメーターの型です.

スキーマタイプの作成
@ nexus/schemaスキーマのスキーマ型は、コンストラクタメソッドのセットを使用して構築されます.他のものの中にタイプの名前とそれの任意の記述を含む.

オブジェクトタイプ:
この関数は、基本的なGraphloObjectTypeの構築に使用します.このオプションは、ObjectDefintionBlockパラメーターを受け取る定義関数を提供しなければなりません.このパラメーターは、フィールドを返す必要があるフィールドの後に名前を付けたり、フィールドを呼び出したり、フィールドの正しい戻り値を指定したりすることで、フィールドを型に追加するために使用されます.これらの関数のそれぞれには、追加されたフィールドの名前と、解決関数を含むフィールドの設定が含まれていなければなりません.ObjectDefinitionブロックは、また、Instementsメソッドを使用してオブジェクト型がインターフェイスを実装する必要があることを、GraphSQLに指示するために使用されます.

インタフェース
InterfaceType関数はObjectType関数と同じように機能します.これは基本的なGraphLInterfaceTypeの構築に使用されます.

unionType :
この関数は、基になるGraphlunionTypeの構築に使用します.この型の設定には、uniondefintionblockを受け取る定義関数が必要です.これはメンバーメソッドを通して型にメンバーを追加するために使用され、どのメンバーが与えられたオブジェクトをタイプするかを決定する方法で、GraphSQL JSを指示します.

ExtendType :
この関数は、既存のオブジェクト型を追加するために使用します.拡張されている型と、新しいフィールドを追加するObjectTypeのような定義関数を含む設定が必要です.

QueryField :
これは、クエリ型にのみ作用し、したがって、定義関数を与えられたExtendType関数の装飾版です.スキーマで可能なクエリを宣言するために使用します.

フィールド
これはExtendType関数の修飾バージョンです.スキーマで可能な任意の突然変異を宣言するために使用します.

enumtype :
enumType関数は、GraphlenumTypeを構成するために使用されます.この関数は、メンバープロパティを通じてENUMのメンバーの集合を与えなければなりません.

scalarType :
ScalarType関数はスカラー型を構成するために使用されます.これらの型には特別なハンドリングがあります.ASNexusMethodが設定時にtrueに設定されている場合は、ObjectDefintionBlock型で使用可能になります.また、3つの関数を指定する必要があります.

parseliteral :
この関数は、SDLに書かれている場合、フィールドの値を解析するために使用されます.

パラメータ
この関数は、パラメータとして与えられた場合、フィールドの値を解析するために使用されます.

シリアル化:
この関数は、フィールドに与えられた値を、クライアントに転送するスカラー値に変換するために使用されます.

ルートタイピング
オブジェクト、インターフェイス、スカラー型を宣言するときに、ルートタイプのプロパティを指定する必要があります.これらのケースのためのもう一つのタイプを指定することは、あなたにどんな利益を与えるよりも、あなたを旅行させそうです.
ルートタイプを指定するとき、私はいつもPathプロパティのためにCount Rainファイル名を使います.この変数には、現在のモジュールへの絶対パスが含まれます.これは、私がファイルを動かすならば、私は手動でファイル輸入経路を変えることについて心配する必要はありません.スキーマ型の宣言がそのルート型でコロケーションされていない場合この動作を維持するために、型宣言を使用して、その型をスキーマ型宣言にインポートすることを提案します.

ランタイム
@ nexus/schema serverを実行するためのランタイム構成を設定することはTSノードを使用することによってずっと簡単になります.ジェイ.jsマップファイルを.Gitignoreと選択のあなたのエディタでそれらをフィルタリングすること;または、あなたのtypescriptコンパイルを別々のdistフォルダに出力して、このように、ランタイムのCountファイル名の値を変えません.

人工物の生成と変更の生成
スキーマで作業するときには、スキーマに対して行われた変更がサーバーに対して行われているスキーマ変更のすべてを終了する前に正しく入力されることを確認する必要があります.これを行うには、スキーマの新しいアーティファクトを生成する必要があります.これは、makeSchema コンストラクタ

export const schema = makeSchema({
  ...,
  shouldExitAfterGenerateArtifacts: process.argv.includes('--nexus-exit'),
  // if the --nexus-exit param is given to the process, exit after the schema artifacts have been generated
});

次のスクリプトを使用して、型のアーティファクトを生成します.

"scripts": {
  "generate": "yarn ts-node ./src/server --nexus-exit",
},

このスクリプトは、アーティファクトが生成された時点までスキーマを実行し、終了します.これは、新しいアーティファクトが生成された後に、型の正しさを真に確認することができるため、スキーマ上で作業するときに便利な動作です.このスクリプトは、あなたのCIプロセスのステップとして実行するのに役立ちます.
スキーマに変更を加える必要があります.既にスキーマの型アーティファクトを以前に生成した場合、これは面倒なことができます.この問題を解決するには、次のスクリプトを使用します.

"scripts": {
  "generate:force": "yarn ts-node --log-error ./src/server --nexus-exit",
},

ログエラーフラグセットを使用すると、TSノードはどんなタイプのエラーも見つけ、スクリプトを実行します.これは、すべての変更が終了するまで、サーバーが正しくコンパイルされない変更の大規模な設定を行う途中でさえ、新しい型のアーティファクトを生成することができます.スクリプトによって報告されたエラーは一般的には無視されなければなりません.

資源
すべてのテクニックを使用してデモプロジェクトを見つけることができますhere .