쓰기 쉬운 Toss Front SDK
Summary
실수하고 싶어도 못 하는 SDK? 토스가 알려주는 ‘의도 중심’ 인터페이스 설계법
단순한 기능 나열을 넘어, 퍼사드 패턴으로 개발자 경험(DX)과 시스템 안정성을 모두 잡는 전략
토스플레이스의 결제 단말기 ‘프론트’ SDK를 개발하며 고민한 ‘쓰기 쉬운 인터페이스’에 대한 인사이트를 담고 있습니다. 복잡한 로직을 퍼사드 패턴으로 감싸 사용자의 의도에 맞게 API를 재설계하고, 리소스 관리 책임을 SDK가 부담하여 구조적으로 에러를 방지하는 실전 노하우를 공유합니다.
- 01좋은 SDK는 사용자가 올바른 방법으로만 사용하도록 유도하여 휴먼 에러를 원천 차단합니다.
- 02퍼사드 패턴의 본질은 기능 은닉이 아니라 ‘사용자의 의도(Intent)’에 따른 API 재구성입니다.
- 0380%의 공통 유즈케이스는 고수준 API로, 20%의 특수 사례는 저수준 탈출구로 대응하는 파레토 법칙을 적용합니다.
- 04‘리소스를 만든 곳에서 닫는다’는 SRP 원칙을 준수하여 메모리 누수를 방지합니다.
- 05고수준 추상화는 내부 구현이 바뀌어도 사용자 코드를 보호하는 하위 호환성의 방패가 됩니다.
RECOMMENDATION
라이브러리나 SDK를 개발하는 엔지니어뿐만 아니라, 사내 공통 모듈을 설계하는 개발자에게 강력히 추천합니다. 문서 가이드로 사용법을 설명하기보다 인터페이스 자체에 안전장치를 설계하고 싶은 분들에게 실질적인 도움이 될 것입니다.
The Problem
외부 연동사가 SDK를 사용할 때 메서드 호출 순서나 리소스 정리(Cleanup) 책임을 직접 관리해야 하는 경우, 인지 부하가 증가하고 메모리 누수나 이벤트 리스너 누수와 같은 휴먼 에러가 발생하기 쉽습니다. 이는 결과적으로 플랫폼의 안정성을 저해하고 연동사의 개발 경험을 악화시키는 요인이 됩니다.
The Solution
복잡한 내부 구현을 사용자의 의도 기반으로 재구성하는 퍼사드(Facade) 패턴을 도입하여 고수준(High-level) 인터페이스를 제공하고, 리소스 관리 책임을 SDK 내부로 은닉화했습니다. 동시에 특수한 유즈케이스를 위해 저수준(Low-level) 인터페이스에 접근할 수 있는 탈출구(Escape Hatch)를 마련하여 편의성과 유연성의 균형을 잡았습니다.
The Result
리소스 생성과 소멸의 책임을 SDK가 직접 가져가는 구조적 개선을 통해 사용자의 실수로 인한 리소스 누수를 방지하고 SDK의 안정성을 확보했습니다. 또한 고수준 API를 통해 80%의 공통 유즈케이스를 단순화함으로써 개발자 경험(DX)을 향상시키고 내부 로직 변경 시에도 사용자 코드를 보호할 수 있는 확장성을 얻었습니다.
Trade-off
추상화 수준을 높일수록 특정 연결만 유지하는 등의 세밀한 제어가 어려워질 수 있으며, SDK 개발자가 내부에서 오케스트레이션 로직을 더 정교하게 관리해야 하므로 유지보수 비용이 증가할 수 있습니다. 본문에서는 이를 해결하기 위해 저수준 인터페이스를 함께 제공하는 방식을 대안으로 제시하고 있습니다.
Key Concepts
More from 토스
View all posts from 토스
누군가는 토스를 테스트하는 동안, 우리는 테스트하는 법을 만듭니다.
QA EngineeringTest AutomationAI in Testing2주 전
es-toolkit: How a Small Internal Library Became a Global Project
JavaScriptTypeScriptTree-shaking2주 전6. 도구를 넘어, 기준과 책임으로
Technical WritingAI AutomationKnowledge Governance2주 전5. Technical Writer, 사라질 결심
LLMGitHub ActionsGenerative AI2주 전es-toolkit, 사내 작은 라이브러리가 전세계적인 라이브러리가 되기까지
JavaScriptTypeScriptTree-shaking3주 전
