目次

URLの境界でフロントエンドフレームワークを切り替え、ページの読み込みごとに1つのフレームワークだけを動かします。置き換え用の画面の開発と、ユーザーに公開するための変更を分け、各リリースで明確なロールバック手順を確保します。

要点#

  • ドキュメントごとに1つのフレームワークを動かし、新旧のルートグループ間ではページ全体を読み込むナビゲーションを使います。
  • 置き換え用の画面は、ユーザーに有効化する前にmainへマージします。
  • どちらの実装も動作できるよう、URL、API契約、永続データの互換性を維持します。
  • 既存のエンドツーエンドテストが同じ操作と期待結果で通ることを必須とし、動作の変更は実装前に合意します。

境界を選ぶ#

この手法は、アプリケーションの各ルートに対してホストが同じHTMLエントリーポイントを返す、ブラウザー描画型のシングルページアプリケーションに適しています。どちらの実装も既存のバックエンドで動作する必要があります。サーバーで描画するアプリケーションでは、ルーティングの判断をサーバー側で行ってください。以下のブラウザー用エントリーコードだけでは不十分です。

公開ページと認証が必要なダッシュボード、顧客向けページと管理画面など、ページ全体の読み込みを許容できるルートグループを選びます。頻繁な操作は1つのグループ内に収めます。境界を越えるとメモリー内の状態が失われるため、導入前に未保存のフォームへの対処を済ませます。

個々の画面を別々に実装しても、移行はルートグループ単位で段階的に進みます。ダッシュボードの置き換え版を開発している間も、既存のダッシュボードはすべてReactのまま維持できます。作業が止まっても、ユーザーは有効な実装を使い続けられますが、2つのコードベースの保守には引き続き時間がかかります。

起動するフレームワークを1つにする#

ブラウザーのエントリーポイントでは、どちらのフレームワークも起動する前に、使う実装を一度だけ選択します。たとえば、公開ページにはFoldkitを使い、/dashboardとその配下には引き続きReactを使えます。

snippet.txt
const isDashboard = (path: string) =>
  path === "/dashboard" || path.startsWith("/dashboard/");

const start = isDashboard(window.location.pathname)
  ? () => import("./dashboard-react/entry")
  : () => import("./public-foldkit/entry");

void start().catch(showStartupError);

各エントリーモジュールがそれぞれのフレームワークを起動します。境界を越えるリンクにはページ全体を読み込むナビゲーションを使い、各実装の内部ではクライアントサイドルーティングを使います。双方向の移動、直接アクセス、ブラウザーの「戻る」をテストします。ルーティングのテストには/dashboardxも含め、/dashboard/に一致しないことを確認します。

動的インポートにより、バンドラーはエントリーコードを分割できます。ただし、使わないフレームワークが一切ダウンロードされないと断言する前に、本番ビルドの出力とネットワークリクエストを確認してください。共有インポート、プリロード設定、ビルド設定が結果に影響することがあります。起動に失敗した場合も、目に見えるエラー表示と復旧操作が必要です。

開発とリリースを分ける#

各ルートグループを4つの段階で進めます。

1. 準備: 現在の動作、バンドルサイズ、既存のエンドツーエンドテストの結果を記録し、意図的な差異について合意します。 2. 開発: 有効なエントリーが旧実装を起動する状態を保ちながら、小さなプルリクエストで置き換え用の画面をマージします。 3. 切り替え: 独立したエントリーポイントの変更で置き換え版を有効にし、同じ受け入れチェックを実施します。 4. 削除: 合意した観察期間を経て、旧実装とその依存関係を削除します。

レビューの単位は、内容を把握できる小ささに保ちます。提示されたtaimeiの移行計画では、22件のIssueと、プルリクエストあたり最大10ファイルという目標が使われていました。これらは計画の例であり、安全性の証明ではありません。また、完了したIssueがそれぞれ同じ作業量を表すわけでもありません。

旧実装を削除するまでは、以前のエントリー選択を復元してデプロイするだけでロールバックできるようにします。その手順をテストし、所要時間を測定します。切り替えの差分が小さければリリース時の変更を限定できますが、置き換え用の画面に不具合がないことまでは保証できません。

互換性を測定可能にする#

既存のエンドツーエンドテストの操作とアサーションを維持します。マークアップの変更に伴ってロケーターの変更が必要になる場合はありますが、移行を通すためにアサーションを緩めると、動作が維持されたという根拠が失われます。意図する差異はコーディング前に記録し、記載のない差異は不具合として扱います。

次の4つの領域を明示的に確認します。

  • 既存のURL、ディープリンク、不明なルートの処理。
  • 認証、認可、APIリクエストの互換性。
  • 共通スタイル、キーボード操作、アクセシビリティ上の動作。
  • 本番用JavaScriptのサイズと、重要なユーザーフローの所要時間。

ロールバックにはデータの互換性も必要です。新しいフロントエンドが、古いフロントエンドでは読めない保存形式で書き込む場合、エントリーポイントの復元だけでは不十分です。永続化形式の互換性を維持するか、テスト済みの変換手段を用意します。CSSクラスが一致するだけでは、見た目やアクセシビリティの同等性は証明できません。

必要に応じてフラグを追加する#

フィーチャーフラグは、顧客グループごとの公開や、デプロイを伴わないロールバックに役立ちます。Cookieまたはユーザーに応じて適切に生成されたサーバーレスポンスを使い、どちらのフレームワークも起動する前に読み取ります。値がない場合や無効な場合は、既存の実装を選択します。ブラウザーから読めるフラグが制御するのは表示であり、サーバー側の認可は独立して維持する必要があります。

ロールバックが反映されるタイミングを正確に定義します。サーバー側の公開対象リストを変更しても、すでに動作中のタブは更新されません。起動後に/api/meを通じてCookieを更新する場合、更新後の選択が適用されるのは次にドキュメントを読み込むときだけです。即時に復旧するには、明示的な更新または再読み込みの仕組みが必要であり、フラグの保存先が分散している場合は反映に遅延が生じることもあります。

フラグの両方の値でエンドツーエンドテストを実施します。共有キャッシュに保存されるHTMLに顧客固有のフラグを埋め込むことは避け、ロールバック対応の終了後は旧コードとともにフラグも削除します。1つの画面内で切り替える必要が出てきたら、境界を再検討してください。その場合、この手法が意図的に避けている統合作業が必要になります。

次のステップ#

リスクの低いルートグループを1つ選び、リリース用チェックリストを作成します。維持するユーザーフロー、許容する差異、データの互換性、そして復旧時間を測定したロールバック手順を含めます。

出典: https://zenn.dev/yasuakiomokawa/articles/de83bb4c4ea928

目次