今さらスキーマファーストに入門する

はじめまして。Wantedly Advent Calendar 2024の18日目を担当する西野です。今年の9月にウォンテッドリーにバックエンドエンジニアとして入社しました。

IT業界での開発経験はそれなりに長い私ですが幅広い知識を持っているとは言い難く、組織的にも技術的にも今までとは全く違った開発を経験したいと思ったことがウォンテッドリーに入社を決めた理由でした。そしてそれは実際に期待通りで、これまでとは全く違う仕事の進め方や知らなかった知識に触れる毎日は大変でもありますが刺激的でもあります。

スキーマファーストという開発方法もそのひとつで、恥ずかしながら入社するまでまったく知らない言葉でした。ウォンテッドリーのシステムはマイクロサービスであり、マイクロサービス間の通信にgRPC + Protocol Buffersを使用し、フロントエンドとバックエンド間の通信にはGraphQLを使用しています。Protocol BuffersとGraphQLの併用にあたってはProtocol Buffersの定義をベースとするシステム設計であるため、APIの実装は必然的にスキーマファーストになっています。

この記事はスキーマファーストによる開発の初学者である私が、入社からの3ヶ月に経験したことをまとめたものになります。これからスキーマファーストに触れるエンジニアの参考になれば幸いです。

スキーマファーストとは

スキーマとはデータの構造や仕様を形式的に定義したものを指します。データベースの設計で3層スキーマ構造という言葉を聞いたことがある人は多いのではないでしょうか。APIのスキーマであれば、それはAPIが取り扱うデータの構造や仕様になります。例えばエンドポイント、リクエストパラメータ、レスポンスボディなどが含まれます。

このスキーマを最初に作成し、その仕様に基づいてAPIを実装する開発手法を「スキーマファースト」といいます。

仕様を決めてから実装に取りかかる開発プロセス自体は一般的だと思いますが、「スキーマを基準とする開発技術 （※1）」を取り入れることでそのプロセスが厳密になるのがスキーマファースト開発の特徴になります。そういった開発技術ではスキーマに基づいてソースコードやバリデーション、テストコードなどを生成する機能を持つため、スキーマ（仕様）と異なる実装ができなくなります。

※1：OpenAPIやGraphQL、Protocol Buffersなどが挙げられる。OpenAPIとGraphQLはコードファーストでの開発も可能だがここでは割愛する。

スキーマファーストのメリット

スキーマファーストの開発には次のようなメリットがあります。

①明確な仕様の定義

スキーマで定義するのはAPIの仕様であり、以降の開発工程の基準となるものであるため、その内容は明確です。例えばProtocol Buffers（.protoファイル）でリクエストパラメータやレスポンスボディを定義する場合は以下のような書き方になります。

// バージョン
syntax = "proto3";

// パッケージ
package sample;

message SampleRequest {
  // Required.
  // 詳細情報を得たいユーザーのID
  int64 user_id = 1;
}

message SampleResponse {
  // Required.
  // Requestで指定されたユーザーのID
  int64 user_id = 1;
  // Optional.
  // 企業ID
  // ユーザーが今所属している企業がある場合のみ入る
  int64 company_id = 2;
  // Optional.
  // 企業名
  // ユーザーが今所属している企業がある場合のみ入る
  string company_name = 3;
}​

.protoファイルを見るのが初めてでも、エンジニアであればどんな型と名称でやりとりしたいのかということは伝わるのではないでしょうか。ウォンテッドリーではコメントに各パラメータが必須か任意かを残すことで、さらに仕様として明確に伝わるようにしています。

また、スキーマをAPIの仕様書として位置づけることで、別途ドキュメントを用意する必要がなくなります。スキーマは開発コードの一部であるため、改修が入った場合でも常に最新の状態が保たれます。そのため、APIの処理内容が仕様と異なるという問題を防ぐことができます。

②手戻りリスクの軽減

スキーマの設計をフロントエンドと共有することで、早い段階でフロントエンド視点での仕様の問題点を洗い出すことができます。スキーマファーストの開発ではAPIの実装はスキーマの確定後になるため、APIの実装後に仕様変更が発生するリスクを減らすことができます。そしてスキーマを確定した後は、スキーマで定義した仕様に基づいてフロントエンドとバックエンドが同期的に実装を進めることができます。

冒頭でも書いた通り、仕様を決めてから実装に取りかかる開発プロセス自体は一般的です。しかしスキーマファーストによる開発技術を取り入れている場合、スキーマによる定義が制約として機能するため、その定義から外れた実装ができなくなります。つまりフロントエンドとバックエンドの仕様の認識のずれによる手戻りをなくすことができるのです。

スキーマファーストのデメリット

スキーマファーストの開発にもデメリットはあります。

①スキーマ定義の難しさ

開発の早い段階でスキーマによって明確な定義が決定できるというのはメリットではありますが同時にデメリットでもあります。最初から完璧な設計をするというのはそう容易なことではありません。要求される機能の複雑さによってはスキーマを確定するのに時間がかかり、なかなか実装に取りかかれないという状況になることもあります。これは私が実際に経験したことであり、スケジュール遅延の原因になってしまいました。

②スキーマ変更のコストの高さ

完璧な仕様を定義したと思っていても実装に入ってみたら予期しなかった問題が見つかったり、ある程度実装が進んでから仕様変更の要求が上がってきたり、といったようなことはエンジニアなら経験があると思います。そのような場合はスキーマを修正する必要が出てきますが、実のところ一度定義されたスキーマを修正するコストは高めです。このことは最初にスキーマを確定するのに時間がかかる理由のひとつでもあります。機能の仕様変更が頻繁に起こり、柔軟な対応が求められるような開発現場で取り入れるのは難しいかもしれません。

ウォンテッドリーのグロースチームとスキーマファーストの相性がいい理由

スキーマファーストによる開発のメリットを活かすためには、APIを作る側（バックエンド）と使う側（フロントエンド）といった異なる役割を持つメンバーが協力してスキーマ設計を進めることが重要です。そのために組織としても、役割を超えて横断的なコミュニケーションが取りやすい文化であることが求められます。

14日の紀平さんの記事でも紹介されていますが、ウォンテッドリーのグロースチームは異なる役割を持つメンバーで構成されています。

フロントエンドとバックエンドが同じチームであるというのは、まさにスキーマファーストに適した体制であると言えます。同じスケジュールを共有し、同じチーム目標に向かって進む仲間であるため、フロントエンド・バックエンドといったどちらかに偏った視点になりにくく相互理解が進み、またそのことはキャッチアップ中である私にとってはシステム全体の理解を深める大きな助けにもなりました。

まとめ

私が初めてのスキーマファースト開発に取り組んで学んだこと、感じたことは以上となります。この記事を書いている途中でも誤った理解をしていた箇所が見つかり、習得には時間がかかる技術であると痛感しました。しかし使いこなすことができれば、品質を保ちながらフロントエンドと足並みをそろえてスピーディに開発を進められる強力なツールであることも実感しています。これからも引き続き自己研鑽を重ねていきたいと思います。