![image](https://memgraph.com/_next/image?url=%2Fimages%2Fblog%2Fgraphql-vs-rest-api%2Fcover.png&w=1920&q=75)

# 개요

> 2025년 현재, 클라이언트-서버 API 설계에는 두 가지 주요 접근 방식이 있습니다. REST API는 20년 넘게 업계 표준이었고, GraphQL은 2015년 오픈소스화 이후 빠르게 성장했습니다. 둘 다 프로덕션에서 충분히 검증되었으며, "최고"의 선택은 프로젝트 요구사항에 따라 달라집니다.

---
# REST API

## 핵심 개념

- HTTP 메서드(GET, POST, PUT, DELETE)를 사용한 리소스 기반 아키텍처
- 각 리소스는 고유한 URL을 가짐 (/users/123, /posts/456)
- JSON 형식의 응답 (사실상 표준)
- Stateless 통신

## 장점
### 1. 낮은 학습 곡선

- 대부분의 개발자가 이미 알고 있음
- HTTP 표준을 그대로 활용
- 새 팀원 온보딩이 빠름

### 2. 강력한 캐싱
```javascript
// HTTP 캐싱을 그대로 활용
GET /api/users/123
Cache-Control: max-age=3600
ETag: "abc123"

// CDN, 브라우저 캐시 모두 자동으로 동작
```
### 3. 성숙한 생태계

- Postman, Insomnia 같은 테스트 도구
- OpenAPI/Swagger로 자동 문서화
- 모든 HTTP 클라이언트 라이브러리 호환
- AWS API Gateway, Nginx 등 인프라 지원 완벽

### 4. 명확한 의미론
```javascript
GET    /api/posts      // 목록 조회
POST   /api/posts      // 생성
GET    /api/posts/123  // 단건 조회
PUT    /api/posts/123  // 전체 수정
PATCH  /api/posts/123  // 부분 수정
DELETE /api/posts/123  // 삭제
```
### 5. 디버깅 용이

- 브라우저 Network 탭에서 바로 확인
- curl 한 줄로 테스트 가능
- 로그에서 URL만 봐도 무슨 요청인지 파악

## 단점
### 1. Over-fetching
```javascript
// 사용자 이름만 필요한데 모든 필드를 받음
GET /api/users/123
{
  "id": 123,
  "name": "홍길동",           // 필요한 필드
  "email": "hong@example.com",  // 불필요
  "phone": "010-1234-5678",     // 불필요
  "address": { ... },            // 불필요
  "created_at": "...",           // 불필요
  "updated_at": "..."            // 불필요
}
```

### 2. Under-fetching (N+1 문제)
```javascript
// 게시글 목록
GET /api/posts
[{ id: 1, title: "...", author_id: 10 }, ...]
`
// 각 게시글의 작성자 정보를 가져오려면 추가 요청 필요
GET /api/users/10
GET /api/users/11
GET /api/users/12
// ...

// 또는 엔드포인트를 추가로 만들어야 함
GET /api/posts?include=author
```

### 3. 버전 관리의 복잡성
```javascript
// API가 변경되면 버전을 올려야 함
/api/v1/users  // 구버전 유지
/api/v2/users  // 신규 필드 추가
/api/v3/users  // 구조 변경

// 여러 버전을 동시에 유지보수해야 함
```

### 4. 엔드포인트 폭발
```javascript
// 다양한 요구사항에 맞춰 엔드포인트가 계속 추가됨
GET /api/posts
GET /api/posts?status=published
GET /api/posts?author=123
GET /api/posts?author=123&status=published
GET /api/posts/trending
GET /api/posts/recommended
GET /api/users/123/posts
// ...
실무 예시
javascript// 사용자 정보와 최근 게시글 5개를 가져오려면
const user = await fetch('/api/users/123').then(r => r.json());
const posts = await fetch(`/api/users/123/posts?limit=5`).then(r => r.json());

// 2번의 네트워크 요청 필요
// 각 게시글의 댓글 수까지 필요하면 3번째 요청 또는 복잡한 엔드포인트 설계 필요
```
---
# GraphQL
## 핵심 개념

> - Facebook(현 Meta)이 2012년 개발, 2015년 오픈소스화
> - 쿼리 언어로 클라이언트가 필요한 데이터 구조를 명시
> - 단일 엔드포인트 (POST /graphql)
> - 강력한 타입 시스템 (Schema Definition Language)
> - 현재는 Linux Foundation 산하 GraphQL Foundation에서 관리

## 장점
### 1. 정확한 데이터 요청

```graphql
query {
  user(id: 123) {
    name          # 필요한 필드만 명시
    email
  }
}

# 응답
{
  "data": {
    "user": {
      "name": "홍길동",
      "email": "hong@example.com"
    }
  }
}
```
### 2. 단일 요청으로 복잡한 데이터 구조
```graphql
query {
  user(id: 123) {
    name
    email
    posts(limit: 5) {
      title
      createdAt
      comments(limit: 3) {
        content
        author {
          name
          avatar
        }
      }
    }
  }
}

# 한 번의 요청으로 사용자 → 게시글 → 댓글 → 작성자 모두 가져옴
```
### 3. 강력한 타입 시스템
```graphql
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
}

# IDE에서 자동완성, 타입 체크 가능
# 컴파일 타임에 오류 발견
```

### 4. 버전 관리 불필요
```graphql
type User {
  id: ID!
  name: String!
  email: String!
  phone: String @deprecated(reason: "Use phoneNumber instead")
  phoneNumber: String
}

# 필드 추가/deprecated만으로 관리
# 클라이언트는 필요한 필드만 요청하므로 호환성 유지
```

### 5. 자가 문서화
```graphql
# 스키마 자체가 문서
# GraphQL Playground에서 모든 타입, 필드, 인자 확인 가능
# 별도 문서 작성 불필요
6. 실시간 기능 (Subscriptions)
graphqlsubscription {
  newMessage(chatId: "123") {
    id
    content
    author {
      name
    }
  }
}

# WebSocket으로 실시간 업데이트
# 채팅, 알림, 실시간 대시보드 구현 용이
```
## 단점
### 1. 학습 곡선

- GraphQL 쿼리 언어 학습 필요
- Schema 설계 패턴 학습 필요
- Resolver 개념 이해 필요
- 팀 전체가 익숙해지기까지 시간 소요

### 2. 캐싱 복잡성
```javascript
// REST는 URL 기반 캐싱
GET /api/users/123 → 캐시 키: /api/users/123

// GraphQL은 쿼리 내용이 캐시 키
// POST 요청이라 HTTP 캐싱 불가
// Apollo Client, urql 같은 전용 캐싱 필요
```
### 3. 쿼리 복잡도 관리
```graphql
# 악의적이거나 비효율적인 쿼리 가능
query {
  users {
    posts {
      comments {
        author {
          posts {
            comments {
              # 무한 중첩...
            }
          }
        }
      }
    }
  }
}

# Depth limiting, Query complexity analysis 필수
```

### 4. N+1 문제
```javascript
// Resolver가 비효율적이면 성능 문제
const resolvers = {
  Post: {
    author: (post) => {
      return db.users.findById(post.authorId); // 각 게시글마다 DB 쿼리!
    }
  }
};

// DataLoader로 해결 필요
const userLoader = new DataLoader(ids => 
  db.users.findByIds(ids) // 배치 처리
);
```

### 5. 파일 업로드
```javascript
// GraphQL 표준이 아님
// multipart/form-data 별도 구현 필요
// 또는 별도 REST 엔드포인트 사용
```
### 6. 에러 처리
```javascript
// HTTP 상태 코드를 활용할 수 없음
// 쿼리 일부만 실패해도 200 OK 반환
{
  "data": {
    "user": null  // 실패
  },
  "errors": [{
    "message": "User not found",
    "path": ["user"]
  }]
}

// 클라이언트가 data와 errors를 모두 확인해야 함
```

## 실무 예시
```javascript
// Apollo Client 예시
const { data, loading, error } = useQuery(
gql`
  query GetUserWithPosts($userId: ID!) {
    user(id: $userId) {
      name
      email
      posts(limit: 5) {
        title
        createdAt
        commentCount  # 서버에서 계산된 필드
      }
    }
  }
`,{
  variables: { userId: '123' }
});

// 한 번의 요청으로 모든 데이터
// 타입 안정성 보장
// 캐싱 자동 처리
```
---
# 성능 비교 (2025년 기준)
- 페이로드 크기
```javascript
// REST - 불필요한 필드 포함
{
  "id": 123,
  "name": "홍길동",
  "email": "hong@example.com",
  "phone": "010-1234-5678",
  "address": { /* ... */ },
  "preferences": { /* ... */ },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2025-02-20T14:20:00Z"
}
// ~800 bytes

// GraphQL - 필요한 필드만
{
  "data": {
    "user": {
      "name": "홍길동",
      "email": "hong@example.com"
    }
  }
}
// ~150 bytes
```

**실측 데이터** (복잡한 중첩 쿼리 기준):
- REST: 평균 3-5개 요청, 총 ~2-3MB
- GraphQL: 1개 요청, ~800KB

## 네트워크 레이턴시

### REST: 
1. 요청 1: 사용자 정보 (100ms)
2. 요청 2: 게시글 목록 (120ms)  
3. 요청 3: 댓글 수 (90ms)
4. 총: ~310ms + 네트워크 오버헤드

### GraphQL:
1. 단일 요청: ~180ms

## 개발 속도

1. REST: 프론트엔드가 새 데이터 필요 → 백엔드 엔드포인트 추가 → 배포 → 사용
2. GraphQL: 프론트엔드가 새 데이터 필요 → 스키마에 이미 있으면 바로 쿼리 작성
---

# 2025년 실무 트렌드
## **REST**가 여전히 우세한 영역
### 1. 공개 API
```javascript
// Stripe, GitHub, Twilio 등 대부분의 공개 API는 REST
GET https://api.stripe.com/v1/customers/cus_xxx
Authorization: Bearer sk_xxx
```

외부 개발자가 사용하기 쉬움
문서화가 직관적
curl로 바로 테스트 가능

### 2. 간단한 CRUD 애플리케이션
```javascript
// To-do 앱, 블로그, 간단한 관리 시스템
GET /api/todos
POST /api/todos
PUT /api/todos/123
DELETE /api/todos/123
```
### 3. 레거시 시스템 통합

- 기존 REST API 인프라 활용
- 마이그레이션 비용 없음

## GraphQL이 강세인 영역
### 1. 모바일 앱
```graphql
# 데이터 사용량 최소화
# 배터리 절약
# 3G/4G 환경에서도 빠른 응답
query {
  feed(limit: 10) {
    id
    thumbnail  # 작은 이미지만
    title
  }
}
```
### 2. 복잡한 데이터 관계
```graphql
# E-commerce, SNS, 협업 도구
query {
  product(id: "123") {
    name
    price
    reviews(limit: 5) {
      rating
      comment
      author {
        name
        verified
      }
    }
    relatedProducts(limit: 3) {
      name
      price
      thumbnail
    }
  }
}
```

### 3. BFF (Backend For Frontend) 패턴
*BFF패턴에 대해선 나중에 따로 다룰 예정입니다*

### 4. 실시간 대시보드
```graphql
subscription {
  orderUpdates {
    orderId
    status
    timestamp
  }
}
# WebSocket으로 실시간 업데이트
```
---

# 선택 가이드
## REST API가 적합할 경우:
1. 공개 API 또는 파트너 API
2. 간단한 CRUD 위주 애플리케이션
3. 팀이 GraphQL 학습 시간이 없는 경우
4. HTTP 캐싱을 적극 활용하고 싶은 경우
5. 레거시 시스템과 통합해야 하는 경우
6. 파일 업로드/다운로드가 주요 기능인 경우

### 구체적 예시:

1. 블로그 플랫폼 (Medium, WordPress)
2. 결제 서비스 API (Stripe, PayPal)
3. OAuth 인증 서비스
4. 간단한 관리자 대시보드


## GraphQL이 적합할 경우:

1. 모바일 앱 (데이터 효율성 중요)
2. 복잡한 데이터 관계가 많은 경우
3. 프론트엔드 요구사항이 자주 변경되는 경우
4. 실시간 기능이 필요한 경우
5. 여러 데이터 소스를 통합하는 BFF 구축
6. 타입 안정성이 중요한 경우

### 구체적 예시:

1. SNS 플랫폼 (Facebook, Instagram)
2. E-commerce (Shopify)
3. 협업 도구 (Notion, Slack)
4. 복잡한 SaaS 대시보드

---
# 실제 기업 사례 (2025년)

## REST 사용사례

- Stripe: 결제 API (외부 개발자 친화적)
- Twilio: SMS/음성 API
- AWS: 대부분의 AWS 서비스

## GraphQL 사용사례

- GitHub: API v4는 GraphQL
- Shopify: Admin API와 Storefront API
- Netflix: 내부 API (Falcor, GraphQL 유사)

## 둘 다 사용하는 사례

- GitHub: REST (v3) + GraphQL (v4)
- Contentful: REST + GraphQL
- Hasura: 자동으로 DB에서 GraphQL 생성

## 하이브리드 접근
실무에서는 둘을 함께 사용하는 경우가 많습니다:
```javascript
// 공개 API: REST
app.get('/api/v1/products/:id', ...)

// 웹/모바일 앱: GraphQL
app.post('/graphql', graphqlHTTP({ schema }))

// 파일 업로드: REST
app.post('/api/upload', upload.single('file'), ...)

// 실시간 알림: GraphQL Subscription
```
### 장점:
1. 각 기술의 강점을 활용
2. 점진적 마이그레이션 가능
3. 레거시 호환성 유지

## 마이그레이션 전략
REST → GraphQL
```javascript
// 1단계: GraphQL 서버가 REST API를 래핑
const resolvers = {
  Query: {
    user: (_, { id }) => fetch(`/api/users/${id}`).then(r => r.json())
  }
}

// 2단계: 점진적으로 Resolver를 직접 DB 접근으로 변경
const resolvers = {
  Query: {
    user: (_, { id }) => db.users.findById(id)
  }
}

// 3단계: 프론트엔드를 하나씩 GraphQL로 전환
```

### 비용 고려사항

#### **REST 추가 비용** 
- 거의 없음 (표준 HTTP)
####  **GraphQL 추가 비용**
1. 개발: 스키마 설계, Resolver 구현
2. 인프라: Apollo Server, DataLoader 등
3. 모니터링: Query complexity, 성능 추적
4. 학습: 팀 교육 시간

# 결론

**2025년 현재, 둘 다 성숙하고 프로덕션에서 검증된 기술이며 프로젝트에 맞게 사용하는게 중요할 것 같습니다.**

## 실무 추천
### 1. 스타트업/신규 프로젝트:
- 작게 시작: REST로 MVP 개발
- 복잡해지면: GraphQL 고려
- 필요시: 하이브리드 접근

### 2. 대규모 프로젝트:
- 내부용: GraphQL (효율성)
- 외부용: REST (접근성)
- 실시간: GraphQL Subscriptions

# 마지막으로 기술 선택시 가장 중요한 것
1. 팀의 경험
2. 프로젝트 요구사항
3. 장기 유지보수 가능성 고려

# 느낀점
REST API는 워낙 익숙하게 써오다 보니 크게 생각하지 않았지만, 블로그를 만들면서 처음 GraphQL을 제대로 다뤄보니 둘의 장단점이 확실히 비교를 할 수 있었습니다.<br />
특히 요즘 GraphQL은 Apollo까지 함께 이해해야 해서 초반에는 머리가 지끈거릴 정도로 어렵고, 학습곡선도 짧지 않지만 그래도 시간이 지나 익숙해지니까 확실히 편한 면이 많았습니다.<br />

개인 프로젝트라도 이렇게 GraphQL을 직접 적용해보고, 그 경험을 바탕으로 글까지 정리해볼 수 있다는 게 참 의미 있고 좋은 기회였던 것 같습니다.

GraphQL vs REST API : 2025년 기준으로 다시 생각해보기

Node.js로 백엔드 서버를 개발하려고 검색하다 보면 Express와 함께 자주 등장하는 이름이 있다. 바로 **NestJS**다.

Express가 필요한 기능을 자유롭게 조합하는 미니멀한 프레임워크라면, NestJS는 애플리케이션을 어떤 구조로 작성해야 하는지 비교적 명확한 기준을 제시한다. 프로젝트 규모가 커지고 참여하는 개발자가 많아질수록 이러한 구조는 코드의 일관성과 유지보수성을 높이는 데 도움이 된다.

NestJS는 객체지향 프로그래밍, 함수형 프로그래밍, 반응형 프로그래밍의 요소를 활용한다. 내부 HTTP 서버로는 기본적으로 Express를 사용하며, 필요에 따라 Fastify로 변경할 수도 있다.

# NestJS는 왜 등장했을까?

Node.js는 JavaScript로 빠르게 서버를 개발할 수 있다는 장점이 있다. Express를 이용하면 몇 줄의 코드만으로 웹 서버를 실행할 수 있다.

```javascript
const express = require('express');
const app = express();

app.get('/hello', (req, res) => {
  res.send('Hello World');
});

app.listen(3000);
```

하지만 Express는 프로젝트 구조를 거의 강제하지 않는다. 개발자는 폴더 구조, 비즈니스 로직 분리, 의존성 관리, 예외 처리, 인증 방식 등을 직접 결정해야 한다.

작은 프로젝트에서는 이러한 자유로움이 장점이다. 반면 프로젝트가 커지면 개발자마다 서로 다른 방식으로 코드를 작성해 구조가 일관되지 않거나, 라우터와 비즈니스 로직이 강하게 결합되는 문제가 발생할 수 있다.

NestJS는 이 문제를 해결하기 위해 다음과 같은 구조를 기본으로 제공한다.

- 역할에 따라 코드를 나누는 Module, Controller, Provider
- 클래스 간 의존성을 관리하는 의존성 주입
- 데코레이터를 활용한 선언적인 라우팅
- 인증, 검증, 로깅, 예외 처리를 위한 공통 실행 계층
- 테스트하기 쉬운 애플리케이션 구조

쉽게 말하면 Express의 유연함 위에 대규모 애플리케이션을 위한 설계 규칙과 개발 도구를 더한 프레임워크라고 볼 수 있다.

# NestJS의 주요 특징

### TypeScript 중심의 개발

NestJS는 JavaScript로도 사용할 수 있지만 TypeScript를 중심으로 설계됐다.

TypeScript를 사용하면 함수의 입력과 출력, 객체의 형태, 클래스 간 관계를 코드에 명시할 수 있다. 컴파일 단계에서 일부 오류를 발견할 수 있고, IDE의 자동 완성과 리팩터링 지원도 더 잘 활용할 수 있다.

백엔드 프로젝트는 데이터베이스 모델, API 요청과 응답, 서비스 간 인터페이스처럼 데이터 구조를 다룰 일이 많다. 따라서 타입을 명확히 정의하는 것이 장기적인 유지보수에 큰 도움이 된다.

### 데코레이터 기반 구조

NestJS 코드에서는 `@Controller()`, `@Get()`, `@Injectable()` 같은 표현을 자주 볼 수 있다. 이를 데코레이터라고 한다.

데코레이터는 클래스나 메서드에 역할과 부가 정보를 선언한다.

```typescript
@Controller('users')
export class UsersController {
  @Get()
  findAll() {
    return '사용자 목록';
  }
}
```

위 코드에서 `@Controller('users')`는 이 클래스가 `/users` 경로의 요청을 처리한다는 뜻이다. `@Get()`은 해당 메서드가 HTTP Method인 GET 요청을 담당한다는 의미다.

라우팅 정보와 클래스의 역할이 코드에 드러나기 때문에 전체 구조를 비교적 쉽게 파악할 수 있다.

### 의존성 주입

의존성 주입(Dependency Injection)은 NestJS의 핵심 개념이다. (이 의존성 주입은 Spring Framework에서도 쓰이는 개념으로 기본적으로 알아두는게 좋다)

어떤 클래스가 필요한 객체를 직접 생성하지 않고, 외부에서 전달받아 사용하는 방식이다.

```typescript
@Injectable()
export class UsersService {
  findAll() {
    return ['Kim', 'Lee', 'Park'];
  }
}

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}
```

`UsersController`는 `UsersService`를 직접 `new`로 생성하지 않는다. NestJS의 의존성 주입 컨테이너가 필요한 인스턴스를 만들어 생성자(constructor)에 전달한다.

이 구조를 사용하면 클래스 간 결합이 줄어든다. 테스트할 때 실제 서비스 대신 가짜 객체를 주입하기도 쉬워진다.

# NestJS의 핵심 구성 요소

### 1. Module

Module은 관련된 기능을 하나의 단위로 묶는다.

예를 들어 사용자 기능에는 사용자 Controller, Service, Repository가 필요할 수 있다. 이를 `UsersModule`에 모아 관리할 수 있다.

```typescript
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}
```

`@Module()`에는 주로 다음 항목이 들어간다.

- `imports`: 현재 모듈에서 사용할 다른 모듈
- `controllers`: 요청을 처리할 Controller
- `providers`: 사용할 Service나 Repository 등의 Provider
- `exports`: 다른 모듈에 공개할 Provider

모든 NestJS 애플리케이션에는 시작점이 되는 루트 모듈이 있으며, 일반적으로 `AppModule`이라는 이름을 사용한다.

### 2. Controller

Controller는 클라이언트의 요청을 받고 응답을 반환한다.

```typescript
import { Controller, Get, Param, Post, Body } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get()
  findAll() {
    return '모든 사용자를 조회합니다.';
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return `${id}번 사용자를 조회합니다.`;
  }

  @Post()
  create(@Body() body: CreateUserDto) {
    return body;
  }
}
```

Controller에서는 다음과 같은 데코레이터를 자주 사용한다.

- `@Get()`, `@Post()`, `@Patch()`, `@Delete()`: HTTP 메서드 지정
- `@Param()`: URL 경로의 매개변수 추출
- `@Query()`: 쿼리스트링 추출
- `@Body()`: 요청 본문 추출
- `@Headers()`: 요청 헤더 추출

Controller에는 요청과 응답을 연결하는 코드만 두고, 복잡한 비즈니스 로직은 Service로 분리하는 것이 일반적이다.

### 3. Provider와 Service

Provider는 NestJS의 의존성 주입 컨테이너가 관리하는 객체다. Service, Repository, Factory, Helper 등이 Provider가 될 수 있다.

그중 Service는 비즈니스 로직을 담당하는 가장 대표적인 Provider다.

```typescript
import { Injectable, NotFoundException } from '@nestjs/common';

@Injectable()
export class UsersService {
  private readonly users = [
    { id: 1, name: 'Kim' },
    { id: 2, name: 'Lee' },
  ];

  findOne(id: number) {
    const user = this.users.find((item) => item.id === id);

    if (!user) {
      throw new NotFoundException('사용자를 찾을 수 없습니다.');
    }

    return user;
  }
}
```

`@Injectable()`을 붙인 클래스는 다른 클래스에 주입될 수 있다. 데이터 조회나 정책 판단 같은 핵심 로직을 Controller에서 분리하면 같은 기능을 여러 곳에서 재사용하기 쉬워진다.

### 4. DTO

DTO(Data Transfer Object)는 계층 사이에서 전달되는 데이터의 형태를 정의하는 객체다.

```typescript
export class CreateUserDto {
  name!: string;
  email!: string;
}
```

DTO를 사용하면 Controller가 어떤 데이터를 받는지 명확해지고, API 문서 생성이나 입력값 검증에도 활용할 수 있다.

`class-validator`와 NestJS의 `ValidationPipe`를 함께 사용하면 요청 데이터를 검증할 수 있다.

```typescript
import { IsEmail, IsString, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name!: string;

  @IsEmail()
  email!: string;
}
```

```typescript
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    transform: true,
  }),
);
```

이렇게 설정하면 정의되지 않은 필드를 제거하고, 잘못된 입력에는 자동으로 오류 응답을 반환할 수 있다.

# 요청은 어떤 과정을 거칠까?

NestJS는 요청과 응답 사이에 여러 실행 계층을 둘 수 있다.

전체 흐름을 단순화하면 다음과 같다.

```text
클라이언트 요청
→ Middleware
→ Guard
→ Interceptor
→ Pipe
→ Controller
→ Service
→ Interceptor
→ 클라이언트 응답
```

각 구성 요소의 역할은 다음과 같다.

### Middleware

요청이 본격적으로 처리되기 전에 공통 작업을 수행한다. 요청 로그, 쿠키 처리, 헤더 설정 등에 사용할 수 있다.

### Guard

요청을 계속 처리해도 되는지 판단한다. 로그인 여부나 사용자 권한을 검사하는 인증·인가 로직에 주로 사용된다.

### Pipe

Controller에 값이 전달되기 전에 입력을 검증하거나 변환한다. 문자열로 들어온 ID를 숫자로 바꾸거나 DTO의 유효성을 검사하는 것이 대표적이다.

### Interceptor

Controller 실행 전후의 흐름을 감싼다. 응답 형식을 통일하거나, 실행 시간을 측정하거나, 캐시를 적용할 때 사용할 수 있다.

### Exception Filter

애플리케이션에서 발생한 예외를 잡아 적절한 HTTP 응답으로 변환한다. 서비스 전체에서 일관된 오류 응답 형식을 만들 때 유용하다.

각 기능의 책임이 분리되어 있기 때문에 인증이나 로깅 같은 코드를 모든 Controller에 반복해서 작성하지 않아도 된다.

# NestJS 프로젝트 시작하기

Nest CLI를 설치하면 기본 프로젝트를 빠르게 만들 수 있다.

```bash
npm install -g @nestjs/cli
nest new my-api
cd my-api
npm run start:dev
```

개발 서버가 실행되면 기본적으로 `http://localhost:3000`에서 애플리케이션을 확인할 수 있다.

생성된 프로젝트의 대표적인 파일은 다음과 같다.

```text
src/
├── app.controller.ts
├── app.controller.spec.ts
├── app.module.ts
├── app.service.ts
└── main.ts
```

- `main.ts`: 애플리케이션을 생성하고 서버를 실행하는 진입점
- `app.module.ts`: 루트 모듈
- `app.controller.ts`: 기본 요청을 처리하는 Controller
- `app.service.ts`: 기본 비즈니스 로직을 담는 Service
- `app.controller.spec.ts`: Controller 테스트 파일

CLI를 이용하면 필요한 구성 요소도 생성할 수 있다.

```bash
nest generate module users
nest generate controller users
nest generate service users
```

축약형인 `nest g module users`, `nest g controller users`, `nest g service users`도 사용할 수 있다.

# Express와 NestJS의 차이

Express와 NestJS는 완전히 경쟁하는 기술이라기보다 추상화 수준이 다르다. NestJS는 기본적으로 Express를 HTTP 플랫폼으로 사용한다.

| 구분 | Express | NestJS |
|---|---|---|
| 성격 | 미니멀한 웹 프레임워크 | 구조화된 애플리케이션 프레임워크 |
| 기본 언어 | JavaScript | TypeScript 중심 |
| 프로젝트 구조 | 개발자가 직접 결정 | Module 중심의 구조 제공 |
| 의존성 주입 | 직접 구성 | 기본 제공 |
| 학습 난이도 | 비교적 낮음 | 개념이 많아 초기 학습 필요 |
| 자유도 | 높음 | 일정한 규칙과 패턴을 따름 |
| 적합한 환경 | 작은 API, 빠른 프로토타입 | 중대형 서비스, 협업 프로젝트 |

작은 서버나 간단한 API라면 Express가 더 빠르고 가벼울 수 있다. 여러 도메인과 개발자가 참여하는 장기 프로젝트라면 NestJS의 구조가 더 큰 장점이 된다.

# NestJS로 만들 수 있는 것

NestJS는 일반적인 REST API 외에도 다양한 서버 애플리케이션을 지원한다.

- REST API 서버
- GraphQL 서버
- WebSocket 기반 실시간 서비스
- 마이크로서비스
- gRPC 서비스
- 메시지 큐 기반 비동기 처리
- 예약 작업과 배치 프로그램
- 서버 렌더링 애플리케이션

데이터베이스 역시 특정 기술에 종속되지 않는다. TypeORM, Prisma, Mongoose, Sequelize, MikroORM 등을 프로젝트 요구사항에 맞게 연결할 수 있다.

Swagger/OpenAPI 연동을 사용하면 Controller와 DTO의 정보를 이용해 API 문서를 생성할 수도 있다. 인증에는 Passport, 설정 관리에는 `@nestjs/config`, 스케줄 작업에는 `@nestjs/schedule` 같은 공식 패키지를 활용할 수 있다.

# NestJS의 장점

### 일관된 프로젝트 구조

Module, Controller, Service의 역할이 명확해 여러 개발자가 함께 작업해도 코드 구조를 예측하기 쉽다.

### 높은 유지보수성과 확장성

기능을 모듈 단위로 분리할 수 있어 프로젝트가 커져도 책임의 경계를 관리하기 좋다.

### 테스트하기 좋은 구조

의존성 주입을 기본으로 사용하기 때문에 실제 데이터베이스나 외부 API 대신 테스트용 객체를 주입하기 쉽다.

### 풍부한 기능

입력 검증, 인증, 캐싱, 로깅, WebSocket, GraphQL, 마이크로서비스 등 서버 개발에 필요한 기능을 공식 문서와 패키지에서 폭넓게 다룬다.

### Express 생태계 활용

기본 플랫폼이 Express이므로 기존 Express 미들웨어와 Node.js 패키지의 상당 부분을 활용할 수 있다. 성능이나 요구사항에 따라 Fastify 어댑터를 선택할 수도 있다.

# 단점과 주의할 점

NestJS는 처음 배울 때 알아야 할 개념이 많다. Module, Provider, Guard, Pipe, Interceptor, 의존성 주입의 관계를 이해하기 전까지는 간단한 기능도 복잡하게 느껴질 수 있다.

데코레이터와 프레임워크의 자동 처리에 익숙하지 않으면 코드가 실제로 어떤 순서로 실행되는지 파악하기 어려울 수도 있다. 문제가 발생했을 때는 요청 생명주기와 의존성 주입 컨테이너의 동작을 이해해야 한다.

또한 작은 프로젝트에서는 파일 수와 초기 설정이 과하게 느껴질 수 있다. 단순한 API 하나를 만들기 위해 Module, Controller, Service, DTO 파일이 필요하다면 Express나 Fastify를 직접 사용하는 편이 효율적일 수 있다.

구조를 제공한다는 장점이 지나친 계층 분리로 이어지지 않도록 주의해야 한다. 규모가 작은 기능까지 무조건 여러 계층으로 나누면 오히려 탐색하기 어려운 코드가 될 수 있다.

# 언제 NestJS를 사용하면 좋을까?

다음과 같은 상황이라면 NestJS가 좋은 선택이 될 수 있다.

- TypeScript로 백엔드 서비스를 개발하려는 경우
- 여러 개발자가 장기간 유지보수할 프로젝트
- 사용자, 주문, 결제처럼 도메인이 여러 개로 나뉘는 서비스
- 인증, 권한, 검증, 로깅 같은 공통 기능이 많은 프로젝트
- REST API에서 향후 GraphQL이나 마이크로서비스로 확장할 가능성이 있는 경우
- 의존성 주입과 객체지향적인 설계를 선호하는 팀
- 자동화된 단위 테스트와 통합 테스트가 중요한 서비스

반대로 단순한 서버리스 함수, 매우 작은 API, 짧은 프로토타입이라면 더 가벼운 프레임워크가 적합할 수 있다.

프레임워크 선택에서 중요한 것은 어떤 기술이 무조건 더 좋으냐가 아니다. 서비스 규모, 팀의 경험, 성능 요구사항, 운영 기간을 함께 고려할 수 있어야한다.

# 처음 공부할 때 추천하는 순서

NestJS의 모든 기능을 처음부터 공부할 필요는 없다. 다음 순서로 작은 CRUD API를 만들어 보는 것이 이해하기 쉽다.

```text
Module과 프로젝트 구조
→ Controller와 라우팅
→ Service와 의존성 주입
→ DTO와 입력값 검증
→ 데이터베이스 연결
→ 예외 처리
→ 인증과 Guard
→ Interceptor와 로깅
→ 테스트 및 API 문서화
```

게시글이나 강의의 코드를 그대로 외우기보다는 요청 하나가 Controller, Service, 데이터베이스를 어떻게 거쳐 응답으로 돌아오는지 추적하는 것이 중요하다.

# 마무리

NestJS는 현재 나도 개발에 주력으로 쓰고있는 프레임워크인 만큼 애정도가 상당히 깊다.

NestJS를 사용해 서버개발을 한다면 TypeScript, 데코레이터, 의존성 주입, 모듈 시스템을 이용해 확장 가능하고 테스트하기 쉬운 서버 애플리케이션을 만들 수 있다.

NestJS의 가장 큰 장점은 단순히 기능이 많다는 점이 아니다. 개발자가 늘어나고 서비스가 복잡해져도 코드의 역할과 위치를 예측할 수 있게 해준다는 데 있다. (뭐 물론 대부분의 프레임워크가 이럴려고 사용하는거긴 하지만...)

당연한 얘기지만 모든 프로젝트에 NestJS가 필요한 것은 아니다. 엔터프라이즈급으로 간다면 자바 공화국인 한국에서 밀고있는 전자정부 프레임워크의 기반이 되는 Spring Framework부터 여전히 한국의 여러 작은 중소기업에서 쓰고있는 PHP의 Laravel, CodeIgniter 등 이 외에도 여러 선택지는 많다.

만약 작은 서비스, 작은 API에서는 NestJS가 구조가 부담이 될 수 있고 초기 학습 비용도 존재한다. 하지만 여러 기능이 연결되는 중대형 백엔드 서비스를 TypeScript로 개발한다면 충분히 고려할 가치가 있다.

NestJS란? 개요부터 핵심 구조와 장단점까지

![nestjs](https://librarian-blog-images.s3.ap-northeast-2.amazonaws.com/709b0388-fd0c-4648-a768-381a590ad90e_nestjs.jpg)

> NestJS 패키지 설치시 ts-jest 때문에 설치가 안되는 현상

# 2023년 1월 중순부터 현재(1월 31일)까지 ts-jest 설치가 안되는 현상이 발견됨

1. 일단 이렇게 패키지 설치가 안될경우에 패키지의 문제인지 아닌지를 확인하기위해서 스택오버플로우에 검색을 해봤지만 외국인들은 설치가 잘만 되는것 같았다
2. 그럼 집에있는 네트워크가 문제인가 싶어 노트북에 핸드폰 테더링을 연결해서 install 해봤지만 실패 (집에있는 인터넷, 핸드폰 모두 KT 사용중)
3. 그렇다면 생각해볼 수 있는건 통신사 문제라는것으로 결론이 났고 그렇게 구글링 시작


# 현재 이 문제는 KT를 사용하고 있는 한국사람들 대상으로 일어나고 있는 문제가 맞았다

1. https://github.com/kulshekhar/ts-jest/issues/3992 확인해보니
2. 한국인들이 이슈를 열어 놓은게 있어 읽어봤다
3. KT망에서만 설치가 안되는것을 확인했다
4. npm support 팀에서 KT망에서만 안되는 원인을 파악중이라고 한다


# 해결책
`npm config set registry https://registry.npmjs.cf/`을 터미널에 입력해 mirror로 바꿔주고 install 하면 제대로 설치된다
나중에 이슈가 해결되면

`npm config set registry https://registry.npmjs.org/`
로 다시 바꿔주는것도 잊지말자..

# 결론
KT나 npm쪽에서 아직 공식적인 발표가 없어 뭐라 하긴 힘들지만... 1월 초까지만 해도 분명 잘됐었다 지금 KT 사용자만 안되는걸로봐선 거의 KT 잘못이 확실한것 같다... 통신사를 바꾸던지 해야지...



NestJS

이 주제의 기록

GraphQL vs REST API : 2025년 기준으로 다시 생각해보기

NestJS란? 개요부터 핵심 구조와 장단점까지

ts-jest 설치 안되는 현상