Antigravity Agent
3.1 KiB
3.1 KiB
Explicit Contracts
📌 Brief Summary
명시적 계약(Explicit Contracts)은 재사용 가능한 React 컴포넌트를 설계할 때 지켜야 할 주요 원칙 중 하나로, 컴포넌트의 명확한 API를 정의하는 것을 의미합니다 [1]. 이는 컴포넌트가 입력으로 받는 것(props), 반환하는 것(이벤트/콜백), 그리고 절대 하지 말아야 할 행동(예: 부모 상태의 직접 변형)을 명시적으로 규정하는 것입니다 [1]. 이러한 강력한 계약은 애플리케이션 내에서 예기치 않은 동작을 방지하고 컴포넌트의 예측 가능성과 재사용성을 높이는 역할을 합니다 [1, 2].
📖 Core Content
- 컴포넌트 설계의 핵심 규칙: 명시적 계약은 단일 책임(Single Responsibility), 상속보다 합성(Composition Over Inheritance), 접근성 우선(Accessibility First)과 함께 재사용 가능한 React 컴포넌트를 구축하기 위한 4가지 황금 법칙 중 하나로 강조됩니다 [1].
- 명확한 API 설계 (Props & Events):
- Props (프로퍼티): 컴포넌트의 API는 오용하기 어렵게 직관적으로 설계되어야 합니다. 구현 방식이 아닌 의도(intent)를 설명하는 용어로 프로퍼티를 명명해야 합니다(예:
showModalNow대신isOpen사용). 또한, 프로퍼티의 개수를 최소화하고 안전한 기본값을 제공하는 것이 좋습니다 [2]. - Events (이벤트): 이벤트 역시 계약의 일부입니다. 컴포넌트가 외부로 상태를 전달해야 할 때(예: '사용자가 확인을 클릭함'), 잘 명명된 콜백을 사용하고 항상 일관되고 유용한 데이터를 페이로드로 전달해야 합니다 [2].
- Props (프로퍼티): 컴포넌트의 API는 오용하기 어렵게 직관적으로 설계되어야 합니다. 구현 방식이 아닌 의도(intent)를 설명하는 용어로 프로퍼티를 명명해야 합니다(예:
- 상태의 경계와 성능: 명확한 계약은 제어 컴포넌트(Controlled)와 비제어 컴포넌트(Uncontrolled)의 상태 소유권(state ownership)을 분명히 설정합니다 [2]. 명확하게 정의된 계약은 우발적인 리렌더링의 위험을 낮추기 때문에 성능 향상의 출발점이 되기도 합니다 [3].
- 대규모 프론트엔드 아키텍처에서의 명시적 계약:
- 모노레포(Monorepo)와 같이 확장 가능한 아키텍처에서 모듈 간의 의존성은 명시적 계약을 통해 한 방향으로만 흘러야 합니다 [4].
- 기능 분할 설계(Feature-Sliced Design, FSD)에서도 슬라이스 경계마다 명시적인 공개 API(Public API)를 강제합니다. 이를 통해 내부 파일의 딥 임포트(deep import)를 막고 우발적인 결합(accidental coupling)을 크게 줄일 수 있습니다 [5, 6].
🔗 Knowledge Connections
- Related Topics: Reusable UI Components, Component API Design, Feature-Sliced Design
- Projects/Contexts: React Component Architecture, Monorepo Architecture
- Contradictions/Notes: 소스에 명시적 계약의 개념이 컴포넌트 수준의 설계 원칙뿐만 아니라, 대규모 모노레포 환경에서의 패키지 간 의존성을 관리하는 아키텍처 원칙으로도 일관되게 적용됨을 보여줍니다 [1, 4].
Last updated: 2026-04-26