피드로 돌아가기
Dev.toBackend
원문 읽기
Zod 기반 Boundary Validation을 통한 CLI 타입 안정성 확보
Build a typed CLI from scratch with Commander.js + Zod
AI 요약
Context
Commander.js의 옵션 파싱 결과가 타입 정의와 무관하게 string 또는 undefined로 반환되는 구조적 한계 존재. 개발자가 직접 Type Casting과 Validation을 수행함에 따라 런타임 에러 발생 가능성이 높은 불안정한 아키텍처 구조임.
Technical Solution
- Commander.js를 인터페이스 계층으로, Zod를 데이터 계약(Contract) 계층으로 분리한 설계 채택
- z.coerce.number()를 활용하여 CLI raw text를 런타임에서 자동 형변환하는 메커니즘 구축
- safeParse() 기반의 제네릭 헬퍼 함수를 구현하여 ZodError를 사용자 친화적 메시지로 변환하는 예외 처리 계층 추가
- 환경 변수(Env Vars)와 CLI 플래그를 병합 후 단일 Schema로 검증하는 Unified Validation 파이프라인 설계
- TypeScript의 strict mode와 Zod의 Type Inference를 결합하여 Cast 없는 End-to-End 타입 안전성 구현
실천 포인트
- CLI 옵션 정의 시 단순 문자열 기반 검증 대신 Zod Schema 도입 검토 - Type Assertion(as string) 사용을 지양하고 Runtime Validation을 통한 Type Narrowing 적용 - Env Var와 CLI Option의 우선순위를 정의한 데이터 병합 전략 수립 - 사용자에게 노출되는 시스템 에러를 정제하는 Error Handler 추상화 레이어 구축