GraphQL과 REST API
고급 설계 완전 정복

A부터 Z까지 — 현업에서 바로 쓰는 API 설계 완전 가이드

🍕 피자 가게 REST API 예시
피자 가게(서버)에 손님(클라이언트)이 주문하는 상황을 API로 표현하면:

GET /pizzas → 피자 메뉴 전체 보여줘
GET /pizzas/1 → 1번 피자(페퍼로니) 정보 보여줘
POST /orders → 피자 주문할게
PUT /orders/5 → 5번 주문 내용 전체 변경할게
PATCH /orders/5 → 5번 주문에서 음료만 바꿀게
DELETE /orders/5 → 5번 주문 취소할게

// 일반 REST 응답
{ "id": 1, "status": "PENDING", "amount": 25000 }

// HATEOAS 응답 — 다음 행동까지 알려줌
{
  "id": 1,
  "status": "PENDING",
  "amount": 25000,
  "_links": {
    "self": { "href": "/orders/1" },
    "cancel": { "href": "/orders/1/cancel", "method": "POST" },
    "pay": { "href": "/orders/1/payment", "method": "POST" },
    "customer": { "href": "/customers/42" }
  }
}

✅ GraphQL의 해결책

# 단 1번의 요청으로 필요한 것만 정확히!
query GetUserProfile {
  user(id: 1) {
    name  # 이것만 필요!
    posts {
      title
      createdAt
    }
    followers {
      name
      avatar
    }
  }
}

# Schema Definition Language (SDL)

type User {
  id: ID!          # ! = Non-null (필수)
  name: String!
  email: String!
  age: Int            # ! 없으면 null 가능
  role: UserRole!    # Enum 타입
  posts: [Post!!]!   # Post 배열, 배열도 Non-null
  createdAt: String!
}

enum UserRole {
  ADMIN
  USER
  MODERATOR
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!         # 중첩 타입
  tags: [String!!]!
  publishedAt: String
}

# Query 타입 — 읽기 작업 정의
type Query {
  user(id: ID!): User
  users(
    page: Int = 1
    limit: Int = 20
    role: UserRole
  ): [User!!]!
  post(id: ID!): Post
  searchPosts(keyword: String!): [Post!!]!
}

# Mutation 타입 — 쓰기 작업 정의
type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
  createPost(input: CreatePostInput!): Post!
}

# Input 타입 — Mutation 입력 정의
input CreateUserInput {
  name: String!
  email: String!
  password: String!
}

input UpdateUserInput {
  name: String    # 모두 선택적 (일부만 수정 가능)
  email: String
}

// NestJS + GraphQL Resolver 구현
@Resolver(() => User)
export class UsersResolver {
  constructor(
    private usersService: UsersService,
    private postsService: PostsService,
  ) {}

  // Query Resolver: user(id: "1") 처리
  @Query(() => User, { nullable: true })
  async user(@Args('id') id: string): Promise<User | null> {
    return this.usersService.findOne(id);
  }

  // Mutation Resolver: createUser(...) 처리
  @Mutation(() => User)
  async createUser(
    @Args('input') input: CreateUserInput,
    @Context() ctx: GqlContext,  // 인증 정보 등 컨텍스트
  ): Promise<User> {
    return this.usersService.create(input);
  }

  // Field Resolver: user.posts 필드 처리
  @ResolveField(() => [Post])
  async posts(@Parent() user: User): Promise<Post[]> {
    // ⚠️ N+1 문제 발생 지점!
    // 10명의 유저를 조회하면 posts도 10번 쿼리됨
    return this.postsService.findByUserId(user.id);
  }
}

문제 상황: 게시글 10개 목록 조회 시, 각 게시글의 작성자 정보를 가져오기 위해 10번의 쿼리가 발생 (N+1 = 1+10 = 11번)

// DataLoader 구현 (NestJS)
@Injectable()
export class UserDataLoader {
  private loader: DataLoader<string, User>;

  constructor(private usersService: UsersService) {
    this.loader = new DataLoader<string, User>(
      async (userIds: string[]) => {
        // 10번 개별 조회 대신 한 번에 IN 쿼리!
        // SELECT * FROM users WHERE id IN (1,2,3,...,10)
        const users = await this.usersService.findByIds(userIds);
        // ID 순서대로 반환 (DataLoader 요구사항)
        return userIds.map(id => users.find(u => u.id === id));
      },
      {
        batch: true,    // 배치 처리
        cache: true,    // 같은 요청 내 캐싱
        maxBatchSize: 100,
      }
    );
  }

  load(id: string) { return this.loader.load(id); }
  loadMany(ids: string[]) { return this.loader.loadMany(ids); }
}

// Resolver에서 DataLoader 사용
@ResolveField(() => User)
async author(@Parent() post: Post): Promise<User> {
  // 이제 자동으로 배치 처리됨!
  return this.userDataLoader.load(post.authorId);
  // 11번 → 2번으로 줄어듦!
  // 1) SELECT posts (1번)
  // 2) SELECT users WHERE id IN (...) (1번)
}

// NestJS Subscription 구현
@Resolver(() => Message)
export class MessagesResolver {
  constructor(
    private messagesService: MessagesService,
    @Inject('PUB_SUB') private pubSub: PubSub,
  ) {}

  // 메시지 전송 Mutation
  @Mutation(() => Message)
  async sendMessage(
    @Args('input') input: SendMessageInput,
  ): Promise<Message> {
    const message = await this.messagesService.create(input);
    
    // 구독자들에게 이벤트 발행
    await this.pubSub.publish(`MESSAGE_SENT_${input.roomId}`, {
      messageSent: message,
    });
    
    return message;
  }

  // Subscription 정의
  @Subscription(() => Message, {
    filter: (payload, variables) => {
      // 같은 채팅방의 메시지만 받기
      return payload.messageSent.roomId === variables.roomId;
    },
  })
  messageSent(@Args('roomId') roomId: string) {
    return this.pubSub.asyncIterator(`MESSAGE_SENT_${roomId}`);
  }
}

// 클라이언트 쿼리
subscription OnMessageSent($roomId: String!) {
  messageSent(roomId: $roomId) {
    id
    content
    sender { name avatar }
    createdAt
  }
}

📡 REST를 선택하세요

• 단순한 CRUD API
• 브라우저 캐싱 활용 필요
• 팀이 REST에 익숙
• 공개 API 제공
• 파일 업로드/다운로드

🔗 GraphQL을 선택하세요

• 모바일 앱 (데이터 절약)
• 복잡한 관계형 데이터
• 다양한 클라이언트 지원
• 빠른 프로토타이핑
• 실시간 + REST 동시 필요

⚡ gRPC를 선택하세요

• 마이크로서비스 간 통신
• 낮은 레이턴시 필수
• 대용량 데이터 스트리밍
• 다언어 지원 필요
• 엄격한 스키마 계약

// JWT 구조: Header.Payload.Signature
// eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiIxMjMifQ.SIGNATURE

// NestJS JWT 전체 구현
// 1. auth.service.ts
@Injectable()
export class AuthService {
  constructor(
    private usersService: UsersService,
    private jwtService: JwtService,
  ) {}

  async login(email: string, password: string) {
    const user = await this.usersService.findByEmail(email);
    if (!user || !await bcrypt.compare(password, user.passwordHash)) {
      throw new UnauthorizedException('Invalid credentials');
    }

    const payload = { sub: user.id, email: user.email, role: user.role };
    
    return {
      accessToken: this.jwtService.sign(payload, { expiresIn: '15m' }),
      refreshToken: this.jwtService.sign(payload, { expiresIn: '7d' }),
    };
  }

  async refreshToken(refreshToken: string) {
    try {
      const payload = this.jwtService.verify(refreshToken);
      const newAccessToken = this.jwtService.sign(
        { sub: payload.sub, email: payload.email, role: payload.role },
        { expiresIn: '15m' }
      );
      return { accessToken: newAccessToken };
    } catch (e) {
      throw new UnauthorizedException('Invalid refresh token');
    }
  }
}

// 2. jwt.guard.ts - API 보호
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  canActivate(context: ExecutionContext) {
    return super.canActivate(context);
  }
}

// 3. roles.guard.ts - RBAC 권한 체크
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>('roles', context.getHandler());
    if (!roles) return true;
    
    const { user } = context.switchToHttp().getRequest();
    return roles.includes(user.role);
  }
}

// 4. 사용 예시
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('ADMIN')
@Delete(':id')
deleteUser(@Param('id') id: string) {
  return this.usersService.remove(id);
  // ADMIN만 호출 가능!
}

// NestJS Google OAuth 구현 (Passport.js)
@Injectable()
export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
  constructor(private authService: AuthService) {
    super({
      clientID: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      callbackURL: '/auth/google/callback',
      scope: ['email', 'profile'],
    });
  }

  async validate(accessToken, refreshToken, profile) {
    const { id, emails, name, photos } = profile;
    return this.authService.findOrCreateGoogleUser({
      googleId: id,
      email: emails[0].value,
      name: `${name.givenName} ${name.familyName}`,
      avatar: photos[0].value,
    });
  }
}

// NestJS Rate Limiting 설정
// npm install @nestjs/throttler

// app.module.ts
@Module({
  imports: [
    ThrottlerModule.forRoot([
      {
        name: 'short',
        ttl: 1000,      // 1초
        limit: 3,       // 1초에 3회
      },
      {
        name: 'medium',
        ttl: 60000,     // 1분
        limit: 20,      // 1분에 20회
      },
      {
        name: 'long',
        ttl: 60 * 60 * 1000,  // 1시간
        limit: 100,           // 1시간에 100회
      },
    ]),
  ],
  providers: [
    {
      provide: APP_GUARD,
      useClass: ThrottlerGuard,
    },
  ],
})

// 특정 엔드포인트에만 적용
@Throttle({ default: { limit: 5, ttl: 60000 } })
@Post('login')
login() { ... }

// Rate Limit 초과 시 응답
// HTTP 429 Too Many Requests
// Retry-After: 60 (헤더로 대기 시간 전달)

// Cache-Aside 패턴 구현
@Injectable()
export class ProductsService {
  constructor(
    @InjectRepository(Product) private repo: Repository<Product>,
    @Inject(CACHE_MANAGER) private cacheManager: Cache,
  ) {}

  async findOne(id: string) {
    const cacheKey = `product:${id}`;

    // 1. 캐시 확인
    const cached = await this.cacheManager.get(cacheKey);
    if (cached) {
      return cached; // 캐시 히트! DB 조회 없음
    }

    // 2. DB 조회
    const product = await this.repo.findOne({ where: { id } });
    if (!product) {
      throw new NotFoundException();
    }

    // 3. 캐시 저장 (1시간)
    await this.cacheManager.set(cacheKey, product, 3600);

    return product;
  }

  async update(id: string, dto: UpdateProductDto) {
    await this.repo.update(id, dto);
    // 데이터 변경 시 캐시 무효화
    await this.cacheManager.del(`product:${id}`);
    return this.findOne(id);
  }
}

// 성능 비교
// DB 직접 조회:  ~50ms (네트워크 + 쿼리)
// Redis 캐시:    ~1ms  (50배 빠름!)

// main.ts — Swagger 설정
async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('Pizza API')
    .setDescription('The Pizza API documentation')
    .setVersion('1.0')
    .addBearerAuth()  // JWT 인증 UI 추가
    .build();
  
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api/docs', app, document);  // /api/docs로 접근
  
  await app.listen(3000);
}

// Controller — 상세 문서화
@ApiTags('pizzas')  // 태그 그룹화
@ApiBearerAuth()   // JWT 필요 표시
@Controller('pizzas')
export class PizzasController {
  @ApiOperation({ summary: '피자 목록 조회', description: '전체 피자 메뉴를 페이지네이션으로 조회합니다' })
  @ApiQuery({ name: 'page', required: false, type: Number, description: '페이지 번호' })
  @ApiResponse({ status: 200, description: '성공', type: [Pizza] })
  @ApiResponse({ status: 401, description: '인증 필요' })
  @Get()
  findAll(@Query() query: FindAllDto) {
    return this.pizzasService.findAll(query);
  }
}

// DTO — 모델 문서화
export class CreatePizzaDto {
  @ApiProperty({ example: '페퍼로니 피자', description: '피자 이름' })
  @IsString()
  @MinLength(2)
  name: string;

  @ApiProperty({ example: 18000, description: '가격 (원)', minimum: 1000 })
  @IsNumber()
  @Min(1000)
  price: number;
}

# AWS API Gateway + Lambda 구성
# serverless.yml

service: pizza-api
provider:
  name: aws
  runtime: nodejs18.x

functions:
  getUsers:
    handler: src/users/get.handler
    events:
      - httpApi:
          path: /v1/users
          method: GET
          authorizer:
            name: jwtAuthorizer  # JWT 검증 Lambda
  
  createOrder:
    handler: src/orders/create.handler
    events:
      - httpApi:
          path: /v1/orders
          method: POST
          authorizer:
            name: jwtAuthorizer

// NestJS API 통합 테스트 (Supertest)
describe('PizzasController (e2e)', () => {
  let app: INestApplication;
  let accessToken: string;

  beforeAll(async () => {
    const moduleFixture = await Test.createTestingModule({
      imports: [AppModule],
    }).compile();

    app = moduleFixture.createNestApplication();
    await app.init();

    // 로그인해서 토큰 획득
    const loginRes = await request(app.getHttpServer())
      .post('/auth/login')
      .send({ email: 'test@test.com', password: 'password' });
    accessToken = loginRes.body.accessToken;
  });

  it('GET /pizzas — 인증 없이 401 반환', () => {
    return request(app.getHttpServer())
      .get('/pizzas')
      .expect(401);
  });

  it('GET /pizzas — 인증 후 200 반환 + 목록 확인', () => {
    return request(app.getHttpServer())
      .get('/pizzas')
      .set('Authorization', `Bearer ${accessToken}`)
      .expect(200)
      .expect((res) => {
        expect(res.body.data).toBeDefined();
        expect(Array.isArray(res.body.data)).toBeTruthy();
      });
  });

  it('POST /pizzas — 피자 생성 성공 + 201 반환', async () => {
    const createDto = { name: '테스트 피자', price: 18000 };
    
    const res = await request(app.getHttpServer())
      .post('/pizzas')
      .set('Authorization', `Bearer ${accessToken}`)
      .send(createDto)
      .expect(201);
    
    expect(res.body.name).toBe(createDto.name);
    expect(res.body.id).toBeDefined();
  });
  
  afterAll(async () => await app.close());
});