핵심요약
토스페이먼츠는 결제 연동의 복잡성을 해결하고 개발자 경험을 향상시키기 위해 V1 SDK의 한계를 넘어 안정성, 확장성, 명확성을 강화한 V2 SDK를 성공적으로 구축했습니다. V2 SDK는 예측 불가능한 운영 문제 해결, 다양한 가맹점 요구사항 수용, 그리고 개발자 친화적인 연동 경험 제공을 목표로 설계되었습니다.
토스페이먼츠 V2 SDK: 안정성, 확장성, 명확성으로 재탄생한 결제 경험
결제 SDK 개발의 특수성과 V1의 한계
- 결제 SDK 개발은 일반적인 프론트엔드 개발과 달리 가맹점 환경에 깊숙이 연동되며 런타임 환경에 따라 예측 불가능한 문제가 발생했습니다.
- V1 SDK는 로그 추가로 인한 성능 저하 및 타입 오류 (
startsWith is not a function) 같은 문제로 안정성이 부족했습니다. - 가맹점의 다양한 요구사항을 수용할 확장성 있는 소프트웨어 구조가 미비했고, API 사용 경험의 명확성 또한 부족했습니다.
V2 SDK의 핵심 가치와 안정성 확보 전략
- V2 SDK는 기존의 '쉬운 연동'을 넘어 안정성, 확장성, 명확성을 핵심 가치로 설정했습니다.
- 안정성을 위해 300개 이상의 단위 테스트와 500개 이상의 E2E 통합 테스트를 확보했습니다.
- Global Trace ID를 활용하여 모니터링 CLI를 구축, 결제 실패 패턴을 빠르게 탐지하고 회복 탄력성을 강화했습니다.
- ElasticSearch 기반 대시보드와 얼럿 시스템을 통해 문제 상황을 즉시 감지할 수 있도록 했습니다.
확장성 높은 아키텍처 및 모듈화 전략
if문 남발로 인한 복잡성 증가 문제를 해결하기 위해 조립 가능한 SDK 개념을 도입했습니다.- Public Interface Layer, Domain Layer, External Service Layer의 3계층 아키텍처로 책임 분리 및 의존성 역전 원칙을 적용했습니다.
- 각 레이어는 인터페이스를 통해 통신하며, 특정 가맹점의 커스텀 요구사항은 새로운 도메인 코드 블록으로 격리하여 표준 SDK의 오염 없이 확장성을 확보했습니다.
명확성을 위한 인터페이스 계약화 및 개발 경험 향상
- SDK 인터페이스를 단순한 함수가 아닌 **'계약'**으로 간주하고, Typescript 및 JSDoc을 활용하여 명세를 강화했습니다.
- Git을 계약서이자 히스토리북으로 활용하여 변경 이력 추적의 단일 신뢰 지점을 만들었습니다.
- Typescript 기반 계약을 통해 자동으로 연동 문서를 생성하고, zod schema를 이용한 런타임 유효성 검증으로 개발자에게 빠른 피드백을 제공했습니다.
