はじめに

こんにちは。西日本テクノロジー＆イノベーション室の樋尻です。

私の所属する西日本テクノロジー＆イノベーション室では、エンジニアリングにまつわる様々な活動をしており、様々な開発を効率的に進めることができるようなコンテンツ開発も担っています。その1つとして、9月末に「SPA + REST API構成のサービス開発リファレンス」を公開しました。これは、シングルページアプリケーション（以下SPA）とREST APIから構成されるWebアプリケーションを開発する際に活用して頂けるコンテンツになっています。

コンテンツはこちらで公開しています → SPA + REST API構成のサービス開発リファレンス

このサービス開発リファレンスでは、SPAとREST APIの理解を深めるために、サンプルとして公開しているアプリケーションと同構成での開発を体験するハンズオン型の学習コンテンツを提供しています。 このハンズオンコンテンツ（以下ハンズオン）は、サービス開発リファレンスのトップページにて公開しており、どなたでもご利用いただけます。

私はサービス開発リファレンスの開発チームの一員として、ハンズオンの作成を担当しました。 この記事ではハンズオンの簡単な紹介と、どのようなことを考えながらハンズオンを作成していったのかをご紹介します。

ハンズオンの概要

ハンズオンでは、チュートリアルとしてよくある題材でもある「ToDo管理」のWebアプリケーションを、SPAとREST APIの構成で開発していきます。SPAとREST APIで主要となる部分を実際に開発してもらうことで、どのようなことを考え、どのようなことを実装しなければいけないのかを体験できます。

サービス開発リファレンスでは、他コンテンツとしてチャットを題材としたサンプルアプリケーション（以下example-chat）も提供しています。このexample-chatの活用方法についてもハンズオンで体験頂けるよう、example-chatと同じ技術要素を使用しています。

具体的には、SPAの開発にはReactとTypeScriptを、REST APIの開発にはJavaと弊社が開発しているJavaアプリケーション開発/実行基盤であるNablarchを使用します。

また、SPAとREST APIを分離しやすくするため、両者間のインタフェース定義としてOpenAPIを使用しています。OpenAPIドキュメントを作成することで、SPA側ではクライアントコードを自動生成し、REST API側ではインタフェースと実装が乖離していないかをテストするといった用途に使用します。

作成にあたって意識したところ

SPAについて丁寧にガイドする

このハンズオンは、当初、社内へのサービス開発リファレンス展開の手段として企画しました。ハンズオンの実施対象を検討する際、社内の案件傾向を踏まえて、JavaでのWebアプリケーション開発経験はあるがSPAの開発経験はそれほど無い人も多いのではないかと想定しました。その場合、Reactを使用したSPAの開発は、REST APIと比較するとどうしても取り掛かるためのハードルが高くなるだろうと考えました。

幸い、Reactのドキュメントは全て日本語化されている上、実装する上でどのように考えればよいかといった考え方も含め、かなり丁寧に説明してくれています。私自身もReactを学習する上ではこのドキュメントがとても役立ちました。 このReactのドキュメントを活用するため、ハンズオンを進めていく中で関連するページがある場合には、理解の助けとなるように該当ページへのリンクを細かに記載するようにしました。

Reactを使用してSPAを実際に開発する場合、例えばコンポーネントの分割であったり、状態の持たせ方であったりといったことを考えていくことなります。Reactのドキュメントには、こういったことに対する考え方のヒントが紹介されており、設計する上でとても参考になります。そのあたりを分かりやすく体験してもらうように、ハンズオンでの開発手順を、Reactの公式ドキュメントで案内されているような開発手順に近くなるように配置しました。そうすることで、Reactのドキュメントと合わせて読みやすくなるため、より取り掛かりやすくなるようにしました。

example-chatを活用するための具体例を示す

サービス開発リファレンスでは、SPAとREST API構成のWebアプリケーション開発で参考にできるexample-chatを提供しています。このexample-chatを実際の開発で有効に活用するためには、example-chatがどのように実装されているかを理解する必要があります。

そこでハンズオンでは、このexample-chatの実装を参考にできるような箇所については、実際にexample-chatから実装を流用して実装するといった体験をしてもらうようにしました。

example-chatはハンズオンのToDo管理と違って様々な機能を実装しているWebアプリケーションです。ハンズオンではその全てを理解できるわけではありませんが、実際に使ってみることで、どのように参考にできるのかをイメージするための助けにはなるだろうと考えました。

実際の開発案件で役に立ちそうな実装をする

使用するライブラリ各々のチュートリアルを参照すれば、それぞれに特化した部分の実装を体験することはできますが、実際の開発ではWebアプリケーションとして横断的に様々な実装が必要になってきます。

例えば、運用するためには認証機能が何かしらの形で必要になります。その他、運用環境でフロントエンドとバックエンドを分けて配置した場合等はオリジン間リソース共有の仕組みも必要になります。

ハンズオンではWebアプリケーション全体を開発するといったメリットを活かし、Webアプリケーションを開発する際に必要となる可能性が高い実装についても体験できるようにしました。

説明はSPAとREST APIに関するところに絞る

ハンズオンではWebアプリケーションを作成しますが、その全てについて説明を見ながら実際に実装すると、ハンズオンのボリュームがとても大きくなってしまいます。ハンズオンを作成していた当初はまさにこの状態になり、当初想定していたボリュームからどんどん膨らんでいってしまいました。

そこで、SPAとREST APIに直接関係が無い部分については極力除外するようにしました。使用するフレームワークに関する設定や環境設定を予め実装したプロジェクトを用意し、ハンズオンではそのプロジェクトからスタートしてもらうようにしました。そうすることで、体験してもらいたい部分に集中してもらえるようにしました。

また、REST APIはその後続にある業務ロジックについてはREST APIと直接関係が無いため、詳細な仕様や実装については説明を省略しました。そうすることで、ハンズオンではREST APIの作成に集中してもらえるようにしました。

自己学習をしやすくする

サービス開発リファレンスを広くお届けするために、その第一歩になりうるハンズオンは取り組みやすい形にできればと考えました。

問いを多く用意して自身でより考えてもらうといった形式にした場合、講師や経験者が近くにいるような状況であればよいのですが、そうでない場合には進めるのが難しくなることもあるのではと考えました。リモート環境下でハンズオンを進めていただくことを想定した場合に、こういった状況が発生しやすそうにも感じました。

そのため、基本的に一人で納得しながら自分のペースで進められるような形式となるように意識しました。自身で考えるよりも体験してもらうことを重視し、より多くの説明を丁寧に書くよう心掛けました。これにより、一人でもハンズオンを体験して頂きやすくなったのではないかと考えています。

有用なコンテンツであり続けるための取り組み

受講者へのフィードバック依頼

ハンズオンは「受講者にとって有益な体験になる」ことを目指しているため、受講者がどのように感じたかが重要になります。そこで、ハンズオン終了後に受講者に対してアンケート回答によるフィードバックをお願いすることにしています。ハンズオンに対してどのように感じたか、どういったものがあると嬉しいか、といったようなことをヒアリングするように努めています。

すべての受講者にとって最適な形にすることは難しいですが、「受講してよかった」と感じて頂けるような内容にするため、受講者からのフィードバックは真摯に受け止め、改善に役立てていこうと考えています。

一例ではありますが、トライアルとして部内の何名かのメンバーには先駆けてハンズオンを受講頂き、そこでも沢山のフィードバックを頂きました。全てに対応できているわけではありませんが、多くは実際にハンズオンの改善ポイントとして取り込みました。

サービス開発リファレンス全体の継続的なアップデート

SPAやREST APIも含め、社内からの需要や世の中の技術トレンドといったものは変化していきます。そういった中で、サービス開発リファレンスが「実際の開発で役立つもの」であるために、ここで紹介したハンズオンを含めてサービス開発リファレンス全体を継続的にアップデートしていく予定です。

まとめ

今回は、サービス開発リファレンスの「ハンズオン」について紹介しました。これからの開発にお役立ていただけましたら幸いです。

本コンテンツはクリエイティブコモンズ(Creative Commons) 4.0 の「表示—継承」に準拠しています。