GraphQL 모범 사례

GraphQL 모범 사례 (Best Practices)

GraphQL은 "반드시 이렇게 해야 한다"는 보편적인 REST 규칙(예: GET은 캐시, POST는 상태 변경) 같은 강제가 없어요. 그래서 오히려 팀마다 서로 다른 패턴으로 발전할 수 있는데, 그래프QL 조직이 정리해 둔 모범 사례가 나름의 기준 역할을 해요.

출처: https://graphql.org/learn/best-practices/

이 페이지가 강조하는 몇 가지를 살펴볼게요.

단일 엔드포인트와 HTTP 상태 코드: GraphQL은 보통 하나의 /graphql 엔드포인트를 쓰고, 요청/응답은 POST로 주고받아요. HTTP 상태 코드로 표현하기 어려운 애플리케이션 수준 에러는 응답의 errors 필드로 전달하는 게 일반적이에요.
버저닝: REST처럼 /v2/... 식으로 URL 버전을 나누기보다, 스키마 필드를 추가·폐기(deprecate)하는 방식으로 계속 진화시키는 걸 권장해요. 스키마의 하위 호환성을 유지하며 새 필드를 더하고, 필요 없어진 필드는 나중에 제거하죠.
Nullable과 Non-Null 구성: !(Non-Null)은 "값이 반드시 있다"는 뜻이지만, 그만큼 장애가 나면 전체 응답이 실패할 위험도 커요. 필드가 실패할 가능성이 있다면 결과 전체를 죽이기보다 Nullable로 두는 게 안전한 경우가 많아요.
페이지네이션: 무한히 많은 목록은 한 번에 다 주지 않고, 커서 기반 페이지네이션 같은 기법으로 조각을 나눠 전달해요.

이렇게 보면 GraphQL에서 "한 표준 답"보다는 스키마가 API 계약이자 문서라는 태도가 중요해요. 팀 내에서 필드 네이밍·페이지네이션·에러 형태를 한 방향으로 잡아두면, 스키마가 커져도 쿼리가 예측 가능하게 유지돼요.