TechTalk スキーマファースト開発 2020/6/15 海老沼 健一 

持ち帰ってほしいこと 2 スキーマファースト開発で コミュニケーションコストを減らして 開発効率を上げよう 

よくある開発スタイル (僕が実際に経験した環境) エンジニアがフロントエンドとサーバーサイドに分かれている 機能開発フロー 1. 機能の仕様書を作る 2. サーバーサイドエンジニアがAPI設計 3. サーバーサイドエンジニアがAPI実装 4. フロントエンドエンジニアが作成されたAPIを使ってクライアントを実装 よくある問題 • 仕様書やドキュメントがちゃんと整備されていない • クライアント側はAPIの実装を待たないといけない • エンドポイント毎のエンコード/デコード処理を書くのが面倒 3 

よくある問題１ 仕様書やドキュメントがちゃんと整備されていない • スケジュールが押してると仕様書やドキュメントを書くのは後回しになりがち • 手動でAPI仕様書を書いているとタイポやミス • ドキュメントがちゃんと整備されていないと、APIの仕様を確認する必要がある • 例えば • エンドポイントとサンプルのレスポンスが貼ってあるだけ • バグ修正で変更した箇所のドキュメントが修正されていない 4 

よくある問題２ クライアント側はAPIの実装を待たなければいけない • クライアント側の通信周りの実装がAPI待ち • 正しいモックデータを用意するのにコミュニケーションコストがかかる • 自前でモックサーバーを用意するにもメンテが必要 5 

よくある問題３ エンドポイント毎のエンコード/デコード処理を書くのが面倒 • サーバー/クライアント共にリクエストとレスポンスの構造体やクラスを用意して、エンコード/デコー ド処理を書く必要があり、コード量が多くなりがち • 例えば • Goだと json.NewEncoder().Encode(), json.Marshal() とか • Dartだと RequestClass.toJson() とか 6 

7 スキーマファースト開発 

スキーマファースト開発とは まずAPIの仕様(スキーマ)を決めて、それをもとにサーバー/クライアント開発を同時に進めて最後に 結合する開発手法 メリット • スキーマという共通言語でコミュニケーションを取れる • 周辺ツールによる開発効率の向上 • ドキュメント生成、モックサーバー立ち上げ • ハンドラー、エンコード/デコード周りのコード生成 • バグの発生を減らせる デメリット • スキーマの学習コスト、導入コストかかる 8 

スキーマファースト開発 • OpenAPI • gRPC (概要のみ) • JSON Schema (概要のみ) • GraphQL 9 

OpenAPI https://openapis.org REST API をYAML/JSONで記述するフォーマットで、Swagger ( https://swagger.io ) が有名 メリット • ドキュメントやコードの生成、モックサーバー • 既存のRESTの知識/仕組みをそのまま使える • キャッシュとか デメリット • リソースに対して画面やユースケース毎に微妙に異なるデー タが欲しくなり、エンドポイントが増えていく (REST API のデ メリット) 10 

gRPC https://grpc.io HTTP/2を利用したハイパフォーマンスなRPCフレームワーク Protocol Buffers というIDL(インタフェース定義言語)でスキーマを定義する 来週のTechTalkで出てくるので今回は省略 11 JSON Schema https://json-schema.org JSONファイルの構造(型、範囲など)をJSONで表現する 採用事例が少なそう 

GraphQL https://graphql.org APIのためのクエリ言語/実装 GraphQL 独自のSDLを使う クライアント側で取得したいデータをクエリ言語で指定 し、/graphql エンドポイントに送る。APIはそのクエリど おりにデータを返す メリット • ドキュメントやコード生成、モックサーバー • スキーマを定義しておけばクライアント主導でレス ポンスを変えれる 12 

GraphQL デメリット • リソースに対するシンプルなCRUDで十分なサービスには必要ない • サーバーの実装が複雑になりがち • n+1問題を解決するためのバッチ処理 • 認証/認可などミドルウェアの設計 • キャッシュの仕組みなどまだ枯れてない • 基本的に1つの /graphql エンドポイントでリクエストを受けるので、エンドポイント単位で キャッシュしていた場合はRESTの知見をそのままは活かしにくい • FastlyやCloudflareなどのCDNではGraphQLクエリのキャッシュに対応しているが、まだ 採用事例は少なそう 13 

14 GraphQL デモ 

GraphQL - エブリスタでの採用事例 フルRailsだったサーバーを Rails + graphql-ruby でリプレイス 良かったこと • APIのドキュメント作成が不要になり工数削減 • API数が900 -> 150クエリに • フロントエンド主導の開発プロセス つらかったこと • 当時はgraphql-rubyが安定していなかった • ベストプラクティスが無かった https://www.slideshare.net/dena_tech/10-132197778 15 

持ち帰ってほしいこと (再掲) 16 スキーマファースト開発で コミュニケーションコストを減らして 開発効率を上げよう