100년 가는 프론트엔드 코드, SDK

결제 SDK는 가맹점의 코드와 다양한 브라우저·웹뷰 환경에서 실행되므로, 로그 추가만으로도 결제가 느려지거나 예상 밖의 입력값에서 오류가 나는 등 일반 프론트엔드와 다른 운영 문제가 발생했습니다. 토스페이먼츠는 V1의 한계를 개선하기 위해 안정성·확장성·명확성을 핵심 가치로 삼고, 단위·E2E 테스트와 ElasticSearch 대시보드, global trace ID 기반 모니터링 CLI를 마련했습니다. 가맹점별 요구사항은 if문으로 쌓는 대신 Public Interface, Domain, External Service 계층으로 나누고 인터페이스를 통해 의존성을 주입해 표준 구현과 커스텀 구현을 조립하도록 설계했습니다. 또한 TypeScript 타입과 JSDoc을 공개 계약으로 분리해 Git에서 변경 이력을 관리하고 CI로 문서를 자동 생성함으로써, 장기간 유지되는 SDK의 안정성과 연동 명확성을 높이는 방법을 제시합니다.

• SDK에 로그를 추가할 때는 호출 빈도와 네트워크 의존성이 가맹점 결제 흐름에 미칠 영향을 고려해야 합니다.
• 테스트만으로 포착하기 어려운 운영 환경의 문제는 trace ID와 가맹점·런타임별 모니터링으로 탐지할 수 있습니다.
• 가맹점별 예외를 핵심 로직의 분기문으로 누적하기보다 교체 가능한 작은 구현 단위로 분리하면 변경 영향을 줄일 수 있습니다.
• 공개 인터페이스를 타입과 JSDoc으로 계약화하고 Git 변경 이력을 관리하면 약속의 의도와 변경 과정을 추적하기 쉽습니다.
• 계약에서 문서를 자동 생성하고 CI에 연결하면 코드와 연동 문서의 불일치를 줄일 수 있습니다.