CR-FASTAPI-001: FastAPI スケルトン作成 - 完了レポート

実装日時

2025-12-02

概要

NexusCore の API を FastAPI ベースに移行するための「ディレクトリ構造」と「最小スケルトンコード」を作成しました。

目的

  • FastAPI ベースの API 実装の土台を作成する
  • 既存の Flask server.py と共存させ、段階的に移行できる構造にする
  • .cursorrules で定義された FastAPI 実装ルールに準拠した構造を確立する

達成内容

  • FastAPI アプリケーションエントリポイントの作成
  • /api/v1/health エンドポイントの実装（認証不要）
  • Pydantic BaseModel を使用したレスポンスモデル定義
  • 認証用 Dependency の雛形作成
  • 将来の拡張を考慮したディレクトリ構造の確立

原則

  • 既存の Flask server.py は変更しない（共存状態を維持）
  • FastAPI のベストプラクティスに従う（APIRouter、Pydantic、型安全性）
  • 認証実装は後続の CR-FASTAPI-003 で行う（現時点では雛形のみ）

実装ステップ

Step 1: FastAPI アプリケーションエントリポイントの作成

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

  • create_app() 関数で FastAPI インスタンスを作成
  • Health check router を /api/v1 prefix でマウント
  • 将来の router 追加を考慮したコメントを追加

主要コード:

def create_app() -> FastAPI:
    app = FastAPI(
        title="NexusCore API",
        version="1.0.0",
        description="NexusCore API - FastAPI implementation",
    )
    app.include_router(health.router, prefix="/api/v1")
    return app

Step 2: Health Check エンドポイントの実装

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

  • APIRouter を使用して /health エンドポイントを定義
  • 認証不要な公開 API として実装
  • HealthCheckResponse を response_model として使用

主要コード:

@router.get("/health", response_model=HealthCheckResponse)
async def health_check() -> HealthCheckResponse:
    return HealthCheckResponse(status="ok", version="1.0.0")

Step 3: レスポンススキーマの定義

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

  • Pydantic BaseModel を使用して HealthCheckResponse を定義
  • status と version フィールドを持つ

主要コード:

class HealthCheckResponse(BaseModel):
    status: str
    version: str | None = None

Step 4: 認証用 Dependency の雛形作成

ファイル: src/nexuscore/api/dependencies/auth.py

  • AuthenticatedUser モデルを定義
  • get_current_user() Dependency の雛形を作成
  • 現時点では未実装のため、常に 401 Unauthorized を返す
  • CR-FASTAPI-003 で実装予定であることを明記

主要コード:

async def get_current_user() -> AuthenticatedUser:
    # TODO: CR-FASTAPI-003 で JWT / API Key 実装に差し替え
    raise HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Authentication not implemented yet",
    )

Step 5: モジュール初期化ファイルの作成

以下の __init__.py ファイルを作成：

  • src/nexuscore/api/routes/__init__.py
  • src/nexuscore/api/schemas/__init__.py
  • src/nexuscore/api/dependencies/__init__.py

各ファイルにはモジュールの説明コメントを追加。

変更ファイル一覧

新規作成ファイル（7ファイル）

  1. src/nexuscore/api/fastapi_app.py - FastAPI アプリケーションエントリポイント
  2. src/nexuscore/api/routes/__init__.py - routes モジュール初期化
  3. src/nexuscore/api/routes/health.py - Health check エンドポイント
  4. src/nexuscore/api/schemas/__init__.py - schemas モジュール初期化
  5. src/nexuscore/api/schemas/health.py - HealthCheckResponse モデル
  6. src/nexuscore/api/dependencies/__init__.py - dependencies モジュール初期化
  7. src/nexuscore/api/dependencies/auth.py - 認証用 Dependency 雛形

変更なしファイル

  • src/nexuscore/api/server.py - 既存の Flask 実装（変更なし、共存状態）

動作確認結果

静的解析結果

  • リンターエラー: なし
  • 型チェック: 未実施（このタスクではテストファイル未作成）

コードレビュー結果

  • .cursorrules の FastAPI 実装ルールに準拠
  • Pydantic BaseModel を使用した型安全な実装
  • APIRouter を使用した適切な構造
  • 認証不要エンドポイントの明示的な扱い

テスト結果

このタスクではテストファイルは作成していません。

理由:

  • CR-FASTAPI-001 は「スケルトン作成」のみを目的とする
  • 後続の CR-FASTAPI-00X で TestClient ベースのテストを追加予定

設計上の改善点

アーキテクチャの改善

  1. 明確な責務分離
    • routes/: エンドポイント定義
    • schemas/: リクエスト/レスポンスモデル
    • dependencies/: 認証などの依存関係
    • 各モジュールの責務が明確
  2. 拡張性の確保
    • 新しい router を追加しやすい構造
    • 認証実装を後から差し替え可能な設計
    • バージョニング（/api/v1/）を考慮した構造
  3. 型安全性の向上
    • Pydantic BaseModel による型定義
    • FastAPI の型推論を活用
    • 暗黙の dict/tuple を排除

将来の拡張性への配慮

  • /api/v1/execute などの主要エンドポイント追加を想定
  • 認証実装（JWT / API Key）の差し替えを考慮
  • Admin 用 router の追加を想定

既知の制約・注意事項

既存コードとの互換性

  • 既存の Flask server.py は変更していないため、既存の API 呼び出しに影響なし
  • FastAPI と Flask は別々のポートで起動する想定（共存状態）

制限事項やトレードオフ

  1. 認証未実装
    • 現時点では get_current_user() は常に 401 を返す
    • 認証が必要なエンドポイントは CR-FASTAPI-003 まで実装不可
  2. テスト未実装
    • このタスクではテストファイルを作成していない
    • 後続タスクで TestClient ベースのテストを追加予定
  3. 既存エンドポイントの未移行
    • Flask の /api/v1/execute などはまだ移行していない
    • 段階的な移行を想定

移行時の注意点

  • FastAPI アプリケーションを起動するには、別途エントリポイント（例: uvicorn src.nexuscore.api.fastapi_app:app）が必要
  • 既存の Flask アプリケーションとは別プロセスで起動する想定

次のステップ

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

  1. CR-FASTAPI-000: API 棚卸し
    • 既存の Flask エンドポイントを棚卸し
    • 移行優先順位を決定
  2. CR-FASTAPI-002: Health Check テスト追加
    • TestClient を使用した /api/v1/health のテスト
    • FastAPI アプリケーションの起動確認
  3. CR-FASTAPI-003: 認証実装
    • JWT または API Key による認証実装
    • get_current_user() の実装
  4. CR-FASTAPI-004: Execute エンドポイント移行
    • Flask の /api/v1/execute を FastAPI に移行
    • 既存機能との互換性確認
  5. CR-FASTAPI-005: その他エンドポイント移行
    • 残りの Flask エンドポイントを段階的に移行
    • Flask の完全な廃止

関連ファイル

  • .cursorrules - FastAPI 実装ルール定義
  • src/nexuscore/api/server.py - 既存の Flask 実装（参考用）
  • docs/completion_reports/ - 他の CR 完了レポート

備考

このタスクは「FastAPI 移行の第一歩」として、最小限のスケルトンコードを作成しました。 既存の Flask 実装を壊すことなく、新しい FastAPI ベースの実装を並行して構築できる状態になっています。

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