この記事は、 NTT Communications Advent Calendar 2023 19日目の記事です。
この記事では、TypeScript未経験のインターン生にすぐにSkyWayの開発に取り組んでもらうために、TypeScriptの学習用コンテンツを作成した話を紹介します。 学習用コンテンツでどのようなスキルを身に着けてもらったのか、効果的に学ぶためにどのような点を工夫したのかについても説明します。
はじめに
皆さまこんにちは。イノベーションセンター SkyWay DevOps プロジェクト所属の@sublimerです。
SkyWayのチームでは、今年の8〜9月に現場受け入れ型のインターンシップを実施しました。 インターン生を受け入れるにあたって、すぐにSkyWayの開発に取り組んでいただけるようにTypeScriptの学習用コンテンツを作ったので、本記事ではその紹介をします。
学習用コンテンツの目的
今回コンテンツを制作するにあたって、以下のスキルを学ぶことを目的として内容を検討しました。 また、インターンシップの期間は2週間で時間が限られているため、学んでほしい内容には優先順位を付けて、優先度が高いものから順に学んでもらうようにしました。具体的には下記の通りです。
- TypeScriptでのサーバーサイドアプリケーション開発
- ドキュメント作成
- コードレビューのreviewee
- テストコード
- CI/CD
- セキュリティ
SkyWayでは、サーバーサイドアプリケーションをTypeScriptで開発しているため、まずはTypeScriptでのサーバーサイドアプリケーション開発を学んでもらうことを目的としました。 また、普段の開発では仕様を考える際に草案をドキュメント化して議論したり、書いたコードをGitHub上でレビューしているため、これらの点についても経験できるようにしました。
テストコードやCI/CDについては、アプリケーションを作る上では必ずしも必要ではないのですが、商用のサービスを開発する上では必要となるスキルであるため、これらについても学べるようにしました。 また、セキュリティについても観点の1つとして意識できるようにしました。
TypeScript学習用コンテンツの紹介
今回は、「指定されたnpmパッケージをインストールしても大丈夫そうか判定するAPI」というお題で、アプリケーションを作ってもらうことにしました。
このアプリケーションを開発するためには、以下のような機能を実装する必要があります。
- npmのAPIを利用して、指定されたnpmパッケージの情報を取得する
- GitHubのAPIを利用して、対応するGitHubリポジトリの情報を取得する
- GitHubのAPIを利用して、対応するGitHubリポジトリのownerの情報を取得する
- 以下のような基準を満たしているかどうかを判定して、その結果に応じてレスポンスを返す(基準はあくまでも一例)
- 直近1年以内に更新がなされているか(アクティブ度合い)
- インストール数が500以上あるか(利用実績の有無)
- コントリビューターが5人以上いるか(複数人がコードに目を通しているか)
実装にあたっては、SkyWayのサーバーサイドアプリケーションでも利用しているフレームワークであるFastifyを利用してもらいました。 (余談ですが、Fastifyを利用している組織の一覧にSkyWayも載せていただきました。)
SkyWayのシステムでは、あるアプリケーションから別のアプリケーションのAPIを呼び出す処理が複数あります。 そのため、APIを呼び出し、その結果を元に処理を行うという部分は、SkyWayの開発を体験する際に役立つと考えました。 npmやGitHubのAPIを利用するメリットは、レートリミットなどの制限はあるものの、今回のアプリケーションで利用する範囲においてはAPIキーなどの認証情報を用意する必要がないことです。 今回はインターンシップという限られた時間の中で開発をしてもらう都合上、アカウントや認証情報の準備が不要なAPIのみを利用して、開発ができるようにしました。
また、今回はAPI呼び出しの処理をクライアントライブラリを使わずに実装してもらうことにしました。 APIのレスポンスはJSON形式となっているため、TypeScriptでレスポンスのデータを扱う際は、型定義を用意する必要があります。 一例として、GitHubのリポジトリ情報を取得するAPIは、以下のドキュメントにあるようなデータを返します。
実際のアプリケーションではこれらのデータのうち一部しか使わないので、必要なデータのみを抽出した、以下のような型定義を用意する必要があります。
type RepositoryInfo = { name: string; full_name: string; owner: { login: string; id: number; }; stargazers_count: number; created_at: string; updated_at: string; pushed_at: string; };
JSONのデータを元に型定義を作成することで、TypeScriptでは型による表現がどのようになっているのかを学べます。
ドキュメントの作成やコードレビューの観点についても、APIドキュメントを作成してもらったり、GitHub上でコードレビューをしてもらうことで、実際の開発に近い形で経験できるようにしました。
また、テストコードやCI/CDについても、取り組みやすいようにコンテンツを検討しました。 具体的には、「基準を満たしているかどうかを判定する」というロジックは複数の条件の組み合わせで判定する必要があるため、テストコードで挙動を担保する価値が大きい部分です。 特にこの部分について、テストコードを書いてもらうことで、テストコードの価値をより実感してもらえるのではないかと考えました。 加えて、外部のAPIを呼び出す箇所はモックを利用してテストを実行することになるため、どの部分をどのようにモックするかという観点についても学べるようにしました。 テストにおいて何をどこまでモックすべきかについては、 fukabori.fmの第13回が非常に参考になる のでおすすめです。
さらに、セキュリティについても、直接ではないものの意識できるようにしています。 npm等のパッケージマネージャーを利用する際は、サプライチェーン攻撃などのセキュリティリスクについて意識する必要があります。 例えば、使おうと思ったパッケージが長い間メンテナンスされていなかったりインストール数が非常に少ない場合、脆弱性の対応が行われなかったり、悪意のあるコードが含まれてリリースされても誰も気づかない、といったリスクが想定されます。 そのため、今回のコンテンツでは、npmパッケージの情報を取得し、その情報を元に判定の処理を実装してもらうことで、npmなどのパッケージマネージャーを利用する際のセキュリティについても意識できるようにしました。 ソフトウェア開発のサプライチェーンセキュリティについては、NTT Communications Advent Calendar 2023 14日目の記事で詳しい解説をしていますので、こちらもぜひご覧ください。
このアプリケーションの開発では以下のようなタスクを行うため、身につけてほしいスキルを効率的に学ぶことができます。
- TypeScriptでのサーバーサイドアプリケーション開発(必須)
- TypeScriptの書き方の理解
- Fastifyの使い方の理解
- 非同期処理(Promise、async/await)の扱い方の理解
- APIの設計
- ドキュメント作成(必須)
- コードレビュー(必須)
- テストコードの追加(ここまでできるとGood)
- GitHub ActionsによるCI(ここまでできるとGood)
- Cloud Runへのデプロイ(ここまでできるとGood)
- デプロイの自動化(できなくても大丈夫)
- 新機能の実装(できなくても大丈夫)
タスクについては、多すぎても少なすぎてもつまらなくなってしまうと考え、多めに準備した上で「必須」「ここまでできるとGood」「できなくても大丈夫」にカテゴライズして、必須から先は進捗状況に応じて取り組んでもらうことにしました。
取り組んでもらった結果
今年の8月28日から9月8日にかけてインターンシップに参加してくださった鈴木さんに、実際にこちらのコンテンツに取り組んでいただきました。 鈴木さんはTypeScriptの経験は無いとのことでしたが、「できなくても大丈夫」のタスクまで実施していただき、良い意味で期待を裏切っていただきました。 そして、その後の商用環境で動いているコードの改善にもスムーズに取り組んでいただきました。
鈴木さんのインターンシップの取り組みは、以下のブログ記事に詳しく書かれているので、ぜひご覧ください。
より高度な内容について
今回は、サーバーサイドアプリケーションの実装、テストコードの追加、CI/CDなどに取り組んでいただきましたが、このコンテンツはより発展的なものにできると考えています。 一例として、以下のような応用的な取り組みが考えられます。
- OpenAPIなどのAPI定義を元にした、ドキュメントやクライアントライブラリの自動生成
- OpenTelemetryやAPMなどを用いたアプリケーションのモニタリング&改善
- RESTではなく、GraphQLを利用してみる
- 生成AIと組み合わせた判定処理の高度化
- npm以外のPackage Registryへの対応
また、題材自体は言語やフレームワーク、クラウドサービスに依存する箇所は少ないため、GoやPython、Rustのような他の言語や、Azure、AWSといったGoogle Cloud以外のクラウドサービスを利用してもらうことも可能です。 もし、オンボーディング用のネタに困っている方がいれば、ぜひ参考にしてみてください。
おわりに
SkyWayでのインターン生に取り組んでもらった、オンボーディング用のコンテンツについて紹介しました。
インターンは期間が限られているため、参加者のスキルと実際に業務に取り組むためのスキルの間にギャップがある場合は、できるだけ時間をかけずに必要なスキルを身に着けてもらう必要があります。 今回のコンテンツは人にもよるかとは思いますが、TypeScript未経験でも概ね2〜3日程度で一通り取り組めるボリュームになっています。 また、実際のサービス開発に近い形で取り組めるように、ドキュメント作成やコードレビュー、テストコードの追加やCI/CDなども取り入れています。 インターン生の受け入れに限らず、オンボーディングやプログラミング学習用のコンテンツを作成する際の参考になれば幸いです。
以上、 NTT Communications Advent Calendar 2023 19日目の記事でした。明日もお楽しみに!
