기능 플래그
masterror는 기본 빌드를 가볍게 유지합니다. 기본적으로 활성화되는 것은 std뿐입니다. 그 외의 모든 것 — 웹 전송, 텔레메트리, 라이브러리 통합 — 은 옵트인입니다. 이 페이지는 Cargo.toml에 선언된 모든 플래그에 대한 완전한 레퍼런스입니다.
[dependencies]
masterror = { version = "0.28", default-features = false }
# or with features:
# masterror = { version = "0.28", features = [
# "std", "axum", "actix", "openapi",
# "serde_json", "tracing", "metrics", "backtrace",
# "colored", "sqlx", "sqlx-migrate", "reqwest",
# "redis", "validator", "config", "tokio",
# "multipart", "teloxide", "init-data", "tonic",
# "frontend", "turnkey", "benchmarks"
# ] }
코어
| 플래그 | 활성화 내용 | 추가 의존성 |
|---|---|---|
std (기본값) | 표준 라이브러리 지원. 모든 런타임 통합에 필요합니다. no_std에서는 비활성화하세요 (no_std 지원 참조) | — |
웹 전송
| 플래그 | 활성화 내용 | 추가 의존성 |
|---|---|---|
axum | RFC 7807 JSON 본문을 갖춘 AppError와 ProblemJson의 IntoResponse; AppErrorKind::status_code() | axum (json, multipart), serde_json |
actix | AppError의 Actix Web ResponseError와 ProblemJson의 Responder | actix-web |
multipart | axum::extract::multipart::MultipartError → BadRequest 매핑 (axum 포함) | axum 경유 |
openapi | 오류 페이로드가 OpenAPI 스펙에 나타나도록 ErrorResponse와 AppCode에 utoipa::ToSchema 제공 | utoipa |
serde_json | AppError/ErrorResponse/ProblemJson의 구조화된 JSON details; FieldValue::Json과 field::json | serde_json |
tonic | 정제된 메타데이터와 함께 오류를 tonic::Status로 변환; StatusConversionError 익스포트 | tonic |
텔레메트리와 관측성
| 플래그 | 활성화 내용 | 추가 의존성 |
|---|---|---|
tracing | 오류 생성 시 구조화된 tracing 이벤트 발행 | tracing, log, log-mdc |
metrics | AppError마다 error_total{code,category} 카운터 증가 | metrics |
backtrace | 지연 std::backtrace::Backtrace 캡처 (RUST_BACKTRACE 존중), with_backtrace() 빌더 | — |
colored | 자동 TTY 감지를 갖춘 컬러 여러 줄 터미널 출력; AppError의 풍부한 Display | owo-colors |
비동기 및 IO 통합
각 통합 플래그는 라이브러리 오류를 분류 체계로 분류하는 From<...> for AppError 변환을 추가합니다:
| 플래그 | 변환 | 추가 의존성 |
|---|---|---|
sqlx | sqlx_core::Error → NotFound / Database (드라이버나 TLS가 없는 경량 sqlx-core) | sqlx-core |
sqlx-migrate | sqlx::migrate::MigrateError → Database (migrate 기능만 켠 전체 sqlx) | sqlx |
redis | redis::RedisError → Cache | redis |
reqwest | reqwest::Error → Timeout / Network / ExternalApi | reqwest |
tokio | tokio::time::error::Elapsed → Timeout | tokio (time) |
validator | validator::ValidationErrors → Validation | validator |
config | config::ConfigError → Config | config |
sqlx와 sqlx-migrate는 의도적으로 분리되어 있습니다. 오류 분류에는 sqlx-core만 필요하지만, 마이그레이션 오류 매핑은 전체 sqlx 크레이트를 가져옵니다.
메시징과 봇
| 플래그 | 변환 | 추가 의존성 |
|---|---|---|
teloxide | teloxide_core::RequestError → RateLimited / Network / ExternalApi / Deserialization / Internal | teloxide-core |
init-data | init_data_rs::InitDataError → TelegramAuth (Telegram Mini Apps init-data 검증) | init-data-rs |
프런트엔드와 도메인
| 플래그 | 활성화 내용 | 추가 의존성 |
|---|---|---|
frontend | frontend 모듈: WASM/브라우저 컨텍스트에서 오류를 wasm_bindgen::JsValue로 변환하고 console.error 로그 발행 | wasm-bindgen, js-sys, serde-wasm-bindgen |
turnkey | turnkey 모듈: TurnkeyErrorKind, TurnkeyError, classify_turnkey_error 및 AppError로의 변환 | — |
benchmarks | Criterion 벤치마크 스위트와 CI 베이스라인 도구 (로컬 프로파일링 전용) | — |
기본 변환 (항상 사용 가능)
기능 플래그가 없어도 AppError는 이미 다음에서 변환됩니다:
| 소스 | 대상 종류 |
|---|---|
std::io::Error | Internal |
String | BadRequest |
레시피
problem+json, OpenAPI 문서, tracing을 갖춘 Axum 기반 REST API:
masterror = { version = "0.28", features = ["axum", "openapi", "serde_json", "tracing"] }
sqlx, 마이그레이션, metrics를 갖춘 데이터베이스 서비스:
masterror = { version = "0.28", features = ["sqlx", "sqlx-migrate", "metrics", "tracing"] }
gRPC 서비스:
masterror = { version = "0.28", features = ["tonic", "tracing", "backtrace"] }
Mini App 인증을 갖춘 Telegram 봇:
masterror = { version = "0.28", features = ["teloxide", "init-data", "reqwest", "tokio"] }
WASM 프런트엔드:
masterror = { version = "0.28", features = ["frontend", "serde_json"] }
no_std 임베디드 또는 라이브러리 타깃:
masterror = { version = "0.28", default-features = false }
참고 사항
sqlx와sqlx-migrate를 제외한 모든 통합 플래그는std를 포함합니다. 이 두 플래그는 플래그 수준에서std에 독립적입니다.axum과actix는 응답 본문이 JSON이므로serde_json을 전이적으로 가져옵니다.- 기능 플래그는 이미 활성화된
ErrorResponse/ProblemJson필드의 와이어 계약을 절대 변경하지 않습니다. 기능(예:serde_json은details를 일반 텍스트에서 구조화된 JSON으로 업그레이드)이나 트레이트 구현만 추가합니다.