GraphQL Schema から TypeScript の型定義を

継続的に生成する

2021/10/22 Kaigi on Rails 2021
株式会社マネーフォワード玉井あゆみ @ayumitamai97

GraphQL Schema から TypeScript の型定義を

継続的に生成する

2021/10/22 Kaigi on Rails 2021
株式会社マネーフォワード玉井あゆみ @ayumitamai97

発表資料

slide

https://kaigi-on-rails-2021-mf-maintain-graphql-types-over-repositories.netlify.app

マネーフォワード

サービス
- バックオフィスの業務効率化SaaS
  「マネーフォワードクラウド」シリーズ
- 家計簿アプリ「マネーフォワード ME」
- など
サービス開発の使用言語
- Ruby (Rails)
- Go
- TypeScript
- Swift
- Kotlin
- など
コーポレートサイト

私

玉井あゆみ @ayumitamai97
マネーフォワードクラウド人事管理
（2020年6月〜）
- API：Rails + GraphQL Ruby (graphql gem)
- フロントエンド：NuxtJS (TypeScript)

GraphQL

GraphQL の型システム

GraphQL Spec (June 2018)
APIに問い合わせ可能なあらゆるデータ型を定義する
- フィールドがどのような種類のオブジェクトを返しうるか
- オブジェクトがどのようなフィールドを持つか
特定の実装（言語、フレームワーク）に依存しない
型の種類
- スカラー (String, Int, Boolean, …)
- オブジェクト
- Enum
- Union

クエリの記法（例：GitHub GraphQL API）

query Query(
  $login: String!, $privacy: RepositoryPrivacy,
  $repoLast: Int, $languagesFirst: Int
) {
  user(login: $login) {
    name bio
    repositories(privacy: $privacy, last: $repoLast) {
      nodes {
        name
        languages(first: $languagesFirst) {
          nodes { name }
        }
      }
    }
  }
}
query Query(
  $login: String!, $privacy: RepositoryPrivacy,
  $repoLast: Int, $languagesFirst: Int
) {
  user(login: $login) {
    name bio
    repositories(privacy: $privacy, last: $repoLast) {
      nodes {
        name
        languages(first: $languagesFirst) {
          nodes { name }
        }
      }
    }
  }
}

{
  "login": "ayumitamai97",
  "privacy": "PUBLIC",
  "repoLast": 5,
  "languagesFirst": 1
}
{
  "login": "ayumitamai97",
  "privacy": "PUBLIC",
  "repoLast": 5,
  "languagesFirst": 1
}

{
  "data": {
    "user": {
      "name": "Ayumi Tamai",
      "bio": "・x・",
      "repositories": {
        "nodes": [
          {
            "name": "cont-codegen-sandbox-api",
            "languages": {
              "nodes": [
                {
                  "name": "Ruby"
                }
              ]
            }
          },
          {
            "name": "cont-codegen-sandbox-client",
            "languages": {
              "nodes": [
                {
                  "name": "HTML"
                }
              ]
            }
          },
          {
            "name": "constellation-theme",
            "languages": {
              "nodes": [
                {
                  "name": "Vim script"
                }
              ]
            }
          },
          {
            "name": "k8s-config",
            "languages": {
              "nodes": []
            }
          },
          {
            "name": "eks-example",
            "languages": {
              "nodes": [
                {
                  "name": "Dockerfile"
                }
              ]
            }
          }
        ]
      }
    }
  }
}
{
  "data": {
    "user": {
      "name": "Ayumi Tamai",
      "bio": "・x・",
      "repositories": {
        "nodes": [
          {
            "name": "cont-codegen-sandbox-api",
            "languages": {
              "nodes": [
                {
                  "name": "Ruby"
                }
              ]
            }
          },
          {
            "name": "cont-codegen-sandbox-client",
            "languages": {
              "nodes": [
                {
                  "name": "HTML"
                }
              ]
            }
          },
          {
            "name": "constellation-theme",
            "languages": {
              "nodes": [
                {
                  "name": "Vim script"
                }
              ]
            }
          },
          {
            "name": "k8s-config",
            "languages": {
              "nodes": []
            }
          },
          {
            "name": "eks-example",
            "languages": {
              "nodes": [
                {
                  "name": "Dockerfile"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

"GraphQL Ruby" on Rails

`gem 'graphql'`

Ruby における GraphQL 実装
GraphQL のリクエストを受け付ける GraphQLController を定義する
- Rails REST API モードや MVC と共存できる
GraphQL Spec 本体には定められていない発展的な機能も含まれる
- Authorization
- Relay (cursor-based pagination)
- など

GraphQL Schema から TypeScript の型定義を

継続的に生成する仕組み

API に型があるなら、フロントエンドでも使いたい

TypeScript の型を GraphQL API に合わせて定義したい
GraphQL Schema の型と TypeScript の型とを二重管理するのは辛い

異なる実装間の共通言語 GraphQL IDL

GraphQL の型システムを説明するために使われる Interface Definition Language
- 拡張子は .graphql
- （当然ながら）どのプログラミング言語による実装かを問わず利用できる
API – フロントエンド間の共通言語として GraphQL Schema IDL を利用する
- Rails のプロジェクトで GraphQL IDL ファイルを生成
- フロントエンドのプロジェクトで TypeScript の型定義を生成
※ 以下の前提で進みます
- GitHub を使用している
- APIとフロントエンドとで GitHub リポジトリが分かれている

GraphQL IDL を生成する – `GraphQL::RakeTask`

graphql gem はコードファースト
- Ruby のコードで Schema を定義するので、IDLを開発者自身の手で書く場面はない
graphql gem が提供している Rake task GraphQL::RakeTask を利用して、
Ruby のコードから GraphQL IDL ファイル *.graphql を生成する
Git Hooks pre-commit などに bin/rake graphql:schema:idl を設定しておくと便利

# lib/tasks/graphql.rake
# Documentation: https://graphql-ruby.org/api-doc/1.9.12/GraphQL/RakeTask
require "graphql/rake_task"

GraphQL::RakeTask.new(
  schema_name: 'MySchema',
  idl_outfile: 'schema.graphql',
  # Schema Introspection に認証・認可などが必要な場合は
  # よしなに context を渡す
  load_context: lambda do |_task|
    { current_user: User.new(role: 'full_access') }
  end
)
# lib/tasks/graphql.rake
# Documentation: https://graphql-ruby.org/api-doc/1.9.12/GraphQL/RakeTask
require "graphql/rake_task"

GraphQL::RakeTask.new(
  schema_name: 'MySchema',
  idl_outfile: 'schema.graphql',
  # Schema Introspection に認証・認可などが必要な場合は
  # よしなに context を渡す
  load_context: lambda do |_task|
    { current_user: User.new(role: 'full_access') }
  end
)

# schema.graphql
schema {
  query: Query
}

type Query {
  user(id: ID!): User
}

type User {
  id: ID!
  username: String!
}
# schema.graphql
schema {
  query: Query
}

type Query {
  user(id: ID!): User
}

type User {
  id: ID!
  username: String!
}

IDLからTS型定義を生成する – `graphql-codegen`

graphql-codegen というパッケージを利用して、 GraphQL IDL から TypeScript の型を自動で生成する

# schema.graphql
schema { query: Query }
type Query { user(id: ID!): User }
type User { id: ID!  username: String! }
# schema.graphql
schema { query: Query }
type Query { user(id: ID!): User }
type User { id: ID!  username: String! }

# codegen.yml
# Documentation: https://www.graphql-code-generator.com/docs/getting-started/codegen-config
overwrite: true
schema:
  - github:{OWNER}/{API_REPO}#{BRANCH}:schema.graphql:
      token: ${GITHUB_PAT} # 指定したリポジトリのREAD権限を持つ
generates:
  ./types/graphql.ts:
    plugins:
      - typescript
    config:
      # GraphQL Client として apollo-client を使用する場合
      apolloClientVersion: 2
# codegen.yml
# Documentation: https://www.graphql-code-generator.com/docs/getting-started/codegen-config
overwrite: true
schema:
  - github:{OWNER}/{API_REPO}#{BRANCH}:schema.graphql:
      token: ${GITHUB_PAT} # 指定したリポジトリのREAD権限を持つ
generates:
  ./types/graphql.ts:
    plugins:
      - typescript
    config:
      # GraphQL Client として apollo-client を使用する場合
      apolloClientVersion: 2

※ 紙幅の都合上、改行を多々省いています

// types/graphql.ts
export type Maybe<T> = T | null;
export type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
export type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
export type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> };
/** All built-in and custom scalars, mapped to their actual values */
export type Scalars = {
  ID: string; String: string; Boolean: boolean;
  Int: number; Float: number;
};
export type Query = {
  __typename?: 'Query';
  user?: Maybe<User>;
};
export type QueryUserArgs = { id: Scalars['ID']; };
export type User = {
  __typename?: 'User';
  id: Scalars['ID'];
  username: Scalars['String'];
};
// types/graphql.ts
export type Maybe<T> = T | null;
export type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] };
export type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> };
export type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> };
/** All built-in and custom scalars, mapped to their actual values */
export type Scalars = {
  ID: string; String: string; Boolean: boolean;
  Int: number; Float: number;
};
export type Query = {
  __typename?: 'Query';
  user?: Maybe<User>;
};
export type QueryUserArgs = { id: Scalars['ID']; };
export type User = {
  __typename?: 'User';
  id: Scalars['ID'];
  username: Scalars['String'];
};

プロジェクト間の同期 – GitHub Actions

APIのプロジェクトとフロントエンドのプロジェクト間で型定義の同期をとる方法
- 🥵 ローカルの GraphQL IDLファイルが更新されたら、ローカルの TypeScript 型定義を自動で更新する
  - 各々のローカルブランチの状態に依存するため、 git commit すると差分が競合する
- 🥵 main ブランチに GraphQL IDLファイルの更新をマージしたら、手で graphql-codegen を実行する
  - 面倒
  - ラグが大きいので実際の Schema と TypeScript 型定義とが合わないタイミングがある
- 🥳 main ブランチで GraphQL Schema が更新されたら、自動で graphql-codegen を実行する
  - ラグが小さく、手作業が一切不要
自動化には GitHub Actions を利用する

GitHub Actions – イベントの流れ

GitHub Actions (1) – GraphQL Schema の更新を通知

name: GraphQL Schema IDL ファイルの更新をフロントエンドのリポジトリに通知する
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: technote-space/get-diff-action@v4.0.1
        with:
          PATTERNS: schema.graphql # このファイルに差分があった場合は env.GIT_DIFF にファイル名が格納される
      - name: フロントエンドのリポジトリに repository_dispatch イベントを通知する
        uses: peter-evans/repository-dispatch@v1
        with:
          repository: {OWNER}/{FRONTEND_REPO}
          token: ${{ secrets.GITHUB_PAT }}
          event-type: graphql-schema-updated
        if: env.GIT_DIFF
name: GraphQL Schema IDL ファイルの更新をフロントエンドのリポジトリに通知する
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: technote-space/get-diff-action@v4.0.1
        with:
          PATTERNS: schema.graphql # このファイルに差分があった場合は env.GIT_DIFF にファイル名が格納される
      - name: フロントエンドのリポジトリに repository_dispatch イベントを通知する
        uses: peter-evans/repository-dispatch@v1
        with:
          repository: {OWNER}/{FRONTEND_REPO}
          token: ${{ secrets.GITHUB_PAT }}
          event-type: graphql-schema-updated
        if: env.GIT_DIFF

GitHub Actions (1) – GraphQL Schema の更新を通知

GitHub Actions (2) – IDL から TypeScript の型を生成しPRを作成

name: APIのリポジトリの GraphQL Schema IDL を読んで TypeScript の型を生成し、PRを作成する
on:
  repository_dispatch:
    types: [ graphql-schema-updated ]
jobs:
  update-graphql-schema-ts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: yarn install
      - name: TypeScript 型定義を生成
        run: GITHUB_PAT=${{ secrets.GITHUB_PAT }} yarn graphql-codegen
      - name: 現在のブランチの状態をコミットし、PRを作成する
        uses: peter-evans/create-pull-request@v3
        with:
          token: ${{ secrets.GITHUB_PAT }} # automerge-action を使わない場合は `GITHUB_TOKEN` で十分
          branch: feature/update-graphql-schema
          title: '[bot] Update types/graphql-schema.ts'
          labels: automerge # automerge-action を使う場合
          # ...
name: APIのリポジトリの GraphQL Schema IDL を読んで TypeScript の型を生成し、PRを作成する
on:
  repository_dispatch:
    types: [ graphql-schema-updated ]
jobs:
  update-graphql-schema-ts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: yarn install
      - name: TypeScript 型定義を生成
        run: GITHUB_PAT=${{ secrets.GITHUB_PAT }} yarn graphql-codegen
      - name: 現在のブランチの状態をコミットし、PRを作成する
        uses: peter-evans/create-pull-request@v3
        with:
          token: ${{ secrets.GITHUB_PAT }} # automerge-action を使わない場合は `GITHUB_TOKEN` で十分
          branch: feature/update-graphql-schema
          title: '[bot] Update types/graphql-schema.ts'
          labels: automerge # automerge-action を使う場合
          # ...

GitHub Actions (2) – IDL から TypeScript の型を生成しPRを作成

GitHub Actions (3) – TypeScript の型を更新したPRをマージ

name: automerge ラベルがつけられたPRを自動で approve & merge する
on:
  pull_request:
    types:
      - labeled
jobs:
  wait-for-checks-and-auto-merge:
    runs-on: ubuntu-latest
    steps:
      - name: Checks がパスするまで待つ
        uses: fountainhead/action-wait-for-check@v1.0.0
        id: wait-for-build-and-test
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          checkName: build_and_test # 実行完了を待ちたい Checks の名前を指定する
          intervalSeconds: 60
          timeoutSeconds: 1200
      # 次ページへ続く
name: automerge ラベルがつけられたPRを自動で approve & merge する
on:
  pull_request:
    types:
      - labeled
jobs:
  wait-for-checks-and-auto-merge:
    runs-on: ubuntu-latest
    steps:
      - name: Checks がパスするまで待つ
        uses: fountainhead/action-wait-for-check@v1.0.0
        id: wait-for-build-and-test
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          checkName: build_and_test # 実行完了を待ちたい Checks の名前を指定する
          intervalSeconds: 60
          timeoutSeconds: 1200
      # 次ページへ続く

GitHub Actions (3) – TypeScript の型を更新したPRをマージ

      # 前のページの続き
      # jobs.wait-for-checks-and-auto-merge.steps
      - name: CIがパスしていたらPRをapproveする
        uses: hmarr/auto-approve-action@v2.0.0
        if: |
          steps.wait-for-build-and-test.outputs.conclusion == 'success' &&
            startsWith(github.head_ref, 'feature/update-graphql-schema') == true
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: CIがパスしていたらPRを自動マージする
        uses: pascalgn/automerge-action@v0.13.0
        if: steps.wait-for-build-and-test.outputs.conclusion == 'success'
        env:
          UPDATE_RETRIES: 10
          UPDATE_RETRY_SLEEP: 10000
          MERGE_DELETE_BRANCH: true
      # 前のページの続き
      # jobs.wait-for-checks-and-auto-merge.steps
      - name: CIがパスしていたらPRをapproveする
        uses: hmarr/auto-approve-action@v2.0.0
        if: |
          steps.wait-for-build-and-test.outputs.conclusion == 'success' &&
            startsWith(github.head_ref, 'feature/update-graphql-schema') == true
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: CIがパスしていたらPRを自動マージする
        uses: pascalgn/automerge-action@v0.13.0
        if: steps.wait-for-build-and-test.outputs.conclusion == 'success'
        env:
          UPDATE_RETRIES: 10
          UPDATE_RETRY_SLEEP: 10000
          MERGE_DELETE_BRANCH: true

GitHub Actions (3) – TypeScript の型を更新したPRをマージ

GitHub Actions – イベントの流れ

We are hiring!

corporate

マネーフォワードはエンジニアを募集しています。

ご応募お待ちしています！

https://corp.moneyforward.com/recruit/

GraphQL Schema から TypeScript の型定義を

継続的に生成する

発表資料

GraphQL Schema から TypeScript の型定義を

継続的に生成する

発表資料

マネーフォワード

私

GraphQL

GraphQL の型システム

クエリの記法（例：GitHub GraphQL API）

"GraphQL Ruby" on Rails

gem 'graphql'

GraphQL Schema から TypeScript の型定義を

継続的に生成する仕組み

API に型があるなら、フロントエンドでも使いたい

異なる実装間の共通言語 GraphQL IDL

GraphQL IDL を生成する – GraphQL::RakeTask

IDLからTS型定義を生成する – graphql-codegen

プロジェクト間の同期 – GitHub Actions

GitHub Actions – イベントの流れ

GitHub Actions (1) – GraphQL Schema の更新を通知

GitHub Actions (1) – GraphQL Schema の更新を通知

GitHub Actions (1) – GraphQL Schema の更新を通知

GitHub Actions (2) – IDL から TypeScript の型を生成しPRを作成

GitHub Actions (2) – IDL から TypeScript の型を生成しPRを作成

GitHub Actions (2) – IDL から TypeScript の型を生成しPRを作成

GitHub Actions (3) – TypeScript の型を更新したPRをマージ

GitHub Actions (3) – TypeScript の型を更新したPRをマージ

GitHub Actions (3) – TypeScript の型を更新したPRをマージ

GitHub Actions (3) – TypeScript の型を更新したPRをマージ

GitHub Actions – イベントの流れ

We are hiring!

`gem 'graphql'`

GraphQL IDL を生成する – `GraphQL::RakeTask`

IDLからTS型定義を生成する – `graphql-codegen`