인터페이스 설계 멘탈 모델

// ❌ 아무렇게나 연결 <결제창 신한카드={{ 카드번호, 유효기간, CVC }} 토스페이={{ 토큰, 사용자키 }} 국민계좌={{ 계좌번호, 예금주 }} /> // → 결제창이 모든 결제수단의 내부 구조를 알아야 함 // → 네이버페이 추가되면? 또 구조 파악해서 추가해야 함 // ✓ 의도적으로 설계된 연결 <결제창 결제수단={토스페이} /> // → "결제수단"이라는 본질이 발견됨 // → 결제창은 결제수단의 내부를 몰라도 됨 // → 새 결제수단 추가해도 결제창은 변경 없음

// ❌ 변경 이유가 다른 것들이 섞여 있음 function CheckoutPage() { // 결제 로직 (결제팀이 바꿈) const processPayment = () => { ... } // 분석 로직 (마케팅팀이 바꿈) const trackPurchase = () => { ... } // UI 로직 (디자인팀이 바꿈) const renderButton = () => { ... } // 세 팀이 같은 파일을 건드림 → 충돌 }

// 결제창과 결제수단의 협력 <결제창 결제수단={토스페이} /> // 협력의 계약: // - 결제창: "나는 결제수단을 받아서 보여주고, 결제를 요청할 거야" // - 결제수단: "나는 pay()를 호출하면 결제를 처리할 거야" // - 서로의 내부는 모름. 계약만 지키면 됨.

onClose: () => void onSubmit: (data: FormData) => void onChange: (value: string) => void

children: ReactNode renderItem: (item: T) => ReactNode

variant: 'primary' | 'secondary' | 'danger' size: 'sm' | 'md' | 'lg'

// 내부에서 직접 구현, 외부에서 바꿀 수 없음 const DISCOUNT_RATE = 0.1

onClose: withFoo(domainFn) // ↑ ↑ ↑ // 구조 층 실제 로직 // 1. onClose — 함수가 들어오도록 허용하는 관절 // 2. withFoo — 층 (로깅, 분석, 에러 처리 등 관심사를 끼워넣음) // 3. domainFn — 실제 로직 (도메인의 일)

┌─────────────────────────────────┐ │ 상위 계층 (비즈니스 로직) │ │ - calc_total, gets_free_shipping │ ├─────────────────────────────────┤ ← 추상화 벽 │ 하위 계층 (데이터 구조) │ │ - add_item, remove_item │ └─────────────────────────────────┘

// ❌ 안에서 결정: PaymentForm이 saveOrder에 종속됨 function PaymentForm() { const handleSubmit = () => { saveOrder() // 뭘 할지 안에서 정해버림 } return <form onSubmit={handleSubmit}>...</form> } // ✓ 밖에서 결정하도록 위임 function PaymentForm({ onSubmit }) { return <form onSubmit={onSubmit}>...</form> } // 사용하는 쪽에서 결정 <PaymentForm onSubmit={saveOrder} /> <PaymentForm onSubmit={withAnalytics(saveOrder)} /> <PaymentForm onSubmit={mockSubmit} /> // 테스트용

// ❌ 안에서 내용물 결정: Card가 특정 내용에 종속됨 function Card() { return ( <div className="card"> <h2>고정된 제목</h2> <p>고정된 내용</p> </div> ) } // ✓ 밖에서 내용물 채움 function Card({ children }) { return <div className="card">{children}</div> } // 사용하는 쪽에서 결정 <Card> <UserProfile user={user} /> </Card> <Card> <PaymentSummary order={order} /> </Card>

function Dialog({ header, children, footer }) { return ( <div className="dialog"> <div className="dialog-header">{header}</div> <div className="dialog-body">{children}</div> <div className="dialog-footer">{footer}</div> </div> ) } <Dialog header={<h2>결제 확인</h2>} footer={<Button onClick={confirm}>확인</Button>} > 정말 결제하시겠습니까? </Dialog>

// ❌ 하드코딩: 변형마다 컴포넌트를 만들어야 함 function PrimaryButton() { return <button className="btn-primary">...</button> } function DangerButton() { return <button className="btn-danger">...</button> } // ✓ 설정으로 선택지 제공 function Button({ variant = 'primary', size = 'md' }) { return <button className={`btn-${variant} btn-${size}`}>...</button> } // 타입으로 선택지를 명시 type ButtonProps = { variant: 'primary' | 'secondary' | 'danger' size: 'sm' | 'md' | 'lg' }

// ❌ 모든 걸 하나에: props가 폭발함 <MegaForm hasHeader={true} headerTitle="결제" hasFooter={true} footerButtons={['cancel', 'submit']} hasValidation={true} validationRules={rules} hasProgress={true} currentStep={2} /> // ✓ 조립: 필요한 것만 조합 <Form> <Form.Header> <h2>결제</h2> <ProgressBar current={2} total={3} /> </Form.Header> <Form.Body> <PaymentFields /> </Form.Body> <Form.Footer> <Button variant="secondary" onClick={cancel}>취소</Button> <Button variant="primary" type="submit">결제</Button> </Form.Footer> </Form>

// Form이 하위 컴포넌트들을 네임스페이스로 제공 const Form = ({ children }) => <form>{children}</form> Form.Header = ({ children }) => <div className="form-header">{children}</div> Form.Body = ({ children }) => <div className="form-body">{children}</div> Form.Footer = ({ children }) => <div className="form-footer">{children}</div>

// API 응답 형태 (백엔드가 정한 것) type ApiUser = { user_name: string user_age: number created_at: string } // 컴포넌트가 기대하는 형태 (프론트엔드가 정한 것) type User = { name: string age: number joinedAt: Date } // ❌ 컴포넌트 안에서 변환: 컴포넌트가 API 형태를 알아야 함 function UserCard({ apiUser }: { apiUser: ApiUser }) { const name = apiUser.user_name // API 형태에 종속 const age = apiUser.user_age // ... } // ✓ 어댑터로 경계에서 변환 const toUser = (apiUser: ApiUser): User => ({ name: apiUser.user_name, age: apiUser.user_age, joinedAt: new Date(apiUser.created_at) }) function UserCard({ user }: { user: User }) { // API 형태 모름, User 형태만 앎 } // 사용 <UserCard user={toUser(apiResponse)} />

"디자인 보니까 가운데는 월을 표시하고, 좌우 화살표로 월을 선택할 수 있어야 하는구나." → 본질: "범위 내에서 값을 선택하는 것"

Input? Modal? Slider? Calendar? Form? Selector? → "월을 선택하는 거니까 input[type='date']랑 비슷하네"

// input[type='date']의 인터페이스 <input type="date" value={value} onChange={onChange} min={min} max={max} /> // 그대로 차용 <MonthSelector value={currentMonth} onChange={setCurrentMonth} min={MIN_MONTH} max={MAX_MONTH} />

// ❌ 구현이 인터페이스를 결정함: props가 데이터의 통로로 전락 interface Props { selectedMonth: number; currentMonth: number; selectMonth: (month: number) => void; // 내부에서 쓰는 걸 그대로 뚫음. 본질이 안 보임. } // ✓ 인터페이스가 구현을 결정함: props가 본질을 드러냄 interface Props { value: number; onChange: (value: number) => void; min?: number; max?: number; // "범위 내에서 값을 선택"이라는 본질이 보임. }

// ❌ Before: props가 데이터의 통로로 전락함 <NavigationSection selectedMonth={selectedMonth} currentMonth={currentMonth} selectMonth={selectMonth} /> // → 세 개가 따로 논다. 관계가 인터페이스에 안 드러남. // → 구현이 인터페이스를 결정함. 내부에서 쓰는 걸 그대로 뚫음. // ✓ After: 본질이 인터페이스에 드러남 <MonthSelector value={selectedMonth} onChange={setSelectedMonth} min={1} max={currentMonth} /> // → "범위 내에서 값을 선택"이라는 본질이 보임. // → input[type='date']처럼 익숙함.

Actions: open/close, show/hide, enable/disable, select/deselect States: loading/success/error, active/inactive, valid/invalid Events: onChange, onSubmit, onCancel, onComplete, onSelect Values: value, defaultValue, checked, selected, disabled

// ❌ 불필요한 관절들 <MonthSelector currentMonth={currentMonth} setCurrentMonth={setCurrentMonth} goPrevMonth={goPrevMonth} // 내부에서 처리 가능 goNextMonth={goNextMonth} // 내부에서 처리 가능 isError={isError} // 여기서 안 씀 data={data} // 여기서 안 씀 /> // ✓ 필요한 관절만 (input[type=date] 차용) <MonthSelector value={currentMonth} onChange={setCurrentMonth} min={MIN_MONTH} max={MAX_MONTH} />

// ❌ 약속보다 적게 함: 이름이 과장 const getOrderSummary = (order) => order.items.length // "summary"라면서 개수만 반환함 // ❌ 약속보다 많이 함: 이름에 없는 일을 함 const formatPrice = (price) => { trackPriceView(price) // 이름에 없는 분석 호출 return `${price.toLocaleString()}원` } // ✓ 약속대로 함: 놀람 없음 const formatPrice = (price) => `${price.toLocaleString()}원`

// 🦾 망치손을 붙임: 파생값을 전부 인터페이스에 박음 const useOrderStore = create((set, get) => ({ order: null, // 파생값들이 인터페이스에 덕지덕지 getTotalPrice: () => get().order?.items.reduce(...), getDiscountedPrice: () => ..., getItemCount: () => ..., getFormattedPrice: () => ..., getShippingFee: () => ..., // 새 요구사항 올 때마다 여기에 추가됨 })) // 🔨 망치를 쥐어줌: 기본값만 내보내고, 파생은 사용처에서 const useOrderStore = create(() => ({ order: null, })) // 사용처에서 순수함수로 파생 const order = useOrderStore(state => state.order) const totalPrice = calculateTotal(order) const discountedPrice = applyDiscount(totalPrice, rate)

// 이 컴포넌트를 누가 쓰나? // 1. 같은 팀 개발자가 쓴다면 // → 내부 사정을 알아도 됨, 변경 시 같이 고치면 됨 // → 인터페이스가 좀 거칠어도 괜찮음 // 2. 다른 팀이 쓴다면 // → 내부를 몰라야 함, 변경 시 깨지면 안 됨 // → 추상화 벽이 필요함 // 3. 외부 사용자(라이브러리)가 쓴다면 // → 버전 관리, 하위 호환성 필수 // → 인터페이스 변경 = breaking change

// ❌ 구현 방식(동기/비동기)으로 인터페이스를 나눔 const form = useForm({ validate: { email: isEmail, // 동기 검증 }, validateOnServer: { email: checkDuplicate, // 비동기 검증 }, }) // 호출자가 "이건 동기, 이건 비동기"를 알아야 함 // ✓ What만 표현: 검증 규칙만 선언 const form = useForm({ validate: { email: [isEmail, checkDuplicate], // 뭘로 검증할지만 }, }) // 동기/비동기는 내부에서 알아서 처리