masterror란 무엇인가요?

masterror는 Display와 source()만으로는 부족한 Rust 서비스를 위한 오류 처리 워크스페이스입니다. thiserror가 트레이트 구현 파생에서 멈추고 anyhow가 타입이 소거된 전파에서 멈추는 반면, masterror는 오류를 전송 경계까지 끝까지 운반합니다:

• AppError — 의미론적 범주(AppErrorKind), 안정적인 기계 판독 가능 코드(AppCode), 선택적인 안전한 공개 메시지, 구조화된 메타데이터, 전송 힌트(Retry-After, WWW-Authenticate)를 갖춘 풍부한 오류 값입니다.
• 보수적인 HTTP 및 gRPC 매핑 — 모든 종류와 코드는 HTTP 상태, tonic::Code 판별값, RFC 7807 type URI에 결정론적으로 매핑됩니다.
• 타입 기반 텔레메트리 — 메타데이터는 임시방편의 String 맵이 아니라 필드별 리덕션 정책을 갖춘 타입 기반 필드(문자열, 정수, 부동 소수점, 기간, IP, UUID, JSON)로 저장됩니다.
• 네이티브 파생 — #[derive(Error)]는 thiserror 구문을 미러링하며, #[app_error(...)]와 #[derive(Masterror)]는 코드, 범주, 리덕션 및 매핑 테이블과 함께 도메인 오류를 AppError에 연결합니다.
• 설계 단계부터의 리덕션 — 소스는 절대 클라이언트에 직렬화되지 않으며, 메시지, 세부 정보 및 메타데이터 필드는 경계에서 리덕션, 해시 또는 마스킹될 수 있습니다.

unsafe 코드가 없고, MSRV가 고정되어 있으며, 기본 std 기능을 비활성화하면 no_std를 지원합니다.

해결하는 문제

thiserror로 파생한 열거형은 무슨 일이 일어났는지 알려줍니다. masterror는 여기에 더해 클라이언트가 무엇을 보는지(상태, 코드, 안전한 메시지, problem+json), 운영자가 무엇을 보는지(구조화된 필드, tracing 이벤트, 카운터), 무엇이 절대 유출되지 않는지(소스, 리덕션된 필드)까지 결정합니다.

주요 기능

빠른 예제

use masterror::{AppError, AppErrorKind, AppResult, ProblemJson, field};

fn find_user(id: u64) -> AppResult<()> {
    masterror::ensure!(id != 0, AppError::bad_request("id must be non-zero"));

    Err(AppError::not_found("user not found")
        .with_field(field::u64("user_id", id))
        .with_field(field::str("request_id", "abc123")))
}

let err = find_user(42).unwrap_err();
assert_eq!(err.kind, AppErrorKind::NotFound);
assert_eq!(err.kind.http_status(), 404);

let problem = ProblemJson::from_app_error(err);
assert_eq!(problem.status, 404);
assert_eq!(problem.code.as_str(), "NOT_FOUND");
assert_eq!(problem.grpc.expect("grpc").name, "NOT_FOUND");

또는 도메인 오류를 한 번만 선언하고 매핑은 파생 매크로에 맡길 수 있습니다:

use masterror::{AppCode, AppError, AppErrorKind, Error};

#[derive(Debug, Error)]
#[error("missing flag: {name}")]
#[app_error(kind = AppErrorKind::BadRequest, code = AppCode::BadRequest, message)]
struct MissingFlag {
    name: &'static str
}

let app: AppError = MissingFlag { name: "feature" }.into();
assert!(matches!(app.kind, AppErrorKind::BadRequest));

워크스페이스 크레이트

문서

시작하기

• 시작하기 — 설치, 첫 오류, 매크로, 첫 파생
• 기능 플래그 — 의존성을 포함한 전체 플래그 레퍼런스

핵심 개념

• 오류 종류와 코드 — 분류 체계, HTTP/gRPC 테이블, problem+json
• Derive 매크로 — #[derive(Error)], #[derive(Masterror)]와 해당 속성
• 컨텍스트와 메타데이터 — Context, ResultExt, 필드, 리덕션, 체인

통합

• 웹 프레임워크 — Axum, Actix, tonic
• 통합 — sqlx, redis, reqwest, validator 등
• 관측성 — tracing, metrics, 백트레이스, 디스플레이 모드

고급

• no_std 지원 — 표준 라이브러리 없이 실행하기
• 모범 사례 — 서비스와 라이브러리를 위한 패턴
• 마이그레이션 — thiserror / anyhow에서 이전하기