GraphQL API 설계 패턴 가이드: Best Practices for Scalable API Design

최근 몇 년간 GraphQL은 데이터 페칭의 효율성과 유연성을 제공하며 현대 웹 및 모바일 애플리케이션 개발에 있어 중요한 API 기술로 자리매김했습니다. REST API의 고질적인 문제였던 오버페칭(over-fetching)과 언더페칭(under-fetching)을 해결하며 클라이언트 요구사항에 최적화된 데이터 응답을 가능하게 합니다. 하지만 GraphQL의 강력한 기능을 제대로 활용하고 확장 가능한(scalable) API를 구축하기 위해서는 체계적인 설계 패턴과 모범 사례를 이해하는 것이 필수적입니다. 이 글에서는 Node.js 환경에서의 백엔드 개발을 중심으로 GraphQL API를 효율적으로 설계하고 구축하기 위한 핵심 패턴들을 심도 있게 다룹니다.

GraphQL 기본 개념 및 REST API와의 차이점

GraphQL은 API를 위한 쿼리 언어이자 서버 측 런타임입니다. 클라이언트가 필요한 데이터를 정확히 요청할 수 있도록 하며, 서버는 요청된 데이터만을 응답합니다. 이는 REST API가 여러 엔드포인트와 고정된 데이터 구조를 가지는 것과 대조적입니다.

GraphQL의 핵심 요소

• 스키마 (Schema): API가 제공할 수 있는 모든 데이터 타입과 필드를 정의합니다. Query, Mutation, Subscription 타입이 포함됩니다.
• 쿼리 (Query): 데이터를 조회하는 작업입니다. 클라이언트가 필요한 필드만을 선택적으로 요청할 수 있습니다.
• 뮤테이션 (Mutation): 데이터를 생성, 수정, 삭제하는 작업입니다. REST의 POST, PUT, DELETE와 유사합니다.
• 서브스크립션 (Subscription): 실시간으로 데이터 변경 사항을 클라이언트에 푸시하는 기능입니다. 웹소켓을 기반으로 구현됩니다.
• 리졸버 (Resolver): 스키마에 정의된 각 필드가 요청되었을 때, 실제 데이터를 가져오는 함수입니다. 데이터베이스, 외부 API 등 다양한 데이터 소스와 연동됩니다.

REST API와의 비교

특징	REST API	GraphQL API
엔드포인트	리소스별 다수의 엔드포인트 (/users, /posts)	단일 엔드포인트 (/graphql)
데이터 페칭	고정된 데이터 구조, 오버/언더페칭 발생 가능	클라이언트 요청에 따라 유연하게 데이터 페칭
데이터 구조	서버가 정의한 고정된 데이터 구조	스키마를 통해 클라이언트가 요청하는 구조 결정
버전 관리	URI 버전 관리 (/v1/users)	스키마 진화로 버전 관리 필요성 감소
복잡성	여러 번의 요청으로 데이터 조합 필요	단일 요청으로 복잡한 데이터 조합 가능

GraphQL은 특히 복잡한 데이터 관계를 가지는 애플리케이션이나, 클라이언트 요구사항이 빠르게 변화하는 환경에서 큰 이점을 제공합니다.

GraphQL 스키마 디자인 패턴

GraphQL API의 핵심은 스키마입니다. 잘 설계된 스키마는 API의 사용성과 유지보수성을 크게 향상시킵니다. 스키마를 디자인할 때 고려해야 할 몇 가지 패턴이 있습니다.

1. Type-First (Schema-First) 디자인

스키마 정의 언어(SDL, Schema Definition Language)를 사용하여 먼저 스키마를 정의하고, 그 스키마에 맞춰 리졸버를 구현하는 방식입니다.

# schema.graphql
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

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

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

type Mutation {
  createUser(name: String!, email: String!): User!
  createPost(title: String!, content: String!, authorId: ID!): Post!
}

장점:

• API의 계약(contract)이 명확하여 클라이언트-서버 간 협업 용이.
• 스키마를 문서화하기 좋음.
• 개발 초기에 API의 전체적인 구조를 파악하기 쉬움.

단점:

• 스키마와 리졸버 코드 간의 동기화 문제 발생 가능.

2. Code-First (Module-First) 디자인

프로그래밍 언어(Node.js의 경우 TypeScript/JavaScript)를 사용하여 스키마를 정의하고, 동시에 리졸버를 구현하는 방식입니다. TypeGraphQL, NestJS 등에서 많이 사용됩니다.

// user.resolver.ts (예시)
import { Resolver, Query, Mutation, Arg, Field, ObjectType, ID } from 'type-graphql';

@ObjectType()
class User {
  @Field(type => ID)
  id: string;

  @Field()
  name: string;

  @Field()
  email: string;

  @Field(type => [Post]) // Post 타입은 별도로 정의
  posts: Post[];
}

@Resolver(User)
export class UserResolver {
  @Query(type => User, { nullable: true })
  async user(@Arg("id") id: string): Promise<User | undefined> {
    // 데이터베이스에서 사용자 조회 로직
    return { id, name: "Test User", email: "test@example.com", posts: [] };
  }

  @Query(type => [User])
  async users(): Promise<User[]> {
    // 데이터베이스에서 모든 사용자 조회 로직
    return [];
  }

  @Mutation(type => User)
  async createUser(
    @Arg("name") name: string,
    @Arg("email") email: string
  ): Promise<User> {
    // 사용자 생성 로직
    return { id: "new-id", name, email, posts: [] };
  }
}

장점:

• 스키마와 리졸버 코드가 함께 있어 개발 생산성 향상.
• TypeScript의 타입 추론 기능을 활용하여 타입 안정성 확보.

단점:

• API의 계약이 코드로만 정의되어 있어, 비개발자나 다른 팀이 API 구조를 파악하기 어려울 수 있음.
• 특정 라이브러리에 종속적일 수 있음.

어떤 패턴을 선택하든, GraphQL 스키마는 명확하고 직관적이며 일관성 있는 네이밍 컨벤션을 따르는 것이 중요합니다. 또한, 필드 레벨의 리졸버 구현을 통해 데이터 페칭 로직을 분리하고, 불필요한 필드를 요청하지 않도록 설계해야 합니다.

데이터 페칭 최적화: N+1 문제 해결 (DataLoader 패턴)

GraphQL의 유연한 쿼리 기능은 클라이언트가 한 번의 요청으로 여러 리소스의 중첩된 데이터를 가져올 수 있게 합니다. 하지만 이로 인해 흔히 "N+1 문제"라고 불리는 성능 문제가 발생할 수 있습니다.

N+1 문제란?

예를 들어, users 쿼리를 통해 여러 사용자를 가져오고, 각 사용자의 posts 목록을 가져오는 시나리오를 생각해봅시다.

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

일반적인 리졸버 구현에서는 다음과 같은 일이 발생할 수 있습니다:

1. users 리졸버가 모든 사용자를 가져오기 위해 1번의 데이터베이스 쿼리를 실행합니다.
2. 각 사용자 객체에 대해 posts 리졸버가 호출되어, 해당 사용자의 게시물을 가져오기 위해 N번의 데이터베이스 쿼리를 실행합니다.

총 1 + N번의 데이터베이스 쿼리가 발생하며, N이 커질수록 성능 저하가 심해집니다.

DataLoader를 이용한 해결

DataLoader는 페이스북에서 개발한 유틸리티 라이브러리로, N+1 문제를 해결하는 데 효과적입니다. DataLoader는 두 가지 핵심 원리로 작동합니다:

1. 배칭 (Batching): 동일한 이벤트 루프 틱 내에서 여러 번 호출된 데이터를 한 번의 배치 요청으로 묶어 처리합니다.
2. 캐싱 (Caching): 이미 로드된 데이터를 캐싱하여 중복 요청을 방지합니다.

DataLoader 구현 예시 (Node.js)

// loaders/userLoader.ts
import DataLoader from 'dataloader';
import { db } from '../db'; // 데이터베이스 연결 모듈 가정

// 사용자 ID 배열을 받아 사용자 객체 배열을 반환하는 배치 함수
async function batchUsers(ids: readonly string[]) {
  const users = await db.users.findMany({
    where: {
      id: { in: ids as string[] },
    },
  });
  // DataLoader는 요청된 ID 순서대로 결과를 반환해야 합니다.
  const userMap = new Map(users.map(user => [user.id, user]));
  return ids.map(id => userMap.get(id));
}

export const userLoader = new DataLoader(batchUsers);

// loaders/postLoader.ts
import DataLoader from 'dataloader';
import { db } from '../db';

async function batchPosts(userIds: readonly string[]) {
  const posts = await db.posts.findMany({
    where: {
      authorId: { in: userIds as string[] },
    },
  });
  const postsByUserId = new Map<string, any[]>();
  posts.forEach(post => {
    const existingPosts = postsByUserId.get(post.authorId) || [];
    existingPosts.push(post);
    postsByUserId.set(post.authorId, existingPosts);
  });
  return userIds.map(userId => postsByUserId.get(userId) || []);
}

export const postLoader = new DataLoader(batchPosts);

리졸버에서 DataLoader 사용 예시

// resolvers/user.resolver.ts
import { userLoader, postLoader } from '../loaders'; // DataLoader 인스턴스 임포트

const resolvers = {
  Query: {
    users: async (parent, args, context) => {
      // 모든 사용자 ID를 가져온다고 가정
      const userIds = await db.users.findMany().then(users => users.map(u => u.id));
      return userIds.map(id => context.loaders.userLoader.load(id)); // DataLoader를 통해 사용자 조회
    },
    user: async (parent, { id }, context) => {
      return context.loaders.userLoader.load(id);
    },
  },
  User: {
    posts: async (parent, args, context) => {
      // parent.id (사용자 ID)를 사용하여 DataLoader를 통해 게시물 조회
      return context.loaders.postLoader.load(parent.id);
    },
  },
};

// 컨텍스트에 DataLoader 인스턴스 주입 (예: Apollo Server)
// const server = new ApolloServer({
//   typeDefs,
//   resolvers,
//   context: () => ({
//     loaders: {
//       userLoader: userLoader,
//       postLoader: postLoader,
//     }
//   })
// });

DataLoader를 사용하면, users 쿼리에서 각 사용자의 posts를 요청하더라도, 모든 postLoader.load(userId) 호출이 한 번의 데이터베이스 쿼리로 묶여 실행됩니다. 이는 GraphQL API의 성능을 크게 향상시키는 가장 중요한 패턴 중 하나입니다.

에러 핸들링 및 유효성 검사

GraphQL은 기본적으로 에러가 발생하면 응답의 errors 배열에 에러 정보를 포함합니다. 하지만 클라이언트가 이해하기 쉽고 예측 가능한 에러 처리를 위해서는 에러를 구조화하는 것이 중요합니다.

1. 커스텀 에러 타입 정의

일반적인 HTTP 상태 코드 대신, GraphQL 스키마 내에서 커스텀 에러 타입을 정의하여 특정 비즈니스 로직 에러를 명확하게 전달할 수 있습니다.

# schema.graphql
interface MutationError {
  message: String!
  code: String!
}

type UserNotFoundError implements MutationError {
  message: String!
  code: String!
  userId: ID!
}

type InvalidInputError implements MutationError {
  message: String!
  code: String!
  field: String
}

type UpdateUserPayload {
  user: User
  error: MutationError
}

type Mutation {
  updateUser(id: ID!, name: String): UpdateUserPayload!
}

이렇게 하면 updateUser 뮤테이션의 결과로 User 객체 또는 MutationError 인터페이스를 구현하는 특정 에러 객체를 받을 수 있습니다.

2. Input Type을 이용한 유효성 검사

뮤테이션의 인자(arguments)를 정의할 때 Input 타입을 사용하여 복잡한 입력을 구조화하고, 서버 측에서 유효성 검사를 수행합니다.

# schema.graphql
input CreateUserInput {
  name: String!
  email: String!
  password: String!
}

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

Node.js 백엔드에서는 class-validator와 같은 라이브러리를 사용하여 CreateUserInput 객체에 대한 유효성 검사를 쉽게 구현할 수 있습니다.

보안 고려사항: 인증, 권한 부여, 쿼리 복잡도 제한

GraphQL API는 단일 엔드포인트와 유연한 쿼리 특성으로 인해 보안에 특별한 주의가 필요합니다.

1. 인증 (Authentication) 및 권한 부여 (Authorization)

• 인증: JWT(JSON Web Token) 또는 OAuth2와 같은 표준 인증 메커니즘을 사용하여 클라이언트의 신원을 확인합니다. 보통 HTTP 헤더(예: Authorization: Bearer <token>)를 통해 토큰을 전달받고, GraphQL 컨텍스트(context)에서 사용자 정보를 파싱하여 리졸버에서 사용할 수 있도록 합니다.
• 권한 부여: 특정 필드나 뮤테이션에 접근할 수 있는 사용자 권한을 제어합니다.
  • 리졸버 레벨: 각 리졸버 함수 내에서 직접 권한 검사 로직을 구현합니다.
  • 디렉티브 (Directives): @auth, @hasRole과 같은 커스텀 디렉티브를 스키마에 정의하여 선언적으로 권한을 적용할 수 있습니다. 이는 스키마를 더 읽기 쉽게 만들고, 권한 로직을 재사용 가능하게 합니다.

# 스키마 디렉티브 예시
directive @auth(requires: Role = ADMIN) on FIELD_DEFINITION | OBJECT

enum Role {
  ADMIN
  REVIEWER
  USER
  UNKNOWN
}

type User @auth(requires: ADMIN) { # User 타입 전체에 ADMIN 권한 요구
  id: ID!
  name: String!
  email: String! @auth(requires: USER) # email 필드는 USER 권한 요구
}

type Query {
  me: User @auth # 로그인된 사용자만 접근 가능
  users: [User!]! @auth(requires: ADMIN) # ADMIN만 모든 사용자 조회 가능
}

2. 쿼리 복잡도 및 깊이 제한

GraphQL의 유연성으로 인해 클라이언트는 매우 깊거나 복잡한 쿼리를 요청할 수 있습니다. 이는 서버에 과도한 부하를 주거나 서비스 거부(DoS) 공격으로 이어질 수 있습니다.

• 쿼리 깊이 제한 (Query Depth Limiting): 쿼리가 중첩될 수 있는 최대 깊이를 설정합니다. (예: 5단계 이상 중첩 금지).
• 쿼리 복잡도 제한 (Query Complexity Limiting): 각 필드에 가중치를 부여하고, 쿼리 전체의 총 가중치가 특정 임계값을 초과하지 않도록 제한합니다. graphql-query-complexity와 같은 라이브러리를 사용하여 구현할 수 있습니다.

3. Rate Limiting

특정 시간 동안 클라이언트가 보낼 수 있는 요청 수를 제한하여 과도한 요청으로부터 서버를 보호합니다. IP 주소, 인증 토큰 등을 기준으로 제한할 수 있습니다.

GraphQL API 아키텍처: Monolithic vs. Federated

GraphQL 서버를 구축하는 방법은 애플리케이션의 규모와 팀 구조에 따라 다양합니다.

1. Monolithic GraphQL 서버

단일 GraphQL 서버가 모든 스키마와 리졸버를 포함하고, 모든 데이터 소스(데이터베이스, REST API 등)에 직접 접근하는 형태입니다.

장점:

• 구현이 간단하고 초기 개발 속도가 빠름.
• 작은 규모의 애플리케이션에 적합.

단점:

• 코드베이스가 커지면 유지보수 및 확장이 어려움.
• 팀이 분리되어 있을 경우, 스키마 충돌 및 배포 복잡성 증가.

아키텍처 다이어그램 (텍스트):

+--------+           +------------------------+           +-------------+
| Client | <-------> | Monolithic GraphQL API | <-------> | Databases   |
+--------+           | (Node.js/Apollo Server)|           | (PostgreSQL)|
                     +------------------------+           | External    |
                                                          | Services    |
                                                          +-------------+

2. Federated GraphQL (스키마 연합)

여러 개의 독립적인 GraphQL 서비스(서브그래프, Subgraphs)를 구축하고, 이들을 하나의 GraphQL 게이트웨이(Gateway)를 통해 통합하여 하나의 통합된 스키마를 클라이언트에 제공하는 방식입니다. Apollo Federation이 대표적인 구현체입니다.

장점:

• 마이크로서비스 아키텍처와 잘 어울림.
• 각 서브그래프는 독립적으로 개발, 배포, 확장 가능.
• 대규모 조직에서 여러 팀이 각자의 도메인에 맞는 GraphQL API를 소유하고 관리할 수 있음.

단점:

• 초기 설정 및 복잡성 증가.
• 게이트웨이와 서브그래프 간의 통신 오버헤드.

아키텍처 다이어그램 (텍스트):

+--------+           +-------------------+           +------------------+
| Client | <-------> | GraphQL Gateway   | <-------> | User Subgraph    |
+--------+           | (Apollo Router)   |           | (Node.js/GraphQL)|
                     +-------------------+           +------------------+
                                   |                   +------------------+
                                   +-----------------> | Product Subgraph |
                                   |                   | (Node.js/GraphQL)|
                                   |                   +------------------+
                                   |                   +------------------+
                                   +-----------------> | Order Subgraph   |
                                                       | (Node.js/GraphQL)|
                                                       +------------------+

federated 아키텍처는 특히 대규모 서비스와 팀에서 높은 확장성과 유연성을 제공합니다. 각 서브그래프는 자체 데이터베이스를 가질 수 있으며, 다른 팀의 서브그래프에 영향을 주지 않고 변경 사항을 배포할 수 있습니다.

GraphQL 캐싱 전략

GraphQL은 클라이언트가 필요한 데이터만 요청하므로 HTTP 캐싱(예: CDN)을 직접 적용하기 어렵습니다. 따라서 GraphQL에 특화된 캐싱 전략이 필요합니다.

1. 클라이언트 측 캐싱

• 정규화된 캐시 (Normalized Cache): Apollo Client, Relay와 같은 GraphQL 클라이언트는 페칭된 데이터를 ID를 기반으로 정규화하여 캐시합니다. 동일한 ID를 가진 객체는 캐시에서 한 번만 저장되며, 데이터가 업데이트되면 해당 객체를 사용하는 모든 UI 컴포넌트가 자동으로 갱신됩니다. 이는 클라이언트 측에서 N+1 문제와 유사한 중복 데이터 페칭을 방지하고 UI 렌더링 성능을 향상시킵니다.

2. 서버 측 캐싱

• DataLoader 캐싱: 위에서 설명했듯이, DataLoader는 동일한 이벤트 루프 틱 내에서 중복된 요청을 캐싱하여 데이터베이스 부하를 줄입니다.
• 응답 캐싱 (Response Caching): 완전한 GraphQL 쿼리 응답 자체를 캐시하는 방식입니다. 이는 주로 읽기 전용(Query) 작업에 유용하며, GET 요청으로 GraphQL 쿼리를 보내는 경우 HTTP 캐싱 메커니즘을 활용할 수도 있습니다. Apollo Server의 response caching 플러그인과 같은 도구를 사용할 수 있습니다.
• 데이터 소스 레벨 캐싱: 데이터베이스 쿼리 결과나 외부 API 호출 결과를 Redis 등 인메모리 캐시에 저장하여 재사용합니다. 이는 리졸버가 데이터를 가져오는 과정에서 직접 구현할 수 있습니다.

캐싱 전략은 애플리케이션의 특성과 데이터의 휘발성(volatility)을 고려하여 신중하게 선택하고 구현해야 합니다.

마무리

GraphQL API는 현대 애플리케이션의 복잡한 데이터 요구사항을 충족시키는 강력한 도구입니다. 이 가이드에서 다룬 스키마 디자인, 데이터 페칭 최적화(DataLoader), 에러 핸들링, 보안 고려사항, 그리고 아키텍처 및 캐싱 패턴들을 잘 이해하고 적용한다면, 확장 가능하고 유지보수하기 쉬운 고성능 GraphQL API를 성공적으로 구축할 수 있을 것입니다. GraphQL의 잠재력을 최대한 발휘하기 위해서는 초기 설계 단계부터 이러한 모범 사례들을 고려하는 것이 중요합니다.