GraphQL API Design Patterns: 확장 가능하고 견고한 백엔드 구축 가이드

최근 몇 년간 API 설계 패러다임에서 GraphQL은 기존 REST API의 한계를 극복하며 개발자들 사이에서 큰 인기를 얻고 있습니다. 클라이언트가 필요한 데이터를 정확히 요청할 수 있도록 하여 네트워크 효율성을 높이고, 개발 생산성을 향상시키는 강력한 도구로 자리매김했죠. 하지만 GraphQL의 유연성은 동시에 복잡성을 내포하고 있으며, 잘못 설계된 API는 성능 저하, 유지보수 어려움, 보안 취약점 등 다양한 문제를 야기할 수 있습니다.

이 글에서는 Node.js 환경에서 GraphQL 백엔드 API를 구축할 때 고려해야 할 핵심 Design Patterns과 모범 사례들을 심층적으로 다룹니다. 스키마 설계 원칙부터 데이터 페칭 최적화, 뮤테이션 관리, 인증/권한 부여, 에러 핸들링에 이르기까지, 확장 가능하고 견고한 GraphQL API를 설계하기 위한 실질적인 가이드를 제공하고자 합니다.

GraphQL 개요 및 REST API와의 비교

GraphQL은 Facebook이 개발한 API를 위한 쿼리 언어이자 런타임입니다. 클라이언트가 서버에 필요한 데이터 구조를 정확히 명시하여 요청할 수 있게 함으로써, REST API에서 흔히 발생하는 Over-fetching (필요 이상의 데이터 수신) 또는 Under-fetching (필요한 데이터를 얻기 위해 여러 번 요청) 문제를 해결합니다.

GraphQL의 핵심 개념은 다음과 같습니다.

• Schema: API가 제공하는 데이터의 형태를 정의하는 타입 시스템입니다. 클라이언트와 서버 간의 계약 역할을 합니다.
• Query: 데이터를 조회하는 요청입니다.
• Mutation: 데이터를 생성, 수정, 삭제하는 요청입니다.
• Subscription: 실시간으로 데이터 변경 사항을 클라이언트에게 푸시하는 기능입니다.

REST API와 GraphQL의 주요 차이점을 비교하면 다음과 같습니다.

특징	REST API	GraphQL
엔드포인트	리소스마다 여러 엔드포인트	단일 엔드포인트 (일반적으로 /graphql)
데이터 페칭	Over-fetching/Under-fetching 발생 가능	클라이언트가 필요한 데이터만 정확히 요청
버전 관리	URL 기반 (예: /v1/users), 헤더 기반	스키마 진화 (필드 추가/deprecated), 비파괴적 변경
개발 생산성	클라이언트가 여러 요청을 조합해야 할 수 있음	단일 요청으로 필요한 모든 데이터 획득 가능
데이터 구조	서버에서 정의한 고정된 응답 구조	클라이언트가 요청한 구조에 따라 동적으로 응답

GraphQL 서버의 일반적인 아키텍처는 다음과 같습니다.

Client (Web/Mobile Application)
      |
      v
[ GraphQL Gateway (Optional, API Gateway) ]
      |
      v
[ GraphQL Server (Node.js, Apollo Server, Express-GraphQL) ]
      |
      +---> [ Resolvers ]
      |         |
      v         v
[ Data Sources (Database, REST APIs, Microservices, Caching Layer) ]

클라이언트의 GraphQL 요청은 GraphQL Server로 전달되고, 서버는 스키마 정의에 따라 Resolvers를 호출하여 실제 데이터베이스나 다른 API 등 Data Sources에서 데이터를 가져와 클라이언트가 요청한 형태로 응답합니다.

GraphQL API 스키마 설계 원칙

GraphQL API의 핵심은 스키마에 있습니다. 잘 설계된 스키마는 API의 사용 편의성, 확장성, 유지보수성을 크게 향상시킵니다. 다음은 스키마 설계 시 고려해야 할 주요 원칙들입니다.

1. 명확하고 직관적인 타입 및 필드 명명 규칙

스키마의 모든 타입, 필드, 인자는 명확하고 일관된 명명 규칙을 따라야 합니다. 일반적으로 CamelCase를 사용하며, 타입 이름은 단수형으로, 필드 이름은 해당 필드가 나타내는 값을 명확히 설명하도록 작성합니다.

• 타입 (Type): User, Post, Comment (단수형, PascalCase)
• 필드 (Field): userName, postTitle, createdAt (CamelCase)
• 인자 (Argument): userId, postId (CamelCase)

2. 풍부한 타입 시스템 활용

GraphQL은 강력한 타입 시스템을 제공합니다. 이를 효과적으로 활용하여 데이터의 유효성을 보장하고 클라이언트 개발자가 API를 쉽게 이해하도록 돕습니다.

• 객체 타입 (Object Type): 데이터 모델을 표현합니다. (예: User, Product)
• 스칼라 타입 (Scalar Type): 기본 데이터 유형 (String, Int, Float, Boolean, ID) 외에 Date, JSON 등 커스텀 스칼라를 정의하여 복잡한 데이터 타입을 표현할 수 있습니다.
• 입력 타입 (Input Type): 뮤테이션의 인자로 사용될 복잡한 객체를 정의합니다. (예: CreateUserInput)
• 열거 타입 (Enum Type): 특정 값들의 집합을 나타냅니다. (예: PostStatus: [PUBLISHED, DRAFT])
• 인터페이스 (Interface): 공통 필드를 가진 여러 타입이 구현할 수 있는 추상 타입을 정의합니다. (예: Node 인터페이스를 구현하는 User, Post)
• 유니온 (Union): 서로 다른 타입을 반환할 수 있는 필드를 정의합니다. (예: SearchResult = User | Post)

3. 관계 명확화 및 GraphQL-First 접근 방식

데이터 모델 간의 관계를 스키마에 명확하게 반영해야 합니다. 예를 들어, User와 Post 간의 관계를 User 타입 내에 posts: [Post!]! 필드로 정의하여 클라이언트가 쉽게 관계된 데이터를 탐색할 수 있도록 합니다.

GraphQL-First 접근 방식은 데이터베이스 스키마나 백엔드 서비스 API에 얽매이지 않고, 클라이언트가 필요로 하는 데이터를 중심으로 스키마를 설계하는 것을 의미합니다. 이후 해당 스키마에 맞춰 백엔드 데이터베이스 모델 및 리졸버를 구현합니다.

# 스키마 정의 예시

# 사용자 정보
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]! # 사용자가 작성한 게시물 목록
}

# 게시물 정보
type Post {
  id: ID!
  title: String!
  content: String!
  author: User! # 게시물의 작성자
  comments: [Comment!]! # 게시물에 달린 댓글 목록
}

# 댓글 정보
type Comment {
  id: ID!
  text: String!
  author: User! # 댓글 작성자
  post: Post! # 댓글이 달린 게시물
}

# 쿼리 정의
type Query {
  user(id: ID!): User # 특정 사용자 조회
  users: [User!]! # 모든 사용자 조회
  post(id: ID!): Post # 특정 게시물 조회
  posts: [Post!]! # 모든 게시물 조회
}

# 뮤테이션 입력 타입 정의
input CreatePostInput {
  title: String!
  content: String!
  authorId: ID!
}

# 뮤테이션 정의
type Mutation {
  createPost(input: CreatePostInput!): Post! # 게시물 생성
}

데이터 페칭 패턴: N+1 문제와 DataLoader

GraphQL의 유연한 쿼리는 클라이언트가 중첩된 관계의 데이터를 한 번의 요청으로 가져올 수 있게 하지만, 이는 N+1 문제로 이어질 수 있습니다. N+1 문제는 부모 객체를 조회한 후, 해당 부모 객체 각각에 연결된 자식 객체들을 조회하기 위해 N번의 추가적인 데이터베이스 쿼리가 발생하는 상황을 의미합니다. 이는 백엔드 서버의 성능을 심각하게 저하시킬 수 있습니다.

예를 들어, 100명의 사용자와 각 사용자가 작성한 게시물을 조회하는 쿼리를 생각해 봅시다.

query GetUsersWithPosts {
  users {
    id
    name
    posts {
      id
      title
    }
  }
}

이 쿼리에서 users 리졸버가 100명의 사용자를 반환하면, 각 User 객체의 posts 필드를 해석하기 위해 100번의 추가적인 posts 조회 데이터베이스 쿼리가 발생할 수 있습니다 (총 1 + 100 = 101번의 쿼리).

DataLoader를 이용한 N+1 문제 해결

N+1 문제를 해결하기 위한 가장 효과적인 패턴 중 하나는 DataLoader입니다. DataLoader는 Facebook에서 개발한 라이브러리로, 다음 두 가지 원칙을 통해 데이터베이스 쿼리 수를 최적화합니다.

1. 배치 (Batching): 동일한 이벤트 루프 틱 내에서 발생한 여러 요청을 한 번의 데이터베이스 쿼리로 묶어 처리합니다.
2. 캐싱 (Caching): 한 번 로드된 데이터를 메모리에 캐싱하여 중복 요청 시 데이터베이스 쿼리 없이 캐시된 데이터를 반환합니다.

Node.js 환경에서 DataLoader를 사용하는 예시는 다음과 같습니다.

// userLoader.js
const DataLoader = require('dataloader');

// N개의 ID를 받아 한 번에 DB에서 사용자들을 조회하는 함수
async function batchUsers(ids) {
  console.log(`User IDs to fetch: ${ids.join(', ')}`); // 실제 DB 쿼리가 한 번만 발생함을 확인
  // 실제 데이터베이스 조회 (예: SQL의 IN 쿼리)
  const users = await db.getUsersByIds(ids); 
  // 요청된 ID 순서에 맞춰 사용자 객체 배열을 반환해야 합니다.
  return ids.map(id => users.find(user => user.id === id) || null);
}

// DataLoader 인스턴스를 생성하는 팩토리 함수
function createUserLoader() {
  return new DataLoader(batchUsers);
}

module.exports = createUserLoader;

GraphQL 서버의 context에 DataLoader 인스턴스를 주입하여 모든 리졸버에서 접근할 수 있도록 합니다.

// server.js (Apollo Server context setup)
const { ApolloServer } = require('apollo-server');
const typeDefs = require('./schema');
const resolvers = require('./resolvers');
const createUserLoader = require('./userLoader');
const db = require('./db'); // 가상의 데이터베이스 모듈

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: () => ({
    // 요청당 새로운 DataLoader 인스턴스를 생성하여 캐시 충돌 방지
    userLoader: createUserLoader(), 
    db, // 데이터베이스 인스턴스
  }),
});

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

리졸버에서는 context를 통해 DataLoader를 사용하여 데이터를 효율적으로 페칭합니다.

// resolvers.js
const resolvers = {
  Query: {
    users: async (parent, args, { db }) => {
      return db.getAllUsers();
    },
    posts: async (parent, args, { db }) => {
      return db.getAllPosts();
    },
  },
  User: {
    posts: async (parent, args, { db }) => {
      // User의 posts 필드 리졸버. DataLoader 사용 없이 직접 조회 시 N+1 문제 발생 가능
      // return db.getPostsByAuthorId(parent.id);
      // DataLoader는 User 타입이 아닌 Post 타입의 author 필드에서 주로 사용
      // User 타입의 posts 필드는 일반적으로 Post 타입의 authorId를 기준으로 조회
      return db.getPostsByAuthorId(parent.id); // 이 부분은 DataLoader의 배치 대상이 아님.
                                            // Post 타입의 author 필드에서 User 정보를 로드할 때 DataLoader가 유용.
    },
  },
  Post: {
    author: async (parent, args, { userLoader }) => {
      // Post의 author 필드 리졸버. DataLoader를 사용하여 N+1 문제 해결
      return userLoader.load(parent.authorId);
    },
  },
  Comment: {
    author: async (parent, args, { userLoader }) => {
      // Comment의 author 필드 리졸버.
      return userLoader.load(parent.authorId);
    },
  },
  // ... (다른 리졸버들)
};

이 예시에서 Post 타입의 author 필드를 조회할 때 userLoader.load(parent.authorId)를 사용합니다. 여러 Post 객체가 동시에 author 필드를 요청하면, DataLoader는 이 모든 authorId를 모아 batchUsers 함수를 한 번만 호출하여 데이터베이스 쿼리 수를 획기적으로 줄입니다.

뮤테이션(Mutation) 설계 모범 사례

GraphQL에서 데이터를 변경하는 작업은 뮤테이션을 통해 이루어집니다. 뮤테이션 설계는 API의 일관성과 사용성을 결정하는 중요한 부분입니다.

1. 단일 책임 원칙 (Single Responsibility Principle)

하나의 뮤테이션은 하나의 명확한 작업을 수행해야 합니다. 예를 들어, createPost는 게시물 생성만을 담당하고, updatePost는 게시물 수정만을 담당해야 합니다. 복잡한 비즈니스 로직을 하나의 뮤테이션에 담기보다는 여러 개의 작은 뮤테이션으로 분리하는 것이 좋습니다.

2. 입력 타입 (Input Type) 활용

뮤테이션의 인자가 많거나 복잡할 경우, Input Type을 사용하여 인자들을 캡슐화하는 것이 좋습니다. 이는 뮤테이션 시그니처를 깔끔하게 유지하고, 클라이언트 개발자가 필요한 인자를 쉽게 파악할 수 있도록 돕습니다.

# 입력 타입 정의
input CreatePostInput {
  title: String!
  content: String!
  authorId: ID!
  tags: [String!]
}

# 뮤테이션 정의
type Mutation {
  createPost(input: CreatePostInput!): Post!
}

3. 페이로드(Payload) 설계

뮤테이션의 결과로 무엇을 반환할 것인지 명확하게 정의하는 것이 중요합니다. 일반적으로 뮤테이션이 성공적으로 수행되었는지 여부, 변경된 객체, 그리고 발생할 수 있는 에러 정보를 포함하는 Payload Type을 반환하는 것이 모범 사례입니다.

# 뮤테이션 결과 페이로드 타입 정의
type CreatePostPayload {
  success: Boolean! # 작업 성공 여부
  message: String # 사용자에게 보여줄 메시지 (옵션)
  post: Post # 생성된 게시물 객체
}

type Mutation {
  createPost(input: CreatePostInput!): CreatePostPayload!
}

리졸버 구현 예시:

// resolvers.js
const resolvers = {
  Mutation: {
    createPost: async (parent, { input }, { db }) => {
      try {
        // 입력 유효성 검사
        if (!input.title || input.title.length < 5) {
          throw new Error('제목은 최소 5자 이상이어야 합니다.');
        }

        const newPost = await db.createPost(input); // DB에 게시물 생성
        return {
          success: true,
          message: '게시글이 성공적으로 생성되었습니다.',
          post: newPost,
        };
      } catch (error) {
        return {
          success: false,
          message: error.message,
          post: null, // 실패 시 post는 null
        };
      }
    },
  },
};

이러한 페이로드 설계는 클라이언트가 뮤테이션 결과를 예측 가능하고 일관된 방식으로 처리할 수 있도록 돕습니다.

인증 및 권한 부여(Authentication & Authorization) 패턴

GraphQL API에서 인증(Authentication)과 권한 부여(Authorization)는 매우 중요합니다. Node.js 백엔드 서버에서 이를 구현하는 일반적인 패턴은 다음과 같습니다.

1. 인증 (Authentication)

사용자를 식별하는 과정입니다. JWT (JSON Web Token)를 사용하여 HTTP 헤더를 통해 토큰을 전달받고, 이를 검증하여 사용자 정보를 추출하는 방식이 널리 사용됩니다.

Apollo Server와 같은 GraphQL 프레임워크는 context 객체를 통해 요청별 상태를 관리할 수 있습니다. context에 인증된 사용자 정보를 주입하여 모든 리졸버에서 접근할 수 있도록 합니다.

// server.js (Apollo Server context setup)
const { ApolloServer } = require('apollo-server');
const jwt = require('jsonwebtoken'); // JWT 라이브러리

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => {
    // HTTP 요청 헤더에서 Authorization 토큰 추출
    const token = req.headers.authorization || '';
    let user = null;

    try {
      if (token) {
        // 'Bearer ' 접두사를 제거하고 토큰 검증
        user = jwt.verify(token.replace('Bearer ', ''), process.env.JWT_SECRET);
      }
    } catch (error) {
      // 토큰이 유효하지 않은 경우 (만료, 변조 등)
      console.error('Invalid token:', error.message);
      // user는 null로 유지되거나, 특정 에러를 context에 추가할 수 있습니다.
    }

    // 모든 리졸버에서 user 객체에 접근 가능
    return { user, loaders: {} /* ... DataLoader 인스턴스 */ };
  },
});

2. 권한 부여 (Authorization)

인증된 사용자가 특정 리소스에 접근하거나 특정 작업을 수행할 권한이 있는지 확인하는 과정입니다.

• 리졸버 레벨 권한 부여: 가장 일반적인 방법으로, 각 리졸버 함수 내에서 context 객체의 user 정보를 기반으로 권한을 확인합니다. 권한이 없는 경우 에러를 발생시킵니다.

• 스키마 디렉티브 활용 (Custom Directives): GraphQL Schema에 @auth, @hasRole과 같은 커스텀 디렉티브를 정의하여 선언적으로 권한을 부여할 수 있습니다. 이는 스키마를 더 읽기 쉽게 만들고, 중복 코드를 줄이는 데 도움이 됩니다.

    # 스키마에 권한 디렉티브 정의 (예시)
    directive @auth(requires: [Role!] = [ADMIN]) on FIELD_DEFINITION | OBJECT

    enum Role {
      USER
      ADMIN
    }

    type User @auth(requires: [USER, ADMIN]) { # User 타입