김신건의 로그 - 위키 / frameworks

[비교] JPA EAGER vs Rails eager_load

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

JPA 와 Rails 는 둘 다 “eager” 라는 용어를 ORM 의 연관 로딩 전략에 사용한다. 이름은 비슷하지만 의미는 정반대.

N+1 문제란

N+1 문제는 연관 객체를 지연 로딩(lazy loading)할 때 발생하는 성능 패턴이다. 부모 목록 1회 쿼리 후, 각 부모의 연관 객체를 N번 추가 쿼리하는 구조다.

sequenceDiagram
    participant APP as 애플리케이션
    participant DB as 데이터베이스

    APP->>DB: SELECT * FROM posts (1번)
    DB-->>APP: [post1, post2, post3, ... postN]

    loop N번 반복
        APP->>DB: SELECT * FROM users WHERE id = ?
        DB-->>APP: author
    end

    Note over APP,DB: 총 N+1번 쿼리 발생

N=100 이면 101번 쿼리. N=1000 이면 1001번 쿼리. ORM의 편리함이 성능 문제의 원인이 된다.

JPA FetchType.EAGER: 매핑 선언 시점에 영구 설정. 그 entity 를 조회할 때마다 항상 자동으로 함께 로드. 끄는 게 권장.
Rails eager_load: 쿼리 시점에 옵트인. 그 쿼리에서만 JOIN 으로 함께 로드. 권장 패턴.

이름이 같아 혼동하기 쉬워 별도 페이지로 정리한다.

로딩 전략 비교 시각화

flowchart LR
    subgraph JPA["JPA 전략"]
        JL["FetchType.LAZY<br/>(기본 권장)"]
        JE["FetchType.EAGER<br/>(기본값, 위험)"]
        JF["JOIN FETCH<br/>(쿼리 시점 명시)"]
        JB["@BatchSize<br/>(IN절 묶음)"]
        JG["EntityGraph<br/>(동적 fetch)"]
    end

    subgraph RAILS["Rails 전략"]
        RL["lazy (기본)"]
        RPL["preload<br/>(2쿼리 IN절)"]
        REL["eager_load<br/>(LEFT OUTER JOIN)"]
        RI["includes<br/>(자동 선택)"]
    end

    JE -->|"N+1 유발"| PROBLEM["N+1 문제"]
    RL -->|"N+1 유발"| PROBLEM

    JF -->|"해결"| SOL["N+1 해결"]
    JB -->|"해결"| SOL
    JG -->|"해결"| SOL
    RPL -->|"해결"| SOL
    REL -->|"해결"| SOL
    RI -->|"해결"| SOL

1줄 비교

측면	JPA `EAGER`	Rails `eager_load`
선언 위치	Entity 매핑 (`@ManyToOne(fetch=EAGER)`)	Query 호출 (`.eager_load(:assoc)`)
적용 범위	그 entity 의 모든 조회	그 쿼리만
변경 가능성	코드 수정 + 재배포	쿼리마다
권장 사용	거의 항상 비권장	권장 (또는 includes)
기본값	`@ManyToOne` 은 EAGER (위험)	명시 안 함 (lazy)
실행 방식	즉시 SELECT (별도 또는 JOIN)	LEFT OUTER JOIN 단일 쿼리

JPA EAGER 의 의미

@Entity
class Post {
    @ManyToOne(fetch = FetchType.EAGER)   // ← 기본값 (위험)
    @JoinColumn(name = "author_id")
    User author;
}

List<Post> posts = em.createQuery("SELECT p FROM Post p", Post.class).getResultList();
// → posts SELECT 1번 + 각 post 의 author SELECT N번 = N+1
// 또는 Hibernate 의 batch fetch 가 켜있으면 IN 절로 일부 묶임

“Post 가 어디서 조회되든 author 도 함께 로드”. 매핑이 영구. 끄려면 코드 수정.

위험:

N+1 폭탄
깊은 그래프 (Post → Comment → User → Profile) 가 의도치 않게 전부 로드
끌 수 없음 (LAZY 로 매핑 변경 후 재배포 필요)

규칙: 모든 연관 LAZY 선언, 쿼리마다 필요한 것만 fetch join / EntityGraph / @BatchSize 로 명시. [[spring-jpa-fetch-type]] 참고.

Rails eager_load 의 의미

class Post < ApplicationRecord
  belongs_to :author, class_name: 'User'
end

# 기본 (lazy)
posts = Post.all
posts.each { |p| puts p.author.name }   # N+1

# eager_load 옵트인
posts = Post.eager_load(:author)
# → 1쿼리: SELECT p.*, u.* FROM posts LEFT OUTER JOIN users ON ...
posts.each { |p| puts p.author.name }   # 추가 쿼리 없음

“이 쿼리 한 번만 author 도 함께”. 쿼리 시점 결정. 다음 쿼리는 lazy.

권장 패턴: 연관은 lazy by default, 필요할 때만 includes/preload/eager_load 명시. [[rails-query-optimization]] 참고.

정확한 매핑

JPA 와 Rails 의 개념적 대응:

Rails 메서드	해당 JPA 패턴	발생 쿼리
`preload(:assoc)`	`@BatchSize` 또는 `JOIN FETCH` 안 쓰는 explicit 2-쿼리	2 쿼리 (부모 + 자식 IN)
`eager_load(:assoc)`	`JOIN FETCH p.assoc` JPQL	1 쿼리 (LEFT OUTER JOIN)
`includes(:assoc)`	(없음)	preload 또는 eager_load 자동
`references(:assoc)`	(없음, JPQL 의 JOIN FETCH 와 유사)	eager_load 강제

JPA 의 FetchType.EAGER 는 Rails 에 직접적 대응 없음. 굳이 비유하면 association 정의에 eager_load(:assoc) 를 default scope 로 박아두는 것 (안티패턴).

Rails 의 “EAGER” 라는 단어

Rails 문서 / 커뮤니티에서 “eager loading” 은 일반적으로 includes / preload / eager_load 셋을 통칭. “eager 로 가져온다” = “lazy 안 하고 미리 가져온다” 의미.

JPA 의 EAGER 는 fetch type = 영구 매핑 속성. 다른 개념.

권장 패턴 비교

// JPA: lazy + 쿼리마다 명시
@Entity
class Post {
    @ManyToOne(fetch = FetchType.LAZY)
    User author;
}

@Query("SELECT p FROM Post p JOIN FETCH p.author")
List<Post> findAllWithAuthor();

# Rails: 기본 lazy + 쿼리마다 명시
class Post < ApplicationRecord
  belongs_to :author, class_name: 'User'
end

def self.with_author
  includes(:author)
end

두 ORM 모두 lazy by default + 쿼리 시점에 fetch 선택 이 best practice. JPA 가 기본을 EAGER 로 잘못 정한 게 함정.

N+1 디버깅 도구

항목	JPA / Hibernate	Rails
로그	`org.hibernate.SQL=DEBUG`	`ActiveRecord::Base.logger`
정적 분석	Hypersistence Utils	bullet gem
자동 감지	(수동)	`strict_loading` (Rails 6.1+)
Profiler	p6spy, datasource-proxy	rack-mini-profiler
인덱스 검사	Hibernate Statistics	EXPLAIN ANALYZE

bullet gem 처럼 자동 N+1 알림 도구가 JPA 진영엔 약함. 직접 통합 테스트에서 Statement count 측정.

JPA: EntityGraph (동적 Fetch 전략)

@NamedEntityGraph 또는 동적 EntityGraph로 쿼리별 fetch 전략을 지정한다:

// 정적 선언
@Entity
@NamedEntityGraph(
  name = "Post.withAuthor",
  attributeNodes = @NamedAttributeNode("author")
)
class Post {
  @ManyToOne(fetch = FetchType.LAZY)
  User author;

  @OneToMany(fetch = FetchType.LAZY)
  List<Comment> comments;
}

// 사용
EntityGraph graph = em.getEntityGraph("Post.withAuthor");
Map<String, Object> hints = Map.of("jakarta.persistence.fetchgraph", graph);
List<Post> posts = em.createQuery("SELECT p FROM Post p", Post.class)
  .setHint("jakarta.persistence.fetchgraph", graph)
  .getResultList();

Spring Data JPA에서:

@Repository
public interface PostRepository extends JpaRepository<Post, Long> {

  @EntityGraph(attributePaths = {"author"})
  List<Post> findAll();

  @EntityGraph(attributePaths = {"author", "comments"})
  Optional<Post> findById(Long id);
}

EntityGraph 타입:

FETCH: 명시한 필드는 EAGER, 나머지는 LAZY
LOAD: 명시한 필드는 EAGER, 나머지는 매핑 기본값 유지

JPA: @BatchSize (N+1 완화)

@BatchSize는 N+1을 완전히 없애지는 않지만, N번 쿼리를 IN절 묶음으로 줄인다:

@Entity
class Post {
  @OneToMany
  @BatchSize(size = 25)
  List<Comment> comments;
}

SELECT * FROM comments WHERE post_id IN (1, 2, ..., 25) 형태로 25개씩 묶어서 조회. N=100 이면 100번 → 4번으로 감소.

전역 배치 크기 설정 (Hibernate):

# application.yml
spring:
  jpa:
    properties:
      hibernate.default_batch_fetch_size: 100

Rails: includes / preload / eager_load 선택 기준

세 메서드는 동작 방식이 다르다:

# preload: 항상 2번 쿼리 (부모 SELECT + IN절 자식 SELECT)
Post.preload(:author)
# → SELECT * FROM posts
# → SELECT * FROM users WHERE id IN (1, 2, 3, ...)

# eager_load: 항상 JOIN 1번 쿼리
Post.eager_load(:author)
# → SELECT posts.*, users.* FROM posts
#     LEFT OUTER JOIN users ON posts.author_id = users.id

# includes: Rails가 상황에 따라 preload 또는 eager_load 자동 선택
Post.includes(:author)
# where 조건에 연관 테이블 컬럼 사용 시 → eager_load
# 그 외 → preload
Post.includes(:author).where('users.active = ?', true).references(:author)
# → eager_load 강제

중첩 연관 로딩:

# posts → author → profile 까지 한번에
Post.includes(author: :profile)

# 여러 연관 동시에
Post.includes(:author, :comments, :tags)

# 3단계 중첩
Post.includes(comments: { author: :profile })

Rails strict_loading (6.1+):

# 모델에서 lazy loading 완전 차단 (개발/테스트 환경에서 N+1 조기 발견)
class ApplicationRecord < ActiveRecord::Base
  self.strict_loading_by_default = true
end

# 특정 쿼리에만 적용
Post.strict_loading.all

함정 비교

JPA 함정

@ManyToOne 기본 EAGER: 명시적으로 LAZY 안 하면 위험
@OneToOne 양방향 LAZY 안 됨 (proxy 못 만듦): bytecode enhancement 또는 optional=false
컬렉션 fetch join + Pageable = in-memory paging: OOM 위험
OSIV (Open Session In View) 가 LAZY 함정 가림: 운영에선 끄기 권장 spring.jpa.open-in-view=false

Rails 함정

find_by + includes 일부 버전에서 includes 무시: .where().first 패턴 권장
uniq/distinct + includes 의 row count 미묘함
select 시 FK 누락: select(:name).includes(:school) 깨짐
polymorphic 은 JOIN 불가, preload 강제

작은 결과 / 큰 결과의 전략

결과 크기	JPA 권장	Rails 권장
부모 < 10	JOIN FETCH	eager_load
부모 < 1000, 자식 비대	2 쿼리 (`@BatchSize`)	preload
Pageable	EntityGraph + slice (collection 제외)	includes + paging
깊은 nested	단계별 explicit fetch	preload 단계 분리

정리

질문	답
JPA EAGER 와 Rails eager_load 가 같은 뜻인가?	아니다. 이름만 같다.
JPA EAGER 사용 권장하나?	아니다. 모든 연관 LAZY.
Rails eager_load 사용 권장하나?	그렇다. lazy default + 쿼리마다 명시.
둘 다 N+1 해결책인가?	Rails eager_load 는 명백한 해결책. JPA EAGER 는 종종 N+1 의 원인.

이름이 미묘하게 같아서 “EAGER 면 빠른 것” 으로 단순화하지 말 것. 두 ORM 의 정반대 권장 사항을 기억.

쿼리 로그로 N+1 확인

JPA / Hibernate

# application.yml
logging:
  level:
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE

// p6spy로 실제 파라미터까지 확인
// pom.xml: p6spy 의존성 추가 후
// spy.properties: appender=com.p6spy.engine.spy.appender.Slf4JLogger

Rails

# config/environments/development.rb
config.log_level = :debug  # SQL 쿼리 전부 출력

# bullet gem: N+1 자동 감지 (개발 환경)
# Gemfile
gem 'bullet', group: :development

# config/environments/development.rb
config.after_initialize do
  Bullet.enable = true
  Bullet.alert = true
  Bullet.rails_logger = true
end

bullet gem이 N+1을 감지하면 로그에:

USE eager loading detected
  Post => [:author]
  Add to your query: .includes([:author])

전략 선택 요약

상황	JPA 선택	Rails 선택
부모 < 10개 + 연관 1개	`JOIN FETCH`	`eager_load`
부모 수백 개 + 연관 1개	`@BatchSize` 또는 `JOIN FETCH`	`preload` 또는 `includes`
연관 컬럼으로 WHERE 필터링	`JOIN FETCH` + JPQL where	`eager_load` + `where`
페이지네이션 + 연관	`EntityGraph` (컬렉션 제외)	`includes` (컬렉션 주의)
다단계 중첩	단계별 쿼리 + `@BatchSize`	`preload` 단계 분리
개발 중 N+1 조기 감지	Hibernate Statistics / p6spy	bullet gem + `strict_loading`

Astro

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Astro 는 콘텐츠 중심 사이트를 위한 정적 사이트 프레임워크다. “Islands Architecture”로 필요한 부분만 hydration하기 때문에 기본 JS 전송량이 0에 가깝다.

이 블로그(shinkeonkim.com)가 Astro 6으로 구축됐다.

마크다운 / MDX 콘텐츠 렌더링
자체 remark 플러그인으로 위키링크 자동 변환 ([[BrainDB]] 참고)
[[D3]] 기반 그래프 페이지의 React Island 호스팅
GitHub Actions를 통한 정적 빌드 → GitHub Pages 배포

사용 상황

상황	적합 여부
블로그, 문서 사이트	✅
콘텐츠 중심 마케팅 페이지	✅
SPA (풍부한 인터랙션 위주)	❌ (Next.js / SvelteKit 추천)
서버 사이드 렌더링 위주 앱	부분 적합 (adapter 필요)
다중 프레임워크 혼용	✅ (React + Vue + Svelte 공존 가능)

Islands Architecture

flowchart TB
    SERVER["빌드 타임 서버"]
    HTML["정적 HTML 출력"]

    subgraph PAGE["렌더링된 페이지"]
        STATIC1["정적 마크다운 콘텐츠"]
        ISLAND1["Island: React 컴포넌트<br/>client:load"]
        STATIC2["정적 이미지 / 텍스트"]
        ISLAND2["Island: D3 그래프<br/>client:visible"]
    end

    BUNDLE1["React 번들 (즉시 hydration)"]
    BUNDLE2["D3 번들 (뷰포트 진입 시)"]

    SERVER --> HTML --> PAGE
    ISLAND1 -.->|"개별 번들"| BUNDLE1
    ISLAND2 -.->|"개별 번들"| BUNDLE2

핵심 개념: 페이지 대부분은 정적 HTML이고, 인터랙션이 필요한 “Island”만 JS 번들을 로드한다. 각 Island는 독립적으로 hydration된다.

client: 디렉티브

디렉티브	언제 hydration
`client:load`	즉시 (페이지 로드 시)
`client:idle`	브라우저가 idle 상태일 때
`client:visible`	뷰포트에 진입할 때
`client:media="(max-width: 768px)"`	미디어 쿼리 충족 시
`client:only="react"`	SSR 없이 클라이언트 전용

핵심 기능

Content Collections

타입 안전 콘텐츠 관리. src/content/ 아래 컬렉션을 content.config.ts에 스키마로 정의한다.

// src/content.config.ts

const posts = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.date(),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { posts };

// 페이지에서 타입 안전 쿼리
const allPosts = await getCollection('posts', ({ data }) => !data.draft);

Component Islands

React, Vue, Svelte 등 여러 프레임워크 컴포넌트를 같은 페이지에서 사용 가능하다:

---


---

<!-- mdx-component: ReactCounter -->
<!-- mdx-component: VueWidget -->

Adapters (서버 배포)

기본은 정적 출력. 서버 기능 필요 시 adapter 추가:

Adapter	플랫폼
`@astrojs/vercel`	Vercel Edge / Serverless
`@astrojs/netlify`	Netlify Functions
`@astrojs/node`	Node.js (자체 서버)
`@astrojs/cloudflare`	Cloudflare Workers

View Transitions

페이지 전환 시 부드러운 애니메이션. MPA(Multi-Page App)에서 SPA처럼 느껴지는 전환을 제공한다.

---

---

<head>
  <!-- mdx-component: ViewTransitions -->
</head>

특정 요소에 이름 부여해 전환 애니메이션 연결:

<img src={post.cover} transition:name="hero-image" />

Astro DB

내장 SQLite 기반 데이터베이스. 빌드 시 seed 데이터 주입 가능.

// db/config.ts

const Comments = defineTable({
  columns: {
    id: column.number({ primaryKey: true }),
    postSlug: column.text(),
    body: column.text(),
  },
});

export default defineDb({ tables: { Comments } });

MDX 지원

마크다운에 JSX 컴포넌트를 삽입. @astrojs/mdx 통합으로 활성화된다.


# 2024년 데이터 분석

<!-- mdx-component: Chart -->

일반 마크다운과 컴포넌트를 혼용할 수 있다.

Integrations (통합)

공식 + 커뮤니티 통합을 astro.config.mjs에 추가한다:





export default defineConfig({
  integrations: [mdx(), react(), sitemap()],
  markdown: {
    remarkPlugins: [remarkWikiLink],
    rehypePlugins: [rehypePrettyCode],
  },
});

프로젝트 구조

src/
├── content/        ← Content Collections (posts, wiki, notes)
├── pages/          ← 파일 기반 라우팅 (.astro, .md, .mdx)
├── layouts/        ← 재사용 레이아웃 컴포넌트
├── components/     ← UI 컴포넌트 (Astro + React 혼용)
└── styles/         ← 글로벌 CSS

public/             ← 정적 파일 (이미지, 폰트, favicon)

실전 예시: 동적 라우팅

---
// src/pages/posts/[slug].astro

export async function getStaticPaths() {
  const posts = await getCollection('posts');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---

<article>
  <h1>{post.data.title}</h1>
  <!-- mdx-component: Content -->
</article>

대안

프레임워크	특징	선택 기준
Next.js	React, SSR/SSG 혼합	React 앱, 풍부한 인터랙션
Gatsby	React, GraphQL 기반	CMS 연동, 플러그인 생태계
SvelteKit	Svelte 기반, 경량	빠른 개발, 작은 번들
Nuxt.js	Vue 기반, SSR/SSG	Vue 팀 선택
Eleventy	프레임워크 무관, 순수 정적	극단적 단순함 선호
Hugo	Go 기반, 매우 빠른 빌드	수천 개 이상 포스트

[!TIP] Astro는 콘텐츠 사이트에 강하다. 인터랙션이 핵심인 앱이라면 Next.js 또는 SvelteKit이 더 적합하다.

함정

[!WARNING] Islands 간 상태 공유 어려움: 각 Island가 독립적이라 Island 간 상태를 공유하려면 nanostore, zustand 같은 클라이언트 상태 라이브러리가 필요하다.

[!CAUTION] .astro 파일에서 async/await: getCollection() 등은 서버 전용이다. 클라이언트에서 document 접근은 브라우저 전용 Island 안에서만 가능하다.

[!WARNING] client:only SSR 누락: client:only는 서버에서 렌더링하지 않으므로, SEO가 중요한 콘텐츠에 사용하면 안 된다.

[!IMPORTANT] remark / rehype 플러그인 순서: MDX 플러그인 체인에서 순서가 중요하다. 특히 위키링크 변환 플러그인은 다른 플러그인보다 먼저 실행해야 할 수 있다.

[!WARNING] Content Collections 타입 갱신: frontmatter 스키마를 변경하면 .astro/types.d.ts를 재생성해야 한다. bun astro sync로 수동 갱신 가능.

BrainDB

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

BrainDB 는 마크다운 파일을 SQLite 기반 데이터베이스로 인덱싱해, 위키링크 처리, 백링크 추출, 콘텐츠 그래프 생성, 깨진 링크 감지를 제공하는 [[Astro]] 통합 라이브러리다. stereobooster가 개발했다.

Obsidian 같은 개인 위키의 “콘텐츠 그래프” 기능을 Astro 정적 사이트에 구현할 수 있게 해주는 게 핵심 목표다.

제공 기능

기능	패키지 / API
위키링크 파싱	`@braindb/remark-wiki-link`
백링크 추출	`db.documentsTo(path)`
콘텐츠 그래프	`db.links()`, `db.documents()`
깨진 링크 감지	링크 대상 검증
Astro 통합	`@braindb/astro`
태그 쿼리	`db.tags()`

처리 흐름

flowchart LR
    MD["마크다운 파일들"]
    PARSE["remark 파싱"]
    WIKILINK["wikilink 추출"]
    SQLITE["SQLite 인덱스"]
    BACKLINK["백링크 맵"]
    GRAPH["콘텐츠 그래프<br/>(nodes + edges)"]
    ASTRO["Astro 빌드"]
    PAGE["페이지 렌더링<br/>(백링크 / 그래프 표시)"]

    MD --> PARSE
    PARSE --> WIKILINK
    WIKILINK --> SQLITE
    SQLITE --> BACKLINK
    SQLITE --> GRAPH
    BACKLINK --> ASTRO
    GRAPH --> ASTRO
    ASTRO --> PAGE

BrainDB는 빌드 타임에 모든 마크다운을 SQLite로 인덱싱하고, 위키링크 관계를 그래프로 만든다. 페이지 렌더링 시 해당 그래프 데이터를 주입해 백링크 목록과 그래프 뷰를 제공한다.

설치 및 기본 설정

bun add @braindb/astro @braindb/remark-wiki-link

// astro.config.mjs


export default defineConfig({
  integrations: [brainDb()],
});

remark 플러그인만 단독으로 사용하는 경우:


export default defineConfig({
  markdown: {
    remarkPlugins: [
      [remarkWikiLink, {
        aliasDivider: '|',
        wikiLinkClassName: 'wikilink',
        newClassName: 'broken',
      }],
    ],
  },
});

위키링크 변환

@braindb/remark-wiki-link는 이중 대괄호 위키링크 패턴을 HTML <a> 태그로 변환한다:

링크 대상이 존재하면 <a href="https://shinkeonkim.com/wiki/.../경로/">제목</a> 로 변환되고, 존재하지 않으면 <a class="wikilink broken">제목</a> 로 변환된다. 별칭 문법(제목|표시텍스트)으로 화면에 표시되는 텍스트를 별도로 지정할 수 있다.

링크 해석 우선순위: 파일 경로 → 파일명 → frontmatter title → frontmatter aliases.

지원 위키링크 문법 (이중 대괄호 패턴):

제목 기본 링크: 이중 대괄호로 제목을 감싸면 링크로 변환
제목|보여줄 텍스트 별칭 링크: 파이프로 표시 텍스트 지정
제목#앵커 섹션 링크: 샵으로 앵커 지정 (일부 버전)

콘텐츠 그래프 활용 예시

BrainDB의 그래프 데이터를 [[D3]] forceSimulation에 연결하는 패턴:

// src/pages/graph.astro


const db = await getBrainDb();
const nodes = db.documents().map(doc => ({
  id: doc.path(),
  title: doc.frontmatter().title,
  group: doc.frontmatter().category,
}));
const links = db.links().map(link => ({
  source: link.from(),
  target: link.to(),
}));

// GraphView.tsx (React Island)


export default function GraphView({ nodes, links }) {
  const svgRef = useRef(null);

  useEffect(() => {
    const simulation = d3.forceSimulation(nodes)
      .force('link', d3.forceLink(links).id(d => d.id))
      .force('charge', d3.forceManyBody().strength(-100))
      .force('center', d3.forceCenter(400, 300));
    // ... 렌더링 로직
  }, [nodes, links]);

  return <svg ref={svgRef} width={800} height={600} />;
}

콘텐츠 그래프 API


const db = await getBrainDb();

// 특정 페이지를 참조하는 페이지 목록 (백링크)
const backlinks = db.documentsTo('/wiki/network/tcp/');

// 전체 문서 목록
const nodes = db.documents();

// 전체 링크 목록 (edges)
const links = db.links();

// 태그 목록
const tags = db.tags();

이 데이터를 [[D3]] forceSimulation에 전달하면 인터랙티브 그래프 뷰가 된다.

이 블로그에서의 사용 (미사용)

원래 @braindb/astro를 astro.config.mjs integrations에 추가해서 쓰려고 했으나, 의존 패키지 better-sqlite3가 Node.js 26과 호환되지 않아 빌드가 깨졌다.

결국 작은 커스텀 remark 플러그인(src/plugins/remark-wikilink.mjs)으로 대체 구현했다:

위키링크 처리: src/plugins/remark-wikilink.mjs
백링크 추출: src/shared/lib/content/content-graph.ts
그래프 데이터: src/shared/lib/content/content-graph.ts

BrainDB가 제공하던 핵심 기능만 추려 보면 양이 많지 않아서, 직접 작성하는 편이 의존성도 가볍고 디버깅도 쉬웠다.

이 블로그의 커스텀 구현 아키텍처

BrainDB를 사용하지 않고 직접 구현한 위키링크 처리 흐름:

flowchart LR
    MD["마크다운 / MDX 파일"]
    REMARK["remark-wikilink.mjs<br/>(커스텀 플러그인)"]
    GRAPH["content-graph.ts<br/>(빌드 타임 그래프 구성)"]
    BACKLINKS["백링크 맵"]
    VALIDATE["validate-content.mjs<br/>(깨진 링크 감지)"]
    PAGE["페이지 렌더링<br/>(백링크 섹션 포함)"]
    GRAPHPAGE["그래프 페이지<br/>(/graph/)"]

    MD --> REMARK
    REMARK --> GRAPH
    GRAPH --> BACKLINKS
    GRAPH --> VALIDATE
    BACKLINKS --> PAGE
    GRAPH -->|"nodes + edges"| GRAPHPAGE

remark-wikilink.mjs는 이중 대괄호 위키링크를 AST 수준에서 <a> 태그로 변환하고, content-graph.ts는 모든 링크를 수집해 그래프 데이터와 백링크 맵을 생성한다.

BrainDB vs 커스텀 구현 비교

기능	BrainDB	커스텀 구현 (이 블로그)
위키링크 파싱	`@braindb/remark-wiki-link`	`remark-wikilink.mjs`
백링크	`db.documentsTo()`	`content-graph.ts`
그래프 데이터	`db.links()`	`content-graph.ts`
저장소	SQLite (better-sqlite3)	빌드 타임 메모리
깨진 링크 감지	내장	커스텀 validate 스크립트
Node 버전 의존성	네이티브 바이너리	없음
추가 번들 크기	better-sqlite3 바이너리	없음
설정 복잡도	낮음 (통합 추가만)	직접 구현 필요

유사 도구

도구	특징
Obsidian	데스크톱 마크다운 위키, 그래프 뷰 제공
Foam (VS Code)	VS Code 위키링크 확장
Dendron	계층 구조 노트 취급
Quartz	Hugo 기반 디지털 정원, 위키링크 지원
Digital Garden (Jekyll)	Jekyll 플러그인, GitHub Pages 배포

함정

[!CAUTION] better-sqlite3 Node 버전 의존성: better-sqlite3는 네이티브 C++ 바인딩을 사용하므로 Node.js 버전이 바뀌면 재빌드가 필요하다. Node 26에서 호환성 문제가 있었다.

[!WARNING] 빌드 타임에만 동작: BrainDB는 Astro 빌드 타임 통합이다. 런타임에 동적으로 콘텐츠를 추가하거나 위키링크를 갱신하는 기능은 없다.

[!TIP] 콘텐츠 양이 적고 Node 버전이 고정된 환경이라면 BrainDB 사용이 편하다. Node 버전이 자주 바뀌거나 네이티브 바이너리 의존을 피하고 싶다면 커스텀 구현을 고려할 것.

커스텀 구현 시 고려 사항

직접 위키링크/백링크 시스템을 구현할 때 알아야 할 사항:

링크 해석 우선순위: slug → 파일명 → frontmatter title → aliases 순으로 매칭
NFC 정규화: 한글 위키링크는 NFC 정규화 후 비교 (macOS와 Linux의 파일시스템 차이)
순환 참조: 그래프 구성 시 순환 링크 처리 필요
빌드 캐싱: 대용량 콘텐츠는 그래프 구성에 시간이 걸리므로 캐싱 고려

D3.js

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

D3 (Data-Driven Documents)는 데이터를 DOM 요소에 바인딩해 SVG, Canvas, HTML 기반 시각화를 만드는 JavaScript 라이브러리다. Mike Bostock이 2011년 발표했고, 현재 v7까지 출시됐다.

이 블로그의 그래프 페이지는 D3의 forceSimulation으로 위키 노드를 배치한다.

“차트 라이브러리”가 아닌 데이터-DOM 변환 엔진이다. Chart.js처럼 완성된 차트를 제공하지 않고, scale/selection/transition 등 저수준 빌딩 블록을 제공해 완전한 커스텀이 가능하다.

사용 상황

상황	D3 적합 여부
커스텀 인터랙티브 시각화	✅
단순 바 / 라인 / 파이 차트	❌ (Chart.js 추천)
네트워크 그래프 / 트리 레이아웃	✅
지리 시각화 (GeoJSON, 투영법)	✅
주식 / 시계열 데이터 분석	✅
빠른 대시보드 구축	❌ (ECharts 추천)

데이터 바인딩 흐름

flowchart TD
    DATA["데이터 배열"]
    SEL["d3.select / selectAll"]
    BIND[".data(array) 바인딩"]
    ENTER["Enter Selection (새 요소 처리)"]
    UPDATE["Update Selection (기존 요소 갱신)"]
    EXIT["Exit Selection (제거 요소 처리)"]
    APPEND[".append() 추가"]
    ATTR[".attr() .style() 갱신"]
    REMOVE[".remove() 제거"]
    DOM["DOM / SVG 결과"]

    DATA --> BIND
    SEL --> BIND
    BIND --> ENTER
    BIND --> UPDATE
    BIND --> EXIT
    ENTER --> APPEND --> DOM
    UPDATE --> ATTR --> DOM
    EXIT --> REMOVE

D3의 핵심 패턴: 데이터와 DOM 요소를 key로 매핑하고, 변화에 따라 enter/update/exit를 각각 처리한다.

핵심 개념

Selection

DOM 요소를 감싸는 래퍼. jQuery selector와 유사하지만 데이터 바인딩이 추가된다.

const svg = d3.select('#chart')
  .attr('width', 800)
  .attr('height', 400);

// 여러 요소 선택
const circles = svg.selectAll('circle')
  .data([10, 20, 30, 40, 50]);

Enter / Update / Exit 패턴

D3 v7에서는 .join() 메서드로 단순화됐다:

svg.selectAll('rect')
  .data(data)
  .join(
    enter  => enter.append('rect').attr('fill', 'steelblue'),
    update => update.attr('fill', 'green'),
    exit   => exit.remove()
  );

v5 이전 방식 (join 없음):

const sel = svg.selectAll('rect').data(data);
sel.enter().append('rect');   // enter
sel.attr('x', d => d.x);     // update
sel.exit().remove();          // exit

Scale (스케일)

데이터 도메인에서 픽셀 범위로 매핑하는 함수다.

const xScale = d3.scaleLinear()
  .domain([0, d3.max(data, d => d.value)])
  .range([0, width]);

const colorScale = d3.scaleOrdinal()
  .domain(['A', 'B', 'C'])
  .range(d3.schemeTableau10);

const timeScale = d3.scaleTime()
  .domain([new Date('2024-01-01'), new Date('2024-12-31')])
  .range([0, width]);

주요 scale 타입:

타입	용도
`scaleLinear`	선형 (숫자 → 숫자)
`scaleLog`	로그 스케일
`scaleTime`	날짜/시간
`scaleBand`	카테고리 → 픽셀 (바 차트)
`scaleOrdinal`	카테고리 → 색상
`scaleSqrt`	제곱근 (버블 차트 반지름)

Axis (축)

const xAxis = d3.axisBottom(xScale)
  .ticks(10)
  .tickFormat(d => `${d}건`);

svg.append('g')
  .attr('transform', `translate(0, ${height})`)
  .call(xAxis);

Transition (애니메이션)

svg.selectAll('rect')
  .data(newData)
  .join('rect')
  .transition()
  .duration(750)
  .ease(d3.easeCubicInOut)
  .attr('height', d => height - yScale(d.value));

Force Simulation

네트워크 그래프, 노드 배치에 사용. 이 블로그 그래프 뷰의 기반.

const simulation = d3.forceSimulation(nodes)
  .force('link', d3.forceLink(links).id(d => d.id).distance(60))
  .force('charge', d3.forceManyBody().strength(-200))
  .force('center', d3.forceCenter(width / 2, height / 2))
  .force('collision', d3.forceCollide().radius(d => d.radius + 5));

simulation.on('tick', () => {
  link
    .attr('x1', d => d.source.x).attr('y1', d => d.source.y)
    .attr('x2', d => d.target.x).attr('y2', d => d.target.y);
  node
    .attr('cx', d => d.x).attr('cy', d => d.y);
});

이 블로그에서 사용한 force:

forceLink: 노드 사이의 연결 거리
forceManyBody: 노드 간 반발력 (음수 strength)
forceCenter: 전체를 화면 중앙으로 끌어당김
forceCollide: 노드끼리 겹치지 않게

실전 예시: 바 차트

const margin = { top: 20, right: 30, bottom: 40, left: 60 };
const width = 600 - margin.left - margin.right;
const height = 400 - margin.top - margin.bottom;

const svg = d3.select('#chart')
  .append('svg')
  .attr('width', width + margin.left + margin.right)
  .attr('height', height + margin.top + margin.bottom)
  .append('g')
  .attr('transform', `translate(${margin.left},${margin.top})`);

const data = [
  { label: 'A', value: 30 },
  { label: 'B', value: 80 },
  { label: 'C', value: 45 },
];

const x = d3.scaleBand()
  .domain(data.map(d => d.label))
  .range([0, width])
  .padding(0.2);

const y = d3.scaleLinear()
  .domain([0, d3.max(data, d => d.value)])
  .range([height, 0]);

svg.selectAll('rect')
  .data(data)
  .join('rect')
  .attr('x', d => x(d.label))
  .attr('y', d => y(d.value))
  .attr('width', x.bandwidth())
  .attr('height', d => height - y(d.value))
  .attr('fill', 'steelblue');

svg.append('g')
  .attr('transform', `translate(0, ${height})`)
  .call(d3.axisBottom(x));

svg.append('g').call(d3.axisLeft(y));

실전 예시: 라인 차트 (시계열)

const line = d3.line()
  .x(d => xScale(d.date))
  .y(d => yScale(d.value))
  .curve(d3.curveMonotoneX);

const area = d3.area()
  .x(d => xScale(d.date))
  .y0(height)
  .y1(d => yScale(d.value))
  .curve(d3.curveMonotoneX);

// 채워진 영역
svg.append('path')
  .datum(data)
  .attr('fill', 'steelblue')
  .attr('fill-opacity', 0.3)
  .attr('d', area);

// 선
svg.append('path')
  .datum(data)
  .attr('fill', 'none')
  .attr('stroke', 'steelblue')
  .attr('stroke-width', 2)
  .attr('d', line);

v7 모듈 구조

D3 v7부터 완전 ESM으로, 하위 패키지만 선택적으로 가져올 수 있다.

// 전체 패키지

// 필요한 것만 (트리 쉐이킹)

주요 하위 패키지:

패키지	역할
`d3-selection`	DOM 선택 및 조작
`d3-scale`	데이터 스케일 매핑
`d3-axis`	축 렌더링
`d3-shape`	경로 생성기 (line, area, arc, pie)
`d3-force`	포스 시뮬레이션
`d3-zoom`	줌 / 팬
`d3-brush`	범위 선택
`d3-transition`	트랜지션
`d3-geo`	지리 투영법
`d3-hierarchy`	트리, 덴드로그램
`d3-color`	색상 공간 변환

대안

라이브러리	특징	적합 상황
Chart.js	완성된 차트 컴포넌트	표준 차트 빠른 구현
ECharts	풍부한 내장 차트 + 고성능	대시보드, 한국어 레이블
Observable Plot	D3 위의 고수준 API	탐색적 데이터 분석
Recharts	React 컴포넌트 기반	React 앱의 표준 차트
Nivo	React + D3, 다양한 차트	React 앱 커스텀 차트
Vega-Lite	JSON 선언형 문법	빠른 시각화 프로토타입

[!TIP] 완성된 차트 유형만 필요하다면 Chart.js 또는 ECharts가 개발 속도가 빠르다. D3는 기존 라이브러리가 지원하지 않는 완전 커스텀 시각화에 특히 강하다.

함정

[!WARNING] Enter/Update/Exit 혼동: v4 이전 예제는 .enter().append() 패턴을 쓴다. v7에서는 .join() 패턴이 훨씬 명확하고 권장된다.

[!CAUTION] SSR 환경: D3 selection은 document, window에 의존한다. Next.js, Astro SSR에서는 브라우저 전용으로 처리하거나 d3-node를 사용해야 한다.

[!WARNING] 성능: 수만 개 이상의 SVG 요소는 렌더링 성능이 급격히 떨어진다. Canvas 기반(d3-canvas) 또는 WebGL(regl, deck.gl) 전환을 고려한다.

[!WARNING] React 통합: D3와 React 모두 DOM을 직접 조작하므로 충돌 가능. useEffect + useRef로 컨테이너만 React에게 맡기고 내부는 D3가 관리하는 패턴을 사용. 또는 D3의 scale/shape만 계산에 쓰고 렌더링은 React JSX로 처리.

[!IMPORTANT] key 함수 미지정: .data(arr) 에서 key 함수를 생략하면 배열 인덱스로 매핑된다. 데이터가 추가/삭제되면 잘못된 요소가 업데이트될 수 있다. .data(arr, d => d.id) 처럼 key 함수를 항상 지정할 것.

Pagefind: 정적 사이트 전문 검색

koa (김신건) — Wed, 15 Jul 2026 00:00:00 GMT

정의

Pagefind 는 정적 사이트 (SSG) 용 클라이언트 사이드 전문 검색 엔진. 빌드 후 정적 인덱스 생성, 브라우저에서 WASM + fetch 로 검색. CloudCannon 이 Rust 로 개발하고 오픈소스로 공개.

서버 없이 완전한 전문 검색 (full-text search) 을 정적 호스팅 환경에서 구현할 수 있다.

아키텍처

flowchart TB
    subgraph "Build Time"
        HTML["정적 HTML 파일"] -->|"pagefind CLI"| Crawler["HTML 크롤러\n(Rust)"]
        Crawler -->|"파싱 + 인덱싱"| Index["pagefind/\n인덱스 shards\n(.pf_meta, .pf_index, .pf_fragment)"]
    end
    subgraph "Runtime (Browser)"
        User["사용자 검색 쿼리"] --> UI["Pagefind UI\n(JS)"]
        UI -->|"fetch shard"| Index
        Index -->|"shard 데이터"| WASM["pagefind.wasm\n(Rust to WASM)"]
        WASM -->|"검색 결과"| UI
        UI -->|"결과 렌더링"| User
    end

핵심 설계:

빌드 시: Rust CLI 가 HTML 을 파싱해 단어 단위 인덱스(shard) 생성
런타임: WASM 모듈이 브라우저에서 실행, 필요한 shard 만 lazy fetch
서버 불필요: CDN 또는 S3 같은 정적 호스팅으로 충분

특징

특징	설명
서버리스	JS + WASM + 정적 파일만으로 동작
인덱스 크기	40MB HTML → 약 300KB 인덱스 (gzip 전)
다국어	언어 자동 감지, stemming 지원
Stemming	Snowball 알고리즘 (영어/한국어 등)
필터	`data-pagefind-filter` 속성으로 카테고리 필터
하이라이팅	검색어 하이라이트 + 주변 문맥 excerpt
Lazy loading	검색어 첫 글자 입력 시 첫 shard 만 fetch
오프라인	Service Worker 와 조합 시 오프라인 검색 가능

인덱스 구조

dist/
  pagefind/
    pagefind.js          # JS API
    pagefind.wasm        # Rust WASM 모듈
    pagefind-ui.js       # 기본 UI 컴포넌트
    pagefind-ui.css
    pagefind-entry.json  # 메타 정보
    index/
      en/
        pagefind.pf_meta     # 언어별 메타
        pagefind.pf_index_0  # 단어 인덱스 shard 0
        pagefind.pf_index_1  # shard 1 ...
    fragment/
      en/
        *.pf_fragment    # 페이지별 본문 excerpt

검색어가 "rag" 이면 "r" 로 시작하는 shard 만 fetch → 불필요한 네트워크 요청 최소화.

Astro 통합

astro-pagefind 패키지 사용 (권장)

npm i -D astro-pagefind

// astro.config.mjs


export default defineConfig({
    integrations: [pagefind()],
    build: {
        format: 'directory',    // pagefind 는 /path/index.html 구조 필요
    },
});

---
// src/components/Search.astro

---

<!-- mdx-component: PagefindSearch -->

수동 통합 (빌드 후 CLI)

// package.json
{
    "scripts": {
        "build": "astro build && npx pagefind --site dist"
    }
}

빌드 결과물에 pagefind/ 디렉토리가 생성된다.

Hugo 통합

# config.yaml
params:
  pagefind: true

<!-- layouts/partials/pagefind.html -->
<link href="/pagefind/pagefind-ui.css" rel="stylesheet" />
<script src="/pagefind/pagefind-ui.js" type="text/javascript"></script>
<div id="search"></div>
<script>
    window.addEventListener('DOMContentLoaded', () => {
        new PagefindUI({ element: '#search', showSubResults: true });
    });
</script>

# Makefile / build script
hugo && npx pagefind --site public

Hugo 는 public/ 이 출력 폴더. 빌드 후 pagefind CLI 를 public/ 에 실행.

JavaScript API (직접 제어)

// 기본 검색
const pagefind = await import('/pagefind/pagefind.js');
await pagefind.init();

const search = await pagefind.search('django');
console.log(search.results.length);   // 매칭 수

// 결과 상세 데이터 로드
for (const result of search.results.slice(0, 5)) {
    const data = await result.data();
    console.log(data.url);        // /wiki/django/
    console.log(data.title);      // 페이지 제목
    console.log(data.excerpt);    // 하이라이트 포함 발췌
    console.log(data.word_count); // 단어 수
    console.log(data.filters);    // 필터 값 (category 등)
}

// 필터 적용
const filtered = await pagefind.search('orm', {
    filters: { category: 'django' }
});

// 디바운스 패턴
let timer;
inputEl.addEventListener('input', (e) => {
    clearTimeout(timer);
    timer = setTimeout(async () => {
        const results = await pagefind.search(e.target.value);
        renderResults(results);
    }, 300);
});

필터링

HTML 에 data-pagefind-filter 속성 추가:

<!-- 카테고리 필터 -->
<article data-pagefind-filter="category:blog">...</article>
<article data-pagefind-filter="category:wiki">...</article>

<!-- 태그 필터 (여러 값) -->
<span data-pagefind-filter="tag[data-value]" data-value="python"></span>
<span data-pagefind-filter="tag[data-value]" data-value="django"></span>

<!-- 날짜 필터 -->
<time data-pagefind-filter="year[datetime]" datetime="2026-07-15"></time>

// 여러 필터 조합
const results = await pagefind.search('queryset', {
    filters: {
        category: 'django',
        tag: ['orm', 'python']
    }
});

검색 대상 커스터마이징

<!-- 특정 영역만 인덱싱 -->
<main data-pagefind-body>
    <h1>제목</h1>
    <article>본문...</article>
</main>

<!-- 특정 영역 인덱싱 제외 -->
<nav data-pagefind-ignore>...</nav>
<aside data-pagefind-ignore="all">
    <!-- 이 안의 모든 요소 제외 -->
</aside>

<!-- 메타 정보 추가 -->
<meta data-pagefind-meta="title" content="[Django] ORM 기본" />
<meta data-pagefind-meta="image" content="/thumbnails/django-orm.png" />

커스텀 UI

기본 UI 를 쓰지 않고 직접 구현:

<input type="search" id="my-search" placeholder="검색..." />
<ul id="results"></ul>

<script type="module">
    const pagefind = await import('/pagefind/pagefind.js');

    document.getElementById('my-search').addEventListener('input', async (e) => {
        const query = e.target.value.trim();
        if (!query) return;

        const search = await pagefind.search(query);
        const items = await Promise.all(
            search.results.slice(0, 10).map(r => r.data())
        );

        document.getElementById('results').innerHTML = items
            .map(item => `
                <li>
                    <a href="${item.url}">${item.title}</a>
                    <p>${item.excerpt}</p>
                </li>
            `)
            .join('');
    });
</script>

Pagefind vs 대안

	Pagefind	Lunr.js	DocSearch (Algolia)	Fuse.js
서버 필요	X	X	X (Algolia 외부)	X
인덱스 위치	정적 파일	JS 번들	Algolia 서버	런타임 생성
인덱스 크기	작음 (shard)	큼 (전체 번들)	외부	없음 (메모리)
언어 지원	자동 감지	수동 설정	자동	없음
대용량 사이트	O (shard)	X (번들 한계)	O	X
무료	O	O	오픈소스 한정 O	O
검색 품질	높음 (WASM)	중간	높음	퍼지 검색
빌드 단계 필요	O	X	O (크롤링)	X
적합	SSG 전용 검색	소규모 앱	문서 사이트	클라이언트 필터

인덱스 크기 예시

사이트 규모	HTML 총 크기	Pagefind 인덱스	초기 fetch
소형 (50 페이지)	2MB	~15KB	첫 shard 만
중형 (500 페이지)	20MB	~150KB	첫 shard 만
대형 (5,000 페이지)	200MB	~1.5MB	첫 shard 만

실제 사용자는 쿼리 시 해당하는 shard 만 fetch 하므로 대형 사이트도 초기 로딩 부담이 작다.

함정

[!WARNING] build.format: 'directory' 필수 (Astro). build.format: 'file' 이면 /path.html 로 생성되어 pagefind 가 URL 을 /path.html 로 인덱싱. 'directory' 로 해야 /path/ 로 인덱싱됨.

[!IMPORTANT] 개발 서버에서는 동작 안 함. pagefind 는 빌드 후 pagefind/ 디렉토리가 있어야 한다. astro dev 에서는 인덱스가 없으므로 검색 불가. 로컬 테스트는 astro build && astro preview.

[!CAUTION] SPA 라우팅과 충돌. Pagefind 는 정적 HTML 인덱싱 기반이므로 클라이언트 사이드 렌더링(CSR) 콘텐츠는 인덱싱 안 됨. SSR/SSG 콘텐츠만 검색 가능.

[!WARNING] 한국어 stemming 미지원. 영어는 Snowball stemming(run/runs/running 동일 처리)이 있지만, 한국어는 형태소 분석 없이 단순 문자열 매칭. 짧은 검색어보다 완전한 단어로 검색할 때 적중률이 높다.

[Framework] Koa.js

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Koa.js 는 Express 창시자 TJ Holowaychuk 이 2013년 발표한 Node.js 웹 프레임워크 입니다. Express 의 후계자 성격이며, 미들웨어를 async/await 로 자연스럽게 표현 하고 양파 (onion) 모델 로 요청/응답을 감쌉니다. 초경량 코어 (약 500 LOC), 라우팅과 body parsing 은 별도 패키지.

2024-2025 년 현재 Koa 2.15+ 또는 Koa 3.x (async/await native, Node 20+) 이 사용됩니다.

왜 Koa 인가

작고 명료: 코어에 라우팅 없음. 필요한 것만 조합.
async/await 우선: Express 의 callback 지옥 없음.
Onion middleware: await next() 로 downstream + upstream 를 자연스럽게.
Context (ctx): request + response 를 감싼 하나의 객체.
Error 처리 단순: try/catch 로 미들웨어 예외 잡음.
경량: 저지연, 오버헤드 최소.

단점:

생태계가 Express 대비 좁음
큰 앱 구조는 스스로 설계 (NestJS 같은 opinionated 프레임워크 없음)
학습 자료 (블로그, 예시) 적음

설치 & 최소 예제

mkdir myapp && cd myapp
npm init -y
npm i koa

// server.js
const Koa = require('koa');
const app = new Koa();

app.use(async (ctx) => {
  ctx.body = 'Hello Koa';
});

app.listen(3000);

node server.js
# curl http://localhost:3000  ->  Hello Koa

Context (`ctx`)

Koa 의 핵심. request + response 통합.

app.use(async (ctx, next) => {
  console.log(ctx.method);           // 'GET'
  console.log(ctx.path);              // '/users/1'
  console.log(ctx.query);             // {page: '1'}
  console.log(ctx.headers);           // 헤더
  console.log(ctx.request.body);      // body (parser 필요)

  ctx.status = 201;
  ctx.body = {ok: true};              // 자동 JSON 직렬화
  ctx.set('X-Custom', 'value');       // 응답 헤더
});

자세한 것은 [[koa-context|Koa Context]] 참조.

Middleware (Onion 모델)

app.use(async (ctx, next) => {
  console.log('A pre');
  await next();
  console.log('A post');
});

app.use(async (ctx, next) => {
  console.log('B pre');
  await next();
  console.log('B post');
});

app.use(async (ctx) => {
  console.log('C');
  ctx.body = 'ok';
});

// 요청 시 출력:
// A pre
//   B pre
//     C
//   B post
// A post

각 미들웨어의 await next() 이전은 downstream 방향, 이후는 upstream 방향. 요청 처리 완료를 순차 관측 가능.

자세한 것은 [[koa-middleware|Koa Middleware]] 참조.

라우팅 (`@koa/router`)

npm i @koa/router

const Koa = require('koa');
const Router = require('@koa/router');

const app = new Koa();
const router = new Router();

router.get('/', async (ctx) => {
  ctx.body = 'Home';
});

router.get('/users/:id', async (ctx) => {
  ctx.body = { id: ctx.params.id };
});

router.post('/users', async (ctx) => {
  ctx.body = ctx.request.body;
});

app.use(router.routes()).use(router.allowedMethods());

app.listen(3000);

자세한 것은 [[koa-router|Koa Router]] 참조.

Body Parser (`@koa/bodyparser`)

npm i @koa/bodyparser

const bodyParser = require('@koa/bodyparser');
app.use(bodyParser());

router.post('/echo', async (ctx) => {
  ctx.body = ctx.request.body;
});

자세한 것은 [[koa-body|Koa Body Parsing]] 참조.

흔한 조합 (스택)

목적	패키지
라우팅	`@koa/router`
Body	`@koa/bodyparser`, `koa-body` (파일 업로드)
Multipart	`@koa/multer`
CORS	`@koa/cors`
Session	`koa-session`
Cookie	내장 (`ctx.cookies`)
Compression	`koa-compress`
Logger	`koa-logger`, `koa-pino-logger`
Static	`koa-static`
JWT	`koa-jwt`, `jose`
Rate limit	`koa-ratelimit`
Views (Jinja)	`@ladjs/koa-views`
Error	내장 + `app.on('error', ...)`

Async / Promise 지원

Koa 는 처음부터 async 지원. 미들웨어가 Promise 를 리턴하거나 async 함수.

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  ctx.set('X-Response-Time', `${ms}ms`);
});

Error 처리

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {
      error: err.message,
      ...(process.env.NODE_ENV !== 'production' && {stack: err.stack}),
    };
    ctx.app.emit('error', err, ctx);
  }
});

app.on('error', (err, ctx) => {
  console.error('server error', err);
});

Koa 는 기본적으로 ctx.status = 4xx/5xx + ctx.throw(4xx, 'message') 지원. 자세한 것은 [[koa-error-handling|Koa Error Handling]] 참조.

응답 반환

ctx.body = 'string';       // text/plain (또는 text/html 자동 감지)
ctx.body = { a: 1 };       // JSON
ctx.body = buffer;         // binary
ctx.body = stream;         // streaming
ctx.body = null;           // 204 no content

Status:

ctx.status = 201;
ctx.throw(404, 'Not found');       // 예외 발생
ctx.assert(user, 401, 'Login required');

Header:

ctx.set('Content-Type', 'application/json');
ctx.append('Set-Cookie', '...');
ctx.remove('X-Foo');

Redirect:

ctx.redirect('/login');
ctx.redirect('back', '/');    // Referer 기반

Config

Koa 자체는 config 없음. dotenv, config, zod 조합.

require('dotenv').config();

const app = new Koa();
app.proxy = process.env.NODE_ENV === 'production';   // X-Forwarded-* 신뢰

TypeScript 지원

@types/koa, @types/koa__router. 하지만 완전한 TS-first 는 아님. NestJS 처럼 완전한 타입 안전 원하면 그쪽.



interface AppState { user?: User; }
interface AppContext { db: DatabaseService; }

const app = new Koa<AppState, AppContext>();
const router = new Router<AppState, AppContext>();

router.get('/me', async (ctx) => {
  const user = ctx.state.user;   // typed
  const users = await ctx.db.query(...);  // typed
  ctx.body = user;
});

ctx.state 는 request 스코프 저장, ctx 확장은 앱 스코프.

프로젝트 구조 (실전)

myapp/
├── src/
│   ├── app.js                # createApp
│   ├── server.js              # 진입점 (listen)
│   ├── config/
│   │   └── index.js
│   ├── middleware/
│   │   ├── error.js
│   │   ├── logger.js
│   │   ├── auth.js
│   │   └── request-id.js
│   ├── routes/
│   │   ├── index.js           # router combine
│   │   ├── users.js
│   │   └── posts.js
│   ├── services/
│   │   └── db.js
│   ├── models/
│   └── utils/
├── test/
├── package.json
└── .env

app.js:

const Koa = require('koa');
const bodyParser = require('@koa/bodyparser');
const cors = require('@koa/cors');
const helmet = require('koa-helmet');

const errorMiddleware = require('./middleware/error');
const loggerMiddleware = require('./middleware/logger');
const routes = require('./routes');

function createApp() {
  const app = new Koa();
  app.proxy = true;

  app.use(errorMiddleware);
  app.use(loggerMiddleware);
  app.use(helmet());
  app.use(cors({origin: 'https://app.example.com', credentials: true}));
  app.use(bodyParser({jsonLimit: '1mb'}));
  app.use(routes.routes()).use(routes.allowedMethods());

  return app;
}

module.exports = createApp;

server.js:

const createApp = require('./app');
const app = createApp();

const server = app.listen(process.env.PORT || 3000, () => {
  console.log(`Listening on ${process.env.PORT || 3000}`);
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  server.close(() => process.exit(0));
});

Fastify 와의 관계

Fastify 는 Koa 이후 등장한 성능 지향 프레임워크. Fastify 가 더 빠르고 (JSON stringify 캐싱, plugin 시스템), 스키마 지원 우수. Koa 는 가벼움 + async/await 초점, Fastify 는 성능 + 표준화.

Express 와의 관계

Koa 는 Express 의 후계자로 시작. TJ 가 Express 를 인수인계 후 Koa 를 만듦. 오늘날 두 프레임워크 병존. 자세한 것은 [[koa-vs-express|Koa vs Express]] 참조.

실전 예: JSON API

const Koa = require('koa');
const Router = require('@koa/router');
const bodyParser = require('@koa/bodyparser');

const app = new Koa();
const router = new Router();

// Global error
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {error: err.message};
  }
});

app.use(bodyParser());

// Routes
router.get('/users', async (ctx) => {
  ctx.body = await getUsersFromDb();
});

router.get('/users/:id', async (ctx) => {
  const user = await getUserById(ctx.params.id);
  ctx.assert(user, 404, 'User not found');
  ctx.body = user;
});

router.post('/users', async (ctx) => {
  const {email, name} = ctx.request.body;
  ctx.assert(email, 400, 'email required');
  const user = await createUser({email, name});
  ctx.status = 201;
  ctx.body = user;
});

app.use(router.routes()).use(router.allowedMethods());

app.listen(3000);

함정

[!WARNING] ctx.body 를 여러 번 할당 하면 마지막 값이 응답. 실수로 downstream 에서 override.

[!CAUTION] await next() 잊으면 hang. Middleware chain 이 다음 단계로 못 감.

[!WARNING] Prod 에서 app.proxy = true 안 하면 X-Forwarded-For 무시. ctx.ip 가 프록시 IP 반환.

[!IMPORTANT] Koa 는 라우팅 X, body parser X, cookie parser X 를 별도 설치. Express 에서 온 사람들이 자주 실수.

[!CAUTION] Middleware 순서. Error handler 를 첫 middleware 로. Body parser 를 라우터 앞에.

[Framework] NestJS

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS 는 Kamil Myśliwiec 이 2017년 발표한 Node.js 서버측 프레임워크 입니다. TypeScript first, Angular 에서 영감받은 모듈 + DI + 데코레이터 아키텍처. Express (기본) 또는 Fastify 를 HTTP 어댑터로 사용하며, REST/GraphQL/WebSocket/gRPC/Microservice 를 하나의 프로그래밍 모델로 커버합니다.

2025년 현재 NestJS 11 이 stable (Node 20 minimum, better logging, microservices status, etc).

왜 NestJS 인가

1. TypeScript 그대로

TypeScript 를 처음부터 상정. 데코레이터, 타입 추론, IDE 지원 최상급.

2. 예측 가능한 구조

Angular 스타일. 새 팀원이 어디에 무엇이 있는지 즉시 파악.

Module: 기능 그룹
Controller: HTTP 라우트
Service (Provider): 비즈니스 로직
DTO / Schema: 데이터 전송 객체
Guard / Interceptor / Pipe / Filter: 요청 lifecycle 훅

3. Dependency Injection

Class-based DI. Constructor injection. 테스트 편의성 극대화.

4. 방대한 통합

TypeORM, Prisma, Mongoose, GraphQL (Apollo), Swagger, Passport, Bull, Kafka, gRPC, Redis, Elasticsearch, WebSocket, SSE.

5. Microservice

같은 코드로 REST + Microservice (Kafka, NATS, RabbitMQ, TCP, gRPC).

빠른 시작

npm i -g @nestjs/cli
nest new myapp
cd myapp
npm run start:dev

기본 구조:

myapp/
├── src/
│   ├── main.ts          # 진입점 (bootstrap)
│   ├── app.module.ts    # root module
│   ├── app.controller.ts
│   └── app.service.ts
├── test/
│   └── app.e2e-spec.ts
├── tsconfig.json
├── nest-cli.json
└── package.json

main.ts



async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableCors();
  await app.listen(3000);
}
bootstrap();

app.module.ts




@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

app.controller.ts



@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

app.service.ts


@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

아키텍처 요약

flowchart LR
  R[HTTP Request] --> MW[Middleware]
  MW --> G[Guard]
  G --> IC1[Interceptor pre]
  IC1 --> P[Pipe]
  P --> C[Controller]
  C --> S[Service<br/>Provider]
  S --> DB[(DB / External)]
  S --> C
  C --> IC2[Interceptor post]
  IC2 --> F[Exception Filter]
  F --> Resp[HTTP Response]

핵심 개념

개념	역할	자세히
**[[nestjs-modules	Module]]**	기능 그룹, DI scope
**[[nestjs-controllers	Controller]]**	HTTP 라우팅
**[[nestjs-providers	Provider]]**	Injectable class (Service, Repository, Factory)
**[[nestjs-guards	Guard]]**	인증/인가
**[[nestjs-interceptors	Interceptor]]**	Cross-cutting (logging, cache, transform)
**[[nestjs-pipes	Pipe]]**	검증, 변환
**[[nestjs-middleware	Middleware]]**	Express-style middleware
**[[nestjs-exception-filters	Exception Filter]]**	예외 처리

Request Lifecycle 순서

Middleware: Express/Fastify 미들웨어. req 만 접근.
Guard: canActivate(context). false 면 즉시 401/403.
Interceptor (before): intercept(context, next) 상반부.
Pipe: 파라미터 검증/변환 (DTO 로 형변환).
Controller method: 실제 라우트 핸들러.
Interceptor (after): map(...) 로 응답 변환.
Exception filter: 어떤 계층이든 예외 발생 시.

HTTP Adapter

Express (@nestjs/platform-express, 기본): Express 4/5 호환
Fastify (@nestjs/platform-fastify): 더 빠름, TypeBox / AJV 스키마

const app = await NestFactory.create<NestFastifyApplication>(
  AppModule,
  new FastifyAdapter(),
);

Interface 만 다르고 대부분의 NestJS 코드는 그대로.

DTO + Validation


export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsInt()
  @Min(18)
  age: number;
}

@Post()
create(@Body() dto: CreateUserDto) {
  // dto 는 이미 validated + typed
}

ValidationPipe 를 global 로 등록하면 모든 DTO 자동 검증. 자세한 것은 [[nestjs-pipes|Pipes]] 참조.

Swagger / OpenAPI

npm i @nestjs/swagger swagger-ui-express

// main.ts

const config = new DocumentBuilder()
  .setTitle('My API')
  .setDescription('...')
  .setVersion('1.0')
  .addBearerAuth()
  .build();

const doc = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, doc);

@ApiProperty() 데코레이터로 DTO 문서화. http://localhost:3000/api 에 Swagger UI.

CLI

nest g mo users         # module
nest g co users         # controller
nest g s users          # service
nest g res users        # resource (module + controller + service + DTO + entity)

nest g guard auth
nest g interceptor logging
nest g pipe validate
nest g filter http-exception

nest build
nest start --watch

NestJS 11 주요 변경

Node 20 minimum: Node 18 EOL
JSON Logger: nest.useLogger(new ConsoleLogger({ json: true }))
개선된 Logger: 더 나은 formatting, maps/sets 지원
Microservices: status(), unwrap(), on() 메서드 (transporter 상태)
NATS: queue-per-handler 지원
WebDAV HTTP method 지원
@Inject() type narrowing: TypeScript 개선
ParseDatePipe: 새 pipe
plainToClass deprecated -> plainToInstance

프로젝트 구조 (실전)

src/
├── main.ts
├── app.module.ts
├── config/
│   ├── database.config.ts
│   ├── app.config.ts
│   └── validation.schema.ts
├── common/
│   ├── decorators/
│   ├── filters/
│   ├── guards/
│   ├── interceptors/
│   ├── pipes/
│   └── middleware/
├── modules/
│   ├── users/
│   │   ├── users.module.ts
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   ├── users.repository.ts    # 또는 Prisma/TypeORM
│   │   ├── dto/
│   │   │   ├── create-user.dto.ts
│   │   │   └── update-user.dto.ts
│   │   ├── entities/
│   │   │   └── user.entity.ts
│   │   └── users.controller.spec.ts
│   ├── auth/
│   │   ├── auth.module.ts
│   │   ├── strategies/
│   │   └── guards/
│   └── health/
└── shared/

실전 조합 (스택)

카테고리	관용 선택
HTTP	Fastify (성능) 또는 Express
DB	Prisma (모던) 또는 TypeORM (성숙) 또는 Drizzle
인증	Passport + JWT, 또는 자체 JWT strategy
Validation	class-validator + class-transformer, 또는 Zod
Config	`@nestjs/config` + Joi schema
Logging	Pino (`nestjs-pino`) 또는 built-in JSON logger
Testing	Jest (내장) + Supertest
Task Queue	Bull / BullMQ (`@nestjs/bull`)
Cache	Redis (`@nestjs/cache-manager`)
Docs	`@nestjs/swagger`
Monitoring	OpenTelemetry (`@opentelemetry/instrumentation-nestjs-core`)

함정

[!WARNING] DI 순환 참조. Module A imports B, B imports A. forwardRef(() => ModuleB) 로 해결하지만 근본 refactoring 이 나음.

[!CAUTION] Global module 남용. @Global() 는 어디서든 provider 접근 가능. 편해 보이지만 의존성 추적 어려움.

[!WARNING] class-validator 는 런타임 필요. Nest 는 TypeScript 를 컴파일하고 나서도 metadata 필요. reflect-metadata import 필수 (main.ts 상단).

[!IMPORTANT] Fastify 는 Express 미들웨어와 호환 X. 이관 시 미들웨어/plugin 재작성.

[!CAUTION] useFactory DI 는 async 가능. 하지만 초기화 순서 이해 필요. Circular deps 조심.

[Koa] Body Parsing

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Koa Body Parsing 은 HTTP 요청 body 를 파싱해 ctx.request.body 에 사용 가능한 형태로 만드는 미들웨어입니다. Koa 코어는 body parser 를 포함하지 않으므로 별도 설치가 필요합니다.

옵션

패키지	특성	언제
`@koa/bodyparser`	공식, JSON/form/text	대부분
`koa-body`	JSON/form/text + multipart 통합	파일 업로드 함께
`koa-bodyparser`	오래된 사실상 표준	기존 코드
`@koa/multer`	multipart only (multer 위)	파일 업로드 특화
`raw-body`	저수준 원본 buffer	커스텀 파싱

@koa/bodyparser (권장)

npm i @koa/bodyparser

const bodyParser = require('@koa/bodyparser');

app.use(bodyParser());

옵션

app.use(bodyParser({
  patchNode: false,
  patchKoa: true,
  jsonLimit: '1mb',        // JSON 크기 제한
  formLimit: '56kb',
  textLimit: '1mb',
  encoding: 'utf-8',
  extendTypes: {
    json: ['application/x-javascript'],
    text: ['text/xml'],
    form: [],
  },
  parsedMethods: ['POST', 'PUT', 'PATCH', 'DELETE'],
  detectJSON: (ctx) => /\.json$/.test(ctx.path),
  strict: true,             // JSON: 배열/객체만 허용
  enableTypes: ['json', 'form', 'text'],
  onerror: (err, ctx) => {
    ctx.throw('body parse error', 422);
  },
}));

사용

router.post('/users', async (ctx) => {
  const {email, name} = ctx.request.body;   // JSON, form 모두 여기
  // ...
});

지원 Content-Type

application/json

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"email": "a@b.com", "name": "kim"}'

ctx.request.body;   // {email: 'a@b.com', name: 'kim'}

application/x-www-form-urlencoded

curl -X POST http://localhost:3000/users \
  -d "email=a@b.com&name=kim"

ctx.request.body;   // {email: 'a@b.com', name: 'kim'}

text/plain

curl -X POST http://localhost:3000/log \
  -H "Content-Type: text/plain" \
  --data-binary "raw text"

ctx.request.body;   // 'raw text'

multipart/form-data (파일 업로드)

@koa/bodyparser 는 multipart 를 지원하지 않음. koa-body 또는 @koa/multer.

koa-body (multipart 포함)

npm i koa-body

const { koaBody } = require('koa-body');

app.use(koaBody({
  multipart: true,
  formidable: {
    uploadDir: '/tmp/uploads',
    maxFileSize: 200 * 1024 * 1024,   // 200 MB
    keepExtensions: true,
  },
  jsonLimit: '10mb',
  urlencoded: true,
  text: true,
}));

파일 업로드

router.post('/upload', async (ctx) => {
  const file = ctx.request.files.upload;
  console.log(file.name);       // 'photo.jpg'
  console.log(file.path);       // '/tmp/uploads/upload_xxx.jpg'
  console.log(file.size);
  console.log(file.type);       // 'image/jpeg'

  // 파일 이동
  const fs = require('fs');
  fs.renameSync(file.path, `/uploads/${Date.now()}-${file.name}`);

  ctx.body = {ok: true};
});

여러 파일

<form enctype="multipart/form-data" method="post">
  <input type="file" name="images" multiple>
</form>

router.post('/upload', async (ctx) => {
  const files = ctx.request.files.images;
  const list = Array.isArray(files) ? files : [files];

  for (const file of list) {
    // ...
  }
});

@koa/multer

Express 의 multer 를 Koa 로. 세밀한 파일 처리:

npm i @koa/multer

const multer = require('@koa/multer');
const path = require('path');

const storage = multer.diskStorage({
  destination: (req, file, cb) => cb(null, '/uploads/'),
  filename: (req, file, cb) => {
    const uniq = Date.now() + '-' + Math.round(Math.random() * 1e9);
    cb(null, uniq + path.extname(file.originalname));
  },
});

const upload = multer({
  storage,
  limits: {fileSize: 10 * 1024 * 1024},
  fileFilter: (req, file, cb) => {
    if (!/\.(jpe?g|png|gif)$/.test(file.originalname)) {
      return cb(new Error('Invalid file type'));
    }
    cb(null, true);
  },
});

// 단일
router.post('/avatar', upload.single('avatar'), async (ctx) => {
  ctx.body = {filename: ctx.file.filename};
});

// 여러
router.post('/gallery', upload.array('photos', 5), async (ctx) => {
  ctx.body = {count: ctx.files.length};
});

Raw body 접근

파싱 전 raw buffer 가 필요한 경우 (webhook 서명 검증 등):

npm i raw-body

const getRawBody = require('raw-body');

app.use(async (ctx, next) => {
  if (ctx.path === '/webhook') {
    ctx.request.rawBody = await getRawBody(ctx.req, {
      length: ctx.length,
      limit: '1mb',
      encoding: ctx.charset,
    });
    // parsed body 는 별도로
    ctx.request.body = JSON.parse(ctx.request.rawBody);
  } else {
    // ...
  }
  await next();
});

Stripe / GitHub webhook 검증:

const signature = ctx.get('X-Stripe-Signature');
if (!verifySignature(ctx.request.rawBody, signature, secret)) {
  ctx.throw(400);
}

Streaming (큰 파일)

파싱 없이 stream 그대로:

const fs = require('fs');
const { pipeline } = require('stream/promises');

router.post('/upload-stream', async (ctx) => {
  const stream = ctx.req;
  const output = fs.createWriteStream(`/uploads/${Date.now()}.bin`);
  await pipeline(stream, output);
  ctx.body = {ok: true};
});

Body parser 를 이 endpoint 에서는 스킵해야 함 (아니면 이미 body 읽혀서 stream empty):

app.use(async (ctx, next) => {
  if (ctx.path === '/upload-stream') return next();
  return bodyParser()(ctx, next);
});

검증 (Zod)

Koa 는 native validation 없음. Zod 등 활용:

const {z} = require('zod');

const CreateUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  age: z.number().int().min(0).max(150),
});

router.post('/users', async (ctx) => {
  const parseResult = CreateUserSchema.safeParse(ctx.request.body);
  if (!parseResult.success) {
    ctx.throw(400, {errors: parseResult.error.errors});
  }
  const data = parseResult.data;   // typed
  // ...
});

미들웨어로 재사용

function validate(schema) {
  return async (ctx, next) => {
    const result = schema.safeParse(ctx.request.body);
    if (!result.success) ctx.throw(400, JSON.stringify(result.error));
    ctx.state.validated = result.data;
    await next();
  };
}

router.post('/users', validate(CreateUserSchema), async (ctx) => {
  const data = ctx.state.validated;
  // ...
});

Compression 처리

Content-Encoding: gzip/deflate 자동 처리는 built-in. @koa/bodyparser 는 native support.

함정

[!WARNING] ctx.request.body 는 parser 뒤에서만. Parser 앞 미들웨어에서는 undefined.

[!CAUTION] 파일 크기 제한 안 걸면 메모리 폭주. 반드시 limit.

[!WARNING] ctx.req 를 stream 으로 소비한 후 body parser 사용 불가. Stream 은 한 번만 읽힘.

[!IMPORTANT] Raw body 는 서명 검증에 필수. Webhook 은 반드시 raw 로 검증.

[!CAUTION] koa-body vs @koa/bodyparser 중 하나만. 둘 다 등록하면 충돌.

[Koa] Context (ctx)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Koa Context (ctx) 는 각 요청마다 생성되어 미들웨어와 route handler 에 전달되는 객체입니다. req (Node 원본), request (Koa 확장), response (Koa 확장), state (요청 스코프 저장), 헬퍼 메서드를 한 곳에 통합합니다.

ctx 의 계층

ctx
├── req                   ← Node 원본 IncomingMessage
├── res                   ← Node 원본 ServerResponse
├── request               ← Koa 확장 Request
│   ├── header, headers
│   ├── method
│   ├── url, originalUrl
│   ├── path
│   ├── query
│   ├── body (bodyparser 뒤)
│   ├── ip, ips
│   └── ...
├── response              ← Koa 확장 Response
│   ├── header, headers (set/get)
│   ├── status
│   ├── message
│   ├── body
│   ├── length
│   ├── type
│   └── ...
├── app                   ← Application
├── state                 ← 요청 스코프 저장소
├── cookies               ← 쿠키 조작
└── (delegated: ctx.body === ctx.response.body 등)

Delegation

편의를 위해 ctx 자체에도 자주 쓰는 속성이 위임되어 있습니다.

ctx.method      === ctx.request.method
ctx.path        === ctx.request.path
ctx.query       === ctx.request.query
ctx.header      === ctx.request.header
ctx.body        === ctx.response.body      // getter/setter
ctx.status      === ctx.response.status
ctx.set(...)    === ctx.response.set(...)

즉 ctx.body = 'ok' 는 ctx.response.body = 'ok'.

Request 정보

app.use(async (ctx) => {
  ctx.method;         // 'GET', 'POST', ...
  ctx.url;             // '/users?page=1' (전체)
  ctx.originalUrl;     // proxy 이전 URL
  ctx.path;            // '/users' (query 제외)
  ctx.querystring;     // 'page=1'
  ctx.query;           // {page: '1'} (parsed)
  ctx.host;            // 'example.com:3000'
  ctx.hostname;        // 'example.com'
  ctx.protocol;        // 'https'
  ctx.secure;          // boolean
  ctx.ip;              // client IP
  ctx.ips;             // proxy chain (proxy=true 필요)

  ctx.header;          // request headers
  ctx.get('user-agent');
  ctx.get('content-type');

  ctx.type;            // request Content-Type (짧게)
  ctx.length;          // Content-Length
});

Body (bodyparser 뒤)

const bodyParser = require('@koa/bodyparser');
app.use(bodyParser());

app.use(async (ctx) => {
  ctx.request.body;      // parsed body
  // JSON:      {name: 'kim'}
  // Form:      {name: 'kim'}
  // Text:      'raw text'
});

주의: Koa 는 기본 body 를 파싱 안 함. @koa/bodyparser, koa-body, koa-bodyparser 하나를 설치.

자세한 것은 [[koa-body|Koa Body Parsing]] 참조.

Files

koa-body 또는 @koa/multer 로 파일 업로드:

const koaBody = require('koa-body').default;
app.use(koaBody({multipart: true}));

app.use(async (ctx) => {
  ctx.request.files;     // {upload: File}
});

Response 조작

body

ctx.body = 'string';                    // text/html (또는 text/plain 감지)
ctx.body = { key: 'value' };            // JSON
ctx.body = Buffer.from('...');           // binary
ctx.body = fs.createReadStream(path);   // stream
ctx.body = null;                         // 204 no content

status

ctx.status = 200;
ctx.status = 201;
ctx.status = 404;

ctx.body 를 설정하면 status 가 자동으로 200 (또는 204 for null). 명시 없으면 대개 404.

message

ctx.message = 'Custom OK';    // 200 Custom OK

type (Content-Type)

ctx.type = 'json';           // -> application/json
ctx.type = 'html';           // -> text/html
ctx.type = 'text';           // -> text/plain
ctx.type = 'application/xml';

length

ctx.length = 1024;    // Content-Length

Auto-computed for string/Buffer, manual for streams.

ctx.set('X-Custom', 'value');
ctx.set({'X-A': 'a', 'X-B': 'b'});
ctx.append('Set-Cookie', 'session=abc');
ctx.remove('X-Foo');
ctx.vary('Accept-Encoding');

redirect

ctx.redirect('/login');
ctx.redirect('/login', 301);   // status 명시
ctx.redirect('back', '/');      // Referer 기반, alt fallback

기본 302.

attachment (파일 다운로드)

ctx.attachment('report.pdf');
ctx.type = 'application/pdf';
ctx.body = fs.createReadStream('/path/to/report.pdf');
// Content-Disposition: attachment; filename="report.pdf"

`ctx.state` (Request-scoped 저장소)

미들웨어 간 데이터 전달. Session, 인증된 사용자 등.

app.use(async (ctx, next) => {
  ctx.state.user = await getUserFromToken(ctx.get('authorization'));
  await next();
});

router.get('/me', async (ctx) => {
  ctx.body = ctx.state.user;
});

TypeScript:

interface AppState { user?: User; requestId: string; }
const app = new Koa<AppState>();

`ctx.throw()` / `ctx.assert()`

ctx.throw(400, 'Missing email');
ctx.throw(401, 'Unauthorized');
ctx.throw(500, 'Internal', {internal: true});   // 3rd = properties

// assert 는 truthy 검사
ctx.assert(user, 401, 'Login required');
ctx.assert(id, 400, 'ID required');

ctx.throw 는 createError() (http-errors) 사용. try/catch 없이 던지면 default error handler 로.

Cookies

ctx.cookies.get('session');
ctx.cookies.set('session', 'abc', {
  httpOnly: true,
  secure: true,
  sameSite: 'lax',
  maxAge: 3600_000,
  path: '/',
  domain: 'example.com',
});
ctx.cookies.set('session', null);   // 삭제

Signed cookies (app.keys 필요):

app.keys = ['secret1', 'secret2'];   // 첫 번째로 서명, 나머지는 검증

ctx.cookies.set('session', 'abc', {signed: true});
ctx.cookies.get('session', {signed: true});   // 검증 실패 시 undefined

Content Negotiation

`ctx.accepts()`

ctx.accepts('json');                     // 'json' | false
ctx.accepts('html', 'json');             // 순위대로
ctx.accepts('image/png', 'image/tiff');

Accept 헤더 기반.

`ctx.acceptsLanguages()`

ctx.acceptsLanguages('en', 'ko');

`ctx.acceptsEncodings()`, `ctx.acceptsCharsets()`

같은 패턴.

`ctx.request` vs `ctx.req`

ctx.req: Node 원본 IncomingMessage. 스트림 접근 등.
ctx.request: Koa 확장. body, query 등 파싱된 것.

미들웨어에서 stream 을 원본으로 처리 (large file upload without body parser):

app.use(async (ctx) => {
  ctx.req.pipe(fs.createWriteStream('/tmp/upload'));
});

`ctx.response` vs `ctx.res`

ctx.res: Node 원본 ServerResponse
ctx.response: Koa 확장

주의: ctx.res.end() 직접 호출하면 Koa 의 응답 처리 우회. 대신 ctx.body 사용.

Async in `ctx`

ctx 는 요청마다 새로 생성. AsyncLocalStorage 를 대체하는 자연스러운 request scope.

app.use(async (ctx, next) => {
  ctx.state.trace = tracer.startSpan('request');
  try {
    await next();
  } finally {
    ctx.state.trace.finish();
  }
});

Prototype extension

ctx.app.context 로 모든 요청에 자동 노출되는 헬퍼 추가:

app.context.db = new Database();

// 어느 미들웨어든
async (ctx) => {
  const user = await ctx.db.query('...');
};

TypeScript 는 AppContext 인터페이스 확장:

declare module 'koa' {
  interface DefaultContext {
    db: Database;
  }
}

함정

[!WARNING] ctx.res.end() 호출 금지 (Koa 응답 우회). ctx.body 로.

[!CAUTION] ctx.request.body 는 body parser 뒤에서만. Parser 전에는 undefined.

[!WARNING] app.proxy = true 안 하면 ctx.ip, ctx.protocol 이 프록시 뒤에서 오답. Nginx / ALB 뒤 배포 시 필수.

[!IMPORTANT] ctx.state 는 request scope. ctx.app.context 확장은 app scope (모든 요청 공유).

[!CAUTION] ctx.throw(500) + downstream 에서 catch 없음 = default error handler 가 500 반환. 사용자에 stack trace 노출 위험.

[Koa] Deployment (PM2, Docker, Kubernetes)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Koa Deployment 는 Node.js 프로덕션 배포의 표준 도구 (Docker, Kubernetes, PM2) + Koa 특화 고려사항 (graceful shutdown, app.proxy, error handling) 을 조합합니다.

Production 준비

`app.proxy = true`

리버스 프록시 (nginx, ALB) 뒤 배포 시:

app.proxy = true;

ctx.ip 가 X-Forwarded-For 첫 값
ctx.protocol 이 X-Forwarded-Proto 반영
ctx.host 가 X-Forwarded-Host 반영

주의: proxy 를 신뢰할 수 있는 환경만. 인터넷 노출 서비스에 app.proxy = true 를 그냥 켜면 IP spoofing 가능. Nginx 앞에 CF 등이 있으면 chain 개수 관리.

Environment

if (process.env.NODE_ENV !== 'production') {
  // dev-only middleware (logger, hot reload)
}

app.env = process.env.NODE_ENV;

Signed cookies

app.keys = [process.env.COOKIE_KEY_1, process.env.COOKIE_KEY_2];

Graceful Shutdown

const server = app.listen(3000);

let shuttingDown = false;

async function shutdown(signal) {
  if (shuttingDown) return;
  shuttingDown = true;
  console.log(`Received ${signal}, shutting down`);

  server.close(async (err) => {
    if (err) {
      console.error(err);
      process.exit(1);
    }
    // DB, Redis, message queue 등 close
    await db.disconnect();
    await redis.quit();
    console.log('Graceful shutdown complete');
    process.exit(0);
  });

  // Force exit after 30s
  setTimeout(() => {
    console.error('Timeout, force exit');
    process.exit(1);
  }, 30_000).unref();
}

process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

주의: server.close() 는 새 요청 accept 중지 + 진행 중 요청 완료 대기. close() 콜백은 keepalive connection 이 닫혀야 호출.

stoppable, terminus 라이브러리 대안:

npm i @godaddy/terminus

const {createTerminus} = require('@godaddy/terminus');

createTerminus(server, {
  signal: 'SIGTERM',
  timeout: 30000,
  onSignal: async () => {
    await db.disconnect();
  },
  healthChecks: {
    '/health/ready': async () => {
      await db.ping();
    },
  },
});

Health Check

router.get('/health/live', async (ctx) => {
  ctx.body = {status: 'ok'};
});

router.get('/health/ready', async (ctx) => {
  try {
    await db.query('SELECT 1');
    ctx.body = {status: 'ready'};
  } catch (err) {
    ctx.status = 503;
    ctx.body = {status: 'not ready', error: err.message};
  }
});

liveness: 앱 프로세스 살아있는가
readiness: 요청 처리 준비 완료 (DB 연결 등)

Logging

개발

if (process.env.NODE_ENV !== 'production') {
  app.use(require('koa-logger')());
}

프로덕션 (JSON)

npm i pino koa-pino-logger

const pino = require('pino');
const pinoLogger = require('koa-pino-logger');

const logger = pino({level: 'info', redact: ['req.headers.authorization']});

app.use(pinoLogger({logger}));

// 사용
app.use(async (ctx, next) => {
  ctx.log.info({userId: ctx.state.user?.id}, 'processing');
  await next();
});

로그 필드 관용

time, level, msg
req: method, url, headers (redacted), remoteAddr
res: statusCode, headers
responseTime, requestId
err: message, stack (dev 만)

Sentry / OpenTelemetry

Sentry

npm i @sentry/node

const Sentry = require('@sentry/node');

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1,
});

// Error middleware
app.use(async (ctx, next) => {
  try { await next(); } catch (err) {
    Sentry.withScope((scope) => {
      scope.setTag('path', ctx.path);
      scope.setUser({id: ctx.state.user?.id});
      Sentry.captureException(err);
    });
    throw err;
  }
});

OpenTelemetry

npm i @opentelemetry/api @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http

// tracing.js
const {NodeSDK} = require('@opentelemetry/sdk-node');
const {getNodeAutoInstrumentations} = require('@opentelemetry/auto-instrumentations-node');
const {OTLPTraceExporter} = require('@opentelemetry/exporter-trace-otlp-http');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT}),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

server.js 최상단에 require('./tracing') (모든 import 이전).

Dockerfile (multi-stage)

# --- builder ---
FROM node:20-alpine AS builder
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

# 프로덕션 의존성만 재설치
RUN npm ci --omit=dev && npm cache clean --force

# --- runtime ---
FROM node:20-alpine
WORKDIR /app

RUN addgroup -g 1001 -S app && adduser -S app -u 1001

COPY --from=builder --chown=app:app /app/node_modules ./node_modules
COPY --chown=app:app package*.json ./
COPY --chown=app:app src ./src

USER app

EXPOSE 3000

CMD ["node", "src/server.js"]

HEALTHCHECK --interval=30s --timeout=3s --start-period=30s \
  CMD wget --spider -q http://localhost:3000/health/live || exit 1

`.dockerignore`

node_modules
.git
.env
.env.*
*.md
test
coverage
Dockerfile
.gitignore
.vscode
.idea

PM2

VM 배포용. K8s 는 kubelet 이 대체.

npm i -g pm2

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'myapp',
    script: 'src/server.js',
    instances: 'max',           // = CPU 개수
    exec_mode: 'cluster',
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000,
    },
    max_memory_restart: '1G',
    kill_timeout: 30000,          // graceful timeout
    listen_timeout: 10000,
    wait_ready: true,             // process.send('ready') 대기
    error_file: '/var/log/myapp/error.log',
    out_file: '/var/log/myapp/out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss',
  }],
};

// server.js
const server = app.listen(port, () => {
  if (process.send) process.send('ready');   // PM2 알림
});

pm2 start ecosystem.config.js --env production
pm2 status
pm2 logs myapp
pm2 reload myapp             # zero-downtime
pm2 startup                   # systemd 등록
pm2 save

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels: {app: myapp}
  template:
    metadata:
      labels: {app: myapp}
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: app
          image: myrepo/myapp:v1.0
          ports: [{containerPort: 3000}]
          env:
            - name: NODE_ENV
              value: production
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef: {name: myapp, key: db-url}
          resources:
            requests: {cpu: 100m, memory: 128Mi}
            limits: {cpu: 500m, memory: 512Mi}
          livenessProbe:
            httpGet: {path: /health/live, port: 3000}
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet: {path: /health/ready, port: 3000}
            periodSeconds: 5
          startupProbe:
            httpGet: {path: /health/live, port: 3000}
            failureThreshold: 30
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                command: ["sleep", "5"]

Reverse Proxy (nginx)

upstream koa_app {
  server 127.0.0.1:3000;
  keepalive 32;
}

server {
  listen 443 ssl http2;
  server_name api.example.com;

  ssl_certificate /etc/ssl/cert.pem;
  ssl_certificate_key /etc/ssl/key.pem;

  client_max_body_size 10M;

  location / {
    proxy_pass http://koa_app;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 60s;
  }
}

Cluster mode (Node built-in)

const cluster = require('cluster');
const os = require('os');

if (cluster.isPrimary) {
  const workers = os.cpus().length;
  for (let i = 0; i < workers; i++) cluster.fork();

  cluster.on('exit', (worker) => {
    console.log(`Worker ${worker.process.pid} died, restarting`);
    cluster.fork();
  });
} else {
  require('./server');
}

PM2 가 이 관리를 대신함.

Environment 관리

npm i dotenv

require('dotenv').config();

Kubernetes 나 Docker Compose 는 env 를 컨테이너에 주입. .env 는 dev 만.

Config schema:

npm i zod

const {z} = require('zod');

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  PORT: z.string().transform(Number).default('3000'),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});

const env = envSchema.parse(process.env);

앱 시작 시 검증.

함정

[!WARNING] Graceful shutdown 안 하면 in-flight 요청 손실. SIGTERM handler + server.close 필수.

[!CAUTION] app.proxy = true 를 프록시 없는 환경에 켜면 IP spoofing 위험. X-Forwarded-For 를 client 가 임의로 설정.

[!WARNING] Stack trace 프로덕션 노출 금지. Error middleware 에서 NODE_ENV 분기.

[!IMPORTANT] terminationGracePeriodSeconds > shutdown 완료 시간. K8s 강제 종료 방지.

[!CAUTION] Node dependency alpine 문제. Native module (bcrypt, prisma) 는 alpine + musl 별도 빌드. multi-stage 로 안전.

[Koa] Error Handling

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Koa Error Handling 은 미들웨어 chain 에서 발생한 예외를 catch 하여 응답을 정형화하는 패턴입니다. Koa 는 자동 error handler 를 제공하지만, 프로덕션은 대개 커스텀 error middleware + app.on('error') 로직을 조합합니다.

기본: try/catch middleware

가장 관용적 패턴. 모든 미들웨어의 최외곽.

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || err.statusCode || 500;
    ctx.body = {
      error: err.message,
      ...(process.env.NODE_ENV !== 'production' && {stack: err.stack}),
    };
    ctx.app.emit('error', err, ctx);
  }
});

app.on('error') 는 로깅/외부 알림 (Sentry) 용:

app.on('error', (err, ctx) => {
  logger.error({err, url: ctx?.url});
  Sentry.captureException(err);
});

`ctx.throw()`

http-errors 기반 예외 발생. Status + message + properties:

ctx.throw(400);                              // 400 Bad Request
ctx.throw(400, 'Missing email');
ctx.throw(404, 'User not found');
ctx.throw(422, 'Validation failed', {
  field: 'email',
  code: 'INVALID_EMAIL',
});

Error 객체 자체:

const err = new Error('boom');
err.status = 400;
throw err;

`ctx.assert()`

Truthy 검사 + 실패 시 throw:

ctx.assert(user, 401, 'Login required');
ctx.assert(id, 400, 'ID required');
ctx.assert(admin, 403);

assert(user, 401) == if (!user) ctx.throw(401).

Async error

Async middleware 에서 throw 는 자동으로 upstream 으로. await 없이 던지면 위험:

// BAD
app.use(async (ctx, next) => {
  await next();
});

app.use(async (ctx) => {
  someAsyncFn().catch(err => { throw err; });   // upstream 안 감
});

await 을 반드시:

app.use(async (ctx) => {
  await someAsyncFn();   // 실패 시 자동 upstream
});

응답 형식 통일

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    const status = err.status || err.statusCode || 500;
    const isProduction = process.env.NODE_ENV === 'production';

    ctx.status = status;
    ctx.body = {
      error: {
        code: err.code || (status === 500 ? 'INTERNAL' : 'ERROR'),
        message: (isProduction && status === 500) ? 'Internal Server Error' : err.message,
        ...(err.details && {details: err.details}),
        ...(!isProduction && {stack: err.stack}),
      },
      timestamp: new Date().toISOString(),
      path: ctx.path,
      requestId: ctx.state.requestId,
    };

    if (status >= 500) {
      ctx.app.emit('error', err, ctx);
    }
  }
});

Custom Error class

class DomainError extends Error {
  constructor(code, message, status = 400, details) {
    super(message);
    this.code = code;
    this.status = status;
    this.details = details;
    this.name = 'DomainError';
  }
}

class UserNotFoundError extends DomainError {
  constructor(id) {
    super('USER_NOT_FOUND', `User ${id} not found`, 404);
    this.userId = id;
  }
}

// 사용
router.get('/users/:id', async (ctx) => {
  const user = await User.findById(ctx.params.id);
  if (!user) throw new UserNotFoundError(ctx.params.id);
  ctx.body = user;
});

Error middleware 에서 특정 error 매핑:

if (err instanceof PrismaClientKnownRequestError) {
  if (err.code === 'P2002') {
    ctx.status = 409;
    ctx.body = {error: 'Duplicate entry'};
    return;
  }
}

Validation error (Zod)

const {ZodError} = require('zod');

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    if (err instanceof ZodError) {
      ctx.status = 400;
      ctx.body = {
        error: 'Validation failed',
        details: err.errors,
      };
      return;
    }
    throw err;   // 다음 handler 로
  }
});

404 처리

Router 가 매칭 실패 시 default 로 404. 커스텀:

app.use(async (ctx, next) => {
  await next();
  if (ctx.status === 404 && !ctx.body) {
    ctx.body = {error: 'Not found', path: ctx.path};
  }
});

또는 router 뒤에 catch-all:

app.use(router.routes());
app.use(router.allowedMethods());
app.use(async (ctx) => {
  ctx.status = 404;
  ctx.body = {error: 'Not found'};
});

`app.on('error')`

Middleware chain 안 오류 + Koa 자체 오류 모두 emit.

app.on('error', (err, ctx) => {
  // ctx 는 있을 수도 없을 수도 (chain 밖 에러는 없음)
  const info = {
    err: {
      message: err.message,
      code: err.code,
      status: err.status,
      stack: err.stack,
    },
    request: ctx ? {
      method: ctx.method,
      url: ctx.url,
      headers: ctx.headers,
      ip: ctx.ip,
    } : null,
  };
  logger.error(info);
});

Unhandled Rejection / Uncaught Exception

Middleware 밖 에러 (setTimeout, background task):

process.on('unhandledRejection', (reason, promise) => {
  logger.error('Unhandled Rejection:', reason);
  Sentry.captureException(reason);
});

process.on('uncaughtException', (err) => {
  logger.error('Uncaught Exception:', err);
  Sentry.captureException(err);
  // 프로세스 재시작 권장 (일관 상태 보장 불가)
  process.exit(1);
});

Client 오류 vs Server 오류

4xx (client): 로그 낮은 level. Alert X.
5xx (server): 로그 error level. Alert O.

if (status >= 500) {
  logger.error({err});
  Sentry.captureException(err);
} else {
  logger.warn({err});
}

Timeout

const timeout = require('koa-timeout-v2');
app.use(timeout(30000, {status: 408}));

Long-running handler 는 별도 (queue 로 오프로드).

Error middleware 순서

최외곽에 (첫 미들웨어). 그래야 downstream 모든 에러 catch.

app.use(errorMiddleware);      // 1
app.use(logger);                // 2
app.use(bodyParser());          // 3
app.use(auth);                  // 4
app.use(router.routes());       // 5

Multiple error handlers

에러 종류별로:

// Layer 1: Domain errors
app.use(async (ctx, next) => {
  try { await next(); } catch (err) {
    if (err instanceof DomainError) {
      ctx.status = err.status;
      ctx.body = {code: err.code, message: err.message};
      return;
    }
    throw err;
  }
});

// Layer 2: Validation errors
app.use(async (ctx, next) => {
  try { await next(); } catch (err) {
    if (err instanceof ZodError) {
      ctx.status = 400;
      ctx.body = {errors: err.errors};
      return;
    }
    throw err;
  }
});

// Layer 3: Fallback (unknown)
app.use(async (ctx, next) => {
  try { await next(); } catch (err) {
    ctx.status = 500;
    ctx.body = {error: 'Internal Server Error'};
    ctx.app.emit('error', err, ctx);
  }
});

함정

[!WARNING] Error middleware 를 마지막에 등록하면 못 잡음. 반드시 첫 번째.

[!CAUTION] Async 안 throw 는 promise rejection. await 없이 next 하면 lost.

[!WARNING] Prod 에서 stack trace 노출 위험. Env 로 분기.

[!IMPORTANT] ctx.throw() vs custom Error. throw 는 http-errors 기반. Custom error 는 별도 인스턴스. Middleware 에서 두 유형 모두 처리.

[!CAUTION] ctx.body 를 error middleware 앞 에서 세팅 후 throw = ctx.body 유지 X. Downstream 이 override.

[Koa] Koa vs Express

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Koa 와 Express 는 모두 Node.js 웹 프레임워크이지만 철학과 API 스타일이 다릅니다. Express 는 오래됐고 방대한 생태계 (2010~), Koa 는 async/await 우선 (2013~). 창시자는 같은 TJ Holowaychuk 이며 Koa 는 Express 의 후계 성격.

한눈에 비교

축	Express	Koa
첫 릴리스	2010	2013
크기	500KB+ (deps)	매우 작음 (~200KB)
비동기	callback 기본, async/await 도 가능	async/await first
미들웨어 모델	linear (next())	onion (await next())
Request/Response	req, res 각각	ctx (통합)
에러 처리	try/catch 어려움 (callback)	async try/catch 자연
라우팅	내장 (`app.get`)	별도 (`@koa/router`)
Body parser	내장 (`express.json()`)	별도 (`@koa/bodyparser`)
템플릿	내장 지원	별도
정적 파일	내장 (`express.static`)	별도 (`koa-static`)
커뮤니티	매우 큼	중간
생태계	방대 (10,000+ 미들웨어)	작음 (koa- 프리픽스)
채택	압도적 다수	소수

미들웨어 스타일

Express

// callback 스타일
app.get('/users/:id', (req, res, next) => {
  User.findById(req.params.id, (err, user) => {
    if (err) return next(err);
    res.json(user);
  });
});

// async 스타일 (수동 try/catch)
app.get('/users/:id', async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    res.json(user);
  } catch (err) {
    next(err);
  }
});

Express 는 async error 를 자동으로 안 잡음. express-async-errors 패키지 또는 wrapper 필요.

Koa

router.get('/users/:id', async (ctx) => {
  const user = await User.findById(ctx.params.id);
  ctx.body = user;
});

Async error 는 upstream 으로 자동 전파. 미들웨어에서 try/catch.

Middleware chain

Express (linear)

app.use((req, res, next) => {
  console.log('1');
  next();
  console.log('1 after');   // 이는 실행되지만 응답 이후 관측 어려움
});

app.use((req, res, next) => {
  console.log('2');
  res.send('done');
});

// 출력: 1, 2, 1 after (하지만 response 완료 이후)

Koa (onion)

app.use(async (ctx, next) => {
  console.log('1 in');
  await next();
  console.log('1 out');    // response 이후 확실히 실행
});

app.use(async (ctx) => {
  console.log('2');
  ctx.body = 'done';
});

// 출력: 1 in, 2, 1 out

Koa 의 onion 모델은 응답 시간 측정, 에러 catch, wrapping 이 자연스럽습니다.

Response 처리

Express

app.get('/', (req, res) => {
  res.status(201);
  res.set('X-Custom', 'value');
  res.json({ok: true});
  // 또는 chain
  res.status(201).set('X-Custom', 'value').json({ok: true});
});

res.send, res.json, res.render, res.redirect 등 method 다양.

Koa

router.get('/', async (ctx) => {
  ctx.status = 201;
  ctx.set('X-Custom', 'value');
  ctx.body = {ok: true};   // JSON 자동
});

ctx.body 하나로. Type 자동 감지 (string -> text/html, object -> json).

Error 처리

Express

app.use((err, req, res, next) => {
  console.error(err);
  res.status(err.status || 500).json({error: err.message});
});

// async error 자동 X (v4)
app.get('/', async (req, res, next) => {
  try {
    await doAsyncWork();
  } catch (err) {
    next(err);   // 수동
  }
});

Express 5 에서 async error 를 자동 처리 예정.

Koa

// 첫 미들웨어
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {error: err.message};
    ctx.app.emit('error', err, ctx);
  }
});

// 그냥 throw
router.get('/', async (ctx) => {
  await doAsyncWork();   // 실패 시 자동 upstream
  ctx.body = 'ok';
});

성능

Express: baseline. 특별한 최적화 없음.
Koa: 조금 빠름 (코어 작음). 미들웨어 오버헤드 감소.
Fastify: 훨씬 빠름 (JSON 최적화, 스키마 컴파일). 성능이 최우선이면 Fastify.

언제 어느 것을?

Express 유지 / 선택

기존 코드베이스
광범위한 미들웨어 필요 (Passport strategies, 특수 통합)
팀이 Express 익숙
튜토리얼/문서/자료 방대 필요
Express 5+ async 개선 후

Koa 선택

새 프로젝트 + async/await 자연스러움 원함
가벼운 코어 + 필요한 것만 조합
Onion 모델 (트레이싱, error handling 통일) 이점
Express 미들웨어 안 필수

대안 고려

Fastify: 성능 최상, schema-first
NestJS: 대규모 앱 구조, TypeScript, DI
Hono: Cloudflare Workers / Edge 최적
Elysia: Bun native

코드 예시 나란히

Hello World

// Express
const express = require('express');
const app = express();

app.get('/', (req, res) => res.send('Hello'));
app.listen(3000);

// Koa
const Koa = require('koa');
const Router = require('@koa/router');

const app = new Koa();
const router = new Router();

router.get('/', ctx => { ctx.body = 'Hello'; });

app.use(router.routes());
app.listen(3000);

JSON API

// Express
app.use(express.json());
app.post('/users', async (req, res, next) => {
  try {
    const user = await User.create(req.body);
    res.status(201).json(user);
  } catch (err) {
    next(err);
  }
});

// Koa
const bodyParser = require('@koa/bodyparser');
app.use(bodyParser());

router.post('/users', async ctx => {
  const user = await User.create(ctx.request.body);
  ctx.status = 201;
  ctx.body = user;
});

Error handler

// Express
app.use((err, req, res, next) => {
  res.status(err.status || 500).json({error: err.message});
});

// Koa (최상단 미들웨어)
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {error: err.message};
  }
});

File upload

// Express + multer
const multer = require('multer');
const upload = multer({dest: '/uploads/'});
app.post('/upload', upload.single('file'), (req, res) => {
  res.json({filename: req.file.filename});
});

// Koa + @koa/multer
const multer = require('@koa/multer');
const upload = multer({dest: '/uploads/'});
router.post('/upload', upload.single('file'), async ctx => {
  ctx.body = {filename: ctx.file.filename};
});

마이그레이션 (Express -> Koa)

주요 변환:

req.method -> ctx.method, req.path -> ctx.path
req.body -> ctx.request.body
res.status(200).json(x) -> ctx.status = 200; ctx.body = x
(req, res, next) -> (ctx, next)
app.get(...) -> Router 로 이관
Middleware 등록 순서 재검토 (onion model 로)
미들웨어 (express-session, helmet, …) -> koa 버전

대규모 앱은 마이그레이션 노력 큼. 새 프로젝트만 Koa 선택 후 기존은 유지가 관용.

함정

[!WARNING] Express middleware 는 Koa 에서 못 씀. Express 는 (req, res, next), Koa 는 (ctx, next). koa-connect 로 래핑 가능하지만 완전 X.

[!CAUTION] Express 5 는 async 자동 처리. Express 4 는 아님. 프로젝트 버전 확인.

[!WARNING] Koa 는 라우팅/body parser 없음. Express 에서 온 사람이 자주 실수.

[!IMPORTANT] 미들웨어 표기법 다름. Express app.use(m), Koa app.use(m) 은 같아 보이지만 signature 다름.

[!CAUTION] 성능은 프레임워크보다 코드가 지배적. 프레임워크 선택은 팀/생태계가 우선.

[Koa] Middleware (Onion Model)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Koa Middleware 는 요청/응답 사이에 실행되는 async 함수입니다. 각 미들웨어는 ctx (context) 와 next (다음 미들웨어를 실행하는 함수) 를 받고, await next() 로 downstream 을 실행하고 그 이후에 upstream 로직을 실행합니다. 이것이 onion model (양파 모델).

기본 구조

app.use(async (ctx, next) => {
  console.log('before');
  await next();
  console.log('after');
});

next() 를 호출 안 하면 다음 미들웨어로 안 감 (chain 중단)
await next() 를 잊으면 async 흐름 깨짐

Onion Model 예시

app.use(async (ctx, next) => {
  console.log('1 in');
  await next();
  console.log('1 out');
});

app.use(async (ctx, next) => {
  console.log('2 in');
  await next();
  console.log('2 out');
});

app.use(async (ctx) => {
  console.log('3 handler');
  ctx.body = 'response';
});

실행 순서:

1 in
  2 in
    3 handler   ← 응답 body 세팅
  2 out
1 out           ← 마지막

await next() 이전: downstream 방향 로직
await next() 이후: upstream 방향 로직

왜 이 모델이 유용한가

1. 응답 시간 측정

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();                             // 실제 handler 실행
  const ms = Date.now() - start;             // handler 끝난 후
  ctx.set('X-Response-Time', `${ms}ms`);
});

2. 에러 catch

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    ctx.status = err.status || 500;
    ctx.body = {error: err.message};
    ctx.app.emit('error', err, ctx);
  }
});

3. 응답 wrapping

app.use(async (ctx, next) => {
  await next();
  if (ctx.body && typeof ctx.body === 'object') {
    ctx.body = {
      success: true,
      data: ctx.body,
      timestamp: new Date().toISOString(),
    };
  }
});

4. 트레이싱

app.use(async (ctx, next) => {
  const span = tracer.startSpan('http.request');
  ctx.state.span = span;
  try {
    await next();
    span.setStatus({code: 0});
  } catch (err) {
    span.setStatus({code: 2, message: err.message});
    throw err;
  } finally {
    span.end();
  }
});

Middleware 종류

함수 (async)

app.use(async (ctx, next) => {
  // ...
});

함수 (일반 Promise 리턴)

app.use((ctx, next) => {
  return doAsyncWork().then(() => next());
});

Generator function (deprecated, Koa v1 스타일)

Koa v3 는 지원 안 함.

조건부 실행

app.use(async (ctx, next) => {
  if (ctx.path.startsWith('/api')) {
    await next();
    return;
  }
  ctx.body = 'not api';
});

Middleware 등록 순서

app.use(errorHandler);
app.use(logger);
app.use(cors());
app.use(helmet());
app.use(bodyParser());
app.use(session);
app.use(authMiddleware);
app.use(router.routes());
app.use(router.allowedMethods());

관용:

최외곽: error handler (모든 예외 catch)
관측: logger, request-id, tracing
보안: cors, helmet
파싱: body parser, cookies
인증: session, auth
라우팅: router

Async 안 하는 미들웨어

app.use((ctx, next) => {
  ctx.set('X-Powered-By', 'Koa');
  return next();
});

ctx.body 만 세팅하고 next() 없이 종료:

app.use(async (ctx) => {
  ctx.body = 'Static response';
});

`next()` 안 부르면?

app.use(async (ctx, next) => {
  ctx.body = 'stopped here';
  // await next() 없음
});

app.use(async (ctx) => {
  ctx.body = 'never reached';
});

두 번째 미들웨어 실행 안 됨. 조건부 short-circuit 에 활용.

`koa-compose` (여러 미들웨어를 하나로)

const compose = require('koa-compose');

const middlewareStack = compose([
  errorHandler,
  logger,
  bodyParser(),
]);

app.use(middlewareStack);

Router 내부에서도 활용.

Conditional middleware (paths)

Koa 자체는 path 별 미들웨어 지원 X. 조건부로 직접:

app.use(async (ctx, next) => {
  if (!ctx.path.startsWith('/admin')) {
    return next();
  }
  // admin 만
  if (!ctx.state.user?.isAdmin) {
    ctx.throw(403);
  }
  await next();
});

또는 koa-mount:

const mount = require('koa-mount');
const adminApp = new Koa();
adminApp.use(adminAuthMiddleware);
adminApp.use(adminRouter.routes());

app.use(mount('/admin', adminApp));

Error propagation

Middleware 안에서 throw 하면 upstream 으로 전파. 첫 error handler 가 catch:

app.use(async (ctx, next) => {
  try { await next(); } catch (err) { /* handle */ }
});

app.use(async (ctx, next) => {
  throw new Error('boom');   // 위 catch 로 감
});

ctx.throw() 도 같은 방식 (http-errors).

App emit error

app.on('error', (err, ctx) => {
  logger.error('Unhandled error:', err);
  Sentry.captureException(err);
});

Middleware chain 밖에서도 처리 가능 (default handler 실행 후 emit).

공식 미들웨어

@koa/* scope:

@koa/router: 라우팅
@koa/cors: CORS
@koa/multer: multipart
@koa/bodyparser: body parsing

Community:

koa-helmet: 보안 헤더
koa-session: session
koa-static: 정적 파일
koa-mount: sub-app mounting
koa-compress: gzip/brotli
koa-logger: 개발 로그
koa-pino-logger: JSON 로그
koa-jwt: JWT 인증
koa-ratelimit: rate limiting
koa-passport: Passport 통합
koa-response-time: X-Response-Time

사용자 정의 미들웨어

옵션 받는 factory 형태 관용:

function requestId(options = {}) {
  const headerName = options.headerName || 'X-Request-Id';

  return async (ctx, next) => {
    const id = ctx.get(headerName) || crypto.randomUUID();
    ctx.state.requestId = id;
    ctx.set(headerName, id);
    await next();
  };
}

app.use(requestId({headerName: 'X-Trace-ID'}));

미들웨어 안에서 next 여러 번 호출

app.use(async (ctx, next) => {
  await next();
  await next();   // Error: next() called multiple times
});

next 는 한 번만.

Middleware 성능

각 미들웨어는 async 함수 호출 오버헤드
20 개 넘어가면 latency 눈에 띔
필수만 등록

함정

[!WARNING] await next() 잊으면 chain 이탈. 다음 미들웨어 실행 안 되고 응답 empty.

[!CAUTION] next() 두 번 호출 = 오류. Koa-compose 가 감지.

[!WARNING] 동기 미들웨어에서 next() return 안 하면 후속 흐름 안 됨. return next() 습관.

[!IMPORTANT] Middleware 순서. Error handler outermost, router innermost.

[!CAUTION] Middleware 안 blocking I/O 금지. Sync fs, JSON.parse 큰 payload 등. Event loop 정지.

[Koa] Router (@koa/router)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

@koa/router 는 Koa 의 공식 라우터입니다. Koa 코어는 라우팅을 제공하지 않으므로 별도 설치가 필요합니다. Express 스타일 라우팅 (HTTP method + URL) 을 지원하며, path-to-regexp 로 파라미터 매칭합니다.

설치

npm i @koa/router

기본

const Koa = require('koa');
const Router = require('@koa/router');

const app = new Koa();
const router = new Router();

router.get('/', async (ctx) => {
  ctx.body = 'Home';
});

router.get('/users/:id', async (ctx) => {
  ctx.body = { id: ctx.params.id };
});

router.post('/users', async (ctx) => {
  ctx.body = ctx.request.body;
});

app
  .use(router.routes())
  .use(router.allowedMethods());

app.listen(3000);

router.routes(): HTTP 요청을 매칭 후 handler 실행
router.allowedMethods(): 405 Method Not Allowed 지원

HTTP Methods

router.get('/path', handler);
router.post('/path', handler);
router.put('/path', handler);
router.patch('/path', handler);
router.delete('/path', handler);
router.head('/path', handler);
router.options('/path', handler);
router.all('/path', handler);       // 모든 method

Path Parameters

router.get('/users/:id', async (ctx) => {
  ctx.params.id;
});

router.get('/users/:userId/posts/:postId', async (ctx) => {
  ctx.params.userId;
  ctx.params.postId;
});

Optional parameter

router.get('/users/:id?', async (ctx) => {
  // /users -> id undefined
  // /users/1 -> id '1'
});

Regex

router.get('/users/:id(\\d+)', async (ctx) => {
  // id 는 숫자만
});

Wildcard

router.get('/files/(.*)', async (ctx) => {
  const path = ctx.params[0];
});

Query Parameters

Koa 자체가 자동 파싱:

router.get('/search', async (ctx) => {
  ctx.query.q;
  ctx.query.page;
});
// GET /search?q=koa&page=2  ->  {q: 'koa', page: '2'}

Router Middleware

Handler 전에 미들웨어 실행:

async function requireAuth(ctx, next) {
  if (!ctx.state.user) ctx.throw(401);
  await next();
}

router.get('/me', requireAuth, async (ctx) => {
  ctx.body = ctx.state.user;
});

// 여러 미들웨어
router.get('/admin', requireAuth, requireAdmin, async (ctx) => {
  ctx.body = 'admin dashboard';
});

Router.use()

Router 전체에 미들웨어:

router.use(async (ctx, next) => {
  console.log(`${ctx.method} ${ctx.path}`);
  await next();
});

router.use('/admin', requireAdmin);   // 특정 prefix 만

router.use(['/admin', '/dashboard'], requireAuth);

Router Prefix

const router = new Router({prefix: '/api/v1'});

router.get('/users', async (ctx) => {
  // 실제 URL: /api/v1/users
});

Nested Router

const rootRouter = new Router();
const usersRouter = new Router({prefix: '/users'});
const postsRouter = new Router({prefix: '/posts'});

usersRouter.get('/', async (ctx) => { ... });
usersRouter.get('/:id', async (ctx) => { ... });

postsRouter.get('/', async (ctx) => { ... });

rootRouter.use(usersRouter.routes(), usersRouter.allowedMethods());
rootRouter.use(postsRouter.routes(), postsRouter.allowedMethods());

app.use(rootRouter.routes()).use(rootRouter.allowedMethods());

Named Route

router.get('user-detail', '/users/:id', async (ctx) => { ... });

// URL 생성
router.url('user-detail', {id: 42});   // '/users/42'
router.url('user-detail', {id: 42}, {query: {tab: 'profile'}});   
// '/users/42?tab=profile'

Template 렌더링, redirect 에 유용.

Route parameters middleware

특정 param 이 있을 때 미리 처리:

router.param('user', async (id, ctx, next) => {
  ctx.state.user = await getUserById(id);
  if (!ctx.state.user) ctx.throw(404);
  await next();
});

router.get('/users/:user', async (ctx) => {
  ctx.body = ctx.state.user;
});

router.get('/users/:user/posts', async (ctx) => {
  ctx.body = await getPostsByUser(ctx.state.user.id);
});

Router 파일 분할

// routes/users.js
const Router = require('@koa/router');
const router = new Router({prefix: '/users'});
const controller = require('../controllers/users');

router.get('/', controller.list);
router.get('/:id', controller.get);
router.post('/', controller.create);
router.patch('/:id', controller.update);
router.delete('/:id', controller.delete);

module.exports = router;

// routes/index.js
const Router = require('@koa/router');
const usersRouter = require('./users');
const postsRouter = require('./posts');

const router = new Router();

router.use(usersRouter.routes(), usersRouter.allowedMethods());
router.use(postsRouter.routes(), postsRouter.allowedMethods());

module.exports = router;

// app.js
const router = require('./routes');
app.use(router.routes()).use(router.allowedMethods());

Controller 패턴

// controllers/users.js
async function list(ctx) {
  ctx.body = await User.findAll();
}

async function get(ctx) {
  const user = await User.findById(ctx.params.id);
  ctx.assert(user, 404, 'Not found');
  ctx.body = user;
}

async function create(ctx) {
  const {email, name} = ctx.request.body;
  ctx.assert(email && name, 400);
  const user = await User.create({email, name});
  ctx.status = 201;
  ctx.body = user;
}

async function update(ctx) {
  const user = await User.findByIdAndUpdate(ctx.params.id, ctx.request.body);
  ctx.body = user;
}

async function del(ctx) {
  await User.findByIdAndDelete(ctx.params.id);
  ctx.status = 204;
}

module.exports = {list, get, create, update, delete: del};

`allowedMethods()`

정의된 route 의 method 를 관리:

Method Not Allowed (405): 정의된 path 인데 wrong method
Not Implemented (501): 서버가 지원 안 함
OPTIONS: 자동 응답 (Allow 헤더)

app.use(router.routes()).use(router.allowedMethods({
  throw: true,       // exception 던짐 (직접 handle 가능)
  notImplemented: () => new NotImplementedError(),
  methodNotAllowed: () => new MethodNotAllowedError(),
}));

Route 순서

Koa router 는 정의 순서 로 매칭:

router.get('/users/me', ...);        // 구체적 먼저
router.get('/users/:id', ...);

/users/:id 를 먼저 정의하면 /users/me 를 id=“me” 로 잡아버림.

OPTIONS / CORS

const cors = require('@koa/cors');

app.use(cors({
  origin: 'https://app.example.com',
  credentials: true,
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowHeaders: ['Content-Type', 'Authorization'],
}));

app.use(router.routes()).use(router.allowedMethods());

Match 정보

router.get('/users/:id', async (ctx) => {
  console.log(ctx.matched);   // 매칭된 route 목록
  console.log(ctx._matchedRouteName);   // named route
});

Redirect

router.redirect('/old', '/new', 301);

Version 라우팅

Router prefix 또는 header 기반:

const v1 = new Router({prefix: '/api/v1'});
const v2 = new Router({prefix: '/api/v2'});

v1.get('/users', v1Controller.list);
v2.get('/users', v2Controller.list);

app.use(v1.routes());
app.use(v2.routes());

함정

[!WARNING] Route 순서 실수. /users/:id 를 /users/me 보다 먼저 정의하면 /users/me 를 id=“me” 로 매치. 항상 구체적 route 를 먼저.

[!CAUTION] router.routes() 를 여러 번 호출 하면 동일 route 여러 번 등록. 한 번만.

[!WARNING] allowedMethods() 없으면 잘못된 method 요청이 404. 405 로 응답하려면 반드시 등록.

[!IMPORTANT] router.get('name', '/path', handler) vs router.get('/path', handler). Named vs unnamed.

[!CAUTION] Nested router 시 prefix 이중 적용. Root router prefix + sub router prefix.

[Koa] Testing (Supertest, Jest, Vitest)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

Koa Testing 은 Supertest (HTTP 호출) + Jest/Vitest (assertions/runner) 조합이 표준입니다. app.callback() 을 Supertest 에 전달하면 실제 HTTP 서버 없이 요청/응답 검증 가능.

설치

npm i -D jest supertest
# 또는
npm i -D vitest supertest

기본 예시

// app.js
const Koa = require('koa');
const Router = require('@koa/router');
const bodyParser = require('@koa/bodyparser');

function createApp() {
  const app = new Koa();
  const router = new Router();

  router.get('/', async (ctx) => {
    ctx.body = 'Hello';
  });

  router.get('/users/:id', async (ctx) => {
    ctx.body = {id: ctx.params.id};
  });

  router.post('/users', async (ctx) => {
    ctx.assert(ctx.request.body.email, 400, 'email required');
    ctx.status = 201;
    ctx.body = ctx.request.body;
  });

  app.use(bodyParser());
  app.use(router.routes()).use(router.allowedMethods());

  return app;
}

module.exports = createApp;

// app.test.js
const request = require('supertest');
const createApp = require('./app');

describe('App', () => {
  let app;

  beforeEach(() => {
    app = createApp();
  });

  it('GET / returns Hello', async () => {
    const res = await request(app.callback())
      .get('/')
      .expect(200);
    expect(res.text).toBe('Hello');
  });

  it('GET /users/:id returns id', async () => {
    const res = await request(app.callback())
      .get('/users/42')
      .expect(200)
      .expect('Content-Type', /json/);
    expect(res.body).toEqual({id: '42'});
  });

  it('POST /users creates user', async () => {
    const res = await request(app.callback())
      .post('/users')
      .send({email: 'a@b.com', name: 'kim'})
      .expect(201);
    expect(res.body.email).toBe('a@b.com');
  });

  it('POST /users returns 400 without email', async () => {
    await request(app.callback())
      .post('/users')
      .send({name: 'kim'})
      .expect(400);
  });
});

Supertest API

request(app.callback())
  .get('/users?page=1&limit=10')
  .set('Authorization', 'Bearer token')
  .set('Accept', 'application/json')
  .expect(200)
  .expect('Content-Type', /json/)
  .expect('X-Custom', 'value')
  .expect((res) => {
    expect(res.body.length).toBe(10);
  });

// POST with body
request(app.callback())
  .post('/users')
  .send({email: 'a@b.com'})     // JSON 자동
  .expect(201);

// Form data
request(app.callback())
  .post('/form')
  .type('form')
  .send({name: 'kim', email: 'a@b.com'});

// File upload
request(app.callback())
  .post('/upload')
  .attach('file', './test/fixtures/photo.jpg');

// Multiple fields
request(app.callback())
  .post('/upload')
  .field('name', 'Test')
  .attach('file', 'test.jpg');

// Cookies
request(app.callback())
  .get('/me')
  .set('Cookie', 'session=abc');

Middleware 단위 테스트

Middleware 를 직접 호출:

const requestId = require('./middleware/request-id');

it('sets X-Request-Id', async () => {
  const ctx = {
    set: jest.fn(),
    get: jest.fn().mockReturnValue(''),
    state: {},
  };
  const next = jest.fn();

  await requestId()(ctx, next);

  expect(ctx.state.requestId).toBeDefined();
  expect(ctx.set).toHaveBeenCalledWith('X-Request-Id', expect.any(String));
  expect(next).toHaveBeenCalled();
});

Mock ctx 는 필요한 필드만 채움.

인증 mocking

async function mockAuth(user) {
  return async (ctx, next) => {
    ctx.state.user = user;
    await next();
  };
}

// 테스트에서 app 재구성
function testApp(overrides = {}) {
  const app = createApp();
  if (overrides.user) {
    app.middleware.unshift(mockAuth(overrides.user));
  }
  return app;
}

it('GET /me returns current user', async () => {
  const app = testApp({user: {id: 1, name: 'kim'}});
  const res = await request(app.callback())
    .get('/me')
    .expect(200);
  expect(res.body.id).toBe(1);
});

DB 격리

SQLite in-memory (Prisma)

process.env.DATABASE_URL = 'file::memory:?cache=shared';

beforeAll(async () => {
  await runMigrations();
});

Testcontainers (PostgreSQL)

const {PostgreSqlContainer} = require('@testcontainers/postgresql');

let container, db;

beforeAll(async () => {
  container = await new PostgreSqlContainer('postgres:16').start();
  process.env.DATABASE_URL = container.getConnectionUri();
  db = require('./db');
  await db.migrate();
}, 60000);

afterAll(async () => {
  await db.disconnect();
  await container.stop();
});

Transaction rollback per test

let tx;

beforeEach(async () => {
  tx = await db.startTransaction();
});

afterEach(async () => {
  await tx.rollback();
});

Snapshot testing

it('GET /users matches snapshot', async () => {
  const res = await request(app.callback())
    .get('/users')
    .expect(200);
  expect(res.body).toMatchSnapshot();
});

HTTP mocking (외부 API)

nock:

npm i -D nock

const nock = require('nock');

beforeEach(() => {
  nock.disableNetConnect();
  nock.enableNetConnect('127.0.0.1');
});

afterEach(() => {
  nock.cleanAll();
});

it('handles external API', async () => {
  nock('https://api.external.com')
    .get('/data/42')
    .reply(200, {value: 'test'});

  const res = await request(app.callback())
    .get('/proxy/42')
    .expect(200);
  expect(res.body.value).toBe('test');
});

또는 MSW.

Error path 테스트

it('returns 404 for missing user', async () => {
  const res = await request(app.callback())
    .get('/users/999')
    .expect(404);
  expect(res.body.error.code).toBe('USER_NOT_FOUND');
});

it('returns 400 on invalid body', async () => {
  await request(app.callback())
    .post('/users')
    .send({email: 'not-an-email'})
    .expect(400);
});

it('logs 500 errors', async () => {
  const errorSpy = jest.spyOn(console, 'error').mockImplementation();

  // Endpoint 가 throw 하도록
  await request(app.callback())
    .get('/error')
    .expect(500);

  expect(errorSpy).toHaveBeenCalled();
  errorSpy.mockRestore();
});

Environment 격리

const originalEnv = process.env.NODE_ENV;

beforeEach(() => {
  process.env.NODE_ENV = 'test';
});

afterEach(() => {
  process.env.NODE_ENV = originalEnv;
});

E2E vs Unit

Unit: middleware, controller 함수를 직접 mock ctx 로 테스트
Integration: app.callback() + Supertest 로 HTTP 요청 시뮬레이션
E2E: 실제 서버 기동 + 실제 DB (또는 testcontainers)

Koa 는 app.callback() 이 실 HTTP 서버 없이 요청 처리 가능해 integration test 가 매우 빠릅니다.

CI 통합 (GitHub Actions)

name: test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
        ports: [5432:5432]
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm test -- --coverage
        env:
          DATABASE_URL: postgres://postgres:test@localhost:5432/postgres

Vitest (더 빠름, ESM 우선)

// vitest.config.js
export default {
  test: {
    environment: 'node',
    globals: true,
    coverage: {
      reporter: ['text', 'html'],
      exclude: ['**/node_modules/**', '**/*.test.js'],
    },
  },
};

// test 는 Jest 와 거의 동일 API

함정

[!WARNING] app.listen() 후 close 안 하면 test 종료 안 됨. app.callback() 을 supertest 에 넘기면 자동. 직접 listen 은 afterAll 에서 close.

[!CAUTION] DB 상태 leak. 각 테스트 후 rollback 또는 truncate.

[!WARNING] process.env 조작. Test 간 leak. beforeEach 에서 backup, afterEach 에서 restore.

[!IMPORTANT] Middleware order 는 test 에도 영향. Auth mock 을 잘못된 위치에 삽입하면 실제 auth 안 우회.

[!CAUTION] Async assertion. expect(promise).resolves / .rejects 형태.

[NestJS] Config (Environment, Validation)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Config 는 @nestjs/config 패키지로 환경변수를 관리합니다. .env 파일 로딩, TypeScript type-safe access, 검증 (Joi/Zod), 여러 환경 (dev/stg/prod) 지원. Global module 로 등록해 어디서든 주입.

설치

npm i @nestjs/config

기본 사용

AppModule


@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,           // 다른 module 에 import 없이도 사용
      envFilePath: '.env',
      cache: true,               // 값 캐시 (성능)
      expandVariables: true,     // ${VAR} 확장
    }),
  ],
})
export class AppModule {}

사용


@Injectable()
export class MyService {
  constructor(private config: ConfigService) {}

  someMethod() {
    const dbUrl = this.config.get<string>('DATABASE_URL');
    const port = this.config.get<number>('PORT', 3000);   // 기본값
    const isProduction = this.config.get<string>('NODE_ENV') === 'production';
  }
}

여러 .env 파일

ConfigModule.forRoot({
  envFilePath: [
    `.env.${process.env.NODE_ENV}.local`,
    `.env.${process.env.NODE_ENV}`,
    '.env.local',
    '.env',
  ],
});

우선순위: 첫 번째 파일 값이 우선.

Type Safety

기본 get() 은 loose. 타입 명시 필요:

const port = this.config.get<number>('PORT');   // 타입은 지정하지만 실제는 string
const port = Number(this.config.get('PORT'));    // 명시적 변환

Validation (Joi)

배포 시점에 필수 값 검증.

npm i joi


@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validationSchema: Joi.object({
        NODE_ENV: Joi.string()
          .valid('development', 'production', 'test', 'staging')
          .default('development'),
        PORT: Joi.number().default(3000),
        DATABASE_URL: Joi.string().required(),
        JWT_SECRET: Joi.string().required().min(32),
        REDIS_HOST: Joi.string().default('localhost'),
        REDIS_PORT: Joi.number().default(6379),
        LOG_LEVEL: Joi.string()
          .valid('error', 'warn', 'info', 'debug')
          .default('info'),
      }),
      validationOptions: {
        allowUnknown: true,   // 미명시 env 허용 (안 하면 오류)
        abortEarly: false,     // 모든 오류 표시
      },
    }),
  ],
})
export class AppModule {}

앱 시작 시 검증 실패 -> immediate error message.

Zod 대안

npm i zod


const configSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test', 'staging']),
  PORT: z.string().transform(Number),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
});

type ConfigType = z.infer<typeof configSchema>;

ConfigModule.forRoot({
  validate: (config) => configSchema.parse(config),
});

Custom Configuration (namespace)

큰 앱은 config 를 여러 파일로 분리:

// config/database.config.ts

export default registerAs('database', () => ({
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT, 10) || 5432,
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  pool: {
    max: parseInt(process.env.DB_POOL_MAX, 10) || 10,
    idleTimeout: 30000,
  },
}));

// config/redis.config.ts
export default registerAs('redis', () => ({
  host: process.env.REDIS_HOST,
  port: parseInt(process.env.REDIS_PORT, 10) || 6379,
  password: process.env.REDIS_PASSWORD,
}));

// config/app.config.ts
export default registerAs('app', () => ({
  name: process.env.APP_NAME || 'my-app',
  port: parseInt(process.env.PORT, 10) || 3000,
  environment: process.env.NODE_ENV,
  version: process.env.APP_VERSION,
}));

AppModule:




@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [databaseConfig, redisConfig, appConfig],
      validationSchema: Joi.object({...}),
    }),
  ],
})

사용

// namespaced access
const dbConfig = this.config.get('database');
const dbHost = this.config.get('database.host');
const poolMax = this.config.get<number>('database.pool.max');

Type-safe namespace

type DatabaseConfig = ConfigType<typeof databaseConfig>;

@Injectable()
export class UsersService {
  constructor(
    @Inject(databaseConfig.KEY)
    private db: DatabaseConfig,
  ) {}

  async connect() {
    console.log(this.db.host);   // typed
  }
}

Async Loading (Vault, AWS Parameter Store)

.env 대신 외부 secret store 에서:

ConfigModule.forRoot({
  isGlobal: true,
  load: [async () => {
    const secrets = await getFromVault();
    return {
      DATABASE_URL: secrets.dbUrl,
      JWT_SECRET: secrets.jwtSecret,
    };
  }],
});

주의: async config 는 앱 부트스트랩 지연. Fallback / caching 필요.

AWS SSM Parameter Store 예


async function loadFromSSM(): Promise<Record<string, string>> {
  const client = new SSMClient({region: 'us-east-1'});
  const command = new GetParametersByPathCommand({
    Path: `/myapp/${process.env.NODE_ENV}/`,
    WithDecryption: true,
    Recursive: true,
  });
  const response = await client.send(command);
  const result: Record<string, string> = {};
  for (const param of response.Parameters || []) {
    const key = param.Name.split('/').pop().toUpperCase();
    result[key] = param.Value;
  }
  return result;
}

Variable Expansion

# .env
BASE_URL=https://api.example.com
USERS_ENDPOINT=${BASE_URL}/users
POSTS_ENDPOINT=${BASE_URL}/posts

ConfigModule.forRoot({
  expandVariables: true,
});

계층: env -> config file -> defaults

// config/default.config.ts
export default {
  cache: {
    ttl: 60,
    max: 1000,
  },
};

// config/production.config.ts
export default {
  cache: {
    ttl: 3600,
  },
};

// 병합 로직

이 패턴은 표준화 안 됨. nest-config 같은 별도 패키지 검토.

Feature Config

한 모듈만 사용:

// UsersModule
@Module({
  imports: [
    ConfigModule.forFeature(usersConfig),
  ],
})

isGlobal: false (기본) 로 다른 module 에서 격리.

프로덕션 관용

12-Factor App

환경변수로 config
코드에 secret 없음
환경별 파일 (.env.dev, .env.prod) 지양, 환경변수 직접

secret 관리

Kubernetes: Secret + ExternalSecrets Operator
AWS: Secrets Manager, SSM Parameter Store, KMS
Vault: HashiCorp Vault
Doppler / 1Password / Infisical: SaaS

Docker/K8s 에서는 .env 파일 대신 환경변수 마운트.

함정

[!WARNING] .env 파일 git 커밋 금지. .gitignore 필수. 실수로 커밋 시 secret rotation.

[!CAUTION] process.env.X 는 항상 string. 숫자, boolean 은 명시적 변환.

[!WARNING] Validation 없으면 조용히 실패. 필수 env 누락되면 undefined 로 부팅 후 나중 오류.

[!IMPORTANT] isGlobal: true 남용. Global 은 어디서든 주입 가능. Feature config 는 격리가 나음.

[!CAUTION] Test 에서 config 격리. process.env 조작은 다른 test 로 leak. beforeEach 에서 restore.

[NestJS] Controllers

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Controller 는 @Controller() 데코레이터가 붙은 클래스로, HTTP 요청을 라우팅하고 응답을 반환합니다. Method 별로 @Get, @Post, @Put, @Patch, @Delete 데코레이터를 붙여 URL + method 조합을 처리합니다.

기본




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

  @Get()
  findAll(@Query('page') page: number = 1) {
    return this.usersService.findAll(page);
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(id);
  }

  @Post()
  @HttpCode(201)
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }

  @Patch(':id')
  update(@Param('id') id: string, @Body() dto: UpdateUserDto) {
    return this.usersService.update(id, dto);
  }

  @Delete(':id')
  @HttpCode(204)
  remove(@Param('id') id: string) {
    return this.usersService.remove(id);
  }
}

URL prefix /users, method 별 하위 경로.

Path Parameter

@Get(':id')
find(@Param('id') id: string) { ... }

@Get(':id/posts/:postId')
findPost(
  @Param('id') id: string,
  @Param('postId') postId: string,
) { ... }

// 전체 params 객체
@Get(':id/posts/:postId')
findPost(@Param() params: {id: string; postId: string}) { ... }

Query Parameter

@Get()
list(
  @Query('page') page: number = 1,
  @Query('limit') limit: number = 10,
) { ... }

// 전체 query 객체
@Get()
list(@Query() query: {page?: string; limit?: string}) { ... }

// DTO 로 (검증 포함)
@Get()
list(@Query() query: ListUsersQuery) { ... }

DTO + [[nestjs-pipes|ValidationPipe]] 로 자동 변환/검증:



export class ListUsersQuery {
  @IsInt()
  @Min(1)
  @Type(() => Number)
  @IsOptional()
  page: number = 1;

  @IsInt()
  @Min(1)
  @Max(100)
  @Type(() => Number)
  @IsOptional()
  limit: number = 10;
}

Request Body

@Post()
create(@Body() dto: CreateUserDto) { ... }

// 특정 필드만
@Post()
create(@Body('email') email: string, @Body('name') name: string) { ... }

Headers, Cookies, IP

@Get()
findAll(
  @Headers('authorization') auth: string,
  @Headers() allHeaders: Record<string, string>,
  @Ip() ip: string,
) { ... }

// Cookies (cookie-parser 필요)
@Get()
withCookie(@Req() req: Request) {
  return req.cookies;
}

Custom Decorator

자주 쓰는 파라미터를 decorator 로:

// common/decorators/user.decorator.ts

export const User = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;
    return data ? user?.[data] : user;
  },
);

// 사용
@Get('me')
me(@User() user: UserEntity) { ... }

@Get('me/email')
myEmail(@User('email') email: string) { ... }

Response

기본 (자동 직렬화)

Method return 값이 자동 JSON 직렬화 + 200 응답.

@Get()
findAll() {
  return {users: [...]};   // -> 200 {"users": [...]}
}

// async 도 OK
@Get(':id')
async find(@Param('id') id: string): Promise<User> {
  return await this.usersService.findOne(id);
}

// Observable 도 OK (RxJS)
@Get()
stream(): Observable<Data> {
  return this.dataService.stream();
}

Status Code

@Post()
@HttpCode(201)              // 명시적 code
create(@Body() dto: CreateUserDto) { ... }

@Delete(':id')
@HttpCode(HttpStatus.NO_CONTENT)   // 204
remove(@Param('id') id: string) { ... }

Headers

@Get()
@Header('Cache-Control', 'none')
@Header('X-Custom', 'value')
findAll() { ... }

Redirect

@Get('legacy')
@Redirect('/new-path', 301)
legacy() { ... }

@Get('dynamic')
dynamic() {
  return {url: '/new-path', statusCode: 301};   // Runtime redirect
}

Raw Response

세밀한 제어 필요 시 @Res():



@Get('download')
download(@Res() res: Response) {
  res.setHeader('Content-Type', 'application/pdf');
  res.sendFile('/path/to/file.pdf');
}

주의: @Res() 를 쓰면 자동 직렬화 못 함. Interceptor 도 우회. Passthrough option 으로 절충:

@Get()
findAll(@Res({passthrough: true}) res: Response) {
  res.setHeader('X-Custom', 'value');
  return {users: [...]};   // 여전히 자동 직렬화
}

Wildcard / Regex

@Get('a*b')          // /aXXb, /axb, ... 모두 매칭
handle() { ... }

@Get(':version(v[0-9]+)/*')   // /v1/anything
versioned(@Param('version') v: string) { ... }

Sub-domain routing

@Controller({ host: 'admin.example.com' })
export class AdminController { ... }

@Controller({ host: ':account.example.com' })
export class TenantController {
  @Get()
  index(@HostParam('account') account: string) { ... }
}

Async, Promise, Observable

세 스타일 모두 지원:

@Get()
sync() {
  return {ok: true};
}

@Get()
async asyncReturn() {
  return await this.service.get();
}

@Get()
observable(): Observable<Data> {
  return this.service.stream();
}

Streaming Response



@Get('file')
file(): StreamableFile {
  const file = createReadStream('/path/to/file.txt');
  return new StreamableFile(file);
}

또는 @Sse() (Server-Sent Events):



@Sse('events')
events(): Observable<MessageEvent> {
  return interval(1000).pipe(
    map(_ => ({data: {time: new Date()}}))
  );
}

Versioning

// main.ts
app.enableVersioning({
  type: VersioningType.URI,
  defaultVersion: '1',
});

@Controller({path: 'users', version: '1'})
export class UsersV1Controller { ... }

@Controller({path: 'users', version: '2'})
export class UsersV2Controller { ... }

URL: /v1/users, /v2/users. Header, Media Type 방식도 있음.

Route Prefix

// main.ts
app.setGlobalPrefix('api');

모든 route 앞에 /api.

@Controller('users')
class UsersController {
  @Get()   // -> GET /api/users
}

특정 controller 는 예외:

app.setGlobalPrefix('api', {
  exclude: [{path: 'health', method: RequestMethod.GET}]
});

Guard / Interceptor / Pipe / Filter 부착

@Controller('users')
@UseGuards(AuthGuard)                       // controller 전체
export class UsersController {

  @Get()
  @UseInterceptors(CacheInterceptor)        // method 만
  @UsePipes(new ValidationPipe())
  @UseFilters(new HttpExceptionFilter())
  findAll() { ... }
}

Global 도 가능 (main.ts 참조).

함정

[!WARNING> @Res() 사용 시 자동 응답/interceptor 우회. passthrough: true 사용.

[!CAUTION] Path 경로 순서. /users/:id 가 /users/me 보다 먼저 정의되면 /users/me 가 id=“me” 로 매치. 구체적 route 를 먼저.

[!WARNING] class-validator metadata 필요. main.ts 에 import 'reflect-metadata' (또는 tsconfig 에 emitDecoratorMetadata: true).

[!IMPORTANT] DTO 안의 Optional field. ? 만으로는 부족. @IsOptional() 데코레이터 함께.

[!CAUTION] @Body() type 은 runtime 검증 X. TypeScript 는 컴파일 후 사라짐. Pipe 로 실제 검증 필수.

[NestJS] Database (TypeORM, Prisma, Mongoose, Drizzle)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Database 통합은 여러 ORM/ODM 을 module 로 감싸 DI + 트랜잭션 + 마이그레이션을 관용화합니다. 주요 선택지: TypeORM (성숙), Prisma (모던, DX 우수), Mongoose (MongoDB), Drizzle (경량 TS 우선).

선택 가이드

도구	강점	약점	언제
Prisma	모던 DX, type-safe, 마이그레이션 우수	별도 schema.prisma 파일, prisma client 크기 큼	새 프로젝트
TypeORM	성숙, 방대한 기능	유지보수 활성도 논란, decorator hell	Legacy 유지
Drizzle	가벼움, TS-first, SQL 그대로	신생, 기능 축적 중	Edge, serverless
Mongoose	MongoDB 사실상 표준	MongoDB 만	MongoDB 워크로드
Sequelize	오래됨, 안정	타입 지원 약함	기존 코드 유지

Prisma 통합 (권장)

설치

npm i prisma @prisma/client
npx prisma init

schema.prisma:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id       Int    @id @default(autoincrement())
  title    String
  body     String
  authorId Int
  author   User   @relation(fields: [authorId], references: [id])
}

마이그레이션

npx prisma migrate dev --name init
npx prisma generate

PrismaService

// prisma/prisma.service.ts


@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    await this.$connect();
  }

  async onModuleDestroy() {
    await this.$disconnect();
  }
}

PrismaModule

// prisma/prisma.module.ts


@Global()
@Module({
  providers: [PrismaService],
  exports: [PrismaService],
})
export class PrismaModule {}

사용

// users/users.service.ts
@Injectable()
export class UsersService {
  constructor(private prisma: PrismaService) {}

  async findAll() {
    return this.prisma.user.findMany({include: {posts: true}});
  }

  async findOne(id: number) {
    return this.prisma.user.findUnique({where: {id}});
  }

  async create(data: {email: string; name: string}) {
    return this.prisma.user.create({data});
  }

  async update(id: number, data: Partial<{email: string; name: string}>) {
    return this.prisma.user.update({where: {id}, data});
  }

  async delete(id: number) {
    return this.prisma.user.delete({where: {id}});
  }
}

트랜잭션

// Interactive
async transferMoney(fromId: number, toId: number, amount: number) {
  return this.prisma.$transaction(async (tx) => {
    await tx.account.update({
      where: {id: fromId},
      data: {balance: {decrement: amount}},
    });
    await tx.account.update({
      where: {id: toId},
      data: {balance: {increment: amount}},
    });
  });
}

// Sequential
await this.prisma.$transaction([
  this.prisma.user.create({data: userData}),
  this.prisma.log.create({data: logData}),
]);

TypeORM 통합

설치

npm i @nestjs/typeorm typeorm pg

Module 등록

// app.module.ts

@Module({
  imports: [
    TypeOrmModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        host: config.get('DB_HOST'),
        port: config.get('DB_PORT'),
        username: config.get('DB_USERNAME'),
        password: config.get('DB_PASSWORD'),
        database: config.get('DB_NAME'),
        entities: [User, Post],
        synchronize: false,   // 프로덕션 false, dev 만 true
        migrations: ['dist/migrations/*.js'],
        migrationsRun: true,
      }),
    }),
    UsersModule,
  ],
})
export class AppModule {}

Entity


@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({unique: true})
  email: string;

  @Column()
  name: string;

  @OneToMany(() => Post, post => post.author)
  posts: Post[];

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

Repository

// users.module.ts
@Module({
  imports: [TypeOrmModule.forFeature([User])],
  providers: [UsersService],
  controllers: [UsersController],
})
export class UsersModule {}

// users.service.ts
@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User) private usersRepo: Repository<User>,
  ) {}

  async findAll(): Promise<User[]> {
    return this.usersRepo.find({relations: {posts: true}});
  }

  async findOne(id: number): Promise<User | null> {
    return this.usersRepo.findOne({where: {id}});
  }

  async create(dto: CreateUserDto): Promise<User> {
    const user = this.usersRepo.create(dto);
    return this.usersRepo.save(user);
  }
}

QueryBuilder

const users = await this.usersRepo
  .createQueryBuilder('u')
  .leftJoinAndSelect('u.posts', 'p')
  .where('u.email LIKE :email', {email: '%example.com'})
  .andWhere('u.createdAt > :date', {date: since})
  .orderBy('u.createdAt', 'DESC')
  .take(10)
  .getMany();

Migration

# 생성
npm run typeorm migration:generate -- -d src/data-source.ts src/migrations/InitSchema

# 실행
npm run typeorm migration:run -- -d src/data-source.ts

# 롤백
npm run typeorm migration:revert -- -d src/data-source.ts

Mongoose (MongoDB)

설치

npm i @nestjs/mongoose mongoose

Schema



@Schema({timestamps: true})
export class User {
  @Prop({required: true, unique: true})
  email: string;

  @Prop({required: true})
  name: string;

  @Prop()
  bio?: string;

  @Prop([{type: Types.ObjectId, ref: 'Post'}])
  posts: Types.ObjectId[];
}

export type UserDocument = User & Document;
export const UserSchema = SchemaFactory.createForClass(User);

Module

@Module({
  imports: [
    MongooseModule.forRoot('mongodb://localhost/nest'),
    MongooseModule.forFeature([{name: User.name, schema: UserSchema}]),
  ],
})
export class UsersModule {}

Service

@Injectable()
export class UsersService {
  constructor(
    @InjectModel(User.name) private userModel: Model<UserDocument>,
  ) {}

  async findAll(): Promise<User[]> {
    return this.userModel.find().populate('posts').exec();
  }

  async create(dto: CreateUserDto): Promise<User> {
    return this.userModel.create(dto);
  }
}

Drizzle (경량 TS)

설치

npm i drizzle-orm postgres
npm i -D drizzle-kit

Schema


export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: varchar('email', {length: 256}).notNull().unique(),
  name: varchar('name', {length: 100}).notNull(),
  createdAt: timestamp('created_at').defaultNow(),
});

export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;

Provider



@Module({
  providers: [
    {
      provide: 'DRIZZLE',
      useFactory: () => {
        const client = postgres(process.env.DATABASE_URL);
        return drizzle(client);
      },
    },
  ],
  exports: ['DRIZZLE'],
})
export class DatabaseModule {}

Service

@Injectable()
export class UsersService {
  constructor(@Inject('DRIZZLE') private db: any) {}

  async findAll() {
    return this.db.select().from(users);
  }

  async create(data: NewUser) {
    return this.db.insert(users).values(data).returning();
  }
}

Connection Pool

프로덕션은 pool 설정 필수:

// Prisma
new PrismaClient({
  datasources: {db: {url: `${databaseUrl}?connection_limit=10&pool_timeout=20`}},
})

// TypeORM
{
  ...
  extra: {
    max: 10,
    idleTimeoutMillis: 30000,
  },
}

트랜잭션 패턴

Prisma

async createUserWithPosts(dto: CreateUserWithPostsDto) {
  return this.prisma.$transaction(async (tx) => {
    const user = await tx.user.create({data: {email: dto.email, name: dto.name}});
    for (const postData of dto.posts) {
      await tx.post.create({data: {...postData, authorId: user.id}});
    }
    return user;
  });
}

TypeORM (DataSource)

async createWithTransaction() {
  return this.dataSource.transaction(async (manager) => {
    const user = await manager.save(User, {...});
    await manager.save(Post, [...]);
    return user;
  });
}

`nestjs-cls` + AsyncLocalStorage (transaction propagation)

여러 service 를 하나의 트랜잭션으로 묶기 어려운 경우 nestjs-cls + Prisma extension 또는 TypeORM QueryRunner 로 request-scoped session.

Health Check

@nestjs/terminus + DB indicator:

@Get('health')
@HealthCheck()
check() {
  return this.health.check([
    () => this.db.pingCheck('database'),
    () => this.mongoose.pingCheck('mongo'),
  ]);
}

함정

[!WARNING] synchronize: true 를 프로덕션에. DB 스키마 자동 변경. 데이터 손실 위험. 마이그레이션 강제.

[!CAUTION] N+1 query. Prisma include, TypeORM relations, Mongoose populate 로 해결. 안 하면 lazy load 로 요청당 수십 query.

[!WARNING] 트랜잭션 안에서 외부 API 호출 금지. DB lock 유지 시간 늘어남.

[!IMPORTANT] Prisma binary target. Docker 이미지가 alpine 이면 binaryTargets = ["linux-musl"] 필요.

[!CAUTION] Migration timing. Deploy 전 migration 실행. Blue/green 시에는 forward-compatible schema.

[NestJS] Deployment (Docker, Kubernetes, PM2)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Deployment 는 프로덕션 환경에서 앱을 배포/운영하기 위한 절차입니다. Docker 이미지 빌드, Kubernetes 매니페스트, PM2 프로세스 관리, graceful shutdown, health check, 로깅, 관측 도구를 포함합니다.

Build

# 프로덕션 빌드
npm run build     # nest build

# dist/ 에 컴파일된 JS
node dist/main.js

nest-cli.json:

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true,
    "webpack": false          // SWC (또는 esbuild) 옵션
  }
}

SWC / esbuild (빠른 빌드)

npm i -D @swc/cli @swc/core

nest-cli.json:

{
  "compilerOptions": {
    "builder": "swc",
    "typeCheck": true
  }
}

주의: SWC 는 emitDecoratorMetadata 지원. class-validator 는 여전히 작동.

Dockerfile (multi-stage)

# --- builder ---
FROM node:20-alpine AS builder
WORKDIR /app

# Dependency cache
COPY package*.json ./
RUN npm ci

# Build
COPY . .
RUN npm run build

# Prisma (있으면)
RUN npx prisma generate

# 프로덕션 의존성만
RUN npm ci --omit=dev && npm cache clean --force

# --- runtime ---
FROM node:20-alpine
WORKDIR /app

# non-root user
RUN addgroup -g 1001 -S app && adduser -S app -u 1001

COPY --from=builder --chown=app:app /app/node_modules ./node_modules
COPY --from=builder --chown=app:app /app/dist ./dist
COPY --from=builder --chown=app:app /app/package.json ./
# Prisma
COPY --from=builder --chown=app:app /app/prisma ./prisma

USER app

EXPOSE 3000

# Graceful shutdown
CMD ["node", "dist/main"]

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=30s \
  CMD wget --spider -q http://localhost:3000/health || exit 1

`.dockerignore`

node_modules
dist
.git
.env
.env.*
*.md
test
coverage
.vscode
.idea

Graceful Shutdown

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

  // Shutdown hooks 활성화
  app.enableShutdownHooks();

  await app.listen(3000);
}
bootstrap();

Provider 에서 OnApplicationShutdown 구현:

@Injectable()
export class DatabaseService implements OnApplicationShutdown {
  async onApplicationShutdown(signal?: string) {
    console.log(`Shutting down: ${signal}`);
    await this.prisma.$disconnect();
  }
}

동작: SIGTERM 수신 -> 새 요청 accept 중지 -> in-flight 요청 완료 -> shutdown hook 실행 -> 프로세스 종료.

Health Check

@nestjs/terminus + @nestjs/health-check:

npm i @nestjs/terminus

// health.controller.ts



@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private http: HttpHealthIndicator,
    private memory: MemoryHealthIndicator,
    private prisma: PrismaHealthIndicator,
  ) {}

  @Get('live')
  @HealthCheck()
  liveness() {
    return this.health.check([
      () => this.memory.checkHeap('memory_heap', 250 * 1024 * 1024),
    ]);
  }

  @Get('ready')
  @HealthCheck()
  readiness() {
    return this.health.check([
      () => this.prisma.isHealthy('database'),
      () => this.http.pingCheck('external_api', 'https://external-api/health'),
    ]);
  }
}

Kubernetes probe

livenessProbe: 앱 살아있는가 (fail 시 재시작)
readinessProbe: 트래픽 받을 준비 (fail 시 LB 에서 제외)
startupProbe: 초기 부팅 (긴 초기화)

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels: {app: myapp}
  template:
    metadata:
      labels: {app: myapp}
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: app
          image: myrepo/myapp:v1.2.3
          ports: [{containerPort: 3000}]
          env:
            - name: NODE_ENV
              value: production
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef: {name: myapp-secrets, key: db-url}
            - name: JWT_SECRET
              valueFrom:
                secretKeyRef: {name: myapp-secrets, key: jwt-secret}
          resources:
            requests: {cpu: 250m, memory: 256Mi}
            limits: {cpu: 1, memory: 1Gi}
          livenessProbe:
            httpGet: {path: /health/live, port: 3000}
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet: {path: /health/ready, port: 3000}
            periodSeconds: 5
          startupProbe:
            httpGet: {path: /health/live, port: 3000}
            failureThreshold: 30
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                command: ["sleep", "5"]   # LB 제외 대기
---
apiVersion: v1
kind: Service
metadata:
  name: myapp
spec:
  selector: {app: myapp}
  ports:
    - port: 80
      targetPort: 3000
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: nginx
  tls:
    - hosts: [api.example.com]
      secretName: myapp-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service: {name: myapp, port: {number: 80}}

HPA

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60

PM2 (Node 프로세스 관리자)

VM 배포 시 사용. Kubernetes 는 kubelet 이 그 역할.

npm i -g pm2

pm2 start dist/main.js --name myapp -i max   # max = CPU 개수
pm2 status
pm2 logs myapp
pm2 reload myapp   # zero-downtime reload
pm2 stop myapp
pm2 startup       # systemd 등록
pm2 save          # 재부팅 시 복원

ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'myapp',
    script: 'dist/main.js',
    instances: 'max',
    exec_mode: 'cluster',
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000,
    },
    max_memory_restart: '1G',
    kill_timeout: 30000,
    listen_timeout: 10000,
    error_file: '/var/log/myapp/error.log',
    out_file: '/var/log/myapp/out.log',
  }],
};

로깅 (JSON, structured)

NestJS 11 native JSON logger

// main.ts

const app = await NestFactory.create(AppModule, {
  logger: new ConsoleLogger({
    json: true,
    logLevels: ['error', 'warn', 'log'],
  }),
});

nestjs-pino (권장)

npm i nestjs-pino pino-http


@Module({
  imports: [
    LoggerModule.forRoot({
      pinoHttp: {
        level: process.env.LOG_LEVEL || 'info',
        transport: process.env.NODE_ENV === 'development'
          ? { target: 'pino-pretty' }
          : undefined,
        redact: ['req.headers.authorization'],
      },
    }),
  ],
})
export class AppModule {}

main.ts:

const app = await NestFactory.create(AppModule, {bufferLogs: true});
app.useLogger(app.get(Logger));

OpenTelemetry

npm i @opentelemetry/api @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http

// tracing.ts



const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

main.ts 최상단에 import './tracing'; (다른 import 보다 먼저).

Sentry

npm i @sentry/node


Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV,
  tracesSampleRate: 0.1,
});

// AllExceptionsFilter 안에서
Sentry.captureException(exception);

Database Migration

Prisma

# 배포 파이프라인에서
npx prisma migrate deploy

TypeORM

npm run typeorm migration:run

Kubernetes init container

initContainers:
  - name: migrate
    image: myrepo/myapp:v1.2.3
    command: ['npx', 'prisma', 'migrate', 'deploy']
    env:
      - name: DATABASE_URL
        valueFrom:
          secretKeyRef: {name: myapp-secrets, key: db-url}
containers:
  - name: app
    ...

CI/CD 예시 (GitHub Actions)

name: deploy
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build & push
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: |
            ghcr.io/myorg/myapp:${{ github.sha }}
            ghcr.io/myorg/myapp:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: azure/setup-kubectl@v3
      - uses: azure/k8s-set-context@v3
        with:
          method: kubeconfig
          kubeconfig: ${{ secrets.KUBECONFIG }}
      - run: |
          kubectl set image deployment/myapp app=ghcr.io/myorg/myapp:${{ github.sha }}
          kubectl rollout status deployment/myapp --timeout=5m

함정

[!WARNING] enableShutdownHooks() 안 부르면 SIGTERM 무시. docker stop 이 SIGKILL 로 강제 종료 -> in-flight 요청 손실.

[!CAUTION] PM2 는 이미 K8s 컨테이너 안에는 불필요. kubelet 이 프로세스 관리. PM2 는 VM 배포용.

[!WARNING] 환경변수 secret 을 이미지에 굽지 마세요. 항상 runtime injection.

[!IMPORTANT] terminationGracePeriodSeconds > shutdown hook 완료 시간. K8s 가 강제 종료하기 전에 정리.

[!CAUTION] Prisma binary target. Alpine + linux-musl 명시 필요. 안 그러면 런타임 오류.

[NestJS] Exception Filters

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Exception Filter 는 애플리케이션에서 발생한 예외를 catch 하여 클라이언트에게 응답 형식을 통일합니다. @Catch() 데코레이터로 어떤 예외를 처리할지 지정합니다. 처리 안 된 예외는 built-in filter 가 500 응답으로 처리하지만, 커스텀 filter 로 로깅, 형식 변환, exception mapping 을 구현합니다.

Built-in Exceptions

import {
  BadRequestException,          // 400
  UnauthorizedException,        // 401
  NotFoundException,             // 404
  ForbiddenException,            // 403
  NotAcceptableException,        // 406
  RequestTimeoutException,       // 408
  ConflictException,             // 409
  GoneException,                 // 410
  PayloadTooLargeException,      // 413
  UnsupportedMediaTypeException, // 415
  UnprocessableEntityException,  // 422
  InternalServerErrorException,  // 500
  NotImplementedException,       // 501
  BadGatewayException,           // 502
  ServiceUnavailableException,   // 503
  GatewayTimeoutException,       // 504
} from '@nestjs/common';

throw new NotFoundException('User not found');
throw new BadRequestException({
  message: 'Invalid input',
  code: 'INVALID_INPUT',
  details: {field: 'email'},
});

Nest 는 이를 다음과 같이 응답:

{
  "statusCode": 404,
  "message": "User not found",
  "error": "Not Found"
}

Custom Exception Filter



@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const res = ctx.getResponse<Response>();
    const req = ctx.getRequest<Request>();
    const status = exception.getStatus();
    const message = exception.getResponse();

    res.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: req.url,
      message: typeof message === 'string' ? message : (message as any).message,
    });
  }
}

`@Catch()` 인자

@Catch()                          // 모든 예외
@Catch(HttpException)             // HttpException 만
@Catch(BadRequestException, NotFoundException)   // 여러 개
@Catch(PrismaClientKnownRequestError)   // 외부 예외

부착 방법

Method / Controller

@Get()
@UseFilters(HttpExceptionFilter)
find() { ... }

@Controller('users')
@UseFilters(HttpExceptionFilter)
export class UsersController { ... }

Global

// main.ts
app.useGlobalFilters(new HttpExceptionFilter());

// 또는 module (DI 지원)

@Module({
  providers: [
    { provide: APP_FILTER, useClass: HttpExceptionFilter },
  ],
})
export class AppModule {}

All Exceptions Filter

가장 넓은 catch. 마지막 방어선.


@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  private readonly logger = new Logger('AllExceptionsFilter');

  catch(exception: unknown, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const res = ctx.getResponse();
    const req = ctx.getRequest();

    const status = exception instanceof HttpException
      ? exception.getStatus()
      : HttpStatus.INTERNAL_SERVER_ERROR;

    const message = exception instanceof HttpException
      ? exception.getResponse()
      : (exception as Error)?.message || 'Internal server error';

    this.logger.error({
      message,
      stack: (exception as Error)?.stack,
      path: req.url,
      method: req.method,
    });

    res.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: req.url,
      message,
    });
  }
}

Filter 순서

여러 filter 를 사용 시:

@Catch(SpecificException) 이 먼저
@Catch() 는 fallback

@Controller()
@UseFilters(BusinessLogicFilter, HttpExceptionFilter, AllExceptionsFilter)

주의: 실제 실행은 스택 형태. 위에서부터 매칭.

Business Exception 패턴

도메인 특화 예외를 정의하고 filter 에서 매핑.

// domain/exceptions/user-already-exists.exception.ts
export class UserAlreadyExistsError extends Error {
  constructor(email: string) {
    super(`User with email ${email} already exists`);
    this.name = 'UserAlreadyExistsError';
  }
}

// business.filter.ts
@Catch(UserAlreadyExistsError)
export class UserAlreadyExistsFilter implements ExceptionFilter {
  catch(exception: UserAlreadyExistsError, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse();
    res.status(409).json({
      statusCode: 409,
      error: 'CONFLICT',
      code: 'USER_ALREADY_EXISTS',
      message: exception.message,
    });
  }
}

Prisma / TypeORM 예외 매핑

Prisma



@Catch(PrismaClientKnownRequestError)
export class PrismaExceptionFilter implements ExceptionFilter {
  catch(exception: PrismaClientKnownRequestError, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse();

    let status = HttpStatus.INTERNAL_SERVER_ERROR;
    let message = 'Database error';

    switch (exception.code) {
      case 'P2002':   // Unique constraint
        status = HttpStatus.CONFLICT;
        message = 'Resource already exists';
        break;
      case 'P2025':   // Not found
        status = HttpStatus.NOT_FOUND;
        message = 'Resource not found';
        break;
      case 'P2003':   // Foreign key
        status = HttpStatus.BAD_REQUEST;
        message = 'Foreign key constraint failed';
        break;
    }

    res.status(status).json({
      statusCode: status,
      code: exception.code,
      message,
    });
  }
}

TypeORM


@Catch(QueryFailedError)
export class QueryFailedFilter implements ExceptionFilter {
  catch(exception: QueryFailedError, host: ArgumentsHost) {
    // ...
  }
}

Filter + Logging + Sentry


@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  private readonly logger = new Logger('AllExceptionsFilter');

  catch(exception: unknown, host: ArgumentsHost) {
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : HttpStatus.INTERNAL_SERVER_ERROR;

    if (status >= 500) {
      Sentry.captureException(exception);
      this.logger.error(exception);
    }

    // ...respond
  }
}

WebSocket / GraphQL / RPC

ArgumentsHost 로 컨텍스트 전환:

@Catch()
export class WsExceptionFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const type = host.getType();

    if (type === 'ws') {
      const client = host.switchToWs().getClient();
      client.emit('error', {message: (exception as Error).message});
    } else if (type === 'http') {
      // HTTP 응답
    }
  }
}

v11: Intrinsic Exception

NestJS 11 에서 도입. 시스템 예외를 표시:

throw new IntrinsicException('Internal error');

내부 오류를 사용자에 노출 X 계층 분리.

Validation Filter (예외 응답 형식 커스텀)


class ValidationException extends HttpException {
  constructor(errors: ValidationError[]) {
    super({
      statusCode: HttpStatus.UNPROCESSABLE_ENTITY,
      error: 'Validation Failed',
      errors: flatten(errors),
    }, HttpStatus.UNPROCESSABLE_ENTITY);
  }
}

// main.ts
app.useGlobalPipes(new ValidationPipe({
  exceptionFactory: (errors) => new ValidationException(errors),
}));

함정

[!WARNING] @Catch() (empty) + 다른 filter 순서. Empty catch 가 먼저 오면 모든 예외 잡아서 다른 filter 실행 안 됨.

[!CAUTION] throw 대신 return error object 하지 마세요. NestJS 는 exception 기반. Return 은 200 처리.

[!WARNING] Async filter 실수. catch 는 sync 인 것처럼 보이지만 async 가능. Await 로 처리.

[!IMPORTANT] Global filter 는 DI 필요 시 APP_FILTER provider. useGlobalFilters() 는 DI 없음.

[!CAUTION] 에러 상세를 클라이언트에 노출 위험. Stack trace, DB error message 등 감출 것.

[NestJS] Guards

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Guard 는 특정 요청이 controller method 에 도달하기 전에 실행되어 접근 허용 여부 를 결정합니다. Middleware 이후, Interceptor / Pipe 이전에 실행되며, canActivate() 가 true 를 반환해야 통과합니다. 주로 인증 (authentication) 과 인가 (authorization) 에 사용.

기본 구조



@Injectable()
export class MyGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    return validateRequest(request);
  }
}

ExecutionContext 는 HTTP/WebSocket/RPC 등 모든 프로토콜 통합.

AuthGuard 예제 (JWT)



@Injectable()
export class JwtAuthGuard implements CanActivate {
  constructor(private jwtService: JwtService) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const req = context.switchToHttp().getRequest();
    const token = this.extractToken(req);
    if (!token) throw new UnauthorizedException('Missing token');

    try {
      const payload = await this.jwtService.verifyAsync(token, {
        secret: process.env.JWT_SECRET,
      });
      req.user = payload;
      return true;
    } catch {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractToken(req: any): string | undefined {
    const [type, token] = req.headers.authorization?.split(' ') ?? [];
    return type === 'Bearer' ? token : undefined;
  }
}

부착 방법

Method 단위

@Controller('users')
export class UsersController {
  @Get('me')
  @UseGuards(JwtAuthGuard)
  me(@Req() req) {
    return req.user;
  }
}

Controller 전체

@Controller('users')
@UseGuards(JwtAuthGuard)
export class UsersController {
  @Get('me') me() { ... }
  @Get(':id') find() { ... }
}

Global

// main.ts
const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new JwtAuthGuard(app.get(JwtService)));

Global 은 DI 어려움. Module 로 등록하는 편이 관용:

// app.module.ts

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: JwtAuthGuard,
    },
  ],
})
export class AppModule {}

Public Endpoint (Guard 우회)

Global guard 를 걸면 모든 route 에 적용. 예외 (로그인, 헬스체크) 처리는 metadata + Reflector.

// common/decorators/public.decorator.ts

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

Guard 에서 확인:


@Injectable()
export class JwtAuthGuard implements CanActivate {
  constructor(
    private reflector: Reflector,
    private jwtService: JwtService,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (isPublic) return true;

    // 인증 로직 ...
  }
}

사용:

@Post('login')
@Public()
login(@Body() dto: LoginDto) { ... }

Roles Guard (인가)

Role 기반 접근 제어.

// roles.decorator.ts

export const ROLES_KEY = 'roles';
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);

// roles.guard.ts
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.getAllAndOverride<string[]>(
      ROLES_KEY,
      [context.getHandler(), context.getClass()],
    );
    if (!requiredRoles) return true;

    const { user } = context.switchToHttp().getRequest();
    return requiredRoles.some((role) => user.roles?.includes(role));
  }
}

사용:

@Controller('admin')
@UseGuards(JwtAuthGuard, RolesGuard)   // 순서 중요: JWT 먼저 -> role 확인
export class AdminController {
  @Get('users')
  @Roles('admin', 'moderator')
  listUsers() { ... }
}

Passport 통합 (`@nestjs/passport`)

Passport strategy 를 NestJS Guard 로 wrapping.

npm i @nestjs/passport passport passport-jwt
npm i @types/passport-jwt -D

JWT Strategy




@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor() {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      secretOrKey: process.env.JWT_SECRET,
    });
  }

  async validate(payload: any) {
    return { userId: payload.sub, email: payload.email };
  }
}

Guard


@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}

Module

@Module({
  imports: [
    PassportModule,
    JwtModule.register({
      secret: process.env.JWT_SECRET,
      signOptions: { expiresIn: '1h' },
    }),
  ],
  providers: [JwtStrategy, AuthService],
  exports: [AuthService, JwtModule],
})
export class AuthModule {}

Local Strategy (username + password)


@Injectable()
export class LocalStrategy extends PassportStrategy(Strategy) {
  constructor(private authService: AuthService) {
    super({ usernameField: 'email' });
  }

  async validate(email: string, password: string): Promise<any> {
    const user = await this.authService.validateUser(email, password);
    if (!user) throw new UnauthorizedException();
    return user;
  }
}

@Injectable()
export class LocalAuthGuard extends AuthGuard('local') {}

// 사용
@Post('login')
@UseGuards(LocalAuthGuard)
async login(@Req() req) {
  return this.authService.login(req.user);
}

Async Guard

async canActivate(context: ExecutionContext): Promise<boolean> {
  const req = context.switchToHttp().getRequest();
  const user = await this.userService.verifyToken(req.headers.token);
  req.user = user;
  return Boolean(user);
}

Guard 실행 순서

여러 guard 를 부착하면 순서대로 AND:

@UseGuards(JwtAuthGuard, RolesGuard, ThrottleGuard)

JwtAuth false -> 즉시 401 (다음 guard 실행 X)
모두 true -> 통과

Guard 에서 예외 던지기

기본:

if (!allowed) throw new UnauthorizedException('Reason');

canActivate 가 false 리턴하면 자동 ForbiddenException. 명시적 예외를 던지는 편이 메시지 커스텀 가능.

WebSocket / RPC Guard

같은 인터페이스, context.switchToWs() / context.switchToRpc():

canActivate(context: ExecutionContext): boolean {
  if (context.getType() === 'ws') {
    const client = context.switchToWs().getClient();
    return client.handshake.auth.token === 'valid';
  }
  const req = context.switchToHttp().getRequest();
  return req.headers.authorization === 'valid';
}

Rate Limit Guard

@nestjs/throttler 사용:


@Module({
  imports: [
    ThrottlerModule.forRoot([{
      ttl: 60000,
      limit: 100,
    }]),
  ],
  providers: [
    { provide: APP_GUARD, useClass: ThrottlerGuard },
  ],
})
export class AppModule {}

Endpoint 별 커스터마이제이션:

@Throttle({ default: { limit: 3, ttl: 60000 } })
@Post('login')
login() { ... }

@SkipThrottle()
@Get('health')
health() { ... }

함정

[!WARNING] Guard 순서. Auth guard 를 먼저, role guard 를 나중에. JWT 없이 role 확인 못 함.

[!CAUTION] Global guard + DI. useGlobalGuards() 는 DI 없이 인스턴스. Module 에서 APP_GUARD 로 등록해야 DI 가능.

[!WARNING] @Public() 데코레이터 안 붙이면 로그인 endpoint 도 인증 요구 -> chicken-and-egg.

[!IMPORTANT] Reflector.getAllAndOverride 는 method + class 순으로. Method decorator 가 class decorator override.

[!CAUTION] Guard 에서 async 는 성능 영향. DB 조회 등 무거우면 캐시 (Redis) 고려.

[NestJS] Interceptors

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Interceptor 는 요청 처리 전/후에 로직을 삽입하는 클래스입니다. AOP (Aspect-Oriented Programming) 패턴의 구현체로, 로깅, 캐싱, 응답 변환, 예외 매핑, RxJS operator 활용 등에 사용합니다.

기본 구조




@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const start = Date.now();
    return next.handle().pipe(
      tap(() => console.log(`Duration: ${Date.now() - start}ms`)),
    );
  }
}

intercept(context, next): 요청 처리 전 로직
next.handle(): 실제 route handler (Observable 반환)
RxJS operators (tap, map, catchError, timeout) 로 파이프라인 구성

부착 방법

Method

@Get()
@UseInterceptors(LoggingInterceptor)
findAll() { ... }

Controller

@Controller('users')
@UseInterceptors(LoggingInterceptor)
export class UsersController { ... }

Global

// main.ts
app.useGlobalInterceptors(new LoggingInterceptor());

// 또는 module (DI 지원)

@Module({
  providers: [
    { provide: APP_INTERCEPTOR, useClass: LoggingInterceptor },
  ],
})
export class AppModule {}

주요 사용 사례

1. Logging

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger('LoggingInterceptor');

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const req = context.switchToHttp().getRequest();
    const {method, url} = req;
    const start = Date.now();

    this.logger.log(`${method} ${url}`);

    return next.handle().pipe(
      tap({
        next: () => {
          const duration = Date.now() - start;
          this.logger.log(`${method} ${url} ${duration}ms`);
        },
        error: (err) => {
          const duration = Date.now() - start;
          this.logger.error(`${method} ${url} ${duration}ms - ${err.message}`);
        },
      }),
    );
  }
}

2. Response Transformation

응답을 일관된 wrapper 형식으로:

interface Response<T> {
  data: T;
  timestamp: string;
  path: string;
}

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
    const req = context.switchToHttp().getRequest();
    return next.handle().pipe(
      map(data => ({
        data,
        timestamp: new Date().toISOString(),
        path: req.url,
      })),
    );
  }
}

3. Cache

@Injectable()
export class CacheInterceptor implements NestInterceptor {
  constructor(
    @Inject(CACHE_MANAGER) private cache: Cache,
  ) {}

  async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
    const req = context.switchToHttp().getRequest();
    const key = `${req.method}:${req.url}`;

    const cached = await this.cache.get(key);
    if (cached) return of(cached);

    return next.handle().pipe(
      tap(async (data) => {
        await this.cache.set(key, data, 60);
      }),
    );
  }
}

@nestjs/cache-manager 의 내장 CacheInterceptor 활용 관용.

4. Timeout



@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      timeout(5000),
      catchError(err => {
        if (err instanceof TimeoutError) {
          return throwError(() => new RequestTimeoutException());
        }
        return throwError(() => err);
      }),
    );
  }
}

5. Class Serialization

ClassSerializerInterceptor (내장) 는 @Exclude(), @Expose() 데코레이터 기반 응답 필터.


export class UserEntity {
  id: number;
  email: string;

  @Exclude()
  password: string;

  @Expose({groups: ['admin']})
  role: string;

  constructor(partial: Partial<UserEntity>) {
    Object.assign(this, partial);
  }
}

@Controller('users')
@UseInterceptors(ClassSerializerInterceptor)
export class UsersController {
  @Get(':id')
  async findOne(@Param('id') id: string) {
    return new UserEntity(await this.service.findOne(id));
    // password 자동 제외
  }
}

6. Exception Mapping

@Injectable()
export class ExceptionMapInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      catchError(err => {
        if (err instanceof PrismaClientKnownRequestError) {
          if (err.code === 'P2002') {
            return throwError(() => new ConflictException('Duplicate entry'));
          }
          if (err.code === 'P2025') {
            return throwError(() => new NotFoundException('Not found'));
          }
        }
        return throwError(() => err);
      }),
    );
  }
}

Interceptor 순서

여러 개는 nested 실행:

@UseInterceptors(A, B, C)

요청: A -> B -> C -> handler
응답: handler -> C -> B -> A

tap 등 side effect 순서 주의.

Async Interceptor

async intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>> {
  const user = await this.userService.findByToken(...);
  return next.handle();
}

Promise 도 리턴 가능. Nest 가 자동 unwrap.

Global 등록 순서

Guards -> Interceptors (before) -> Pipes -> Handler -> Interceptors (after) -> Exception Filters

Guards 가 먼저 실행. Interceptor 는 next.handle() 전후로 감쌈.

실전 조합

API 응답 통일 + 로깅 + timeout

// main.ts
app.useGlobalInterceptors(
  new LoggingInterceptor(),
  new TimeoutInterceptor(),
  new TransformInterceptor(),
);

또는 module 로:

@Module({
  providers: [
    { provide: APP_INTERCEPTOR, useClass: LoggingInterceptor },
    { provide: APP_INTERCEPTOR, useClass: TimeoutInterceptor },
    { provide: APP_INTERCEPTOR, useClass: TransformInterceptor },
  ],
})
export class AppModule {}

함정

[!WARNING] ClassSerializerInterceptor + Fastify. Fastify 는 기본 JSON.stringify 성능이 매우 빠른데, class-transformer 를 거치면 오히려 느려질 수 있음. 벤치마크.

[!CAUTION] Interceptor 안에서 응답 조작. map() 으로 새 객체 반환 필수. 원본 mutate 는 side effect.

[!WARNING] @Res() 사용 endpoint 에는 interceptor after 로직 안 실행. passthrough: true 로 우회 가능.

[!IMPORTANT] Global interceptor 에서 특정 route 우회. Reflector + custom decorator (@SkipInterceptor()) 로.

[!CAUTION] RxJS 학습 부담. tap, map, catchError, throwError 는 기본. 복잡한 파이프는 이해하기 어려움.

[NestJS] Microservices (Kafka, NATS, RabbitMQ, gRPC, TCP)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Microservices 는 HTTP 대신 message broker (Kafka, RabbitMQ, NATS, Redis) 나 gRPC / TCP 로 통신하는 서비스를 같은 프로그래밍 모델로 작성하는 기능입니다. Controller 대신 Message pattern handler 를 정의하고, ClientProxy 로 다른 서비스에 요청합니다.

지원 Transport

TCP (기본): 단순 socket
Redis (pub/sub): 이벤트 유연
NATS: 가벼움, cloud native
MQTT: IoT
RabbitMQ (AMQP): 성숙, queue + routing
Kafka: 이벤트 스트리밍, 대규모
gRPC: HTTP/2 + Protocol Buffers, RPC
Custom: 자체 구현

Microservice 앱 생성

// main.ts



async function bootstrap() {
  const app = await NestFactory.createMicroservice(AppModule, {
    transport: Transport.KAFKA,
    options: {
      client: {
        brokers: ['localhost:9092'],
        clientId: 'my-service',
      },
      consumer: {
        groupId: 'my-consumer-group',
      },
    },
  });
  await app.listen();
}
bootstrap();

Hybrid (HTTP + Microservice)

한 앱이 HTTP 도 서빙:

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.connectMicroservice({
    transport: Transport.KAFKA,
    options: {...},
  });

  await app.startAllMicroservices();
  await app.listen(3000);   // HTTP
}

Message Pattern (Request-Response)

Controller 에서:



@Controller()
export class UsersController {
  @MessagePattern({cmd: 'get_user'})
  async getUser(@Payload() data: {id: number}) {
    return this.usersService.findOne(data.id);
  }

  @MessagePattern({cmd: 'create_user'})
  async createUser(@Payload() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}

Broker 에서 {cmd: 'get_user'} 패턴 매칭.

Event Pattern (Fire-and-forget)

응답 없음, side effect 만:

@EventPattern('user_created')
async handleUserCreated(@Payload() data: UserCreatedEvent) {
  await this.emailService.sendWelcome(data.email);
}

Client (다른 서비스 호출)

Module


@Module({
  imports: [
    ClientsModule.register([
      {
        name: 'USERS_SERVICE',
        transport: Transport.KAFKA,
        options: {
          client: {brokers: ['localhost:9092']},
          consumer: {groupId: 'orders-consumer'},
        },
      },
    ]),
  ],
})
export class OrdersModule {}

사용


@Injectable()
export class OrdersService {
  constructor(
    @Inject('USERS_SERVICE') private usersClient: ClientKafka,
  ) {}

  async onModuleInit() {
    // Kafka 는 subscribe 명시적으로
    this.usersClient.subscribeToResponseOf('get_user');
    await this.usersClient.connect();
  }

  async getUser(id: number) {
    // Request-response (RxJS Observable 반환)
    return this.usersClient.send({cmd: 'get_user'}, {id}).toPromise();
  }

  async notifyUserCreated(user: User) {
    // Event (fire-and-forget)
    this.usersClient.emit('user_created', user);
  }
}

Kafka 심화

Producer 설정

{
  transport: Transport.KAFKA,
  options: {
    client: {
      brokers: ['localhost:9092'],
      clientId: 'producer-1',
    },
    producer: {
      allowAutoTopicCreation: true,
      transactionalId: 'my-txn',   // exactly-once
    },
    consumer: {
      groupId: 'my-group',
      allowAutoTopicCreation: true,
      sessionTimeout: 30000,
      heartbeatInterval: 3000,
    },
    subscribe: {
      fromBeginning: false,
    },
  },
}

커스텀 partition

this.kafka.emit('user_created', {
  key: user.id.toString(),   // partition key
  value: user,
  headers: {'x-source': 'nest'},
});

Exactly-once

Producer 트랜잭션 + consumer offset commit 관리. 자세한 것은 Kafka 문서.

RabbitMQ 심화

설정

{
  transport: Transport.RMQ,
  options: {
    urls: ['amqp://localhost:5672'],
    queue: 'user_queue',
    queueOptions: {
      durable: true,
    },
    noAck: false,        // manual ack
    prefetchCount: 10,   // per-worker
  },
}

Manual Ack

@MessagePattern('process_order')
async processOrder(@Payload() data: any, @Ctx() ctx: RmqContext) {
  const channel = ctx.getChannelRef();
  const originalMsg = ctx.getMessage();

  try {
    await this.processInternal(data);
    channel.ack(originalMsg);
  } catch (error) {
    channel.nack(originalMsg, false, false);   // DLQ 로 (false = requeue X)
  }
}

Dead Letter Exchange

queueOptions: {
  durable: true,
  arguments: {
    'x-dead-letter-exchange': 'dlx',
    'x-dead-letter-routing-key': 'user_dlq',
    'x-message-ttl': 60000,
  },
}

gRPC

Proto 파일

// users.proto
syntax = "proto3";
package users;

service UsersService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc StreamUsers (Empty) returns (stream User);
}

message GetUserRequest {
  int32 id = 1;
}

message User {
  int32 id = 1;
  string email = 2;
  string name = 3;
}

message Empty {}

Server

// main.ts
const app = await NestFactory.createMicroservice<MicroserviceOptions>(
  AppModule,
  {
    transport: Transport.GRPC,
    options: {
      package: 'users',
      protoPath: join(__dirname, 'users.proto'),
      url: '0.0.0.0:5000',
    },
  },
);
await app.listen();

Controller



@Controller()
export class UsersController {
  @GrpcMethod('UsersService', 'GetUser')
  async getUser(data: {id: number}): Promise<User> {
    return this.usersService.findOne(data.id);
  }

  @GrpcStreamMethod('UsersService', 'StreamUsers')
  streamUsers(): Observable<User> {
    return this.usersService.stream();
  }
}

Client


@Injectable()
export class OrdersService implements OnModuleInit {
  private usersService: UsersServiceClient;

  constructor(@Inject('USERS_PACKAGE') private client: ClientGrpc) {}

  onModuleInit() {
    this.usersService = this.client.getService<UsersServiceClient>('UsersService');
  }

  async getUser(id: number) {
    return firstValueFrom(this.usersService.getUser({id}));
  }
}

Message Serialization

기본 JSON. Custom serializer / deserializer:

class CustomSerializer implements Serializer {
  serialize(value: any): any {
    return {data: value, timestamp: Date.now()};
  }
}

Retry / DLQ

프레임워크 레벨 지원 제한적. Consumer 코드에서:

@MessagePattern('process')
async process(@Payload() data: any, @Ctx() ctx: RmqContext) {
  const retryCount = data.retry || 0;
  try {
    await this.handleMessage(data);
    ctx.getChannelRef().ack(ctx.getMessage());
  } catch (err) {
    if (retryCount < 3) {
      // republish with retry count
    } else {
      // DLQ
      ctx.getChannelRef().nack(ctx.getMessage(), false, false);
    }
  }
}

v11 신규

Status / Unwrap / On methods: transporter 상태
NATS queue per handler
NATS gracefull shutdown
DI container 로부터 microservice options

Interceptor / Guard / Pipe

같은 개념 적용:

@UseGuards(AuthGuard)
@UseInterceptors(LoggingInterceptor)
@MessagePattern('secure_op')
async secureOp(@Payload() data: any) { ... }

Guard 안:

canActivate(ctx: ExecutionContext): boolean {
  if (ctx.getType() === 'rpc') {
    const rpcCtx = ctx.switchToRpc();
    // ...
  }
}

함정

[!WARNING] Kafka subscribe 를 잊으면 응답 못 받음. subscribeToResponseOf('pattern') + connect().

[!CAUTION] Message ordering. Kafka 는 partition 안에서만 순서. RabbitMQ 는 queue 안에서 순서.

[!WARNING] Exactly-once vs at-least-once. 대부분 broker 는 at-least-once. Idempotent handler 필수.

[!IMPORTANT] Timeout 관리. Request-response 는 client 가 timeout 명시. 응답 안 오면 hang.

[!CAUTION] Serialization. 큰 payload 는 broker 부담. Reference (S3 URL) 만 전달하는 편이 나은 경우.

[NestJS] Middleware

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Middleware 는 route handler 실행 이전, Guard 도 실행되기 전에 실행되는 함수/클래스입니다. Express/Fastify 표준 middleware 를 그대로 사용할 수 있는 지점입니다. 요청 body 파싱, 로깅, session, cookie, CORS, helmet 등.

Middleware 순서 (전체 lifecycle)

Middleware ← 여기
Guard
Interceptor (before)
Pipe
Controller handler
Interceptor (after)
Exception filter

Middleware 는 raw req, res 만 접근. NestJS 컨텍스트 (ExecutionContext) 없음.

클래스 스타일



@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`${req.method} ${req.url}`);
    next();
  }
}

함수 스타일

export function logger(req: Request, res: Response, next: NextFunction) {
  console.log(`${req.method} ${req.url}`);
  next();
}

차이:

클래스: DI 가능 (@Injectable())
함수: DI 불가, 간단

Module 에서 등록

configure() 메서드에서:


@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes(UsersController);
  }
}

forRoutes 옵션

Controller 이름

consumer.apply(LoggerMiddleware).forRoutes(UsersController, OrdersController);

URL path

consumer.apply(LoggerMiddleware).forRoutes('users');
consumer.apply(LoggerMiddleware).forRoutes('users/*');

Method + path 객체


consumer.apply(LoggerMiddleware).forRoutes(
  { path: 'users', method: RequestMethod.GET },
  { path: 'users', method: RequestMethod.POST },
);

모든 route

consumer.apply(LoggerMiddleware).forRoutes('*');

exclude

consumer
  .apply(LoggerMiddleware)
  .exclude(
    { path: 'health', method: RequestMethod.GET },
    { path: 'metrics', method: RequestMethod.GET },
    'admin/*',
  )
  .forRoutes('*');

여러 middleware

consumer
  .apply(LoggerMiddleware, RequestIdMiddleware, SecurityMiddleware)
  .forRoutes('*');

Global Middleware

main.ts 에서:

// main.ts

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.use(express.json({limit: '1mb'}));
  app.use(logger);   // 함수 middleware
  await app.listen(3000);
}

주의: app.use() 로 등록한 middleware 는 controller 스코프 밖. MiddlewareConsumer 는 route 별 세밀.

Common Middleware 통합

CORS

// main.ts
app.enableCors({
  origin: ['https://app.example.com'],
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  credentials: true,
});

또는:


app.use(cors({ ... }));

Helmet

npm i helmet


app.use(helmet());

CSP, XSS-Protection, X-Frame-Options 등 자동

Body Parser

Express 는 기본 body parser 포함. Fastify 는:

// main.ts
app.useGlobalPipes(new ValidationPipe());   // DTO 검증

Multer (파일 업로드):

npm i @nestjs/platform-express multer



@Post('upload')
@UseInterceptors(FileInterceptor('file'))
upload(@UploadedFile() file: Express.Multer.File) { ... }

Session

npm i express-session
npm i @types/express-session -D


app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    maxAge: 3600 * 1000,
  },
}));

npm i cookie-parser


app.use(cookieParser());

Compression

npm i compression


app.use(compression());

Request ID (분산 트레이싱)


@Injectable()
export class RequestIdMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const reqId = (req.headers['x-request-id'] as string) || uuidv4();
    req['requestId'] = reqId;
    res.setHeader('X-Request-Id', reqId);
    next();
  }
}

Interceptor 에서도 접근:

const req = context.switchToHttp().getRequest();
const reqId = req.requestId;

Rate Limiter (Middleware 대안: Guard)

npm i @nestjs/throttler


@Module({
  imports: [ThrottlerModule.forRoot([{ttl: 60000, limit: 100}])],
  providers: [{provide: APP_GUARD, useClass: ThrottlerGuard}],
})

Guard 로 처리하는 편이 관용. Middleware 는 인프라 (nginx, ALB) 로 처리.

Middleware 안에서 DI

@Injectable()
export class AuthMiddleware implements NestMiddleware {
  constructor(private authService: AuthService) {}

  async use(req: Request, res: Response, next: NextFunction) {
    const token = req.headers.authorization?.split(' ')[1];
    if (token) {
      req['user'] = await this.authService.verify(token);
    }
    next();
  }
}

주의: 인증은 Middleware 보다 [[nestjs-guards|Guard]] 가 관용. Guard 는 예외 던지기, decorator 지원, ExecutionContext 등이 유리.

Fastify 와의 차이

Fastify 는 Express middleware 와 호환 아님. Fastify plugin 을 사용해야 함:



await app.register(fastifyHelmet);
await app.register(fastifyCors);

함정

[!WARNING] Middleware 는 Guard 보다 먼저. 인증을 middleware 로 하면 @Public() 데코레이터 활용 못 함. Guard 로 이관.

[!CAUTION] next() 안 호출 하면 요청 hanging. 조건 분기에서 조심.

[!WARNING] Fastify 에서 Express middleware 오작동. 예: express-session 은 Fastify 에서 작동 X. @fastify/session.

[!IMPORTANT] app.use() 는 global, MiddlewareConsumer 는 route 별. 둘의 역할 구분.

[!CAUTION] Middleware DI 순서. configure() 는 module 로딩 시점에 실행. Async 초기화 필요 시 dynamic module.

[NestJS] Modules

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Module 은 @Module() 데코레이터가 붙은 클래스로, 관련된 controller, provider, import/export 를 하나로 묶는 조직 단위입니다. Angular 의 NgModule 에서 영감. 애플리케이션 = module 트리 이고, root module (AppModule) 이 진입점입니다.

기본 구조





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

4 개의 배열

imports: 이 모듈이 사용할 다른 모듈
controllers: HTTP 라우트를 처리할 controller
providers: 이 모듈 내부에서 DI 로 주입할 클래스
exports: 이 모듈을 import 한 다른 모듈에서 사용할 provider

왜 모듈로 나누나

Feature 단위 조직: users, auth, orders 등 도메인별
의존성 격리: import 하지 않은 module 의 provider 는 접근 못 함
테스트 편의: 모듈 단위 테스트 가능
재사용: 공통 모듈 (Database, Config, Logger)

Feature Module 패턴

큰 앱은 여러 feature module 로 나눔:

// AppModule (root)
@Module({
  imports: [
    ConfigModule.forRoot(),
    DatabaseModule,
    UsersModule,
    AuthModule,
    OrdersModule,
    HealthModule,
  ],
})
export class AppModule {}

각 feature 는 자기 controller + service + DTO 소유.

Shared Module

여러 모듈이 공통 provider 사용:

@Module({
  providers: [CommonService],
  exports: [CommonService],
})
export class CommonModule {}

이 module 을 import 한 곳에서 CommonService 를 injection 받을 수 있음.

주의: 각 module 은 별도 DI container. Shared module 을 여러 곳에서 import 해도 provider instance 는 동일 (singleton).

Global Module

@Global() 로 모든 모듈에서 접근 가능:

@Global()
@Module({
  providers: [LoggerService],
  exports: [LoggerService],
})
export class LoggerModule {}

이제 어느 module 이든 imports 없이 LoggerService 주입.

주의: 남용 금지. 의존성이 명확하지 않아 refactoring 어려움. Config, Logger 등 정말 전역인 것만.

Dynamic Module (동적 설정)

Runtime 에 옵션을 받아 module 을 configure. forRoot, forRootAsync, forFeature 관용:

// database.module.ts


@Module({})
export class DatabaseModule {
  static forRoot(options: DatabaseOptions): DynamicModule {
    return {
      module: DatabaseModule,
      providers: [
        {
          provide: 'DATABASE_OPTIONS',
          useValue: options,
        },
        DatabaseService,
      ],
      exports: [DatabaseService],
    };
  }

  static forRootAsync(asyncOptions: DatabaseAsyncOptions): DynamicModule {
    return {
      module: DatabaseModule,
      imports: asyncOptions.imports || [],
      providers: [
        {
          provide: 'DATABASE_OPTIONS',
          useFactory: asyncOptions.useFactory,
          inject: asyncOptions.inject || [],
        },
        DatabaseService,
      ],
      exports: [DatabaseService],
    };
  }
}

사용

// AppModule
@Module({
  imports: [
    DatabaseModule.forRoot({
      host: 'localhost',
      port: 5432,
    }),
    // 또는 async
    DatabaseModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        host: config.get('DB_HOST'),
        port: config.get('DB_PORT'),
      }),
    }),
  ],
})
export class AppModule {}

forFeature 는 여러 곳에서 다른 옵션으로 재사용 (예: TypeORM 의 entity 별 repository):

@Module({
  imports: [TypeOrmModule.forFeature([User, Order])],
})
export class MyModule {}

Circular Dependency (순환 참조)

Module A imports B, B imports A -> forwardRef:

// UsersModule
@Module({
  imports: [forwardRef(() => AuthModule)],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

// AuthModule
@Module({
  imports: [forwardRef(() => UsersModule)],
  providers: [AuthService],
  exports: [AuthService],
})
export class AuthModule {}

서비스 안에서도:

@Injectable()
export class AuthService {
  constructor(
    @Inject(forwardRef(() => UsersService))
    private usersService: UsersService,
  ) {}
}

주의: 순환 참조 자체가 설계 냄새. 대개 두 서비스를 하나로 합치거나, 공통 인터페이스를 별도 module 로 추출.

Module 의 lifecycle hooks


@Injectable()
export class MyService implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    // 모든 module 이 초기화된 후
    console.log('Module initialized');
  }

  async onModuleDestroy() {
    // 애플리케이션 종료 전
    await this.cleanup();
  }
}

전체 lifecycle:

OnModuleInit
OnApplicationBootstrap
OnModuleDestroy
BeforeApplicationShutdown (app.enableShutdownHooks() 필요)
OnApplicationShutdown

모듈 재구성 패턴

Feature module

users/
├── users.module.ts
├── users.controller.ts
├── users.service.ts
├── users.repository.ts
├── dto/
├── entities/
└── users.controller.spec.ts

Sub-modules

users/
├── users.module.ts
├── profile/
│   ├── profile.controller.ts
│   ├── profile.service.ts
│   └── profile.module.ts
├── settings/
│   ├── settings.controller.ts
│   ├── settings.service.ts
│   └── settings.module.ts

users.module.ts 가 ProfileModule, SettingsModule 을 import.

실전 예: DatabaseModule + UsersModule

// database/database.module.ts



@Module({})
export class DatabaseModule {
  static forRoot(): DynamicModule {
    return {
      module: DatabaseModule,
      providers: [
        {
          provide: PrismaClient,
          useFactory: (config: ConfigService) => new PrismaClient({
            datasources: {
              db: { url: config.get('DATABASE_URL') }
            }
          }),
          inject: [ConfigService],
        },
      ],
      exports: [PrismaClient],
      global: true,
    };
  }
}

// users/users.module.ts
@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

// app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({isGlobal: true}),
    DatabaseModule.forRoot(),
    UsersModule,
  ],
})
export class AppModule {}

함정

[!WARNING] Provider export 잊지 않기. exports 에 안 넣으면 imports 한 module 에서 접근 못 함.

[!CAUTION] @Global() 남용. Global module 로 하면 편하지만 의존성 관계 흐려짐.

[!WARNING] Circular deps 는 refactor 신호. forwardRef 는 임시 방편.

[!IMPORTANT] DynamicModule 은 imports 배열에. forRoot() 호출 결과가 module 리터럴. 정적 module 과 섞어도 됨.

[!CAUTION] Feature module 이 너무 큼. sub-module 로 분할. 하나의 module 에 20+ file 이면 리팩토링.

[NestJS] Pipes (Validation, Transformation)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Pipe 는 controller method 로 들어가는 인자를 변환 (transformation) 하거나 검증 (validation) 하는 클래스입니다. Guard/Interceptor 이후, handler 이전에 실행됩니다. 두 가지 관용:

변환: ParseIntPipe (string -> number)
검증: ValidationPipe (DTO 검증)

내장 Pipe

import {
  ParseIntPipe,
  ParseFloatPipe,
  ParseBoolPipe,
  ParseArrayPipe,
  ParseUUIDPipe,
  ParseDatePipe,     // v11 신규
  ParseEnumPipe,
  DefaultValuePipe,
  ValidationPipe,
} from '@nestjs/common';

@Get(':id')
find(@Param('id', ParseIntPipe) id: number) { ... }

@Get()
list(
  @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
  @Query('active', new DefaultValuePipe(true), ParseBoolPipe) active: boolean,
) { ... }

@Get(':uuid')
findByUuid(@Param('uuid', ParseUUIDPipe) uuid: string) { ... }

@Get()
byDate(@Query('date', ParseDatePipe) date: Date) { ... }

@Get()
byIds(
  @Query('ids', new ParseArrayPipe({items: Number, separator: ','}))
  ids: number[],
) { ... }

파싱 실패 시 자동 400 BadRequest.

ValidationPipe (DTO 검증)

class-validator + class-transformer 필요:

npm i class-validator class-transformer

전역 활성화

// main.ts
app.useGlobalPipes(new ValidationPipe({
  whitelist: true,               // DTO 에 없는 필드 제거
  forbidNonWhitelisted: true,    // 있으면 오류 (선택)
  transform: true,                // 자동 변환 (string -> number 등)
  transformOptions: {
    enableImplicitConversion: true,
  },
}));

DTO 정의

import {
  IsEmail,
  IsInt,
  IsString,
  IsOptional,
  MinLength,
  MaxLength,
  Min,
  Max,
  IsEnum,
  IsDate,
  ValidateNested,
  IsArray,
} from 'class-validator';

export enum Role {
  Admin = 'admin',
  User = 'user',
  Guest = 'guest',
}

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  @MaxLength(128)
  password: string;

  @IsString()
  @MinLength(1)
  @MaxLength(50)
  name: string;

  @IsInt()
  @Min(0)
  @Max(150)
  age: number;

  @IsEnum(Role)
  role: Role;

  @IsDate()
  @Type(() => Date)               // string -> Date 자동 변환
  birthDate: Date;

  @IsOptional()
  @IsString()
  bio?: string;

  @ValidateNested()
  @Type(() => AddressDto)
  address: AddressDto;

  @IsArray()
  @IsString({each: true})
  @ArrayMinSize(1)
  tags: string[];
}

사용

@Post()
create(@Body() dto: CreateUserDto) {
  // 이미 validated + transformed
  // birthDate 는 Date 인스턴스
  // ...
}

검증 실패 시 자동 400:

{
  "statusCode": 400,
  "message": [
    "email must be an email",
    "password must be longer than or equal to 8 characters"
  ],
  "error": "Bad Request"
}

Query DTO 검증

export class ListUsersQuery {
  @Type(() => Number)
  @IsInt()
  @Min(1)
  @IsOptional()
  page?: number = 1;

  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(100)
  @IsOptional()
  limit?: number = 10;

  @IsOptional()
  @IsEnum(['asc', 'desc'])
  order?: 'asc' | 'desc' = 'desc';
}

@Type(() => Number) 는 class-transformer 로 string -> number.

Custom Pipe


@Injectable()
export class TrimPipe implements PipeTransform<string, string> {
  transform(value: string, metadata: ArgumentMetadata): string {
    if (typeof value !== 'string') return value;
    return value.trim();
  }
}

@Injectable()
export class ParsePositiveIntPipe implements PipeTransform<string, number> {
  transform(value: string): number {
    const n = parseInt(value, 10);
    if (isNaN(n) || n <= 0) {
      throw new BadRequestException('Must be a positive integer');
    }
    return n;
  }
}

Pipe 부착 방법

Parameter

@Get(':id')
find(@Param('id', ParseIntPipe) id: number) { ... }

// 옵션 있는 pipe
@Get(':id')
find(
  @Param('id', new ParseIntPipe({errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE}))
  id: number,
) { ... }

// 여러 pipe (순서대로)
@Get()
list(@Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number) { ... }

Method

@Post()
@UsePipes(new ValidationPipe({transform: true}))
create(@Body() dto: CreateUserDto) { ... }

Controller

@Controller('users')
@UsePipes(new ValidationPipe())
export class UsersController { ... }

Global

// main.ts
app.useGlobalPipes(new ValidationPipe({...}));

// 또는 module
@Module({
  providers: [
    { provide: APP_PIPE, useClass: ValidationPipe },
  ],
})
export class AppModule {}

Transform 옵션

@Type() 없이 자동 변환:

new ValidationPipe({
  transform: true,
  transformOptions: {
    enableImplicitConversion: true,   // TS 타입 기반 자동 변환
  },
})

이제 page: number 필드가 string 으로 들어와도 자동으로 Number. 위험도 있음 ("abc" -> NaN).

Whitelist / ForbidNonWhitelisted

new ValidationPipe({
  whitelist: true,             // DTO 에 없는 필드 자동 제거
  forbidNonWhitelisted: true,  // 있으면 오류
})

whitelist: 안전 (extra 필드 무시)
forbidNonWhitelisted: 엄격 (스키마 강제, 오탈자 방지)

Nested Validation

export class AddressDto {
  @IsString() city: string;
  @IsString() zipCode: string;
}

export class CreateUserDto {
  @IsEmail() email: string;

  @ValidateNested()
  @Type(() => AddressDto)
  address: AddressDto;

  @IsArray()
  @ValidateNested({each: true})
  @Type(() => AddressDto)
  addresses: AddressDto[];
}

Groups / Conditional

export class UpdateUserDto {
  @IsOptional()
  @IsEmail({}, {groups: ['update']})
  email?: string;
}

new ValidationPipe({groups: ['update']})

Async Custom Validator


@ValidatorConstraint({name: 'IsEmailUnique', async: true})
export class IsEmailUniqueConstraint implements ValidatorConstraintInterface {
  constructor(private usersService: UsersService) {}
  async validate(email: string) {
    const exists = await this.usersService.emailExists(email);
    return !exists;
  }
}

export function IsEmailUnique(options?: ValidationOptions) {
  return function(object: object, propertyName: string) {
    registerDecorator({
      target: object.constructor,
      propertyName,
      options,
      validator: IsEmailUniqueConstraint,
    });
  };
}

주의: Async custom validator 는 useContainer 설정 필요.

Zod 대체

class-validator 대신 zod 사용 가능. NestJS 는 nestjs-zod 등 통합 라이브러리.



const CreateUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  age: z.number().int().min(0).max(150),
});

export class CreateUserDto extends createZodDto(CreateUserSchema) {}

TypeScript 타입 자동 추론. 런타임 검증.

v11 신규: ParseDatePipe

@Get()
byDate(@Query('date', new ParseDatePipe()) date: Date) { ... }

// 옵션
@Get()
byDate(
  @Query('date', new ParseDatePipe({
    optional: true,
    default: () => new Date(),
  }))
  date: Date,
) { ... }

ISO 8601 문자열 -> Date. 실패 시 400.

함정

[!WARNING] ValidationPipe global 등록 안 하면 DTO 검증 안 됨. main.ts 에 반드시.

[!CAUTION] transform: false 상태에서 @Type() 무력. transform 필수.

[!WARNING] class-validator metadata 필요. reflect-metadata import + tsconfig emitDecoratorMetadata: true.

[!IMPORTANT] Nested DTO 는 @ValidateNested() + @Type() 필수. 안 하면 nested 는 검증 skip.

[!CAUTION] enableImplicitConversion 은 위험할 수도. age: number 필드에 "abc" 오면 NaN. 명시적 @Type(() => Number) 가 안전.

[NestJS] Providers & Dependency Injection

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Provider 는 @Injectable() 데코레이터가 붙은 클래스 (또는 값/factory) 로, DI container 에 등록되어 다른 클래스에 주입됩니다. Service, Repository, Factory, Helper 등이 모두 provider 입니다. Constructor injection 이 기본.

왜 DI 인가

수동 초기화 없이 필요한 의존성을 주입:

// DI 없이
class UsersController {
  private service = new UsersService(new UsersRepo(new PrismaClient()));
}

// DI
@Controller('users')
class UsersController {
  constructor(private service: UsersService) {}
}

Testability: mock 주입 쉬움
가독성: 의존성 명시
재사용: singleton 자동
loose coupling: 인터페이스 기반

Injectable Service


@Injectable()
export class UsersService {
  constructor(
    private readonly repo: UsersRepository,
    private readonly logger: LoggerService,
  ) {}

  async findAll() {
    this.logger.log('finding all users');
    return this.repo.findAll();
  }
}

Module 에 등록:

@Module({
  providers: [UsersService, UsersRepository, LoggerService],
  exports: [UsersService],
})
export class UsersModule {}

기본 등록 형태

providers: [UsersService]

는 축약형:

providers: [
  {
    provide: UsersService,     // 토큰 (클래스 이름)
    useClass: UsersService,    // 실제 클래스
  },
]

Custom Provider

`useClass` - 다른 클래스로 대체

providers: [
  {
    provide: LoggerService,
    useClass: process.env.NODE_ENV === 'production'
      ? ProductionLogger
      : DevLogger,
  },
]

Injectable 은 LoggerService 지만 실제로는 env 에 따라 다른 구현.

`useValue` - 고정 값

const mockUsersService = {
  findAll: () => [{id: 1, name: 'kim'}],
};

providers: [
  {
    provide: UsersService,
    useValue: mockUsersService,
  },
]

테스트 mock 이나 상수 config 에 유용.

`useFactory` - Factory 함수

providers: [
  {
    provide: 'DATABASE_CONNECTION',
    useFactory: async (config: ConfigService) => {
      const client = new PrismaClient({
        datasources: {db: {url: config.get('DATABASE_URL')}}
      });
      await client.$connect();
      return client;
    },
    inject: [ConfigService],   // factory 인자
  },
]

Async 도 OK. inject 배열 순서 == factory 인자 순서.

`useExisting` - alias

providers: [
  LoggerService,
  {
    provide: 'ALIAS_LOGGER',
    useExisting: LoggerService,
  },
]

Non-Class Token

Class 가 아닌 값 (문자열, symbol) 을 토큰으로:

export const DATABASE_CONNECTION = 'DATABASE_CONNECTION';

providers: [
  {
    provide: DATABASE_CONNECTION,
    useFactory: () => new PrismaClient(),
  },
]

// 주입 시
@Injectable()
export class UsersRepo {
  constructor(
    @Inject(DATABASE_CONNECTION) private db: PrismaClient,
  ) {}
}

TypeScript 는 어떤 타입인지 몰라 @Inject() 명시. Symbol 도 가능:

export const DATABASE_CONNECTION = Symbol('DATABASE_CONNECTION');

Class 를 그대로 토큰으로 쓰면 @Inject() 필요 없음 (TypeScript 가 메타데이터 저장).

Provider Scope

기본은 Singleton (앱 한 개). 다른 scope:


@Injectable({ scope: Scope.DEFAULT })      // singleton (default)
@Injectable({ scope: Scope.REQUEST })      // 요청마다 새 instance
@Injectable({ scope: Scope.TRANSIENT })    // 주입마다 새 instance
export class MyService {}

REQUEST scope

각 HTTP 요청마다 새 instance. Request context 접근 가능.




@Injectable({ scope: Scope.REQUEST })
export class RequestContextService {
  constructor(@Inject(REQUEST) private request: Request) {}

  getUserId(): string {
    return this.request.user.id;
  }
}

주의: REQUEST scope provider 를 주입받는 상위 provider 도 자동으로 REQUEST scope. 성능 오버헤드 (요청마다 인스턴스 생성 + injection graph 재구성). 꼭 필요할 때만.

TRANSIENT

주입될 때마다 새 instance. Consumer 별 독립 상태.

@Injectable({ scope: Scope.TRANSIENT })
export class Counter {
  private count = 0;
  increment() { return ++this.count; }
}

// UserService.counter 와 OrderService.counter 는 다른 인스턴스

Optional Injection


@Injectable()
export class MyService {
  constructor(
    @Optional() @Inject('OPTIONAL_TOKEN') private optional?: string,
  ) {}
}

주입 못 하면 undefined.

Async Provider

DB 연결 등 초기화가 async 인 경우:

{
  provide: 'DATABASE',
  useFactory: async () => {
    const conn = await connectToDb();
    return conn;
  },
}

AppModule 이 초기화 완료된 후 앱 시작.

Circular Dependency

Provider A -> B -> A -> forwardRef:

@Injectable()
export class AService {
  constructor(
    @Inject(forwardRef(() => BService))
    private bService: BService,
  ) {}
}

@Injectable()
export class BService {
  constructor(
    @Inject(forwardRef(() => AService))
    private aService: AService,
  ) {}
}

Refactoring 가 나은 편이 대부분.

Repository 패턴

// users.repository.ts
@Injectable()
export class UsersRepository {
  constructor(private prisma: PrismaService) {}

  async findAll() {
    return this.prisma.user.findMany();
  }

  async findOne(id: string) {
    return this.prisma.user.findUnique({where: {id}});
  }

  async create(data: CreateUserDto) {
    return this.prisma.user.create({data});
  }
}

Service 가 repo 를 주입:

@Injectable()
export class UsersService {
  constructor(private repo: UsersRepository) {}

  async findAll() {
    return this.repo.findAll();
  }
}

Multi-Provider (여러 값 배열)

여러 인스턴스를 하나의 토큰 배열로:

export const HANDLER = 'HANDLER';

providers: [
  {provide: HANDLER, useClass: HandlerA, multi: true} as any,   // Nest 는 표준 multi 없음
  {provide: HANDLER, useClass: HandlerB, multi: true} as any,
]

NestJS 는 표준 multi-provider 없음 (Angular 에는 있음). 대신 배열 provider:

providers: [
  HandlerA,
  HandlerB,
  {
    provide: 'HANDLERS',
    useFactory: (a: HandlerA, b: HandlerB) => [a, b],
    inject: [HandlerA, HandlerB],
  },
]

Lifecycle Hook

Provider 도 module 처럼:


@Injectable()
export class DatabaseService implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    await this.connect();
  }

  async onModuleDestroy() {
    await this.disconnect();
  }
}

실전 패턴

Config injection

@Injectable()
export class ApiClient {
  private baseUrl: string;

  constructor(private config: ConfigService) {
    this.baseUrl = this.config.get('API_URL');
  }
}

여러 구현 선택

@Module({
  providers: [
    {
      provide: 'PAYMENT_GATEWAY',
      useClass: process.env.PAYMENT === 'stripe' ? StripeGateway : PayPalGateway,
    },
  ],
  exports: ['PAYMENT_GATEWAY'],
})
export class PaymentModule {}

Strategy Pattern

interface EmailSender {
  send(to: string, subject: string, body: string): Promise<void>;
}

@Injectable() class SendGridSender implements EmailSender { ... }
@Injectable() class SmtpSender implements EmailSender { ... }

@Module({
  providers: [
    {
      provide: 'EMAIL_SENDER',
      useClass: SendGridSender,
    },
  ],
  exports: ['EMAIL_SENDER'],
})
export class EmailModule {}

Testing DI

const module = await Test.createTestingModule({
  providers: [
    UsersService,
    {
      provide: UsersRepository,
      useValue: {
        findAll: jest.fn().mockResolvedValue([{id: 1, name: 'kim'}]),
      },
    },
  ],
}).compile();

const service = module.get<UsersService>(UsersService);

자세한 것은 [[nestjs-testing|NestJS Testing]] 참조.

함정

[!WARNING] REQUEST scope 의 성능 비용. 매 요청 인스턴스 생성 + graph 재구성. Global logger, tracing 에는 다른 방식 (AsyncLocalStorage) 검토.

[!CAUTION] @Inject() 누락. String/Symbol 토큰 사용 시 @Inject() 명시 필수. Class 는 자동.

[!WARNING] Circular dependency 는 refactor 신호. forwardRef 는 응급.

[!IMPORTANT] useFactory 의 inject 순서. inject 배열 순서 == factory 인자 순서.

[!CAUTION] Module 에 provider 안 등록하면 UNKNOWN_DEPENDENCIES 오류. 오류 메시지의 module 이름 확인.

[NestJS] Testing (Jest, Supertest, e2e)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

NestJS Testing 은 Jest (기본) + Supertest 조합으로 unit test 와 e2e test 를 지원합니다. @nestjs/testing 의 Test.createTestingModule 로 module 을 격리된 형태로 만들고, provider 를 mock 으로 교체합니다.

Unit Test 기본

// users.service.spec.ts



describe('UsersService', () => {
  let service: UsersService;
  let repo: jest.Mocked<UsersRepository>;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        UsersService,
        {
          provide: UsersRepository,
          useValue: {
            findAll: jest.fn(),
            findOne: jest.fn(),
            create: jest.fn(),
          },
        },
      ],
    }).compile();

    service = module.get<UsersService>(UsersService);
    repo = module.get(UsersRepository);
  });

  it('should be defined', () => {
    expect(service).toBeDefined();
  });

  it('findAll returns users', async () => {
    repo.findAll.mockResolvedValue([{id: 1, name: 'kim'}]);
    const result = await service.findAll();
    expect(result).toEqual([{id: 1, name: 'kim'}]);
    expect(repo.findAll).toHaveBeenCalledTimes(1);
  });

  it('create throws on duplicate email', async () => {
    repo.create.mockRejectedValue(new UserAlreadyExistsError('a@b.com'));
    await expect(
      service.create({email: 'a@b.com', name: 'kim'})
    ).rejects.toThrow(UserAlreadyExistsError);
  });
});

Controller Test

// users.controller.spec.ts
describe('UsersController', () => {
  let controller: UsersController;
  let service: jest.Mocked<UsersService>;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      controllers: [UsersController],
      providers: [
        {
          provide: UsersService,
          useValue: {
            findAll: jest.fn(),
            findOne: jest.fn(),
          },
        },
      ],
    }).compile();

    controller = module.get(UsersController);
    service = module.get(UsersService);
  });

  it('GET /users returns all users', async () => {
    service.findAll.mockResolvedValue([{id: 1, name: 'kim'}]);
    const result = await controller.findAll();
    expect(result).toHaveLength(1);
  });
});

Controller test 는 unit test 지만 실제 HTTP 는 안 거침 (그건 e2e).

E2E Test

실제 HTTP 요청을 보내 응답 검증. Nest 앱 실체 사용.

// test/app.e2e-spec.ts




describe('AppController (e2e)', () => {
  let app: INestApplication;

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

    app = moduleFixture.createNestApplication();
    app.useGlobalPipes(new ValidationPipe({whitelist: true, transform: true}));
    await app.init();
  });

  afterAll(async () => {
    await app.close();
  });

  it('/ (GET)', () => {
    return request(app.getHttpServer())
      .get('/')
      .expect(200)
      .expect('Hello World!');
  });

  it('POST /users creates user', () => {
    return request(app.getHttpServer())
      .post('/users')
      .send({email: 'a@b.com', password: 'secret123', name: 'kim'})
      .expect(201)
      .expect(res => {
        expect(res.body.id).toBeDefined();
        expect(res.body.email).toBe('a@b.com');
      });
  });

  it('POST /users returns 400 on invalid input', () => {
    return request(app.getHttpServer())
      .post('/users')
      .send({email: 'not-an-email'})
      .expect(400);
  });
});

Provider override

E2E 에서 특정 provider 만 mock:

const moduleFixture = await Test.createTestingModule({
  imports: [AppModule],
})
  .overrideProvider(EmailService)
  .useValue({send: jest.fn().mockResolvedValue(true)})
  .overrideProvider(getRepositoryToken(User))
  .useValue({find: jest.fn(), save: jest.fn()})
  .overrideGuard(JwtAuthGuard)
  .useValue({canActivate: jest.fn().mockReturnValue(true)})
  .compile();

overrideProvider
overrideGuard
overrideInterceptor
overridePipe
overrideFilter

DB 격리

패턴 1: SQLite in-memory

// test.module.ts
TypeOrmModule.forRoot({
  type: 'sqlite',
  database: ':memory:',
  entities: [User, Order],
  synchronize: true,
})

빠름, 격리 완벽. PostgreSQL-specific 기능은 불가.

패턴 2: PostgreSQL + transaction rollback

let queryRunner: QueryRunner;

beforeEach(async () => {
  queryRunner = dataSource.createQueryRunner();
  await queryRunner.connect();
  await queryRunner.startTransaction();
});

afterEach(async () => {
  await queryRunner.rollbackTransaction();
  await queryRunner.release();
});

패턴 3: Testcontainers


let container: StartedPostgreSqlContainer;

beforeAll(async () => {
  container = await new PostgreSqlContainer('postgres:16').start();
  process.env.DATABASE_URL = container.getConnectionUri();
}, 60000);

afterAll(async () => {
  await container.stop();
});

프로덕션 DB 와 동일 환경. Docker 필요.

Fixture / Seed

async function seedUser(prisma: PrismaService, override: Partial<User> = {}) {
  return prisma.user.create({
    data: {
      email: `test-${Date.now()}@example.com`,
      name: 'Test User',
      password: 'hashed',
      ...override,
    },
  });
}

it('finds seeded user', async () => {
  const user = await seedUser(prisma);
  const result = await service.findOne(user.id);
  expect(result.email).toBe(user.email);
});

Mocking 패턴

jest.spyOn

const spy = jest.spyOn(service, 'sendEmail').mockResolvedValue(true);
await service.notify(user);
expect(spy).toHaveBeenCalledWith(user.email);

jest.mock (모듈 전체)

jest.mock('nodemailer', () => ({
  createTransport: () => ({
    sendMail: jest.fn().mockResolvedValue(true),
  }),
}));

MSW (외부 HTTP mock)

npm i -D msw



const server = setupServer(
  http.get('https://api.example.com/users/:id', ({params}) => {
    return HttpResponse.json({id: params.id, name: 'kim'});
  }),
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Guards 테스트

Guard 자체를 직접 테스트:

describe('JwtAuthGuard', () => {
  let guard: JwtAuthGuard;
  let jwtService: jest.Mocked<JwtService>;

  beforeEach(async () => {
    const module = await Test.createTestingModule({
      providers: [
        JwtAuthGuard,
        {provide: JwtService, useValue: {verifyAsync: jest.fn()}},
      ],
    }).compile();

    guard = module.get(JwtAuthGuard);
    jwtService = module.get(JwtService);
  });

  it('returns true for valid token', async () => {
    jwtService.verifyAsync.mockResolvedValue({sub: 1});
    const context = createMockExecutionContext({
      headers: {authorization: 'Bearer token'},
    });
    await expect(guard.canActivate(context)).resolves.toBe(true);
  });
});

createMockExecutionContext 는 자체 헬퍼:

function createMockExecutionContext(req: Partial<Request>): ExecutionContext {
  return {
    switchToHttp: () => ({
      getRequest: () => req,
    }),
  } as any;
}

Pipe 테스트

const pipe = new ValidationPipe({transform: true, whitelist: true});
const dto = {email: 'not-an-email'};

await expect(
  pipe.transform(dto, {type: 'body', metatype: CreateUserDto})
).rejects.toThrow(BadRequestException);

Coverage

npm run test:cov

jest.config.js:

module.exports = {
  moduleFileExtensions: ['js', 'json', 'ts'],
  rootDir: '.',
  testRegex: '.*\\.spec\\.ts$',
  transform: {'^.+\\.(t|j)s$': 'ts-jest'},
  collectCoverageFrom: ['**/*.(t|j)s'],
  coverageDirectory: '../coverage',
  coverageThreshold: {
    global: {
      statements: 80,
      branches: 75,
      functions: 80,
      lines: 80,
    },
  },
};

CI 통합 예시 (GitHub Actions)

name: test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run test:cov
      - run: npm run test:e2e
        env:
          DATABASE_URL: postgres://postgres:test@localhost:5432/postgres

함정

[!WARNING] E2E test 에서 useGlobalPipes/Filters/Guards 등록 안 하면 main.ts 와 다른 동작. Test 도 명시적으로 등록.

[!CAUTION] 테스트 격리. DB, cache, external service 를 각 test 별로 reset. 아니면 flaky.

[!WARNING] process.env 조작. beforeEach 에서 backup, afterEach 에서 복원. 아니면 다른 test 로 leak.

[!IMPORTANT] Jest module reset. jest.resetModules() 로 module cache clear. Global state 있는 경우 필수.

[!CAUTION] Async assertion. await expect(...).rejects.toThrow() 형태. expect(...).toThrow() 는 sync.

[Frontend] React 19.x: Actions, Activity, RSC, Foundation

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

React 19 (2024-12-05) 는 Server Components 의 정식화 와 Actions 라는 새 패러다임을 들고 나온 메이저 릴리즈. 이후 19.1 (2025-06), 19.2 (2025-10-01) 까지 minor 릴리즈에서 Activity / Performance Tracks / Partial Pre-rendering 같은 굵직한 기능 이 계속 추가되었다.

2026-06 시점 기준 현재 LTS 줄기는 19.x. React 20 / 19.3 은 아직 공식 발표 전. 이 페이지는 2026-06 의 운영자 시점 에서 정리한 React 19.x 의 작은 백과.

버전 매트릭스

버전	출시	핵심
19.0	2024-12-05	Actions, ref-as-prop, Document Metadata, Asset Loading, `use()`, `useActionState` / `useFormStatus` / `useOptimistic`, Server Components 안정화
19.1	2025-06	점진 안정화 + 버그 픽스 (큰 신 기능 없음)
19.2	2025-10-01	`
`,` useEffectEvent`,` cacheSignal`, Performance Tracks, Partial Pre-rendering, Web Streams for Node,` useId`prefix`r`
19.0.1 / 19.1.2 / 19.2.1	2025-12-03	RSC RCE 보안 패치

Actions: 폼/네트워크 워크플로의 새 표준

폼 제출 같은 비동기 전이 를 useTransition 위에서 정식화 한 것이 Actions. 함수 자체에 async 가 들어가도 isPending 이 자동으로 잡힌다.

function UpdateName() {
  const [name, setName] = useState('');
  const [error, setError] = useState(null);
  const [isPending, startTransition] = useTransition();

  const handleSubmit = () => {
    startTransition(async () => {
      const err = await updateName(name);
      if (err) {
        setError(err);
        return;
      }
      redirect('/path');
    });
  };

  return (
    <div>
      <input value={name} onChange={(e) => setName(e.target.value)} />
      <button onClick={handleSubmit} disabled={isPending}>Update</button>
      {error && <p>{error}</p>}
    </div>
  );
}

위 패턴 위에 3 종 hook 이 얹힌다:

Hook	역할
`useActionState(action, initial)`	Action 의 마지막 결과 + `isPending` 보관. 폼 결과 처리의 표준
`useFormStatus()`	`<form>` 의 자손 컴포넌트 에서 부모 폼의 pending 상태 조회 (prop drilling 없이)
`useOptimistic(state, updater)`	낙관적 업데이트 (서버 응답 전 미리 UI 갱신)

<form action={fn}> 형태로 DOM 액션 prop 도 추가. Server Actions ('use server') 와 합쳐지면 클라이언트 → 서버 mutation 의 일등 시민이 된다.

Server Components 정식화

'use client' / 'use server' 디렉티브 기반의 분할. 19 에서 안정 API 로 진입.

디렉티브	의미
`'use client'`	번들러에게 클라이언트 경계 알림. 별도 `<script>` 청크로 묶임
`'use server'`	번들러에게 서버 endpoint 알림. 클라이언트에서 호출하면 POST 가 일어남

번들러 기능 이지 React 의 런타임 기능이 아니다. Next.js, Waku, RedwoodJS 같은 프레임워크 가 묶어서 제공.

ref 가 prop 이 되다

forwardRef 는 더 이상 필요 없다. 함수 컴포넌트가 그냥 ref prop 을 받을 수 있다.

// 19 이전
const Button = forwardRef(function Button(props, ref) {
  return <button ref={ref} {...props} />;
});

// 19+
function Button({ ref, ...props }) {
  return <button ref={ref} {...props} />;
}

forwardRef 자체는 deprecated. 새 코드는 바로 prop 으로 받자.

Document Metadata

<title>, <meta>, <link> 를 컴포넌트 트리 어디에서나 렌더 가능. React 가 자동으로 <head> 로 올린다. React Helmet 같은 라이브러리가 사실상 불필요.

function BlogPost({ post }) {
  return (
    <article>
      <h1>{post.title}</h1>
      <title>{post.title}</title>
      <meta name="author" content="Josh" />
      <link rel="author" href="https://twitter.com/joshcstory/" />
      <meta name="keywords" content={post.keywords} />
    </article>
  );
}

SSR / RSC / CSR 어디서나 같은 방식. 중복 태그는 React 가 알아서 dedupe.

Asset Loading 과 `preload` / `preinit`

스타일시트, 스크립트, 폰트, 이미지의 로딩 라이프사이클 을 Suspense 와 연결. 데이터처럼 준비될 때까지 일관되게 기다림.


// 곧 쓸 자원을 미리 로드 (priority hint)
preload('https://example.com/font.woff2', { as: 'font' });

// 다운로드 + 초기화까지
preinit('https://example.com/script.js', { as: 'script' });

라우터 / 코드 스플리트 시점에 미리 호출해두면 TTI 개선.

`use()` API: Promise / Context 의 일관된 read

use(promise) 는 렌더 중 Promise 결과 를 읽는다. Suspense 가 받아서 fallback 을 띄운다.

use(context) 는 useContext 와 거의 같지만 if 안에서 호출 가능. Rules of Hooks 의 최상위 호출 제약을 조건부 사용 영역에서 풀어준 첫 hook.

function Message({ messagePromise }) {
  const msg = use(messagePromise); // Suspense 가 받음
  return <p>{msg}</p>;
}

19.2 의 큰 4가지

1. `<Activity>`: pre-render + 상태 보존

// 이전
{isVisible && <!-- mdx-component: Page -->}

// 19.2+
<Activity mode={isVisible ? 'visible' : 'hidden'}>
  <!-- mdx-component: Page -->

mode	효과
`visible`	정상 렌더 + effect mount
`hidden`	렌더는 유지 하되 effect 는 unmount, 업데이트는 우선순위 낮춤

다음 페이지로 갈 가능성이 높은 영역을 백그라운드로 미리 그려두기. 뒤로가기 시 입력값/스크롤 등 상태 보존. SPA 라우터의 워킹 디스플레이 패턴.

2. `useEffectEvent`

useEffect 의 의존성으로 들어가야 하는 값 과 그 안에서 단순히 읽기만 하는 값 을 문법적으로 분리. eslint-plugin-react-hooks@latest 가 디펜던시 배열에 자동으로 넣지 않도록 처리한다.

function ChatRoom({ roomId, theme }) {
  // theme 가 바뀌어도 effect 는 재실행 안 됨
  const onConnected = useEffectEvent(() => {
    showNotification('Connected!', theme);
  });

  useEffect(() => {
    const conn = createConnection(serverUrl, roomId);
    conn.on('connected', () => onConnected());
    conn.connect();
    return () => conn.disconnect();
  }, [roomId]); // theme 는 의존성이 *아니다*
}

“이건 이벤트인데 effect 안에서 발생한다” 라는 드문 사례 만 사용. 모든 함수를 wrap 하는 남발 금지.

3. Performance Tracks (Chrome DevTools)

Chrome DevTools 의 custom track 으로 React 의 Scheduler / Components 두 트랙 추가.

Scheduler ⚛: blocking / transition / idle 우선순위별 작업 흐름.
Components ⚛: 컴포넌트 트리의 mount / render / effect 시점.

기존 React DevTools Profiler 보다 브라우저 전체 timing 과 함께 볼 수 있어서 interaction → first paint 까지 일관된 그림. reference/dev-tools/react-performance-tracks 참고.

4. Partial Pre-rendering

정적 부분은 미리 빌드해 CDN 에서, 동적 부분은 런타임에 이어서 렌더.

// 빌드 시
const { prelude, postponed } = await prerender(<!-- mdx-component: App -->, {
  signal: controller.signal,
});
await savePostponedState(postponed);
// prelude 를 CDN 으로

// 런타임
const postponed = await getPostponedState(request);
const resumeStream = await resume(<!-- mdx-component: App -->, postponed);
// 클라이언트로 스트림

Next.js / Vercel 의 Partial Pre-rendering (PPR) 이 같은 의도. React 가 직접 지원 하게 됨.

사라지는 것들

항목	상태
`forwardRef`	deprecated. `ref` prop 사용
`defaultProps` (함수 컴포넌트)	제거
String refs (`<X ref="foo">`)	제거
Module Pattern Factories	제거
`createFactory`	제거
`react-test-renderer/shallow`	제거 (Enzyme 종료 흐름)
Create React App	2025-02-14 sunsetting

CRA 는 공식 종료. 새 프로젝트는 Vite, Next.js, Parcel, RSBuild, Expo 중 선택. 프레임워크 없이 시작 도 공식 가이드가 있다.

보안: 2025-12 RSC 사건

날짜	사건
2025-12-03	RSC 의 unauthenticated RCE 공개. 19.0.1 / 19.1.2 / 19.2.1 으로 즉시 업그레이드 권장
2025-12-11	동일 패치 시도 중 추가 취약점 2건 (DoS, Source Code Exposure) 발견

Server Components 를 프로덕션 에서 쓰는 모든 곳 이 영향. RSC 위에 입력 검증 / 권한 체크 가 반드시 들어가야 한다는 점이 다시 부각되었다.

React Foundation

날짜	사건
2025-10-07	React Foundation 발표. Meta 단독 에서 재단 거버넌스 로
2026-02-24	Linux Foundation 산하 정식 출범. AWS, Amazon, Callstack, Expo, Microsoft, Software Mansion, Vercel 합류

Meta 의 내부 release process 가 외부 stakeholder 와 공동 운영 으로 전환. Vue 와 비슷한 재단 거버넌스 모델.

React 17/18 에서 19 로

19 Upgrade Guide 의 골자:

모든 변경 이 codemod 로 자동화되어 있다 (@codemod/react-19-codemod 류).
Suspense 안의 사이드 이펙트 가 더 엄격해짐. useEffect 의 클린업 누락 등이 새로 잡힘.
Strict Mode 가 더 강력해짐 (double-invoke 가 effect 까지 확장).
peer dep 으로 react@18 을 요구하는 라이브러리들이 대부분 19 호환 되었다. 안 된 곳만 알림.

김신건의 현장 메모

Asset Loading 은 SSR 페이지에서 FOUC 줄이는 효과가 즉시 보인다. 라우트 진입 직전 preinit('app.css', { as: 'style' }) 한 줄.
Actions 는 <form action={...}> 형태로 progressive enhancement 가 그대로 가능. JS off 인 환경에서도 폼이 동작하는 것이 오랜만에 부활한 정통.
Activity 는 탭 전환이 많은 admin 같은 곳에서 강력. 상태 보존 이 직접 코드보다 깔끔.
Performance Tracks 는 언제 effect 가 늦게 mount 되었는지 가 Chrome 화면 안에서 그대로 보여서 문제 재현 의 grep 가능 영역이 커졌다.

참고

[Frontend] React Compiler 1.0: 자동 memoization 의 새 표준

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

React Compiler 는 React 컴포넌트와 hook 의 불필요한 재계산 을 빌드 타임에 자동으로 잡아주는 optimizing compiler. 손으로 useMemo / useCallback / React.memo 를 박는 대신, 컴파일러가 값과 함수의 변경 여부 를 분석해 자동으로 캐싱한다.

핵심 약속 4가지:

자동 memoization: 손으로 쓰지 않아도 정확하게 박힌다.
조건부 memoization: if/return 이후의 값 까지 memoize 가능 (수동 hook 으로는 불가능했던 영역).
Rules of React 강제: ESLint 와 함께 위반을 조용히 잡아낸다.
점진 도입: 'use memo' 디렉티브 하나로 컴포넌트 단위 부터 켤 수 있다.

v1.0 은 2025년 10월 7일 출시. 거의 10년에 걸친 컴파일러 실험 의 첫 안정 결과물이다.

왜 컴파일러인가?

React 의 멘탈 모델은 “매 렌더마다 새로 계산”. 깔끔하지만, 비싼 계산 이나 자식의 reference equality 가 필요한 곳에서는 다음 같은 코드가 불가피했다:

const filtered = useMemo(
  () => items.filter((it) => it.tag === activeTag),
  [items, activeTag],
);

const handleClick = useCallback(
  (id: string) => onSelect(id),
  [onSelect],
);

const Child = memo(function Child({ data }) {
  // ...
});

문제는 3가지:

디펜던시 배열을 사람이 관리: 빠뜨리면 stale, 너무 많이 넣으면 무의미.
memoize 한 함수도 변하면 자식이 다시 렌더: 한 군데서 끊기면 사슬 전체가 무너진다.
useMemo 자체가 비용: dependency 비교 + 캐시 슬롯 관리. 오히려 무겁다.

자동화는 비용 자체를 줄이는 것이 아니라 사람의 일관성을 보장 하기 위한 것. 컴파일러는 조건부 early-return 이후 의 값까지 memoize 한다.

컴파일러는 어떻게 동작하는가

Babel 이 만든 Abstract Syntax Tree (AST) 를 받아서, 자체 IR (HIR, High-Level Intermediate Representation) 로 lowering. HIR 은 Control Flow Graph (CFG) 기반이라 정확한 data-flow analysis 와 mutability inference 가 가능하다.

Source (JSX/TS)
  ↓ Babel parse
AST
  ↓ React Compiler lowering
HIR (CFG-based)
  ↓ multi-pass
    ├ data-flow analysis
    ├ mutability inference
    ├ scope formation (memoization 단위)
    └ rules-of-react validation
  ↓ codegen
Optimized output (AST)
  ↓ Babel print
JS

이 분리 덕에 다음이 가능:

조건부 분기 이후 memoize: useMemo 의 최상위 위치 제약이 사라진다.
세분화 (granular) scope: 거대한 useMemo 하나가 아니라 필요한 값마다 따로.
lint 가 같은 분석을 재활용: eslint-plugin-react-hooks 의 새 규칙들이 compiler 의 HIR 분석 결과를 그대로 쓴다.

공식 예시 (조건부 return 후의 theme 값까지 memoize):


export default function ThemeProvider(props) {
  if (!props.children) {
    return null;
  }
  // 컴파일러는 conditional return 이후의 값도 memoize 한다
  const theme = mergeTheme(props.theme, use(ThemeContext));
  return (
    <!-- mdx-component: ThemeContext -->

      {props.children}
    
  );
}

수동 useMemo 로는 불가능한 위치. 컴파일러만의 강점.

컴파일 모드와 디렉티브

모드	동작	용도
`infer` (기본)	컴포넌트 / hook 으로 추론 되면 자동 컴파일	새 코드, 전체 도입
`annotation`	`'use memo'` 가 명시된 함수만 컴파일	점진 도입 초기
`all`	모든 함수를 컴파일 시도	보통 권장하지 않음
`syntax`	parse 만 하고 실제 변환은 하지 않음	debugging

함수 단위 디렉티브 (모드와 무관하게 우선):

function StableComponent() {
  'use memo';      // 이 컴포넌트는 *반드시* 컴파일
  // ...
}

function ProblematicComponent() {
  'use no memo';   // 이 컴포넌트는 *반드시* 컴파일에서 제외
  // 보통 Rules of React 위반을 발견한 임시 escape
}

권장 도입 흐름:

compilationMode: 'annotation' 으로 켜고, 잘 검증된 컴포넌트부터 'use memo' 추가.
ESLint 새 규칙으로 위반 코드 식별 + 수정.
compilationMode: 'infer' 로 전환.
문제 발견된 컴포넌트만 'use no memo' 로 임시 격리 + 원인 수정 후 제거.

설정 (`babel.config.js`)

// babel.config.js
module.exports = {
  plugins: [
    [
      'babel-plugin-react-compiler',
      {
        compilationMode: 'annotation',
        target: '18',                  // '17' | '18' | '19' (기본 '19')
        panicThreshold: 'none',        // 'all_errors' | 'critical_errors' | 'none'
        logger: {
          logEvent(filename, event) {
            if (event.kind === 'CompileSuccess') {
              console.log('Compiled:', filename);
            }
          },
        },
        gating: {
          source: 'my-feature-flags',           // 모듈 경로
          importSpecifierName: 'isCompilerEnabled', // 토글 함수
        },
      },
    ],
  ],
};

주요 옵션:

target: '17' | '18': React 19 미만이면 react-compiler-runtime 을 의존성에 추가하고 target 을 명시. v1.0 의 놀라운 약속.
panicThreshold: 일반적으로 'none' 권장. 컴파일에 실패한 함수는 그대로 두고 넘어감.
gating: A/B 테스트나 feature flag 로 환경에 따라 켜고 끄기. Meta 가 내부적으로 쓰던 방식.

빌드 도구 매트릭스

빌드 도구	지원 상태 (2026-06)
Babel	1차 (`babel-plugin-react-compiler`)
Vite	`@vitejs/plugin-react` 의 Babel 옵션 경유, 또는 `vite-plugin-react-compiler`
Next.js	`next.config.js` 의 `reactCompiler: true`. 15.3.1+ 에서 swc plugin 으로 빌드 속도 크게 개선
swc	experimental. @kdy1dev 가 작업. Next.js 가 먼저 활용
oxc	작업 중 (oxc-project/oxc#10048)
Rsbuild	1차 지원
Expo	SDK 54 부터 기본 enable

새 프로젝트는 create-vite, create-next-app, create-expo-app 모두 컴파일러 enable 옵션 을 제공한다. 새 코드면 거의 무조건 켜는 것이 권장.

ESLint 통합

v1.0 부터 별도 eslint-plugin-react-compiler 는 폐지. eslint-plugin-react-hooks 의 recommended preset 안으로 통합되었다.

// eslint.config.js (Flat Config)


export default defineConfig([
  reactHooks.configs.flat.recommended,
]);

새 규칙 일부:

set-state-in-render: 렌더 중 setState 호출로 인한 무한 루프 패턴.
set-state-in-effect: Effect 안에서 불필요한 state 동기화 를 잡음.
refs: 렌더 중 ref 접근 같은 unsafe 사용을 잡음.

ESLint 만 켜는 것도 유의미: 컴파일러를 실제로 도입하지 않아도, Rules of React 위반을 컴파일러의 IR 수준 분석으로 잡아낼 수 있다.

`useMemo` / `useCallback` / `React.memo` 는 이제 필요 없나?

대부분의 경우 그렇다. 컴파일러는 손으로 쓴 것보다 더 정밀하게 memoize 한다.

다만 다음 세 경우는 escape hatch 로 그대로 둘 가치가 있다:

useEffect 의 dependency 가 정확히 memoize 된 값이어야 할 때: 컴파일러가 언제 reference 가 바뀌는지 의 의도를 표현할 곳이 코드에 명시되어 있어야 안전.
외부 라이브러리에 stable reference 를 넘겨야 할 때: 라이브러리의 hook 내부가 dep array 를 보는 경우.
이미 깔린 기존 useMemo 를 제거: 컴파일 결과가 미세하게 달라질 수 있어, 코드를 건드리지 않고 두는 편이 안전. 새 코드는 안 써도 OK.

프로덕션 결과

Meta 가 자체 앱들에 수년간 적용한 결과 (공식 글):

Meta Quest Store: 초기 로드와 페이지 이동 최대 12% 개선. 일부 인터랙션은 2.5배 이상 빨라짐.
메모리 사용량은 중립: memoize 추가 비용이 그만한 가치 가 있도록 균형.

오픈소스 사례:

Sanity Studio: 거대한 content editor 의 복잡한 트리에서 도입 회고 (discussion #33).
Wakelet: 측정된 수치 와 함께 도입 회고 (discussion #52).

v1.0 까지의 타임라인

시점	이벤트
2017	Meta 의 Prepack 실험. 종료되었지만 Hooks 설계의 토대 가 됨
2021	Xuan Huang 의 첫 prototype 데모
2024-02	React Labs 글, 본격적인 Compiler 작업 상황 공개
2024-05	React Conf 2024 에서 experimental 공개
2024-10	Beta 출시. Meta 사내 사용량 확대
2025-10-07	v1.0 stable, ESLint 통합, 새 프로젝트 기본 enable
2025-10-16	React Conf 2025 에서 리뷰

v1.0 은 시작점. 공식 글이 명시하는 방향:

더 정밀한 memoization (현재보다 세분화 + 예측 가능성).
더 많은 Rules of React 를 정적으로 검증.
swc / oxc 와의 통합 강화 → 빌드 속도.
Library precompilation: 라이브러리 저작자가 미리 컴파일된 결과 를 패키지에 동봉.

김신건의 로그 - 위키 / frameworks

[비교] JPA EAGER vs Rails eager_load

정의

N+1 문제란

로딩 전략 비교 시각화

1줄 비교

JPA EAGER 의 의미

Rails eager_load 의 의미

정확한 매핑

Rails 의 “EAGER” 라는 단어

권장 패턴 비교

N+1 디버깅 도구

JPA: EntityGraph (동적 Fetch 전략)

JPA: @BatchSize (N+1 완화)

Rails: includes / preload / eager_load 선택 기준

함정 비교

JPA 함정

Rails 함정

작은 결과 / 큰 결과의 전략

정리

쿼리 로그로 N+1 확인

JPA / Hibernate

Rails

전략 선택 요약

관련 위키

Astro

정의

사용 상황

Islands Architecture

client: 디렉티브

핵심 기능

Content Collections

Component Islands

Adapters (서버 배포)

View Transitions

Astro DB

MDX 지원

Integrations (통합)

프로젝트 구조

실전 예시: 동적 라우팅

대안

함정

관련 위키

BrainDB

정의

제공 기능

처리 흐름

설치 및 기본 설정

위키링크 변환

콘텐츠 그래프 활용 예시

콘텐츠 그래프 API

이 블로그에서의 사용 (미사용)

이 블로그의 커스텀 구현 아키텍처

BrainDB vs 커스텀 구현 비교

유사 도구

함정

커스텀 구현 시 고려 사항

관련 위키

D3.js

정의

사용 상황

데이터 바인딩 흐름

핵심 개념

Selection

Enter / Update / Exit 패턴

Scale (스케일)

Axis (축)

Transition (애니메이션)

Force Simulation

실전 예시: 바 차트

실전 예시: 라인 차트 (시계열)

v7 모듈 구조

대안

함정

관련 위키

Pagefind: 정적 사이트 전문 검색

정의

아키텍처

특징

인덱스 구조

Context (`ctx`)

라우팅 (`@koa/router`)

Body Parser (`@koa/bodyparser`)