GraphQL API Design Patterns: Node.js 백엔드 개발 가이드

현대 웹 및 모바일 애플리케이션 개발에서 API는 클라이언트와 서버 간의 핵심적인 통신 창구입니다. REST API가 오랫동안 표준으로 자리매김했지만, 복잡한 데이터 요구사항과 다양한 클라이언트 환경에 대응하기 위해 GraphQL이 강력한 대안으로 부상하고 있습니다. GraphQL은 클라이언트가 필요한 데이터를 정확히 요청할 수 있도록 하여 오버페칭(Over-fetching)과 언더페칭(Under-fetching) 문제를 해결하며, 유연하고 강력한 API를 구축할 수 있게 돕습니다.

이 글에서는 GraphQL API를 효과적으로 설계하고 구축하기 위한 핵심 디자인 패턴과 모범 사례들을 Node.js 백엔드 개발 관점에서 깊이 있게 다룹니다. 스키마 설계부터 데이터 페칭 최적화, 보안 및 에러 처리까지, 견고하고 확장 가능한 GraphQL API를 만들기 위한 여정을 함께 탐험해 보겠습니다.

GraphQL의 핵심 원리 이해

GraphQL은 API를 위한 쿼리 언어이자 런타임입니다. 클라이언트가 필요한 데이터를 한 번의 요청으로 가져올 수 있도록 하며, 서버는 정의된 스키마에 따라 요청을 처리합니다. 이 섹션에서는 GraphQL의 가장 기본적인 구성 요소들을 살펴보겠습니다.

스키마와 타입 시스템

GraphQL API의 핵심은 스키마(Schema)입니다. 스키마는 API가 제공하는 데이터의 형태와 클라이언트가 수행할 수 있는 작업(쿼리, 뮤테이션, 서브스크립션)을 정의합니다. 모든 GraphQL 서비스는 스키마 정의 언어(Schema Definition Language, SDL)로 작성된 타입 시스템을 가집니다.

# 스키마 정의 언어 (SDL) 예시

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

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

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

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

위 예시에서 User와 Post는 객체 타입(Object Type)이며, 각 필드는 특정 타입을 가집니다. !는 해당 필드가 null이 될 수 없음을 의미합니다. Query 타입은 데이터를 조회하는 엔트리 포인트이고, Mutation 타입은 데이터를 변경하는 엔트리 포인트입니다.

Query, Mutation, Subscription

• Query: 데이터를 읽거나 조회하는 작업입니다. REST의 GET 요청과 유사하지만, 클라이언트가 원하는 필드만 선택적으로 요청할 수 있다는 점에서 더욱 강력합니다.
• Mutation: 데이터를 생성, 수정, 삭제하는 작업입니다. REST의 POST, PUT, DELETE 요청과 유사합니다. 뮤테이션은 일반적으로 단일 루트 필드에서 시작하며, 여러 개의 뮤테이션을 하나의 요청으로 묶어 보낼 수도 있습니다.
• Subscription: 실시간으로 데이터를 구독하는 작업입니다. 주로 WebSocket을 통해 구현되며, 서버에서 특정 이벤트가 발생하면 클라이언트에 자동으로 데이터를 푸시(Push)합니다. 채팅 애플리케이션이나 실시간 알림 시스템에 유용합니다.

GraphQL API 아키텍처 설계

GraphQL 서버는 클라이언트 요청을 받아 스키마에 따라 데이터를 처리하고 응답하는 역할을 합니다. Node.js 환경에서 GraphQL API를 구축할 때 고려할 수 있는 일반적인 아키텍처 패턴을 살펴보겠습니다.

일반적인 GraphQL 서버 아키텍처

대부분의 GraphQL 서버는 다음과 같은 구성 요소를 가집니다.

+----------------+       +-------------------+       +-------------------+
|    Client      | ----> | GraphQL Gateway   | ----> | GraphQL Service   |
| (Web/Mobile)   |       | (Apollo Server)   |       | (Resolvers)       |
+----------------+       +-------------------+       +-------------------+
                                   |                           |
                                   V                           V
                          +-------------------+       +-------------------+
                          |     Data Sources  | <---> |    Databases      |
                          | (REST APIs, DBs)  |       | (PostgreSQL, NoSQL)|
                          +-------------------+       +-------------------+

• GraphQL Gateway: 클라이언트의 모든 GraphQL 요청을 받는 단일 엔트리 포인트입니다. 요청을 파싱하고 유효성을 검사하며, 적절한 GraphQL 서비스로 라우팅하거나 직접 처리합니다. Apollo Server와 같은 라이브러리가 이 역할을 수행하기에 적합합니다.
• GraphQL Service: 스키마에 정의된 각 필드에 대한 데이터를 실제로 가져오는 로직(Resolver)을 포함합니다. 이 서비스는 데이터베이스, 다른 REST API, 마이크로서비스 등 다양한 데이터 소스와 통신하여 데이터를 통합합니다.
• Data Sources: 실제 데이터가 저장되거나 관리되는 곳입니다. 관계형 데이터베이스(PostgreSQL, MySQL), NoSQL 데이터베이스(MongoDB, Redis), 혹은 기존에 구축된 REST API 등이 될 수 있습니다.

Node.js + Apollo Server 기반 아키텍처

Node.js 환경에서는 Apollo Server가 GraphQL 서버를 구축하는 데 가장 널리 사용되는 프레임워크 중 하나입니다. Express.js, Koa.js 등 다양한 HTTP 서버 프레임워크와 쉽게 통합됩니다.

// server.ts (간략화된 Apollo Server 설정 예시)
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { typeDefs } from './schema';
import { resolvers } from './resolvers';
import { PrismaClient } from '@prisma/client'; // 데이터 소스 예시

interface MyContext {
  prisma: PrismaClient;
}

const prisma = new PrismaClient();

const server = new ApolloServer<MyContext>({
  typeDefs,
  resolvers,
});

async function startApolloServer() {
  const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 },
    context: async ({ req }) => ({ prisma }), // 모든 resolver에 Prisma 클라이언트 주입
  });
  console.log(`🚀 Server ready at ${url}`);
}

startApolloServer();

이 아키텍처에서 typeDefs는 GraphQL 스키마를 정의하고, resolvers는 각 스키마 필드에 대한 데이터 페칭 로직을 구현합니다. context 객체를 통해 PrismaClient와 같은 데이터 소스 인스턴스를 모든 리졸버에서 쉽게 접근할 수 있도록 주입할 수 있습니다.

모놀리식 vs 마이크로서비스 환경에서의 GraphQL

• 모놀리식: 단일 GraphQL 서버가 모든 스키마와 리졸버를 관리하고, 모든 데이터 소스에 직접 접근합니다. 초기 개발 속도가 빠르고 관리가 단순하지만, 규모가 커지면 복잡성이 증가할 수 있습니다.
• 마이크로서비스: 여러 개의 독립적인 마이크로서비스가 각각의 GraphQL 스키마 조각을 가지며, GraphQL Gateway (예: Apollo Federation)가 이 스키마들을 하나로 합쳐(Schema Stitching 또는 Federation) 단일 GraphQL API를 제공합니다. 이는 각 서비스의 독립성을 유지하면서도 클라이언트에게는 통합된 뷰를 제공합니다.

효율적인 스키마 디자인 패턴

잘 설계된 GraphQL 스키마는 API의 사용성과 확장성을 결정하는 핵심 요소입니다. 다음은 몇 가지 중요한 스키마 디자인 패턴입니다.

객체 지향적 스키마 설계

GraphQL 스키마는 실제 세상의 객체와 그 관계를 반영하도록 설계되어야 합니다.

• 타입 간 관계: User와 Post처럼, 객체 간의 1대1, 1대다, 다대다 관계를 명확하게 정의합니다.
• 인터페이스 (Interfaces): 여러 타입이 공통 필드를 가질 때 인터페이스를 활용하여 코드 중복을 줄이고 다형성을 구현합니다. 예를 들어, Node 인터페이스는 모든 객체가 id 필드를 갖도록 강제할 수 있습니다.
• 유니온 (Unions): 특정 필드가 여러 타입 중 하나를 반환할 수 있을 때 유니온 타입을 사용합니다. 예를 들어, SearchResult는 Post나 User 중 하나를 반환할 수 있습니다.

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

union SearchResult = User | Post

Naming Conventions

일관된 Naming Convention은 스키마의 가독성을 높이고 사용자가 API를 쉽게 이해하도록 돕습니다.

• 타입 이름: PascalCase (예: User, Post).
• 필드 이름: camelCase (예: userName, createdAt).
• enum 값: ALL_CAPS (예: PENDING, APPROVED).
• Mutation 이름: 동사로 시작하는 camelCase (예: createUser, updatePost).

페이징 및 커서 기반 데이터 로딩

대량의 데이터를 효율적으로 처리하기 위해 페이징(Pagination)은 필수적입니다. GraphQL에서는 Relay Cursor Connections Specification을 따르는 것이 일반적입니다.

• Connection 패턴: edges와 pageInfo 필드를 포함하는 Connection 타입을 사용하여, 다음 페이지를 위한 커서(cursor)와 총 페이지 정보 등을 제공합니다.
• first, last, before, after 인자를 사용하여 데이터를 요청합니다.

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

type UserEdge {
  node: User!
  cursor: String!
}

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

type Query {
  users(first: Int, after: String): UserConnection!
}

Input Type 활용

Mutation의 인자가 많아지거나 복잡해질 때 Input Type을 사용하여 인자를 구조화하면 스키마의 가독성을 높이고 재사용성을 향상시킬 수 있습니다.

input CreateUserInput {
  name: String!
  email: String
}

input UpdatePostInput {
  id: ID!
  title: String
  content: String
}

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

데이터 Fetching 최적화 전략

GraphQL은 유연하지만, 잘못 설계되면 성능 문제가 발생하기 쉽습니다. 특히 N+1 문제와 같은 데이터베이스 쿼리 최적화는 백엔드 개발에서 매우 중요합니다.

N+1 문제와 DataLoader

N+1 문제는 GraphQL에서 가장 흔히 발생하는 성능 문제입니다. 예를 들어, posts를 조회하고 각 post의 author 정보를 가져올 때, posts 수만큼 author를 조회하는 쿼리가 추가로 발생하여 총 N+1개의 쿼리가 실행되는 상황입니다.

이 문제를 해결하기 위해 DataLoader 라이브러리를 사용합니다. DataLoader는 동일한 이벤트 루프 틱 내에서 발생하는 여러 요청을 배치(Batch)로 묶어 단일 데이터베이스 쿼리로 실행하고, 결과를 캐싱하여 중복 요청을 방지합니다.

// usersDataLoader.ts
import DataLoader from 'dataloader';
import { PrismaClient } from '@prisma/client';

export const createUserDataLoader = (prisma: PrismaClient) => {
  return new DataLoader(async (userIds: readonly string[]) => {
    const users = await prisma.user.findMany({
      where: {
        id: {
          in: userIds.map(String),
        },
      },
    });
    // 요청된 순서대로 결과를 매핑하여 반환해야 합니다.
    const userMap = new Map(users.map(user => [user.id, user]));
    return userIds.map(id => userMap.get(id) || new Error(`User not found for ID: ${id}`));
  });
};

// resolvers.ts (사용 예시)
import { createUserDataLoader } from './usersDataLoader';

interface MyContext {
  prisma: PrismaClient;
  dataLoaders: {
    users: DataLoader<string, any>; // User 타입 정의에 따라 any 대신 User 사용
  };
}

export const resolvers = {
  Post: {
    author: async (parent: any, args: any, context: MyContext) => {
      // N+1 문제 없이 DataLoader를 통해 배치 처리
      return context.dataLoaders.users.load(parent.authorId);
    },
  },
  Query: {
    user: async (parent: any, { id }: { id: string }, context: MyContext) => {
      return context.dataLoaders.users.load(id);
    },
  },
};

// server.ts (context에 DataLoader 주입)
// ...
const server = new ApolloServer<MyContext>({
  typeDefs,
  resolvers,
});

async function startApolloServer() {
  const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 },
    context: async ({ req }) => ({
      prisma,
      dataLoaders: {
        users: createUserDataLoader(prisma), // 요청마다 새로운 DataLoader 인스턴스 생성
      },
    }),
  });
  console.log(`🚀 Server ready at ${url}`);
}
// ...

캐싱 전략

캐싱은 API 성능을 크게 향상시킬 수 있는 또 다른 중요한 전략입니다.

• 클라이언트 측 캐싱: Apollo Client와 같은 라이브러리는 내장 캐시를 제공하여 이전에 가져온 데이터를 저장하고 재사용합니다.
• 서버 측 캐싱:
  • HTTP 캐싱: Cache-Control 헤더를 사용하여 CDN이나 프록시 서버에서 캐싱을 활성화합니다. GraphQL은 POST 요청을 주로 사용하기 때문에 HTTP 캐싱이 REST에 비해 복잡할 수 있습니다.
  • 데이터베이스 캐싱: Redis와 같은 인메모리 데이터 스토어를 활용하여 자주 접근하는 데이터를 캐싱합니다.
  • 리졸버 캐싱: 특정 리졸버의 결과를 캐싱하여 반복적인 계산이나 데이터베이스 조회를 줄입니다.

배치(Batching) 및 지속적인 쿼리(Persistent Queries)

• 쿼리 배치(Query Batching): 여러 개의 GraphQL 쿼리를 하나의 HTTP 요청으로 묶어 전송하는 기술입니다. 네트워크 오버헤드를 줄일 수 있습니다.
• 지속적인 쿼리(Persistent Queries): 클라이언트가 쿼리 문자열 대신 쿼리의 해시 값이나 ID를 서버에 보내는 방식입니다. 서버는 미리 저장된 쿼리 맵에서 해당 쿼리를 찾아 실행합니다. 이는 네트워크 페이로드 크기를 줄이고, 서버가 미리 쿼리의 복잡성을 분석할 수 있게 하여 보안과 성능을 향상시킵니다.

보안 및 에러 핸들링

API는 항상 보안 위협에 노출되어 있으며, 사용자에게 친숙한 에러 메시지를 제공하는 것도 중요합니다.

인증(Authentication) 및 인가(Authorization)

• 인증: 사용자의 신원을 확인하는 과정입니다. JWT(JSON Web Token)를 사용하여 클라이언트의 요청 헤더에서 토큰을 검증하고, context 객체에 인증된 사용자 정보를 주입하는 것이 일반적입니다.
• 인가: 인증된 사용자가 특정 리소스에 접근하거나 특정 작업을 수행할 권한이 있는지 확인하는 과정입니다. 리졸버 레벨에서 권한 검사를 수행하거나, 스키마 디렉티브(@auth)를 사용하여 선언적으로 권한을 정의할 수 있습니다.

// resolvers.ts (인가 예시)
import { GraphQLError } from 'graphql';

// ...
Post: {
  author: async (parent: any, args: any, context: MyContext) => {
    if (!context.currentUser) { // context에 주입된 사용자 정보 확인
      throw new GraphQLError('Authentication required.', {
        extensions: { code: 'UNAUTHENTICATED' },
      });
    }
    // ... 실제 데이터 로드 로직
  },
},
// ...

에러 메시지 표준화

GraphQL은 기본적으로 에러가 발생하면 errors 배열에 에러 정보를 담아 응답합니다. 이 에러 메시지를 일관된 형식으로 제공하고, 클라이언트가 쉽게 처리할 수 있도록 확장하는 것이 중요합니다. extensions 필드를 사용하여 커스텀 에러 코드, 상세 정보 등을 추가할 수 있습니다.

{
  "errors": [
    {
      "message": "Authentication required.",
      "locations": [ { "line": 2, "column": 3 } ],
      "path": [ "post", "author" ],
      "extensions": {
        "code": "UNAUTHENTICATED",
        "timestamp": "2023-10-27T10:00:00Z"
      }
    }
  ],
  "data": null
}

Query Depth Limiting 및 Complexity Analysis

악의적인 사용자가 매우 깊거나 복잡한 쿼리를 보내 서버에 과부하를 줄 수 있습니다.

• Query Depth Limiting: 쿼리의 최대 깊이를 제한하여 무한 루프나 과도한 중첩 쿼리를 방지합니다.
• Complexity Analysis: 쿼리의 복잡성을 계산하여 미리 정의된 임계값을 초과하는 쿼리를 거부합니다. 각 필드에 가중치(cost)를 부여하여 쿼리 전체의 비용을 계산할 수 있습니다. Apollo Server는 이러한 기능을 위한 플러그인을 제공합니다.

Node.js 기반 GraphQL 서버 구현 예시

지금까지 다룬 패턴들을 Node.js와 Apollo Server를 사용하여 간단한 예시로 구현해 보겠습니다.

// src/schema.ts
import gql from 'graphql-tag';

export const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
  }

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

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

  input CreateUserInput {
    name: String!
    email: String
  }

  input CreatePostInput {
    title: String!
    content: String
    authorId: ID!
  }

  type Mutation {
    createUser(input: CreateUserInput!): User!
    createPost(input: CreatePostInput!): Post!
  }
`;

// src/resolvers.ts
import { GraphQLError } from 'graphql';
import DataLoader from 'dataloader';
import { PrismaClient } from '@prisma/client';

// DataLoader를 위한 타입 정의 (Prisma 모델에 따라 실제 타입을 사용)
interface User {
  id: string;
  name: string;
  email: string | null;
}

// 컨텍스트 인터페이스
interface MyContext {
  prisma: PrismaClient;
  dataLoaders: {
    users: DataLoader<string, User>;
  };
  currentUser?: User; // 인증된 사용자 정보
}

// DataLoader 팩토리 함수 (요청당 한 번만 생성)
const createUserDataLoader = (prisma: PrismaClient) => {
  return new DataLoader(async (userIds: readonly string[]) => {
    const users = await prisma.user.findMany({
      where: {
        id: { in: userIds.map(String) },
      },
    });
    const userMap = new Map(users.map(user => [user.id, user]));
    return userIds.map(id => userMap.get(id) || new GraphQLError(`User with ID ${id} not found`));
  });
};

export const resolvers = {
  Query: {
    users: async (parent: any, args: any, context: MyContext) => {
      // 인증 예시: 모든 사용자 조회는 인증 필요
      if (!context.currentUser) {
        throw new GraphQLError('Authentication required to view users.', {
          extensions: { code: 'UNAUTHENTICATED' },
        });
      }
      return context.prisma.user.findMany();
    },
    user: async (parent: any, { id }: { id: string }, context: MyContext) => {
      return context.dataLoaders.users.load(id);
    },
    posts: async (parent: any, args: any, context: MyContext) => {
      return context.prisma.post.findMany();
    },
    post: async (parent: any, { id }: { id: string }, context: MyContext) => {
      return context.prisma.post.findUnique({ where: { id } });
    },
  },

  Mutation: {
    createUser: async (parent: any, { input }: { input: { name: string; email?: string } }, context: MyContext) => {
      return context.prisma.user.create({ data: input });
    },
    createPost: async (parent: any, { input }: { input: { title: string; content: string; authorId: string } }, context: MyContext) => {
      // 인가 예시: 게시물 생성은 특정 권한 필요 (예시에서는 단순히 인증된 사용자만 가능)
      if (!context.currentUser) {
        throw new GraphQLError('Authentication required to create a post.', {
          extensions: { code: 'FORBIDDEN' },
        });
      }
      return context.prisma.post.create({
        data: {
          title: input.title,
          content: input.content,
          author: {
            connect: { id: input.authorId },
          },
        },
      });
    },
  },

  User: {
    posts: async (parent: any, args: any, context: MyContext) => {
      // User의 posts 필드 리졸버 (N+1 문제 방지를 위해 DataLoader 활용)
      // 현재는 DataLoader가 User ID로 User만 로드하므로, Post를 로드하는 DataLoader 추가 필요
      // 또는 Prisma의 관계형 쿼리 사용:
      return context.prisma.user.findUnique({ where: { id: parent.id } }).posts();
    },
  },

  Post: {
    author: async (parent: any, args: any, context: MyContext) => {
      // DataLoader를 통해 N+1 문제 해결
      return context.dataLoaders.users.load(parent.authorId);
    },
  },
};

// src/server.ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { typeDefs } from './schema';
import { resolvers } from './resolvers';
import { PrismaClient } from '@prisma/client';
import DataLoader from 'dataloader';
import jwt from 'jsonwebtoken'; // JWT 인증을 위한 라이브러리 (예시)

interface User { // 실제 User 모델과 일치해야 합니다.
  id: string;
  name: string;
  email: string | null;
}

interface MyContext {
  prisma: PrismaClient;
  dataLoaders: {
    users: DataLoader<string, User>;
  };
  currentUser?: User; // 인증된 사용자 정보
}

const prisma = new PrismaClient();
const JWT_SECRET = process.env.JWT_SECRET || 'supersecretkey'; // 실제 환경에서는 환경 변수 사용

const createUserDataLoader = (prismaInstance: PrismaClient) => {
  return new DataLoader(async (userIds: readonly string[]) => {
    const users = await prismaInstance.user.findMany({
      where: { id: { in: userIds.map(String) } },
    });
    const userMap = new Map(users.map(user => [user.id, user]));
    return userIds.map(id => userMap.get(id) || new Error(`User with ID ${id} not found`));
  });
};

const server = new ApolloServer<MyContext>({
  typeDefs,
  resolvers,
});

async function startApolloServer() {
  const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 },
    context: async ({ req }) => {
      const token = req.headers.authorization?.split('Bearer ')[1] || '';
      let currentUser: User | undefined;
      try {
        if (token) {
          const decodedToken = jwt.verify(token, JWT_SECRET) as { userId: string };
          currentUser = await prisma.user.findUnique({ where: { id: decodedToken.userId } }) as User;
        }
      } catch (error) {
        console.error('Invalid JWT token:', error);
      }

      return {
        prisma,
        dataLoaders: {
          users: createUserDataLoader(prisma), // 요청마다 새 DataLoader 인스턴스 생성
        },
        currentUser,
      };
    },
  });
  console.log(`🚀 Server ready at ${url}`);
}

startApolloServer();

위 예시는 Prisma를 데이터베이스 ORM으로 사용하여 User와 Post 모델을 관리하고, DataLoader를 통해 N+1 문제를 해결하며, JWT를 이용한 간단한 인증 및 인가 로직을 context와 리졸버에 통합하는 방법을 보여줍니다.

마무리

GraphQL API는 현대 애플리케이션의 복잡한 데이터 요구사항을 충족시키는 강력하고 유연한 도구입니다. 이 가이드에서 다룬 스키마 디자인 패턴, 데이터 페칭 최적화 전략, 그리고 보안 및 에러 핸들링 기법들은 견고하고 확장 가능한 GraphQL API를 구축하는 데 필수적인 요소들입니다. Node.js와 Apollo Server를 활용하면 이러한 패턴들을 효과적으로 구현할 수 있습니다.

GraphQL은 지속적으로 발전하고 있으며, 더 나은 개발 경험과 성능을 위한 새로운 도구와 패턴들이 계속해서 등장하고 있습니다. 이 글이 GraphQL 여정을 시작하거나 기존 API를 개선하려는 백엔드 개발자들에게 유용한 지침이 되기를 바랍니다.