몇 년 전 한 동료가 농담처럼 던진 말이 아직도 기억난다. “REST API는 말을 너무 많이 해. 그래프QL은 필요한 것만 딱 말해줘.” 당시에는 그 말이 참 와닿았다. 클라이언트가 원하는 데이터만 정확히 가져올 수 있다는 점, 오버페칭이나 언더페칭의 고민에서 벗어날 수 있다는 점에서 그래프QL은 마치 맞춤 양복을 입은 것처럼 느껴졌다. 하지만 시간이 지나면서 그 ‘필요한 것만’이라는 장점이 때로는 독이 될 수도 있다는 생각이 들었다. 특히 오류 처리라는 측면에서 그래프QL은 마치 말을 아끼는 사람처럼, 중요한 이야기를 숨기고 있는 건 아닌지 의문이 들기 시작했다.
그래프QL의 기본 응답 코드가 이제 HTTP 500으로 변경된다는 소식은 이런 맥락에서 꽤 의미심장하다. 이전까지 그래프QL은 성공적인 쿼리든, 부분적인 오류든, 심지어 서버 내부에서 문제가 발생하든 간에 항상 HTTP 200을 반환했다. 클라이언트는 응답 본문을 뜯어봐야만 실제로 무슨 일이 일어났는지 알 수 있었다. 이는 마치 식당에서 주문을 했는데, 종업원이 아무 말 없이 접시를 내미는 것과 같았다. 음식이 반만 차려져 있거나, 심지어 상한 음식이 섞여 있더라도 말이다. 그래프QL의 이런 설계는 ‘클라이언트가 원하는 것만 주겠다’는 철학의 연장선상에 있었지만, 현실에서는 운영과 디버깅의 골칫거리가 되곤 했다.
HTTP 상태 코드는 웹의 기본적인 의사소통 수단이다. 200은 성공, 404는 찾을 수 없음, 500은 서버 오류라는 식으로, 상태 코드는 클라이언트와 서버 간의 최소한의 공통 언어를 제공한다. 그래프QL이 이 언어를 무시한 것은 일종의 ‘언어의 오만’이었다. 클라이언트가 그래프QL 쿼리를 보낼 때, 서버는 마치 “너희는 HTTP 상태 코드 같은 건 신경 쓰지 마. 내가 다 알아서 해줄게”라는 태도를 취한 셈이다. 하지만 현실에서는 그렇지 않았다. 모니터링 시스템은 200 응답만 보고 모든 것이 정상이라고 판단했고, 개발자는 응답 본문을 일일이 파헤쳐야만 진짜 문제를 찾을 수 있었다. 이는 마치 전화로 고객 서비스에 문의했는데, 상담원이 “네, 알겠습니다”만 반복하다가 갑자기 전화를 끊어버리는 것과 같았다. 고객은 도대체 무슨 일이 일어났는지 알 길이 없다.
이번 변경은 그래프QL이 드디어 웹의 기본적인 규칙을 인정하는 순간처럼 보인다. HTTP 500을 기본 응답으로 사용하기로 한 것은, 그래프QL도 이제 ‘말하기’를 배우고 있다는 뜻이다. 서버 내부에서 문제가 발생하면, 더 이상 침묵하지 않고 명확하게 “문제가 생겼다”고 알려주는 것이다. 이는 그래프QL의 초기 철학과 다소 충돌하는 결정일 수도 있다. 그래프QL은 클라이언트에게 최대한의 유연성을 제공하는 것을 목표로 했지만, 그 유연성이 때로는 혼란을 낳기도 했다. 이제 그래프QL은 유연성과 명확성 사이에서 균형을 찾으려는 시도를 하고 있는 것이다.
오류는 시스템의 일부다. 중요한 것은 오류를 어떻게 처리하고, 어떻게 전달하느냐이다. 그래프QL이 HTTP 500을 기본 응답으로 채택한 것은, 오류를 숨기지 않고 직면하겠다는 의지의 표현이다.
하지만 이 결정이 모든 문제를 해결해줄까? 여전히 의문은 남는다. 그래프QL의 응답 본문에는 여전히 부분적인 오류나 경고가 포함될 수 있다. HTTP 500은 서버의 전반적인 상태를 나타낼 뿐, 클라이언트가 받은 데이터의 정확성을 보장하지는 않는다. 예를 들어, 일부 필드에서 오류가 발생했지만 전체 쿼리는 성공적으로 처리되었다면, HTTP 200을 반환해야 할까, 아니면 500을 반환해야 할까? 이런 모호함은 여전히 개발자들을 혼란스럽게 만들 수 있다. 그래프QL이 ‘말하기’를 배운 것은 반가운 일이지만, 아직 완전히 성숙한 언어가 되려면 더 많은 고민이 필요해 보인다.
그래프QL의 이번 변화는 기술의 진화가 단순히 새로운 기능을 추가하는 것만이 아니라는 사실을 상기시킨다. 때로는 기본적인 것들, 즉 웹의 근본적인 원칙을 다시 돌아보는 것이 더 중요할 때도 있다. 그래프QL이 HTTP 상태 코드를 존중하기로 한 것은, 기술이 더 이상 외로운 섬이 아니라 웹이라는 거대한 생태계의 일부임을 인정하는 것이다. 이는 그래프QL뿐만 아니라 모든 기술이 가져야 할 겸손함이 아닐까.
이제 개발자들은 그래프QL을 사용할 때 HTTP 상태 코드를 더 신뢰할 수 있게 되었다. 하지만 여전히 주의가 필요하다. 그래프QL의 응답은 여전히 복잡한 구조를 가지고 있으며, 그 안에는 다양한 수준의 오류가 숨어 있을 수 있다. HTTP 500이라는 명확한 신호는 시작에 불과하다. 진정한 과제는 그래프QL이 이 신호를 어떻게 더 풍부하고 유용한 정보로 확장해나갈지에 달려 있다.
이번 변화에 대한 자세한 내용은 GraphQL 공식 블로그에서 확인할 수 있다.
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
