1.4k LOC 레거시 파서를 Zod 기반 단일 스키마로 통합하여 설정 무결성 확보

One Schema to Rule Them All: The Config v2 Rewrite

IT Lackey2026년 6월 4일9분intermediate

AI 요약

Context

독립적으로 성장한 3개의 설정 블록과 개별 파서로 인한 기술 부채 누적 상황. 오타 발생 시 경고 없이 기본값으로 폴백되는 Silent Failure와 설정 파일 손상 시의 무분별한 기본값 적용으로 인한 시스템 불안정성 심화.

Zod 기반 단일 Schema 설계를 통한 소스 오브 트루스(Source of Truth) 통합 및 파싱/변환/검증 로직 중앙화
.passthrough()를 최상위에 적용하여 하위 버전 호환성을 유지하는 Round-trip 데이터 보존 구조 설계
.catch(undefined)와 .strict()를 혼합 사용하여 필드별 유연성과 핵심 레코드(profiles, sources)의 엄격한 검증을 동시에 달성
superRefine을 활용한 레거시 키(stashes[]) 및 제거된 타입에 대한 명시적 Migration 경로 강제
Schema로부터 JSON Schema를 자동 생성하고 CI Drift Test를 통해 코드와 문서 간 동기화 강제
TypeScript Type Inference를 적용하여 스키마 변경 시 타입 선언의 병렬 수정 비용 제거

실천 포인트

1. 설정 파일의 Silent Failure 방지를 위해 기본값 폴백 전 엄격한 유효성 검사 단계 도입 검토

2. 스키마-타입-문서(JSON Schema) 간의 정렬을 위한 자동화 파이프라인 및 CI Drift Test 구축

3. 하위 호환성이 필요한 경우 전체 엄격 모드 대신 특정 필드에만 .strict()를 적용하는 계층적 검증 전략 채택

태그