Files

T

koriweb 5ba5a55c78 feat: Wiki 지식 자산 업데이트 - UX Scenarios, Frontend, Game Design, Topics 추가 [2026-05-08]

2026-05-08 19:52:07 +09:00

11 KiB

Raw Blame History

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, tags, raw_sources, last_reinforced, github_commit, inferred_by, tech_stack

title

Composition API

📌 한 줄 통찰 (The Karpathy Summary)

Vue 3 Composition API는 컴포넌트의 옵션(data, methods, computed 등)이 아닌 '논리적 관심사(Logical concerns)'를 기준으로 코드를 구성하고 조직할 수 있게 해주는 강력한 기능이다 [1]. 반응형 원시 타입(ref, reactive)과 함수를 활용하여 상태와 로직을 캡슐화하고 재사용 가능한 형태로 만든다 [1]. 기존의 Options API에 비해 대규모 프로젝트에서의 확장성, 코드 재사용성, 그리고 TypeScript와의 뛰어난 호환성을 제공하여 유지보수성을 극대화한다 [2-4].

📖 구조화된 지식 (Synthesized Content)

반응형 상태 관리 (Reactive State Management): ref()와 reactive() 함수를 통해 반응형 상태를 선언한다. ref()는 원시 값과 객체를 모두 지원하며 .value 속성을 통해 접근하고, reactive()는 주로 복잡한 객체나 배열을 다루기 위해 설계되었다 [5, 6]. 내재된 한계로 인해 유연성을 갖춘 ref()를 반응형 상태 선언의 주요 API로 사용하는 것이 종종 권장된다 [6].
컴포저블 (Composables): 재사용 가능한 상태 기반 로직을 캡슐화한 함수로, Composition API 재사용성의 초석이다 [7, 8]. 과거 Vue 2의 Mixins 패턴이 초래하던 네이밍 충돌이나 데이터 출처가 불분명해지는 문제를 '상속 대신 합성(Composition over Inheritance)'이라는 접근법을 통해 투명하고 타입 안전하게 해결한다 [9].
논리적 관심사 그룹화: 기존 Options API에서는 단일 기능에 대한 로직이 data, methods, computed 곳곳에 흩어져 있었으나, Composition API를 사용하면 관련된 모든 로직을 한 곳에 밀집시킬 수 있어 가독성과 추적성이 향상된다 [10, 11].
<script setup> 문법의 결합: 현대 Vue 3 개발에서는 <script setup> 문법을 일관되게 사용하여 보일러플레이트를 줄인다 [12]. 이 구문 내에서 선언된 변수와 함수는 템플릿에 자동으로 노출되며, 코드를 더 간결하게 만들고 IDE의 지원을 극대화한다 [13].
Provide / Inject를 통한 컨텍스트 공유: 엔터프라이즈 환경에서 데이터가 불필요한 중간 컴포넌트 계층을 거치는 'Prop Drilling' 문제를 방지한다 [14]. 전역 로거, API 클라이언트 주입이나 테마 및 다국어 지원 등 '컨텍스트 인식(Context-aware)' 컴포넌트 트리를 구성하는 데 활용된다 [14, 15].
강력한 TypeScript 호환성: Composition API는 TypeScript와 매끄럽게 통합되어 뛰어난 타입 추론을 제공한다 [2, 11]. 이는 런타임 에러를 사전에 방지하고 버그를 최소화하며 개발 속도를 높이는 결정적 요인으로 작용한다 [3, 4].

⚠️ 모순 및 업데이트 (Contradictions & Updates)

가파른 학습 곡선 (Steeper Learning Curve): 단순하고 선언적인 구조를 가진 Options API에 비해 Composition API는 상대적으로 학습 곡선이 가파르다 [16, 17].
반응성(Reactivity) 상실의 위험: reactive를 원시 값에 잘못 사용하거나, 반응형 객체를 직접 구조 분해 할당(Destructuring)할 경우 반응성 연결이 끊어지는 흔한 실수가 발생할 수 있다. 이를 유지하려면 속성에 직접 접근하거나 toRefs() 유틸리티를 사용해야 한다 [18]. 또한 JavaScript 내부에서 ref 변수에 접근할 때 .value를 누락하는 실수에 유의해야 한다 [18].
라이프사이클 및 비동기 로직의 위치 제약: 데이터 페칭 및 이벤트 리스너 설정 로직은 setup 함수 내부의 적절한 라이프사이클 훅 안에서 호출되어야 한다. 이 규칙을 벗어날 경우 메모리 누수(Memory leaks)나 예기치 않은 동작이 발생할 수 있다 [19].
단순 컴포넌트에서의 오버엔지니어링: 재사용성이 낮고 기능이 단순한 단일 기능 컴포넌트에서는 Composition API를 도입하는 것이 불필요하게 복잡할 수 있으며, 이 경우 Options API를 사용하는 것이 더 직관적일 수 있다 [16, 20].

🔗 지식 연결 (Graph)

[관계 유형 A: 아키텍처/기반 기술]

Options API
- 연결 이유: Composition API 이전의 기본 컴포넌트 작성 방식이자 대조되는 개념이다 [1].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 프로젝트의 크기(단순함 vs 복잡성)에 따라 어떤 API 설계가 더 적합한지 트레이드오프를 명확히 비교 평가할 수 있다 [16, 20].
Composables
- 연결 이유: Composition API의 유연성을 실질적인 재사용 단위로 구현하는 핵심 패턴이다 [7, 8].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: Mixins을 대체하며 복잡한 상태 로직을 어떻게 투명하고 안전하게 모듈화하여 캡슐화할 수 있는지 설계 원리를 이해할 수 있다 [8, 9].
Reactivity System (ref, reactive)
- 연결 이유: Composition API의 근간이 되는 반응형 원시 타입 메커니즘이다 [21].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: Vue가 데이터 변경을 어떻게 추적하고 파생 상태(computed)나 부수 효과(watch)를 처리하는지 내부 렌더링 원리를 이해할 수 있다 [5, 21].

[관계 유형 B: 구현/활용 도구]

Pinia
- 연결 이유: Vuex를 대체하며 Composition API 스타일을 완벽하게 지원하는 Vue 3의 공식 상태 관리 라이브러리이다 [22-24].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 로컬 상태 관리(Composables)를 넘어 전역 상태 관리를 어떻게 타입 안전하게 구축하고 관리하는지 확장할 수 있다 [23, 25, 26].
TypeScript
- 연결 이유: Composition API가 제공하는 구조적 이점을 극대화하는 강력한 정적 타입 시스템이다 [2, 27].
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: Props/Emits의 엄격한 계약(Contract) 정의를 통해 대규모 협업에서 어떻게 런타임 에러를 방지하고 IDE 지원을 향상시키는지 배울 수 있다 [27, 28].

Deeper Research Questions

Options API와 Composition API의 아키텍처적 차이는 무엇이며, 프로젝트의 규모, 팀의 경험, 컴포넌트 재사용성에 따라 이 둘을 어떻게 선택하거나 혼용해야 하는가?
ref()와 reactive()의 내부적인 반응성 추적(Reactivity Tracking) 메커니즘 차이는 무엇이며, 구조 분해 할당 시 발생하는 반응성 상실(Reactivity Loss)은 왜 일어나는가?
기존 Vue 2의 Mixins 패턴이 대규모 프로젝트에서 야기했던 네이밍 충돌과 암묵적 의존성 문제를 Composables 패턴은 어떤 구조적 원리로 해결하는가?
대규모 엔터프라이즈 환경에서 Composition API와 <script setup> 문법을 결합하여 사용할 때, 메모리 누수를 방지하고 번들 사이즈를 최적화하기 위한 모범 코딩 표준은 무엇인가?
로컬 상태를 관리하는 Composables와 애플리케이션 전역 상태를 관리하는 Pinia 스토어 사이의 경계와 역할은 어떻게 설계해야 하는가?

Practical Application Contexts

Implementation: <script setup> 블록을 활용하여 관련 있는 상태(ref), 계산된 속성(computed), 사이드 이펙트(watch)를 묶어서 응집력 있게 구현하며, 템플릿에 불필요한 래핑 없이 데이터를 바인딩한다.
System Design: 대규모 애플리케이션에서 '스마트(Container) 컴포넌트'와 '덤(Presentational) 컴포넌트' 패턴을 나눌 때, 복잡한 데이터 페칭 및 비즈니스 로직을 Composable 함수로 분리하여 스마트 컴포넌트에 주입하는 아키텍처를 설계한다.
Operation / Maintenance: 기능 단위로 코드가 묶여 있어 리팩토링 시 추적과 분리가 용이해지며(최대 30%의 리팩토링 시간 단축), 강력한 TypeScript 추론을 통해 다수 개발자가 협업하는 런타임 환경에서 코드의 무결성과 유지보수성을 크게 높일 수 있다.
Learning Path: ref와 reactive의 동작 원리를 이해하는 것을 시작으로, 기본적인 컴포넌트 내부 로직을 작성해 본 후 자주 사용되는 로직을 Composable 함수로 추출하고, 마지막으로 Pinia를 활용한 전역 상태 패턴을 학습하는 순서로 접근한다.
My Project Relevance: 프레임워크별 실전 아키텍처 패턴을 분석하는 데 있어, UI와 비즈니스 로직을 모듈화하고 프론트엔드의 상태 관리를 확장성 있게 가져가기 위한 핵심적인 구조적 전략으로 평가될 수 있다.

Adjacent Topics

React Hooks
- 확장 방향: Composition API의 철학적 영감이 된 React의 패턴으로, 양대 프레임워크가 상태 기반 로직의 재사용성이라는 과제를 어떻게 다르게 해석하고 해결했는지 패러다임 비교 학습을 진행할 수 있다.
Micro-frontends
- 확장 방향: 대규모 애플리케이션을 여러 독립적인 모듈로 분할하는 엔터프라이즈 아키텍처로, Composition API로 철저히 캡슐화된 컴포넌트들이 분산 환경에서 어떻게 일관성을 유지하는지 탐구할 수 있다.

Last updated: 2026-05-03

Raw Source: 00_Raw/2026-05-03/Composition API.md

🤖 LLM 활용 힌트 (How to Use This Knowledge)

언제 이 지식을 쓰는가:

(TODO)

언제 쓰면 안 되는가:

(TODO)

🧪 검증 상태 (Validation)

정보 상태: needs_review
출처 신뢰도: A
검토 이유: (P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)

🧬 중복 검사 (Duplicate Check)

기존 유사 문서: (TODO: 인덱서 클러스터 리포트 참조)
처리 방식: UPDATE (자동 정규화)
처리 이유: Phase 1 정규화 — 옛 템플릿/누락 필드 보강.

🕓 변경 이력 (Changelog)

날짜	변경 내용	처리 방식	신뢰도
2026-05-08	P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화)	UPDATE	A

💻 코드 패턴 (Code Patterns)

패턴 1: (TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)

# TODO

🤔 의사결정 기준 (Decision Criteria)

선택 A를 써야 할 때:

(TODO)

선택 B를 써야 할 때:

(TODO)

기본값:

(TODO)

❌ 안티패턴 (Anti-Patterns)

[안티패턴]: (TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)

11 KiB Raw Blame History