3.5 KiB
3.5 KiB
Public APIs
📌 Brief Summary
프론트엔드 아키텍처 및 컴포넌트 라이브러리 설계에서 퍼블릭 API(Public APIs)는 컴포넌트나 패키지가 외부와 상호작용하기 위해 노출하는 명시적인 계약이자 안정적인 진입점(entry point)을 의미합니다 [1, 2]. 이는 컴포넌트가 받는 속성(props)과 반환하는 이벤트(callbacks)를 정의하며, 내부 구현 세부 사항을 캡슐화합니다 [2]. 명확한 퍼블릭 API를 강제하는 것은 패키지 간의 무분별한 참조를 방지하고, 변화하는 요구사항 속에서도 안전하게 확장 가능한 UI를 구축하는 데 필수적입니다 [3, 4].
📖 Core Content
- 컴포넌트 API 설계의 중요성: 재사용 가능한 UI를 구축하는 것은 단순히 코드를 적게 작성하는 것이 아니라, 지속적인 변화에서 살아남을 수 있는 API를 설계하는 것입니다 [3]. 좋은 컴포넌트 API는 직관적이고 오용하기 어려워야 하며, 최소한의 속성(props)만 노출해야 합니다 [5]. 이는 컴포넌트가 무엇을 받아들이고, 무엇을 반환하며, 절대 하지 말아야 할 행동(예: 부모 상태 변이)을 규정하는 명시적 계약(Explicit Contracts) 역할을 수행합니다 [2].
- 모노레포와 패키지 경계 관리: 대규모 모노레포 환경에서는 모듈성 유지를 위해 엄격한 퍼블릭 API 노출이 필요합니다 [1, 4]. 소비자는 내부의 깊은 경로(예:
import Button from "@acme/ui/src/button/Button")가 아닌, 의도적으로 노출된 안정적인 진입점(예:import { Button } from "@acme/ui")을 통해서만 모듈을 가져와야 합니다 [4]. 이를 강제하기 위해 패키지의package.json에서exports필드를 정의하거나 ESLint 규칙을 적용하여 딥 임포트(deep imports)를 차단해야 합니다 [4, 6]. - FSD(Feature-Sliced Design)와의 통합: 확장 가능한 프론트엔드 아키텍처 방법론인 FSD는 슬라이스(slice) 경계에서 명시적인 퍼블릭 API 사용을 권장합니다 [7]. 애플리케이션은 공유 패키지나 슬라이스의
index.ts같은 퍼블릭 API 파일을 통해서만 임포트하고, 내부 파일은 철저히 내부에 유지되도록 설계함으로써 의도치 않은 결합(accidental coupling)을 크게 줄일 수 있습니다 [7, 8]. - 거버넌스 및 브레이킹 체인지 방지: 여러 앱에서 사용되는 공유 패키지(예:
packages/ui)의 퍼블릭 API가 변경될 경우 파급 효과가 크므로, 예측 불가능한 시스템 중단을 막기 위해 엄격한 관리가 필요합니다 [9, 10].CODEOWNERS등을 이용해 소유권을 명확히 하고, 공유 모듈의 퍼블릭 API에 변경 사항이 있을 때는 반드시 코드 리뷰를 요구하는 정책을 수립해야 합니다 [9, 10].
🔗 Knowledge Connections
- Related Topics: Component API Design, Monorepo Architecture, Feature-Sliced Design (FSD), Explicit Contracts
- Projects/Contexts: 대규모 리액트 애플리케이션의 모노레포 구축(Nx/Turborepo), 확장 가능하고 유지보수 용이한 재사용 UI 컴포넌트 라이브러리 설계
- Contradictions/Notes: 컴포넌트 내부의 복잡성은 숨기고 외부로는 단순하고 일관된 진입점을 제공해야 한다는 원칙은, 단일 컴포넌트 설계와 대규모 패키지 구조 설계 양쪽 모두에 공통적으로 핵심적인 지침으로 강조됩니다 [2, 4].
Last updated: 2026-04-26