| name | custom-middleware |
| description | Axum Tower 커스텀 미들웨어 작성 패턴 - from_fn, from_fn_with_state, 요청/응답 가로채기, 실전 예시 |
Axum 커스텀 미들웨어 작성 패턴
소스: https://docs.rs/axum/0.8.1/axum/middleware/index.html | https://docs.rs/axum/0.8.1/axum/middleware/fn.from_fn.html | https://docs.rs/axum/0.8.1/axum/middleware/fn.from_fn_with_state.html
검증일: 2026-06-20
주의: axum 0.8.x 기준. 0.6 이하에서는 Next<B> 제네릭 파라미터가 필요했으나, 0.7부터 Next는 제네릭 없이 사용한다.
(DISPUTED 수정: 변경 기점이 0.8이 아닌 0.7임. axum 0.7 공식 발표 및 Discussion #2488에서 확인)
주의: 미들웨어 함수의 Request 타입은 반드시 axum::extract::Request를 사용해야 한다. axum::http::Request는 제네릭(Request<T>)이므로 그대로 쓰면 컴파일 에러가 발생한다.
tower-http vs 커스텀 미들웨어 선택 기준
| 상황 | 선택 |
|---|
| CORS, 압축, 트레이싱, 타임아웃 등 범용 기능 | tower-http 기성 미들웨어 |
| 비즈니스 로직이 포함된 인증/인가 | 커스텀 미들웨어 (from_fn) |
| 앱 State 접근이 필요한 미들웨어 | from_fn_with_state |
| 복잡한 상태 머신, 커넥션 풀링 등 | Tower Service 트레이트 직접 구현 |
대부분의 경우 from_fn으로 충분하다. Service 트레이트 직접 구현은 거의 필요하지 않다.
middleware::from_fn (가장 간단)
async fn을 미들웨어로 변환한다. 함수 시그니처: Request와 Next를 받고 impl IntoResponse를 반환.
use axum::{
extract::Request,
middleware::{self, Next},
response::Response,
Router,
routing::get,
};
async fn my_middleware(
request: Request,
next: Next,
) -> Response {
let response = next.run(request).await;
response
}
let app = Router::new()
.route("/", get(handler))
.layer(middleware::from_fn(my_middleware));
Next 호출 규칙
next.run(request)은 반드시 한 번만 호출한다.- 호출하지 않으면 요청이 핸들러에 도달하지 않는다 (요청 차단 패턴).
Next는 Clone이 아니므로 복수 호출은 컴파일 에러가 된다.
from_fn_with_state (State 접근)
미들웨어 함수에서 앱 State에 접근해야 할 때 사용한다.
use axum::{
extract::{Request, State},
http::StatusCode,
middleware::Next,
response::Response,
};
#[derive(Clone)]
struct AppState {
api_keys: Vec<String>,
}
async fn api_key_middleware(
State(state): State<AppState>,
request: Request,
next: Next,
) -> Result<Response, StatusCode> {
let key = request
.headers()
.get("x-api-key")
.and_then(|v| v.to_str().ok());
match key {
Some(k) if state.api_keys.contains(&k.to_string()) => {
Ok(next.run(request).await)
}
_ => Err(StatusCode::UNAUTHORIZED),
}
}
let state = AppState {
api_keys: vec!["secret-key-1".into()],
};
let app = Router::new()
.route("/api/data", get(data_handler))
.route_layer(middleware::from_fn_with_state(
state.clone(),
api_key_middleware,
))
.(state);
함수 시그니처 순서
State 추출자는 반드시 Request, Next보다 앞에 와야 한다.
async fn mw(
State(state): State<AppState>,
request: Request,
next: Next,
) -> Response { ... }
State 외에 다른 추출자도 Request 앞에 배치할 수 있다.
async fn mw(
State(state): State<AppState>,
headers: HeaderMap,
request: Request,
next: Next,
) -> Response { ... }
요청 가로채기 패턴
이 섹션의 예시들은 아래 공통 import를 전제한다.
use axum::{
extract::Request,
http::StatusCode,
middleware::Next,
response::Response,
};
요청 헤더 읽기
async fn log_request(
request: Request,
next: Next,
) -> Response {
let method = request.method().clone();
let uri = request.uri().clone();
let user_agent = request
.headers()
.get("user-agent")
.and_then(|v| v.to_str().ok())
.unwrap_or("unknown")
.to_string();
tracing::info!(%method, %uri, %user_agent, "incoming request");
next.run(request).await
}
요청 본문 읽기 후 재구성
본문을 읽으면 소비되므로, 읽은 후 새 Request로 재구성해야 한다.
use axum::body::Body;
use axum::extract::Request;
use http_body_util::BodyExt;
async fn log_body(
request: Request,
next: Next,
) -> Result<Response, StatusCode> {
let (parts, body) = request.into_parts();
let bytes = body
.collect()
.await
.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?
.to_bytes();
tracing::info!(body = %String::from_utf8_lossy(&bytes), "request body");
let request = Request::from_parts(parts, Body::from(bytes));
Ok(next.run(request).await)
}
주의: 요청 본문을 메모리에 전부 로드하므로 대용량 업로드에는 부적합하다. RequestBodyLimitLayer와 함께 사용을 권장한다.
요청 차단 (Early Return)
next.run()을 호출하지 않으면 요청이 핸들러에 도달하지 않는다.
async fn reject_if_missing_header(
request: Request,
next: Next,
) -> Result<Response, StatusCode> {
if request.headers().get("x-required-header").is_none() {
return Err(StatusCode::BAD_REQUEST);
}
Ok(next.run(request).await)
}
응답 가로채기 패턴
이 섹션의 예시들도 axum::extract::Request, middleware::Next, response::Response import를 전제한다.
응답 헤더 추가
async fn add_response_header(
request: Request,
next: Next,
) -> Response {
let mut response = next.run(request).await;
response.headers_mut().insert(
"x-request-id",
uuid::Uuid::new_v4().to_string().parse().unwrap(),
);
response
}
응답 상태 코드 기반 로깅
async fn log_response(
request: Request,
next: Next,
) -> Response {
let method = request.method().clone();
let uri = request.uri().clone();
let start = std::time::Instant::now();
let response = next.run(request).await;
let latency = start.elapsed();
let status = response.status();
if status.is_server_error() {
tracing::error!(%method, %uri, %status, ?latency, "server error");
} else {
tracing::info!(%method, %uri, %status, ?latency, "response");
}
response
}
실전 예시: 요청 로깅 미들웨어
요청/응답 양쪽을 모두 로깅하는 통합 미들웨어.
use axum::{
extract::Request,
http::StatusCode,
middleware::Next,
response::Response,
};
use std::time::Instant;
async fn request_logging_middleware(
request: Request,
next: Next,
) -> Response {
let method = request.method().clone();
let uri = request.uri().clone();
let start = Instant::now();
tracing::info!(%method, %uri, "-> request");
let response = next.run(request).await;
let latency = start.elapsed();
let status = response.status();
tracing::info!(%method, %uri, %status, latency_ms = %latency.as_millis(), "<- response");
response
}
적용:
let app = Router::new()
.route("/api/users", get(list_users))
.layer(middleware::from_fn(request_logging_middleware));
실전 예시: API 키 검증 미들웨어
DB나 설정에서 API 키를 검증하는 패턴.
use axum::{
extract::{Request, State},
http::StatusCode,
middleware::Next,
response::{IntoResponse, Response},
Json,
};
use serde_json::json;
#[derive(Clone)]
struct AppState {
valid_api_keys: Vec<String>,
}
async fn validate_api_key(
State(state): State<AppState>,
request: Request,
next: Next,
) -> Result<Response, Response> {
let api_key = request
.headers()
.get("x-api-key")
.and_then(|v| v.to_str().ok());
match api_key {
Some(key) if state.valid_api_keys.contains(&key.to_string()) => {
Ok(next.run(request).await)
}
Some(_) => Err((
StatusCode::FORBIDDEN,
Json(json!({"error": "Invalid API key"})),
).into_response()),
None => Err((
StatusCode::UNAUTHORIZED,
Json(json!({"error": "Missing x-api-key header"})),
).into_response()),
}
}
적용:
let state = AppState {
valid_api_keys: vec!["key-abc-123".into(), "key-def-456".into()],
};
let app = Router::new()
.route("/api/data", get(data_handler))
.route_layer(middleware::from_fn_with_state(
state.clone(),
validate_api_key,
))
.route("/health", get(health_handler))
.with_state(state);
route_layer를 사용하면 그 위에 선언된 라우트에만 미들웨어가 적용된다. /health는 미들웨어를 통과하지 않는다.
미들웨어에 Request Extensions 전달
미들웨어에서 추출한 데이터를 핸들러에 전달할 때 request.extensions_mut()를 사용한다.
use axum::{
extract::Request,
http::StatusCode,
middleware::Next,
response::Response,
};
#[derive(Clone)]
struct CurrentUser {
id: u64,
name: String,
}
async fn auth_middleware(
mut request: Request,
next: Next,
) -> Result<Response, StatusCode> {
let token = request
.headers()
.get("authorization")
.and_then(|v| v.to_str().ok())
.ok_or(StatusCode::UNAUTHORIZED)?;
let user = verify_token(token)
.await
.map_err(|_| StatusCode::UNAUTHORIZED)?;
request.extensions_mut().insert(user);
Ok(next.run(request).await)
}
use axum::Extension;
async fn protected_handler(
Extension(user): Extension<CurrentUser>,
) -> String {
format!("Hello, {}", user.name)
}
layer() vs route_layer() 적용 범위
let app = Router::new()
.route("/protected", get(protected_handler))
.route("/public", get(public_handler))
.route_layer(middleware::from_fn(auth_mw))
.route("/health", get(health_handler));
| 메서드 | 적용 범위 | 매칭 안 된 요청 |
|---|
.layer() | 모든 요청 (fallback 포함) | 미들웨어 통과 |
.route_layer() | 매칭된 라우트만 | 미들웨어 통과하지 않음 |
인증 미들웨어는 .route_layer()를 사용해야 404 응답이 인증 에러로 바뀌는 문제를 방지할 수 있다.
미들웨어 적용 순서
.layer() 호출 순서와 실행 순서는 역순이다.
let app = Router::new()
.route("/", get(handler))
.layer(middleware::from_fn(mw_a))
.layer(middleware::from_fn(mw_b));
직관적 순서를 원하면 tower::ServiceBuilder를 사용한다:
use tower::ServiceBuilder;
let app = Router::new()
.route("/", get(handler))
.layer(
ServiceBuilder::new()
.layer(middleware::from_fn(mw_a))
.layer(middleware::from_fn(mw_b)),
);
