Как Axum связан с экосистемами Tokio и Tower?

Tokio как runtime

Все обработчики Axum — это async fn, которые выполняются в Tokio-runtime. Axum не управляет потоками напрямую: он делегирует планирование задач Tokio. Типичный запуск сервера:

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(handler));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Макрос #[tokio::main] создаёт multi-thread runtime (по умолчанию — по числу CPU). tokio::net::TcpListener — это неблокирующий TCP-листенер из Tokio, который Axum использует для приёма соединений.

Архитектурная связь Axum, Tokio и Tower

Axum — это HTTP-фреймворк, построенный поверх двух экосистем: Tokio предоставляет асинхронный runtime и I/O-примитивы, а Tower определяет абстракцию сервиса через трейт Service<Request>. Это не случайная зависимость — сам Router в Axum реализует tower::Service, что позволяет встраивать его в любой Tower-совместимый стек.

Tower как слой middleware

Tower вводит понятие Service и Layer. Каждый middleware в Axum — это tower::Layer, оборачивающий внутренний Service. Пример подключения нескольких слоёв через tower::ServiceBuilder:

use tower::ServiceBuilder;
use tower_http::trace::TraceLayer;
use tower_http::timeout::TimeoutLayer;
use std::time::Duration;

let app = Router::new()
    .route("/api/data", get(data_handler))
    .layer(
        ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())
            .layer(TimeoutLayer::new(Duration::from_secs(30)))
    );

Здесь TraceLayer и TimeoutLayer — реальные типы из крейта tower-http. ServiceBuilder компонует их слева направо: сначала трейсинг, потом таймаут, потом маршрутизатор.

Router как Tower Service

Поскольку Router сам реализует Service<Request>, его можно тестировать напрямую через tower::ServiceExt::oneshot, без поднятия реального TCP-сервера:

use tower::ServiceExt;
use axum::body::Body;
use http::{Request, StatusCode};

#[tokio::test]
async fn test_health() {
    let app = Router::new().route("/health", get(|| async { "ok" }));

    let response = app
        .oneshot(Request::builder().uri("/health").body(Body::empty()).unwrap())
        .await
        .unwrap();

    assert_eq!(response.status(), StatusCode::OK);
}

Подводные камни

• Блокирующие операции (файловый I/O через std, тяжёлые CPU-вычисления) в async-обработчиках блокируют Tokio-поток — нужно использовать tokio::task::spawn_blocking.
• ServiceBuilder применяет слои в обратном порядке относительно их объявления: первый объявленный — самый внешний. Путаница в порядке ломает auth/tracing middleware.
• Middleware, добавленный через .layer() на уровне Router, оборачивает все маршруты; middleware на уровне отдельного маршрута (.route_layer()) применяется только к нему — неочевидное различие.
• Tokio runtime по умолчанию multi-thread; для тестов часто нужен #[tokio::test] с flavor = "current_thread", иначе тесты с shared state могут давать гонки.
• Крейт tower-http — отдельная зависимость, не входит в axum напрямую; забыть добавить его в Cargo.toml — распространённая ошибка.
• При использовании кастомного Tower Service вместо Router нужно явно реализовывать Clone, так как Axum клонирует сервис для каждого соединения.
• axum::serve требует Tokio runtime; попытка запустить его в другом async runtime (например, async-std) приведёт к панике.

• Отвечать определением без production-сценария.
• Не называть runtime boundary, security boundary или failure mode.
• Игнорировать версию API, observability и тестовую проверку.

• Объясняет механизм своими словами и без выдуманных API.
• Называет реальные риски, диагностику и критерий корректности.
• Связывает ответ с текущей документацией и миграционными ограничениями.