Composition API

📌 Brief Summary

Vue 3의 Composition API는 작고 독립적인 단위로 애플리케이션의 복잡한 로직을 구성할 수 있게 해주는 API 모음이다. 기존 Options API가 데이터나 메서드 등 옵션 타입별로 코드를 분리했던 것과 달리, 기능적 논리 단위별로 관련된 코드를 그룹화할 수 있게 해준다. 이를 통해 상태 저장 로직(Stateful logic)을 캡슐화하고 재사용하는 '컴포저블(Composable)' 패턴을 구현하여, 대규모이거나 빠르게 성장하는 애플리케이션에서 높은 유지보수성과 확장성을 제공한다.

📖 Core Content

로직의 캡슐화와 재사용 (Composables 패턴) Composition API를 활용하면 상태 기반 로직을 '컴포저블'이라는 독립적이고 재사용 가능한 함수로 추출할 수 있다. 마우스 위치 추적, 비동기 데이터 패칭(useFetch), 윈도우 크기 조정 등 시간에 따라 변하는 상태를 관리하는 로직을 여러 컴포넌트 간에 충돌 없이 공유할 수 있다. 과거 Options API에서 사용하던 Mixins의 한계(네임스페이스 충돌, 암묵적 의존성)를 완벽히 해결한다.
기능 중심의 코드 구조화 기존 Options API에서는 특정 기능과 관련된 로직이 data(), methods(), created() 등으로 흩어져 있어 컴포넌트가 거대해질수록 파악하기 어려웠다. Composition API는 단일 기능과 관련된 모든 로직을 한 곳에 모을 수 있어 가독성을 높이고 디버깅 및 코드 추출을 용이하게 한다.
TypeScript와의 강력한 통합 Composition API는 네이티브 수준의 TypeScript 지원을 제공한다. 기존 방식보다 보일러플레이트 코드가 적고, 변수나 함수에 대한 강력한 타입 추론과 제네릭 지원을 통해 훨씬 안정적인 개발자 경험(DX)을 선사한다.
컴포저블 작성 베스트 프랙티스
- 명명 규칙: 컴포저블 함수명은 use로 시작해야 한다 (예: useMouse).
- 입력 매개변수 유연성: 일반 값뿐만 아니라 ref나 getter 함수도 입력받을 수 있도록 설계하며, 내부에서 toValue()를 사용해 처리하는 것이 권장된다.
- 반환 값 처리: 반환 객체를 구조 분해 할당(Destructuring)할 때 반응성을 잃지 않도록, reactive 객체가 아닌 여러 개의 ref를 포함하는 일반(plain) 객체를 반환해야 한다.
- 부수 효과(Side Effects) 관리: <script setup> 또는 setup() 내부에서 동기적으로 호출해야 하며, onMounted()에서 DOM 이벤트 리스너 등을 등록하고 onUnmounted()에서 반드시 정리(Clean-up)해야 한다.
현대 Vue 생태계의 표준 Nuxt 3, Pinia, Vue Router 4, VueUse 등 최신 Vue 생태계의 핵심 도구들은 Composition API를 기본 전제로 설계되어 있어 원활한 통합을 제공한다.

⚖️ Trade-offs & Caveats

자유도에 따른 파편화 위험: 코드를 조직하는 방식에 대한 강제성이 적다. 따라서 팀 내에 엄격한 컨벤션(예: ESLint 규칙, 명명 규칙, 계층화된 디렉토리 구조)이 없다면, 개발자마다 다른 방식으로 로직을 구현하여 코드가 혼란스러워질 수 있다. 너무 많은 로직을 setup() 내부에 방치하면 오히려 유지보수가 어려워진다.
반응성(Reactivity) 객체의 함정: 초보자의 경우 ref()와 reactive()의 사용 기준에 혼란을 겪기 쉽다. 특히, 반응형 객체의 프로퍼티를 일반적인 방식으로 구조 분해 할당하면 반응성이 끊어지므로 toRefs()나 storeToRefs()를 반드시 사용해야 하며, ref에 접근할 때 .value를 붙이는 것을 잊는 실수가 잦다.
러닝 커브 상승: Options API가 초보자 친화적이었던 반면, Composition API는 JavaScript의 클로저(Closures), 반응성 동작 원리, 함수 스코프에 대한 깊은 이해를 요구한다. 따라서 주니어 개발자 위주의 팀이나 구조가 단순한 프로젝트에서는 오히려 생산성을 저하시킬 수 있다.
기존 Options API와의 혼용 제약: 컴포저블은 setup() 내부에서만 완벽히 동작한다. 기존 Options API 기반의 컴포넌트(data(), created() 등)에서 VueUse나 Pinia 같은 최신 도구를 사용하려면 중복된 상태를 만들거나 부자연스러운 연결(glue) 코드를 작성해야 하는 하이브리드 상태의 고통(Hybrid Pain)이 따른다.

🔗 Knowledge Connections

[아키텍처/기반 기술]

Composables
- 연결 이유: Composition API를 활용해 상태 유지 로직을 캡슐화하는 핵심 소프트웨어 설계 패턴이다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 상태를 가지는 로직과 순수 함수의 분리, 단일 책임 원칙에 기반한 프론트엔드 모듈화 전략.
Options API
- 연결 이유: Composition API가 대체하거나 보완하고자 하는 이전 Vue의 기본 문법이자 비교 대상이다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 프레임워크의 진화 과정, 소규모 프로젝트와 대규모 프로젝트에 각각 적합한 API 선택 기준 및 점진적 마이그레이션(Migration) 전략.
React Hooks
- 연결 이유: Composition API의 설계에 큰 영감을 준 React의 논리 합성 패턴이다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 상태 변경 시 전체가 재실행(Re-render)되는 React Hooks와, setup()에서 한 번만 실행되며 프록시(Proxy) 기반으로 추적하는 Vue의 실행 모델(Execution Model) 차이.

[구현/활용 도구]

Pinia
- 연결 이유: Composition API를 기반으로 설계된 Vue 3의 공식 상태 관리 라이브러리로, Vuex를 대체한다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 컴포저블 스토어 패턴을 통한 전역 상태 관리 및 Mutations 없이 상태를 다루는 현대적인 상태 정규화(Normalization) 기법.
VueUse
- 연결 이유: Composition API를 활용해 200개 이상의 유틸리티를 구현한 오픈소스 컴포저블 컬렉션이다.
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 브라우저 API, 센서, 상태 동기화 등을 추상화하는 실전 컴포저블 구현 모범 사례.

Deeper Research Questions

Composition API의 프록시(Proxied refs) 기반 반응성 모델은 React Hooks의 실행 모델과 비교하여 렌더링 최적화 측면에서 어떤 근본적인 차이를 만들어내는가?
대규모 엔터프라이즈 환경에서 Composition API로 로직을 캡슐화할 때, 도메인 주도 설계(DDD) 관점에서 기능 중심 모듈화(Feature-based architecture)를 어떻게 설계할 수 있는가?
상태 저장 로직을 재사용하고자 할 때, 렌더리스 컴포넌트(Renderless Components) 패턴과 컴포저블(Composables) 패턴 중 인스턴스 오버헤드와 UI 렌더링 제어권 측면에서 어느 것을 선택해야 하는가?
기존 Options API로 작성된 거대한 레거시 컴포넌트를 Composition API로 점진적으로 리팩토링할 때(Hybrid 상태), 부작용과 코드 중복을 최소화하는 전략은 무엇인가?
대규모 리스트나 복잡한 상태 트리를 다룰 때, 반응성 오버헤드를 줄이기 위해 shallowRef나 v-memo와 같은 고급 최적화 기법을 어떻게 적용해야 하는가?

Practical Application Contexts

Implementation: 비동기 데이터 로딩(useFetch), 윈도우 사이즈 추적(useWindowSize), 모달 상태 관리 등 여러 UI 컴포넌트에서 반복되는 로직을 단일 함수로 분리하여 작성할 때 구현된다.
System Design: 컴포넌트 트리를 구성할 때, UI 레이어(Template)와 비즈니스 로직 레이어(Composable)를 명확히 격리하여 각 컴포넌트가 프레젠테이셔널(Presentational) 역할을 수행하도록 돕는 기반 구조로 작동한다.
Operation / Maintenance: 관련된 로직이 단일 함수로 응집되므로, UI 렌더링 환경 없이도 비즈니스 로직만 별도로 단위 테스트(Unit Testing)하기 쉬워져 유지보수성이 대폭 향상된다.
Learning Path: Vue의 기초 문법을 익힌 뒤, ref와 reactive의 동작 원리인 반응성 시스템을 공부하고, VueUse 라이브러리의 소스 코드를 읽으며 우수한 컴포저블 작성 컨벤션을 학습하는 경로로 이어진다.
My Project Relevance: 컴포넌트의 크기가 비대해져 코드 파악이 어렵거나(Giant Component 현상), 동일한 상태 관리 로직을 여러 뷰(View)에서 복사-붙여넣기로 사용하고 있는 경우 이를 리팩토링하는 핵심 솔루션이 될 수 있다.

Adjacent Topics

Renderless Components
- 확장 방향: 자체 템플릿(Markup)을 가지지 않고 상태와 로직만 하위 스코프 슬롯(Scoped Slots)으로 전달하는 또 다른 뷰 로직 재사용 패턴으로, Composition API의 대안적 접근법을 이해할 수 있다.
Vue 3 Reactivity System
- 확장 방향: 프록시(Proxy) 기반으로 작동하는 ref, reactive, watchEffect의 내부 원리와 의존성 추적(Dependency tracking) 메커니즘을 심도 있게 탐구할 수 있다.

Last updated: 2026-05-02

9.6 KiB Raw Blame History