excatt/graphql

GraphQL Skill

GraphQL 스키마 설계 가이드를 실행합니다.

스키마 기본

타입 정의

# 스칼라 타입
type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  isActive: Boolean!
  balance: Float
  createdAt: DateTime!
}

# 열거형
enum OrderStatus {
  PENDING
  PROCESSING
  SHIPPED
  DELIVERED
  CANCELLED
}

# 인터페이스
interface Node {
  id: ID!
}

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

# 유니온
union SearchResult = User | Product | Order

관계 모델링

type User {
  id: ID!
  name: String!
  orders: [Order!]!          # 1:N
  profile: Profile           # 1:1
  friends: [User!]!          # N:N
}

type Order {
  id: ID!
  user: User!                # N:1
  items: [OrderItem!]!
}

type OrderItem {
  id: ID!
  product: Product!
  quantity: Int!
}

Query 설계

기본 쿼리

type Query {
  # 단일 조회
  user(id: ID!): User

  # 목록 조회 (페이지네이션)
  users(
    first: Int
    after: String
    filter: UserFilter
    orderBy: UserOrderBy
  ): UserConnection!

  # 검색
  search(query: String!): [SearchResult!]!

  # 뷰어 패턴 (현재 사용자)
  viewer: User
}

# 필터 입력
input UserFilter {
  status: UserStatus
  createdAfter: DateTime
  nameContains: String
}

# 정렬 입력
input UserOrderBy {
  field: UserOrderField!
  direction: OrderDirection!
}

enum UserOrderField {
  NAME
  CREATED_AT
}

enum OrderDirection {
  ASC
  DESC
}

Connection 패턴 (Relay)

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

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

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

Mutation 설계

입력 타입

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!
}

input CreateUserInput {
  name: String!
  email: String!
  password: String!
}

# Payload 패턴
type CreateUserPayload {
  user: User
  errors: [Error!]
}

type Error {
  field: String
  message: String!
  code: ErrorCode!
}

enum ErrorCode {
  VALIDATION_ERROR
  NOT_FOUND
  UNAUTHORIZED
  CONFLICT
}

일괄 처리

type Mutation {
  bulkUpdateUsers(input: BulkUpdateUsersInput!): BulkUpdateUsersPayload!
}

input BulkUpdateUsersInput {
  updates: [UserUpdateInput!]!
}

input UserUpdateInput {
  id: ID!
  name: String
  email: String
}

type BulkUpdateUsersPayload {
  users: [User!]!
  failedIds: [ID!]!
  errors: [Error!]
}

Subscription 설계

type Subscription {
  # 실시간 업데이트
  orderStatusChanged(orderId: ID!): Order!

  # 새 메시지
  messageReceived(channelId: ID!): Message!

  # 필터링된 이벤트
  notificationReceived(userId: ID!): Notification!
}

Resolver 구현

기본 Resolver

const resolvers = {
  Query: {
    user: async (_, { id }, context) => {
      return context.dataSources.users.findById(id);
    },

    users: async (_, { first, after, filter }, context) => {
      return context.dataSources.users.findAll({ first, after, filter });
    },
  },

  Mutation: {
    createUser: async (_, { input }, context) => {
      try {
        const user = await context.dataSources.users.create(input);
        return { user, errors: null };
      } catch (error) {
        return {
          user: null,
          errors: [{ message: error.message, code: 'VALIDATION_ERROR' }],
        };
      }
    },
  },

  User: {
    orders: async (user, _, context) => {
      return context.dataSources.orders.findByUserId(user.id);
    },
  },
};

DataLoader (N+1 해결)

const DataLoader = require('dataloader');

// DataLoader 생성
const userLoader = new DataLoader(async (ids) => {
  const users = await db.users.findByIds(ids);
  return ids.map(id => users.find(u => u.id === id));
});

// Resolver에서 사용
const resolvers = {
  Order: {
    user: (order, _, context) => {
      return context.loaders.user.load(order.userId);
    },
  },
};

인증/인가

Context 설정

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: async ({ req }) => {
    const token = req.headers.authorization?.replace('Bearer ', '');
    const user = token ? await verifyToken(token) : null;

    return {
      user,
      dataSources: { /* ... */ },
      loaders: { /* ... */ },
    };
  },
});

Directive 기반 인가

directive @auth(requires: Role = USER) on FIELD_DEFINITION

enum Role {
  ADMIN
  USER
  GUEST
}

type Query {
  users: [User!]! @auth(requires: ADMIN)
  viewer: User @auth
}

const authDirective = (schema, directiveName) => {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
      const directive = getDirective(schema, fieldConfig, directiveName)?.[0];
      if (directive) {
        const { resolve = defaultFieldResolver } = fieldConfig;
        fieldConfig.resolve = async (source, args, context, info) => {
          if (!context.user) throw new AuthenticationError('Not authenticated');
          if (directive.requires && context.user.role !== directive.requires) {
            throw new ForbiddenError('Not authorized');
          }
          return resolve(source, args, context, info);
        };
      }
      return fieldConfig;
    },
  });
};

에러 처리

// 커스텀 에러
class ValidationError extends ApolloError {
  constructor(message, fields) {
    super(message, 'VALIDATION_ERROR', { fields });
  }
}

// Resolver에서 사용
const resolvers = {
  Mutation: {
    createUser: async (_, { input }) => {
      if (!isValidEmail(input.email)) {
        throw new ValidationError('Invalid email', { email: 'Invalid format' });
      }
      // ...
    },
  },
};

성능 최적화

Query Complexity

const server = new ApolloServer({
  validationRules: [
    createComplexityLimitRule(1000, {
      scalarCost: 1,
      objectCost: 10,
      listFactor: 10,
    }),
  ],
});

Depth Limiting

const depthLimit = require('graphql-depth-limit');

const server = new ApolloServer({
  validationRules: [depthLimit(5)],
});

체크리스트

스키마 설계

• [ ] 명확한 타입 정의
• [ ] Null 가능성 명시 (!)
• [ ] Connection 패턴 (페이지네이션)
• [ ] Input/Payload 타입 분리

보안

• [ ] 인증/인가
• [ ] Query complexity 제한
• [ ] Depth limiting
• [ ] Rate limiting

성능

• [ ] DataLoader (N+1 해결)
• [ ] 적절한 캐싱
• [ ] 쿼리 분석

출력 형식

## GraphQL Schema Design

### Types
```graphql
# 핵심 타입 정의

Queries

# 쿼리 정의

Mutations

# 뮤테이션 정의

Resolver Example

// Resolver 구현

Security

• 인증: JWT
• 인가: Directive 기반
• 제한: Complexity 1000, Depth 5

---

요청에 맞는 GraphQL 스키마를 설계하세요.