Initial Commit: Reinforced Knowledge Wiki v1.0 - Pure Origin

Design & Experience/TypeScript의 안전한 인터페이스 설계.md

@@ -0,0 +1,46 @@
+---
+id: P-REINFORCE-AUTO-08AE3A
+category: "[[10_Wiki/💡 Topics/Design & Experience]]"
+confidence_score: 0.90
+tags: [auto-reinforced]
+last_reinforced: 2026-04-20
+github_commit: "[P-Reinforce] Continuous Worker - TypeScript의 안전한 인터페이스 설계"
+---
+
+# [[TypeScript의 안전한 인터페이스 설계]]
+
+## 📌 한 줄 통찰 (The Karpathy Summary)
+> TypeScript의 인터페이스 설계는 언어의 근본적인 특성인 구조적 타이핑(Structural Typing)의 유연성을 수용하면서도, 의도치 않은 데이터 유입과 런타임 에러를 방어하는 것을 핵심으로 합니다 [1-3]. 이를 위해 개발자는 `interface`와 `type alias`를 전략적으로 선택하고, `readonly`를 통한 불변성 확보, 식별 가능한 유니온을 활용한 상태 관리, 그리고 `satisfies` 연산자나 브랜디드 타입(Branded Types) 같은 고급 기법을 동원해야 합니다 [4-8]. 결과적으로 안전한 인터페이스 설계는 시스템의 예측 가능성을 높이고 변경에 따른 부작용을 최소화하는 견고한 아키텍처적 도구로 작용합니다 [9].
+
+## 📖 구조화된 지식 (Synthesized Content)
+*   **구조적 타이핑과 과잉 속성 체크 (Structural Typing & EPC)**
+    TypeScript는 객체의 실제 구조가 일치하면 동일한 타입으로 간주하는 구조적 타이핑을 사용합니다 [3, 10]. 이러한 유연성은 예기치 않은 속성의 유입이라는 허점을 만드는데, 이를 방어하기 위해 객체 리터럴 직접 할당 시 과잉 속성 체크(Excess Property Checking, EPC)가 작동합니다 [1, 3]. 더 나아가 할당 과정에서 타입 단언(`as`)을 사용하기보다 `satisfies` 연산자를 활용하면, 객체의 구체적인 속성(리터럴 타입 등)을 유지하면서도 인터페이스 요구사항을 엄격하게 검증하여 과잉 속성과 오타를 컴파일 시점에 차단할 수 있습니다 [8, 11-13].
+
+*   **Interface와 Type Alias의 전략적 선택**
+    성능과 확장성 측면에서 두 도구는 명확한 차이를 가집니다. `interface`는 컴파일러가 이름을 기준으로 캐싱을 수행하며 선언 병합(Declaration Merging)이 가능해 확장에 유리하므로, 핵심 도메인 모델이나 외부 API 계약에 적합합니다 [4, 14, 15]. 반면 `type alias`의 교집합(`&`)은 매번 구조를 재계산하여 성능을 저하시킬 수 있으나, 동일한 이름의 재선언을 막아 엄격한 관리가 가능하므로 비즈니스 로직 내부에서 유용합니다 [4, 15-17].
+
+*   **불변성(Immutability)을 통한 데이터 보호**
+    객체나 배열이 예기치 않게 변경되는 것을 막기 위해 `readonly` 수식어를 사용합니다 [5, 18]. 런타임 오버헤드가 발생하는 `Object.freeze()`와 달리 `readonly`는 컴파일 시점에 완벽히 동작하여 효율적인 데이터 무결성을 제공합니다 [5, 19, 20]. 단, 기본 `readonly`는 얕은(shallow) 수준만 보호하므로, 중첩된 객체를 다룰 때는 매핑 타입과 조건부 타입을 결합한 `DeepReadonly`와 같은 재귀적 타입을 설계해야 완벽한 방어가 가능합니다 [6, 21, 22].
+
+*   **식별 가능한 유니온(Discriminated Unions)과 완전성 검사**
+    공통된 리터럴 속성(태그)을 사용하여 타입을 좁히는(Narrowing) 식별 가능한 유니온 패턴은 상태 관리에서 불가능한 상태를 원천 차단합니다 [6, 23, 24]. 이와 함께 `never` 타입을 활용한 완전성 검사(Exhaustiveness Checking)를 적용하면, 새로운 타입이나 상태가 추가되었을 때 개발자가 이를 누락하지 않도록 컴파일 에러를 발생시켜 빈틈없는 수비 체계를 유지할 수 있습니다 [24-26].
+
+*   **브랜디드 타입(Branded Types)을 활용한 명목적 타이핑**
+    구조적 타이핑의 한계로 인해 본질적으로 다른 데이터(예: 이메일과 일반 이름 문자열)가 섞이는 것을 막기 위해 브랜디드 타입을 사용합니다 [7, 27]. 고유한 표식(`__brand` 등)이나 `unique symbol`을 타입에 부여함으로써 컴파일 시점에 엄격한 명목적 타이핑(Nominal Typing)을 에뮬레이트하며, 외부의 오염된 데이터가 시스템 핵심 로직으로 침투하는 것을 차단합니다 [7, 28, 29].
+
+*   **SOLID 원칙에 기반한 인터페이스 설계**
+    안전한 설계는 객체 지향의 원칙과 궤를 같이합니다. 인터페이스 분리 원칙(ISP)에 따라 한 인터페이스에 너무 많은 책임을 부여하지 않고 최소 단위로 쪼개야 변경에 유연하게 대응할 수 있습니다 [30, 31]. 또한, 복잡한 내부 서브시스템을 단순한 인터페이스로 노출하는 퍼사드(Facade) 패턴을 적용하면, 개발자의 인지 부하를 줄이고 휴먼 에러를 방지할 수 있습니다 [31-33].
+
+## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
+- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
+- **정책 변화:** Design & Experience 분야의 자동 자산화 수행.
+
+## 🔗 지식 연결 (Graph)
+- **Related Topics:** [[구조적 타이핑]], [[과잉 속성 체크(EPC)]], [[식별 가능한 유니온]], [[브랜디드 타입]], [[불변성(Immutability)]]
+- **Projects/Contexts:** [[대규모 애플리케이션 개발]], [[프론트엔드 아키텍처 및 SDK 설계]]
+- **Contradictions/Notes:** `type`과 `interface`의 사용 지침과 관련하여, TypeScript 성능과 캐싱을 고려해 객체 확장에 `interface extends`를 권장하는 측면과 [4, 14], 선언 병합(Declaration Merging)으로 인한 의도치 않은 타입 변경을 방지하기 위해 보다 엄격한 `type`의 사용을 선호하는 개발자들의 의견이 대립하는 사례가 존재합니다 [15, 17, 34, 35].
+
+---
+*Last updated: 2026-04-18*
+- Raw Source: [[00_Raw/2026-04-20/TypeScript의 안전한 인터페이스 설계.md]]
+---