К содержимому
Войти

Python Road Map

🌍 WSGI, ASGI и серверы приложений

Django, Flask и FastAPI сами не слушают порт. Сокеты, разбор HTTP и процессы берёт на себя сервер приложений: gunicorn, uvicorn, granian. С приложением он говорит через стандартный интерфейс, WSGI или ASGI. Поэтому один и тот же FastAPI запускается под uvicorn, granian или gunicorn. Отсюда два вопроса техсекции: что происходит с запросом до твоего обработчика и почему сервис запускают четырьмя процессами, а не одним

🧠 Как это устроено

WSGI: функция на один запрос

WSGI описан в PEP 333 и обновлён для Python 3 в PEP 3333. Его придумали, чтобы любой фреймворк работал с любым сервером. Приложение здесь просто вызываемый объект с двумя аргументами:

  • environ — словарь с запросом в стиле CGI: REQUEST_METHOD, PATH_INFO, QUERY_STRING, заголовки как HTTP_*, тело в файлоподобном wsgi.input
  • start_response(status, headers) — функция, которой приложение сообщает статус и заголовки ответа

Тело ответа приложение возвращает итерируемым объектом из байтовых строк: списком или генератором

Ключевое свойство WSGI: вызов синхронный и занимает поток, пока не вернёт ответ. Поэтому сервер держит столько одновременных запросов, сколько у него потоков и процессов. WebSocket в эту модель тоже не помещается: соединение живёт минутами, а интерфейс умеет только «получил запрос, вернул ответ»

ASGI: корутина и два канала

ASGI вырос из Django Channels и решает именно эти две проблемы. Приложение — корутина с тремя аргументами:

  • scope — словарь с описанием соединения: type (http, websocket или lifespan), method, path, headers и другие поля
  • receive — корутина, которая отдаёт следующее входящее событие: кусок тела http.request, сообщение из WebSocket, http.disconnect
  • send — корутина, через которую приложение отправляет события: http.response.start со статусом и заголовками, затем один или несколько http.response.body

Запрос и ответ превратились в поток событий, поэтому соединение может жить сколько угодно. WebSocket здесь просто другая последовательность: websocket.connect, обмен websocket.receive и websocket.send, websocket.disconnect. Стриминг ответа — несколько send с more_body=True. А раз приложение корутина, тысячи ожидающих соединений обслуживает один event loop в одном потоке

Третий тип scope, lifespan, сервер присылает один раз на процесс: lifespan.startup до первого запроса и lifespan.shutdown при остановке. На нём держится lifespan в FastAPI, о нём следующая страница

Путь запроса от сокета до обработчика

На примере uvicorn:

  1. Ядро принимает TCP-соединение в очередь listen. Её длину у uvicorn задаёт --backlog, по умолчанию 2048
  2. Event loop воркера (uvloop, если установлен, иначе asyncio) делает accept и начинает читать байты из сокета
  3. Парсер HTTP разбирает байты в метод, путь и заголовки. Это httptools (обёртка над llhttp из Node.js, на C) или h11 на чистом Python. Выбирается флагом --http, по умолчанию auto: httptools, если он есть
  4. Сервер собирает scope и создаёт задачу с вызовом app(scope, receive, send)
  5. Фреймворк внутри app находит маршрут, вызывает middleware и твой обработчик, сериализует результат
  6. Приложение вызывает send, сервер превращает события в байты ответа и пишет их в сокет. Соединение остаётся открытым для следующего запроса, без него uvicorn закроет его через 5 секунд (--timeout-keep-alive)

Пункт 5 — код фреймворка и твой, остальное делает сервер

Какие бывают серверы

СерверЧто этоИнтерфейсы
gunicornменеджер процессов с pre-fork: мастер следит за воркерами, перезапускает упавшиеWSGI; с версии 24 есть свой ASGI-воркер
uvicornASGI-сервер на asyncio/uvloop, умеет запускать несколько воркеров самASGI, WSGI через адаптер
granianсервер на Rust (hyper и tokio), сеть обслуживают потоки Rust, Python вызывается только для приложенияASGI, WSGI, свой RSGI

Классическая связка — gunicorn с uvicorn-воркерами: gunicorn управляет процессами, а внутри каждого работает uvicorn со своим event loop. Запустить её можно тремя способами, и первый устарел:

  • -k uvicorn.workers.UvicornWorker из самого uvicorn. Модуль uvicorn.workers объявлен устаревшим и будет удалён: при импорте он пишет DeprecationWarning и отправляет к пакету uvicorn-worker
  • -k uvicorn_worker.UvicornWorker из отдельного пакета uvicorn-worker, это прямая замена
  • без gunicorn: uvicorn main:app --workers 4. Встроенный менеджер перезапускает упавшие воркеры и убивает зависшие

Ещё в gunicorn 24 появился собственный ASGI-воркер --worker-class asgi, с версии 25.1 он стабильный. Но в проектах и туториалах пока чаще встречается связка с uvicorn

🛠️ На практике

Минимальные приложения без фреймворка

Оба приложения читают тело и отвечают методом, путём и размером тела

Python · Минимальное WSGI-приложение

# wsgi_app.py — запуск: gunicorn wsgi_app:app -w 2
def app(environ, start_response):
    size = int(environ.get("CONTENT_LENGTH") or 0)
    body = environ["wsgi.input"].read(size)
    text = f"{environ['REQUEST_METHOD']} {environ['PATH_INFO']} body={len(body)}B\n".encode()
    start_response("200 OK", [("Content-Type", "text/plain")])
    return [text]

Python · Минимальное ASGI-приложение

# asgi_app.py — запуск: uvicorn asgi_app:app
async def app(scope, receive, send):
    if scope["type"] != "http":
        return  # lifespan и websocket здесь не обрабатываем
    body = b""
    while True:
        message = await receive()  # тело может прийти несколькими кусками
        body += message.get("body", b"")
        if not message.get("more_body"):
            break
    text = f"{scope['method']} {scope['path']} body={len(body)}B\n".encode()
    await send({
        "type": "http.response.start",
        "status": 200,
        "headers": [(b"content-type", b"text/plain")],
    })
    await send({"type": "http.response.body", "body": text})
curl -X POST -d hello localhost:8000/orders
POST /orders body=5B

Так выглядит scope для GET /orders?id=7 под uvicorn. Заголовки и строка запроса остались байтами:

{'http_version': '1.1', 'method': 'GET', 'path': '/orders', 'query_string': b'id=7',
 'headers': [(b'host', b'localhost:8013'), (b'user-agent', b'curl/8.7.1'), (b'accept', b'*/*')],
 'client': ('127.0.0.1', 61248)}

До первого запроса приложение получило {'type': 'lifespan.startup'}. Проверено на Python 3.13, uvicorn 0.54, gunicorn 27, granian 2.8

Процессы, а не потоки: замер

В CPython байткод в каждый момент выполняет один поток процесса, это GIL, он разобран на странице «GIL и free-threading». Для веб-сервера это значит простую вещь: потоки помогают, пока обработчики ждут, и не помогают, пока считают. Четыре одновременных запроса к WSGI-приложению под gunicorn, 8 ядер:

КонфигурацияОбработчик ждёт 0,3 с (time.sleep)Обработчик считает ~0,2 с
-w 11,28 с0,88 с
-w 1 --threads 40,34 с0,88 с
-w 4—0,26 с

На ожидании четыре потока справились за время одного запроса. На расчёте они по очереди брали GIL, и вышло как с одним воркером. Четыре процесса посчитали параллельно: у каждого свой GIL

Реальный обработчик — смесь: разобрать JSON, сходить в базу, собрать ответ. Части «посчитать» хватает, чтобы процесс упёрся в одно ядро. Поэтому в проде сервис запускают несколькими процессами-воркерами, а потоки и корутины внутри процесса закрывают ожидание

Сколько воркеров

Единой формулы нет, есть точка старта и замер под нагрузкой:

  • синхронные WSGI-воркеры: документация gunicorn предлагает начинать с (2 × ядра) + 1, чтобы пока один воркер ждёт базу, другой считал. Там же сказано, что обычно хватает 4–12 воркеров, а лишние снижают пропускную способность
  • async-воркеры uvicorn: один event loop и так держит тысячи ожидающих соединений, поэтому начинают с числа ядер
  • память: каждый воркер загружает приложение целиком. Восемь воркеров по 300 МБ — 2,4 ГБ ещё до первого запроса

Флаги -w у gunicorn и --workers у uvicorn по умолчанию берут значение из WEB_CONCURRENCY, без неё запускается один воркер. Как оно соотносится с лимитом CPU контейнера, разберём на странице про Python в контейнере

Django и Flask под ASGI-сервером

Django умеет оба интерфейса из коробки: в проекте есть wsgi.py и asgi.py. Под ASGI асинхронные view работают в event loop и держат сотни соединений без потоков, становятся возможны long-polling и WebSocket через Channels. Синхронные view и middleware Django запускает в потоке через sync_to_async, каждый переход стоит десятки микросекунд. Поэтому документация Django советует включать ASGI, только если в проекте есть асинхронный код. Границы async ORM разобраны на странице про Django и DRF

Flask — WSGI-фреймворк. Под ASGI-сервер его заворачивают в адаптер, документация Flask рекомендует asgiref.wsgi.WsgiToAsgi. Uvicorn умеет то же через --interface wsgi и берёт пакет a2wsgi, если он установлен. Без него включается встроенная обёртка, а она устарела. Каждый запрос всё равно занимает поток в пуле адаптера, так что ускорения нет: это способ запустить старое приложение на том же сервере, что и новое

Reverse proxy перед uvicorn

В проде между интернетом и uvicorn обычно стоит nginx (или балансировщик облака, Ingress в Kubernetes). Он берёт на себя то, что Python-серверу делать невыгодно:

  • принимает TLS и HTTP/2 от клиентов, а к воркерам ходит по HTTP/1.1 на localhost или через Unix-сокет (uvicorn: --uds /run/app.sock)
  • буферизует медленных клиентов. Телефон на плохом 3G отправляет тело запроса десять секунд, и синхронный воркер gunicorn всё это время занят. Nginx дочитает тело сам и отдаст воркеру целиком
  • отдаёт статику, ограничивает размер тела и частоту запросов, распределяет нагрузку между несколькими инстансами

У прокси есть цена: приложение видит адрес nginx, а не клиента, и http вместо https. Nginx передаёт настоящие значения в X-Forwarded-For и X-Forwarded-Proto. Uvicorn читает их только от доверенных адресов из --forwarded-allow-ips, по умолчанию это 127.0.0.1 и ::1. Nginx в соседнем контейнере приходит с другого адреса, и без него в списке rate limit по IP забанит всех пользователей разом. "*" доверяет всем, его ставят, только если прокси затирает эти заголовки от клиента

⚠️ Где ошибаются

Ставить много потоков на CPU-тяжёлый сервис. --threads 16 в одном воркере выглядит как 16-кратный запас, но на расчётах потоки не ускоряют, это видно в замере выше. Параллелизм по CPU дают процессы

Копировать uvicorn.workers.UvicornWorker из старого туториала. Работает, но модуль устарел и будет удалён. Замена — пакет uvicorn-worker с классом uvicorn_worker.UvicornWorker или встроенный uvicorn --workers

Держать в памяти воркера состояние, общее для всех запросов. Счётчик или кэш словарём в глобальной переменной расходятся между воркерами: у каждого процесса своя копия. На одном воркере в разработке всё сходится, на четырёх в проде нет. Общее состояние держат в Redis или базе

Открыть пул соединений к базе при импорте модуля. С --preload gunicorn импортирует приложение один раз в мастере до fork, и сокеты пула достаются всем воркерам сразу: несколько процессов пишут в одно соединение и могут получить чужой ответ. Uvicorn стартует воркеры через spawn, там каждый процесс импортирует всё заново. Надёжное место для пула одно: событие lifespan startup внутри каждого воркера

🎯 Вопросы с собеседований

Что такое WSGI и ASGI, зачем uvicorn и gunicorn

Это интерфейсы между сервером приложений и фреймворком. В WSGI приложение — синхронная функция app(environ, start_response), которая занимает поток до конца ответа. В ASGI это корутина app(scope, receive, send), запрос и ответ идут событиями, поэтому работают WebSocket и тысячи ожидающих соединений в одном event loop. Сервер берёт на себя сокеты, разбор HTTP и процессы. Gunicorn — менеджер процессов с pre-fork для WSGI. Uvicorn — ASGI-сервер на asyncio. Их часто связывают: gunicorn управляет процессами, внутри каждого работает uvicorn-воркер. Сейчас для этого берут пакет uvicorn-worker или просто uvicorn --workers, старый uvicorn.workers устарел

Почему для параллелизма запускают несколько процессов, а не потоки, и как выбрать число воркеров

Из-за GIL потоки одного процесса не выполняют Python-код параллельно: на ожидании базы они помогают, на разборе JSON упираются в одно ядро. Каждый процесс получает свой интерпретатор и свой GIL, поэтому N процессов используют N ядер. Для синхронных воркеров gunicorn стартовая точка (2 × ядра) + 1. Для async-воркеров начинают с числа ядер, потому что один event loop и так держит много соединений. Дальше число подбирают нагрузочным тестом и смотрят на память: каждый воркер грузит приложение целиком

Можно ли запустить Django или Flask под ASGI-сервером и что это даст

Django — да, у него есть asgi.py. Выигрыш будет, только если есть асинхронные view: они держат много соединений без потоков, появляются long-polling и WebSocket через Channels. Синхронные view под ASGI выполняются в потоке через sync_to_async, это накладные расходы без пользы, поэтому полностью синхронный проект оставляют на WSGI. Flask — WSGI-фреймворк, его заворачивают в адаптер WsgiToAsgi из asgiref или запускают через uvicorn --interface wsgi с установленным a2wsgi. Каждый запрос всё равно занимает поток, ускорения это не даст

Что такое reverse proxy перед uvicorn и зачем он

Это сервер вроде nginx, который принимает запросы клиентов и пересылает их воркерам. Он терминирует TLS, отдаёт статику, режет большие тела и частые запросы, балансирует между инстансами. Главное для Python: он буферизует медленных клиентов, и воркер получает запрос целиком, а не ждёт его десять секунд по 3G. Цена — приложение видит адрес прокси, поэтому nginx передаёт X-Forwarded-For и X-Forwarded-Proto, а в uvicorn адрес прокси добавляют в --forwarded-allow-ips

Чем granian отличается от uvicorn

Granian написан на Rust поверх hyper и tokio: сеть и разбор HTTP идут в потоках Rust, Python вызывается только для приложения. Uvicorn делает это в Python на asyncio или uvloop. В granian из коробки есть HTTP/2, менеджер воркеров с перезапуском и собственный интерфейс RSGI рядом с ASGI и WSGI. Платишь тем, что это не чистый Python: отладка сложнее, часть расширений ASGI не реализована, trio и gevent не поддерживаются. Разница в скорости видна на лёгких эндпоинтах, а когда время уходит на базу, она тонет в ожидании

📚 Что почитать

  • PEP 3333 — спецификация WSGI: environ, start_response и правила для итерируемого ответа
  • ASGI: HTTP & WebSocket — все ключи scope и типы событий, плюс таблица соответствия с WSGI
  • Uvicorn: Deployment — встроенные воркеры, gunicorn через uvicorn-worker, пример конфига nginx и заголовки прокси
  • Django: Asynchronous support — что происходит с sync и async view под WSGI и ASGI и сколько стоит переход между ними