FastAPIの初期実装は非常に快適です。しかし運用フェーズに入ると、次のような症状が出てきます。

• 一覧APIのレスポンスが急に遅くなる
• 同時接続が増えるとp95が跳ねる
• CPUは余っているのにタイムアウトが増える
• DB接続数が上限に張り付く

こうした問題の多くは「Pythonが遅い」のではなく、SQLAlchemyの使い方とDBアクセス設計 に起因します。

本記事では、FastAPI + SQLAlchemy + PostgreSQL構成を前提に、実際の改善手順を計測ベースで整理します。

1. 最初に測るべき指標

最適化は、体感ではなく数値で進めます。最低限、以下を可視化します。

• APIのp50/p95/p99レイテンシ
• エンドポイント別SQL発行回数
• 1リクエストあたりのDB滞在時間
• connection pool待ち時間
• slow query件数（200ms以上など）

OpenTelemetryやNew Relicを使っているなら、アプリspanとDB spanを必ず紐付けてください。これだけでボトルネック特定速度が上がります。

2. N+1問題を最優先で潰す

最も頻出するのがN+1です。例えばユーザー一覧でプロフィールを参照すると、ユーザー数分の追加クエリが発行されます。

2.1 悪い例

1
2
3
4
5
6
7
8

users = session.query(User).limit(100).all()
result = []
for u in users:
    result.append({
        "id": u.id,
        "name": u.name,
        "profile": u.profile.bio,
    })

2.2 改善例（joinedload/selectinload）

1
2
3
4
5
6
7
8

from sqlalchemy.orm import selectinload

users = (
    session.query(User)
    .options(selectinload(User.profile))
    .limit(100)
    .all()
)

joinedload と selectinload はデータ量で使い分けます。

• 1対1/少量: joinedload
• 1対多/件数多め: selectinload

闇雲に joinedload を増やすと行爆発が起きるため、EXPLAINで確認しながら適用します。

3. SQLAlchemy 2.xスタイルへ揃える

旧query APIと新APIが混在すると可読性と最適化精度が落ちます。2.xスタイルへ統一しましょう。

1
2
3
4
5
6
7
8
9

from sqlalchemy import select

stmt = (
    select(Order)
    .where(Order.status == "paid")
    .order_by(Order.created_at.desc())
    .limit(50)
)
orders = session.execute(stmt).scalars().all()

この形式は、EXPLAIN の追跡や再利用がしやすく、レビュー品質も上がります。

4. 必要な列だけ取る（過剰フェッチの削減）

ORMは便利ですが、何も考えずモデル全体を取ると不要データまで転送されます。特にJSONカラムやTEXTが重い場合、ここが効きます。

1
2

stmt = select(User.id, User.name, User.email).where(User.active.is_(True))
rows = session.execute(stmt).all()

一覧APIはDTO用の軽量SELECTを使い、詳細APIでのみ重いカラムを取得する設計が安定します。

5. 接続プール設定を環境に合わせる

pool_size を適当に増やすだけでは逆効果です。PostgreSQL側上限とアプリ台数を合わせて設計します。

1
2
3
4
5
6
7
8

engine = create_engine(
    DB_URL,
    pool_size=20,
    max_overflow=10,
    pool_timeout=10,
    pool_recycle=1800,
    pool_pre_ping=True,
)

設計の目安:

• DB max_connections = 300
• API Pod = 6
• 1 Podあたりpool_size 20

この時点で理論最大120接続。バッチや管理接続も見込み、余白を残すのが安全です。

6. トランザクション境界を短くする

長いトランザクションはロック競合とスループット低下を招きます。

悪い例:

1. DB更新
2. 外部API呼び出し
3. メール送信
4. commit

この順は危険です。外部I/Oをトランザクション外へ逃がします。

改善例:

1. DB更新 + commit
2. 外部通知は非同期ジョブで実行

これだけで同時処理性能が目に見えて改善します。

7. インデックス設計をAPI単位で見直す

「インデックスはある」だけでは不足です。実際のWHERE + ORDER BYに合っているかが重要です。

例: 注文履歴API

1
2
3
4
5

SELECT id, total_amount, created_at
FROM orders
WHERE user_id = $1 AND status = 'paid'
ORDER BY created_at DESC
LIMIT 50;

この場合、次の複合indexが有効です。

1
2

CREATE INDEX CONCURRENTLY idx_orders_user_status_created_at_desc
ON orders (user_id, status, created_at DESC);

単独indexを乱立させるより、アクセスパターンに合わせた複合indexを厳選した方が効きます。

8. キャッシュ導入は「遅い理由の解決後」に行う

キャッシュは万能ではありません。N+1やスロークエリを放置したまま載せると、整合性事故の温床になります。

導入順序:

1. SQL最適化
2. 接続プール調整
3. 必要なエンドポイントに限定してRedis cache

キャッシュキーは resource:id:version 形式にし、更新時の無効化戦略を先に定義してください。

9. 負荷試験シナリオ（k6例）

最適化の成果は負荷試験で確認します。最低3シナリオが必要です。

• steady: 通常トラフィック
• burst: 短時間ピーク
• soak: 長時間連続実行（リーク検知）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '2m', target: 50 },
    { duration: '5m', target: 50 },
    { duration: '1m', target: 200 },
    { duration: '2m', target: 0 },
  ],
};

export default function () {
  const res = http.get('https://api.example.com/orders?limit=50');
  check(res, { 'status 200': (r) => r.status === 200 });
  sleep(1);
}

改善前後で p95, SQL回数, DB CPU を比較し、定量で判断します。

10. 本番での改善手順テンプレート

1. ボトルネックendpointの特定
2. SQLログとEXPLAIN ANALYZE取得
3. N+1解消
4. 必要列取得へ変更
5. インデックス追加（CONCURRENTLY）
6. pool設定調整
7. 負荷試験再実施
8. 段階リリース（10%→50%→100%）

この手順を運用チーム全体でテンプレ化すると、パフォーマンス問題への対応速度が上がります。

まとめ

FastAPI + SQLAlchemyの性能改善は、派手なテクニックより 計測→原因分離→小さく改善 の積み重ねが効きます。

• N+1解消
• 過剰フェッチ削減
• 接続プール最適化
• インデックスの再設計
• 負荷試験で再検証

この5点を回せば、遅いAPIは高確率で改善できます。まずは「1リクエストあたりのSQL発行数」を可視化するところから始めるのが最短です。

付録: 改善施策の優先順位（最短で効く順）

時間が限られる現場では、まず「SQL発行回数削減 → インデックス最適化 → connection pool調整」の順で着手すると効果が出やすいです。特に、N+1解消だけでp95が半減するケースは珍しくありません。改善後は必ず同一負荷条件で再計測し、数字で効果を残しておくと、次の改善投資判断が通りやすくなります。

FastAPIでAPIを作ると、重い処理はすぐに非同期ジョブへ逃がしたくなります。画像変換、レポート生成、外部API連携、メール配信など、Celeryは非常に便利です。ですが、本番で問題になるのは「動くかどうか」ではなく、失敗したときに壊れないか です。

• 同じジョブが二重実行される
• 一時障害で永遠にリトライしてキューが詰まる
• ワーカー再起動で中途半端な状態が残る
• 完了通知が先に飛んで実データがない

本記事では FastAPI + Celery + Redis 構成を前提に、再実行安全性（idempotency）と運用信頼性を上げる実装手順をまとめます。

1. まず守るべき設計原則

非同期基盤の事故は、ほぼ次の4原則で防げます。

1. At-least-once前提（同一タスク再実行は必ず起こる）
2. 副作用は冪等化（何回実行されても結果が壊れない）
3. 状態遷移を明示（PENDING/RUNNING/SUCCEEDED/FAILED）
4. 失敗を可観測化（リトライ回数・死活・滞留時間を計測）

この原則を外すと、障害時に「何が完了して何が未完了か」が追えなくなります。

2. 参照アーキテクチャ

• API: FastAPI
• Queue Broker: Redis
• Worker: Celery
• Result Store: PostgreSQL（業務状態）
• Monitoring: Flower + Prometheus + Sentry

ポイントは、業務上重要な状態はRedis結果バックエンドに依存しない ことです。Redisは一時的に使い、真実の状態はRDBに持たせます。

3. 実装の土台: タスク受付API

3.1 受け付け時に idempotency_key を必須化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from sqlalchemy import select

app = FastAPI()

class JobRequest(BaseModel):
    idempotency_key: str
    report_type: str
    user_id: str

@app.post("/reports")
def create_report(req: JobRequest):
    existing = find_job_by_key(req.idempotency_key)
    if existing:
        return {"job_id": existing.id, "status": existing.status}

    job = create_job_record(
        idempotency_key=req.idempotency_key,
        status="PENDING",
        report_type=req.report_type,
        user_id=req.user_id,
    )
    generate_report.delay(job.id)
    return {"job_id": job.id, "status": "PENDING"}

これでクライアント再送が来てもジョブ多重作成を防げます。

3.2 DB制約で最終防衛線を張る

idempotency_key に UNIQUE 制約を入れ、アプリバグ時も二重作成を防ぎます。

1

ALTER TABLE async_jobs ADD CONSTRAINT uq_async_jobs_idempotency UNIQUE (idempotency_key);

4. Celeryタスクの実践設定

4.1 推奨設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

from celery import Celery

celery_app = Celery(
    "worker",
    broker="redis://redis:6379/0",
    backend="redis://redis:6379/1",
)

celery_app.conf.update(
    task_acks_late=True,
    task_reject_on_worker_lost=True,
    worker_prefetch_multiplier=1,
    task_time_limit=900,
    task_soft_time_limit=840,
    task_default_retry_delay=30,
    task_routes={"tasks.generate_report": {"queue": "reports"}},
)

• acks_late=True: 実行完了後にACK。途中クラッシュ時は再配信
• prefetch_multiplier=1: 取り込み過多を防ぎ、偏りを減らす
• time limit: ハング抑止

4.2 リトライは指数バックオフ + 上限

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@celery_app.task(
    bind=True,
    autoretry_for=(TemporaryExternalError,),
    retry_backoff=True,
    retry_backoff_max=300,
    retry_jitter=True,
    max_retries=7,
)
def generate_report(self, job_id: str):
    ...

無制限リトライは障害増幅装置です。必ず上限を設定します。

5. 冪等タスクの実装パターン

5.1 状態遷移をトランザクションで管理

1
2
3
4
5
6
7
8

def start_job(job_id: str):
    with session.begin():
        job = session.get(Job, job_id, with_for_update=True)
        if job.status in ("RUNNING", "SUCCEEDED"):
            return False
        job.status = "RUNNING"
        job.started_at = utcnow()
    return True

FOR UPDATE を使い、同時実行で状態が競合しないようにします。

5.2 副作用前に“実行済みチェック”

外部API呼び出しやファイル生成前に、既に成果物が存在するか確認します。

• 既に同名レポートが生成済みならスキップ
• 外部通知は送信履歴テーブルで重複防止
• 決済や課金は必ず業務ID単位で一意化

5.3 完了処理はCompare-and-Setで確定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

def complete_job(job_id: str, result_url: str):
    updated = session.execute(
        """
        UPDATE async_jobs
        SET status='SUCCEEDED', result_url=:url, finished_at=now()
        WHERE id=:id AND status='RUNNING'
        """,
        {"id": job_id, "url": result_url},
    )
    return updated.rowcount == 1

これで二重完了更新を防げます。

6. 失敗時の設計（DLQ相当の運用）

Celeryに“標準DLQ”はありませんが、実運用では次の形で代替できます。

• リトライ上限超過時に FAILED_PERMANENT へ遷移
• 失敗理由とスタックトレースをDB保存
• 再実行API（手動リカバリ）を提供
• 重大失敗はSentry + Pagerで通知

この構成で「黙って死ぬジョブ」をなくせます。

7. 監視設計（最低限）

メトリクス

• キュー滞留数（queue length）
• oldest message age
• タスク成功率 / 失敗率
• p95 実行時間
• リトライ回数分布

アラート例

• 滞留数が通常の3倍を10分継続
• 失敗率 > 5% が15分継続
• oldest message age > 20分
• worker heartbeat消失

「CPU高い」より「キューが古い」がユーザー影響に直結します。

8. デプロイ時の落とし穴

8.1 ローリング更新での重複実行

• acks_late + graceful shutdown を設定
• TERM 後にタスク完了待ち時間を確保
• 長時間ジョブは分割し、中断耐性を持たせる

8.2 スキーマ変更の順序

非同期基盤では、ワーカーとAPIが異なるバージョンで同居します。

安全な順序:

1. 先に後方互換なDB変更を適用
2. ワーカーを先に更新
3. APIを更新
4. 非互換削除は次リリースで

これを守らないと、古いタスクが新スキーマで失敗します。

9. ローカル・ステージングでの検証手順

1. 正常系: ジョブ作成→完了→結果取得
2. 再送系: 同一 idempotency_key で2回POST
3. 障害系: 外部APIタイムアウトを強制しリトライ確認
4. クラッシュ系: 実行中にworker再起動し再配信確認
5. 負荷系: 1000ジョブ投入で滞留時間と失敗率確認

この5ケースを自動テストに入れるだけで、運用品質は大幅に上がります。

10. 本番チェックリスト

• idempotency_key のUNIQUE制約あり
• 冪等な状態遷移実装（RUNNING/SUCCEEDED）
• リトライ上限 + バックオフ設定済み
• 手動再実行導線あり
• 失敗通知（Sentry/Pager）有効
• 滞留監視とアラート運用あり
• デプロイ手順に互換性ルール明記

まとめ

FastAPI + Celeryの本質は、非同期化そのものではなく 失敗しても壊れない設計 にあります。

• At-least-once を前提に設計する
• 冪等性をDB制約と状態遷移で担保する
• リトライと監視を“運用可能”な形で実装する
• デプロイ時のバージョン混在を想定する

ここまで作り込むと、ジョブ基盤は「たまに落ちるブラックボックス」から「予測可能に運用できるインフラ」へ変わります。まずは idempotency_key と状態遷移の明確化から始めるのがおすすめです。

FastAPI は実装が速い反面、認証・認可を最小構成のまま本番に出してしまい、後からセキュリティ事故に発展するケースが少なくありません。特に「JWT を入れたから安全」という誤解は危険です。

本記事では、開発速度を落とさずに本番で耐える認証基盤を作るための設計を、コード例と運用手順込みで解説します。

1. 認証と認可を分離して設計する

最初に押さえるべきは責務分離です。

• 認証（Authentication）: 誰かを確認する
• 認可（Authorization）: 何をしてよいか判定する

この2つを混ぜると、実装も監査も破綻します。FastAPI では dependency を分け、get_current_user と require_permission を独立させるのが基本です。

2. JWT は「短命 + リフレッシュ + 失効管理」で使う

アクセストークンを長寿命にすると、漏えい時の被害が大きくなります。実運用では以下が標準です。

• Access Token: 5〜15分
• Refresh Token: 7〜30日
• Refresh Token は DB 保存し、ローテーション時に旧トークンを失効

sub だけでなく、jti（トークンID）や scope を持たせると管理しやすくなります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

from datetime import datetime, timedelta, timezone
import jwt

ALGORITHM = "HS256"


def create_access_token(user_id: str, scopes: list[str], secret: str) -> str:
    now = datetime.now(timezone.utc)
    payload = {
        "sub": user_id,
        "scope": " ".join(scopes),
        "iat": int(now.timestamp()),
        "exp": int((now + timedelta(minutes=10)).timestamp()),
        "jti": "generated-uuid"
    }
    return jwt.encode(payload, secret, algorithm=ALGORITHM)

3. 鍵管理とローテーション

秘密鍵を .env に固定して数年運用するのは典型的な事故パターンです。最低限、次を実施します。

• KMS/Vault など外部シークレット管理を利用
• kid をヘッダに持たせ、複数鍵を並行運用
• 鍵ローテーション手順を runbook 化

ローテーションの要点:

1. 新鍵を追加（検証側は新旧どちらも受理）
2. 発行側を新鍵へ切替
3. 旧鍵の有効期限を過ぎたら削除

この手順にすると、無停止で切替できます。

4. FastAPI Dependencyで認可を明示化

ロジック中で if user.role == "admin" を乱立させると、抜け漏れが起こります。権限チェックは dependency 化し、ルート定義に明示します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from fastapi import Depends, HTTPException, status


def require_permission(required: str):
    def checker(user=Depends(get_current_user)):
        if required not in user.permissions:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="insufficient permissions"
            )
        return user
    return checker


@router.delete("/projects/{project_id}")
def delete_project(
    project_id: str,
    user=Depends(require_permission("project:delete"))
):
    ...

ルート単位で要件が見えるため、レビュー効率と監査性が上がります。

5. RBAC/ABAC の使い分け

小規模なら RBAC（role-based）で十分ですが、顧客単位データや組織階層があると ABAC（属性ベース）を併用した方が安全です。

• RBAC: admin, editor, viewer
• ABAC: tenant_id, resource_owner_id, department

実務では「ロールで粗く許可し、属性で絞る」が扱いやすいです。

6. マルチテナントで必須の防御

マルチテナント API では、ID 推測よりもテナント境界漏れが主要リスクです。対策は次の通りです。

• すべての DB クエリに tenant_id 条件を必須化
• 管理者 API でも境界を明示的に超える操作だけ許可
• 監査ログに tenant_id, actor_id, resource_id を残す

SQLAlchemy でも repository 層で共通フィルタを強制すると漏れを減らせます。

7. 監査ログを設計段階で入れる

認証系は障害後に「誰が何をしたか」が必要になります。後付けだと間に合いません。最低限、次を記録します。

• ログイン成功/失敗（IP, user-agent, reason）
• 権限エラー（403）
• 重要操作（削除、権限変更、請求情報更新）
• トークン失効・再発行

フォーマットは JSON 構造化に統一し、SIEM や OpenSearch に流せる形にしておくと分析が速いです。

8. レート制限とブルートフォース対策

パスワード認証がある場合、レート制限なしは危険です。slowapi などを使い、ログイン系エンドポイントに制限を入れます。

1
2
3
4
5
6
7
8
9

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@router.post("/auth/login")
@limiter.limit("5/minute")
def login(...):
    ...

さらに次を組み合わせると強化できます。

• 失敗回数に応じた遅延（progressive delay）
• CAPTCHA（必要時のみ）
• 異常IP/ASN の遮断

9. よくある実装ミス

ミスA: 署名検証はしているが aud/iss 未検証

結果:

• 他システム向けトークンを誤受理

対処:

• issuer/audience を厳格検証
• 想定外クレームは拒否

ミスB: refresh token の使い回しを検知しない

結果:

• 漏えい時に長期間乗っ取られる

対処:

• ローテーション時に旧トークン失効
• 再利用検知時はセッション全失効

ミスC: 認可チェックが一部エンドポイントで抜ける

結果:

• 水平権限昇格

対処:

• dependency ベースで強制
• 重要ルートにセキュリティテスト追加

10. テスト戦略（必須）

認証はユニットテストだけでなく、統合テストで権限境界を確認します。

• 有効トークン/期限切れ/改ざんトークン
• role ごとのアクセス可否
• tenant 越境アクセス拒否
• refresh token 再利用検知

pytest では fixture で role 別トークンを用意し、回帰を防ぎます。

11. 障害時 runbook（最低限）

インシデント時に迷わないよう、次を文書化しておきます。

1. 鍵漏えい疑い時の全トークン失効手順
2. 認証基盤障害時のフェイル動作（許可しすぎを防ぐ）
3. 監査ログの検索手順
4. 関係者通知テンプレート

特に「認証サーバーが落ちたとき、API をどうするか」は事前に決めておく必要があります。

12. 導入チェックリスト

• access token は短寿命（<=15分）
• refresh token は DB 管理 + ローテーション
• 鍵ローテーション手順がある
• ルート単位で認可 dependency が明示されている
• tenant 境界を DB レイヤーで強制している
• 監査ログ（認証/認可/重要操作）を構造化保存
• レート制限と異常検知がある
• 権限境界の統合テストがある

FastAPI の認証・認可は、フレームワーク機能だけでは守り切れません。トークン寿命設計、鍵運用、境界強制、監査、テスト、runbookまで含めて初めて、本番で信頼できるセキュリティ基盤になります。

FastAPI は開発速度が高く、PoC から本番まで一気に進めやすいフレームワークです。しかし、早く作れることと安全に運用できることは別問題です。実際の障害は、コードの正しさよりも運用の隙から発生します。

本記事では、FastAPI を本番で安心して運用するためのハードニング手順を、実装可能な形でまとめます。対象は「すでにAPIが動いているが、運用強度を上げたい」チームです。

1. 入口防御：TLS、ヘッダ、レート制限

TLS終端とForwardedヘッダ

ロードバランサ配下で動かす場合、X-Forwarded-For と X-Forwarded-Proto の扱いを明確にします。誤るとクライアントIPが取れず、監査も制限も機能しません。

1
2
3
4
5

from fastapi import FastAPI
from starlette.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(TrustedHostMiddleware, allowed_hosts=["api.example.com", "*.example.com"])

allowed_hosts をワイルドにしすぎると Host Header Injection の温床になります。

セキュリティヘッダ

最低限次を返します。

• Strict-Transport-Security
• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy

APIでも無関係ではありません。管理画面やドキュメントUIを守る意味があります。

レート制限

ブルートフォースと突発負荷に備え、IPまたはAPIキー単位でレート制限を設定します。

• 認証系: 5 req/min
• 通常API: 60 req/min
• 高負荷検索: 20 req/min

Redis バックエンド方式にして、アプリ再起動でカウンタが失われないようにします。

2. 認証・認可の落とし穴を塞ぐ

JWT検証の必須項目

exp だけ見て通す実装は危険です。少なくとも次を検証します。

• iss（発行者）
• aud（想定利用先）
• nbf（有効開始）
• kid に基づく鍵ローテーション

認可は「エンドポイント単位」ではなく「リソース単位」

/users/{id} のアクセス時に、path パラメータの id とトークンの主体を照合しない事故は頻発します。FastAPI の dependency で統一的に実施します。

1
2
3

def authorize_user_resource(current_user, target_user_id: str):
    if not (current_user.is_admin or current_user.user_id == target_user_id):
        raise HTTPException(status_code=403, detail="forbidden")

3. 入出力の安全化：Pydanticだけでは不十分

Pydantic は型安全に強いですが、ビジネス制約は別で実装が必要です。

• 文字列長上限
• 許可文字セット
• SQL/NoSQLインジェクションの危険文字
• HTML/Markdown サニタイズ

特に検索APIやエクスポートAPIは、クエリ文字列が巨大化しやすく DoS の入口になります。max_length を必ず定義してください。

4. 性能ハードニング：ワーカ・DB・タイムアウト

Uvicorn/Gunicorn 構成

CPUコア数に応じて worker を決めます。目安は workers = 2 * core + 1 から開始し、実測で調整。

1

gunicorn app.main:app -k uvicorn.workers.UvicornWorker --workers 5 --bind 0.0.0.0:8000 --timeout 30

DB接続プール

asyncpg や SQLAlchemy async engine のプール上限を設定しないと、ピーク時に接続飽和します。

• min: 5
• max: 30（DB性能と相談）
• pool timeout: 5s

タイムアウト戦略

上流・下流の timeout を揃えないと、雪崩障害が発生します。

• 外部API呼び出し: connect 1s / read 3s
• DBクエリ: statement timeout 2s（重処理は別キュー）
• API全体: 10s で fail fast

5. 例外設計と障害時の挙動

本番障害では「500が出ること」より「500の意味が不明」なことが問題です。エラーレスポンス形式を固定し、trace_id を必ず返します。

1
2
3
4
5
6
7

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "unexpected error",
    "trace_id": "8f3d..."
  }
}

内部例外はそのまま返さず、ログ側に stack trace を記録。ユーザーには安全な文言のみ返却します。

6. 可観測性：ログ・メトリクス・トレース

構造化ログ

JSON ログを標準化し、次を必須項目にします。

• timestamp
• level
• service
• trace_id
• user_id（可能なら）
• endpoint
• latency_ms

メトリクス

最低限:

• RPS
• エラー率（4xx/5xx）
• P50/P95/P99 latency
• DB遅延
• 外部API失敗率

トレース

OpenTelemetry で endpoint → service → DB をつなぐと、障害切り分けが劇的に速くなります。

7. デプロイ戦略：壊さずに出す

推奨は Blue/Green か Canary。FastAPI 単体の問題より、周辺設定差異が事故の原因になります。

リリース前チェックリスト:

1. DB migration の後方互換性
2. 依存ライブラリ脆弱性スキャン
3. load test（代表3API）
4. rollback 手順の実行確認
5. feature flag で段階有効化

8. 運用で効くインシデント訓練

月1回、次の擬似障害を実施すると運用強度が上がります。

• DB遅延 3秒化
• 外部API 30% 失敗
• メモリリーク発生
• JWT鍵ローテーション失敗

重要なのは、復旧時間だけでなく「誰が何を見て判断したか」を記録することです。Runbook の更新まで含めて初めて訓練が完結します。

9. すぐ使える最小ハードニングチェック

• Host ヘッダ制限
• JWT iss/aud/exp/nbf 検証
• 全エンドポイントに認可 dependency
• 外部API timeout/retry/circuit breaker
• JSON 構造化ログ + trace_id
• P95 latency 監視とアラート
• rollback 手順が5分で実行可能

この 7 項目が揃うだけで、障害時の被害規模は大きく下がります。

まとめ

FastAPI は高速開発の武器ですが、本番運用では「早く作る」より「安全に壊れる」設計が重要です。入口防御、認証認可、性能制御、観測性、リリース運用をセットで整備すれば、チームは安心して機能開発に集中できます。

もし何から始めるか迷うなら、まずは trace_id 付きの構造化ログと timeout 統一から着手してください。最小の投資で、運用の見通しが一気に良くなります。

10. セキュアな開発フローを維持するためのCI設定

本番ハードニングはコードだけでなく、CI フローで担保する必要があります。推奨するジョブは次の通りです。

1. 依存脆弱性スキャン（pip-audit / osv-scanner）
2. SAST（bandit など）
3. 型チェック（mypy）
4. 負荷テストのスモーク（k6）
5. OpenAPI 差分チェック（破壊的変更検出）

特に OpenAPI 差分チェックは有効です。意図しないレスポンス変更を早期に検知でき、フロントエンド障害を防げます。

11. バックアップと復旧を設計に含める

API 運用は「壊れない」ではなく「壊れても戻せる」が現実的です。最低限次を決めておきます。

• DB バックアップ頻度（例: 15分ごと増分、日次フル）
• 復旧目標（RTO/RPO）
• 復旧手順の担当と実行順

復旧訓練をしていないバックアップは、存在しないのと同じです。四半期に一度は検証環境でリストア演習を行ってください。

12. 監査対応を見据えたログ保全

B2B API では監査要件が後から増えることが多いです。最初から次を満たす設計にしておくと後で困りません。

• 監査ログとアプリログを分離
• 重要操作（権限変更、削除、課金操作）の証跡保存
• ログ保持期間の明確化（例: 180日）
• 改ざん検知（WORM ストレージや署名）

「誰が、いつ、何をしたか」を追えることは、障害解析だけでなく法務リスク低減にも直結します。

最終まとめ

FastAPI の本番運用は、フレームワーク知識だけでは足りません。セキュリティ、性能、可観測性、復旧性を一体で設計することが重要です。チェックリスト化し、CI と運用手順へ落とし込むことで、安定した開発速度を維持できます。