GraphQL with Spring Boot

Spring Boot에서 GraphQL을 붙인다는 것

Spring Boot에서 GraphQL을 도입한다는 것은 REST 컨트롤러를 하나 더 만드는 일이 아니라, 스키마와 리졸버 중심으로 API 레이어를 다시 구성하는 일에 가깝다.

중심 요소는 다음과 같다.

• GraphQL 스키마
• Query/Mutation 리졸버
• 타입별 필드 리졸버
• 데이터 로딩 전략

기본 구성

Spring for GraphQL에서는 보통 다음 흐름으로 개발한다.

1. 스키마 파일을 정의한다.
2. @QueryMapping, @MutationMapping으로 진입점을 만든다.
3. 복합 필드는 @SchemaMapping으로 해결한다.
4. 필요하면 DataLoader로 N+1 문제를 완화한다.

예를 들어 게시글 목록을 조회하는 Query와 작성자 정보를 붙이는 구조라면, 게시글 조회와 작성자 조회를 별도 리졸버로 나누는 식이다.

왜 @SchemaMapping이 중요한가

GraphQL은 클라이언트가 요청한 필드만 계산한다. 그래서 복합 필드는 별도 필드 리졸버로 분리하는 편이 좋다.

예를 들어 Post.author를 조회할 때:

• 클라이언트가 author를 요청하지 않으면 굳이 조회하지 않는다.
• 요청했을 때만 작성자 조회 로직이 실행된다.

이 지점이 GraphQL의 유연성이자, 동시에 N+1 문제가 생기기 쉬운 부분이다.

실무에서 주의할 점

1. 스키마가 진짜 계약이다

컨트롤러 메서드보다 스키마가 우선이다. 필드명, nullable 여부, 리스트 구조가 곧 API 계약이 된다.

2. N+1 문제를 경계해야 한다

게시글 100개를 반환하면서 각 게시글마다 작성자를 개별 조회하면 GraphQL은 금방 비효율적이 된다. DataLoader나 배치 조회 전략이 중요하다.

3. 조회와 변경을 과하게 섞지 않기

GraphQL은 유연하지만, 도메인 경계를 무시하고 스키마를 비대하게 만들면 REST보다 더 관리하기 어려워진다.

언제 잘 맞나

• 조회 조합이 자주 바뀌는 화면
• BFF 성격의 API 레이어
• 프런트엔드가 필요한 데이터 구조를 빠르게 바꿔야 하는 환경

반대로 단순 CRUD 위주의 내부 관리 시스템이라면 REST가 더 단순할 수 있다.

정리

Spring Boot에서 GraphQL을 잘 쓰려면 “쿼리를 받는 기술”보다 스키마 설계와 데이터 로딩 전략을 먼저 봐야 한다. 생산성은 높지만, 리졸버 구조를 잘못 잡으면 복잡도도 빠르게 커진다.