Spring Boot로 GraphQL API 만들기 (GraphQL Java)

개요

이 글은 Spring Boot 환경에서 GraphQL Java를 사용해 GraphQL API를 만드는 방법을 단계별로 설명한다. 처음 접하는 개발자도 이해할 수 있도록 스키마 작성, 의존성 설정, 리졸버 구현, 간단한 테스트 흐름을 예제로 보여준다. 예제는 실무에서 바로 적용 가능한 형태로 구성되어 있으며, spring boot graphql 예제와 graphql java spring boot 설정, spring boot graphql schema 관련 핵심 사항을 포함한다.

프로젝트 설정

의존성 구성 (Gradle)

간단한 Gradle 설정 예제. Kotlin DSL 대신 일반 Groovy Gradle 예시를 사용한다.

plugins {
    id "org.springframework.boot" version "2.7.0"
    id "io.spring.dependency-management" version "1.0.11.RELEASE"
    id "java"
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'com.graphql-java-kickstart:graphql-spring-boot-starter:11.1.0'
    implementation 'com.graphql-java-kickstart:graphql-java-tools:11.1.0'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

application.properties

기본 GraphQL 엔드포인트와 GraphiQL(또는 Playground) 설정.

server.port=8080
graphql.servlet.mapping=/graphql
graphql.servlet.enabled=true
graphql.playground.enabled=true

스키마 작성

GraphQL 스키마는 src/main/resources 폴더에 schema.graphqls 파일로 둔다. 스키마는 API 계약을 명확하게 한다.

type Query {
    bookById(id: ID!): Book
    allBooks: [Book]
}

type Book {
    id: ID!
    title: String!
    author: String!
    publishedYear: Int
}

도메인과 저장소

간단한 메모리 기반 저장소로 시작한다. 실제 환경에서는 JPA나 외부 API에 연결하면 된다.

package com.example.demo.model;

public class Book {
    private String id;
    private String title;
    private String author;
    private Integer publishedYear;

    // 생성자, getter, setter 생략
}

package com.example.demo.repository;

import com.example.demo.model.Book;
import java.util.*;

public class BookRepository {
    private final Map<String, Book> books = new HashMap<>();

    public BookRepository() {
        Book b1 = new Book("1", "Spring Boot Guide", "Kim", 2020);
        Book b2 = new Book("2", "GraphQL in Action", "Lee", 2021);
        books.put(b1.getId(), b1);
        books.put(b2.getId(), b2);
    }

    public Book getById(String id) {
        return books.get(id);
    }

    public List<Book> getAll() {
        return new ArrayList<>(books.values());
    }
}

리졸버 구현

graphql-java-tools를 사용하면 스키마에 대응하는 리졸버를 간단히 만들 수 있다. Query 타입을 구현하는 클래스 예제.

package com.example.demo.resolver;

import com.coxautodev.graphql.tools.GraphQLQueryResolver;
import com.example.demo.model.Book;
import com.example.demo.repository.BookRepository;
import java.util.List;
import org.springframework.stereotype.Component;

@Component
public class Query implements GraphQLQueryResolver {

    private final BookRepository bookRepository = new BookRepository();

    public Book bookById(String id) {
        return bookRepository.getById(id);
    }

    public List<Book> allBooks() {
        return bookRepository.getAll();
    }
}

실행 및 테스트

앱을 기동한 후 GraphiQL 또는 Playground에서 쿼리를 실행한다. curl로도 테스트 가능하다.

curl -X POST -H "Content-Type: application/json" --data '{"query":"{ allBooks { id title author publishedYear } }"}' http://localhost:8080/graphql

점검 포인트

• 스키마 파일 이름과 위치: src/main/resources/schema.graphqls로 두면 자동 인식됨.
• 의존성 충돌 주의: Spring Boot 버전과 kickstart 라이브러리 호환성 확인 필요.
• 비즈니스 로직은 리졸버에서 최소화하고 서비스 계층으로 분리 권장.
• 권한과 입력 검증을 리졸버에서 처리하거나 DataFetcher 레벨에서 적용.
• 캐싱, 페이징 전략은 대형 데이터셋에 필수적임.

참고와 확장

이 예제는 기본 흐름을 보여준다. 실제 프로젝트에서는 다음을 고려한다.

• JPA 연동: Spring Data JPA로 데이터 계층 교체.
• Batch Loader: N+1 문제 해결을 위한 DataLoader 적용.
• 스키마 분리: 대규모 서비스는 모듈별 스키마 관리.

맺음말

위 예제는 spring boot graphql schema 설계와 graphql java spring boot 설정을 이해하는 데 초점을 맞췄다. 단계별로 따라가면 spring boot graphql 예제 형태로 기본 API를 빠르게 구성할 수 있다. 이후엔 인증, 권한, 성능 최적화 등 실무 요구에 맞춰 확장하면 된다.