[GraphQL] 기본 문법

GraphQL은 클라이언트가 서버에 요청을 보낼 때 Operation(작업) 과 Selection Set(선택 집합) 을 포함하여 데이터를 주고받습니다.
서버는 Object Type, Input Type, Scalar Type, Enum Type 등의 다양한 데이터 타입을 활용하여 API를 정의합니다.

---

1. 클라이언트 → 서버 요청

GraphQL 요청에는 Operation(작업) 과 Selection Set(선택 집합) 이 포함됩니다.

🔹 Operation (작업 유형)

GraphQL에서 클라이언트가 수행할 수 있는 작업(Operation)에는 Query, Mutation, Subscription이 있습니다.

1) Query (조회 작업)

• 데이터를 조회하는 작업
• HTTP GET 또는 POST 요청을 통해 실행됨

query {
  user(id: "1") {
    name
    email
  }
}

 

2) Query에서 변수 사용

변수를 활용하면 동적으로 값을 전달할 수 있습니다.

예제: 변수 사용

query GetUser($userId: ID!) {
  user(id: $userId) {
    name
    email
  }
}

변수 전달 (JSON)

{
  "userId": "1"
}

3) Query에서 기본값 지정

• 기본값을 지정하면 변수를 제공하지 않아도 실행 가능

query GetUser($userId: ID! = "1") {
  user(id: $userId) {
    name
    email
  }
}

---

4) Mutation (데이터 변경 작업)

• 데이터를 추가(Create), 수정(Update), 삭제(Delete) 하는 작업
• 서버에서 결과값 반환

mutation {
  createUser(name: "Alice", email: "alice@example.com") {
    id
    name
  }
}

 

5) Mutation에서 변수 사용

mutation CreateUser($name: String!, $email: String!) {
  createUser(name: $name, email: $email) {
    id
    name
    email
  }
}

변수(JSON)

{
  "name": "Alice",
  "email": "alice@example.com"
}

---

6) Subscription (실시간 데이터)

• 서버에서 실시간 데이터를 제공하는 작업
• WebSocket을 통해 변경 사항을 푸시(Push) 방식으로 전달

subscription {
  newMessage {
    content
    sender {
      name
    }
  }
}

 

---

2. Selection Set (선택 집합)

• 쿼리 키워드는 생략 가능

  {
    user(id: "1") {
      name
      email
    }
  }
  

• 중첩 필드(Nested Fields) 요청 가능

  {
    user(id: "1") {
      name
      posts {
        title
        comments {
          content
        }
      }
    }
  }
  

---

3. GraphQL 데이터 타입

🔹 Object Type (객체 타입)

• 서버에서 반환하는 실제 데이터 구조를 정의하는 타입
  

  type User {
    id: ID!
    name: String!
    email: String!
    posts: [Post]
  }
  
  type Post {
    id: ID!
    title: String!
    content: String!
  }
  

---

🔹 Input Type (입력 타입)

• Mutation에서 입력 값을 전달할 때 사용
  

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

---

4. Scalar Type (기본 스칼라 타입)

GraphQL에서 기본적으로 제공하는 데이터 타입이며 리프 값(Leaf Value) 으로 사용됩니다.

타입	설명	예제
Int	정수	42
Float	실수	3.14
String	문자열	"Hello"
Boolean	참/거짓	true, false
ID	고유 식별자	"1", "abc123"

---

5. Custom Scalar (사용자 정의 스칼라)

GraphQL 기본 스칼라에는 Date, DateTime이 포함되지 않으므로, 서버에서 직접 정의해야 합니다.

scalar DateTime

type User {
  id: ID!
  name: String!
  createdAt: DateTime!
}

---

6. Enum Type (열거형)

• 리프(Leaf) 값으로 사용되는 상수 타입
  

  enum UserRole {
    ADMIN
    USER
    GUEST
  }
  
  type User {
    id: ID!
    name: String!
    role: UserRole!
  }
  

---

7. NonNull Type (!)

• 기본적으로 모든 필드는 nullable
• !를 붙이면 null 허용 안 함
  

  type User {
    id: ID!   # null일 수 없음
    name: String! # null일 수 없음
    email: String  # null 가능
  }
  

---

8. List Type (리스트)

• 리스트([])를 사용하여 배열 데이터 표현
  

  type Query {
    users: [User]      # User 객체 배열, null 포함 가능
    activeUsers: [User!]! # User 객체 배열 (null 없음, 배열 자체도 null 아님)
  }
  

  리스트 타입 설명

---

정리

개념	설명	예제
Operation	클라이언트가 서버에 요청하는 방식	Query, Mutation, Subscription
Selection Set	필요한 데이터만 요청 가능	{ user { name email } }
Object Type	서버의 데이터 구조	type User { id: ID! name: String! }
Input Type	Mutation 입력 값	input CreateUserInput { name: String! }
Scalar Type	기본 제공 데이터 타입	Int, Float, String, Boolean, ID
Custom Scalar	서버에서 추가로 정의한 타입	scalar DateTime
Enum Type	열거형 상수 타입	enum UserRole { ADMIN USER GUEST }
NonNull Type (!)	null 불가능한 타입	name: String!
List Type ([])	리스트 데이터 타입	[User!]!