Spring Boot와 GraphQL로 만드는 차세대 API 서비스 – 쉽게 따라하는 가이드!

GraphQL이란 무엇인가?

GraphQL은 2015년 페이스북에서 개발한 데이터 쿼리 언어로, 기존의 REST API의 단점을 보완하는 데 중점을 둔 기술입니다. GraphQL은 클라이언트가 원하는 데이터를 명확하게 요청하고, 정확히 필요한 데이터만 응답받을 수 있도록 설계되었습니다. 그로 인해 불필요한 데이터 전송을 줄이고, 복잡한 API 호출을 단순화하는 데 큰 장점을 제공합니다.

1. GraphQL의 주요 특징

• 단일 엔드포인트: REST API에서는 리소스마다 별도의 엔드포인트를 설정해야 하지만, GraphQL에서는 단일 엔드포인트만으로 모든 데이터를 요청할 수 있습니다.
• 클라이언트 주도 데이터 요청: 클라이언트는 필요한 데이터만 요청할 수 있기 때문에 오버페칭(over-fetching)과 언더페칭(under-fetching) 문제를 해결할 수 있습니다.
• 타입 시스템: GraphQL은 엄격한 스키마 정의를 통해, 서버와 클라이언트 간의 데이터 일관성을 유지할 수 있습니다.
• 실시간 데이터 갱신: Subscriptions라는 기능을 통해, 클라이언트는 서버에서 데이터가 변경될 때 실시간으로 업데이트된 데이터를 받을 수 있습니다.

2. GraphQL의 장점

2.1. 데이터 효율성

REST API에서는 특정 데이터를 요청하기 위해 여러 번의 네트워크 호출이 필요할 수 있지만, GraphQL은 한 번의 요청으로 필요한 모든 데이터를 가져올 수 있습니다. 이는 모바일 및 저대역폭 환경에서 특히 유리합니다.

2.2. 유연성

GraphQL에서는 클라이언트가 데이터를 정의하기 때문에, 서버에서 일괄적인 응답을 전송할 필요가 없습니다. 이를 통해 개발자는 API를 좀 더 유연하게 설계할 수 있습니다.

2.3. 발전된 도구 지원

GraphQL을 사용하면, 강력한 개발 도구(예: GraphiQL, Apollo Client)를 통해 API를 시각적으로 탐색하고 실시간으로 쿼리를 실행할 수 있습니다.

반응형

3. Spring Boot에서 GraphQL 설정하기

이제 Gradle 기반의 Spring Boot 프로젝트에서 GraphQL API를 구축하는 방법을 살펴보겠습니다. 이 예제는 간단한 GraphQL API를 구현하여 사용자가 원하는 데이터만 요청할 수 있도록 하는 기본적인 구조를 설명합니다.

3.1. 프로젝트 설정

1) Gradle 프로젝트 생성

먼저, Spring Initializr에서 새로운 Gradle 프로젝트를 생성합니다. 필수적인 의존성은 다음과 같습니다:

• Spring Web
• Spring Boot GraphQL
• Spring Boot DevTools

2) Gradle 설정

build.gradle 파일에 다음 의존성을 추가합니다.

plugins {
    id 'org.springframework.boot' version '3.1.4'
    id 'io.spring.dependency-management' version '1.1.2'
    id 'java'
}

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

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-graphql'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

test {
    useJUnitPlatform()
}

3.2. GraphQL 스키마 설정

프로젝트 루트에 src/main/resources 폴더 안에 graphql 폴더를 생성하고, 그 안에 schema.graphqls 파일을 작성합니다. 이 파일은 GraphQL 스키마를 정의하는 역할을 합니다.

type Query {
    hello: String
    userById(id: ID!): User
}

type User {
    id: ID
    name: String
    age: Int
}

위 스키마는 hello라는 간단한 쿼리와 userById라는 쿼리를 정의하고 있으며, User 타입을 정의하고 있습니다.

3.3. 서비스 및 리졸버 구현

1) User 클래스 생성

src/main/java/com/example/demo/model/User.java 파일을 생성하여, 사용자 정보를 담는 User 엔티티 클래스를 작성합니다.

package com.example.demo.model;

public class User {
    private String id;
    private String name;
    private int age;

    public User(String id, String name, int age) {
        this.id = id;
        this.name = name;
        this.age = age;
    }

    // Getter and Setter
    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

2) 리졸버(Resolver) 클래스 구현

GraphQL에서 쿼리를 처리하는 리졸버를 작성합니다. src/main/java/com/example/demo/resolver/UserResolver.java 파일을 생성합니다.

package com.example.demo.resolver;

import com.example.demo.model.User;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.stereotype.Controller;

import java.util.HashMap;
import java.util.Map;

@Controller
public class UserResolver {

    private static Map<String, User> users = new HashMap<>();

    static {
        users.put("1", new User("1", "John", 30));
        users.put("2", new User("2", "Jane", 25));
    }

    @QueryMapping
    public String hello() {
        return "Hello, GraphQL!";
    }

    @QueryMapping
    public User userById(String id) {
        return users.get(id);
    }
}

@QueryMapping 어노테이션을 사용하여 GraphQL 스키마에서 정의한 쿼리를 처리합니다. userById 쿼리는 입력된 사용자 ID에 해당하는 사용자 정보를 반환합니다.

3.4. 테스트 실행

이제 애플리케이션을 실행하고 http://localhost:8080/graphiql에 접속합니다. 여기서 GraphiQL 인터페이스를 통해 다음과 같은 쿼리를 실행해봅니다.

{
  hello
}

결과:

{
  "data": {
    "hello": "Hello, GraphQL!"
  }
}

다음으로 사용자 데이터를 조회하는 쿼리를 실행합니다.

{
  userById(id: "1") {
    id
    name
    age
  }
}

결과:

{
  "data": {
    "userById": {
      "id": "1",
      "name": "John",
      "age": 30
    }
  }
}

728x90

이 블로그 글을 통해 GraphQL의 기본 개념과 장점을 설명하고, Spring Boot 프로젝트에서 GraphQL API를 구축하는 방법을 다뤘습니다. REST API의 한계를 극복하고 클라이언트 주도적인 데이터를 제공하고 싶다면 GraphQL을 도입하는 것을 고려해보세요.

Spring Boot에서 GraphQL을 사용하면 직관적이고 강력한 API를 설계할 수 있습니다. 앞으로도 GraphQL의 실시간 기능이나 다양한 인증 방법을 다룬 고급 주제로 확장할 수 있습니다.