#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(),
}
}#이 접근 방식을 사용해야 할 때
적합한 경우:
- 기존 actix-web 앱에 복잡한 비즈니스 로직을 위해 Ranvier를 추가하는 경우
- actix extractor와 미들웨어에 익숙한 팀
- HTTP 처리에 actix의 성능이 필요한 경우
- 비즈니스 워크플로우에 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