はじめに

VSCodeを使って、FastAPIのデバッグができる方法を調査しました。
本記事では、デバッグ環境構築の方法をご紹介します。

動作イメージ

下記のGifのようにVSCodeのブレークポイントでコードを止めることができます。また、ホバーした変数の値を参照したり、書き換えることができます。

環境設定の概要

環境構築手順の要点は下記の通りです。

対象となるFastAPIプロジェクトのrequirements.txtにdebugpyを追加する
debugpyを起動できるように、docker-compose.ymlを設定する
VSCodeからアクセスできるように、launch.jsonを作成する

フォルダ構造

今回のサンプルのディレクトリ構造は下記のとおりです。

　（VSCodeプロジェクトルート）
  ├ docker-compose.yml
  ├ backend
    ├ app
      ├ Dockerfile
      ├ requirements.txt
      ├ main.py # FastAPI実行ファイル

環境設定の手順

1. requirements.txt に debugpy を追加する

requirements.txt

fastapi
debugpy # 追加

2. debugpyを起動できるように、docker-compose.ymlを設定する

docker-compose.yml

  backend:
    build:
      context: ./backend
      dockerfile: ./Dockerfile
    volumes:
      - ./backend/:/backend
    env_file: ./backend/.env
    working_dir: /backend/app
    command: sh -c "python3 -m debugpy --listen 0.0.0.0:5678 -m uvicorn main:app --reload --proxy-headers --host='0.0.0.0' --port=8000"
    ports:
      - "8000:8000"
      - "5678:5678"
    tty: true
    stdin_open: true

下記のdiffは、通常のdocker-compose.ymlとの差分を表したものです。通常の設定と異なる箇所は、command, portsの指定です。

    env_file: ./backend/.env
    working_dir: /backend/app
-    command: sh -c "uvicorn main:app --reload --proxy-headers --host='0.0.0.0' --port=8000"
+    command: sh -c "python3 -m debugpy --listen 0.0.0.0:5678 -m uvicorn main:app --reload--proxy-headers --host='0.0.0.0' --port=8000"
    ports:
-      - "8080:8000"
+      - "8000:8000"
+      - "5678:5678" # debugpy用のポートを追加
    tty: true

command: python3 -m debugpy --listen 0.0.0.0:5678 -m を先頭につけます
ports: 5678ポートをフォワーディングします

3. VSCodeからアクセスできるように、launch.jsonを作成する

launch.json は、プロジェクト内の.vscode/ディレクトリ配下に作成します。

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "debugpy",
            "request": "attach",
            "name": "Docker (FastAPI)",
            "connect": {
                "host": "localhost",
                "port": 5678  // docker-compose.ymlの ports の定義と同じにします
            },
            // docker-compose.ymlの volumes で定義した構造と同じにするよう設定します
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}/backend",
                    "remoteRoot": "/backend"
                }
            ]
        }
    ]
}

上記のlaunch.jsonファイルの中で要点は下記のとおりです。

host
- localhostとします
port
- ポートフォワーディングしたdebugpyのport番号を指定します
pathMapping
- localRoot: ホスト側の起点ディレクトリです。サンプルコードでは、プロジェクト内の/backendディレクトリを指定しています。
- remoteRoot: コンテナ内の起点ディレクトリです。サンプルコードでは、/backendディレクトリを指定しています。
  これらの設定は、docker-compose.ymlのvolume指定を参考に記述すると良いです。
補足
- launch.jsonの"request"オプションには、connectやlistenなどのオプションがあります。詳細は下記のリンクを御覧ください。
  - Update launch.json handling to support "listen" and "connect" · Issue #10437 · microsoft/vscode-python

使ってみる

ここまでの手順で、VSCodeからdebugpyを利用する準備は終了です。動作確認には以下の手順を実行してください。

docker-compose up を実行し、FastAPIコンテナを起動する
VSCodeを開き、適当な行番号をマークする（赤印をつける）
VSCodeサイドメニューの実行とデバッグをクリックし、上部の▷ Docker (FastAPI)をクリックする
OpenAPIなどからFastAPIにリクエストを飛ばし、指定した行で処理が止まることを確認する

Happy Hacking!

ローカルファイルの変更がDockerコンテナ内に反映されないときは？（mac環境など）

docker-compose.ymlに下記の環境変数を追加すると、FastAPIが強制リロードしてくれます。
※ ただし反映まで3秒程度のラグが生じるようです。

    environment:
      - WATCHFILES_FORCE_POLLING=true

参考記事