2nd/01_Archive/2026-04-20/견고한 도메인 모델 및 API 계약 설계.md

---
id: P-REINFORCE-AUTO-E5BF95
category: "10_Wiki/💡 Topics/Programming & Language"
confidence_score: 0.90
tags: [auto-reinforced]
last_reinforced: 2026-04-20
github_commit: "[P-Reinforce] Continuous Worker - 견고한 도메인 모델 및 API 계약 설계"
---

# [[견고한 도메인 모델 및 API 계약 설계|견고한 도메인 모델 및 API 계약 설계]]

## 📌 한 줄 통찰 (The Karpathy Summary)
> 견고한 도메인 모델 및 API 계약 설계는 TypeScript의 정적 타입 시스템을 활용하여 유효하지 않은 상태를 원천 차단하고 예측 가능한 애플리케이션 구조를 만드는 과정입니다. 이를 위해 식별 가능한 유니온, 브랜디드 타입, 불변성 제약, 그리고 "검증하지 말고 파싱하라"와 같은 설계 철학을 결합하여, 경계면에서부터 데이터의 무결성을 보장하는 안전한 계약을 수립합니다.

## 📖 구조화된 지식 (Synthesized Content)
* **"검증하지 말고 파싱하라 (Parse, don't validate)":** 시스템 경계(API 진입점이나 출구)에서 타입이 지정되지 않은 데이터를 수동으로 검증하기만 하는 대신, 잘 정의된 타입의 데이터로 파싱하여 변환해야 합니다 [1, 2]. Zod와 같은 런타임 검증 라이브러리를 브랜디드 타입과 결합하면, 알 수 없는 데이터를 명확한 타입으로 좁히고 시스템 내부에서 정적 분석의 이점을 온전히 누릴 수 있습니다 [3, 4].
* **식별 가능한 유니온(Discriminated Unions)과 완전성 검사:** 객체의 공통 리터럴 속성을 식별자로 사용하는 유니온 타입을 통해, 런타임에 유효하지 않은 상태가 아예 표현될 수 없도록 도메인을 모델링합니다 [5-7]. 여기에 `never` 타입을 활용한 완전성 검사(Exhaustiveness checking)를 더하면, 새로운 API 응답 상태나 도메인 로직이 추가될 때 처리되지 않은 케이스를 컴파일 에러로 즉각 잡아낼 수 있습니다 [6, 8-10].
* **브랜디드 타입(Branded Types)을 통한 명목적 타이핑:** TypeScript의 구조적 타이핑이 갖는 한계(기본 타입에의 집착)를 극복하기 위해, 식별용 가상 속성이나 `unique symbol`을 교집합으로 추가하여 고유한 불투명 타입(Opaque Types)을 생성합니다 [11-14]. 이를 통해 사용자 ID와 주문 ID처럼 구조가 동일한 문자열이나 숫자일지라도 서로 섞여 API 계약을 위반하는 치명적인 버그를 컴파일 타임에 차단합니다 [3, 15, 16].
* **`satisfies` 연산자를 활용한 엄격한 계약 강제:** 변수를 거친 간접 할당 과정에서는 타입스크립트의 과잉 속성 체크(Excess Property Checking)가 작동하지 않을 수 있습니다 [17, 18]. 백엔드 API 응답을 프론트엔드 모델로 매핑할 때 `satisfies` 연산자를 사용하면, 추가된 초과 속성을 엄격하게 에러로 잡아내면서도 구체적인 리터럴 타입 추론을 그대로 유지하여 계약의 엄격성과 유연성을 동시에 달성합니다 [19-22].
* **불변성(Immutability) 확립:** 객체와 배열의 무분별한 상태 변경을 막고 데이터 무결성을 보장하기 위해 `readonly` 수식어와 `DeepReadonly` 재귀적 유틸리티 타입을 적용합니다 [23-25]. 식별자, 설정 객체, API 응답 등 절대 변경되어서는 안 되는 핵심 데이터에 컴파일 타임의 강력한 보호막을 제공합니다 [25, 26].
* **도메인 방어 및 예외 처리 설계:** 비즈니스 로직에서 예상 가능한 실패를 처리할 때 단순히 `throw`로 예외를 발생시키는 대신, `Result` 타입을 명시적으로 반환합니다 [27-30]. 이를 통해 함수 시그니처 자체를 견고한 계약으로 만들어, API의 가능한 모든 결과(오류 포함)를 소비자가 안전하고 철저하게 처리하도록 강제합니다 [28, 29, 31].

## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.

## 🔗 지식 연결 (Graph)
- **Related Topics:** [[Parse, don't validate|Parse, don't validate]], [[식별 가능한 유니온 (Discriminated Unions)|식별 가능한 유니온 (Discriminated Unions)]], [[브랜디드 타입 (Branded Types)|브랜디드 타입 (Branded Types)]], [[satisfies 연산자|Satisfies 연산자]], [[불변성 (Immutability)|불변성 (Immutability)]], Result 타입
- **Projects/Contexts:** Zod를 활용한 런타임 데이터 검증, API 응답 처리 및 상태 머신 모델링
- **Contradictions/Notes:** 소스에 따르면 교집합(`&`)과 타입 별칭(`type`)만으로도 객체를 조합할 수 있지만, 대규모 프로젝트의 성능과 컴파일러 캐싱 최적화를 고려할 때 핵심 도메인 객체 선언에는 인터페이스 상속(`interface extends`)을 우선시하는 것이 권장됩니다 [32-34]. 또한 비즈니스 흐름 제어를 위해 전통적인 예외(`Exception`) 투척보다는 `Result` 패턴을 활용하는 방식이 더욱 안전한 설계로 제시됩니다 [28, 30, 35].

---
*Last updated: 2026-04-18*
- Raw Source: 00_Raw/2026-04-20/견고한 도메인 모델 및 API 계약 설계.md
---