PyCharmでFastAPIを動かし始めたとき、Uvicornの起動設定で毎回ハマっていました。特にデバッグ中に意図せずプロセスが落ちたり、別のPCに環境を移すと動作しなくなったりするのがストレスでした。
結局、古いチュートリアルで紹介されていたスクリプトパス指定が原因だと気づき、現代的なアプローチに切り替える必要性を感じました。
何が起きたか（課題）
FastAPIとUvicornを組み合わせる際、PyCharmの実行構成でUvicornを直接パス指定で実行すると、以下の問題が頻発していました。
- デバッグセッションが不安定になり、ブレークポイントが意図しない場所で動作しない、または全く機能しない。
- 仮想環境の絶対パスに依存するため、CI/CD環境や別メンバーの環境で構成を再現するのが困難（ポータビリティの欠如）。
- 環境構築のたびにUvicornの実行ファイルパスを手動で探す手間が発生する。
どう解決したか（概要）
解決策は、Uvicornの実行方法をスクリプトパス指定から、Pythonの標準機能であるモジュール実行（-m相当）に切り替えることです。
PyCharmの実行構成ダイアログで、実行対象を「Module」に指定し、モジュール名としてuvicornを指定します。そして、引数にmain:app --host 0.0.0.0 --port 8000 --reloadを設定する流れです。
このアプローチは、CLIでpython -m uvicorn main:app ...と実行するのと同じであり、PyCharmが依存関係を適切に解決してくれるため、デバッグの安定性が劇的に向上します。
FastAPIの役割はアプリロジックの定義、Uvicornの役割はASGIサーバーとしての実行基盤提供です。これらをPyCharm上で統合する際、モジュール実行は最も堅牢な方法でした。
前提として、必要なパッケージ（fastapi, uvicorn, pydantic）は仮想環境にインストール済みである必要があります。
例えば、シンプルなmain.pyが存在する場合、PyCharmの実行構成で以下のように設定しました。
- 実行構成（Run Configuration）を開く。
- 新規でPython構成を追加。
- 実行対象（Script path）を "Module" に変更。
- モジュール名に
uvicornを入力。 - パラメータに
main:app --host 0.0.0.0 --port 8000 --reloadを記述。
この設定により、デバッガがプロセスを確実に捕捉し、コード変更時のホットリロードもスムーズに動作するようになりました。
効果（Before/After）
| 項目 | 変更前（スクリプトパス指定） | 変更後（モジュール実行） |
|---|---|---|
| デバッグ安定性 | 頻繁にデバッガがアタッチ失敗する | 常に安定してブレークポイントで停止する |
| 環境再現性 | 仮想環境パス依存で再設定が必要 | 構成ファイル（.idea）に依存せずポータブル |
| 開発効率 | パス調整に時間を浪費 | 設定後はコード修正に集中可能 |
この変更により、開発サイクルのストレスが大幅に減少し、FastAPIの持つインタラクティブドキュメント（Swagger UI: http://127.0.0.1:8000/docs など）を安心して活用できるようになりました。
🚀 詳細な設定とコードはこちら
具体的なWAFのルール設定や、より詳細なログ解析データは元のブログで公開しています。