🌐
GraphQL 핵심 치트시트

스칼라 타입, 스키마 정의(SDL), Query/Mutation/Subscription 문법, Spring for GraphQL 연동(@QueryMapping, @BatchMapping), N+1 DataLoader 최적화 및 보안 레퍼런스
#graphql#api#query#mutation#subscription#sdl#spring#spring-boot#spring-graphql#apollo#dataloader#backend최종 업데이트: 2026-09-29
GraphQL 핵심 치트시트 핵심 명령어 및 실전 가이드

스칼라 타입, 스키마 정의(SDL), Query/Mutation/Subscription 문법, Spring for GraphQL 연동(@QueryMapping, @BatchMapping), N+1 DataLoader 최적화 및 보안 레퍼런스
## 1. GraphQL 핵심 개념 & REST 비교
```text
[GraphQL vs REST API 핵심 비교]
• 엔드포인트     : REST는 리소스별 수많은 엔드포인트 vs GraphQL은 단일 엔드포인트 (/graphql)
• Over-fetching : REST는 불필요한 필드까지 전부 반환 vs GraphQL은 클라이언트가 요청한 필드만 정확히 반환
• Under-fetching: REST는 여러 번의 연쇄 HTTP 요청 필요 vs GraphQL은 1번의 쿼리로 연관 데이터 일괄 조회
• 타입 시스템   : 스키마(SDL)를 통한 엄격한 정적 타입 검증 및 자동 문서화(Introspection) 지원
• HTTP 메서드   : 대부분 POST 요청 body(JSON)에 쿼리 스트링을 담아 전송
```
```graphql
# 클라이언트 요청 예시 (POST /graphql)
query {
  user(id: "usr_100") {
    name
    email
    posts(limit: 2) {
      title
    }
  }
}
```

## 2. 기본 스칼라 타입 & Nullability
```graphql
# [5가지 내장 기본 스칼라(Scalar) 타입]
# Int     : 부호 있는 32비트 정수
# Float   : 부호 있는 배정밀도 부동소수점
# String  : UTF-8 문자열
# Boolean : true 또는 false
# ID      : 고유 식별자 (내부적으로는 String 직렬화)

type Product {
  id: ID!               # 필수(Non-null) ID
  name: String!         # 필수 문자열
  price: Float!         # 필수 부동소수점
  rating: Int           # 널 허용(Nullable) 정수 (값 없으면 null)
  isAvailable: Boolean! # 필수 불리언
  tags: [String!]!      # 배열과 내부 요소 모두 non-null
}

# [리스트와 Nullability 조합 규칙]
# [String]   : 배열 자체도 null 가능, 배열 내부 요소도 null 가능 (ex: null, [null, "a"])
# [String!]  : 배열 자체는 null 가능, 내부 요소는 반드시 문자열 (ex: null, ["a", "b"])
# [String]!  : 배열은 필수 존재, 내부 요소는 null 가능 (ex: [], ["a", null])
# [String!]! : 배열과 내부 요소 모두 필수 존재 (ex: [], ["a", "b"])
```

## 3. 스키마 정의 언어 (SDL: Types, Enums & Custom Scalars)
```graphql
# 커스텀 스칼라 선언
scalar DateTime
scalar JSON

# 열거형(Enum) 정의
enum UserRole {
  ADMIN
  USER
  GUEST
}

# 객체 타입(Object Type) 정의
type User {
  id: ID!
  email: String!
  name: String!
  role: UserRole!
  createdAt: DateTime!
  profile: Profile
  posts: [Post!]!
}

type Profile {
  avatarUrl: String
  bio: String
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  likeCount: Int!
}
```

## 4. Query 실전 문법 (인자, 별칭 & 프래그먼트)
```graphql
# 1. 인자(Arguments) 전달 & 중첩 조회
query GetUserProfile {
  user(id: "usr_42") {
    name
    profile {
      avatarUrl
    }
  }
}

# 2. 별칭(Aliases) : 동일한 필드를 서로 다른 인자로 한 번에 조회
query CompareUsers {
  firstUser: user(id: "usr_1") {
    ...UserBasicInfo
  }
  secondUser: user(id: "usr_2") {
    ...UserBasicInfo
  }
}

# 3. 프래그먼트(Fragments) : 공통 필드 모음 재사용
fragment UserBasicInfo on User {
  id
  name
  email
  role
}
```

## 5. 변수(Variables) & 지시어(@include, @skip)
```graphql
# 변수 선언 시 타입과 기본값 지정 ($withPosts: Boolean = false)
query GetUserWithCondition($userId: ID!, $withPosts: Boolean!) {
  user(id: $userId) {
    id
    name
    email
    # @include : 조건이 true일 때만 필드 포함
    posts @include(if: $withPosts) {
      id
      title
    }
    # @skip : 조건이 true이면 필드 제외
    profile @skip(if: $withPosts) {
      bio
    }
  }
}

# [GraphQL 변수 JSON (HTTP Body의 "variables" 필드)]
# {
#   "userId": "usr_42",
#   "withPosts": true
# }
```

## 6. Mutation 데이터 변경 & 입력 객체(Input)
```graphql
# 스키마 정의: Mutation 전용 Input Object
input CreatePostInput {
  title: String!
  content: String!
  tags: [String!]
}

# 변경 결과 Payload 반환 패턴 (UI 캐시 갱신 용이)
type CreatePostPayload {
  success: Boolean!
  post: Post
  clientMutationId: String
}

# Mutation 요청 쿼리
mutation CreateNewPost($input: CreatePostInput!) {
  createPost(input: $input) {
    success
    post {
      id
      title
      createdAt
      author {
        id
        name
      }
    }
  }
}
```

## 7. Subscription 실시간 이벤트 구독 (WebSockets)
```graphql
# 스키마 정의
type Subscription {
  postCreated: Post!
  commentAdded(postId: ID!): Comment!
  messageSent(roomId: ID!): Message!
}

# 클라이언트 구독 요청 (WebSocket 프로토콜 ws:// 또는 wss://)
subscription WatchRoomMessages($roomId: ID!) {
  messageSent(roomId: $roomId) {
    id
    sender {
      name
    }
    text
    sentAt
  }
}
```
```text
[실무 권장사항]
• 프로토콜 : graphql-ws 라이브러리 사용 권장 (구형 subscriptions-transport-ws는 deprecated)
• 하트비트 : 주기적인 Ping/Pong 패킷으로 모바일 끊김 및 유휴 커넥션 감지
```

## 8. 인터페이스(Interface) & 유니온(Union) 다형성
```graphql
# 인터페이스 정의
interface Node {
  id: ID!
}

interface Content {
  id: ID!
  title: String!
  author: User!
}

# 인터페이스 구현
type Article implements Content {
  id: ID!
  title: String!
  author: User!
  wordCount: Int!
}

type Video implements Content {
  id: ID!
  title: String!
  author: User!
  durationSeconds: Int!
}

# 유니온(Union) 타입 정의 (스칼라가 아닌 Object 타입들의 합집합)
union SearchResult = Article | Video | User

# 인라인 프래그먼트(... on Type) 및 __typename을 활용한 쿼리
query UniversalSearch($keyword: String!) {
  search(keyword: $keyword) {
    __typename # 실제 객체 타입명 반환 ("Article", "Video", "User")
    ... on Article {
      id
      title
      wordCount
    }
    ... on Video {
      id
      title
      durationSeconds
    }
    ... on User {
      id
      name
      email
    }
  }
}
```

## 9. 백엔드 리졸버 & N+1 해결 (DataLoader)
```javascript
// 리졸버 기본 시그니처: (parent, args, context, info)
const resolvers = {
  Query: {
    user: async (_, { id }, { db }) => db.findUserById(id),
    posts: async (_, { limit }, { db }) => db.findRecentPosts(limit),
  },
  Post: {
    // [N+1 발생 원인]: Post가 100건이면 author 리졸버가 100번 개별 SQL 실행!
    // author: async (post, _, { db }) => db.findUserById(post.authorId),

    // [DataLoader 해결]: 1개의 이벤트 루프 틱 동안의 요청을 모아 1번의 'WHERE id IN (...)'으로 일괄 조회
    author: (post, _, { loaders }) => loaders.userLoader.load(post.authorId),
  },
};

// DataLoader 인스턴스 생성 (요청(Context) 단위 격리 필수!)
import DataLoader from 'dataloader';

export function createLoaders(db) {
  return {
    userLoader: new DataLoader(async (userIds) => {
      // SELECT * FROM users WHERE id IN (1, 2, 3...)
      const users = await db.findUsersByIds(userIds);
      // 반드시 전달받은 userIds 순서와 1:1로 매핑하여 반환해야 함!
      const userMap = new Map(users.map(u => [u.id, u]));
      return userIds.map(id => userMap.get(id) || null);
    }),
  };
}
```

## 10. 페이지네이션 (Cursor-based Relay Connection)
```graphql
# 표준 Relay Connection 명세
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type PostEdge {
  cursor: String!
  node: Post!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# 쿼리 요청: 특정 커서 이후(after) N개(first) 조회
query GetPaginatedPosts($first: Int!, $after: String) {
  posts(first: $first, after: $after) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      cursor
      node {
        id
        title
        likeCount
      }
    }
  }
}
```

## 11. 에러 응답 구조 & 핸들링 모범 사례
```json
{
  "data": {
    "user": null
  },
  "errors": [
    {
      "message": "해당 사용자를 찾을 수 없습니다.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND",
        "invalidArgs": ["usr_999"],
        "timestamp": "2026-09-29T11:30:00Z"
      }
    }
  ]
}
```
```text
[GraphQL 에러 처리 핵심 원칙]
• HTTP 200 OK  : GraphQL 엔진이 쿼리를 정상 파싱/실행했다면 필드 에러가 있더라도 HTTP 상태 코드는 200 반환
• 부분 응답     : 에러가 발생하지 않은 다른 필드는 "data"에 정상 포함되어 렌더링 가능 (Partial Data)
• extensions   : 클라이언트 분기 처리를 위해 표준 코드(UNAUTHENTICATED, FORBIDDEN, BAD_USER_INPUT)를 extensions에 포함
• 보안 주의    : 운영(Production) 환경에서는 내부 SQL/스택트레이스가 클라이언트로 노출되지 않도록 에러 마스킹 필수
```

## 12. 운영 및 보안 모범 사례 (Security & Production)
```text
[GraphQL 보안 5대 수칙]
1. 인트로스펙션(Introspection) 비활성화
   - 운영 배포 시 __schema, __type 쿼리를 막아 내부 구조 노출 방지
2. 쿼리 깊이 제한 (Query Depth Limit)
   - 악의적인 무한 순환 쿼리 방지 (user { posts { author { posts { author... } } } })
3. 쿼리 복잡도 분석 (Query Cost/Complexity Analysis)
   - 계산 비용이 큰 필드에 가중치를 부여하고, 임계치 초과 쿼리 거부
4. 지속 쿼리 (Persisted Queries)
   - 클라이언트는 쿼리 본문 대신 사전에 등록된 해시(SHA-256)값만 전송하여 대역폭 절약 및 임의 쿼리 차단
5. 배치 요청 개수 제한 (Batching Attack 방지)
   - 단일 HTTP 요청에 수천 개의 query 배열을 담아 보내는 무차별 대입(Brute-force) 공격 차단
```

## 13. Spring for GraphQL 설정 & 스키마 구성
```groovy
// build.gradle (Spring Boot 3.x / 2.7+ 공식 스타터)
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-graphql'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    // WebSocket 구독 지원 필요 시 추가
    implementation 'org.springframework.boot:spring-boot-starter-websocket'
}
```
```yaml
# application.yml
spring:
  graphql:
    graphiql:
      enabled: true            # 브라우저 테스트 UI 활성화 (http://localhost:8080/graphiql)
      path: /graphiql
    http:
      path: /graphql           # GraphQL 단일 HTTP 엔드포인트 (기본값: /graphql)
    websocket:
      path: /graphql           # Subscription용 웹소켓 엔드포인트
    schema:
      printer:
        enabled: true          # 서버 기동 시 병합된 최종 스키마를 콘솔에 출력
```
```graphql
# src/main/resources/graphql/schema.graphqls
# Spring Boot가 해당 디렉터리의 모든 .graphqls 파일을 자동 로드하여 병합합니다.
type Query {
    bookById(id: ID!): Book
    allBooks: [Book!]!
}

type Mutation {
    createBook(input: CreateBookInput!): Book!
}

type Subscription {
    bookAdded: Book!
}

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

type Author {
    id: ID!
    name: String!
}

input CreateBookInput {
    title: String!
    pageCount: Int!
    authorId: ID!
}
```

## 14. Spring 컨트롤러 구현 (@QueryMapping, @MutationMapping)
```java
package com.example.demo.controller;

import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.data.method.annotation.SubscriptionMapping;
import org.springframework.stereotype.Controller;
import reactor.core.publisher.Flux;

import java.util.List;

@Controller
public class BookController {

    private final BookService bookService;

    public BookController(BookService bookService) {
        this.bookService = bookService;
    }

    // 1. Query.bookById(id: ID!) 매핑 (메서드명과 스키마 필드명 일치)
    @QueryMapping
    public Book bookById(@Argument Long id) {
        return bookService.findById(id);
    }

    // 2. Query.allBooks 매핑
    @QueryMapping
    public List<Book> allBooks() {
        return bookService.findAll();
    }

    // 3. Mutation.createBook(input: CreateBookInput!) 매핑
    // Java 17+ record 클래스를 사용하면 별도 매퍼 없이 자동 바인딩
    @MutationMapping
    public Book createBook(@Argument CreateBookInput input) {
        return bookService.create(input);
    }

    // 4. Subscription.bookAdded 매핑 (Reactive Flux 반환)
    @SubscriptionMapping
    public Flux<Book> bookAdded() {
        return bookService.getBookAddedFlux();
    }
}

// DTO는 record로 정의 권장
public record CreateBookInput(String title, int pageCount, Long authorId) {}
```

## 15. Spring N+1 해결 (@BatchMapping & DataLoader)
```java
@Controller
public class BookAuthorController {

    private final AuthorService authorService;

    public BookAuthorController(AuthorService authorService) {
        this.authorService = authorService;
    }

    // [단건 해결]: @SchemaMapping (N+1 문제 발생 가능!)
    // allBooks로 책 100건 조회 시, 각 책마다 author 메서드가 100번 호출됨
    // @SchemaMapping(typeName = "Book", field = "author")
    // public Author getAuthor(Book book) {
    //     return authorService.findById(book.authorId());
    // }

    // [⭐️ 실무 권장]: @BatchMapping (DataLoader 자동 구성)
    // 부모 리스트(List<Book>)를 한 번에 인자로 전달받아 외래키 목록을 추출하고,
    // "SELECT * FROM author WHERE id IN (...)" 1번의 쿼리로 묶어서 Map 형태로 반환
    @BatchMapping(typeName = "Book", field = "author")
    public Map<Book, Author> author(List<Book> books) {
        List<Long> authorIds = books.stream().map(Book::authorId).toList();
        Map<Long, Author> authorMap = authorService.findAllByIds(authorIds);

        // Book 객체와 대응하는 Author 객체를 Map으로 매핑하여 반환
        return books.stream()
            .collect(Collectors.toMap(
                book -> book,
                book -> authorMap.get(book.authorId())
            ));
    }
}
```
```text
[@BatchMapping 핵심 동작 방식]
• GraphQL Java의 DataLoader를 수동 등록할 필요 없이 Spring이 런타임에 자동 주입
• 동일 실행 컨텍스트(Event Loop/Execution loop) 내의 Book 필드 요청을 한곳에 취합하여 1회 배치 조회 실행
• 반환 타입: Map<부모, 자식> 또는 Flux<자식> (순서 보장형) 지원
```

## 16. Spring 예외 처리 & 보안 (@GraphQlExceptionHandler & Security)
```java
// 1. 전역 GraphQL 예외 핸들러 (@ControllerAdvice)
@ControllerAdvice
public class GraphQlExceptionResolver {

    @GraphQlExceptionHandler
    public GraphQLError handleNotFound(EntityNotFoundException ex, DataFetchingEnvironment env) {
        return GraphQLError.newError()
            .errorType(ErrorType.NOT_FOUND)
            .message(ex.getMessage())
            .path(env.getExecutionStepInfo().getPath())
            .location(env.getField().getSourceLocation())
            .extensions(Map.of(
                "errorCode", "RESOURCE_NOT_FOUND",
                "timestamp", Instant.now().toString()
            ))
            .build();
    }
}
```
```java
// 2. Spring Security 연동 (메서드 보안 적용)
@Controller
public class SecureAdminController {

    // Spring Security의 @PreAuthorize를 컨트롤러 메서드에 그대로 적용 가능!
    @PreAuthorize("hasRole('ADMIN')")
    @MutationMapping
    public Boolean deleteBook(@Argument Long id) {
        bookService.delete(id);
        return true;
    }

    // 현재 인증된 사용자 Principal 주입
    @QueryMapping
    public UserProfile me(@AuthenticationPrincipal CustomUserDetails user) {
        return user.toProfile();
    }
}
```
💬
GraphQL 핵심 치트시트

의견 및 질문

댓글 수정

댓글 삭제
