Python（バックエンド）とTypeScript（フロントエンド）を分ける構成は珍しくありません。しかし2言語構成の本当の問題は「言語を分けること」自体ではなく、両者のAPI型が手書きでずれていくことです。ある個人開発アプリの実装記録から、OpenAPIだけを唯一の境界にする設計を紹介します。

なぜPythonだけで画面まで作らなかったのか

このアプリは、時系列処理・データ取得・機械学習をPython（FastAPI）、操作画面をTypeScript（React）に分けています。すべてPythonで完結させる選択肢もありましたが、ダッシュボード的なUIの実装効率と型の恩恵を考え、責務ごとに言語を変える構成を選んでいます。

境界をOpenAPIだけに絞る

2言語構成でよくある事故は、バックエンドのレスポンス構造が変わったのに、フロントエンドのinterface定義を直し忘れることです。これを防ぐため、型定義を手書きで二重管理せず、FastAPIが生成するOpenAPIスキーマを唯一の正とする設計にしています。

FastAPI/Python
  └─ OpenAPI schemaを生成
        └─ openapi-typescriptで型生成
              └─ openapi-fetchでReactから呼ぶ

この構成にすると、バックエンドのレスポンスを変更した瞬間、フロントエンドが型エラーとして気づけます。予測結果・評価指標・ジョブ状態を、Python側とTypeScript側で二重にinterface定義しないことが重要なポイントです。

CIでの型ズレ検知も仕込む

この構成の価値は「型が生成される」ことだけでなく、「型のズレを機械的に検知できる」ことにあります。開発記録によれば、チェックスクリプトにOpenAPIスキーマのエクスポート・差分チェックを組み込み、ruff・mypy strict・pytest・フロントエンドの型チェック・Vitest・ビルド・Playwright E2Eまでを一気通貫で実行する運用にしています。これにより「バックエンドは直したがフロントエンドの型生成を忘れた」という状態がCI相当のチェックで検出可能になります。

長時間処理はジョブ化してポーリングする

データ同期・モデル学習・予測のような時間のかかる処理は、同期的なHTTPリクエストで待たせるのではなく、ジョブとして起動しIDを返し、UI側がその状態をポーリングする設計にしています。株価アプリのような「いつのデータで、どこまで処理済みか」が重要な文脈では、単に結果を待たせるより、進行段階（データ同期／モデル学習／本番予測／研究用予測）を画面上で可視化できることが安全性に直結します。

この設計が効く場面

• バックエンドとフロントエンドを別々の担当（人間・AIエージェント問わず）が触る
• APIの形が開発中に頻繁に変わる
• 「型が合っているつもり」のまま本番へ出すリスクを避けたい
• 長時間かかる処理を、進捗が見える形でUIに出したい

Python×TypeScriptのハイブリッド構成自体は目新しくありませんが、「境界をOpenAPIだけに絞り、型ズレをCIで検知する」という運用まで含めて設計しておくと、個人開発でも壊れにくい構成にできます。