Share
Embed
(Vue Fes 2023) 18営業日で350コンポーネント規模のVueアプリにデザインシステムを導入する方法
弊社 (株式会社フライル) では、18 営業日という超短期でデザインシステムを導入しました。このプロジェクトで得た知見を共有致します。
技術的工夫
AST を使用して事前にできる限り自動でマイグレーションした上で判別できない部分に全て TODO コメントを自動付与
ESLint のカスタムルールを実装してできる限りレビューは自動化
デザインシステムが壊れていないか確認するために VRT を実施
Autify による E2E テスト
プロジェクト管理上の工夫
手作業は短期集中でタスクのスイッチングコストをゼロに
進捗は数値で管理
マニュアルテストを複数回実施してバグに対処
最後にデザイナーとペアプロで細かいデザインを修正
プロジェクトを通じた反省と学び
コンポーネントの依存関係を事前に詳細に把握しておくべきだった (コンフリクトが起きるケースが見られた)
マイグレーション自体の間違いについて
まず上記の共有をした後に、技術的工夫 1 点目の AST によるプログラム修正の方法の共有に時間を割こうと思っています。
Yuichiro Yamashita
October 28, 2023
Transcript
66 slides
-
自己紹介 (baseballyama) • 株式会社フライル ◦ TypeScript / Vue / Svelte
◦ Kotlin / Spring Boot ◦ Python / Fast API / Open AI ◦ AWS / Terraform ◦ MySQL / Fargate / S3 / SQS / その他 • Svelteコアチームメンバー ◦ Svelte5に向けて活動中 ◦ 少しだけ Svelte用 ESLintプラグイン • その他 ◦ 最近はひたすらPythonを書いている ▪ この話は来月の JSConf JP で... -
本日みなさんにお伝えしたいこと • Big Bang リファクタリングを実施した経験談 • Big Bang リファクタリングを支援する強力な武器の紹介 ◦
(あらゆるリファクタリングに適用できます!) -
• 前提 ◦ プロジェクトの概要 ◦ Big Bang vs Incremental
• プロジェクト管理面での工夫 ◦ Big Bang を選択した理由 ◦ 我々が重要視したこと ◦ スイッチングコストを極限まで減らす ◦ 重要でないページの細かいデザイン調整は後回しにする ◦ 進捗は数値で見える化 ◦ マニュアルテストを複数回実施 ◦ デザイナーとのペアデザイン • 技術面での工夫 ◦ ESLintのカスタムルールでレビューはできる限り自動化 ◦ 可能な限り自動マイグレーション (今回の目玉) ◦ デザインコンポーネントの破損はVRTで検査 ◦ E2Eテストで重要・頻出導線の破損を防ぐ アジェンダ -
今回の発表は、セクションの区切りごとに DALL·E 3 で描いた画像を挿入してみました。 但し、1枚だけ DALL·E 3 で描いていない画像が1枚あります。 DALL·E 3
で描いていない画像はどれなのか予想しつつ、引き続きお楽しみくださいま せ。 -
今回扱うプロジェクトの使用技術 • Vue3.3 • TypeScript 5.2 • Vite 4.5 •
Storybook / Chromatic • ESLint • Stylelint -
プロジェクトの概要 • プロジェクト規模 (2023/10/28 (土) 現在) ※
それ以外のファイル (例: Svelte) は省略 • プロジェクトのスコープ ◦ UIコンポーネント (35個) は既に実装済み ▪ (UIコンポーネントの設計やデザイン原則などは今回の発表の対象外) ◦ UIコンポーネントをプロダクトに取り込む作業が今回の対象 ファイル種別 ファイル数 行数 Vue 432 71,115 TypeScript 765 9,519 -
プロジェクトの概要 • (デザイン原則を含む) デザインシステムを導入した理由 ◦ サービス全体で一貫したデザインにするため ▪ 一貫したデザインはユーザーを迷わせません ◦ UIの実装を迅速にするため
▪ もう font-size を指定する必要はありません 😄 • なぜ今だったのか ◦ いわゆる大企業と呼ばれる企業様への導入が進行中 ▪ ユーザー数が増える前に大幅なデザイン変更を完了させたかった ◦ 開発者数の増加 ▪ 開発者が増えるほどデザインシステムによる効率化効果が増す -
Big Bang vs Incremental Big Bang (一度に大規模な変更を適用) • 計画とテストが非常に重要
• 一気に大量のコードを変更するのでバグの原因特定が困難 • 機能開発やバグ修正と並走できない (コンフリクトする可能性が高いため) Incremental (小さなステップに分割して変更を適用) • 計画の変更が容易 • テストを頻繁に実行するため、リスクを低減 (分散) できる • 機能開発やバグ修正と並走できる 多くの場合、Incrementalが安全で効率的です。ただし、状況によりBig Bangも選択肢となる場合があります。 -
我々が重要視したこと • 最短期間でリリースする ◦ 特にクリティカルなバグが見つかった時に対応できない期間を最小化するため 最短期間でリリースするために... • 1⃣
(プロ管) スイッチングコストを極限まで減らす • 2⃣ (プロ管) 重要でないページの細かいデザイン 調整は後回しに ◦ マージン・パディングなど... • 3⃣ (プロ管) 進捗は数値で見える化 • 6⃣ (技術) ESLintのカスタムルールでレビューは できる限り自動化 • 7⃣ (技術) 可能な限り自動マイグレーション (今 回の目玉) 品質を維持するために... • 4⃣ (プロ管) マニュアルテストを複数回実施 • 5⃣ (プロ管) デザイナーとのペアデザイン • 8⃣ (技術) デザインコンポーネントの破損はVRT で検査 • 9⃣ (技術) E2Eテストで重要・頻出導線の破損を 防ぐ -
我々が重要視したこと • 最短期間でリリースする ◦ 既存機能にクリティカルなバグが見つかった時に対応できない期間を最小化するため 最短期間でリリースするために... • 1⃣
(プロ管) スイッチングコストを極限まで減らす • 2⃣ (プロ管) 重要でないページの細かいデザイン 調整は後回しに ◦ マージン・パディングなど... • 3⃣ (プロ管) 進捗は数値で見える化 • 6⃣ (技術) ESLintのカスタムルールでレビューは できる限り自動化 • 7⃣ (技術) 可能な限り自動マイグレーション (今 回の目玉) 品質を維持するために... • 4⃣ (プロ管) マニュアルテストを複数回実施 • 5⃣ (プロ管) デザイナーとのペアデザイン • 8⃣ (技術) デザインコンポーネントの破損はVRT で検査 • 9⃣ (技術) E2Eテストで重要・頻出導線の破損を 防ぐ -
1⃣ スイッチングコストを極限まで減らす 以前、Flyleでは、リファクタリングタスクを開発作業のうちの20%を使用する手法を採用し ていました。(Vue2 から Vue3 へのアップグレードの初期はこの方法を採用していまし た。) しかし、自分を含め進捗が芳しくなく、その20%の時間を1人に集約するアプローチに変 更したところ、一気に進捗した、という経験をしました。
これは、複数のタスクに同時期に取り組んだことにより、毎回それぞれのタスクの情報を 思い出すのに時間がかかっていたことが原因であると結論づけました。 以降、Flyleでは、タスクスイッチングのコストを最小化する方法 (つまりインクリメンタル アプローチであろうがビッグバンアプローチであろうが誰かが一気に対応する方法) でリ ファクタリングを実施しています。 -
4⃣ マニュアルテストを複数回実施 Big Bang リリースで恐ろしいことは、バグの発生です。漸進的リファクタリングと比べ、バ グ混入のリスクは圧倒的に高くなります。 バグを全て潰し込むことは現実的ではないでしょう。 しかし、一方で、結局のところお客様が日々お使い頂く上で不便がない状態であれば、 それは実質的にバグがない状態とも言える訳です。 そこで、我々は、機能の詳細な一覧とユーザー権限のマトリクス表を作り、全社員に協
力頂いて、複数回のマニュアルテストを実施しました。 これにより、結果として、リリース後、お客様からの報告を受けたバグはほとんどなかっ たと記憶しています。 -
5⃣ デザイナーとのペアデザイン リリース直前の最終段階では、デザイン仕切れなかった細かな部分に関して、デザイナー1人 対 エンジニア2人 などのペアで、口頭ベースでペアデザインを実施しました。 このフェーズでは、デザインでは表現しきれていなかった細かな部分などをデザイナーが事前に リストアップした上で、ペアデザイン時にまずエンジニアに説明、エンジニアは少ない工数で対応 する方法や代替案を提案し、その場で合意しながら実装まで行う、というプロセスを実施しまし
た。 これにより、特に主要導線のデザイン少ない工数で一気に磨き込むことができました。 振り返ると、短期で取り組む Big Bang タイプのデザイン変更プロジェクトにおいては、この作業 は最後に品質を磨き込む重要なプロセスだったと思います。 -
我々が重要視したこと • 最短期間でリリースする ◦ 特にクリティカルなバグが見つかった時に対応できない期間を最小化するため 最短期間でリリースするために... • 1⃣
(プロ管) スイッチングコストを極限まで減らす • 2⃣ (プロ管) 重要でないページの細かいデザイン 調整は後回しに ◦ マージン・パディングなど... • 3⃣ (プロ管) 進捗は数値で見える化 • 6⃣ (技術) ESLintのカスタムルールでレビューは できる限り自動化 • 7⃣ (技術) 可能な限り自動マイグレーション (今 回の目玉) 品質を維持するために... • 4⃣ (プロ管) マニュアルテストを複数回実施 • 5⃣ (プロ管) デザイナーとのペアデザイン • 8⃣ (技術) デザインコンポーネントの破損はVRT で検査 • 9⃣ (技術) E2Eテストで重要・頻出導線の破損を 防ぐ -
8⃣ デザインコンポーネントの破損はVRTで検査 Storybook と Chromatic を使用してUIコンポーネントに意図しない変更が入っていない かを自動チェックできる仕組みを導入しました。 (これは余談ですが、Storybook でストーリーを for
文で一気に作成する方法がわからなかったので 独自の方法で for 文で作成できるようにしました。一般的にはどうするのが良いのでしょうか?) -
9⃣ E2Eテストで重要・頻出導線の破損を防ぐ Flyleは元々、Autify を使用して、重要導線 (例: ログイン) に対してはE2Eテストを実装し ていました。 今回のリファクタリングプロジェクトにおいても、Autifyが意図しない破損がないかを確認 することで、重要導線が壊れていないかを確認することができました。
(実際にはリファクタリング後にほぼ全てのAutifyのテストが落ちたのでその修正が大変 でしたが、それでも主要導線が動くことが確認できたことは重要だったと思います) -
正規表現ベースでの置換 手軽にできる方法ですね。手軽にできる一方で、意図しない置換が発生する可能性が あります。 例えば、HTMLのID属性を一括で削除したいとします。 正規表現は /\sid=["'].*?["']/ といったところでしょうか。 しかし、これでは const foo
= (bar, id="foo") => {} のような文字列にもマッチしてしまい ます。 これでは正しくリファクタリングができません。 そこで、より高度なリファクタリングをするためには、ASTを変更することによる置換を選 択する場合があります。 -
{ type: 'Program', body: [ { type: 'VariableDeclaration' , declarations:
[ { type: 'VariableDeclarator' , id: { type: 'Identifier', name: 'foo', }, init: { type: 'Literal', value: 'bar', raw: '"bar"', }, }, ], kind: 'const', }, ], sourceType: 'module', } ASTを変更することによる置換 AST (Abstract Syntax Tree) とは、抽象 構文木のことです。 例えば、const foo = "bar"; は、 右のようなASTになります。 -
{ type: 'Program', body: [ { type: 'VariableDeclaration' , declarations:
[ { type: 'VariableDeclarator' , id: { type: 'Identifier', name: 'foo', }, init: { type: 'Literal', value: 'baz', raw: '"baz"', }, }, ], kind: 'const', }, ], sourceType: 'module', } ASTを変更することによる置換 “bar” を “baz” に変更する { type: 'Program', body: [ { type: 'VariableDeclaration' , declarations: [ { type: 'VariableDeclarator' , id: { type: 'Identifier', name: 'foo', }, init: { type: 'Literal', value: 'bar', raw: '"bar"', }, }, ], kind: 'const', }, ], sourceType: 'module', } -
ASTの構造を理解する方法 AST Explorer (https://astexplorer.net/) というサイトがあります。 このサイトでは、HTML, JavaScript, CSS をはじめとし た多くのプログラム言語に関して、ASTを確認できるサ
イトです。 例えば、JavaScriptの場合、Acorn や Espree など多く のパーサーを使用してASTを確認できます。 また、ESTree という JavaScript の AST 仕様は、 ESTreeのGitHubリポジトリで確認できます。 https://github.com/estree/estree/blob/0fa6c005fa45 2f1f970b3923d5faa38178906d08/es5.md -
VueのファイルをASTに変換する方法 各プログラム言語に対するASTの確認方法はわかったと思います。 しかし、Vueファイルには HTML, TypeScript, SCSS など、複数の言語を実装します。どう やってVueファイルの内容をASTに変換すれば良いのでしょうか。 Vueの内部実装はわからないのですが、Svelteの場合、正規表現を用いて<script> ブ
ロックと <style> ブロックを判定しています。 ということで、正規表現で各ブロックを分割しましょう。 const REGEXP_TEMPLATE = /(<(template).*?>)([\s\S]*)(<\/(template)>)/m; const REGEXP_SCRIPT_STYLE = /(<(script|style).*?>)([\s\S]*?)(<\/(script|style)>)/m; -
VueのファイルをASTに変換する方法 各ブロックに分解できたら、プログラムをASTにしていきましょう。 例えば JavaScript を recast を使用して AST にする最小のコードは以下です。
import { parse } from "recast"; const ast = parse("const foo = 'bar';"); -
VueのファイルをASTに変換する方法 得られたASTを走査して変更を加えるコードの雛形は以下です。 import { walk } from "zimmerframe"; walk(ast,
null, { _(node, { state, next }) { // AST に変更を加える処理 manipulate(node); // 次のノードへ next(state); }, }); -
VueのファイルをASTに変換する方法 具体的なASTを変更するコードは以下です。 import type { Node } from "@babel/types/lib";
const manipulate = (node: Node) => { if (node.type === "VariableDeclarator") { const { init } = node; if (init?.type === "StringLiteral") { init.value = "bar"; } } }; -
VueのファイルをASTに変換する方法 また MagicString を使用して書き換えることもできます。 import type { Node } from
"@babel/types/lib"; import MagicString from "magic-string"; const magicString = new MagicString("const foo = 'foo';"); const manipulate = (node: Node) => { if (node.type === "VariableDeclarator" ) { const { init } = node; if (init?.type === "StringLiteral") { const [start, end] = init.range ?? []; if (start != null && end != null) { magicString.overwrite(start, end, "'bar'"); } } } }; -
MagicString とは Suppose you have some source code. You want
to make some light modifications to it - replacing a few characters here and there, wrapping it with a header and footer, etc - and ideally you'd like to generate a source map at the end of it. You've thought about using something like recast (which allows you to generate an AST from some JavaScript, manipulate it, and reprint it with a sourcemap without losing your comments and formatting), but it seems like overkill for your needs (or maybe the source code isn't JavaScript). Your requirements are, frankly, rather niche. But they're requirements that I also have, and for which I made magic-string. It's a small, fast utility for manipulating strings and generating sourcemaps. -
VueのファイルをASTに変換する方法 最後に、変更後のASTを文字列に書き戻す最小のコードは以下です。 import { print } from "recast"; const
jsString = print(ast).code -
VueのファイルをASTに変換する方法 とはいえ、実際に使えるレベルのコードを1から書くのは面倒だと思います。 そこで、今回Flyleで実際に使用したコードをベースにしたリファクタリングツールをライブラリと して公開しました。 vue-service-bay というライブラリです。 https://github.com/flyle-io/vue-service-bay README
に使い方を書いていますので、このライブラリが皆様のリファクタリングライフを劇的 に楽にして、機能開発に専念できる環境づくりに寄与できたらとても嬉しく思います。 また、よければスターして頂けると嬉しいです。 弊社開発チームのメンバーも喜ぶと思います。 -
想定質問 : なぜマイグレーションをコード化する必要があるのか 正規表現を使用して確認しながら一括置換すれば良いじゃないかと思われるかもしれま せん。しかし、この方法だと2つの問題があります • 前のスライドで述べたように誤検知が発生します。 • 実際のプロジェクトでは色んな人が並行で開発しているため、全員の開発のキリが 良いタイミングで一括でマイグレーションする必要があります。
都度都度確認しながらマイグレーションする場合、その間他の全員が待ちになって しまうため、事前にマイグレーションをコード化しておいて、ある時点で一気に置換 する必要があります。 -
まとめ • Big Bang リリースを避けられない場合もある ◦ それでも可能な限りスコープは最小化しよう ◦ そして段取りが命 •
自動化できるものは全て自動化しよう ◦ Big Bang の期間はバグ修正すらできないのでリスクが高まっていく ◦ 機械は人間よりも確実で早い ◦ vue-service-bay もよければ使ってください • ペアデザインはおすすめ ◦ 事前に決まっていない細かなデザインは最後にデザイナー・エンジニア間のペア作 業で調整するのがおすすめ。 • マニュアルテストは何度もやろう ◦ お客様にご迷惑をおかけしないために -
デザインシステムを導入した個人的な感想 • CSSあまり書かなくて良いの最高 (単純にコードが見やすい) • デザインシステムというレールがあるからこそESLint / Stylelint でより縛れるから
最高 ◦ よりコードの統一感を維持できる ◦ コードレビューも楽になった • デザイナー間とのコミュニケーションが簡単になって最高 ◦ デザインシステムと乖離するデザインがあったら単に相談すればよくなった。 そしたらデザインチームで検討してデザイン原則・デザインシステムに適合し たUIに変更してくれる ▪ (以前は一旦ここはそれで実装するか、みたいな意思決定が多少あったのでコードがぐちゃっ とする原因になっていた)