GraphQL APIをスキーマファースト開発するためのモックサーバをRailsとApolloで作る

GMOペパボ Advent Calendar 2017の23日目の記事です。

今回はJavaScriptでGraphQLのサーバ/クライアントや関連ツールを提供しているApolloのツールセットでRailsプロジェクトでGraphQLのモックサーバを立ち上げるところまでを試してみます。

業務でRails製の(RESTishな)Web APIとVue.js製のSPAからなるアプリケーションを開発していて、スキーマファースト開発を取り入れています。また、GraphQLで通信するAPIを実験的に導入しはじめていますが、こちらは明示的な開発フローを決めず導入しようとしているため、なかなかサクサクと開発が進まないのが現状です。そこで、GraphQLでも先にインタフェースだけを決めてから、モックサーバを使ってフロントエンドとバックエンドで並行開発していけばよいのでは、という発想になります。

しかし、そもそもGraphQLはサーバに対するクエリを書くためのスキーマありきの技術であり、それがRESTの文脈におけるAPIとは異なる点です。その点で、スキーマファースト開発と呼ぶと語弊があるかもしれません。ですが、ここでは「GraphQLの型やフィールドだけを書いて、実際にデータを問い合わせる部分(リゾルバ)を書かない」ことをスキーマファースト開発とひとまず呼びます。つまり、裏の実装を後回しにして、フロントエンド/バックエンドでインタフェースについて合意が取れればモックサーバを使って開発を進められる、という状態を目指します。

利用ツール

上述したとおり、Apolloのツールセットを使います。

www.apollographql.com

具体的には次のものを使います。

ダミーデータを返してくれるサーバのことをスタブサーバと呼んだりもしますが、graphql-toolsが"Mocking"という言葉を使っているので、この記事ではモックサーバと呼ぶことにします。

最終構成

今回はRailsでgraphql-rubyを使っている状況を想定します。Railsプロジェクトにおける最終的な構成は次のとおりです(関係する部分だけ書いています)。

.
├── app
│    └── graphql
│         ├── app_schema.rb
│         ├── mutations
│         └── types
├── lib
│    └── tasks
│         └── graphql.rake
└── mock_app
     ├── index.js
     ├── mocks.js
     ├── package.json
     └── type_defs.js

詳細は次の通りです。

  • app 配下にgraphql-rubyで書いたGraphQLスキーマを置く
  • lib 配下にGraphQLスキーマをダンプするRakeタスクを置く
  • mock_app 配下にモックサーバの実装を置く
    • type_defs.js はRakeタスクで生成する

想定する開発フロー

想定する開発フローは次の通りです。

  1. graphql-rubyのDSLでGraphQLの型やフィールドを書く
  2. 追加した型やフィールドのダミーデータを書く
    • モックサーバで使う
  3. レビュー
  4. モックサーバを立ち上げる
    • graphql-rubyでGraphQLスキーマをダンプしてApolloで使える形式にする
    • ExpressとApolloでGraphQLモックサーバを立ち上げる
  5. フロントエンド/バックエンドが並行して開発する

それぞれ説明します。

graphql-rubyのDSLでGraphQLの型やフィールドを書く

これはgraphql-rubyをふつうに使うときとほぼ同じになります。まだ裏の実装ができていないので resolver を書かない点が違いといえます。

Types::QueryType = GraphQL::ObjectType.define do
  name 'Query'

  field :user do
    type Types::UserType
    argument :email, !types.String

    resolve ->(obj, args, ctx) {
      # まだ裏の実装がないので書かない
    }
  end
end

Types::UserType = GraphQL::ObjectType.define do
  name 'User'

  field :email, !types.String
  connection :articles, Types::ArticleType.connection_type
end

Types::ArticleType = GraphQL::ObjectType.define do
  name 'Article'

  field :title, !types.String
  field :body, !types.String
end

このように開発に必要な型とフィールドだけを書いていきます。

追加した型やフィールドのダミーデータを書く

モックサーバとして動かすには、サーバになんらかのデータを返してもらう必要があります。Apolloのgraphql-toolsで作れるモックサーバは、フィールドの型に応じてある程度ランダムにデータを返してくれるようになっています。しかし、実際に返ってくるであろうものに近いデータを返したほうがフロントエンドの開発ではありがたいということもあるでしょう。また、ダミーデータを見ればフィールドの表現しているものの雰囲気がわかるという利点もあります。

Apolloのモックサーバが返す値を指定するために、次のようなオブジェクトを定義します。ここでは仮に mocks.js とします。

// mock_app/mocks.js

module.exports = {
  User: () => ({
    email: 'kymmt90@example.com',
  }),
  Article: () => ({
    title: 'The Article',
    body: 'This is the article.',
  }),
};

GraphQLの型に対して、型のフィールドとダミーデータを持つオブジェクトを書き、それを返す関数を持たせているだけです。これを書いておくだけで、connectionなどを使ってクエリがネストしているときも、graphql-toolsのモックサーバがいい感じにダミーデータを返してくれるようになります。

レビュー

上述した流れでスキーマとダミーデータだけ書けたら、チームでレビューするなりして合意をとります。

モックサーバを立ち上げる

Apolloを使ってモックサーバを立ち上げます。

Expressとapollo-serverを使って、次のようなサーバを書きます。ここでは mock_app/index.js とします。

// mock_app/index.js

const express = require('express');
const bodyParser = require('body-parser');
const { graphqlExpress } = require('apollo-server-express');
const { addMockFunctionsToSchema, makeExecutableSchema } = require('graphql-tools');

// モックサーバの作成
const typeDefs = require('./type_defs');
const schema = makeExecutableSchema({ typeDefs });
const mocks = require('./mocks')
addMockFunctionsToSchema({ schema, mocks });

// GraphQLエンドポイントを持つExpressサーバの立ち上げ
const app = express();
app.use('/graphql', bodyParser.json(), graphqlExpress({ schema }));
app.listen(3000, () => {
  console.log('GraphQL mock server is running!!1');
});

mock_app/package.json は次のような感じです。

{
  "name": "graphql-mock-server",
  "private": true,
  "version": "0.0.1",
  "description": "graphql-mock-server",
  "author": "kymmt90",
  "dependencies": {
    "apollo-server-express": "*",
    "graphql-tools": "*",
    "graphql": "*",
    "express": "*",
    "body-parser": "*"
  }
}

index.js に書いたように、GraphQLスキーマを type_defs.js から読み込みます。この type_defs.js を得るために、graphql-rubyで定義したスキーマをもとに、次のRakeタスクを書き、スキーマをダンプできるようにします。

# lib/tasks/graphql.rake
namespace :graphql do
  namespace :schema do
    desc 'Dump GraphQL schema as a JavaScript file'
    task dump_as_js: :environment do
      schema = AppSchema.to_definition
      File.open(Rails.root.join('mock_app', 'type_defs.js'), 'w') do |f|
        f.puts("module.exports = `\n")
        f.puts(schema)
        f.puts('`')
      end
    end
  end
end

bin/rails graphql:schema:dump_as_js を実行すると次のようなファイルが得られます。type_defs.js では、GraphQLスキーマをJSの文字列として定義しています。

// mock_app/type_defs.js

module.exports = `
type Article {
  body: String!
  title: String!
}

# The connection type for Article.
type ArticleConnection {
  # A list of edges.
  edges: [ArticleEdge]

  # Information to aid in pagination.
  pageInfo: PageInfo!
}

# An edge in a connection.
type ArticleEdge {
  # A cursor for use in pagination.
  cursor: String!

  # The item at the end of the edge.
  node: Article
}

# Properties for creating an article by a specified user
input ArticleInputType {
  # Body of the article
  body: String

  # Title of the article
  title: String!

  # Email address of the user
  user_email: String!
}

type Mutation {
  # Create an article by the specified user
  createArticle(article: ArticleInputType): Article
}

pp# Information about pagination in a connection.
type PageInfo {
  # When paginating forwards, the cursor to continue.
  endCursor: String

  # When paginating forwards, are there more items?
  hasNextPage: Boolean!

  # When paginating backwards, are there more items?
  hasPreviousPage: Boolean!

  # When paginating backwards, the cursor to continue.
  startCursor: String
}

type Query {
  user(email: String!): User
}

type User {
  articles(
    # Returns the elements in the list that come after the specified global ID.
    after: String

    # Returns the elements in the list that come before the specified global ID.
    before: String

    # Returns the first _n_ elements from the list.
    first: Int

    # Returns the last _n_ elements from the list.
    last: Int
  ): ArticleConnection
  email: String!
}
`

ここまで来れば、あとは index.js をサーバとして起動すれば終わりです。

$ (cd mock_app && npm install && node start index)
GraphQL mock server is running!!1

次のように、サーバがGraphQLのクエリを受け取りつつ、自分で書いたダミーデータがサーバから返ってくるようになります。これでスタブサーバが手に入ったので、フロントエンドとバックエンドを並行開発していくことができます。

f:id:kymmt90:20171224113344p:plain

まとめ

Railsでgraphql-rubyを使っている場合に、Apolloのツールセットを使ってGraphQLのモックサーバを作る方法について説明しました。Apolloが便利なので、わりと簡単にセットアップできました。

GraphQL APIの開発方法はまだ模索段階なので、2018年はこれを業務に取り入れてみて気になる点がないか確かめていきたいという気持ちです。

参考

Railsの内部やPluginによる拡張方法について学べる本 "Crafting Rails 4 Applications" を読んだ

読みました、というよりは夏の終わりぐらいから何度か読んでいました。

Crafting Rails 4 Applications: Expert Practices for Everyday Rails Development (The Facets of Ruby)

Crafting Rails 4 Applications: Expert Practices for Everyday Rails Development (The Facets of Ruby)

どのような本か

Rails中上級者向けとよく言われている本です。Railsの内部構造を知りたかったり、Rails Plugin/Rails Engineを開発したいという人が読むと勉強になる内容です。著者はRailsのコントリビュータでありDeviseなどの開発で有名なPlatformatecの、というよりは、現在はElixirやPhoenixの開発で有名なといったほうがよさそうなJosé Valim氏です。

Railsの内部構造、Rails Plugin/Rails Engineの開発について書かれていると説明しましたが、具体的な例を挙げると次のような内容が含まれています。

  • 内部構造
    • Railsのレンダリングの仕組みを追う
    • Active Modelを構成するモジュールの構造を追う
  • Rails Plugin
    • コントローラで使うrender:pdfオプションを追加する
    • ビューテンプレートをファイルではなくDBから読み込めるようにする
    • ERBやHamlのようなテンプレートハンドラを新しく追加する
  • Rails Engine
    • Server Sent Eventsでストリーム通信できるようなRails Engineを作る
    • MongoDBにActiveSupport::Notificationsで得られるイベントを保存するMoutable and Isolated Engineを作る

どう役立つか

上にも書いたとおり、Rails Plugin/Rails Engineを作りたい人にとっては、例となるコードを通じてどうやればいいのかがわかるので便利だと思います。

本の題名のとおり、Rails 4(具体的にはv4.0.0)のコードを対象としています。なので、Rails 5のコードと照らし合わせながら読もうとすると、もちろん実装はRails 4から変わっており、サンプルコードなどはそのまま動かないものもあります(それはそれで勉強になりますが)。そういうわけで、Railsの内部については現在のものが直接わかるということにはならないのですが、Railsが実装されるうえで生まれたアイデアを学ぶというスタンスで読むと、Railsを使うときの周辺知識や文脈が補強されるのでよいのではと思います。

個人的には、この本でのRails PluginやRailtiesについての説明を参考にしながらSchemaConformistというRails Pluginを書けたので便利でした。

参考資料

この本を読み解くのには次の記事に集められた資料が役立ちました。

techracho.bpsinc.jp




おおざっぱには上述したような本です。残りは読書メモを貼っておきます。

  • Rails Plugin
    • Rails用に特化したgemのこと
    • rails new pluginでスケルトンのプロジェクトを生成できる
    • Railsアプリケーションを動かしてテストするために、プロジェクト内にデフォルトでtest/dummyという最小限のRailsプロジェクトが一式できる
  • Railsのレンダリングスタック
  • Active Model
    • Active Model準拠のAPIを持つクラスを作ると、コントローラやビューでRails Wayに乗って扱えるようになるので便利
  • Action View
    • ビューはform_forlink_toなどのヘルパーメソッドを持つビューコンテキストオブジェクト内で実行される
    • テンプレートを探す (lookup) ための情報を持つlookup contextをコントローラとビューで共有している
    • ActinoView::Resolver#find_templateをオーバーライドすると、ファイルシステム以外からテンプレートを読み出せる
    • ActionController::Metal
      • HTTPのことを知らないAbstractControllerとHTTPのことを全部知っているActionController::Baseの間の軽量なコントローラ
      • Rackアプリケーションとして動作し、HTTPを扱える最小限の機能を持つ
    • テンプレートハンドラ
      • テンプレートハンドラは内部APIActionView::Template.register_template_handlerで登録
      • テンプレートハンドラは「レンダリング後の文字列を返すRubyコード」の文字列表現を返すようにすればよい
  • Rails::Railtie
    • Railsの初期化とデフォルト設定にフックできる
    • 利用例
      • アプリ初期化時にタスクを実行したい
      • プラグインで設定値を変えたい
      • プラグインでRakeタスクを入れたい
      • Rails consoleかrunner実行時にプラグインでコードを実行したい
      • プラグインの設定値を追加したい
  • Moutable and Isolated Engines
    • rails plugin new foo --mootableでスケルトンを生成するRails Engine
    • 名前空間が独立なので、本体のアプリケーションのコンポーネントをオーバーライドしない
  • Rack middlewares
    • 使いたいコントローラの中でuse FooControllerMiddlewareとできる
  • Rakeタスクで:environmentを指定している意味
    • Rakeタスク実行前にRailsの初期化処理するために、config/environment.rbを実行したい
      • 初期化を必要とするRakeタスクは多数存在(例:rake db:migrate
    • これを指定することでアプリケーションを初期化することができる
    • DBへのアクセスやアプリケーション内のクラスを利用するときは:environmentが必要
  • 1ファイルからなるRailsアプリケーション
    • config.ruRails::Applicationの子クラスを設定してinitialize!してrun Rails.applicationしたものをrackupする

Yokohama.rb Monthly Meetup #85 に参加した

2017-11-11(土)のYokohama.rb Monthly Meetup #85メモです。

yokohamarb.doorkeeper.jp

Rubyレシピブック

@igrepさんと、第10章の「Webプログラミング」の続きで次のレシピを読みました。

  • 265: クッキーを処理する
  • 266: セッションを使用する

cgiRackを使う方法がそれぞれ説明されていましたが、rackup でWebサーバがシュッと立ち上がるというのもあってRackを使うのが圧倒的に楽な感じです。

るびま移行

@miyohideさんから、るびまをHikiからJekyllにリプレースするにあたって、URLの構成が変わるのでしばらくリダイレクトしたいといったような点について相談会がありました。AWSのS3に備わっているリダイレクト機能が使えるのではという解決案が出ていました。

OpenAPI

OpenAPI (Swagger) について、それ自体がどういうものかという点と、OpenAPIを使ったAPI開発の実際について紹介しました。説明に使ったのは次のあたりです。

その後、リクエストバリデーションやJSON Schemaの仕様完璧には使えない問題などについてなんやかんや話したりしました。

Banken

自己紹介のときの雑談でPunditを使っているという話が出た流れで、@hamaknさんからPunditと同種の認可ライブラリであるBankenの実例について紹介がありました。

github.com

Punditとの差別化ポイントとして、認可ポリシーを表現するクラス(PunditではPolicy, BankenではLoyaltyと呼ぶ)をモデルに対応づけるPunditとは異なり、コントローラと対応づける点があるそうです。そちらのほうが、アプリが複雑になるときに管理が楽になるようです。詳しくは次を読んでみてください。



次回は2017-12-09です。

yokohamarb.doorkeeper.jp

テスト時にAPIドキュメントのスキーマ定義からレスポンスのJSONを自動でバリデーションするgemを作った

あらかじめ書いたJSON Hyper Schema/OpenAPI 2.0のAPIドキュメントにおけるレスポンスのスキーマ定義をもとに、APIモードのRailsでHTTPリクエストを発行するテストを実行すると、自動でレスポンスのJSONをバリデーションしてくれるSchemaConformistというgemを作りました。

github.com

といっても、次の記事でやっていることをgem (Rails plugin) として切り出して、JSON Hyper Schemaにも対応させたあと、いくつか設定できるようにしただけのものです。

使いかた

インストールは、Railsのプロジェクトで Gemfilegem 'schema_conformist' を追加すれば終わりです。

あとは、テスト実行前に次のパスへAPIドキュメントを置いておきます。

  • JSON Hyper Schemaを使うとき
    • public/schema.json
  • OpenAPI 2.0を使うとき
    • public/swagger.json
    • OpenAPI 2.0を使うときは設定 schema_conformist.driver:open_api_2 を指定(後述します)

これで、Railsのintegration testやRSpecのrequest specでHTTPリクエストを発行したときに、APIドキュメントに書いたレスポンスのJSON Schemaにもとづいて、自動で実際のレスポンスのバリデーションが実行されるようになります。

テストを実行したときにどのような結果になるかについては、次のエントリをご覧ください。

バリデーションNGのときは次のようなエラーが出ます。

  1) Users GET /users/:id レスポンスがAPI定義と一致する
     Failure/Error: assert_schema_conform

     Committee::InvalidResponse:
       Invalid response.

       #: failed schema #/properties//users/{userId}/properties/GET: "email" wasn't supplied.

オプション

オプションはひとまず次のものを用意しました。READMEもご覧ください。

  • schema_conformist.driver
    • JSON Hyper SchemaとOpenAPI 2.0どちらを使うか
      • :hyper_schema:open_api_2 を指定
    • デフォルトはJSON Hyper Schema(深い意味はないです…)
  • schema_conformist.ignored_api_paths
    • バリデーションしないAPIパスの正規表現のリスト
    • デフォルトは空
  • schema_conformist.schema_path
    • API定義のファイルパス
    • デフォルトは上述のとおり

config/environments/test.rb あたりに次のように書いておけばOKです。

config.schema_conformist.driver = :open_api_2
config.schema_conformist.ignored_api_paths << %r(\A/private)
config.schema_conformist.schema_path = Rails.root.join('path', 'to', 'swagger.json')

余談

このgemを作った理由の一つとして、José Valim氏の "Crafting Rails 4 Applications" を一通り読んだ結果、Rails pluginを作りたくなったというのがあります。Rails内部の仕組みを細かく見ていったり、Rails pluginでRailsを拡張していったりする本です。今回もいくつか参考にしました。

Crafting Rails 4 Applications: Expert Practices for Everyday Rails Development (The Facets of Ruby)

Crafting Rails 4 Applications: Expert Practices for Everyday Rails Development (The Facets of Ruby)



以上です。興味のあるかたはご活用ください。

社内勉強会でスキーマファースト開発についてしゃべった

2017-10-24(火)にペパボEC事業部において「EC事業部 TechMTG #4」という社内勉強会がありました。この機会に、昨今のWeb API開発事情について知ってもらおうと思い、最近はチームでスキーマファースト開発をやってみているという話をしました。



スライドにも書いていますが、主に次のようなことを話しました。

  • スキーマファースト開発の概要
  • どのようなツールをどう使うか
  • サービス開発での実例

次のような質疑応答が(主にCTOとの間で)あった気がします。

  • スキーマ書くのがコストにならないか?
    • 他の部分で楽になるので、そこは歯を食いしばる。周辺ツールで楽にはなる
  • 最近、インターネットでGraphQLとかいう最先端技術を見たがどうか?
    • 向き不向きがありそう。参照系はGraphQLが有効そう
    • 実はGraphQLも徐々に使っているし、もっと広げていきたい

こういう考えかたがあるということを前提知識がない人も含めて説明するのはなかなか難しいですが、考えるなかで自分でもある程度整理がつけられたかなという感じです。また、このテーマはRubyKaigi 2017での@onkさんのAPI Development in 2017に影響を受けています。ありがとうございます。

おつかれさまでした。