6.10. FastAPI

CMD ["fastapi", "run", "app/main.py", "--port", "8000"]

 ⚡️ Starting FastAPI in production mode
 🐍 Using import string: app.main:app
 🌐 Server started at http://0.0.0.0:8000
    Documentation at http://0.0.0.0:8000/docs
  Logs:
INFO:     Started server process [1]
{"ts": "…", "level": "info", "logger": "app", "message": "старт приложения"}

docker logs имя 2>&1 | python3 -c '
import json, sys
lines = [l for l in sys.stdin if l.strip()]
bad = sum(1 for l in lines if not l.lstrip().startswith("{"))
print(f"строк: {len(lines)}, не JSON: {bad}")'

CMD ["fastapi", "run", "app/main.py", "--port", "8000", "--workers", "4"]

from contextlib import asynccontextmanager

from fastapi import FastAPI


@asynccontextmanager
async def lifespan(app: FastAPI):
    # startup
    app.state.pool = await create_pool()
    yield
    # shutdown — вызывается при SIGTERM
    await app.state.pool.close()


app = FastAPI(lifespan=lifespan)

with TestClient(app) as client:      # lifespan выполняется
    ...

CMD ["fastapi", "run", "app/main.py", "--proxy-headers", "--port", "8000"]

cd resources/examples/fastapi-basic
docker build -q -t fastapi-basic . > /dev/null && echo "образ собран"
docker run -d --name api -p 8000:8000 fastapi-basic > /dev/null
sleep 6
curl -s localhost:8000/ | python3 -m json.tool

образ собран
{
    "pid": 1,
    "service": "fastapi-basic"
}

docker exec api ps -o pid,args

PID   COMMAND
    1 /opt/venv/bin/python /opt/venv/bin/fastapi run app/main.py --port 8000
   14 ps -o pid,args

mkdir -p /tmp/fapi/app && cd /tmp/fapi

cat > app/main.py <<'PY'
import os

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"pid": os.getpid()}
PY

cat > requirements.txt <<'EOF'
fastapi[standard]==0.141.1
EOF

cat > Dockerfile.cli <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["fastapi", "run", "app/main.py", "--port", "8000"]
EOF

cat > Dockerfile.uvicorn <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
EOF

for v in cli uvicorn; do
    docker build -q -f "Dockerfile.$v" -t "fapi:$v" . > /dev/null
    docker run -d --name "f-$v" -p "80$([ "$v" = cli ] && echo 41 || echo 42):8000" "fapi:$v" > /dev/null
done
sleep 6

for v in cli uvicorn; do
    port=$([ "$v" = cli ] && echo 8041 || echo 8042)
    printf '%-8s HTTP %s   PID приложения: %s\n' "$v" \
        "$(curl -s -o /dev/null -w '%{http_code}' localhost:$port/)" \
        "$(curl -s localhost:$port/ | python3 -c 'import json,sys; print(json.load(sys.stdin)["pid"])')"
done

cli      HTTP 200   PID приложения: 1
uvicorn  HTTP 200   PID приложения: 1

docker logs f-cli 2>&1 | head -6

FastAPI   Starting production server 🚀
 
             Searching for package file structure from directories with
             __init__.py files
             Importing from /app
 
    module   🐍 app/main.py

docker rm -f f-cli f-uvicorn > /dev/null

cat > requirements-gunicorn.txt <<'EOF'
fastapi[standard]==0.141.1
gunicorn==26.0.0
EOF

cat > Dockerfile.gunicorn <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements-gunicorn.txt .
RUN pip install --no-cache-dir -r requirements-gunicorn.txt
COPY app/ ./app/
CMD ["gunicorn", "app.main:app", "-k", "uvicorn.workers.UvicornWorker", \
     "--bind", "0.0.0.0:8000", "--workers", "2"]
EOF

docker build -q -f Dockerfile.gunicorn -t fapi:gunicorn . > /dev/null
docker run -d --name f-gun -p 8043:8000 fapi:gunicorn > /dev/null
sleep 6

echo "=== работает, но: ==="
curl -s -o /dev/null -w '  HTTP %{http_code}\n' localhost:8043/
printf '  процессов: %s\n' "$(docker exec f-gun sh -c 'for f in /proc/[0-9]*/cmdline; do tr "\0" " " < "$f"; echo; done | grep -c "[g]unicorn"')"

echo
echo "=== размер образов ==="
docker images --format '  {{.Repository}}:{{.Tag}}  {{.Size}}' | grep -E 'fapi:(cli|gunicorn)'

docker rm -f f-gun > /dev/null

=== работает, но: ===
  HTTP 200
  процессов: 3
=== размер образов ===
  fapi:gunicorn  268MB
  fapi:cli       255MB

cat > app/lifecycle.py <<'PY'
"""Демонстрация lifespan: создание и закрытие ресурсов."""
import asyncio
import os
from contextlib import asynccontextmanager

from fastapi import FastAPI


class FakePool:
    """Имитация пула соединений."""

    def __init__(self) -> None:
        self.closed = False

    async def close(self) -> None:
        print("[pool] закрываю соединения...", flush=True)
        await asyncio.sleep(0.5)
        self.closed = True
        print("[pool] соединения закрыты", flush=True)


_ready = False


@asynccontextmanager
async def lifespan(app: FastAPI):
    global _ready
    print(f"[lifespan] startup, PID={os.getpid()}", flush=True)
    app.state.pool = FakePool()
    _ready = True
    print("[lifespan] готов принимать запросы", flush=True)

    yield

    _ready = False
    print("[lifespan] shutdown начат", flush=True)
    await app.state.pool.close()
    print("[lifespan] shutdown завершён", flush=True)


app = FastAPI(lifespan=lifespan)


@app.get("/")
async def root():
    return {"pid": os.getpid(), "ready": _ready}


@app.get("/slow")
async def slow(seconds: float = 4.0):
    await asyncio.sleep(min(seconds, 20.0))
    return {"slept": seconds}
PY

cat > Dockerfile.lifespan <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["fastapi", "run", "app/lifecycle.py", "--port", "8000"]
EOF

docker build -q -f Dockerfile.lifespan -t fapi:lifespan . > /dev/null
docker run -d --name f-life -p 8044:8000 fapi:lifespan > /dev/null
sleep 6

echo "=== логи старта ==="
docker logs f-life 2>&1 | grep lifespan

echo
echo "=== graceful shutdown с активным запросом ==="
curl -s -m 20 "localhost:8044/slow?seconds=4" > /tmp/life-result.txt &
CURL_PID=$!
sleep 1
s="$(date +%s.%N)"; docker stop --timeout 20 f-life > /dev/null; e="$(date +%s.%N)"
wait $CURL_PID 2>/dev/null
printf '  время stop: %.1f c, код: %s\n' \
    "$(awk -v a="$s" -v b="$e" 'BEGIN{print b-a}')" \
    "$(docker inspect f-life --format '{{.State.ExitCode}}')"
printf '  ответ клиенту: %s\n' "$(cat /tmp/life-result.txt)"
echo "  логи завершения:"
docker logs f-life 2>&1 | grep -E 'shutdown|pool' | sed 's/^/    /'
docker rm f-life > /dev/null; rm -f /tmp/life-result.txt

=== логи старта ===
[lifespan] startup, PID=1
[lifespan] готов принимать запросы

=== graceful shutdown с активным запросом ===
  время stop: 4.1 c, код: 0
  ответ клиенту: {"slept":4.0}
  логи завершения:
    [lifespan] shutdown начат
    [pool] закрываю соединения...
    [pool] соединения закрыты
    [lifespan] shutdown завершён

cat > app/bad_signal.py <<'PY'
"""ОШИБКА: свой обработчик перехватывает сигнал раньше Uvicorn."""
import asyncio
import signal
import sys

from fastapi import FastAPI

app = FastAPI()


def handle(signum, _frame):
    print("[мой обработчик] завершаю немедленно", flush=True)
    sys.exit(0)


signal.signal(signal.SIGTERM, handle)


@app.get("/slow")
async def slow():
    await asyncio.sleep(5)
    return {"done": True}
PY

cat > Dockerfile.badsignal <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
CMD ["fastapi", "run", "app/bad_signal.py", "--port", "8000"]
EOF

docker build -q -f Dockerfile.badsignal -t fapi:badsignal . > /dev/null
docker run -d --name f-bad -p 8045:8000 fapi:badsignal > /dev/null
sleep 6

curl -s -m 15 localhost:8045/slow > /tmp/bad-result.txt 2>&1 &
CURL_PID=$!
sleep 1
docker stop --timeout 20 f-bad > /dev/null
wait $CURL_PID 2>/dev/null
echo -n "ответ клиенту: "
[ -s /tmp/bad-result.txt ] && cat /tmp/bad-result.txt || echo "(пусто — соединение оборвано)"
echo
docker logs f-bad 2>&1 | grep 'мой обработчик'
docker rm f-bad > /dev/null; rm -f /tmp/bad-result.txt

ответ клиенту: (пусто — соединение оборвано)
[мой обработчик] завершаю немедленно

cat > app/probes.py <<'PY'
"""Раздельные пробы: liveness не зависит от базы, readiness зависит."""
import os
import time
from contextlib import asynccontextmanager

from fastapi import FastAPI, Response

_started_at = time.monotonic()
_ready = False

# Имитация недоступности базы через переменную окружения
DB_DOWN_AFTER = float(os.environ.get("DB_DOWN_AFTER", "0"))


def db_available() -> bool:
    if DB_DOWN_AFTER and (time.monotonic() - _started_at) > DB_DOWN_AFTER:
        return False
    return True


@asynccontextmanager
async def lifespan(_app: FastAPI):
    global _ready
    _ready = True
    yield
    _ready = False


app = FastAPI(lifespan=lifespan)


@app.get("/healthz")
async def healthz():
    """Liveness: только процесс. О базе НЕ знает."""
    return {"status": "ok"}


@app.get("/readyz")
async def readyz(response: Response):
    """Readiness: процесс и зависимости."""
    if not _ready:
        response.status_code = 503
        return {"status": "starting"}
    if not db_available():
        response.status_code = 503
        return {"status": "database unavailable"}
    return {"status": "ready"}


@app.get("/data")
async def data(response: Response):
    """Запрос, которому нужна база."""
    if not db_available():
        response.status_code = 503
        return {"error": "database unavailable"}
    return {"items": [1, 2, 3]}


@app.get("/ping")
async def ping():
    """Запрос, которому база не нужна — работает всегда."""
    return {"pong": True}
PY

cat > Dockerfile.probes <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
HEALTHCHECK --interval=5s --timeout=3s --start-period=15s --start-interval=2s --retries=3 \
  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz',timeout=2).status==200 else 1)"
CMD ["fastapi", "run", "app/probes.py", "--port", "8000"]
EOF

docker build -q -f Dockerfile.probes -t fapi:probes . > /dev/null
docker run -d --name f-probes -p 8046:8000 -e DB_DOWN_AFTER=8 fapi:probes > /dev/null
sleep 20

echo "=== база недоступна (прошло больше 8 секунд) ==="
printf '  /healthz  (liveness):  HTTP %s\n' \
    "$(curl -s -o /dev/null -w '%{http_code}' localhost:8046/healthz)"
printf '  /readyz   (readiness): HTTP %s\n' \
    "$(curl -s -o /dev/null -w '%{http_code}' localhost:8046/readyz)"
printf '  /data     (нужна база): HTTP %s\n' \
    "$(curl -s -o /dev/null -w '%{http_code}' localhost:8046/data)"
printf '  /ping     (база не нужна): HTTP %s\n' \
    "$(curl -s -o /dev/null -w '%{http_code}' localhost:8046/ping)"
echo
printf '  статус healthcheck: %s\n' "$(docker inspect f-probes --format '{{.State.Health.Status}}')"
printf '  перезапусков: %s\n' "$(docker inspect f-probes --format '{{.RestartCount}}')"
docker rm -f f-probes > /dev/null

=== база недоступна (прошло больше 8 секунд) ===
  /healthz  (liveness):  HTTP 200
  /readyz   (readiness): HTTP 503
  /data     (нужна база): HTTP 503
  /ping     (база не нужна): HTTP 200

  статус healthcheck: healthy
  перезапусков: 0

cat > Dockerfile.workers <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ ./app/
ARG WORKERS=1
ENV WORKERS=${WORKERS}
CMD ["sh", "-c", "exec fastapi run app/main.py --port 8000 --workers ${WORKERS}"]
EOF

docker build -q -f Dockerfile.workers -t fapi:workers . > /dev/null

for n in 1 3; do
    docker run -d --name "f-w$n" -e WORKERS="$n" -p "805$n:8000" fapi:workers > /dev/null
    sleep 7
    printf 'WORKERS=%s → процессов: %s, PID ответов: ' "$n" \
        "$(docker exec "f-w$n" sh -c 'ps -o pid= | wc -l')"
    for _ in 1 2 3 4; do
        curl -s "localhost:805$n/" | python3 -c 'import json,sys; print(json.load(sys.stdin)["pid"], end=" ")'
    done
    echo
    docker rm -f "f-w$n" > /dev/null
done

WORKERS=1 → процессов: 2, PID ответов: 1 1 1 1 
WORKERS=3 → процессов: 5, PID ответов: 8 9 10 8 

cd resources/examples/fastapi-basic
sed -n '1,30p' app/settings.py

"""Конфигурация через переменные окружения с валидацией при старте."""
from __future__ import annotations

import os
from dataclasses import dataclass


@dataclass(frozen=True)
class Settings:
    """Приложение падает при старте, если конфигурация некорректна."""

    app_name: str = "fastapi-basic"
    log_level: str = "INFO"
    shutdown_delay: float = 0.0

    @classmethod
    def from_env(cls) -> Settings:
        raw_delay = os.environ.get("SHUTDOWN_DELAY", "0")
        try:
            delay = float(raw_delay)
        except ValueError as exc:
            raise ValueError(f"SHUTDOWN_DELAY должен быть числом, получено: {raw_delay!r}") from exc

docker build -q -t fastapi-basic . > /dev/null
echo "=== корректная конфигурация ==="
docker run -d --name cfg-ok -p 8060:8000 fastapi-basic > /dev/null
sleep 6
curl -s -o /dev/null -w '  HTTP %{http_code}\n' localhost:8060/
docker rm -f cfg-ok > /dev/null

echo "=== некорректная конфигурация ==="
docker run --rm -e SHUTDOWN_DELAY=не-число fastapi-basic 2>&1 | tail -3

=== корректная конфигурация ===
  HTTP 200
=== некорректная конфигурация ===
ValueError: SHUTDOWN_DELAY должен быть числом, получено: 'не-число'

cd resources/examples/fastapi-basic
sed -n '1,20p' tests/test_api.py

"""Тесты API через TestClient."""
import pytest
from fastapi.testclient import TestClient

from app.main import app


@pytest.fixture
def client():
    # Контекстный менеджер запускает lifespan: без него readiness останется False
    with TestClient(app) as c:
        yield c

docker build -q --target test -t fastapi-basic:test . > /dev/null && echo "тесты прошли"

mkdir -p /tmp/fapi-test && cd /tmp/fapi-test
cat > demo_test.py <<'PY'
"""Разница между TestClient с контекстным менеджером и без."""
from contextlib import asynccontextmanager

from fastapi import FastAPI
from fastapi.testclient import TestClient

_ready = False


@asynccontextmanager
async def lifespan(_app: FastAPI):
    global _ready
    _ready = True
    yield
    _ready = False


app = FastAPI(lifespan=lifespan)


@app.get("/readyz")
async def readyz():
    return {"ready": _ready}


# БЕЗ контекстного менеджера: lifespan не выполняется
client_no_ctx = TestClient(app)
print("без with:", client_no_ctx.get("/readyz").json())

# С контекстным менеджером: lifespan выполняется
with TestClient(app) as client:
    print("с with: ", client.get("/readyz").json())
PY

docker run --rm -v "$PWD/demo_test.py:/t.py:ro" \
    -e PYTHONUNBUFFERED=1 \
    python:3.13-slim sh -c \
    'pip install -q "fastapi[standard]==0.141.1" 2>/dev/null && python /t.py'

без with: {'ready': False}
с with:  {'ready': True}

cd /tmp
docker rm -f api 2>/dev/null || true
docker rmi -f $(docker images -q --filter 'reference=fapi:*') fastapi-basic fastapi-basic:test 2>/dev/null || true
rm -rf /tmp/fapi /tmp/fapi-test

cd resources/examples/fastapi-basic
docker build -q -t fb . > /dev/null
docker run -d --name fbt -p 8080:8000 fb > /dev/null
sleep 8
curl -s -o /dev/null -w 'healthz: HTTP %{http_code}\n' localhost:8080/healthz
# ps в slim-образе нет — читаем /proc внутри container'а
docker exec fbt cat /proc/1/cmdline | tr '\0' ' ' | cut -c1-40; echo
time docker stop fbt
docker inspect fbt --format 'код: {{.State.ExitCode}}'
docker rm -f fbt > /dev/null; docker rmi -f fb > /dev/null

healthz: HTTP 200
python -m uvicorn app.main:app --host 0.

код: 0