CR-FASTAPI-001: FastAPI Skeleton Introduction - 完了レポート

実装日時

2025年12月3日

概要

目的

今後の移行先となる FastAPI アプリケーションの最小スケルトンを作成し、以下の基盤を整える：

  • /api/v1/health エンドポイント
  • ルータ分割の土台
  • テスト基盤

ゴール

  • .cursorrules に定義された FastAPI / Pydantic / /api/v1 のルールに従った実装
  • 既存の Flask アプリに影響を与えない独立した実装
  • Pydantic + 明示的レスポンスモデルのパターン確立

原則

  • 既存の Flask アプリケーション設定には触れない
  • 新規ファイル追加と最小限の import のみ
  • 動作確認は pytest ベースのテストで行う

実装ステップ

Step 1: FastAPI アプリ本体の作成・更新

ファイル: src/nexuscore/api/fastapi_app.py

変更内容:

  • docs_url="/api/docs" と openapi_url="/api/openapi.json" を追加
  • 将来のルータ追加用のプレースホルダコメントを追加
  • ローカル実行用コマンド例のコメントを追加

変更理由:

  • OpenAPI ドキュメントへのアクセスパスを明確化
  • 将来の拡張性を考慮したコメント追加
  • 開発者向けの実行方法を明示

Step 2: Health ルータの更新

ファイル: src/nexuscore/api/routes/health.py

変更内容:

  • timestamp フィールドを含むように HealthCheckResponse の生成を更新
  • datetime.now() を使用してタイムスタンプを生成

変更理由:

  • CR-FASTAPI-001 の要件（timestamp フィールド）を満たすため
  • レスポンスに時刻情報を含めることで、API の稼働状況をより詳細に把握可能に

Step 3: Schemas モジュールの更新

ファイル: src/nexuscore/api/schemas/health.py

変更内容:

  • status フィールドを Literal["ok"] に変更（型安全性の向上）
  • version フィールドを必須フィールドに変更（str | None = None → str）
  • timestamp: datetime フィールドを追加

変更理由:

  • Pydantic の型安全性を最大限に活用
  • レスポンス形式を明確に定義
  • OpenAPI スキーマに正確に反映されるように

Step 4: テストファイルの作成

ファイル: tests/api/test_fastapi_health.py

実装内容:

  • FastAPI TestClient を使用したテスト実装
  • 3つのテストケースを実装：
    1. test_health_check_status_code: ステータスコード 200 の検証
    2. test_health_check_response_format: レスポンス形式の検証（status, version, timestamp）
    3. test_health_check_openapi_definition: OpenAPI スキーマ定義の確認

実装理由:

  • CR-FASTAPI-001 の要件を満たすため
  • エンドポイントの動作を保証するため
  • 将来の変更に対する回帰テストとして機能

変更ファイル一覧

新規作成ファイル

  • tests/api/test_fastapi_health.py - FastAPI Health エンドポイントのテスト

変更ファイル

  • src/nexuscore/api/fastapi_app.py - FastAPI アプリ本体（docs_url, openapi_url 追加、コメント追加）
  • src/nexuscore/api/routes/health.py - Health ルータ（timestamp 追加）
  • src/nexuscore/api/schemas/health.py - Health スキーマ（型定義の強化、timestamp 追加）

動作確認結果

静的解析結果

  • リンターエラー: なし
  • 型チェック: 問題なし

テスト結果

実行コマンド:

source myenv_linux/bin/activate
export PYTHONPATH=/home/yn441611/NexusCore/src:$PYTHONPATH
python -m pytest tests/api/test_fastapi_health.py -v

結果:

============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-9.0.1
collected 3 items

tests/api/test_fastapi_health.py::test_health_check_status_code PASSED   [ 33%]
tests/api/test_fastapi_health.py::test_health_check_response_format PASSED [ 66%]
tests/api/test_fastapi_health.py::test_health_check_openapi_definition PASSED [100%]

============================== 3 passed in 3.90s ===============================

確認項目:

  • ✅ /api/v1/health エンドポイントが 200 を返す
  • ✅ レスポンスに status: "ok" が含まれる
  • ✅ レスポンスに version フィールドが含まれる（文字列）
  • ✅ レスポンスに timestamp フィールドが含まれる（ISO形式の文字列）
  • ✅ OpenAPI スキーマに /api/v1/health が定義されている
  • ✅ OpenAPI スキーマに GET メソッドが定義されている
  • ✅ OpenAPI スキーマに 200 レスポンスが定義されている

コードレビュー結果

  • ✅ .cursorrules のルールに準拠
  • ✅ Pydantic BaseModel を使用したレスポンスモデル
  • ✅ /api/v1 プレフィックスの使用
  • ✅ 既存の Flask アプリに影響なし

設計上の改善点

アーキテクチャの改善

  1. ルータ分割の基盤確立
    • src/nexuscore/api/routes/ ディレクトリ構造を確立
    • ドメインごとのルータ分割パターンを確立
  2. スキーマ分離
    • src/nexuscore/api/schemas/ ディレクトリ構造を確立
    • レスポンスモデルを独立したモジュールとして管理
  3. 型安全性の向上
    • Literal["ok"] を使用した型安全性の向上
    • Pydantic の型システムを最大限に活用

将来の拡張性への配慮

  1. プレースホルダコメント
    • 将来追加予定のルータ（auth, admin, projects, runs）をコメントで明示
    • 開発者が次のステップを理解しやすい構造
  2. テスト基盤の確立
    • FastAPI TestClient を使用したテストパターンを確立
    • 他のエンドポイントでも同様のパターンを適用可能

コード品質の向上

  1. 明確な型定義
    • Pydantic BaseModel を使用した明示的なレスポンスモデル
    • OpenAPI スキーマへの自動反映
  2. ドキュメント化
    • docstring によるエンドポイントの説明
    • コメントによる実行方法の明示

既知の制約・注意事項

既存コードとの互換性

  • ✅ 既存の Flask アプリケーション（src/nexuscore/api/server.py）には影響なし
  • ✅ 既存の Flask アプリと共存可能な設計

制限事項やトレードオフ

  1. インポート時間
    • FastAPI アプリのインポートに時間がかかる場合がある（依存関係の読み込み）
    • テスト実行時は PYTHONPATH の設定が必要
  2. 実行環境
    • WSL Ubuntu 環境での動作確認済み
    • myenv_linux 仮想環境での動作確認済み

移行時の注意点

  • FastAPI アプリは既存の Flask アプリとは別ポートで実行可能
  • 将来的に Flask から FastAPI への完全移行を検討する際は、段階的な移行を推奨

運用視点の補足

ポート設計

  • Flask アプリ: ポート 5000（既存の Web UI）
  • FastAPI アプリ: ポート 8000（新規 API）
  • 両方を同時に起動可能（別ポートのため）

起動方法（公式）

ローカル開発環境（WSL Ubuntu）:

# 仮想環境を有効化
source myenv_linux/bin/activate

# PYTHONPATH を設定して FastAPI アプリを起動
export PYTHONPATH=/home/yn441611/NexusCore/src:$PYTHONPATH
uvicorn nexuscore.api.fastapi_app:app --reload --host 127.0.0.1 --port 8000

アクセス先:

  • FastAPI アプリ: http://127.0.0.1:8000
  • API ドキュメント: http://127.0.0.1:8000/api/docs
  • OpenAPI スキーマ: http://127.0.0.1:8000/api/openapi.json
  • Health エンドポイント: http://127.0.0.1:8000/api/v1/health

.cursorrules との対応関係

CR-FASTAPI-001 で確立された実装パターンは、.cursorrules のルールに完全に準拠しています：

ディレクトリ構造規則:

  • FastAPI ルートは必ず src/nexuscore/api/routes/ 配下に作成
  • レスポンススキーマは src/nexuscore/api/schemas/ 配下の Pydantic BaseModel を使用
  • 認証依存関係は src/nexuscore/api/dependencies/ 配下に配置

API パス規則:

  • Public API は /api/v1/* プレフィックスを使用
  • Internal API は /internal/* または /system/* を使用（将来実装）

レスポンスモデル規則:

  • すべてのエンドポイントで Pydantic BaseModel を使用
  • response_model パラメータで明示的に指定
  • OpenAPI スキーマに自動反映

テスト規則:

  • FastAPI TestClient を使用
  • tests/api/ 配下に配置
  • PYTHONPATH 設定が必要

これらのパターンは、今後の CR-FASTAPI-002 以降でも同様に適用されます。

次のステップ

推奨されるフォローアップアクション

  1. 他のエンドポイントの移行
    • CR-FASTAPI-000 で棚卸しした Public endpoints の移行を優先
    • /api/v1/execute と /api/v1/status/<task_id> の移行（Phase 1）
  2. 認証機能の実装
    • src/nexuscore/api/dependencies/auth.py の活用
    • Bearer Token 認証の実装
  3. 外部統合 API の移行
    • src/nexuscore/webapp/api_external.py のエンドポイントを FastAPI に移行
    • /api/v1/projects, /api/v1/projects/<project_id>/run など
  4. ドキュメント整備
    • OpenAPI スキーマの詳細化
    • エンドポイントごとの説明文追加
  5. CI/CD への統合
    • テストの自動実行
    • コードカバレッジの測定

関連ドキュメント

まとめ

CR-FASTAPI-001 の実装により、FastAPI アプリケーションの基盤が確立されました。/api/v1/health エンドポイントの実装とテストを通じて、今後の移行作業のパターンが確立されました。すべてのテストが成功し、.cursorrules のルールに準拠した実装が完了しています。

This site uses Just the Docs, a documentation theme for Jekyll.