Claude Code × Python FastAPI 本番開発2026 — 設計・型安全コード生成・pytest自動化・Dockerデプロイまで

# プロジェクトディレクトリ作成
mkdir fastapi-app && cd fastapi-app
# CLAUDE.md を先に配置（上記内容で）
 
# Claude Code を起動
claude

# app/core/config.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from functools import lru_cache
 
class Settings(BaseSettings):
    """アプリケーション設定。環境変数から自動読み込み。"""
 
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
    )
 
    # アプリ設定
    app_name: str = "FastAPI Production API"
    app_version: str = "1.0.0"
    debug: bool = False
 
    # DB 設定
    database_url: str = "postgresql+asyncpg://user:password@localhost/dbname"
    database_pool_size: int = 10
    database_max_overflow: int = 20
 
    # JWT 設定
    secret_key: str  # 必須: 本番では 256bit ランダム文字列
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30
 
    # CORS 設定
    allowed_origins: list[str] = ["http://localhost:3000"]
 
@lru_cache
def get_settings() -> Settings:
    """シングルトンで設定を返す（DI用）。"""
    return Settings()

# app/models/user.py
import uuid
from datetime import datetime
from sqlalchemy import String, Boolean, func
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
class Base(DeclarativeBase):
    pass
 
class User(Base):
    __tablename__ = "users"
 
    id: Mapped[uuid.UUID] = mapped_column(
        primary_key=True, default=uuid.uuid4, index=True
    )
    email: Mapped[str] = mapped_column(
        String(255), unique=True, index=True, nullable=False
    )
    hashed_password: Mapped[str] = mapped_column(nullable=False)
    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False)
    created_at: Mapped[datetime] = mapped_column(
        default=func.now(), server_default=func.now()
    )
    updated_at: Mapped[datetime] = mapped_column(
        default=func.now(), onupdate=func.now(), server_default=func.now()
    )

# app/api/v1/users.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy import select
 
from app.core.database import get_db
from app.core.security import get_current_user, get_password_hash
from app.models.user import User
from app.schemas.user import UserCreate, UserRead, UserUpdate
 
router = APIRouter(prefix="/users", tags=["users"])
 
@router.post("/", response_model=UserRead, status_code=status.HTTP_201_CREATED)
async def create_user(
    user_in: UserCreate,
    db: AsyncSession = Depends(get_db),
) -> UserRead:
    """新規ユーザーを登録する。メールアドレス重複時は 400 を返す。"""
    # 重複チェック
    result = await db.execute(select(User).where(User.email == user_in.email))
    existing = result.scalar_one_or_none()
    if existing:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="このメールアドレスは既に登録されています。",
        )
    # パスワードハッシュ化
    hashed_pw = get_password_hash(user_in.password)
    db_user = User(email=user_in.email, hashed_password=hashed_pw)
    db.add(db_user)
    await db.commit()
    await db.refresh(db_user)
    return db_user
 
@router.get("/me", response_model=UserRead)
async def read_current_user(
    current_user: User = Depends(get_current_user),
) -> UserRead:
    """現在の認証済みユーザー情報を返す。"""
    return current_user

# tests/conftest.py
import pytest
import pytest_asyncio
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.pool import StaticPool
 
from app.main import app
from app.core.database import Base, get_db
from app.core.security import get_password_hash, create_access_token
from app.models.user import User
 
# テスト用インメモリ SQLite エンジン
TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
 
test_engine = create_async_engine(
    TEST_DATABASE_URL,
    connect_args={"check_same_thread": False},
    poolclass=StaticPool,  # in-memory 共有のため必須
)
 
@pytest_asyncio.fixture(autouse=True)
async def setup_db():
    """各テスト前にテーブルを作成し、テスト後に削除する。"""
    async with test_engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    yield
    async with test_engine.begin() as conn:
        await conn.run_sync(Base.metadata.drop_all)
 
@pytest_asyncio.fixture
async def db_session():
    """テスト用 DB セッションを提供する。"""
    async with AsyncSession(test_engine) as session:
        yield session
 
@pytest_asyncio.fixture
async def client(db_session: AsyncSession):
    """DB を差し替えた FastAPI テストクライアントを提供する。"""
    app.dependency_overrides[get_db] = lambda: db_session
    async with AsyncClient(
        transport=ASGITransport(app=app), base_url="http://test"
    ) as ac:
        yield ac
    app.dependency_overrides.clear()
 
@pytest_asyncio.fixture
async def normal_user(db_session: AsyncSession) -> User:
    """テスト用通常ユーザーを作成する。"""
    user = User(
        email="test@example.com",
        hashed_password=get_password_hash("testpassword123"),
    )
    db_session.add(user)
    await db_session.commit()
    await db_session.refresh(user)
    return user
 
@pytest_asyncio.fixture
def user_token(normal_user: User) -> str:
    """テスト用アクセストークンを生成する。"""
    return create_access_token(subject=str(normal_user.id))

# tests/integration/test_users.py
import pytest
from httpx import AsyncClient
 
@pytest.mark.asyncio
async def test_create_user_success(client: AsyncClient):
    """正常なユーザー登録のテスト。"""
    response = await client.post(
        "/api/v1/users/",
        json={"email": "new@example.com", "password": "securepass123"},
    )
    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "new@example.com"
    assert "hashed_password" not in data  # パスワードが非公開であることを確認
 
@pytest.mark.asyncio
async def test_create_user_duplicate_email(client: AsyncClient, normal_user):
    """重複メールアドレスで 400 が返ることを確認。"""
    response = await client.post(
        "/api/v1/users/",
        json={"email": normal_user.email, "password": "anypassword"},
    )
    assert response.status_code == 400
    assert "既に登録" in response.json()["detail"]
 
@pytest.mark.asyncio
async def test_read_current_user(client: AsyncClient, user_token: str):
    """認証済みユーザーが /me エンドポイントにアクセスできることを確認。"""
    response = await client.get(
        "/api/v1/users/me",
        headers={"Authorization": f"Bearer {user_token}"},
    )
    assert response.status_code == 200
    assert response.json()["email"] == "test@example.com"

# カバレッジ付きテスト実行
pytest --cov=app --cov-report=html tests/
# htmlcov/index.html でカバレッジを視覚的に確認
 
# 期待する出力例:
# ==================== 12 passed in 1.83s ====================
# TOTAL: 84%

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd /path/to/fastapi-app && python -m pytest tests/ -x -q --tb=short 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

# ── ステージ1: 依存関係ビルド ──
FROM python:3.12-slim AS builder
 
WORKDIR /build
 
# ビルド依存のみインストール
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc libpq-dev \
    && rm -rf /var/lib/apt/lists/*
 
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt
 
# ── ステージ2: 本番ランタイム ──
FROM python:3.12-slim AS runtime
 
# セキュリティ: 非rootユーザー作成
RUN useradd --create-home --shell /bin/bash appuser
WORKDIR /home/appuser/app
 
# ビルドステージの site-packages のみコピー
COPY --from=builder /root/.local /home/appuser/.local
 
# アプリコードをコピー
COPY --chown=appuser:appuser app/ ./app/
 
USER appuser
 
# PATH に .local/bin を追加
ENV PATH=/home/appuser/.local/bin:$PATH
 
# ヘルスチェック
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD python -c "import httpx; httpx.get('http://localhost:8000/health')" || exit 1
 
EXPOSE 8000
 
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

# docker-compose.yml
version: "3.9"
 
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:password@db:5432/appdb
      - SECRET_KEY=dev-secret-key-change-in-production
      - DEBUG=true
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./app:/home/appuser/app/app  # ホットリロード用
 
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
 
volumes:
  postgres_data:

# 開発環境の起動
docker compose up -d
 
# API の動作確認
curl http://localhost:8000/docs
# → Swagger UI が表示されれば成功
 
# ログ確認
docker compose logs -f api

name: CI/CD Pipeline
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.12"]
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: "pip"
 
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-asyncio pytest-cov httpx aiosqlite
 
      - name: Run linting (ruff)
        run: ruff check app/ tests/
 
      - name: Run type checking (mypy)
        run: mypy app/
 
      - name: Run tests with coverage
        run: |
          pytest tests/ --cov=app --cov-report=xml --cov-fail-under=80
 
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
 
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Deploy to Fly.io
        uses: superfly/flyctl-actions/setup-flyctl@master
 
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

# FastAPI コードレビュー専門エージェント
 
あなたは FastAPI のセキュリティ・パフォーマンス専門のコードレビュアーです。
 
## レビュー観点（優先度順）
1. **セキュリティ**: SQLインジェクション・認証バイパス・権限昇格のリスク
2. **N+1問題**: SELECT文のループ実行（selectinload/joinedload の提案）
3. **型安全性**: Pydantic バリデーションの抜け漏れ
4. **非同期安全性**: sync ブロッキング処理の混入（requests → httpx 等）
5. **エラーハンドリング**: 適切な HTTPException の使用
 
## レビュー出力形式
各問題について:
- 場所: ファイル名:行番号
- 重大度: CRITICAL / WARNING / INFO
- 問題: 何が問題か
- 修正案: 具体的なコード例付き

# Fly.io の初期設定（初回のみ）
fly launch --name my-fastapi-app --region nrt
 
# 環境変数の設定
fly secrets set SECRET_KEY="$(openssl rand -hex 32)"
fly secrets set DATABASE_URL="postgresql+asyncpg://..."
 
# デプロイ実行
fly deploy
 
# デプロイ確認
fly status
fly logs