Ranvier
EN

#Ranvier 시작하기

버전: 0.51.0 최근 업데이트: 2026-07-16 카테고리: 시작하기

이 문서는 canonical 퀵스타트 이후의 탐색 경로입니다. 별도의 두 번째 의존성 설치 방법을 제시하지 않습니다.

#1. 여기서 시작하기

Canonical 퀵스타트를 먼저 완료합니다. Rust 1.93.0 이상과 공개 ranvier facade를 사용하는 유일한 첫 사용자 설치 경로입니다.

#2. 세 가지 워크플로로 후보 API 익히기

  1. 타입 상태 진행 — Transition, 타입이 연결된 Axon handoff, Outcome.
  2. 타입 JSON 네이티브 HTTP — 지원되는 네이티브 ingress와 타입 요청/응답 경계.
  3. Bus capability 정책 — 명시적인 리소스와 요청 컨텍스트 접근 정책.

세 워크플로는 모두 Canonical 또는 Supported이며 외부 런타임 서비스 없이 반복 gate에서 컴파일됩니다.

#3. HTTP 경계 선택하기

  • 새 의사결정 중심 서비스: 네이티브 Ranvier::http()를 사용합니다.
  • 기존 Axum 서비스: Axum + Ranvier 하이브리드 가이드를 따르고 Axon에 필요한 상태만 연결합니다.
  • 의사결정 파이프라인이 없는 단순 CRUD/프록시: Axum만 사용하는 편이 단순합니다. Ranvier를 모든 엔드포인트의 필수 wrapper로 쓰지 않습니다.

#4. 안정 경로 확장하기

  • Hello World 튜토리얼
  • API 안정성 계약
  • 테스트 패턴
  • 프로덕션 준비 체크리스트

기존 장문 온보딩의 핵심 내용은 또 다른 설치법으로 남기지 않고 다음과 같은 제한된 심화 지도로 보존합니다.

#Transition 조합과 테스트

  • .then()은 이전 단계의 Next 출력과 다음 transition 입력이 일치하는지 컴파일 시점에 검사합니다.
  • transition을 일반 async 단위로 테스트한 뒤, 명시적인 Bus와 execute()로 전체 Axon을 테스트합니다.
  • 실행 예제: `typed-state-tree`, `testing-patterns`.

#오류와 Outcome 경계

  • Fault에는 보통 thiserror를 사용한 도메인 오류 enum을 사용합니다.
  • Next와 Fault는 Rust 타입을 유지합니다. 스키마로 기술된 Branch, Jump, Emit payload는 런타임 검증 경계를 지납니다.
  • 실행 예제: `custom-error-types`.

#Bus, Resources, 권위 상태

  1. 한 의사결정 경로를 따라가는 실행 단위 capability에는 Bus를 사용합니다. Capability 존재와 접근 정책은 런타임 검사입니다.
  2. DB 풀, 설정, HTTP/cache client 같은 프로세스 로컬 인프라 handle에는 Resources: ResourceRequirement를 사용합니다.
  3. 여러 서비스 인스턴스에서 일관돼야 하는 가변 상태에는 외부 권위 시스템을 사용합니다.

Ranvier는 Resources를 숨은 DI container로 만들지 않으며 프레임워크 소유 ORM이나 mocking DSL을 제공하지 않습니다. 생태계 client는 명시적인 resource 뒤에 두고 테스트에서는 해당 handle을 교체합니다.

#복원력과 영속성

  • Transition 경계와 멱등성 모델을 명확히 한 뒤 retry/DLQ 정책을 추가하고, Timeline event로 retry와 DLQ 활동을 확인합니다.
  • 장기 실행 워크플로에는 checkpoint/resume을 사용하되 trace 생명주기와 권위 persistence를 명시적으로 선택합니다.
  • 실행 예제: `retry-dlq-demo`, `state-persistence-demo`.
  • 운영 문서: 영속성 runbook, 프로덕션 증거 pack.

#5. Lab/Experimental 자료는 마지막에 보기

안정 경로가 동작한 뒤에만 Examples Explorer의 Lab 또는 Experimental 항목을 참고합니다. 이 항목은 일상 Developer/Release 지원 범위에 포함되지 않습니다.