[Rust 공식문서 한국어 정리] 77. Rust Axum 가이드

[Rust 공식문서 한국어 정리] 77. Rust Axum 가이드



원문 제목: axum — Web framework for Rust

작성자: Tokio Contributors



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 1. 서론 — 이 문서가 다루는 내용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



이 문서는 Rust의 현대적 웹 프레임워크인 axum을 소개합니다.

타입 안전한 라우팅, 추출기(Extractor), Tower 서비스 통합, 그리고 비동기 핸들러를 다룹니다.

axum의 설계 철학, 상태 관리, 에러 처리, 그리고 미들웨어(레이어) 구성을 중심으로 설명합니다.

hyper와 tokio 위에 구축되었으며, Rust의 타입 시스템을 최대한 활용하여 컴파일 타임에 많은 오류를 방지합니다.

Rust로 백엔드 API를 개발하려는 개발자에게 가장 추천되는 프레임워크입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔑 2. 핵심 개념 4가지

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



① Router: 타입 안전하게 경로와 메서드를 매핑하는 라우팅 엔진입니다.

② Extractor: 요청의 일부를 타입으로 추출하는 트레이트로, Path, Query, Json 등이 있습니다.

③ State: Router와 핸들러 간에 공유 상태를 주입하는 메커니즘입니다.

④ Layer: Tower 미들웨어를 적용하여 요청/응답을 가로채 가공합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 3. 주요 내용 상세

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



axum은 tokio와 hyper 위에 구축된 웹 프레임워크입니다.

Router::new().route("/", get(handler))로 간단하게 라우팅을 정의합니다.

경로 파라미터는 Path 추출기로 자동 파싱되며, 타입 불일치 시 400 에러를 자동 반환합니다.



Extractor는 핸들러의 인자로 선언하여 사용합니다.
fn handler(Path(id): Path, Query(params): Query

, Json(body): Json)

각 Extractor는 실패 시 자체적인 에러 응답을 생성하며, 순차적으로 적용됩니다.



State는 Router::with_state(state)로 공유합니다.

fn handler(State(pool): State)로 데이터베이스 연결 풀을 주입받습니다.

State는 Clone이 필요하며, Arc로 감싸는 것이 일반적입니다.



Layer는 Tower의 Service 레이어를 axum에 적용합니다.

.layer(TraceLayer::new_for_http())로 요청 로깅을,

.layer(CorsLayer::permissive())로 CORS를 처리합니다.



에러 처리는 IntoResponse 트레이트로 통일합니다.

Result를 반환하면, AppError가 IntoResponse를 구현하면 자동 변환됩니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🛠 4. 실전 활용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



axum으로 RESTful API 서버를 구축하고, Extractor/State로 타입 안전한 엔드포인트를 설계합니다.

Tower 미들웨어로 인증, 로깅, rate limiting을 공통 처리합니다.

SQLx나 SeaORM과 연동하여 비동기 데이터베이스 액세스를 수행합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 5. 정리

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



axum은 Rust의 타입 시스템과 Tower 생태계를 활용한 현대적 웹 프레임워크입니다.

Extractor와 IntoResponse로 타입 안전한 API를 구축하고, Layer로 재사용 가능한 미들웨어를 구성합니다.

Tokio 기반의 비동기 성능과 Rust의 안전성을 동시에 누릴 수 있는 최고의 선택지입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 출처 링크

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



원문: https://docs.rs/axum/latest/axum/

axum Examples: https://github.com/tokio-rs/axum/tree/main/examples



#Rust #Axum #WebFramework #Tower #Async #API #Backend #번역