#빠른 시작: 5분 만에 Hello World API 만들기

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

난이도: 초급 소요 시간: ~5분 목표: Ranvier HTTP API를 실행하고 로컬에서 "Hello, World!"를 반환하기.

#사전 요구 사항

• Rust 툴체인 설치 (rustup, cargo)
• ranvier CLI 설치: cargo install ranvier-cli

#1단계: 새 프로젝트 생성 (1분)

ranvier new hello-world --template minimal
cd hello-world

생성되는 구조:

hello-world/
├── Cargo.toml
├── src/main.rs
└── README.md

#2단계: 생성된 코드 살펴보기 (1분)

src/main.rs를 여세요. 최소한의 Ranvier 앱을 확인할 수 있습니다:

use ranvier_core::prelude::*;
use ranvier_http::prelude::*;
use ranvier_macros::transition;
use ranvier_runtime::Axon;

#[transition]
async fn greet(_input: (), _resources: &(), _bus: &mut Bus) -> Outcome<String, anyhow::Error> {
    Outcome::Next("Hello from Ranvier!".to_string())
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt::init();

    let hello = Axon::<(), (), anyhow::Error>::new("hello-world")
        .then(greet);

    Ranvier::http()
        .bind("127.0.0.1:3000")
        .route("/", hello)
        .run(())
        .await
        .map_err(|e| anyhow::anyhow!("Server error: {}", e))?;

    Ok(())
}

핵심 개념:

• #[transition] — 비동기 함수를 타입이 지정된 Axon Transition으로 표시
• Outcome::Next(value) — Transition의 정상 경로 결과
• Axon::new("label").then(fn) — 실행 파이프라인 구성
• Ranvier::http().route("/", axon) — 파이프라인을 HTTP 라우트에 연결

#3단계: 서버 실행 (1분)

cargo run

예상 출력:

Starting server on http://127.0.0.1:3000

#4단계: 확인 (30초)

새 터미널에서:

curl http://127.0.0.1:3000/

예상 응답:

Hello from Ranvier!

성공! Ranvier HTTP API가 실행 중입니다.

#5단계: 동작 이해하기 (1분)

HTTP GET /
    ↓
Ranvier::http() ingress
    ↓
Axon pipeline: () → greet() → String
    ↓
HTTP 200 "Hello from Ranvier!"

Axon은 타입이 지정된 실행 파이프라인입니다. 모든 단계는 Transition — 타입이 지정된 입출력을 가진 순수 비동기 함수입니다. Bus는 트레이싱과 같은 횡단 관심사를 위한 부채널입니다.

#다음 단계

#문제 해결

ranvier: command not found cargo install ranvier-cli를 실행하고 ~/.cargo/bin이 PATH에 포함되어 있는지 확인하세요.

포트가 이미 사용 중 main.rs에서 바인드 주소를 변경하세요: .bind("127.0.0.1:3001").

컴파일 오류 자세한 오류 목록을 보려면 cargo check를 실행하세요. 일반적인 문제는 FAQ를 참조하세요.