튜토리얼

Ranvier 첫 회로를 직접 구성해 봅시다.

이 튜토리얼은 최신 hello-world 예제를 기준으로 회로를 만들고, CLI schematic export와 VSCode 확장 워크플로까지 이어서 설명합니다.

1. 의존성 설치

cargo add ranvier
cargo add ranvier-macros
cargo add tokio --features full
cargo add anyhow

2. Transition 정의 (최신 hello-world)

use ranvier::prelude::*;
use ranvier_macros::transition;

#[derive(Clone)]
struct Greet;

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

#[derive(Clone)]
struct Exclaim;

#[transition]
async fn exclaim(state: String, _resources: &(), _bus: &mut Bus) -> Outcome<String, anyhow::Error> {
    Outcome::Next(format!("{} 🚀", state))
}

3. schematic 모드 가드 + Ingress Builder 연결

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let hello = Axon::<(), (), anyhow::Error>::new("HelloWorld")
        .then(greet)
        .then(exclaim);

    if hello.maybe_export_and_exit()? {
        return Ok(());
    }

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

    Ok(())
}

cargo run으로 실행한 뒤 http://127.0.0.1:3000에 접속하세요.

4. 리소스 연결 이해하기

DB 풀, 트레이서, 설정 같은 공유 리소스는 명시적으로 연결합니다. Ingress에서 리소스를 주입하고, Transition에서는 필요한 순간에만 Bus에서 읽습니다.

5. 기준 예제 실행 (저장소)

Hello World (HTTP)

cargo run -p hello-world

Typed State Tree

cargo run -p typed-state-tree

Schematic Baseline

cargo run -p basic-schematic

기준 예제 목록은 저장소에서 확인할 수 있습니다: ranvier/examples

6. Ranvier CLI로 schematic/projection 사용

cargo install ranvier-cli
ranvier schematic hello-world --output schematic.json

7. VSCode 확장 워크플로

code --install-extension cellaxon.ranvier-vscode
# 명령 팔레트:
# Ranvier: Open Circuit View
# Ranvier: Run Schematic Export

8. Trace Projection 생성

ranvier status projection-from-example order-processing-demo \
  --output ./dist/trace-order \
  --service "Ranvier Service" \
  --circuit-id order_processing \
  --circuit-version 0.1.0