Что такое tower::ServiceBuilder и как он используется с Axum?

Базовый пример с Axum

use axum::{Router, routing::get};
use tower::ServiceBuilder;
use tower_http::{
    trace::TraceLayer,
    compression::CompressionLayer,
    timeout::TimeoutLayer,
    cors::CorsLayer,
};
use std::time::Duration;

let middleware_stack = ServiceBuilder::new()
    .layer(TraceLayer::new_for_http())
    .layer(TimeoutLayer::new(Duration::from_secs(30)))
    .layer(CompressionLayer::new())
    .layer(CorsLayer::permissive());

let app = Router::new()
    .route("/", get(handler))
    .layer(middleware_stack);

Порядок слоёв в ServiceBuilder — снаружи внутрь: первый вызванный .layer() обернёт сервис снаружи и выполнится первым при входящем запросе.

Зачем нужен ServiceBuilder

Когда к роутеру применяется несколько .layer() вызовов подряд, каждый оборачивает предыдущий тип в новый дженерик: Timeout<Compression<Trace<Router>>>. При трёх-четырёх слоях ошибки компилятора становятся нечитаемыми. tower::ServiceBuilder решает эту проблему: он накапливает слои через .layer() и возвращает финальный тип через .service(inner) или преобразует накопленные слои в Layer через .into_inner() / .layer().

ServiceBuilder с buffer, concurrency, rate limit

use tower::ServiceBuilder;
use tower::limit::{ConcurrencyLimitLayer, RateLimitLayer};
use tower::buffer::BufferLayer;
use std::time::Duration;

let middleware_stack = ServiceBuilder::new()
    .layer(BufferLayer::new(1024))          // очередь до 1024 запросов
    .layer(ConcurrencyLimitLayer::new(64))  // не более 64 одновременно
    .layer(RateLimitLayer::new(           // не более 1000 в секунду
        1000,
        Duration::from_secs(1),
    ));

let app = axum::Router::new()
    .route("/api", axum::routing::get(handler))
    .layer(middleware_stack);

Использование service() вместо layer()

Если нужно обернуть конкретный сервис (например, для тестирования), вместо .into_inner() используйте .service(inner):

use tower::ServiceBuilder;
use tower_http::trace::TraceLayer;
use axum::Router;

let router = Router::new().route("/", axum::routing::get(handler));

// Оборачиваем конкретный сервис напрямую
let service = ServiceBuilder::new()
    .layer(TraceLayer::new_for_http())
    .service(router);

// Можно передать в axum::serve
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
axum::serve(listener, service.into_make_service()).await.unwrap();

Отладка типов через check_service

При сложных цепочках можно принудительно указать ожидаемый тип, чтобы компилятор выдал точное сообщение об ошибке:

use tower::ServiceBuilder;
use tower_http::trace::TraceLayer;
use axum::body::Body;
use axum::http::{Request, Response};

fn assert_service<S>(_: &S)
where
    S: tower::Service<Request<Body>, Response = Response<Body>>,
{}

let svc = ServiceBuilder::new()
    .layer(TraceLayer::new_for_http())
    .service(axum::Router::new());

assert_service(&svc); // ошибка здесь, если тип неверный

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

• Порядок слоёв в ServiceBuilder противоположен порядку отдельных Router::layer() вызовов: в ServiceBuilder первый слой — внешний, в Router::layer().layer() последний — внешний.
• BufferLayer и ConcurrencyLimitLayer требуют, чтобы сервис реализовывал Clone или был обёрнут в Arc; иначе tower::buffer::worker не сможет держать копию сервиса.
• RateLimitLayer из Tower держит состояние внутри; при использовании нескольких реплик (несколько TcpListener-воркеров) каждый получит свой счётчик — реального глобального rate limit не будет без внешнего Redis/etc.
• Версии tower и tower-http должны совпадать с зависимостями Axum; конфликт даёт ошибку «the trait Layer is not implemented for...» без явного указания на версию.
• ServiceBuilder::service() потребляет builder; после него нельзя добавить ещё слои. Если нужны дополнительные слои — добавьте их через Router::layer() после.
• При использовании .into_inner() возвращается анонимный тип-стек; сохранять его в переменную с явным типом невозможно без impl Layer или box.
• Логирование через TraceLayer работает только если tracing_subscriber инициализирован до запуска сервера; часто забывают вызвать tracing_subscriber::fmt::init() в main.
• При тестировании с tower::ServiceExt::oneshot() убедитесь, что сервис реализует Clone — oneshot потребляет экземпляр, и если сервис не клонируется, тест можно запустить только один раз.

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

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