쓰기 쉬운 Toss Front SDK

Context

외부 SDK 가이드는 단순 예시 코드만 제공할 경우 연동사가 콜백 등록 누락, 이벤트 리스너 해제 누락, 메모리 누수 등 구조적 실수를 범할 수 있다. 이러한 휴먼 에러는 SDK 플랫폼의 안정성 문제로 직결되므로 인터페이스 설계 단계에서 사전 방지 필요했다.

Technical Solution

• Facade 패턴으로 고수준(High-level) 인터페이스 제공: start() 메서드 하나로 서버 오픈, 연결별 리스너 등록, 자동 오케스트레이션을 통합 처리
• 저수준(Low-level) 인터페이스와 공존: open(), close(), send(), listen 계열 메서드를 병행 제공해 특수 케이스(20%)에 대한 탈출구(Escape Hatch) 확보
• 자동화된 정리 책임 구조: stop() 메서드 호출 시 Map 기반 리스너 추적으로 모든 connection별 unlisten 동작 자동 수행
• 단일 책임 원칙(SRP) 적용: "리소스를 만든 곳에서 닫는다" 원칙으로 connection 생성과 정리 책임을 SDK 내부에 집중
• 의도 기반 API 설계: AWS CDK의 L2 레벨처럼 사용자가 "서버를 시작한다", "파일을 업로드한다"는 자연스러운 목적만 표현

Key Takeaway

SDK 품질은 제공하는 기능의 개수보다 사용자가 그 기능을 어떤 형태로 사용하게 되느냐에 따라 결정되므로, Facade 패턴으로 80% 공통 유즈케이스를 단순화하고 저수준 API로 20% 특수 케이스를 지원하는 이층 구조가 DX 개선, 성능 안정성 확보, Breaking Change 방지를 동시에 가능하게 한다.