#actix-web 통합 가이드

버전: 0.33.0 최종 업데이트: 2026-03-15 적용 대상: ranvier-core, ranvier-macros, ranvier-runtime 카테고리: 통합


actix-web 핸들러와 extractor에서 Ranvier transition을 사용하세요.

#개요

actix-web은 Rust를 위한 강력하고 실용적이며 매우 빠른 웹 프레임워크입니다. actix 핸들러에 Ranvier transition을 통합하여 두 프레임워크의 장점을 모두 활용할 수 있습니다:

  • actix-web: Extractor, 미들웨어, 견고한 HTTP 처리
  • Ranvier: Schematic 시각화, Bus 전파, 조합 가능한 로직

#통합 패턴

권장 접근 방식은 actix 핸들러 내에서 Ranvier transition을 호출하는 것입니다:

#actix 핸들러에서 Ranvier Transition 호출

use actix_web::{web, HttpRequest, HttpResponse};
use ranvier_core::{Bus, Outcome};
use ranvier_macros::transition;
use ranvier_runtime::Axon;

// Ranvier transition 정의
#[transition]
async fn process_order(
    order: Order,
    _res: &(),
    bus: &mut Bus
) -> Outcome<OrderResult, AppError> {
    // 비즈니스 로직
    Outcome::Next(OrderResult { id: order.id, status: "processed" })
}

// actix 핸들러
async fn create_order(
    req: HttpRequest,
    order: web::Json<Order>,
    pipeline: web::Data<Axon<Order, OrderResult, AppError, ()>>
) -> HttpResponse {
    let mut bus = Bus::new();

    // 선택사항: 요청에서 인증 정보를 추출하여 Bus에 저장
    if let Some(auth) = req.extensions().get::<AuthContext>() {
        bus.insert(auth.clone());
    }

    // Ranvier 파이프라인 실행
    match pipeline.execute(order.into_inner(), &(), &mut bus).await {
        Outcome::Next(result) => HttpResponse::Ok().json(result),
        Outcome::Fault(err) => HttpResponse::BadRequest().json(err),
        _ => HttpResponse::InternalServerError().finish(),
    }
}

// actix 앱 설정
#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let pipeline = Axon::simple::<AppError>("order-pipeline")
        .then(process_order);

    HttpServer::new(move || {
        App::new()
            .app_data(web::Data::new(pipeline.clone()))
            .route("/orders", web::post().to(create_order))
    })
    .bind(("127.0.0.1", 8080))?
    .run()
    .await
}

#Ranvier와 함께 actix Extractor 사용

use actix_web::{web, HttpResponse, Responder};
use actix_web_httpauth::extractors::bearer::BearerAuth;

async fn protected_handler(
    auth: BearerAuth,  // actix extractor
    data: web::Json<RequestData>,
    pipeline: web::Data<Axon<RequestData, ResponseData, AppError, ()>>
) -> impl Responder {
    let mut bus = Bus::new();

    // 추출된 토큰을 Ranvier transition을 위해 Bus에 저장
    bus.insert(auth.token().to_string());

    match pipeline.execute(data.into_inner(), &(), &mut bus).await {
        Outcome::Next(result) => HttpResponse::Ok().json(result),
        Outcome::Fault(err) => HttpResponse::Unauthorized().json(err),
        _ => HttpResponse::InternalServerError().finish(),
    }
}

#이 접근 방식을 사용해야 할 때

적합한 경우:

  1. 기존 actix-web 앱에 복잡한 비즈니스 로직을 위해 Ranvier를 추가하는 경우
  2. actix extractor와 미들웨어에 익숙한 팀
  3. HTTP 처리에 actix의 성능이 필요한 경우
  4. 비즈니스 워크플로우에 Ranvier의 Schematic 시각화를 원하는 경우

고려사항:

  • 컨텍스트 연결: actix 요청 컨텍스트(extractor)를 Ranvier Bus로 수동으로 연결해야 함
  • 미들웨어 가시성: actix 미들웨어는 Ranvier Schematic에 표시되지 않음
  • 테스트: actix 통합 테스트 필요 (Ranvier transition은 별도로 단위 테스트)

#트레이드오프

측면 장점 제한사항
Extractor actix의 강력한 extractor 사용 (Json, Query, Path, Auth) Bus로의 수동 연결 필요
미들웨어 actix 미들웨어 생태계 활용 Ranvier Schematic에서 보이지 않음
비즈니스 로직 Schematic 시각화가 포함된 Ranvier transition actix-Ranvier 통합을 위한 추가 보일러플레이트
성능 actix의 검증된 HTTP 성능 + Ranvier 로직 컨텍스트 연결로 인한 최소한의 오버헤드

#대안과의 비교

  • 순수 Ranvier 대비: actix 통합은 actix extractor/미들웨어를 제공하지만 일부 Schematic 가시성을 잃음
  • Tower 통합 대비: 유사한 패턴이지만 actix는 다른 extractor 모델을 가짐 (함수 매개변수 vs request.extensions)
  • Axum 통합 대비: actix는 트레이트 기반 extractor를, Axum은 타입 기반 extractor를 사용

#관련 문서

  • Tower 통합 — 전체 예제 포함
  • Axum 통합 — Axum 미들웨어와 Ranvier