大規模 Vue アプリケーションの TypeScript 移行

Editor's Notes

• #2: 大規模 Vue アプリケーションの TypeScript 移行 という題で弊社の事例を紹介いたします。 よろしくおねがいします。
• #3: ちょっとだけ自己紹介を。 株式会社スタディストの笹木と申します。 社内では技術支援ユニットというチームで、主にWebフロントエンドのリードみたいなことをやってます。 本勉強会のテーマである、今気になってるものは TypeScript です。 ちょっと勉強会テーマに対して無理があるんじゃないか疑惑がありますが、社内勉強会向けに温めてたものなのでご容赦ください。
• #4: 本日お話する内容は概ねこの3テーマです。 まず、弊社が開発している サービス Teachme Biz と、現状の技術構成をお話します。 次に、現状の課題感とソレに対して TypeScript ならどう解決できるのかという理想ベースのお話をします。 最後に、実際に移行作業に行ってみて、どんな壁があったか、どのようなアプローチで解消したかの事例をご紹介いたします。
• #5: まず TeachmeBiz という弊社のサービスについてです
• #6: Teachme Biz は、ビジュアルベースの手順書の作成、共有を簡単にした、手順書マネジメントプラットフォームです。
• #7: 簡単に言うと、従来の文字だらけでわかりづらい手順書を、ビジュアルベースで統一されたフォーマットの手順書におきかえることで、企業の生産性を高めていこうというサービスです。
• #8: クライアントには iOS や Android といったネイティブアプリもありますが、本日はこちら Webフロントエンドについてお話いたします。
• #9: こちらが Teachme Biz Webフロントエンドの技術スタックとなっています。 基本は Vue2 を使って SPA を構築し、 Storybook でコンポーネントを管理、eslint でコード品質を揃えて、Jest や reg-suit で品質担保といった、よくある、比較的モダンな構成となっています。
• #10: また、本日のメインである TypeScript についても、歴史的経緯などもあり、長年使用せずに JavaScript だけで開発してきたというのが現状になります。
• #11: ここからは現状の技術構成における課題感と、TypeScript による解決の話に移りたいと思います。
• #12: 最初は非常に順調だった Teachme Biz のフロントエンドも、長らく運用を続け、サービスや組織がスケールするごとに、無視できないレベルの課題が溢れてきました。 それらは様々なレイヤーで生じる多種多様な問題でしたが、多くは一つの原因に帰着するものです。ソレはなにか。
• #13: シンプルに、型がない。ということです。
• #14: 型がないと開発にどんな問題があるのか、現状のフロントエンドの課題感を整理し、危険/無秩序/非効率/暗黙知 という 4つの項目に分類しました。
• #15: 危険 値に Null が入る可能性があるか判断できないというよくある問題です。 弊社でも、必要なNull チェックを怠って機能が動かなくなってしまったという事例があるぐらいには、サービスの根幹への影響のある問題です
• #16: 無秩序 これは型がないことにより、コードの実装方法、参照方法の自由度が高まり、一貫性のない無秩序なコードが量産されてしまうことです。 始めは些細な歪みでも、割れ窓化が進み、一貫性のないカオスなコードベースが出来上がっていきます。
• #17: 非効率 型情報がないと、エディタが型の推論をできずに開発生産性が下がってしまいます。 特に vscode と TypeScript の相性は非常に良いので、ツールの力を借りれるとこでは借りていきたいところです。
• #18: 暗黙知 コードに関する情報が経験則だったり、実際にコードを読まないと使い方がわからなかったりする問題です。 中途半端な認識でコードを改修してしまうと、先程の無秩序にも繋がってしまいます。
• #19: 以上、危険、無秩序、非効率、暗黙知。型がないことによる問題が４種類ありました。
• #20: これらの問題を解決するため、 TypeScript へコードベースを移行することを考えてみます。 TypeScriptに移行することで、
• #21: 危険だったコードは Null 安全に
• #22: 無秩序だったコードは厳密な型定義によってアーキテクチャを保護
• #23: 非効率だった開発は、型定義よってエディタのパワーを最大限に引き出せるように
• #24: 暗黙知だったコードベースは、型がそのままドキュメントとして機能するように
• #25: これらの分析結果から、TypeScript への移行は銀の弾丸になると判断し、移行を決意しました。
• #26: では実際に TypeScript 移行を行おうとすると、どんな問題があり、どう解決したのかを最後にお話します。
• #27: 先程 TypeScript は銀の弾丸だと言いましたが、現実はそんなに甘くなかったです。 JavaScriptプロジェクトのTypeScript への移行は、新規に TypeScript プロジェクトを立ち上げるより遥かに難しいと言われています。
• #28: 弊社においても例外はなく、移行を阻む壁が、大きく分けて4つ現れました。
• #29: それがこちらの4つ。 実務経験者が居ない、現行コードとの並走が必要、そもそもフレームワークが相性悪い、APIインタフェースがよくわかならい。 それぞれについて、どのようなアプローチで解消しているのかをお話します。
• #30: まずひとつ目、単純に TypeScript の実務経験者が居ない。 これは私自身も含めてです。個人開発なんかではよく触っていましたが、仕事として、動くプロダクトのために書いた経験はまったくありませんでした。
• #31: なので、まずは自分がリードできるように、体系的に言語理解を深めるというステップを最初に踏みました。 キャッチアップには公式ドキュメントなどのオンラインソースも多く当たりましたが、体系的な理解を深めるという意味では、この2冊の書籍に助けられました。
• #32: こちらの実践TypeScriptについては、社内で輪読を行うことで、自分の理解を深めながら社内への TypeScript の普及を促すことが出来ました。
• #33: また、段階的な移行の中で、プルリクエストを小さく頻繁に出し、積極的に多くの人にレビューを求めることで、メンバーに TypeScript に慣れて貰えるように心がけました。
• #34: これで経験者不足の問題は、とりあえず突破することができました。
• #35: 2つ目の壁は、機能開発を止めることは出来ないので、現行コードとの並走が必要ということです。 TypeScript移行は、どうしても顧客価値を生み出す改修ではないため、本業の片手間で行う必要があります。
• #36: そのため、移行の段階を分け、少しずつプロダクトと組織に TypeScript を馴染ませるように進めています。 左側が移行開始直後の状態で、リポジトリに対して JavaScript が25%。 右側が直近ですが、 JavaScript のシェアから1ポイント TypeScript が奪って、1.1% となっています。 このように、少しずつ TypeScript のシェアを高めていき、半年から1年のスパンでの完全移行を目指しています。
• #37: 移行の段階については、全5ステップに分類しています。 まず1ステップ目は、副作用がなく、ドメイン知識も不要な関数。 配列操作とかテキスト操作といった純粋なやつですね。 これならプロダクトに詳しくない人でもレビューが容易でとっつきやすいです。
• #38: ステップ2 副作用はないが、ドメイン知識が必要な関数。 具体的には権限判定ロジックやデータのバリデーション関数といったもの。
• #39: ステップ３，ドメインと密接なデータモデル。 ここらへんが TS 化の恩恵を一番受けやすいですが、どのような型付けを行うのか、設計を慎重に行う必要があるフェーズです
• #40: ステップ4 Vuex ストア周り。 TeachmeBiz では、APIのハンドリングは全て Vuex 上のグローバルストアで行うというルールになっているので、API絡みの型に、このステップで手を入れていきます。
• #41: 最後に Vue コンポーネント。 ここは次の壁でお話しますが、優先度も低く、最悪やらなくても良いと思っているので、一番下のステップになっています。
• #42: ちなみに、これらのステップは、厳密に前ステップが終わらないと次に進めないというわけでなく、ある程度そのステップの方針と移行例が出たら、次のステップに進んで方針を固めるというサイクルを回すことで、他のメンバーでも移行作業を行いやすいように進めています。
• #43: これで2つ目の壁も攻略しました。現時点ではですが、 TypeScript 移行とプロダクト開発を並走することが出来ています。
• #44: 壁3つ目、そもそも Vue や Vuex と TypeScript の相性が悪い。 これは Vue と TypeScript に少しでも触れた方なら聞いたことがあるかもしれませんが、 Vue、少なくとも今主流の Vue2 に関しては、その独自性から TypeScript との相性はかなり悪いです。
• #45: この壁に対しては、型安全可できない箇所を割り切って、コスパの良い移行をするための、調査、分析を繰り返しました。 特に、その気になればもっと型安全化は出来るが、既存コードを大きく書き換えてしまうアプローチは取らないという決断を取りました。 これは現行コードとの並走が必要という兼ね合いもあり、移行してるコードとしてないコードで差異が大きすぎるという状況を作りたくないというのがあります。 また、将来的に Vue バージョン3 への移行を行うことを考えると、マイグレーションしやすいコードを維持することも重要だと考えています。 この辺りの落とし所については、こちらの 実践TypeScript にかかれている内容を大いに参考にしました。 また、Vuex への型付けについては、こちらの vuex-type-helper という型レベルのみを提供するライブラリを採用し、コスパの良い移行方針を定めることができました。
• #46: 落とし所を見つけて妥協するというのも一つの解決策ということで、3つ目の壁もクリア。
• #47: 最後は、APIの仕様が曖昧で、APIレスポンスに対して型付けが難しいという壁です。
• #48: その原因は、Railsで動いている API のドキュメントはあるにはあるんですが、品質が怪しいというところです。
• #49: このドキュメント、それなりに網羅はされているのですが、フロントエンドで信頼するには正確性に欠けるという問題があります。 特に、TypeScriptで必要とする型の情報がほとんど定義されていないため、TS移行の壁を乗り越えるためには使えません。 では既存ドキュメントを更新していくのかと言うと、このドキュメントは APIBlueprint という古くからあるフォーマットで書かれており、情報も少ないためメンテナンスが難しいです。 APIBlueprint の開発はほぼ止まっていることから、 Swagger のような強力なエコシステムの成熟も期待できません。
• #50: ではどうするか、ずいぶんと欲張りな話になってきましたが、TypeScript移行と並行して、APIドキュメントもOpenAPIへ移行しようと決意しました。
• #51: イケイケの OpenAPI 3 を使うことで、型情報まで明記したドキュメントを再構築。 信頼性担保のため、今後は RSpec のような API の自動テストで、ドキュメントの定義通りの挙動をしているのかをテストし、ドキュメントの劣化を防ぐ予定です。
• #52: そして、OpenAPI といえばその豊富なエコシステム。 今回は openapi-typescript という、、スキーマを元に型を生成するライブラリを採用しました。
• #53: 少し分かりづらい具体例ですが、OpenAPI のスキーマから生成した型情報を使う例です。 ここでは getUsers というAPI名を指定することで、ユーザー一覧APIのレスポンスの型を推論できるようになってます。 (このスライドいらないかも)
• #54: この辺りは実験的な段階ではありますが、APIを含んだ型安全もできるようになりました。
• #55: まとめると、JavaScriptプロジェクトを TypeScript に移行する上で、このような4種類の壁がありましたが
• #56: いずれも、今のところは適切なアプローチで乗り越え、順調に TypeScript 移行を進めることができています。
• #57: 最後に本スライドのまとめです。 本日は、 JavaScript で書かれた型のない Webアプリケーションには、危険、非効率、無秩序、暗黙知といった問題がいっぱいあることをお話しました。 それらを解決するための TypeScript は一見銀の弾丸でしたが、適切なアプローチを取って乗り越える必要がある壁がいくつかあることについて、弊社の事例を紹介いたしました。 TypeScript移行はまだまだ序盤であるため、今回お話した内容が正解かどうかはわかりませんが、じわじわとリスクが取り除かれていることは実感しているので、今後も継続しながら、プロセスの改善ができればと考えています。 以上です。ご清聴ありがとうございました。