[GraphQL] GraphQL 쿼리(Query)와 뮤테이션(Mutation) 작성법

GraphQL은 클라이언트가 서버에 원하는 데이터를 정확하게 요청하거나, 데이터를 변경(create, update, delete)할 수 있도록 설계된 API 쿼리 언어이다. GraphQL에서 데이터를 조회할 때는 Query, 데이터를 생성·수정·삭제할 때는 Mutation을 사용한다.

 

GraphQL 쿼리(Query) 작성 방법

---

쿼리(Query)는 데이터를 "읽기(read)" 위한 요청이다.

REST에서 GET 요청과 유사하지만, GraphQL은 필드 단위로 응답을 제어할 수 있다는 점이 특징이다.

 

📌 기본 구조

query {
  entityName {
    field1
    field2
  }
}

 

GraphQL 쿼리(Query) 작성 방법

1. GraphQL 스키마 정의
2. 데이터 모델 및 서비스 생성
3. GraphQL 리졸버 생성
4. SpringBoot 애플리케이션 설정

 

1️⃣ GraphQL 스키마 정의

GraphQL은 API에서 제공할 데이터의 구조를 스키마로 정의한다. 이는 클라이언트가 어떤 데이터를 요청할 수 있는지, 어떤 필드들이 존재하는지를 나타낸다.

# schema.graphqls

type User {
  id: ID!
  name: String!
  email: String!
}

type Query {
  users: [User]
  user(id: ID!): User
}

 

2️⃣ 데이터 모델 및 서비스 생성

Java에서 실제 사용자 정보를 표현할 엔티티와 서비스를 생성한다.

// User.java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    private Long id;
    private String name;
    private String email;
    // getters, setters
}

// UserService.java
@Service
public class UserService {
    private final List<User> users = List.of(
        new User(1L, "Alice", "alice@example.com"),
        new User(2L, "Bob", "bob@example.com")
    );

    public List<User> getAllUsers() {
        return users;
    }

    public User getUserById(Long id) {
        return users.stream().filter(u -> u.getId().equals(id)).findFirst().orElse(null);
    }
}

 

3️⃣ GraphQL 리졸버 생성

GraphQL 리졸버는 쿼리 필드가 호출되었을 때 실제 데이터를 반환하는 역할을 한다.

// UserQueryResolver.java
@Component
public class UserQueryResolver implements GraphQLQueryResolver {

    private final UserService userService;

    public UserQueryResolver(UserService userService) {
        this.userService = userService;
    }

    public List<User> users() {
        return userService.getAllUsers();
    }

    public User user(Long id) {
        return userService.getUserById(id);
    }
}

 

4️⃣ Spring Boot 애플리케이션 설정

graphql-spring-boot-starter 라이브러리를 통해 GraphQL 서버를 구성한다.

<!-- build.gradle 또는 pom.xml에 추가 -->
<dependency>
  <groupId>com.graphql-java-kickstart</groupId>
  <artifactId>graphql-spring-boot-starter</artifactId>
  <version>11.1.0</version>
</dependency>

@SpringBootApplication
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
  
  @Bean
  public GraphQLSchema graphQLSchema(QueryResolver queryResolver) {
    return new GraphQLSchemaGenerator()
      .withOperationsFromSingleton(queryResolver)
      .generate();
  }
}

 

---

GraphQL 뮤테이션(Mutation) 작성법

---

뮤테이션은 데이터를 변경(craete, update, delete) 하기 위한 요청이다.

REST의 POST, PUT, DELETE와 유사한 개념이다.

 

📌 기본 구조

mutation {
  mutationName(input: { field1: value, field2: value }) {
    returnField1
    returnField2
  }
}

• mutationName은 서버에서 정의된 뮤테이션 이름이며, inut은 서버에 보낼 데이터이다.

 

GraphQL 뮤테이션(Mutation) 작성 방법

1. GraphQL 스키마 정의
2. 데이터 모델 및 서비스 생성
3. GraphQL Mutation 리졸버 생성
4. SpringBoot 애플리케이션 설정

 

1️⃣ GraphQL 스키마 정의 (Mutation 포함)

# schema.graphqls

type Mutation {
  createUser(input: CreateUserInput!): User
}

input CreateUserInput {
  name: String!
  email: String!
}

 

2️⃣ 데이터 모델 및 서비스 (생성 메서드 포함)

사용자 정보를 담은 데이터 모델과 해당 데이터를 제공하는 서비스를 생성

public class CreateUserInput {
  private String name;
  private String email;
}

// UserService.java (추가)
private final List<User> userStorage = new ArrayList<>();

public User createUser(String name, String email) {
    User user = new User();
    user.setId((long) (userStorage.size() + 1));
    user.setName(name);
    user.setEmail(email);
    userStorage.add(user);
    return user;
}

 

3️⃣ GraphQL Mutation 리졸버 생성

사용자를 생성하는 메서드를 추가한다.

// UserMutationResolver.java
@Component
public class UserMutationResolver implements GraphQLMutationResolver {

    private final UserService userService;

    public UserMutationResolver(UserService userService) {
        this.userService = userService;
    }

    public User createUser(CreateUserInput input) {
        return userService.createUser(input.getName(), input.getEmail());
    }
}

 

4️⃣ SpringBoot 애플리케이션 설정

Spring Boot 애플리케이션을 구성하고 GraphQL을 설정

@SpringBootApplication
public class Application {
  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
  
  @Bean
  public GraphQLSchema graphQLSchema(QueryResolver queryResolver, MutationResolver 
  mutationResolver) {
    return new GraphQLSchemaGenerator()
      .withOperationsFromSingletons(queryResolver, mutationResolver)
      .generate();
  }
}

 

---

🛒 커머스 플랫폼 GraphQL 예제

---

데이터 모델 구성

• User: 사용자 정보
• Product: 상품 정보
• Order: 주문 정보
• Payment: 결제 정보
• Shipment: 배송 정보

 

🧾 스키 정의 예시

type Order {
  id: ID!
  products: [Product]
  payment: Payment
  shipment: Shipment
}

interface Payment {
  method: String!
  amount: Float!
}

type CreditCardPayment implements Payment {
  method: String!
  amount: Float!
  cardNumberMasked: String!
}

 

복잡한 쿼리 예시 1: 주문 + 배송 + 제품

query GetOrderAndPaymentDetails {
  getOrder(id: "1001") {
    id
    products {
      name
      price
    }
    shipment {
      trackingNumber
      status
    }
  }
}

 

복잡한 쿼리 예시 2: 사용자 주문 이력

query GetCustomerOrderHistory {
  user(id: "u123") {
    name
    orders {
      id
      payment {
        amount
        method
      }
    }
  }
}

 

복잡한 쿼리 예시 3: 결제 인터페이스 활용

query GetOrderAndPaymentWithInterface {
  getOrder(id: "1002") {
    id
    payment {
      method
      ... on CreditCardPayment {
        cardNumberMasked
      }
    }
  }
}