간단한 연동에는 SDK를 건너뛰세요
TMT소프트웨어를 만들다 보면 서드파티 SDK를 쓸지, HTTP 기반 API를 직접 호출할지 갈림길에 서는 일이 많습니다. 최근 𝕏에서 저는 후자를 선호한다고 밝혔는데, 꽤 활발한 대화로 이어졌습니다. 그래서 어떤 경우에는 SDK를 피하는 것이 오히려 이득이 되고 개발 과정을 단순하게 만들어 주는 이유를 자세히 살펴보려 합니다.
SDK의 단점
멘탈 모델 불일치
SDK에서 제일 불만스러운 점 하나는 SDK가 강요하는 멘탈 모델입니다. SDK는 API와의 상호작용을, 제가 문제에 자연스럽게 접근하는 방식과는 다른 틀로 짜 놓는 경우가 많습니다. 저는 함수를 호출하고, 결과를 받고, 캐시하고, 필요한 만큼 응답을 파싱하는 단순한 방식을 선호합니다. 투명하고 직관적이니까요. 반면 SDK를 쓰면 블랙박스를 다루게 되고, 내 코드와 외부 서버 사이의 연동 지점이 가려질 수 있습니다.
엄밀히 말하면 HTTP 엔드포인트를 호출하는 순간 이미 블랙박스 영역에 들어선 것이지만, SDK를 쓰면 그 블랙박스가 서비스의 서버에서 내 서버까지 뻗어 들어옵니다. 굳이 그럴 필요가 없다면 저는 그렇게 하고 싶지 않습니다.
숨겨진 복잡성
SDK는 문서를 파고들어야만 드러나는 복잡성을 숨기고 있을 수 있습니다. 전역 상태나 겉으로 잘 드러나지 않는 내부 메커니즘에 의존하기도 합니다. 전역 환경 변수를 참조하는 경우도 흔한데, 이 역시 문서를 찾아봐야 이해할 수 있습니다. 이런 불투명함은 애플리케이션의 혼란과 예기치 않은 동작으로 이어질 수 있습니다.
낡은 의존성
또 다른 문제는 SDK가 오래된 의존성에 기대는 경우가 있어서, 프로젝트에서 이미 쓰고 있는 라이브러리와 충돌할 수 있다는 점입니다. 시간이 지나며 변해 가는 전역 상태를 끌어들여 유지보수 부담을 키우기도 합니다. 게다가 SDK가 내가 쓰는 환경에 맞게 설계된 것이 아니라면 엄청난 혼란을 각오해야 합니다.
학습 부담
SDK를 쓴다는 것은 서버의 API뿐 아니라 SDK 자체의 API까지 배워야 한다는 뜻입니다. 불필요한 학습 곡선이 더해지고, 특히 간단한 연동을 다룰 때는 개발 속도가 느려질 수 있습니다.
API 직접 호출의 장점
오프라인 개발
저는 애플리케이션을 오프라인에서 개발할 수 있어야 한다고 강하게 믿는 편입니다. 개발 속도가 빨라지고, 테스트가 단순해지고, 복잡한 테스트 인프라 없이도 다양한 상황을 시뮬레이션할 수 있습니다. MSW(mock service worker) 같은 도구를 쓰면 제가 호출하는 API를 손쉽게 모킹할 수 있는데, SDK가 만들어 내는 호출을 어떻게 모킹할지 알아내는 것보다 훨씬 간단합니다.
타입 정보
SDK가 유용한 타입 정보를 제공한다고 주장하는 사람들도 있습니다. 하지만 REST 엔드포인트의 응답을 찾아보고 Zod 같은 도구로 직접 타입을 만드는 일은 그리 어렵지 않습니다. 간단한 경우라면 이 방식 때문에 별다른 어려움을 겪은 적이 없습니다.
교체 용이성
HTTP 엔드포인트를 직접 호출할 때가 본격적인 SDK를 쓸 때보다 벤더를 갈아타기 쉬운 경우가 많은데, 앞서 설명한 문제들이 큰 이유입니다. 직접 호출하는 HTTP 엔드포인트는 기존 코드를 훑어 가며 새 공급자로 옮길 때 흐름을 따라가기가 더 쉽습니다. SDK를 쓰고 있다면, 중요할 수도 있는 일들이 시야에서 완전히 가려진 채 벌어지고 있는 셈입니다.
SDK를 써야 할 때
이런 불만에도 불구하고, SDK가 제 몫을 하는 자리가 있다는 점은 인정합니다. 많은 엔드포인트와 상호작용해야 하는, 서비스와의 깊은 연동을 한다면 SDK가 엄청나게 도움이 될 수 있습니다. 지금 진행 중인 SaaS 프로젝트에서는 Twilio와 Stripe의 엔드포인트를 몇 개만 다루고 있어서 연동 파일이 아주 가볍습니다. 하지만 더 복잡한 연동이라면 주저 없이 SDK를 쓸 겁니다(사실 조금은 주저할지도 모르지만, 오래 가진 않을 겁니다. 저도 어른이니까요).
결론
SDK는 강력한 도구이고, 존재해 줘서 고맙기도 합니다. 하지만 간단한 API 연동에서는 불필요한 군더더기와 인지 부담을 불러올 수 있습니다. HTTP 엔드포인트와 직접 상호작용하면 코드베이스를 가볍게, 개발 과정을 민첩하게 유지할 수 있습니다. 소프트웨어의 모든 것이 도그마일 필요는 없고, 결국 판단의 문제라는 점을 기억하세요. 제 관점이 여러분의 프로젝트에서 더 나은 결정을 내리는 데 도움이 되길 바랍니다. 즐거운 코딩 되세요!