Ranvier
EN 문서 보기

#빠른 시작 — 5분 만에 첫 번째 API 만들기

버전: 0.33.0 최종 업데이트: 2026-03-15 적용 대상: ranvier (facade), ranvier-core, ranvier-macros, ranvier-runtime, ranvier-http 카테고리: Getting Started

Ranvier로 첫 번째 타입 안전 HTTP API를 만들어 보세요. 이 가이드는 5분 이내에 완료할 수 있습니다.

#사전 요구 사항

  • Rust 툴체인 1.85+ (edition = "2024" 지원 포함)
  • cargo 패키지 매니저

Rust가 설치되어 있지 않다면 rustup.rs에서 설치하세요.

rustc --version  # Verify 1.85.0 or later

#1단계: 프로젝트 생성

cargo init my-api
cd my-api

Cargo.toml에 다음 의존성을 추가하세요:

[package]
name = "my-api"
version = "0.1.0"
edition = "2024"

[dependencies]
ranvier = "0.33"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

단일 ranvier facade 크레이트로 10개의 워크스페이스 크레이트 전체(core, macros, runtime, http 등)에 접근할 수 있습니다.

#2단계: Hello Transition 작성

src/main.rs를 다음 코드로 교체하세요:

use ranvier::prelude::*;
use serde_json::json;

/// A simple transition that returns a JSON response
#[transition]
async fn hello(
    _state: (),
    _resources: &(),
    _bus: &mut Bus,
) -> Outcome<serde_json::Value, String> {
    Outcome::Next(json!({
        "message": "Hello from Ranvier!",
        "version": "0.33.0"
    }))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    // Axon::simple — same-type input/output pipeline
    let axon = Axon::simple::<serde_json::Value>("hello")
        .then(hello);

    tracing::info!("Ranvier server starting on http://127.0.0.1:3000");

    Ranvier::http()
        .bind("127.0.0.1:3000")
        .route("/api/hello", axon)
        .run(())
        .await?;

    Ok(())
}

#코드 설명

요소 용도
#[transition] 비동기 함수를 Ranvier Transition으로 변환하는 매크로
Outcome::Next(T) 성공 결과를 반환하고 다음 노드로 진행
Axon::simple::<T>(label) 동일 타입(T → T) 파이프라인의 편의 생성자
Bus 타입 안전 의존성 주입 컨테이너
Ranvier::http() 라우팅 및 미들웨어를 지원하는 HTTP Ingress 빌더

#3단계: 서버 실행

cargo run

출력:

INFO my_api: Ranvier server starting on http://127.0.0.1:3000

#4단계: API 테스트

새 터미널에서:

curl http://localhost:3000/api/hello

응답:

{
  "message": "Hello from Ranvier!",
  "version": "0.33.0"
}

#핵심 개념

개념 설명
Transition #[transition] 매크로 또는 Transition 트레이트를 통해 구현되는 비즈니스 로직의 단위
Axon Transition들을 체이닝하는 실행 파이프라인
Outcome Transition의 결과 타입 — Next, Fault, Branch, Jump, Emit
Bus 타입 안전 공유 상태 컨테이너 (insert, read, get, require)
Schematic Axon에서 자동 생성되는 실행 그래프 구조

#다음 단계

  • Hello World — Transition과 Axon 파이프라인을 처음부터 만들기
  • 튜토리얼: TODO API — JWT 인증, CRUD, Guard를 포함한 완전한 REST API 만들기
  • Bus 접근 패턴 — read(), get(), require(), try_require() 메서드 결정 트리
  • 프로덕션 준비 체크리스트 — 배포 전 체크리스트

#관련 문서

  • 시작 가이드 — 개념, 설정, 첫 프로젝트를 다루는 완전한 온보딩 가이드
  • 보안 강화 — SQL 인젝션 방지, 타이밍 안전 인증
  • 패턴 카탈로그 — 사가, 팬아웃/팬인 등 재사용 가능한 패턴