실제로 막아 주는 버그

function total(order) {
  return order.items
    .reduce((s,i) => s + i.price, 0);
}

total({ item: [] });
// TypeError: Cannot read
// properties of undefined
// ★ 배포 후 사용자가 발견

type Order = {
  items: { price: number }[];
};
function total(order: Order) {
  return order.items
    .reduce((s,i) => s + i.price, 0);
}

total({ item: [] });
// ★ 'item' 은 'items' 여야 합니다

타입이 주는 실질적 이득

• 자동완성 — 객체에 뭐가 들었는지 외울 필요가 없습니다. 실무에서 이게 제일 큽니다
• 안전한 리팩터링 — 필드 이름을 바꾸면 고쳐야 할 곳이 전부 빨갛게 뜹니다
• 문서 역할 — 함수 시그니처만 봐도 무엇을 넣고 무엇이 나오는지 압니다
• 팀 확장 — 새 사람이 코드를 읽는 속도가 확연히 다릅니다

시작하기

npm i -D typescript @types/node
npx tsc --init                   # tsconfig.json 생성

# 빌드
npx tsc                          # dist/ 로 컴파일
npx tsc --noEmit                 # ★ 타입 검사만 (CI 에서 쓰는 형태)

# 개발 중 바로 실행
npx tsx src/index.ts             # tsx — 가장 편함

# TypeScript 를 그대로 실행 (Node 24+ 기본 · Node 26 에서 정식)
node src/index.ts
#  · 타입 "지우기"만 합니다 — 타입 검사는 tsc --noEmit 로 따로
#  · enum · 구 데코레이터 · namespace 같은 "코드를 만들어 내는" 문법은 안 됩니다
#    → tsconfig 에 "erasableSyntaxOnly": true 를 켜 두면 미리 막아 줍니다

// tsconfig.json — 처음엔 이 정도면 충분합니다
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,                    // ★ TS 7 부터는 기본값입니다
    "skipLibCheck": true,              // 라이브러리 타입은 검사 생략 (빌드 속도)
    "types": ["node"],                 // ★ TS 7 기본값이 [] — 필요한 것만 적습니다
    "outDir": "dist",
    "rootDir": "src",                  // ★ TS 7 기본값이 "./" — src 라면 꼭 적으세요
    "erasableSyntaxOnly": true,        // node src/index.ts 로 돌릴 거라면
    "paths": { "@/*": ["./src/*"] }    // ★ tsconfig 위치 기준 상대경로 (baseUrl 없음)
  },
  "include": ["src/**/*"]
}

타입 표기

// 기본
let name: string = "김현우";
let age: number = 30;
let ok: boolean = true;
let big: bigint = 10n;
let sym: symbol = Symbol();

// 배열 · 튜플
let tags: string[] = ["a", "b"];
let pair: [number, string] = [1, "a"];      // 길이·순서 고정
let named: [x: number, y: number] = [1, 2];  // 이름 붙은 튜플

// 객체
let user: { id: number; name?: string } = { id: 1 };  // ? = 선택

// 함수
const add = (a: number, b: number): number => a + b;
const log = (msg: string): void => console.log(msg);

// 특수 타입
let anything: any;        // ❌ 타입 검사 포기 — 쓰지 마세요
let safe: unknown;       // ✅ 확인 후에만 쓸 수 있음
function fail(): never { throw new Error(); }   // 절대 반환 안 함

추론 — 적지 않아도 되는 곳

// ❌ 불필요한 표기 (오히려 읽기 나쁨)
const name: string = "김현우";
const nums: number[] = [1, 2, 3];
const user: { id: number } = { id: 1 };

// ✅ 추론에 맡기기
const name = "김현우";          // "김현우" (리터럴 타입!)
const nums = [1, 2, 3];         // number[]
const user = { id: 1 };         // { id: number }

// ★ 타입을 꼭 적어야 하는 곳은 두 군데뿐입니다
function f(a: number) { }       // ① 함수 매개변수
let result: string | null = null;  // ② 나중에 채울 변수

const 와 리터럴 타입

let  a = "hello";     // string       (재할당 가능하므로 넓게)
const b = "hello";    // "hello"      ★ 리터럴 타입으로 좁게

// 객체는 안쪽까지 좁혀지지 않습니다
const conf = { mode: "dark" };          // { mode: string }
const conf2 = { mode: "dark" } as const; // { readonly mode: "dark" } ✅

// as const 의 진짜 쓸모 — 상수에서 타입 만들기
const ROLES = ["admin", "user", "guest"] as const;
type Role = typeof ROLES[number];       // "admin" | "user" | "guest"
// ★ 배열만 고치면 타입이 따라옵니다 (t08 에서 더)

// satisfies — 타입 검사는 받되 좁은 추론은 유지 (TS 4.9+)
const config = {
  port: 3000,
  host: "localhost",
} satisfies Record<string, string | number>;
config.port.toFixed();   // ✅ number 로 정확히 추론됨

차이점 정리

// interface — 확장 가능하고 선언 병합됨
interface User { id: number; name: string; }
interface User { email: string; }        // ★ 자동으로 합쳐짐
interface Admin extends User { level: number; }

// type — 무엇이든 이름 붙일 수 있음
type ID = string | number;                       // 유니온
type Point = [number, number];                   // 튜플
type Handler = (e: Event) => void;               // 함수
type Admin2 = User & { level: number };          // 교차
type Keys = keyof User;                          // 계산된 타입

실무에서 자주 쓰는 형태

// 인덱스 시그니처 — 키를 미리 모를 때
type Dict = { [key: string]: number };
type Dict2 = Record<string, number>;      // 같은 뜻, 이쪽이 읽기 좋음

// 읽기 전용
type ReadonlyUser = {
  readonly id: number;
  readonly tags: readonly string[];       // 배열도 따로 표시
};

// 함수 속성이 있는 객체 (콜러블)
type Logger = {
  (msg: string): void;                     // 함수로도 호출 가능
  level: "info" | "error";                 // 속성도 있음
};

// 생성자 타입 (DI 컨테이너 만들 때)
type Ctor<T> = new (...args: any[]) => T;

// 중첩 객체
interface ApiResponse<T> {
  data: T;
  meta: { page: number; total: number };
  error?: { code: string; message: string };
}

교차 타입의 함정

type A = { x: string };
type B = { x: number };
type C = A & B;          // x: string & number = never (만들 수 없는 타입)

const c: C = { x: ??? };  // ★ 어떤 값도 넣을 수 없습니다

// interface extends 였다면 에러로 즉시 알려 줍니다
interface D extends A { x: number }   // ❌ 컴파일 에러 ✅ 더 안전

타입 좁히기 — TS 는 흐름을 읽습니다

function format(value: string | number | Date | null) {
  if (value === null) return "-";
  // 여기부터 value: string | number | Date

  if (typeof value === "string") return value.trim();     // string
  if (typeof value === "number") return value.toFixed(2); // number
  return value.toISOString();                             // Date ★ 자동 추론
}

// 좁히는 방법들
typeof x === "string"          // 원시 타입
x instanceof Date              // 클래스
"name" in obj                  // 속성 존재
Array.isArray(x)               // 배열
x === null / x != null         // null 체크
x.kind === "circle"            // ★ 판별 유니온 (아래)

판별 유니온 — 실무에서 가장 강력한 패턴

type Result<T> =
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

function render(res: Result<User>) {
  switch (res.status) {
    case "loading": return "불러오는 중…";
    case "success": return res.data.name;    // ★ data 가 여기서만 존재
    case "error":   return res.error.message;
  }
}

// ★ 이 패턴의 진짜 가치:
//   "로딩 중인데 data 를 읽는" 버그가 컴파일 단계에서 막힙니다.
//   isLoading·data·error 를 각각 boolean 으로 두는 설계보다 훨씬 안전합니다.

빠짐없이 처리했는지 검사하기

type Shape =
  | { kind: "circle"; r: number }
  | { kind: "rect"; w: number; h: number }
  | { kind: "tri"; b: number; h: number };

function area(s: Shape): number {
  switch (s.kind) {
    case "circle": return Math.PI * s.r ** 2;
    case "rect":   return s.w * s.h;
    case "tri":    return (s.b * s.h) / 2;
    default: {
      // ★ 모든 경우를 처리했다면 s 는 never 가 됩니다
      const _exhaustive: never = s;
      throw new Error(`알 수 없는 도형: ${JSON.stringify(s)}`);
    }
  }
}

// Shape 에 새 종류를 추가하면 → 이 줄에서 컴파일 에러
// "처리를 빼먹었다"를 배포 전에 알 수 있습니다 ★

좁히기가 풀리는 순간 — 함정

function f(user: { name?: string }) {
  if (user.name) {
    // 여기서는 string
    doSomething();          // 이 함수가 name 을 지워도 TS 는 모른 척합니다 (낙관적)
    user.name.trim();       // ✅ 통과 — 바로 쓰는 건 좁히기가 유지됩니다
    setTimeout(() => user.name.trim(), 100);
    //                ❌ 'user.name' is possibly 'undefined'
    //                ★ 콜백 안에서는 좁히기가 풀립니다 (나중에 실행되니까)
  }
}

// ✅ 지역 변수로 뽑아 두면 안전합니다
const name = user.name;
if (name) {
  setTimeout(() => name.trim(), 100);    // ✅ 클로저 안에서도 유지
}

기본형

// 매개변수 · 반환
function add(a: number, b: number): number { return a + b; }

// 선택 · 기본값 · 나머지
function greet(name: string, title?: string, ...rest: string[]) { }

// 함수 타입을 이름 붙여 재사용
type Middleware = (req: Request, res: Response, next: () => void) => void;
const auth: Middleware = (req, res, next) => { next(); };
// ★ 이렇게 하면 매개변수 타입을 다시 안 적어도 됩니다 (문맥 추론)

// 콜백 타입
function retry<T>(fn: () => Promise<T>, times: number): Promise<T> { ... }

// this 타입 명시 (첫 매개변수 자리, 실제 인자는 아님)
function handler(this: HTMLButtonElement, e: MouseEvent) {
  this.disabled = true;
}

반환 타입은 적을까 말까

// 내부 함수 — 추론에 맡기세요
const double = (n: number) => n * 2;

// ★ 공개 API·라이브러리는 명시하세요
export function getUser(id: number): Promise<User> { ... }
// 이유: 구현을 고쳤을 때 "반환 타입이 조용히 바뀌는 것"을 막습니다

오버로드 — 입력에 따라 출력이 다를 때

// 선언 (호출부에서 보이는 시그니처)
function parse(input: string): object;
function parse(input: string, raw: true): string;
// 구현 (밖에서는 안 보임)
function parse(input: string, raw?: boolean): object | string {
  return raw ? input : JSON.parse(input);
}

parse("{}");            // object
parse("{}", true);      // string  ★ 정확히 좁혀짐

// ★ 대부분은 오버로드보다 제네릭·유니온이 낫습니다
// 오버로드 (장황함)
function first(a: string[]): string;
function first(a: number[]): number;

// 제네릭 (한 줄)
function first<T>(a: T[]): T | undefined { return a[0]; }

// 조건부 반환이 필요하면 (t09)
function get<T extends boolean>(raw: T): T extends true ? string : object;

실무 패턴 — 함수 시그니처로 API 설계하기

// 옵션 객체 — 인자가 3개를 넘으면 이렇게 바꾸세요
type FetchOptions = {
  method?: "GET" | "POST" | "PUT" | "DELETE";
  headers?: Record<string, string>;
  timeout?: number;
  retry?: number;
};
async function request<T>(url: string, opts: FetchOptions = {}): Promise<T> { ... }

// 호출부가 읽기 좋아집니다
await request<User>("/api/users/1", { timeout: 3000, retry: 2 });

왜 필요한가

// ❌ any — 타입 정보가 사라집니다
function firstAny(arr: any[]): any { return arr[0]; }
const a = firstAny(["x"]);      // any — 자동완성 없음, 오타 못 잡음

// ✅ 제네릭 — 넣은 타입이 그대로 나옵니다
function first<T>(arr: T[]): T | undefined { return arr[0]; }
const b = first(["x"]);         // string ★
const c = first([1, 2]);        // number

// 여러 개도 가능
function pair<K, V>(k: K, v: V): [K, V] { return [k, v]; }

// 제약 — "이런 성질은 있어야 한다"
function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}
longest("abc", "de");        // ✅ string 에는 length 가 있음
longest([1,2], [3]);         // ✅ 배열도
longest(1, 2);               // ❌ number 에는 length 가 없음

기본값과 키 제약

// 기본 타입 인자
type ApiResult<T = unknown> = { data: T; ok: boolean };

// 키를 제약 — 실무에서 매우 자주 쓰는 형태
function pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
  const out = {} as Pick<T, K>;
  for (const k of keys) out[k] = obj[k];
  return out;
}

const user = { id: 1, name: "김", pw: "secret" };
pick(user, ["id", "name"]);      // { id: number; name: string } ★
pick(user, ["nope"]);            // ❌ 없는 키는 컴파일 에러

실무에서 만나는 제네릭

// ① API 클라이언트
async function api<T>(path: string): Promise<T> {
  const res = await fetch(path);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json() as Promise<T>;
}
const user = await api<User>("/api/users/1");     // user: User

// ② 저장소 인터페이스 (Nest·계층 설계에서 그대로 씁니다)
interface Repository<T, ID = number> {
  findById(id: ID): Promise<T | null>;
  findAll(): Promise<T[]>;
  save(entity: T): Promise<T>;
  delete(id: ID): Promise<void>;
}
class UserRepository implements Repository<User> { ... }

// ③ 이벤트 맵 — 타입 안전한 이벤트 버스
type Events = {
  "order.created": { orderId: string; amount: number };
  "user.login":    { userId: number };
};
function emit<K extends keyof Events>(name: K, payload: Events[K]) { ... }

emit("order.created", { orderId: "A1", amount: 1000 });   // ✅
emit("order.created", { userId: 1 });                     // ❌ 잡힘 ★

객체 다루기

interface User {
  id: number; name: string; email: string;
  password: string; createdAt: Date;
}

// 응답에서 비밀번호 빼기 — ★ 실무 최다 사용
type UserResponse = Omit<User, "password">;

// 생성 요청 — 서버가 만드는 필드 제외
type CreateUser = Omit<User, "id" | "createdAt">;

// 수정 요청 — 일부만 보낼 수 있게
type UpdateUser = Partial<CreateUser>;

// 목록용 — 필요한 것만
type UserSummary = Pick<User, "id" | "name">;

// 상태별 색상 사전
type Status = "active" | "inactive" | "banned";
const COLOR: Record<Status, string> = {
  active: "green", inactive: "gray", banned: "red",
};   // ★ 상태를 추가하면 여기서 컴파일 에러가 납니다

유니온 · 함수 다루기

type Status = "loading" | "success" | "error";
type Done = Exclude<Status, "loading">;      // "success" | "error"

// ★ 함수에서 타입을 역으로 뽑아내기 — 매우 실용적
function createUser(name: string, age: number) {
  return { id: 1, name, age, createdAt: new Date() };
}
type User = ReturnType<typeof createUser>;   // 반환 객체 타입
type Args = Parameters<typeof createUser>;   // [string, number]

// async 함수라면 Awaited 로 벗기기
async function fetchUser() { return { id: 1, name: "김" }; }
type FetchedUser = Awaited<ReturnType<typeof fetchUser>>;

// 실무: Prisma·zod 처럼 "값에서 타입이 나오는" 라이브러리와 궁합이 좋습니다
const userSchema = z.object({ name: z.string(), age: z.number() });
type UserInput = z.infer<typeof userSchema>;   // ★ 스키마 하나로 타입까지

세 가지 연산자

interface User { id: number; name: string; tags: string[]; }

// ① keyof — 키들의 유니온
type UserKey = keyof User;              // "id" | "name" | "tags"

// ② typeof — 값에서 타입 얻기 (타입 자리에서 씀)
const defaults = { retry: 3, timeout: 5000 };
type Config = typeof defaults;          // { retry: number; timeout: number }

// ③ 인덱스드 액세스 — 속성의 타입 꺼내기
type Name = User["name"];               // string
type Tag  = User["tags"][number];       // string ★ 배열 요소 타입
type Some = User["id" | "name"];        // number | string

// 조합 — 배열 상수에서 유니온 타입 만들기
const ROLES = ["admin", "user", "guest"] as const;
type Role = (typeof ROLES)[number];     // "admin" | "user" | "guest"
// ★ 배열만 고치면 타입이 자동으로 따라옵니다

실무 활용

// ① 타입 안전한 속성 접근기
function get<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}
const name = get(user, "name");     // string ★
get(user, "nope");                  // ❌ 컴파일 에러

// ② 정렬 키를 실제 필드로 제한
function sortBy<T>(list: T[], key: keyof T, dir: "asc" | "desc" = "asc") {
  return list.toSorted((a, b) =>
    (a[key] > b[key] ? 1 : -1) * (dir === "asc" ? 1 : -1));
}
sortBy(users, "createdAt");         // ✅
sortBy(users, "typo");              // ❌ 잡힘

// ③ 설정 객체에서 환경 변수 타입 만들기
const ENV_KEYS = ["DB_HOST", "DB_PORT", "REDIS_URL"] as const;
type EnvKey = (typeof ENV_KEYS)[number];
const env = {} as Record<EnvKey, string>;
env.DB_HOST;      // ✅ 자동완성됨
env.DB_HOSTT;     // ❌ 오타를 잡아 줍니다

// ④ 라우트 경로 타입화 (템플릿 리터럴과 조합 — t10)
const routes = {
  home: "/",
  user: "/users/:id",
  order: "/orders/:orderId/items/:itemId",
} as const;

type RouteName = keyof typeof routes;       // "home" | "user" | "order"
type RoutePath = (typeof routes)[RouteName];

기본 문법

// A extends B ? 참일때 : 거짓일때
type IsString<T> = T extends string ? true : false;
type A = IsString<"hi">;      // true
type B = IsString<42>;        // false

// 실용 예 — null 을 제외한 타입
type NonNull<T> = T extends null | undefined ? never : T;

// 유니온에 적용하면 각각에 분배됩니다 (분배 조건부 타입)
type ToArray<T> = T extends any ? T[] : never;
type R = ToArray<string | number>;    // string[] | number[]  ★ 각각 적용

// 분배를 막고 싶으면 대괄호로 감쌉니다
type NoDist<T> = [T] extends [any] ? T[] : never;
type R2 = NoDist<string | number>;    // (string | number)[]

infer — 타입 안에서 꺼내 오기

// 배열의 요소 타입 꺼내기
type ElementOf<T> = T extends (infer U)[] ? U : never;
type E = ElementOf<string[]>;              // string

// Promise 벗기기 (Awaited 의 원리)
type Unwrap<T> = T extends Promise<infer U> ? U : T;

// 함수 반환 타입 (ReturnType 의 원리)
type Ret<F> = F extends (...args: any[]) => infer R ? R : never;

// 첫 번째 매개변수만
type FirstArg<F> = F extends (a: infer A, ...rest: any[]) => any ? A : never;

// 재귀 — 깊이 중첩된 Promise 도 전부 벗기기
type DeepAwait<T> = T extends Promise<infer U> ? DeepAwait<U> : T;
type X = DeepAwait<Promise<Promise<string>>>;   // string

실무에서 쓰는 조건부 타입

// ① API 응답 형태를 요청에 따라 바꾸기
type ApiResult<T, Raw extends boolean = false> =
  Raw extends true ? string : { data: T; ok: boolean };

declare function call<T, R extends boolean = false>(
  url: string, raw?: R): Promise<ApiResult<T, R>>;

const a = await call<User>("/u");          // { data: User; ok: boolean }
const b = await call<User, true>("/u", true);  // string ★
// ⚠ call<User>("/u", true) 는 에러입니다 — 타입 인자를 하나라도 적으면
//   나머지(R)는 추론되지 않고 기본값 false 로 고정되기 때문입니다

// ② 옵션에 따라 필수 필드가 달라지는 함수
type Options =
  | { mode: "file"; path: string }
  | { mode: "memory" };            // path 를 받으면 컴파일 에러

// ③ 깊은 Partial (중첩 객체 전부 선택적으로)
type DeepPartial<T> = T extends object
  ? { [K in keyof T]?: DeepPartial<T[K]> }
  : T;

// ④ null 가능한 필드만 골라내기
type NullableKeys<T> = {
  [K in keyof T]: null extends T[K] ? K : never
}[keyof T];

매핑드 타입

// Partial 의 실제 구현이 이렇습니다
type MyPartial<T> = { [K in keyof T]?: T[K] };
type MyReadonly<T> = { readonly [K in keyof T]: T[K] };

// 수식어 제거 (- 를 붙임)
type Mutable<T> = { -readonly [K in keyof T]: T[K] };
type Concrete<T> = { [K in keyof T]-?: T[K] };     // 선택 → 필수

// 값 타입 바꾸기
type Stringify<T> = { [K in keyof T]: string };
type Nullable<T> = { [K in keyof T]: T[K] | null };

// 키 이름 바꾸기 (as 절)
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K]
};
type UserGetters = Getters<{ name: string; age: number }>;
// { getName: () => string; getAge: () => number }  ★

// 키 걸러 내기 (never 를 반환하면 제외됨)
type OnlyStrings<T> = {
  [K in keyof T as T[K] extends string ? K : never]: T[K]
};

템플릿 리터럴 타입

type Lang = "ko" | "en";
type Page = "home" | "about";
type Key = `${Lang}.${Page}`;
// "ko.home" | "ko.about" | "en.home" | "en.about"  ★ 조합이 자동 생성

// 내장 문자열 유틸
Uppercase<"abc">      // "ABC"
Lowercase<"ABC">      // "abc"
Capitalize<"abc">     // "Abc"
Uncapitalize<"Abc">   // "abc"

// 실무 ① 이벤트 이름 규칙 강제
type Entity = "order" | "user";
type Action = "created" | "updated" | "deleted";
type EventName = `${Entity}.${Action}`;
function emit(e: EventName) { }
emit("order.created");     // ✅
emit("order.create");      // ❌ 오타를 잡아 줍니다

// 실무 ② 라우트 파라미터 추출 (조건부 + infer 조합)
type Params<P extends string> =
  P extends `${string}:${infer Param}/${infer Rest}`
    ? { [K in Param | keyof Params<Rest>]: string }
    : P extends `${string}:${infer Param}`
      ? { [K in Param]: string }
      : {};

type P = Params<"/users/:userId/orders/:orderId">;
// { userId: string; orderId: string }  ★

사용자 정의 타입 가드

// x is T — "이 함수가 true 면 x 는 T 다" 라고 컴파일러에 알림
function isUser(x: unknown): x is User {
  return typeof x === "object" && x !== null
      && "id" in x && typeof (x as User).id === "number";
}

const data: unknown = await res.json();
if (isUser(data)) {
  data.name;          // ✅ 여기서는 User
}

// asserts — 아니면 던지는 형태
function assertUser(x: unknown): asserts x is User {
  if (!isUser(x)) throw new TypeError("User 가 아닙니다");
}
assertUser(data);
data.name;            // ✅ 이후 전부 User

// 배열 필터에서 타입 좁히기 (아주 자주 쓰입니다)
const items: (string | null)[] = ["a", null, "b"];
const clean = items.filter((x): x is string => x !== null);   // string[] ★
// ★ 이 표기가 없으면 (string | null)[] 로 남습니다

any · unknown · never

let a: any;      a.foo.bar();       // ✅ 통과 — 런타임에 터짐
let u: unknown;  u.foo;              // ❌ 컴파일 에러 ✅ 안전
if (typeof u === "string") u.trim(); // ✅ 확인 후 사용

// catch 절은 unknown 으로 받으세요 (tsconfig: useUnknownInCatchVariables)
try { ... } catch (e) {
  if (e instanceof Error) log(e.message);
  else log(String(e));
}

타입 단언 as — 최후의 수단

// ❌ 나쁜 사용 — 거짓말하면 런타임에 터집니다
const user = JSON.parse(raw) as User;    // 실제로 User 인지 아무도 검사 안 함
const el = document.getElementById("x") as HTMLInputElement;  // null 일 수도

// ✅ 그나마 정당한 사용
const el2 = document.getElementById("x");
if (el2 instanceof HTMLInputElement) el2.value = "";   // 검사 후

// ✅ 초기화 중인 객체를 채워 나갈 때
const out = {} as Record<string, number>;

// ❌ 절대 금지 — 두 번 단언해서 억지로 통과시키기
const bad = value as unknown as User;

TS 클래스에서 추가되는 것

class UserService {
  // 접근 제어자 (컴파일 시점 검사 — 런타임에는 사라짐)
  public  name = "";
  private secret = "";        // JS 의 #secret 과 달리 런타임 보호는 없음
  protected shared = "";
  readonly id: number;

  // ★ 생성자 매개변수 속성 — 이 축약이 Nest 코드의 기본형입니다
  constructor(
    private readonly repo: UserRepository,
    private readonly logger: Logger,
  ) { this.id = 1; }
  // 위 한 줄이 "필드 선언 + this.repo = repo" 를 대신합니다

  // 추상 클래스
}

abstract class Base {
  abstract handle(req: Request): Promise<void>;   // 자식이 반드시 구현
  protected log(m: string) { console.log(m); }     // 공통 구현
}

// 인터페이스 구현
interface Runnable { run(): void; }
class Job extends Base implements Runnable {
  async handle(req: Request) { }
  run() { }
}

데코레이터 — 실제로 무슨 일이 일어나나

// 데코레이터는 "클래스·메서드를 감싸는 함수"입니다
function Log(target: any, key: string, desc: PropertyDescriptor) {
  const original = desc.value;
  desc.value = function (...args: any[]) {
    console.log(`→ ${key}(${JSON.stringify(args)})`);
    const result = original.apply(this, args);
    console.log(`← ${key} =`, result);
    return result;
  };
}

class Calc {
  @Log
  add(a: number, b: number) { return a + b; }
}
new Calc().add(1, 2);
// → add([1,2])
// ← add = 3

// ★ Nest 의 @Injectable() · @Controller() 도 원리는 같습니다.
//   "메타데이터를 붙여 두고 프레임워크가 나중에 읽는" 구조입니다.

// 옛 데코레이터(Nest·TypeORM)를 쓰려면 tsconfig 에
{
  "experimentalDecorators": true,
  "emitDecoratorMetadata": true      // ★ 타입 정보를 런타임에 남김 (DI 에 필요)
}
// TS 5.0 의 표준 데코레이터는 문법이 다릅니다.
// Nest 는 아직 experimental 쪽을 씁니다 — 섞지 마세요.

타입 전용 import

// 값과 타입을 구분해서 가져오기
import type { User } from "./types";        // ★ 빌드 후 완전히 사라짐
import { type User, createUser } from "./user";   // 섞어 쓰기

// 왜 중요한가:
//  · 번들에서 불필요한 import 가 사라짐
//  · 순환 참조를 끊을 수 있음
//  · isolatedModules 환경(esbuild·swc)에서 필수

// tsconfig 로 강제할 수 있습니다
{ "verbatimModuleSyntax": true }   // 타입은 반드시 import type 으로

선언 파일 만들기

// types/legacy-lib.d.ts — 타입이 없는 라이브러리에 타입 얹기
declare module "legacy-lib" {
  export function calculate(a: number, b: number): number;
  export default class Client {
    constructor(key: string);
    send(msg: string): Promise<void>;
  }
}

// 빠른 회피 (급할 때만 — any 로 들어옵니다)
declare module "some-untyped-lib";

// 이미지·CSS import 를 타입으로 인정시키기 (프런트엔드)
declare module "*.svg" {
  const content: string;
  export default content;
}

전역 타입 확장 — 실무에서 자주 필요합니다

// types/global.d.ts

// ① 환경 변수에 타입 붙이기 (Node)
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      DATABASE_URL: string;
      JWT_SECRET: string;
      NODE_ENV: "development" | "production" | "test";
    }
  }
}
process.env.DATABASE_URL;   // ✅ string 으로 자동완성
process.env.TYPO;           // ⚠ 에러 아님 — string | undefined
//   @types/node 에 [key: string] 인덱스 시그니처가 있어 오타는 못 잡습니다.
//   "선언한 키는 string 으로 확정"까지가 이 방법의 효과입니다

// ② Express Request 확장 (인증 미들웨어가 붙이는 값)
declare global {
  namespace Express {
    interface Request {
      user?: { id: number; role: string };
    }
  }
}
// 이제 req.user 가 타입으로 인식됩니다

// ③ window 확장 (브라우저)
declare global {
  interface Window { __APP_CONFIG__: { apiUrl: string }; }
}

export {};   // ★ 이 파일을 모듈로 만들기 위해 필요합니다

실무 기준 설정 TS 7

{
  "compilerOptions": {
    /* 출력 형태 */
    "target": "ES2022",              // 어떤 문법으로 내보낼지 ("es5" 는 하드 에러)
    "module": "NodeNext",            // Node 서버면 NodeNext (TS 7 기본값은 esnext)
    "moduleResolution": "NodeNext",  // module 과 짝을 맞춰야 함
    "lib": ["ES2022"],               // 브라우저면 ["ES2022","DOM"]
    "outDir": "dist",
    "rootDir": "src",                // ★ TS 7 기본값이 "./" 로 바뀌었습니다
    "sourceMap": true,               // ★ 디버깅·스택 트레이스에 필요

    /* 검사 강도 — 여기가 핵심 */
    "strict": true,                  // ★ TS 7 부터 기본값 (아래 항목들을 한 번에 켬)
    "noUncheckedIndexedAccess": true,// arr[0] 을 T|undefined 로 (강력 추천)
    "noImplicitOverride": true,      // override 키워드 강제
    "noUnusedLocals": true,          // 안 쓰는 변수 경고
    "exactOptionalPropertyTypes": false,  // 팀에 따라 (엄격하지만 번거로움)

    /* 호환 */
    "skipLibCheck": true,            // ★ 빌드 속도 크게 개선
    "forceConsistentCasingInFileNames": true,  // 대소문자 (macOS↔Linux 사고 방지)
    "resolveJsonModule": true,       // JSON import 허용
    "types": ["node"],               // ★ TS 7 기본값이 [] — 필요한 것만 적습니다

    /* 데코레이터 (Nest·TypeORM) — TS 7 에서도 계속 지원됩니다 */
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    // ※ 데코레이터를 쓰면 "erasableSyntaxOnly": true 는 켤 수 없습니다

    /* 경로 별칭 — baseUrl 없이, tsconfig 위치 기준 상대경로로 */
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

strict 가 켜는 것들

// noUncheckedIndexedAccess 를 켜면 이렇게 바뀝니다
const arr = [1, 2, 3];
const n = arr[10];        // number | undefined ★ (기본은 number)
n.toFixed();              // ❌ 에러 — 실제로 undefined 일 수 있으니까

// 번거롭지만 "배열 인덱스 접근"으로 인한 런타임 에러를 근본적으로 막습니다
const first = arr[0];
if (first !== undefined) first.toFixed();   // ✅

경로 별칭은 두 곳을 맞춰야 합니다

tsconfig.json 의 paths 는 "타입 검사"만 압니다.
실제 실행 시에는 경로를 못 찾습니다.

해결책 (하나 고르세요)
  · 번들러 사용 (Vite·tsup) → 번들러 설정에도 alias 추가
  · tsc-alias → 빌드 후 경로를 실제 상대경로로 치환
  · package.json 의 "imports" 사용 (#utils/*) → 런타임이 직접 이해 ★
  · tsx 실행기 → tsconfig paths 를 런타임에 해석 (개발용)

① 불가능한 상태를 표현할 수 없게 만들기

type State = {
  isLoading: boolean;
  data?: User;
  error?: Error;
};
// isLoading 이면서 error 도
// 있는 상태가 "표현 가능"
// → 버그의 온상

type State =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success";
      data: User }
  | { status: "error";
      error: Error };
// 잘못된 조합이 불가능 ★

② 원시 타입 남용 피하기 (branded type)

// ❌ 둘 다 number — 순서를 바꿔 넣어도 통과합니다
function transfer(fromUserId: number, toAccountId: number) { }

// ✅ 브랜드를 붙여 구분
type UserId = number & { readonly __brand: "UserId" };
type AccountId = number & { readonly __brand: "AccountId" };

const toUserId = (n: number) => n as UserId;

function transfer2(from: UserId, to: AccountId) { }
transfer2(accountId, userId);   // ❌ 컴파일 에러 ★ 사고를 막습니다

③ 계층별 타입 분리

// DB 엔티티 (내부)
interface UserEntity {
  id: number; email: string; passwordHash: string;
  createdAt: Date; deletedAt: Date | null;
}

// API 응답 (외부) — ★ 엔티티를 그대로 내보내지 마세요
type UserDto = Omit<UserEntity, "passwordHash" | "deletedAt" | "createdAt"> & {
  createdAt: string;                  // 날짜는 ISO 문자열로
};
// ★ createdAt 도 Omit 에 넣어야 합니다 — 안 빼면 Date & string 이 되어
//   아래 toDto 의 toISOString() 결과를 넣을 수 없습니다

// 요청 (입력)
type CreateUserDto = Pick<UserEntity, "email"> & { password: string };

// 변환은 한 곳에서
const toDto = (e: UserEntity): UserDto => ({
  id: e.id, email: e.email, createdAt: e.createdAt.toISOString(),
});

④ 스키마에서 타입 뽑기 (요즘 표준)

import { z } from "zod";

// 한 번만 정의하면 검증과 타입이 동시에 나옵니다
export const CreateUserSchema = z.object({
  email: z.email(),
  password: z.string().min(8),
  age: z.number().int().positive().optional(),
});

export type CreateUser = z.infer<typeof CreateUserSchema>;   // ★ 타입 자동 생성

// 컨트롤러에서
const body = CreateUserSchema.parse(req.body);   // 검증 + 타입 확정
body.email;      // string 으로 안전하게

자주 만나는 에러

// 7053 의 전형적인 경우
const colors = { red: "#f00", blue: "#00f" };
function get(key: string) {
  return colors[key];    // ❌ 7053
}
// ✅ 해결 1 — 키를 좁히기
function get2(key: keyof typeof colors) { return colors[key]; }
// ✅ 해결 2 — 사전 타입으로 선언
const colors2: Record<string, string> = { ... };

초과 속성 검사 — 헷갈리는 규칙

interface Opts { a: number }

// ❌ 객체 리터럴을 직접 넣으면 "초과 속성"을 잡습니다
const x: Opts = { a: 1, b: 2 };        // 에러 ★

// ✅ 변수를 거치면 통과합니다 (구조적 타이핑)
const tmp = { a: 1, b: 2 };
const y: Opts = tmp;                    // 통과 (놀랍게도)

// 이유: 리터럴은 "오타를 잡아 주려고" 특별히 엄격하게 봅니다.
// 변수는 "더 많은 속성이 있어도 조건은 만족한다"고 판단합니다.

에러 메시지 읽는 요령

Type '{ id: string; }' is not assignable to type 'User'.
  Types of property 'id' are incompatible.
    Type 'string' is not assignable to type 'number'.   ← ★ 여기가 진짜 원인

규칙
  · 들여쓰기가 가장 깊은 마지막 줄부터 읽으세요
  · 긴 타입은 에디터에서 해당 부분에 커서를 올려 확인
  · 라이브러리 타입 에러라면 skipLibCheck 로 일단 걸러 보기

타입으로 하는 재귀

// 문자열 뒤집기
type Reverse<S extends string> =
  S extends `${infer H}${infer R}` ? `${Reverse<R>}${H}` : "";
type A = Reverse<"hello">;      // "olleh"

// 문자열을 구분자로 쪼개 튜플로
type Split<S extends string, D extends string> =
  S extends `${infer H}${D}${infer R}` ? [H, ...Split<R, D>] : [S];
type B = Split<"a,b,c", ",">;   // ["a", "b", "c"]

// 깊은 readonly
type DeepReadonly<T> = T extends (infer U)[]
  ? readonly DeepReadonly<U>[]
  : T extends object
    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
    : T;

// 중첩 객체의 경로 문자열 만들기 (i18n·폼 라이브러리가 쓰는 기법)
type Paths<T, P extends string = ""> = T extends object
  ? { [K in keyof T & string]:
      | (P extends "" ? K : `${P}.${K}`)
      | Paths<T[K], P extends "" ? K : `${P}.${K}`>
    }[keyof T & string]
  : never;

type C = Paths<{ user: { name: string; addr: { city: string } } }>;
// "user" | "user.name" | "user.addr" | "user.addr.city" ★

한계와 주의

제약
  · 재귀 깊이 제한 (기본 약 100, 꼬리 재귀 최적화 시 1000)
  · "Type instantiation is excessively deep" 에러를 만나게 됨
  · 타입 계산이 느려지면 에디터 자동완성이 눈에 띄게 느려짐
  · 유니온 조합이 커지면 폭발 (10 × 10 × 10 = 1000 가지)

측정
  tsc --diagnostics            # 타입 검사 시간·인스턴스 수
  tsc --generateTrace trace    # 어느 타입이 느린지 추적

그래도 알아 두면 좋은 이유

• 라이브러리 타입 에러를 해석할 수 있게 됩니다 — 실무에서 이게 제일 큽니다
• tRPC·Zod 처럼 타입이 자동으로 흘러가는 도구를 제대로 쓸 수 있습니다
• 사내 공통 라이브러리를 만들 때 쓰는 사람이 편한 API를 설계할 수 있습니다

무엇으로 이루어져 있나

언제 Node 를 고르나

버전 관리

# 2026-08 현재
#   24  Active LTS  (2026-10 까지 활성 · 2028-04 EOL)   ★ 운영 기본값
#   26  Current     (2026-10 에 LTS 승격 예정)
#   22  Maintenance (2027-04 EOL) — 신규 프로젝트에는 쓰지 마세요
#   20  EOL (2026-04) ❌
node -v

# ★ 2026-10 Node 27 부터 릴리스 정책이 바뀝니다
#   · 메이저는 매년 한 번만 · 홀짝 구분 폐지 — 모든 메이저가 LTS 로 승격
#   · 총 지원 36개월 (활성 18 + 유지보수 18)

# 버전 관리 도구 (프로젝트마다 다른 버전이 필요할 때)
nvm install 24 && nvm use 24        # 전통의 강자
fnm use 24                          # 더 빠른 대안

# 프로젝트에 버전 고정
echo "24" > .nvmrc
# package.json 에도 명시
{ "engines": { "node": ">=24" } }

ESM 프로젝트에서 자주 막히는 것

// ① __dirname 이 없다
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";

const __filename = fileURLToPath(import.meta.url);
const __dirname  = dirname(__filename);

// ★ Node 20.11+ 부터는 더 짧게
const __dirname2 = import.meta.dirname;
const __filename2 = import.meta.filename;

// ② require 가 없다 → CJS 전용 패키지를 쓰려면
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const legacy = require("old-cjs-package");

// ③ JSON import (Node 22+ 안정화)
import pkg from "./package.json" with { type: "json" };

// ④ 확장자를 반드시 적어야 한다
import { helper } from "./utils/helper.js";   // ★ .js 필수
// TypeScript 로 짜도 import 경로에는 .js 를 적습니다 (컴파일 결과 기준)

모듈 로딩 순서와 순환 참조

// a.js
import { bValue } from "./b.js";
export const aValue = "A";
console.log("a 에서 본 b:", bValue);

// b.js
import { aValue } from "./a.js";
export const bValue = "B";
console.log("b 에서 본 a:", aValue);   // ★ 여기서 터집니다

// 실행 결과 (node a.js)
//   ReferenceError: Cannot access 'aValue' before initialization
// a 가 아직 평가되지 않은 상태에서 b 가 a 를 읽었기 때문입니다
// (export const 는 초기화 전 접근이 에러입니다. CommonJS 였다면 조용히 undefined)

내장 모듈은 node: 접두어로

import fs from "node:fs/promises";     // ✅ 권장
import fs from "fs/promises";           // 동작은 하지만

// node: 를 쓰는 이유
//  · npm 에 같은 이름의 패키지가 있어도 안전 (혼동·공격 방지)
//  · 내장 모듈임이 한눈에 보임
//  · Deno·Bun 등 다른 런타임과의 호환

libuv 의 6단계 페이즈

   ┌───────────────────────────┐
┌─>│  timers                   │  setTimeout · setInterval
│  ├───────────────────────────┤
│  │  pending callbacks        │  일부 시스템 에러 콜백
│  ├───────────────────────────┤
│  │  idle, prepare            │  내부용
│  ├───────────────────────────┤     ┌────────────────┐
│  │  poll                     │<────│  들어오는 I/O   │
│  ├───────────────────────────┤     └────────────────┘
│  │  check                    │  setImmediate
│  ├───────────────────────────┤
└──┤  close callbacks          │  socket.on("close")
   └───────────────────────────┘

★ 매크로태스크 콜백이 하나 끝날 때마다 마이크로태스크 큐를
  전부 비웁니다 (process.nextTick → Promise 순서 · Node 11+)

// 이 순서가 보장되지 않는 유명한 예
setTimeout(() => console.log("timeout"), 0);
setImmediate(() => console.log("immediate"));
// 메인 모듈에서는 실행 시점에 따라 순서가 뒤바뀝니다

// 하지만 I/O 콜백 안에서는 항상 immediate 가 먼저
fs.readFile("f.txt", () => {
  setTimeout(() => console.log("timeout"), 0);
  setImmediate(() => console.log("immediate"));   // ★ 항상 이게 먼저
});
// poll 페이즈 다음이 check 페이즈이기 때문입니다

이벤트 루프 지연 측정 — 운영 필수 지표

import { monitorEventLoopDelay } from "node:perf_hooks";

const h = monitorEventLoopDelay({ resolution: 10 });
h.enable();

setInterval(() => {
  console.log({
    mean: h.mean / 1e6,        // 평균 지연 (ms)
    p99:  h.percentile(99) / 1e6,
    max:  h.max / 1e6,
  });
  h.reset();
}, 5000);

// 판단 기준
//   p99 < 10ms   정상
//   p99 > 50ms   무언가 메인 스레드를 막고 있음 ★
//   p99 > 200ms  사용자가 체감하는 수준 — 즉시 조사

메인 스레드를 막는 흔한 코드

// ① 동기 파일 API
const data = fs.readFileSync("big.json");     // ❌ 그동안 전부 정지
// → await fs.readFile() 로

// ② 큰 JSON
JSON.parse(hugeString);                        // ❌ 50MB 면 수백 ms
// → 스트리밍 파서(stream-json) 또는 워커로

// ③ 동기 암호화
crypto.pbkdf2Sync(pw, salt, 100000, 64, "sha512");   // ❌
// → 비동기 버전 사용 (libuv 스레드 풀로 감)

// ④ 큰 배열 반복
hugeArray.map(heavyTransform);                 // ❌ 100만 건이면 수 초
// → 청크로 나눠 setImmediate 사이에 양보하거나 워커로

// 양보 패턴 (급할 때)
for (let i = 0; i < items.length; i++) {
  handleItem(items[i]);         // ★ 이름을 process 로 지으면 전역 process 를 가립니다
  if (i % 1000 === 0) await new Promise(r => setImmediate(r));   // ★ 숨통
}

파일 다루기

import fs from "node:fs/promises";        // ★ 항상 promises 버전
import path from "node:path";

// 읽기 · 쓰기
const text = await fs.readFile("a.txt", "utf8");   // ★ 인코딩 지정 안 하면 Buffer
await fs.writeFile("b.txt", text, "utf8");
await fs.appendFile("log.txt", line + "\n");

// JSON
const conf = JSON.parse(await fs.readFile("config.json", "utf8"));
await fs.writeFile("out.json", JSON.stringify(data, null, 2));

// 존재 확인 — ★ existsSync 대신 이 방법
try {
  await fs.access(file, fs.constants.R_OK);
} catch { /* 없거나 권한 없음 */ }

// 디렉터리
await fs.mkdir("a/b/c", { recursive: true });     // 중간 경로까지 생성
const files = await fs.readdir("dir");
const entries = await fs.readdir("dir", { withFileTypes: true });
for (const e of entries) if (e.isDirectory()) ...;

// 재귀 탐색 (Node 20+)
const all = await fs.readdir("src", { recursive: true });

// 삭제 · 이동 · 복사
await fs.rm("dir", { recursive: true, force: true });
await fs.rename("a.txt", "b.txt");
await fs.cp("src", "dst", { recursive: true });

// 정보
const st = await fs.stat("a.txt");
st.size; st.mtime; st.isFile();

경로 — 문자열로 붙이지 마세요

// ❌ 윈도우에서 깨집니다
const p = dir + "/" + name;

// ✅ 항상 path 모듈
path.join(dir, "sub", name);          // 구분자 자동
path.resolve("a", "b");               // 절대 경로로
path.dirname(p); path.basename(p); path.extname(p);
path.parse(p);                        // { dir, base, name, ext }

// 확장자 바꾸기
path.format({ ...path.parse(p), base: undefined, ext: ".png" });

// ★ 경로 검증 — 보안상 매우 중요
const safe = path.resolve(UPLOAD_DIR, userInput);
if (!safe.startsWith(path.resolve(UPLOAD_DIR) + path.sep)) {
  throw new Error("잘못된 경로");     // ../../etc/passwd 차단
}

대용량이면 스트림으로 (n05)

// ❌ 2GB 파일을 메모리에 통째로
const data = await fs.readFile("huge.csv");   // OOM

// ✅ 한 줄씩
import { createReadStream } from "node:fs";
import { createInterface } from "node:readline";
const rl = createInterface({ input: createReadStream("huge.csv") });
for await (const line of rl) { ... }

왜 스트림인가

[통째로 읽기]  10GB 파일 → 메모리 10GB 필요 → 즉시 OOM
[스트림]       10GB 파일 → 64KB 씩 흘려보냄 → 메모리 수 MB

게다가 "첫 바이트가 도착하는 즉시" 처리를 시작할 수 있습니다.
파일 업로드·다운로드·CSV 처리·응답 압축이 전부 스트림입니다.

네 가지 종류

import { pipeline } from "node:stream/promises";
import { createReadStream, createWriteStream } from "node:fs";
import { createGzip } from "node:zlib";

// ★ pipeline 을 쓰세요 — 에러 처리와 정리를 알아서 해 줍니다
await pipeline(
  createReadStream("big.log"),
  createGzip(),
  createWriteStream("big.log.gz"),
);

// ❌ pipe 는 에러 시 스트림이 남아 메모리 누수가 됩니다
readable.pipe(gzip).pipe(writable);

직접 Transform 만들기

import { Transform } from "node:stream";

// CSV 한 줄씩 → 객체로 변환하며 필터링
const parseCsv = new Transform({
  objectMode: true,                 // ★ 객체를 흘려보낼 때 필수
  transform(chunk, enc, cb) {
    const [id, name, amount] = String(chunk).split(",");
    if (Number(amount) > 10000) {
      this.push({ id, name, amount: Number(amount) });
    }
    cb();                            // ★ 반드시 호출 (안 하면 멈춤)
  },
});

await pipeline(
  createReadStream("orders.csv"),
  splitLines,
  parseCsv,
  async function* (source) {         // 비동기 제너레이터도 됩니다
    for await (const row of source) {
      await db.insert(row);
      yield `${row.id} 처리\n`;
    }
  },
  createWriteStream("result.log"),
);

Buffer — 이진 데이터

const buf = Buffer.from("안녕", "utf8");
buf.length;                    // 6 (한글은 3바이트)
buf.toString("base64");        // "7JWI64WV"
Buffer.from(b64, "base64").toString("utf8");

// 자주 쓰는 곳
crypto.randomBytes(32).toString("hex");        // 토큰 생성
Buffer.concat([a, b]);                          // 청크 합치기

// ⚠️ 한글을 청크 경계에서 자르면 깨집니다
// → StringDecoder 를 쓰거나 스트림에 인코딩을 지정하세요
import { StringDecoder } from "node:string_decoder";

프레임워크 없이

import { createServer } from "node:http";

const server = createServer(async (req, res) => {
  // 라우팅을 직접 해야 합니다
  const url = new URL(req.url, `http://${req.headers.host}`);

  if (req.method === "GET" && url.pathname === "/health") {
    res.writeHead(200, { "Content-Type": "application/json" });
    return res.end(JSON.stringify({ ok: true }));
  }

  if (req.method === "POST" && url.pathname === "/api/users") {
    // ★ 본문도 직접 모아야 합니다 (스트림으로 옵니다)
    const chunks = [];
    for await (const c of req) chunks.push(c);
    const body = JSON.parse(Buffer.concat(chunks).toString());
    res.writeHead(201, { "Content-Type": "application/json" });
    return res.end(JSON.stringify({ id: 1, ...body }));
  }

  res.writeHead(404).end("Not Found");
});

server.listen(3000, () => console.log("http://localhost:3000"));

운영에서 반드시 챙길 것

// ① 타임아웃 (기본값이 관대합니다)
server.requestTimeout = 30_000;      // 요청 하나의 최대 시간
server.headersTimeout = 10_000;      // 헤더 수신 대기
server.keepAliveTimeout = 65_000;    // ★ 로드밸런서보다 길게!

// ② 우아한 종료 — 무중단 배포의 핵심
process.on("SIGTERM", async () => {
  console.log("종료 신호 수신");
  server.close(async () => {          // 새 연결 차단, 진행 중인 요청은 완료
    await db.end();
    await redis.quit();
    process.exit(0);
  });
  setTimeout(() => process.exit(1), 30_000).unref();   // 강제 종료 안전장치
});

// ③ 요청 본문 크기 제한 (안 하면 메모리 공격에 노출)
let size = 0;
for await (const c of req) {
  size += c.length;
  if (size > 1_000_000) { res.writeHead(413).end(); return; }
}

HTTP 클라이언트 — 내장 fetch

// Node 18+ 는 fetch 가 내장입니다 (axios 없이도 충분)
const res = await fetch("https://api.example.com/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ q: 1 }),
  signal: AbortSignal.timeout(3000),        // ★ 타임아웃 필수
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

// 커넥션 재사용 (성능 차이가 큽니다)
import { Agent, setGlobalDispatcher } from "undici";
setGlobalDispatcher(new Agent({ keepAliveTimeout: 60_000, connections: 100 }));

기본 사용

import { EventEmitter, once, on } from "node:events";

class OrderService extends EventEmitter {
  async create(dto) {
    const order = await this.repo.save(dto);
    this.emit("created", order);        // ★ 알림만 하고 신경 안 씀
    return order;
  }
}

const svc = new OrderService();
svc.on("created", (o) => sendMail(o));       // 여러 개 등록 가능
svc.on("created", (o) => updateStats(o));
svc.once("ready", () => init());              // 한 번만

// Promise 로 기다리기
const [order] = await once(svc, "created");

// 비동기 이터레이터로 받기
for await (const [order] of on(svc, "created")) { ... }

// 정리
svc.off("created", handler);
svc.removeAllListeners("created");

실무에서 주의할 점

// ① 비동기 리스너의 에러는 잡히지 않습니다
svc.on("created", async (o) => {
  await sendMail(o);            // ❌ 실패하면 unhandledRejection
});

// ✅ 반드시 감싸세요
svc.on("created", (o) => {
  sendMail(o).catch(err => logger.error({ err }, "메일 발송 실패"));
});

// ② "error" 이벤트는 특별합니다 — 리스너가 없으면 프로세스가 죽습니다
emitter.emit("error", new Error("펑"));   // 리스너 없으면 crash
emitter.on("error", (e) => logger.error(e));   // ★ 반드시 등록

// ③ emit 은 동기입니다
emitter.emit("x");            // 모든 리스너가 "즉시" 순서대로 실행됨
console.log("이 줄은 리스너들이 다 끝난 뒤에 실행됩니다");

언제 쓰고 언제 쓰지 말까

환경 변수 다루기

process.env.NODE_ENV;          // 항상 string | undefined
process.argv.slice(2);         // CLI 인자
process.cwd();                 // 실행 위치 (파일 위치와 다릅니다!)
process.pid; process.uptime(); process.memoryUsage();

// Node 20+ 는 .env 를 내장으로 읽습니다 (dotenv 불필요)
// node --env-file=.env app.js

// ★ 시작할 때 한 번 검증하세요 — 실무 필수 패턴
import { z } from "zod";

const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "production", "test"]),
  PORT: z.coerce.number().default(3000),        // 문자열 → 숫자 변환
  DATABASE_URL: z.url(),
  JWT_SECRET: z.string().min(32),
  REDIS_URL: z.url().optional(),
});

export const env = EnvSchema.parse(process.env);
// ★ 값이 없거나 형식이 틀리면 "부팅 시점에" 죽습니다.
//   운영 중에 undefined 로 터지는 것보다 백 배 낫습니다.

env.PORT;        // number 로 타입까지 확정됨

시그널과 우아한 종료

// 컨테이너는 종료할 때 SIGTERM 을 보냅니다
async function shutdown(signal) {
  logger.info({ signal }, "종료 시작");

  server.close();                    // ① 새 요청 안 받기
  await new Promise(r => setTimeout(r, 5000));   // ② LB 가 알아챌 시간
  await queue.close();               // ③ 작업 큐 정리
  await db.end();                    // ④ DB 커넥션 반납
  await redis.quit();

  logger.info("정상 종료");
  process.exit(0);
}

process.on("SIGTERM", () => shutdown("SIGTERM"));   // 컨테이너·PM2
process.on("SIGINT",  () => shutdown("SIGINT"));    // Ctrl+C

// 안전장치 — 30초 안에 못 끝내면 강제 종료
process.on("SIGTERM", () => {
  setTimeout(() => { logger.fatal("강제 종료"); process.exit(1); },
             30_000).unref();
});

종료 코드

0    정상
1    일반 오류
137  SIGKILL — ★ 컨테이너 메모리 초과(OOMKilled)일 가능성이 높음
143  SIGTERM — 정상적인 종료 요청

"이유 없이 재시작된다" 면 종료 코드부터 확인하세요.
137 이면 애플리케이션 로그에는 아무것도 안 남습니다.

무엇을 언제 쓰나

워커 스레드 — CPU 작업 분리

// heavy-worker.js
import { parentPort, workerData } from "node:worker_threads";

function heavyCalc(data) { /* 오래 걸리는 계산 */ return result; }

parentPort.postMessage(heavyCalc(workerData));

// main.js — Promise 로 감싸 쓰기
import { Worker } from "node:worker_threads";

function runWorker(data) {
  return new Promise((resolve, reject) => {
    const w = new Worker("./heavy-worker.js", { workerData: data });
    w.on("message", resolve);
    w.on("error", reject);
    w.on("exit", (code) => {
      if (code !== 0) reject(new Error(`워커 종료 코드 ${code}`));
    });
  });
}

app.post("/report", async (req, res) => {
  const result = await runWorker(req.body);   // ★ 메인 스레드는 계속 다른 요청 처리
  res.json(result);
});

워커 풀 — 실무 형태

import Piscina from "piscina";

const pool = new Piscina({
  filename: new URL("./worker.js", import.meta.url).href,
  maxThreads: 4,               // ★ CPU 코어 수 이하로
  idleTimeout: 30_000,
});

const result = await pool.run({ imagePath });   // 알아서 풀에서 배정

클러스터 — 코어를 다 쓰기

import cluster from "node:cluster";
import { availableParallelism } from "node:os";

if (cluster.isPrimary) {
  const n = availableParallelism();
  for (let i = 0; i < n; i++) cluster.fork();

  cluster.on("exit", (worker, code) => {
    logger.warn({ pid: worker.process.pid, code }, "워커 종료 — 재시작");
    cluster.fork();                        // ★ 죽으면 다시 띄우기
  });
} else {
  startServer();                           // 워커들이 같은 포트를 공유합니다
}

# PM2 — 코드 수정 없이 클러스터 + 무중단 재시작
pm2 start dist/index.js -i max        # 코어 수만큼
pm2 reload app                        # ★ 무중단 재시작
pm2 monit

네 가지 방법

import { execFile, spawn } from "node:child_process";
import { promisify } from "node:util";
const execFileAsync = promisify(execFile);

// ✅ 안전 — 인자를 배열로 넘기면 셸 해석이 없습니다
const { stdout } = await execFileAsync("git", ["log", "-1", "--format=%H"]);

// ❌ 위험 — 사용자 입력이 그대로 셸 명령이 됩니다
exec(`convert ${userInput} out.png`);
// userInput 이 "a.png; rm -rf /" 라면?

스트림으로 다루기

// ffmpeg 로 동영상 변환하며 진행률 받기
const ff = spawn("ffmpeg", [
  "-i", input, "-vf", "scale=640:-1", "-y", output,
]);

ff.stderr.on("data", (chunk) => {       // ffmpeg 는 stderr 로 진행률을 냅니다
  const m = String(chunk).match(/time=(\S+)/);
  if (m) sendProgress(m[1]);
});

await new Promise((resolve, reject) => {
  ff.on("close", (code) =>
    code === 0 ? resolve() : reject(new Error(`ffmpeg 실패 ${code}`)));
  ff.on("error", reject);               // ★ 실행 파일 자체가 없을 때
});

// 파이썬 스크립트에 데이터 넘기고 결과 받기
const py = spawn("python3", ["analyze.py"]);
py.stdin.write(JSON.stringify(data));
py.stdin.end();

let out = "";
for await (const c of py.stdout) out += c;
const result = JSON.parse(out);

문제 상황

// ❌ 10,000개 요청을 동시에 발사
await Promise.all(users.map(u => sendEmail(u)));

// 무슨 일이 일어나나
//   · 소켓 10,000개 동시 오픈 → EMFILE (파일 디스크립터 고갈)
//   · 메일 서버가 429/503 으로 차단
//   · 메모리에 10,000개의 Promise + 응답 버퍼
//   · DB 라면 커넥션 풀이 즉시 고갈
// ★ "동시에 몇 개까지" 를 반드시 정해야 합니다

직접 구현 — 개념 이해용

async function mapLimit(items, limit, fn) {
  const results = new Array(items.length);
  let index = 0;

  async function worker() {
    while (index < items.length) {
      const i = index++;                    // ★ 원자적으로 하나씩 가져감
      results[i] = await fn(items[i], i);
    }
  }

  await Promise.all(
    Array.from({ length: Math.min(limit, items.length) }, worker));
  return results;
}

await mapLimit(users, 10, sendEmail);       // 동시에 10개씩

실무 — 라이브러리를 쓰세요

import pLimit from "p-limit";
import pRetry from "p-retry";

const limit = pLimit(10);                   // 동시 10개

const results = await Promise.all(
  users.map(u => limit(() => sendEmail(u)))
);

// 재시도까지 조합 (지수 백오프 + 지터 내장)
await pLimit(5)(() =>
  pRetry(() => callFlakyApi(id), {
    retries: 3,
    minTimeout: 200,
    onFailedAttempt: (e) => logger.warn({ attempt: e.attemptNumber }),
  }));

// ★ 배치로 나눠 처리 (DB 대량 작업의 정석)
const chunk = (arr, n) =>
  Array.from({ length: Math.ceil(arr.length / n) },
             (_, i) => arr.slice(i * n, i * n + n));

for (const batch of chunk(rows, 1000)) {
  await db.insertMany(batch);               // 1,000건씩 커밋
  await new Promise(r => setImmediate(r));  // 이벤트 루프에 양보
}

프로세스를 죽이는 것들

// ① 처리되지 않은 예외
setTimeout(() => { throw new Error("펑"); }, 0);

// ② 처리되지 않은 Promise 거부 (Node 15+ 부터 기본이 crash)
async function f() { throw new Error("펑"); }
f();                       // await 도 catch 도 없음 → 프로세스 종료

// ③ EventEmitter 의 error 이벤트에 리스너 없음
socket.emit("error", err);

// ④ 메모리 초과 (OOM)
// ⑤ 스택 오버플로 (무한 재귀)

// 최상위 안전망 — 로그를 남기고 "깨끗하게" 종료
process.on("uncaughtException", (err, origin) => {
  logger.fatal({ err, origin }, "처리되지 않은 예외");
  // 여기서 계속 돌리면 안 됩니다 — 상태를 신뢰할 수 없습니다
  gracefulExit(1);
});

process.on("unhandledRejection", (reason) => {
  logger.fatal({ reason }, "처리되지 않은 Promise 거부");
  gracefulExit(1);
});

function gracefulExit(code) {
  server.close(() => process.exit(code));
  setTimeout(() => process.exit(code), 5000).unref();
}

운영 에러 vs 프로그래머 에러

// 에러 클래스로 구분 (🟨 JS j08 · 🚂 Express x06)
class AppError extends Error {
  constructor(msg, { status = 500, code, retryable = false } = {}) {
    super(msg);
    this.name = this.constructor.name;
    this.status = status; this.code = code;
    this.isOperational = true;              // ★ 이 플래그로 구분
    this.retryable = retryable;
  }
}

// 핸들러에서
if (err.isOperational) {
  res.status(err.status).json({ code: err.code, message: err.message });
} else {
  logger.error({ err }, "예상치 못한 오류");
  res.status(500).json({ message: "서버 오류" });   // ★ 내부 정보 노출 금지
}

스택 트레이스 제대로 보기

# async 스택이 잘려 보일 때
node --stack-trace-limit=50 app.js

# TypeScript 빌드 결과의 스택을 원본으로
npm i source-map-support
node -r source-map-support/register dist/index.js
# 또는 tsconfig 에 "sourceMap": true 후 --enable-source-maps 플래그
node --enable-source-maps dist/index.js

메모리 구조와 한도

process.memoryUsage();
// {
//   rss:        상주 메모리 전체 (컨테이너가 보는 값)
//   heapTotal:  V8 이 확보한 힙
//   heapUsed:   실제 사용 중인 힙  ★ 이게 계속 늘면 누수
//   external:   Buffer 등 힙 밖 (C++ 객체)
//   arrayBuffers: ArrayBuffer
// }

# 힙 한도 설정 — 컨테이너 메모리의 70~75% 정도로
node --max-old-space-size=1536 app.js        # 2GB 컨테이너 기준

# 안 정해도 Node 20+ 는 cgroup 한도를 읽어 기본 힙을 잡아 줍니다.
# 그래도 못 박아 두는 편이 사고를 줄입니다 (아래 설명)

메모리 누수의 흔한 원인

• 무한히 커지는 Map/배열 — 캐시에 TTL·최대 크기가 없음
• 해제 안 된 이벤트 리스너 — 요청마다 등록만 함
• 정리 안 된 타이머 — setInterval 을 clearInterval 안 함
• 클로저가 큰 객체를 붙잡음 — 응답 전체를 캡처한 콜백
• 전역 변수 누적 — 요청 정보를 모듈 스코프에 저장

측정 도구

# ① 힙 스냅샷 — 무엇이 메모리를 잡고 있나
node --inspect app.js
# Chrome 에서 chrome://inspect → Memory → Heap snapshot
# ★ 부하 전/후 두 장을 찍어 "Comparison" 으로 비교하는 것이 핵심

# 코드에서 직접 찍기
import { writeHeapSnapshot } from "node:v8";
writeHeapSnapshot("/tmp/heap.heapsnapshot");

# ② CPU 프로파일 — 어디서 시간을 쓰나
node --cpu-prof --cpu-prof-dir=./prof app.js
# .cpuprofile 파일을 Chrome DevTools 에 드래그

# ③ 간단한 벤치마크
import { performance } from "node:perf_hooks";
const t = performance.now();
doWork();
console.log(performance.now() - t, "ms");

# ④ 부하 테스트 (🚀 대규모 k13)
npx autocannon -c 100 -d 30 http://localhost:3000/api

성능 개선 순서

1) 측정한다                    ← 이걸 건너뛰면 대부분 헛수고
2) DB 쿼리를 본다              ← 90%가 여기 (인덱스·N+1)
3) 불필요한 await 를 병렬로     ← Promise.all
4) 이벤트 루프 지연을 확인      ← 동기 코드가 막고 있는지 (n03)
5) 캐시를 넣는다                ← Redis (🚀 k03)
6) CPU 작업을 워커로            ← n09
7) 그래도 부족하면 수평 확장     ← 🚀 k11

내장 테스트 러너 Node 20+

// test/user.test.js
import { test, describe, before, mock } from "node:test";
import assert from "node:assert/strict";

describe("UserService", () => {
  before(async () => { await db.migrate(); });

  test("이메일이 중복이면 실패한다", async () => {
    await createUser({ email: "a@b.c" });
    await assert.rejects(
      () => createUser({ email: "a@b.c" }),
      /중복/,
    );
  });

  test("모킹", () => {
    const fn = mock.fn(() => 42);
    assert.equal(fn(), 42);
    assert.equal(fn.mock.callCount(), 1);
  });
});

node --test                       # test/ 아래 전부 실행
node --test --watch                # 저장하면 재실행
node --test --experimental-test-coverage   # 커버리지

그 밖의 내장 기능

# 파일 감시 재시작 (nodemon 불필요)
node --watch src/index.js
node --watch-path=./src --watch-path=./config app.js

# .env 읽기 (dotenv 불필요)  Node 20.6+
node --env-file=.env --env-file=.env.local app.js

# TypeScript 를 그대로 실행 (Node 24+ 기본 · Node 26 에서 정식)
node src/index.ts
#  · 타입 "지우기"만 합니다 — 타입 검사는 tsc --noEmit 로 따로
#  · enum · 구 데코레이터 · namespace 같은 "코드를 만들어 내는" 문법은 안 됩니다
#    → tsconfig 에 "erasableSyntaxOnly": true 를 켜 두면 미리 막아 줍니다

# 단일 실행 파일로 패키징 (Node 20+, 실험적)
node --experimental-sea-config sea-config.json

Node 26 에서 새로 생긴 것

# package.json 의 scripts 를 npm 없이 바로 실행 — 훨씬 빠릅니다
#   (이건 Node 22 부터 정식 기능입니다. 24 에서도 그대로 됩니다)
node --run build
node --run test -- --grep user

# 테스트 러너 보강
node --test --test-random-order      # 순서 의존 테스트를 찾아냅니다
node --test --test-name-tag=slow     # 태그로 골라 실행

// SQLite 가 런타임에 들어 있습니다 (better-sqlite3 불필요)
//   22.13 · 23.4 부터 --experimental-sqlite 플래그가 필요 없고,
//   25.7 부터 "릴리스 후보" 단계입니다
import { DatabaseSync } from "node:sqlite";
const db = new DatabaseSync("app.db");
db.exec(`CREATE TABLE IF NOT EXISTS todo (id INTEGER PRIMARY KEY, t TEXT)`);
db.prepare("INSERT INTO todo (t) VALUES (?)").run("장보기");
console.log(db.prepare("SELECT * FROM todo").all());

// 새 표준 내장 (Node 26)
const cache = new Map();
cache.getOrInsertComputed("user:1", (k) => loadUser(k));  // 없으면 만들어 넣고 반환
for (const x of Iterator.concat([1, 2].values(), [3].values())) { /* 1,2,3 */ }

// Temporal 이 전역으로 들어왔습니다 (j-탭 날짜 절 참고)
Temporal.Now.instant().toString();   // 2026-08-04T05:00:00Z

// fetch · FormData · WebSocket 전부 내장 (Node 18+ / 22+)
const res = await fetch(url);
const ws = new WebSocket("wss://...");     // Node 22+

// 구조화 복제 · UUID · 타이머 Promise 버전
structuredClone(obj);
crypto.randomUUID();
import { setTimeout as sleep } from "node:timers/promises";
await sleep(1000);                          // ★ 깔끔한 지연

// 유용한 내장 유틸
import { parseArgs } from "node:util";      // CLI 인자 파싱 (Node 18.3+)
const { values } = parseArgs({
  options: { port: { type: "string", short: "p" } },
});

install vs ci

npm install          # lock 파일을 "고칠 수 있음" — 개발용
npm ci               # ★ lock 그대로 설치, node_modules 삭제 후 재설치
                     #   CI·Docker 는 반드시 이것 (재현성 + 속도)

npm install --save-exact pkg    # 정확한 버전으로 고정
npm outdated                    # 오래된 패키지 확인
npm update                      # semver 범위 안에서 갱신
npm audit                       # ★ 알려진 취약점 검사
npm audit fix                   # 자동 수정 (major 변경은 안 함)
npm ls pkg                      # 이 패키지가 왜 설치됐는지 추적

버전 표기 읽기

"express": "^5.2.1"     ^ = 마이너·패치 허용  5.x.x  ★ 기본값
"express": "~5.2.1"     ~ = 패치만 허용       5.2.x
"express": "5.2.1"      정확히 이 버전
"express": "*"          아무거나 — ❌ 절대 금지

★ lock 파일이 있으면 실제 설치 버전은 lock 이 결정합니다.
  그래서 lock 파일 커밋이 필수입니다.

실무 npm 스크립트

{
  "scripts": {
    "dev": "node --watch --env-file=.env src/index.js",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/index.js",

    "test": "node --test",
    "test:watch": "node --test --watch",

    "lint": "eslint . --max-warnings 0",
    "format": "prettier --write .",
    "typecheck": "tsc --noEmit",

    "check": "npm run typecheck && npm run lint && npm test",
    "prepare": "husky"
  }
}

# 스크립트에 인자 넘기기
npm run test -- --grep "user"

# 라이프사이클 훅 (자동 실행)
preinstall / postinstall / prepare / prepublishOnly

# ⚠️ postinstall 은 보안 위험입니다 — 악성 패키지의 주요 통로
npm ci --ignore-scripts        # 필요하면 차단

디버거 붙이기

# Chrome DevTools 로 디버깅
node --inspect src/index.js              # 9229 포트
node --inspect-brk src/index.js          # 첫 줄에서 멈춤
# chrome://inspect 에서 연결

# 컨테이너 안의 프로세스에 붙기
node --inspect=0.0.0.0:9229 app.js
docker run -p 9229:9229 ...

# VS Code 는 launch.json 없이도 "JavaScript Debug Terminal" 에서
# 그냥 npm run dev 하면 브레이크포인트가 걸립니다 ★

console 의 쓸모 있는 기능

console.table(users);                 // 객체 배열을 표로 ★
console.time("db"); ... console.timeEnd("db");
console.dir(obj, { depth: null });    // 깊은 객체 전부 펼치기
console.trace("여기까지 어떻게 왔나");  // 호출 스택
console.count("hit");                 // 호출 횟수

// 조건부 디버그 로그 (내장 util)
import { debuglog } from "node:util";
const debug = debuglog("app:db");
debug("쿼리 실행 %s", sql);           // NODE_DEBUG=app:db 일 때만 출력

운영 로깅 — pino

import pino from "pino";

export const logger = pino({
  level: process.env.LOG_LEVEL ?? "info",
  // ★ 비밀 값 마스킹 — 실수로 토큰을 로그에 남기는 사고를 막습니다
  redact: ["req.headers.authorization", "*.password", "*.creditCard"],
  formatters: { level: (label) => ({ level: label }) },
  // 개발에서만 예쁘게
  transport: process.env.NODE_ENV !== "production"
    ? { target: "pino-pretty" } : undefined,
});

logger.info({ userId: 1, orderId: "A-1" }, "주문 생성");
// {"level":"info","time":...,"userId":1,"orderId":"A-1","msg":"주문 생성"}

// 요청마다 추적 ID 붙이기 (여러 서비스의 로그를 잇는 열쇠)
import { AsyncLocalStorage } from "node:async_hooks";
const als = new AsyncLocalStorage();

app.use((req, res, next) => {
  const requestId = req.headers["x-request-id"] ?? crypto.randomUUID();
  als.run({ requestId }, next);           // ★ 이 요청의 모든 비동기 흐름에 전파
});

// 어디서든 꺼내 쓸 수 있습니다 (매개변수로 넘길 필요 없음)
export const log = (obj, msg) =>
  logger.info({ ...obj, ...als.getStore() }, msg);

세 런타임 비교 2026

같은 서버, 세 가지 방식

// ① Node — server.mjs   $ node server.mjs
import { createServer } from "node:http";

createServer((req, res) => {
  res.writeHead(200, { "content-type": "application/json" });
  res.end(JSON.stringify({ runtime: "node", v: process.version }));
}).listen(3000);

// ② Deno — server.ts   $ deno run --allow-net server.ts
Deno.serve({ port: 3000 }, (_req: Request) =>
  Response.json({ runtime: "deno", v: Deno.version.deno }));
// ★ TS 를 그대로 실행합니다. 빌드 단계가 없습니다.

// ③ Bun — server.ts   $ bun server.ts
Bun.serve({
  port: 3000,
  fetch: (_req: Request) => Response.json({ runtime: "bun", v: Bun.version }),
});
// ★ Deno·Bun 은 둘 다 "요청 → Response 반환" 이라는
//   표준 Fetch 모델을 씁니다. Hono 같은 프레임워크가
//   세 런타임에서 같은 코드로 도는 이유입니다.

Bun — 진짜 강점과 아직 조심할 점

Deno 2 — 권한 모델이 핵심

# Deno 는 "기본값이 아무것도 못 함" 입니다
deno run server.ts                    # ❌ 네트워크 접근에서 즉시 거부
deno run --allow-net=:3000 server.ts  # 포트만 열어 줌
deno run --allow-read=./data \
         --allow-env=PORT,DATABASE_URL \
         --allow-net=api.example.com server.ts   # ★ 화이트리스트

deno run -A server.ts                 # 전부 허용 — 편하지만 의미가 사라집니다

# npm 패키지를 그대로 (Deno 2)
import express from "npm:express@5";
deno install                          # package.json · node_modules 인식

지금 새 프로젝트를 시작한다면

마이그레이션에서 실제로 걸리는 것들

• 네이티브 애드온 — 제일 먼저 깨집니다. 목록부터 뽑으세요 (npm ls --all | grep -i "gyp\|napi")
• node: 내장 모듈의 가장자리 — cluster·vm· async_hooks·v8 은 호환이 부분적입니다
• APM · 프로파일러 — Datadog·Sentry 에이전트가 Node 전용인 경우가 많습니다
• 도커 이미지·베이스 OS — 배포 파이프라인 전체를 같이 바꿔야 합니다(🧰 도구 o12)
• 팀 — “새벽 3시에 이 런타임을 디버깅할 사람이 있는가”가 마지막 질문입니다

최소 구성

import express from "express";

const app = express();
app.use(express.json());                 // ★ JSON 본문 파싱 (없으면 req.body 가 undefined)

app.get("/health", (req, res) => {
  res.json({ ok: true, uptime: process.uptime() });
});

app.get("/api/users/:id", async (req, res) => {
  const user = await db.user.findUnique({ where: { id: Number(req.params.id) } });
  if (!user) return res.status(404).json({ message: "없습니다" });
  res.json(user);
});

app.post("/api/users", async (req, res) => {
  const created = await db.user.create({ data: req.body });
  res.status(201).json(created);
});

const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => console.log(`http://localhost:${port}`));

실무 초기 세팅

import express from "express";
import helmet from "helmet";
import cors from "cors";
import compression from "compression";
import pinoHttp from "pino-http";

const app = express();

app.set("trust proxy", 1);              // ★ LB 뒤에 있으면 필수 (실제 IP·https 인식)
app.disable("x-powered-by");            // 서버 정보 숨기기

app.use(helmet());                       // 보안 헤더 (x10)
app.use(cors({ origin: env.ALLOWED_ORIGINS.split(",") }));
app.use(compression());                  // 응답 gzip
app.use(express.json({ limit: "1mb" })); // ★ 크기 제한 필수
app.use(express.urlencoded({ extended: true }));
app.use(pinoHttp({ logger }));           // 요청 로그

app.use("/api/users", userRouter);        // 라우터 등록 (x02)
app.use(notFoundHandler);                 // 404
app.use(errorHandler);                    // ★ 에러는 항상 맨 마지막 (x06)

라우터로 나누기

// routes/user.routes.ts
import { Router } from "express";
const router = Router();

router.get("/", listUsers);
router.get("/:id", getUser);
router.post("/", validate(CreateUserSchema), createUser);
router.patch("/:id", requireAuth, updateUser);
router.delete("/:id", requireAuth, requireRole("admin"), deleteUser);

export default router;

// app.ts
app.use("/api/users", userRouter);       // 앞에 붙는 경로를 여기서 결정
app.use("/api/orders", orderRouter);

경로 패턴

app.get("/users/:id", ...)               // req.params.id
app.get("/users/:id/orders/:orderId")    // 여러 개
app.get("/files/*splat", ...)            // Express 5 의 와일드카드
app.get(/^\/api\/v[12]\//, ...)          // 정규식도 가능

// 쿼리스트링
// GET /users?page=2&size=20&sort=name
req.query.page     // "2"  ★ 항상 문자열 (숫자 변환 필요)

// ★ 순서가 중요합니다 — 먼저 매칭된 것이 이깁니다
router.get("/me", getMe);          // 이게 위에 있어야
router.get("/:id", getUser);       // "me" 가 id 로 잡히지 않습니다

폴더 구조 — 기능 단위로 나누세요

src/
  controllers/
    user.controller.ts
    order.controller.ts
    ...20개
  services/
    ...20개
  routes/
    ...20개
→ 기능 하나 고치려면
  폴더 5개를 오감

src/
  modules/
    user/
      user.routes.ts
      user.service.ts
      user.schema.ts
      user.test.ts
    order/
      ...
  shared/
    middleware/
    db.ts
  app.ts

// 계층 역할을 지키세요 (Nest 와 같은 원칙)
// routes    — URL 매칭, 미들웨어 연결만
// service   — 비즈니스 규칙 (여기에 req/res 를 넘기지 마세요 ★)
// repository— DB 접근

// ❌ 서비스가 HTTP 를 알면 테스트도 재사용도 어려워집니다
export async function createUser(req: Request, res: Response) { ... }

// ✅ 서비스는 순수한 입력·출력
export async function createUser(dto: CreateUserDto): Promise<User> { ... }

동작 구조

요청 →  [helmet] → [json 파싱] → [로거] → [인증] → [핸들러] → 응답
                                                    ↓ next(err)
                                              [에러 미들웨어]

· next()      다음 미들웨어로
· next(err)   ★ 에러 미들웨어로 건너뜀
· 아무것도 안 하면 → 요청이 그대로 멈춥니다 (타임아웃)
· res 를 보내면 → 체인 종료

// 미들웨어는 그냥 함수 3개(또는 4개) 짜리입니다
const requestTime: RequestHandler = (req, res, next) => {
  const start = Date.now();
  res.on("finish", () => {                 // ★ 응답이 끝난 뒤 실행
    logger.info({ ms: Date.now() - start, path: req.path }, "요청 완료");
  });
  next();                                   // ★ 반드시 호출
};

// 에러 미들웨어는 인자가 4개 (이 시그니처로 구분합니다)
const errorHandler: ErrorRequestHandler = (err, req, res, next) => { ... };

실무에서 만드는 미들웨어

// ① 인증 — req 에 사용자 정보를 붙임
export const requireAuth: RequestHandler = (req, res, next) => {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return next(new UnauthorizedError());
  try {
    req.user = jwt.verify(token, env.JWT_SECRET) as JwtPayload;
    next();
  } catch {
    next(new UnauthorizedError("토큰이 유효하지 않습니다"));
  }
};

// ② 권한 — 매개변수를 받는 미들웨어는 "함수를 반환"하는 형태
export const requireRole = (...roles: string[]): RequestHandler =>
  (req, res, next) =>
    roles.includes(req.user?.role ?? "")
      ? next()
      : next(new ForbiddenError());

// ③ async 래퍼 (Express 4 에서 필수, 5 에서는 불필요)
export const asyncHandler = (fn: RequestHandler): RequestHandler =>
  (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);

router.get("/:id", asyncHandler(async (req, res) => {
  const user = await service.find(req.params.id);   // 던져도 안전
  res.json(user);
}));

요청에서 값 꺼내기

// ★ 숫자 변환을 잊지 마세요 — 흔한 버그
const page = Number(req.query.page ?? 1);
if (!Number.isInteger(page) || page < 1) throw new ValidationError("page");

// 배열로 올 수도 있습니다: ?tag=a&tag=b → ["a","b"]
const tags = [req.query.tag ?? []].flat();

// ★ 실무에서는 검증 라이브러리로 한 번에 처리하세요 (x05)

응답 보내기

res.json({ data });                     // JSON (Content-Type 자동)
res.status(201).json(created);
res.status(204).end();                  // 본문 없음 (삭제 성공)
res.redirect(302, "/login");
res.sendFile(path.resolve("public/a.pdf"));
res.download(filePath, "보고서.pdf");    // 다운로드 헤더 자동
res.set("Cache-Control", "public, max-age=3600");
res.cookie("token", t, {
  httpOnly: true, secure: true, sameSite: "lax", maxAge: 3600_000,
});

// 스트리밍 응답 (큰 파일 — 메모리 절약)
import { pipeline } from "node:stream/promises";
await pipeline(createReadStream(bigFile), res);

// SSE (실시간 알림)
res.writeHead(200, {
  "Content-Type": "text/event-stream",
  "Cache-Control": "no-cache",
  Connection: "keep-alive",
});
const timer = setInterval(() => res.write(`data: ${Date.now()}\n\n`), 1000);
req.on("close", () => clearInterval(timer));   // ★ 정리 필수

스키마 정의

import { z } from "zod";

export const CreateUserSchema = z.object({
  email: z.email("이메일 형식이 아닙니다"),
  password: z.string().min(8, "8자 이상").regex(/[0-9]/, "숫자 포함"),
  name: z.string().min(1).max(50),
  age: z.number().int().positive().optional(),
  role: z.enum(["user", "admin"]).default("user"),
  tags: z.array(z.string()).max(10).default([]),
});

export type CreateUserDto = z.infer<typeof CreateUserSchema>;   // ★ 타입 자동 생성

// 쿼리는 문자열로 오므로 변환이 필요합니다
export const ListQuerySchema = z.object({
  page: z.coerce.number().int().min(1).default(1),     // ★ "2" → 2
  size: z.coerce.number().int().min(1).max(100).default(20),
  keyword: z.string().trim().optional(),
});

미들웨어로 연결

type Target = "body" | "query" | "params";

export const validate =
  (schema: z.ZodTypeAny, target: Target = "body"): RequestHandler =>
  (req, res, next) => {
    const result = schema.safeParse(req[target]);
    if (!result.success) {
      return res.status(400).json({
        message: "입력값이 올바르지 않습니다",
        errors: result.error.issues.map(i => ({
          field: i.path.join("."),
          message: i.message,
        })),
      });
    }
    if (target === "query") {
      // ★ Express 5 에서 req.query 는 getter 전용 — 재할당하면 TypeError
      Object.defineProperty(req, "query", { value: result.data });
    } else {
      req[target] = result.data;      // ★ 변환·기본값이 적용된 값으로 교체
    }
    next();
  };

// 사용
router.post("/", validate(CreateUserSchema), async (req, res) => {
  const dto = req.body as CreateUserDto;    // ✅ 검증·변환 완료된 값
  res.status(201).json(await service.create(dto));
});

중앙 집중 에러 처리

// errors.ts — 도메인 에러 정의
export class AppError extends Error {
  constructor(
    message: string,
    public status = 500,
    public code = "INTERNAL_ERROR",
    public details?: unknown,
  ) { super(message); this.name = this.constructor.name; }
}
export class NotFoundError extends AppError {
  constructor(what = "리소스") { super(`${what}를 찾을 수 없습니다`, 404, "NOT_FOUND"); }
}
export class UnauthorizedError extends AppError {
  constructor(m = "인증이 필요합니다") { super(m, 401, "UNAUTHORIZED"); }
}
export class ForbiddenError extends AppError {
  constructor(m = "권한이 없습니다") { super(m, 403, "FORBIDDEN"); }
}
export class ConflictError extends AppError {
  constructor(m: string) { super(m, 409, "CONFLICT"); }
}

// middleware/error.ts — ★ 앱에서 마지막에 등록
export const errorHandler: ErrorRequestHandler = (err, req, res, _next) => {
  const requestId = req.headers["x-request-id"];

  if (err instanceof AppError) {
    logger.warn({ err, requestId, path: req.path }, "처리된 오류");
    return res.status(err.status).json({
      code: err.code, message: err.message, details: err.details, requestId,
    });
  }

  // 라이브러리 에러 변환
  if (err instanceof z.ZodError) {
    return res.status(400).json({ code: "VALIDATION_ERROR", errors: err.issues });
  }
  if (err.code === "P2002") {             // Prisma 유니크 위반
    return res.status(409).json({ code: "DUPLICATE", message: "이미 존재합니다" });
  }

  // 예상 못 한 에러 — ★ 내부 정보를 노출하지 마세요
  logger.error({ err, requestId, path: req.path }, "예상치 못한 오류");
  res.status(500).json({
    code: "INTERNAL_ERROR", message: "서버 오류가 발생했습니다", requestId,
  });
};

컨트롤러가 깨끗해집니다

router.get("/:id",
  async (req, res) => {
  try {
    const u = await find(id);
    if (!u) return res.status(404)
      .json({ message: "없음" });
    res.json(u);
  } catch (e) {
    console.error(e);
    res.status(500)
      .json({ message: "오류" });
  }
});

router.get("/:id",
  async (req, res) => {
  const u = await find(id);
  if (!u) throw new NotFoundError("사용자");
  res.json(u);
});
// 에러 미들웨어가
// 알아서 처리 ★
// (Express 5 기준)

404 와 프로세스 레벨

// 어떤 라우트에도 안 걸린 요청
app.use((req, res) => {
  res.status(404).json({ code: "NOT_FOUND", message: `${req.method} ${req.path}` });
});
app.use(errorHandler);       // ★ 반드시 맨 마지막

// 프로세스 레벨 안전망 (🟩 Node n12)
process.on("unhandledRejection", (e) => { logger.fatal({ e }); process.exit(1); });

무엇을 고를까

JWT 구현

import jwt from "jsonwebtoken";
import bcrypt from "bcrypt";

// 회원가입 — 비밀번호는 반드시 해시
const hash = await bcrypt.hash(password, 12);      // ★ 평문 저장 절대 금지

// 로그인
const ok = await bcrypt.compare(password, user.passwordHash);
if (!ok) throw new UnauthorizedError("아이디 또는 비밀번호가 올바르지 않습니다");
//        ★ "비밀번호가 틀렸습니다" 라고 하면 계정 존재 여부가 새어 나갑니다

const accessToken = jwt.sign(
  { sub: String(user.id), role: user.role },
  env.JWT_SECRET,
  { expiresIn: "15m", issuer: "my-api" },
);
const refreshToken = crypto.randomUUID();
await redis.set(`refresh:${refreshToken}`, user.id, { EX: 60 * 60 * 24 * 14 });

res.cookie("refresh", refreshToken, {
  httpOnly: true, secure: true, sameSite: "strict", path: "/auth",
});
// ★ path 는 이 쿠키를 쓰는 라우트를 모두 포함해야 합니다
//   (/auth/refresh 로 좁히면 /auth/logout 에는 쿠키가 안 실려 로그아웃이 안 됩니다)
res.json({ accessToken });

검증 · 갱신 · 로그아웃

// 검증 미들웨어
export const requireAuth: RequestHandler = (req, _res, next) => {
  const token = req.headers.authorization?.split(" ")[1];
  if (!token) return next(new UnauthorizedError());
  try {
    const payload = jwt.verify(token, env.JWT_SECRET, { issuer: "my-api" });
    req.user = { id: Number(payload.sub), role: payload.role };
    next();
  } catch (e) {
    next(e instanceof jwt.TokenExpiredError
      ? new UnauthorizedError("토큰이 만료되었습니다")
      : new UnauthorizedError());
  }
};

// 갱신 — 리프레시 토큰 회전(rotation)
router.post("/auth/refresh", async (req, res) => {
  const rt = req.cookies.refresh;
  const userId = await redis.get(`refresh:${rt}`);
  if (!userId) throw new UnauthorizedError("다시 로그인해 주세요");

  await redis.del(`refresh:${rt}`);            // ★ 한 번 쓰면 폐기
  // 새 토큰 발급…
});

// 로그아웃 — 리프레시만 지우면 됩니다 (액세스는 15분 뒤 자동 만료)
router.post("/auth/logout", async (req, res) => {
  await redis.del(`refresh:${req.cookies.refresh}`);
  res.clearCookie("refresh").status(204).end();
});

업로드 — multer

import multer from "multer";

const upload = multer({
  storage: multer.diskStorage({
    destination: (req, file, cb) => cb(null, env.UPLOAD_DIR),
    filename: (req, file, cb) =>
      // ★ 사용자 파일명을 그대로 쓰지 마세요
      cb(null, `${crypto.randomUUID()}${path.extname(file.originalname)}`),
  }),
  limits: {
    fileSize: 5 * 1024 * 1024,        // ★ 5MB 제한 (없으면 디스크가 찹니다)
    files: 5,
  },
  fileFilter: (req, file, cb) => {
    const allowed = ["image/jpeg", "image/png", "image/webp"];
    if (!allowed.includes(file.mimetype))
      return cb(new ValidationError("이미지만 업로드할 수 있습니다"));
    cb(null, true);
  },
});

router.post("/upload", requireAuth, upload.single("file"), (req, res) => {
  res.status(201).json({ filename: req.file!.filename });
});

실무 — 클라우드 스토리지 직접 업로드

// ★ 서버를 거치지 않는 것이 정답입니다
// 서버는 "업로드 허가증(presigned URL)"만 발급합니다
import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

router.post("/upload-url", requireAuth, async (req, res) => {
  const key = `uploads/${req.user.id}/${crypto.randomUUID()}.jpg`;
  const url = await getSignedUrl(
    s3,
    new PutObjectCommand({ Bucket: env.S3_BUCKET, Key: key, ContentType: "image/jpeg" }),
    { expiresIn: 300 },              // 5분간 유효
  );
  res.json({ uploadUrl: url, key });
});

// 클라이언트가 직접 S3 로 PUT → 서버 대역폭·메모리 0 ★

다운로드

router.get("/files/:id", requireAuth, async (req, res) => {
  const file = await db.file.findUnique({ where: { id: req.params.id } });
  if (!file) throw new NotFoundError("파일");
  if (file.ownerId !== req.user.id) throw new ForbiddenError();   // ★ 권한 확인

  // 경로 검증 (n04)
  const abs = path.resolve(env.UPLOAD_DIR, file.storedName);
  if (!abs.startsWith(path.resolve(env.UPLOAD_DIR) + path.sep))
    throw new ForbiddenError();

  res.download(abs, file.originalName);       // 한글 파일명도 자동 인코딩
});

스키마와 클라이언트

// prisma/schema.prisma
model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String
  orders    Order[]
  createdAt DateTime @default(now())

  @@index([createdAt])
}

model Order {
  id       Int    @id @default(autoincrement())
  userId   Int
  user     User   @relation(fields: [userId], references: [id])
  amount   Int
  status   OrderStatus @default(PENDING)
}

enum OrderStatus { PENDING PAID CANCELLED }

npx prisma migrate dev --name init     # 개발 — 마이그레이션 생성·적용
npx prisma migrate deploy              # ★ 운영 — 적용만
npx prisma generate                    # 타입 재생성
npx prisma studio                      # GUI 로 데이터 보기

쿼리

// 조회 — 필요한 필드만 (★ select 를 쓰는 습관)
const users = await prisma.user.findMany({
  where: { name: { contains: keyword }, createdAt: { gte: from } },
  select: { id: true, name: true, _count: { select: { orders: true } } },
  orderBy: { createdAt: "desc" },
  skip: (page - 1) * size,
  take: size,
});

// 관계 포함 — N+1 을 자동으로 막아 줍니다
const withOrders = await prisma.user.findMany({
  include: { orders: { where: { status: "PAID" }, take: 5 } },
});

// 트랜잭션
await prisma.$transaction(async (tx) => {
  const order = await tx.order.create({ data: dto });
  await tx.stock.update({
    where: { productId: dto.productId },
    data: { quantity: { decrement: dto.qty } },
  });
  return order;
});

// 원자적 차감 — 동시성 문제 방지 (🚀 대규모 k05)
const r = await prisma.stock.updateMany({
  where: { productId, quantity: { gte: qty } },     // ★ 조건을 쿼리 안에
  data: { quantity: { decrement: qty } },
});
if (r.count === 0) throw new ConflictError("재고가 부족합니다");

기본 방어 3종

import helmet from "helmet";
import cors from "cors";
import rateLimit from "express-rate-limit";

// ① 보안 헤더
app.use(helmet());                    // CSP·X-Frame-Options 등 15종

// ② CORS — ★ origin: true 나 "*" 는 위험합니다
app.use(cors({
  origin: env.ALLOWED_ORIGINS.split(","),   // 화이트리스트
  credentials: true,                         // 쿠키를 주고받을 때
  maxAge: 86400,
}));

// ③ Rate Limit
app.use("/api", rateLimit({
  windowMs: 60_000, limit: 100,
  standardHeaders: "draft-8",   // express-rate-limit v8 기준 (구형 클라이언트는 "draft-6")
  message: { code: "TOO_MANY_REQUESTS" },
}));

// 로그인은 훨씬 빡빡하게 (무차별 대입 방지)
app.use("/auth/login", rateLimit({ windowMs: 15 * 60_000, limit: 5 }));

체크리스트

• ☐ SQL 인젝션 — ORM 이나 파라미터 바인딩 사용. 문자열로 쿼리를 만들지 마세요
• ☐ XSS — 사용자 입력을 HTML 로 렌더링할 때 이스케이프. React 는 기본으로 해 주지만 dangerouslySetInnerHTML 은 예외
• ☐ Mass Assignment — req.body 를 그대로 DB 에 넘기지 마세요(x05)
• ☐ 경로 순회 — 파일 경로에 사용자 입력이 들어가면 검증(x08)
• ☐ 비밀번호 — bcrypt·argon2 로 해시. MD5·SHA 단독 금지
• ☐ 비밀 값 — 코드·이미지·로그에 남기지 않기
• ☐ 의존성 — npm audit 를 CI 에 포함
• ☐ 에러 응답 — 스택·내부 경로 노출 금지(x06)
• ☐ HTTPS — 운영은 예외 없이. 쿠키에 secure

// 응답 헤더에서 서버 정보 지우기
app.disable("x-powered-by");

// 요청 크기 제한 (메모리 고갈 공격 방지)
app.use(express.json({ limit: "1mb" }));

// 오래 걸리는 요청 끊기 — 서버 타임아웃으로
// (connect-timeout 패키지는 응답 후에도 핸들러가 계속 도는 문제로 비권장)
const server = app.listen(3000);
server.requestTimeout = 30_000;
server.headersTimeout = 35_000;

// NoSQL 인젝션 (MongoDB 를 쓴다면) — Zod 로 값의 타입을 강제하세요
// ($gt 같은 객체가 문자열 자리에 못 들어오게. x05 참고)
// ★ express-mongo-sanitize 는 Express 5 와 호환되지 않습니다

supertest

// app.ts 에서 app 만 export 하고, listen 은 server.ts 에서 하세요 ★
// 그래야 테스트에서 포트 없이 app 을 그대로 쓸 수 있습니다

import request from "supertest";
import { describe, it, expect, beforeEach } from "vitest";
import { app } from "../src/app.js";

describe("POST /api/users", () => {
  beforeEach(async () => { await resetDb(); });

  it("정상 생성되면 201 을 반환한다", async () => {
    const res = await request(app)
      .post("/api/users")
      .send({ email: "a@b.c", password: "12345678", name: "김" })
      .expect(201);

    expect(res.body).toMatchObject({ email: "a@b.c" });
    expect(res.body).not.toHaveProperty("password");    // ★ 노출 확인
  });

  it("이메일 형식이 틀리면 400", async () => {
    const res = await request(app)
      .post("/api/users")
      .send({ email: "not-an-email", password: "12345678" })
      .expect(400);
    expect(res.body.errors[0].field).toBe("email");
  });

  it("인증 없이 접근하면 401", () =>
    request(app).delete("/api/users/1").expect(401));
});

무엇을 테스트할까

// DB 는 진짜를 쓰는 편이 낫습니다 (Testcontainers)
import { PostgreSqlContainer } from "@testcontainers/postgresql";

let container;
beforeAll(async () => {
  container = await new PostgreSqlContainer("postgres:18").start();
  process.env.DATABASE_URL = container.getConnectionUri();
  await runMigrations();
}, 60_000);

afterAll(() => container.stop());

// 외부 API 는 모킹 (msw 가 실무 표준)
import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";

const server = setupServer(
  http.get("https://api.pay.com/verify", () =>
    HttpResponse.json({ status: "APPROVED" })),
);
beforeAll(() => server.listen());
afterAll(() => server.close());

실무에서 쓰는 구조

src/
  app.ts                 미들웨어 등록 · 라우터 연결 (listen 은 여기 X)
  server.ts              listen · 우아한 종료
  config/
    env.ts               ★ Zod 로 환경 변수 검증 (n08)
  modules/
    user/
      user.routes.ts     URL 매칭
      user.service.ts    비즈니스 규칙 (req/res 를 모름)
      user.repository.ts DB 접근
      user.schema.ts     Zod 스키마 + 타입
      user.test.ts
  shared/
    middleware/          auth · validate · error
    errors.ts            AppError 계열
    db.ts  redis.ts  logger.ts
  types/
    express.d.ts         ★ Request 확장 (🔷 TS t13)

배포 전 체크리스트

• ☐ NODE_ENV=production (Express 가 뷰 캐시 등을 켭니다)
• ☐ 환경 변수 검증이 부팅 시 동작하는가
• ☐ /health 엔드포인트 — DB 연결까지 확인
• ☐ 우아한 종료 — SIGTERM 처리(🟩 Node n08)
• ☐ keepAliveTimeout > 로드밸런서 타임아웃
• ☐ 구조화 로그 + 요청 ID
• ☐ helmet · cors · rate limit
• ☐ 비밀 값이 이미지에 없는지

# 멀티 스테이지 — 이미지 크기를 크게 줄입니다
FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /app/dist ./dist
# ★ root 로 실행하지 마세요
USER node
EXPOSE 3000
# ★ npm start 로 하면 SIGTERM 이 안 옵니다
#   (Dockerfile 은 줄 끝 # 주석을 지원하지 않습니다 — 주석은 항상 따로 한 줄로)
CMD ["node", "dist/server.js"]

// /health — 진짜 상태를 확인해야 의미가 있습니다
app.get("/health", async (req, res) => {
  try {
    await prisma.$queryRaw`SELECT 1`;
    await redis.ping();
    res.json({ status: "ok", uptime: process.uptime() });
  } catch (e) {
    res.status(503).json({ status: "degraded" });
  }
});
// ★ 단, liveness 프로브에는 DB 검사를 넣지 마세요 —
//   DB 가 잠깐 흔들릴 때 모든 서버가 재시작됩니다 (🚀 대규모 k14)

무엇을 고를 것인가

SSE — 30줄이면 끝난다

const clients = new Map<string, Response>();

app.get('/events', requireAuth, (req, res) => {
  res.set({
    'Content-Type':  'text/event-stream',
    'Cache-Control': 'no-cache, no-transform',   // no-transform 중요
    'Connection':    'keep-alive',
    'X-Accel-Buffering': 'no',                   // Nginx 버퍼링 끄기
  });
  res.flushHeaders();

  // ★ push() 가 사용자 ID 로 찾으므로 키도 사용자 ID 로
  //   (한 사람이 탭을 여러 개 연다면 Map<string, Set<Response>> 로)
  const id = String(req.user!.id);
  clients.set(id, res);

  // 15초마다 주석 한 줄 — 프록시가 유휴 연결을 끊는 것을 막는다
  const ping = setInterval(() => res.write(': ping\n\n'), 15_000);

  req.on('close', () => { clearInterval(ping); clients.delete(id); });
});

export function push(userId: string, event: string, data: unknown) {
  const res = clients.get(userId);
  if (!res) return;
  res.write(`event: ${event}\n`);
  res.write(`id: ${Date.now()}\n`);              // 재연결 시 이어받기용
  res.write(`data: ${JSON.stringify(data)}\n\n`); // 빈 줄 두 개가 끝 표시
}

브라우저 쪽 — 끊김을 전제로

const es = new EventSource('/events', { withCredentials: true });

es.addEventListener('job.progress', (e) => {
  const { jobId, percent } = JSON.parse(e.data);
  setProgress(jobId, percent);
});

// 브라우저가 자동 재연결한다. 다만 '끊긴 동안'은 스스로 메워야 한다
es.onopen  = () => syncMissed();      // 놓친 것 한 번 당겨오기
es.onerror = () => setStatus('연결 끊김 — 자동 재시도 중');

// 서버가 Last-Event-ID 를 받아 이어 보낼 수도 있다
// (req.headers['last-event-id'])

여러 대로 늘리면 생기는 문제

// Redis Pub/Sub 으로 서버 간에 이벤트를 흘려 준다
import { createClient } from 'redis';

const sub = createClient({ url: process.env.REDIS_URL });
const pub = sub.duplicate();
await Promise.all([sub.connect(), pub.connect()]);

// 어느 서버에서 발생하든 전체에 뿌린다
export const emit = (userId: string, event: string, data: unknown) =>
  pub.publish('events', JSON.stringify({ userId, event, data }));

// 내 프로세스에 그 사용자가 붙어 있으면 내려보낸다
await sub.subscribe('events', (raw) => {
  const { userId, event, data } = JSON.parse(raw);
  push(userId, event, data);
});

• 연결 수 제한 — 한 사용자가 탭 20개를 열 수 있습니다. 사용자당 상한을 두세요
• 느린 클라이언트 — res.write() 가 false 를 반환하면 버퍼가 찬 것입니다. 계속 밀어 넣으면 서버 메모리가 터집니다
• 그레이스풀 셧다운 때 연결을 먼저 닫아 클라이언트가 다른 서버로 붙게 하세요

중계 서버 — 요청을 소켓에 실어 보낸다

import express from 'express';
import { WebSocketServer } from 'ws';
import { randomUUID } from 'node:crypto';

const app = express();
const agents  = new Map<string, WebSocket>();          // tenant → 소켓
const waiting = new Map<string, (r: TunnelRes) => void>(); // reqId → 응답 대기

const wss = new WebSocketServer({ noServer: true });

wss.on('connection', (ws, req, tenant: string) => {
  agents.set(tenant, ws);

  ws.on('message', (buf) => {
    const msg = JSON.parse(buf.toString());
    waiting.get(msg.id)?.(msg);                        // 기다리던 요청에 응답 전달
    waiting.delete(msg.id);
  });

  // 죽은 연결 청소 — TCP 는 끊겨도 한동안 살아 있는 척한다
  let alive = true;
  ws.on('pong', () => { alive = true; });
  const iv = setInterval(() => {
    if (!alive) return ws.terminate();
    alive = false; ws.ping();
  }, 30_000);

  ws.on('close', () => { clearInterval(iv); agents.delete(tenant); });
});

// 외부 요청 → 해당 테넌트의 에이전트로
// ★ Express 5 는 와일드카드에 이름이 필요합니다 (그냥 * 는 시작할 때 에러)
app.all('/t/:tenant/*rest', async (req, res) => {
  const ws = agents.get(req.params.tenant);
  if (!ws || ws.readyState !== ws.OPEN)
    return res.status(503).json({ error: 'agent offline' });

  const id = randomUUID();
  const body = await readBody(req);                    // 상한을 두고 읽는다

  const answer = new Promise<TunnelRes>((ok, ng) => {
    waiting.set(id, ok);
    setTimeout(() => { waiting.delete(id); ng(new Error('timeout')); }, 30_000);
  });

  ws.send(JSON.stringify({
    id, method: req.method,
    path: '/' + req.params.rest.join('/'),            // *rest 는 경로 조각 배열
    headers: stripHopByHop(req.headers),
    body: body.toString('base64'),
  }));

  try {
    const r = await answer;
    res.status(r.status).set(r.headers).send(Buffer.from(r.body, 'base64'));
  } catch { res.status(504).json({ error: 'agent timeout' }); }
});

사내 에이전트 — 받아서 로컬로 넘긴다

import WebSocket from 'ws';

const LOCAL = 'http://127.0.0.1:3000';
let backoff = 1_000;

function connect() {
  const ws = new WebSocket(`wss://relay.example.com/agent`, {
    headers: { authorization: `Bearer ${process.env.AGENT_TOKEN}` },
  });

  ws.on('open', () => { backoff = 1_000; log.info('tunnel up'); });

  ws.on('message', async (buf) => {
    const m = JSON.parse(buf.toString());
    try {
      // 로컬 서비스로 그대로 전달 (허용 경로만!)
      const r = await fetch(LOCAL + m.path, {
        method: m.method,
        headers: m.headers,
        body: ['GET', 'HEAD'].includes(m.method)
          ? undefined : Buffer.from(m.body, 'base64'),
        signal: AbortSignal.timeout(25_000),
      });
      const body = Buffer.from(await r.arrayBuffer());
      ws.send(JSON.stringify({
        id: m.id, status: r.status,
        headers: Object.fromEntries(r.headers),
        body: body.toString('base64'),
      }));
    } catch (e) {
      ws.send(JSON.stringify({ id: m.id, status: 502, headers: {}, body: '' }));
    }
  });

  // 끊기면 지수 백오프로 재연결 — 중계 서버 재시작 때 몰리는 것을 막는다
  const retry = () => {
    const jitter = Math.random() * 1_000;
    setTimeout(connect, Math.min(backoff, 60_000) + jitter);
    backoff *= 2;
  };
  ws.on('close', retry);
  ws.on('error', () => ws.close());
}
connect();

직접 만들 때 반드시 챙길 것

• 인증은 연결 시점에 — 토큰 검증 후에만 agents 에 등록. 테넌트 id 를 클라이언트가 자기 입으로 말하게 두면 안 됩니다
• 경로 화이트리스트 — 에이전트가 로컬의 아무 데나 요청을 전달하면 사내망 전체가 노출됩니다(SSRF)
• 본문 크기 상한 — 메모리에 통째로 올리는 구조라 10MB 정도로 제한하고, 큰 파일은 별도 스트리밍 경로로
• 동시 요청 상한 — 에이전트당 p-limit 으로 묶지 않으면 사내 서버가 먼저 쓰러집니다
• hop-by-hop 헤더 제거 — connection·upgrade· transfer-encoding 을 그대로 넘기면 프록시가 오작동합니다

직접 만들 것인가, 가져다 쓸 것인가

Range 응답 — 동영상 스트리밍의 최소 조건

import { createReadStream } from 'node:fs';
import { stat } from 'node:fs/promises';           // ★ await 하려면 promises 쪽

app.get('/media/:id', async (req, res) => {
  const file = await resolveSafe(req.params.id);   // 경로 조작 방어
  const { size } = await stat(file);
  const range = req.headers.range;

  if (!range) {
    res.set({ 'Content-Length': size, 'Accept-Ranges': 'bytes',
              'Content-Type': 'video/mp4' });
    return createReadStream(file).pipe(res);
  }

  // "bytes=1048576-" 형태를 파싱한다
  const m = /^bytes=(\d*)-(\d*)$/.exec(range);
  if (!m) return res.status(416).set('Content-Range', `bytes */${size}`).end();

  // "bytes=-500" 은 "끝에서 500바이트" 라는 뜻입니다 (접미 범위)
  const start = m[1] ? Number(m[1]) : Math.max(0, size - Number(m[2]));
  const end   = m[1] && m[2] ? Math.min(Number(m[2]), size - 1) : size - 1;
  if (start >= size || start > end)
    return res.status(416).set('Content-Range', `bytes */${size}`).end();

  res.status(206).set({
    'Content-Range':  `bytes ${start}-${end}/${size}`,
    'Accept-Ranges':  'bytes',
    'Content-Length': end - start + 1,
    'Content-Type':   'video/mp4',
  });
  createReadStream(file, { start, end }).pipe(res);
});

업로드 — 메모리에 올리지 않기

multer({ storage: memoryStorage() })
// 2GB 파일 3개 = 서버 사망

import { pipeline } from 'node:stream/promises';
await pipeline(req, createWriteStream(tmp));
// 또는 S3 멀티파트로 바로 흘린다

// 재개 가능한 업로드 — 청크를 오프셋으로 받는다 (tus 프로토콜의 핵심)
app.patch('/upload/:id', async (req, res) => {
  const offset = Number(req.headers['upload-offset']);
  const meta   = await store.get(req.params.id);
  if (!meta) return res.sendStatus(404);

  // 클라이언트가 아는 위치와 서버가 아는 위치가 다르면 거부한다
  if (offset !== meta.received)
    return res.status(409).set('Upload-Offset', meta.received).end();

  const ws = createWriteStream(meta.path, { flags: 'a' });
  let written = 0;
  req.on('data', (c) => { written += c.length; });
  await pipeline(req, ws);

  meta.received += written;
  await store.set(req.params.id, meta);
  res.set('Upload-Offset', meta.received).sendStatus(204);
});

파일은 앱 서버를 거치지 않는 게 최선

// 프리사인 URL — 브라우저가 스토리지에 직접 올린다
app.post('/upload-url', requireAuth, async (req, res) => {
  const key = `u/${req.user.id}/${randomUUID()}`;
  const url = await getSignedUrl(s3, new PutObjectCommand({
    Bucket: BUCKET, Key: key,
    ContentType: req.body.type,
  }), { expiresIn: 300 });                 // 5분짜리 일회용 주소

  res.json({ url, key });
});

// 다운로드도 마찬가지 — 앱 서버는 '주소만' 발급한다
app.get('/files/:id/url', requireAuth, async (req, res) => {
  const f = await db.file.findUnique({ where: { id: req.params.id } });
  if (!f || f.ownerId !== req.user.id) return res.sendStatus(404);
  res.json({ url: await getSignedUrl(s3,
    new GetObjectCommand({ Bucket: BUCKET, Key: f.key }), { expiresIn: 60 }) });
});

• 앱 서버의 대역폭·메모리를 쓰지 않습니다
• Content-Type·크기 제한을 서명에 함께 걸 수 있습니다
• 업로드 완료는 스토리지 이벤트나 클라이언트 콜백으로 확인

놓치기 쉬운 것

• 백프레셔 — pipe/pipeline 을 쓰세요. res.write() 반환값을 무시하고 계속 쓰면 메모리가 붑니다
• 중단 처리 — 사용자가 탭을 닫으면 req.on('aborted'). 임시 파일을 지워 주지 않으면 디스크가 찹니다
• 업로드 파일명을 그대로 쓰지 마세요 — ../../etc/passwd, 확장자 위장, 유니코드 트릭이 들어옵니다. 서버가 만든 UUID를 키로 쓰고 원본 이름은 DB 에만 두세요
• Nginx client_max_body_size 를 함께 올리지 않으면 앱까지 오지도 못하고 413 이 납니다
• 이미지·영상은 비동기 후처리 큐로 — 요청 안에서 변환하면 타임아웃이 납니다

멱등성 — 같은 요청을 두 번 받아도 한 번만

// 클라이언트가 요청마다 키를 만들어 보낸다 (재시도 시 같은 키)
app.post('/orders', requireAuth, async (req, res) => {
  const key = req.get('Idempotency-Key');
  if (!key) return res.status(400).json({ error: 'Idempotency-Key 필요' });

  // 같은 키로 이미 처리했다면 그때 결과를 그대로 돌려준다
  const hit = await db.idempotency.findUnique({ where: { key } });
  // (status 0 = 아직 처리 중 — res.status(0) 은 RangeError 이므로 따로 답한다)
  if (hit?.status === 0) return res.status(409).json({ error: '처리 중입니다' });
  if (hit) return res.status(hit.status).json(hit.body);

  // 동시에 두 번 들어온 경우 — DB 유니크 제약이 한쪽을 막아 준다
  try {
    await db.idempotency.create({ data: { key, userId: req.user.id,
                                          status: 0, body: {} } });
  } catch { return res.status(409).json({ error: '처리 중입니다' }); }

  const order = await createOrder(req.user.id, req.body);
  await db.idempotency.update({
    where: { key }, data: { status: 201, body: order },
  });
  res.status(201).json(order);
});

웹훅 수신 — 서명 검증이 먼저

// ★ 서명 검증에는 '가공되지 않은 원문'이 필요하다.
//   express.json() 이 먼저 파싱해 버리면 검증할 수 없다.
app.post('/webhooks/pay',
  express.raw({ type: 'application/json', limit: '1mb' }),
  async (req, res) => {
    const sig = req.get('x-signature') ?? '';
    const ts  = Number(req.get('x-timestamp') ?? 0);

    // 재전송 공격 방어 — 5분 넘은 것은 거부
    if (Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(400);

    const mine = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET!)
                       .update(`${ts}.`).update(req.body).digest();
    const theirs = Buffer.from(sig, 'hex');

    // 길이가 다르면 timingSafeEqual 이 예외를 던진다
    if (mine.length !== theirs.length ||
        !crypto.timingSafeEqual(mine, theirs)) return res.sendStatus(401);

    const event = JSON.parse(req.body.toString());

    // 같은 이벤트가 여러 번 온다 — 결제사는 재시도를 보장한다
    const fresh = await db.webhookEvent.create({ data: { id: event.id } })
                          .catch(() => null);
    if (!fresh) return res.sendStatus(200);        // 이미 처리함

    // ★ 무거운 일은 큐에 넣고 즉시 200 — 늦게 답하면 결제사가 재시도한다
    await queue.add('pay.event', event);
    res.sendStatus(200);
  });

웹훅을 못 받았을 때 — 폴링 보완

// 웹훅은 '반드시 온다'가 아니라 '보통 온다' 입니다.
// 서버 재배포 중이거나 장애가 나면 그대로 유실됩니다.
// 그래서 상용 서비스는 폴링을 하나 더 둡니다.

// 5분마다: 결제 요청은 있는데 아직 결론이 없는 건을 직접 조회
cron.schedule('*/5 * * * *', async () => {
  const stuck = await db.order.findMany({
    where: { status: 'PENDING', createdAt: { lt: minutesAgo(3) } },
    take: 100,
  });
  for (const o of stuck) {
    const r = await pg.getPayment(o.paymentKey);    // 결제사에 직접 물어본다
    if (r.status === 'DONE')     await markPaid(o.id, r);
    if (r.status === 'CANCELED') await markCanceled(o.id, r);
  }
});

돈이 걸린 API 의 기본기

• 금액을 클라이언트에서 받지 마세요. 상품 id 만 받고 금액은 서버가 계산합니다 — 가장 흔한 취약점입니다
• 결제 승인과 주문 확정은 같은 트랜잭션에 — 중간에 죽으면 돈은 빠졌는데 주문이 없는 상태가 됩니다
• 모든 상태 변화를 로그로 — 분쟁이 나면 로그가 증거입니다. 절대 지우거나 덮어쓰지 마세요(append-only)
• 테스트 키와 운영 키를 코드로 분리 — 운영 DB 에 테스트 결제가 섞이면 정산이 안 맞습니다
• 환불·부분취소까지 설계한 뒤 시작하세요. 나중에 붙이면 상태 머신을 다시 짜야 합니다

Express 와의 비교

스프링과의 대응표 — 자바 개발자용

시작하기

npm i -g @nestjs/cli
nest new my-api                     # 프로젝트 생성

# 리소스 한 벌 통째로 (컨트롤러·서비스·DTO·테스트)
nest g resource users               # ★ 가장 많이 씁니다

# 개별 생성
nest g module orders
nest g controller orders
nest g service orders
nest g guard auth
nest g interceptor logging
nest g pipe validation

npm run start:dev                   # 감시 모드
npm run build && npm run start:prod

src/
  main.ts                  부트스트랩 (전역 파이프·CORS·Swagger)
  app.module.ts            루트 모듈
  common/
    filters/               예외 필터
    guards/                가드
    interceptors/          인터셉터
    decorators/            커스텀 데코레이터
    dto/                   공통 DTO (페이지네이션 등)
  config/
    configuration.ts       설정 로더 + 검증
  modules/
    users/
      users.module.ts
      users.controller.ts
      users.service.ts
      dto/create-user.dto.ts
      entities/user.entity.ts
      users.service.spec.ts
    orders/
      ...

main.ts — 실무 기본형

import { NestFactory } from "@nestjs/core";
import { ValidationPipe, VersioningType } from "@nestjs/common";
import helmet from "helmet";

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    bufferLogs: true,                       // 로거 준비 전 로그를 모아 둠
  });

  app.use(helmet());
  app.enableCors({ origin: process.env.ALLOWED_ORIGINS?.split(",") });
  app.setGlobalPrefix("api");
  app.enableVersioning({ type: VersioningType.URI });   // /api/v1/...

  // ★ 전역 검증 파이프 — 이 설정이 핵심입니다 (s06)
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,                 // DTO 에 없는 속성 제거
    forbidNonWhitelisted: true,      // 있으면 에러
    transform: true,                 // 문자열 → 숫자 자동 변환
    transformOptions: { enableImplicitConversion: true },
  }));

  app.enableShutdownHooks();         // ★ SIGTERM 처리 (s16)

  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

모듈 — 기능의 경계

@Module({
  imports: [                      // 이 모듈이 쓸 다른 모듈
    TypeOrmModule.forFeature([User]),
    forwardRef(() => OrdersModule),      // 순환 참조 해결
  ],
  controllers: [UsersController], // HTTP 진입점
  providers: [                    // 주입 가능한 것들
    UsersService,
    UsersRepository,
    { provide: "CACHE_TTL", useValue: 300 },        // 값 주입
    { provide: MailService, useClass: SmtpMailService },  // 구현 교체
    {                                                // 팩토리
      provide: "REDIS",
      useFactory: (cfg: ConfigService) => createClient({ url: cfg.get("REDIS_URL") }),
      inject: [ConfigService],
    },
  ],
  exports: [UsersService],        // ★ 다른 모듈에 공개할 것 (안 적으면 못 씁니다)
})
export class UsersModule {}

의존성 주입 — 왜 좋은가

@Injectable()
export class UsersService {
  constructor(
    private readonly repo: UsersRepository,        // ★ 타입만 적으면 주입됩니다
    private readonly mailer: MailService,
    @Inject("CACHE_TTL") private readonly ttl: number,   // 토큰으로 주입
  ) {}
}

// 테스트에서는 가짜로 갈아 끼울 수 있습니다
const module = await Test.createTestingModule({
  providers: [
    UsersService,
    { provide: UsersRepository, useValue: mockRepo },   // ★
    { provide: MailService, useValue: { send: vi.fn() } },
    { provide: "CACHE_TTL", useValue: 60 },
  ],
}).compile();

전역 모듈과 동적 모듈

// 어디서나 쓰이는 것 (Config·Logger·Prisma)
@Global()
@Module({ providers: [PrismaService], exports: [PrismaService] })
export class PrismaModule {}
// ★ 남용하지 마세요 — 의존 관계가 안 보이게 됩니다

// 동적 모듈 — 설정을 받아 구성 (라이브러리에서 흔한 패턴)
@Module({})
export class MailModule {
  static forRoot(options: MailOptions): DynamicModule {
    return {
      module: MailModule,
      providers: [{ provide: "MAIL_OPTIONS", useValue: options }, MailService],
      exports: [MailService],
    };
  }
}
// AppModule 에서: MailModule.forRoot({ host: ... })

기본형

@Controller("users")            // → /api/users
export class UsersController {
  constructor(private readonly service: UsersService) {}

  @Get()
  findAll(@Query() query: ListUsersDto) {
    return this.service.findAll(query);      // ★ Promise 를 그냥 반환하면 됩니다
  }

  @Get(":id")
  findOne(@Param("id", ParseIntPipe) id: number) {   // ★ 변환+검증
    return this.service.findOne(id);
  }

  @Post()
  @HttpCode(201)
  create(@Body() dto: CreateUserDto) {
    return this.service.create(dto);
  }

  @Patch(":id")
  update(@Param("id", ParseIntPipe) id: number,
         @Body() dto: UpdateUserDto) {
    return this.service.update(id, dto);
  }

  @Delete(":id")
  @HttpCode(204)
  remove(@Param("id", ParseIntPipe) id: number) {
    return this.service.remove(id);
  }
}

자주 쓰는 데코레이터

// 커스텀 데코레이터 — 실무에서 반드시 만들게 됩니다
export const CurrentUser = createParamDecorator(
  (data: keyof JwtUser | undefined, ctx: ExecutionContext) => {
    const req = ctx.switchToHttp().getRequest();
    return data ? req.user?.[data] : req.user;
  },
);

// 사용
@Get("me")
getMe(@CurrentUser() user: JwtUser) {
  return this.service.findOne(user.id);
}
@Get("my-orders")
myOrders(@CurrentUser("id") userId: number) { ... }

서비스 작성

@Injectable()
export class UsersService {
  private readonly logger = new Logger(UsersService.name);

  constructor(
    private readonly repo: UsersRepository,
    private readonly events: EventEmitter2,
  ) {}

  async create(dto: CreateUserDto): Promise<User> {
    const exists = await this.repo.findByEmail(dto.email);
    if (exists) throw new ConflictException("이미 가입된 이메일입니다");

    const { password, ...rest } = dto;          // ★ 평문 비밀번호는 저장 객체에서 뺍니다
    const user = await this.repo.save({
      ...rest,
      passwordHash: await bcrypt.hash(password, 12),
    });

    this.logger.log(`사용자 생성 id=${user.id}`);
    this.events.emit("user.created", new UserCreatedEvent(user.id));
    return user;
  }

  async findOne(id: number): Promise<User> {
    const user = await this.repo.findById(id);
    if (!user) throw new NotFoundException(`사용자 ${id} 를 찾을 수 없습니다`);
    return user;
  }
}

생명주기 훅

@Injectable()
export class CacheWarmer implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    await this.warmUp();            // ★ 앱 시작 시 1회
  }
  async onModuleDestroy() {
    await this.client.quit();       // ★ 종료 시 정리 (enableShutdownHooks 필요)
  }
}

// 순서: onModuleInit → onApplicationBootstrap
//       → (종료) onModuleDestroy → beforeApplicationShutdown → onApplicationShutdown

이벤트로 느슨하게 연결하기

// 발행
this.events.emit("order.created", { orderId, userId });

// 구독 — 다른 모듈에서
@Injectable()
export class OrderCreatedListener {
  @OnEvent("order.created", { async: true })
  async handle(event: OrderCreatedEvent) {
    await this.mail.sendOrderConfirm(event.orderId);
  }
}

class-validator 방식 (Nest 기본)

export class CreateUserDto {
  @IsEmail({}, { message: "이메일 형식이 아닙니다" })
  email: string;

  @IsString()
  @MinLength(8)
  @Matches(/[0-9]/, { message: "숫자를 포함해야 합니다" })
  password: string;

  @IsString()
  @Length(1, 50)
  name: string;

  @IsOptional()
  @IsInt()
  @Min(0) @Max(150)
  @Type(() => Number)          // ★ 쿼리는 문자열이므로 변환 필요
  age?: number;

  @IsEnum(Role)
  role: Role = Role.USER;

  @ValidateNested({ each: true })   // 중첩 객체 검증
  @Type(() => AddressDto)
  addresses: AddressDto[];
}

// 부분 업데이트용 — 전부 optional 로 만들어 줍니다
export class UpdateUserDto extends PartialType(CreateUserDto) {}
// 일부만 골라 쓰기
export class LoginDto extends PickType(CreateUserDto, ["email", "password"]) {}

파이프 — 변환과 검증

// 내장 파이프
@Param("id", ParseIntPipe) id: number
@Query("active", ParseBoolPipe) active: boolean
@Param("uuid", ParseUUIDPipe) uuid: string
@Query("page", new DefaultValuePipe(1), ParseIntPipe) page: number

// 커스텀 파이프
@Injectable()
export class TrimPipe implements PipeTransform {
  transform(value: unknown) {
    return typeof value === "string" ? value.trim() : value;
  }
}

Zod 를 쓰고 싶다면

// class-validator 대신 Zod 로 통일하는 팀도 많습니다
@Injectable()
export class ZodValidationPipe implements PipeTransform {
  constructor(private schema: ZodSchema) {}
  transform(value: unknown) {
    const r = this.schema.safeParse(value);
    if (!r.success) {
      throw new BadRequestException({
        message: "입력값이 올바르지 않습니다",
        errors: r.error.issues.map(i => ({ field: i.path.join("."), message: i.message })),
      });
    }
    return r.data;
  }
}

@Post()
create(@Body(new ZodValidationPipe(CreateUserSchema)) dto: CreateUserDto) {}

전역 예외 필터

@Catch()                               // 모든 예외
export class AllExceptionsFilter implements ExceptionFilter {
  private readonly logger = new Logger("Exception");

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const res = ctx.getResponse<Response>();
    const req = ctx.getRequest<Request>();
    const requestId = req.headers["x-request-id"];

    // ① Nest 내장 예외
    if (exception instanceof HttpException) {
      const status = exception.getStatus();
      const body = exception.getResponse();
      if (status >= 500) this.logger.error({ exception, requestId });
      return res.status(status).json({ ...normalize(body), requestId });
    }

    // ② 라이브러리 예외 변환
    if (exception instanceof Prisma.PrismaClientKnownRequestError) {
      if (exception.code === "P2002")
        return res.status(409).json({ code: "DUPLICATE", requestId });
      if (exception.code === "P2025")
        return res.status(404).json({ code: "NOT_FOUND", requestId });
    }

    // ③ 예상치 못한 것 — 내부 정보를 감춥니다
    this.logger.error({ exception, path: req.url, requestId }, "처리되지 않은 예외");
    res.status(500).json({
      code: "INTERNAL_ERROR", message: "서버 오류가 발생했습니다", requestId,
    });
  }
}

// main.ts
app.useGlobalFilters(new AllExceptionsFilter());

도메인 예외 설계

// 비즈니스 규칙 위반은 HTTP 를 몰라도 되게
export class DomainError extends Error {
  constructor(message: string, public readonly code: string) {
    super(message);
    this.name = this.constructor.name;
  }
}
export class InsufficientStockError extends DomainError {
  constructor(productId: number) {
    super(`상품 ${productId} 의 재고가 부족합니다`, "INSUFFICIENT_STOCK");
  }
}

// 필터에서 HTTP 로 매핑
const DOMAIN_STATUS: Record<string, number> = {
  INSUFFICIENT_STOCK: 409,
  PAYMENT_DECLINED: 402,
  LIMIT_EXCEEDED: 429,
};

@Catch(DomainError)
export class DomainExceptionFilter implements ExceptionFilter {
  catch(err: DomainError, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse();
    res.status(DOMAIN_STATUS[err.code] ?? 400)
       .json({ code: err.code, message: err.message });
  }
}

JWT 인증 구성

@Module({
  imports: [
    PassportModule,
    JwtModule.registerAsync({
      inject: [ConfigService],
      useFactory: (cfg: ConfigService) => ({
        secret: cfg.getOrThrow("JWT_SECRET"),
        signOptions: { expiresIn: "15m", issuer: "my-api" },
      }),
    }),
  ],
  providers: [AuthService, JwtStrategy, JwtAuthGuard],
  exports: [AuthService],
})
export class AuthModule {}

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(cfg: ConfigService, private users: UsersService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: cfg.getOrThrow("JWT_SECRET"),
    });
  }
  // 반환값이 req.user 에 들어갑니다
  async validate(payload: JwtPayload) {
    return { id: Number(payload.sub), role: payload.role };
  }
}

전역 가드 + 공개 엔드포인트

// ★ 기본을 "인증 필요"로 두고, 공개할 것만 표시하는 편이 안전합니다
export const IS_PUBLIC = "isPublic";
export const Public = () => SetMetadata(IS_PUBLIC, true);

@Injectable()
export class JwtAuthGuard extends AuthGuard("jwt") {
  constructor(private reflector: Reflector) { super(); }

  canActivate(ctx: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC, [
      ctx.getHandler(), ctx.getClass(),
    ]);
    if (isPublic) return true;
    return super.canActivate(ctx);
  }
}

// app.module.ts — 전역 등록
providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }]

// 사용
@Public()
@Post("login")
login(@Body() dto: LoginDto) { ... }

권한(역할) 가드

export const Roles = (...roles: Role[]) => SetMetadata("roles", roles);

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}
  canActivate(ctx: ExecutionContext): boolean {
    const required = this.reflector.getAllAndOverride<Role[]>("roles", [
      ctx.getHandler(), ctx.getClass(),
    ]);
    if (!required?.length) return true;
    const { user } = ctx.switchToHttp().getRequest();
    if (!required.includes(user?.role))
      throw new ForbiddenException("권한이 없습니다");
    return true;
  }
}

@Roles(Role.ADMIN)
@Delete(":id")
remove(@Param("id") id: number) { ... }

인터셉터 — 응답 변환 · 로깅 · 타임아웃

// ① 응답 형태 통일
@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, ApiResponse<T>> {
  intercept(ctx: ExecutionContext, next: CallHandler) {
    return next.handle().pipe(
      map(data => ({ success: true, data, timestamp: new Date().toISOString() })),
    );
  }
}

// ② 소요 시간 로깅
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger("HTTP");
  intercept(ctx: ExecutionContext, next: CallHandler) {
    const req = ctx.switchToHttp().getRequest();
    const start = Date.now();
    return next.handle().pipe(
      tap(() => this.logger.log(
        `${req.method} ${req.url} ${Date.now() - start}ms`)),
    );
  }
}

// ③ 타임아웃 — 오래 걸리는 요청 끊기
@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  intercept(ctx: ExecutionContext, next: CallHandler) {
    return next.handle().pipe(
      timeout(10_000),
      catchError(e => e instanceof TimeoutError
        ? throwError(() => new RequestTimeoutException())
        : throwError(() => e)),
    );
  }
}

민감 정보 제거 — 직렬화

// 엔티티에 표시하고
export class User {
  id: number;
  email: string;
  name: string;
  role: string;

  @Exclude()                 // ★ 응답에서 자동 제거
  passwordHash: string;

  @Expose()
  get displayName() { return `${this.name}(${this.role})`; }
}

// 전역으로 켜기
app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));

미들웨어 — Express 그대로

@Injectable()
export class RequestIdMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const id = (req.headers["x-request-id"] as string) ?? randomUUID();
    req.headers["x-request-id"] = id;
    res.setHeader("x-request-id", id);
    next();
  }
}

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(RequestIdMiddleware).forRoutes("*");   // ★ Nest 11(Express 5)은 "{*splat}"
    consumer.apply(RawBodyMiddleware)
            .forRoutes({ path: "webhooks/*", method: RequestMethod.POST });
    // ★ Nest 11 부터 와일드카드 문법이 path-to-regexp v8 기준으로 바뀌었습니다
    //   "*" → "{*splat}" · "webhooks/*" → "webhooks/{*splat}"
  }
}

ConfigModule + 검증

// config/configuration.ts
export default () => ({
  port: parseInt(process.env.PORT ?? "3000", 10),
  database: { url: process.env.DATABASE_URL },
  redis: { url: process.env.REDIS_URL },
  jwt: { secret: process.env.JWT_SECRET, expiresIn: "15m" },
});

// app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,                    // 어디서나 주입 가능
      load: [configuration],
      envFilePath: [`.env.${process.env.NODE_ENV}`, ".env"],
      cache: true,
      validationSchema: Joi.object({     // ★ 부팅 시 검증
        NODE_ENV: Joi.string().valid("development", "production", "test"),
        PORT: Joi.number().default(3000),
        DATABASE_URL: Joi.string().uri().required(),
        JWT_SECRET: Joi.string().min(32).required(),
      }),
      validationOptions: { abortEarly: false },
    }),
  ],
})
export class AppModule {}

// 사용
constructor(private readonly config: ConfigService) {}

this.config.get<number>("port");
this.config.getOrThrow<string>("jwt.secret");   // ★ 없으면 즉시 에러

타입 안전한 설정 — 권장 형태

// registerAs 로 네임스페이스 + 타입
export const dbConfig = registerAs("database", () => ({
  url: process.env.DATABASE_URL!,
  poolSize: Number(process.env.DB_POOL ?? 10),
}));

// 주입할 때 타입이 살아 있습니다
constructor(
  @Inject(dbConfig.KEY)
  private readonly db: ConfigType<typeof dbConfig>,
) {}

this.db.poolSize;    // ✅ number 로 자동완성

환경별 설정 전략

.env                 공통 기본값 (커밋 O — 비밀 값 없음)
.env.development     로컬 (커밋 X)
.env.test            테스트용
.env.production      ❌ 만들지 마세요 — 운영은 환경 변수 주입

운영 값 주입 경로
  Docker      -e / --env-file
  K8s         ConfigMap · Secret
  AWS         Parameter Store · Secrets Manager
  Vercel 등   대시보드 환경 변수

무엇을 고를까

// TypeORM — 엔티티
@Entity("users")
export class User {
  @PrimaryGeneratedColumn() id: number;
  @Column({ unique: true }) email: string;
  @Column() name: string;

  @OneToMany(() => Order, o => o.user)
  orders: Order[];

  @CreateDateColumn() createdAt: Date;
  @DeleteDateColumn() deletedAt?: Date;     // 소프트 삭제
}

// 모듈 등록
TypeOrmModule.forRootAsync({
  inject: [ConfigService],
  useFactory: (cfg) => ({
    type: "postgres",
    url: cfg.getOrThrow("DATABASE_URL"),
    autoLoadEntities: true,
    synchronize: false,          // ★ 운영에서 true 면 데이터가 날아갑니다
    logging: cfg.get("NODE_ENV") !== "production",
    extra: { max: 10 },          // 커넥션 풀
  }),
})

Prisma 를 Nest 에 붙이기

@Injectable()
export class PrismaService extends PrismaClient
  implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() { await this.$connect(); }
  async onModuleDestroy() { await this.$disconnect(); }
}

@Global()
@Module({ providers: [PrismaService], exports: [PrismaService] })
export class PrismaModule {}

// 서비스에서
constructor(private readonly prisma: PrismaService) {}
const users = await this.prisma.user.findMany({ where: { active: true } });

N+1 을 피하는 법 — 어느 쪽이든

// ❌ N+1 — 사용자 100명이면 쿼리 101번
const users = await repo.find();
for (const u of users) u.orders = await orderRepo.findBy({ userId: u.id });

// ✅ TypeORM — relations 또는 QueryBuilder
await repo.find({ relations: { orders: true } });
await repo.createQueryBuilder("u")
  .leftJoinAndSelect("u.orders", "o")
  .where("u.active = :a", { a: true })
  .getMany();

// ✅ Prisma — include
await prisma.user.findMany({ include: { orders: true } });

방법 ① 명시적 트랜잭션 (가장 확실)

// Prisma
async createOrder(dto: CreateOrderDto) {
  return this.prisma.$transaction(async (tx) => {
    const order = await tx.order.create({ data: { ...dto } });

    const r = await tx.stock.updateMany({
      where: { productId: dto.productId, quantity: { gte: dto.qty } },
      data: { quantity: { decrement: dto.qty } },
    });
    if (r.count === 0) throw new InsufficientStockError(dto.productId);
    //  ★ 던지면 자동 롤백됩니다

    await tx.pointHistory.create({ data: { userId: dto.userId, amount: -dto.qty } });
    return order;
  }, { timeout: 5000, isolationLevel: "ReadCommitted" });
}

// TypeORM
await this.dataSource.transaction(async (manager) => {
  await manager.save(order);
  await manager.decrement(Stock, { productId }, "quantity", qty);
});

방법 ② 데코레이터로 (AsyncLocalStorage)

// 스프링처럼 쓰고 싶다면 이 조합이 사실상 표준입니다
@Injectable()
export class OrdersService {
  @Transactional()                    // ★ 스프링과 같은 느낌
  async createOrder(dto: CreateOrderDto) {
    await this.orderRepo.save(dto);
    await this.stockRepo.decrease(dto.productId, dto.qty);
    // 두 리포지토리가 "같은 트랜잭션"을 자동으로 공유합니다
  }
}
// 내부적으로 AsyncLocalStorage 로 트랜잭션 컨텍스트를 전파합니다
// (🟩 Node n16 의 요청 ID 전파와 같은 원리)

계층 규칙 — 이것만 지키면 됩니다

캐시

CacheModule.registerAsync({
  isGlobal: true,
  inject: [ConfigService],
  useFactory: (cfg) => ({
    stores: [new KeyvRedis(cfg.getOrThrow("REDIS_URL"))],
    ttl: 60_000,                     // 기본 60초
  }),
})

// ① 자동 캐시 (GET 응답 전체)
@UseInterceptors(CacheInterceptor)
@CacheTTL(300_000)
@Get()
findAll() { ... }

// ② 직접 제어 — 실무에서는 이쪽이 더 많습니다
constructor(@Inject(CACHE_MANAGER) private cache: Cache) {}

async findOne(id: number) {
  const key = `user:${id}`;
  const hit = await this.cache.get<User>(key);
  if (hit) return hit;

  const user = await this.repo.findById(id);
  // ★ TTL 에 랜덤을 섞어 동시 만료를 피합니다 (🚀 대규모 k04)
  await this.cache.set(key, user, 300_000 + Math.random() * 60_000);
  return user;
}

async update(id: number, dto: UpdateUserDto) {
  const user = await this.repo.update(id, dto);
  await this.cache.del(`user:${id}`);     // ★ 수정이 아니라 삭제
  return user;
}

큐 — 오래 걸리는 일은 넘기세요

BullModule.forRootAsync({
  inject: [ConfigService],
  useFactory: (cfg) => ({
    connection: { url: cfg.getOrThrow("REDIS_URL") },
    defaultJobOptions: {
      attempts: 3,
      backoff: { type: "exponential", delay: 1000 },   // 재시도 1s → 2s (attempts 3 = 첫 시도 + 재시도 2번)
      removeOnComplete: { age: 3600, count: 1000 },     // ★ 안 지우면 Redis 가 참
      removeOnFail: { age: 86400 },
    },
  }),
}),
BullModule.registerQueue({ name: "email" })

// 작업 넣기 — 컨트롤러는 즉시 응답합니다
constructor(@InjectQueue("email") private emailQueue: Queue) {}

await this.emailQueue.add("welcome", { userId },
  { delay: 5000, jobId: `welcome:${userId}` });   // ★ jobId 로 중복 방지

// 처리하기
@Processor("email", { concurrency: 5 })
export class EmailProcessor extends WorkerHost {
  async process(job: Job<{ userId: number }>) {
    await job.updateProgress(50);
    await this.mailer.sendWelcome(job.data.userId);
  }

  @OnWorkerEvent("failed")
  onFailed(job: Job, err: Error) {
    this.logger.error({ jobId: job.id, attempts: job.attemptsMade, err });
  }
}

단위 테스트

describe("UsersService", () => {
  let service: UsersService;
  let repo: { findByEmail: Mock; save: Mock };

  beforeEach(async () => {
    repo = { findByEmail: vi.fn(), save: vi.fn() };

    const module = await Test.createTestingModule({
      providers: [
        UsersService,
        { provide: UsersRepository, useValue: repo },      // ★ 가짜 주입
        { provide: EventEmitter2, useValue: { emit: vi.fn() } },
      ],
    }).compile();

    service = module.get(UsersService);
  });

  it("이메일이 중복이면 ConflictException", async () => {
    repo.findByEmail.mockResolvedValue({ id: 1 });
    await expect(service.create(dto)).rejects.toThrow(ConflictException);
  });

  it("정상 생성 시 이벤트를 발행한다", async () => {
    repo.findByEmail.mockResolvedValue(null);
    repo.save.mockResolvedValue({ id: 1, ...dto });
    await service.create(dto);
    expect(repo.save).toHaveBeenCalledOnce();
  });
});

E2E 테스트

describe("Users (e2e)", () => {
  let app: INestApplication;

  beforeAll(async () => {
    const module = await Test.createTestingModule({
      imports: [AppModule],
    })
      .overrideProvider(MailService)          // ★ 외부 연동만 교체
      .useValue({ send: vi.fn() })
      .overrideGuard(ThrottlerGuard)          // 테스트에서는 rate limit 끄기
      .useValue({ canActivate: () => true })
      .compile();

    app = module.createNestApplication();
    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));  // ★ main.ts 와 동일하게
    await app.init();
  });

  afterAll(() => app.close());

  it("POST /users → 201", () =>
    request(app.getHttpServer())
      .post("/users")
      .send({ email: "a@b.c", password: "12345678", name: "김" })
      .expect(201)
      .expect(res => expect(res.body).not.toHaveProperty("passwordHash")));

  it("잘못된 이메일 → 400", () =>
    request(app.getHttpServer())
      .post("/users").send({ email: "x" }).expect(400));
});

WebSocket — 실시간

@WebSocketGateway({ cors: true, namespace: "/chat" })
export class ChatGateway implements OnGatewayConnection {
  @WebSocketServer() server: Server;

  async handleConnection(client: Socket) {
    const token = client.handshake.auth.token;
    try {
      client.data.user = this.jwt.verify(token);     // ★ 연결 시 인증
    } catch {
      client.disconnect();
    }
  }

  @SubscribeMessage("message")
  async onMessage(@MessageBody() dto: MessageDto,
                  @ConnectedSocket() client: Socket) {
    const saved = await this.chatService.save(dto, client.data.user.id);
    this.server.to(dto.roomId).emit("message", saved);
    return { ok: true };                              // ack
  }
}

마이크로서비스

// 서비스 쪽 — HTTP 대신 메시지로 통신
const app = await NestFactory.createMicroservice(AppModule, {
  transport: Transport.REDIS,           // 또는 KAFKA · RMQ · TCP · gRPC
  options: { host: "redis", port: 6379 },
});

@MessagePattern("order.create")       // 요청-응답
async create(@Payload() dto: CreateOrderDto) { ... }

@EventPattern("order.created")        // 단방향 이벤트
async onCreated(@Payload() event: OrderCreatedEvent) { ... }

// 호출하는 쪽
constructor(@Inject("ORDER_SERVICE") private client: ClientProxy) {}
const order = await firstValueFrom(this.client.send("order.create", dto));
this.client.emit("order.created", event);      // 응답을 안 기다림

GraphQL — 코드 우선 방식

@ObjectType()
export class User {
  @Field(() => Int) id: number;
  @Field() email: string;
  @Field(() => [Order]) orders: Order[];
}

@Resolver(() => User)
export class UsersResolver {
  @Query(() => [User])
  users(@Args("keyword", { nullable: true }) keyword?: string) { ... }

  @ResolveField(() => [Order])
  orders(@Parent() user: User) {
    return this.loader.ordersByUser.load(user.id);   // ★ DataLoader 로 N+1 방지
  }
}

헬스체크

@Controller("health")
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: TypeOrmHealthIndicator,
    private memory: MemoryHealthIndicator,
  ) {}

  // ★ liveness — 프로세스가 살아 있는지만 (의존성 검사 X)
  @Get("live")
  @Public()
  live() { return { status: "ok" }; }

  // ★ readiness — 트래픽을 받을 준비가 됐는지 (의존성 포함)
  @Get("ready")
  @Public()
  @HealthCheck()
  ready() {
    return this.health.check([
      () => this.db.pingCheck("database", { timeout: 1500 }),
      () => this.memory.checkHeap("memory_heap", 512 * 1024 * 1024),
    ]);
  }
}

우아한 종료

app.enableShutdownHooks();          // ★ main.ts

@Injectable()
export class GracefulService implements OnApplicationShutdown {
  async onApplicationShutdown(signal: string) {
    this.logger.log(`${signal} 수신 — 정리 시작`);
    await this.queue.close();        // 진행 중인 작업 완료 대기
    await this.redis.quit();
  }
}

관측 · 문서

// Prometheus 메트릭
import { PrometheusModule } from "@willsoto/nestjs-prometheus";
imports: [PrometheusModule.register({ path: "/metrics" })]

// OpenTelemetry 분산 추적 (🚀 대규모 k12)
// Swagger 자동 문서
const config = new DocumentBuilder()
  .setTitle("My API").setVersion("1.0")
  .addBearerAuth()
  .build();
SwaggerModule.setup("docs", app, SwaggerModule.createDocument(app, config));
// ★ 운영에서는 인증을 걸거나 비활성화하세요

배포 체크리스트

• ☐ NODE_ENV=production · npm ci --omit=dev
• ☐ 환경 변수 검증 스키마가 동작하는가 (s10)
• ☐ synchronize: false · 마이그레이션으로 스키마 관리
• ☐ 전역 ValidationPipe 의 whitelist 켜짐
• ☐ 응답에 비밀번호 해시가 안 나가는가 (s09)
• ☐ liveness / readiness 분리
• ☐ enableShutdownHooks + Dockerfile 이 node 직접 실행
• ☐ Swagger 가 운영에 열려 있지 않은가
• ☐ 로그가 JSON 한 줄인가 (nestjs-pino)

CQRS — 읽기와 쓰기를 나누기

// 명령 — 상태를 바꿉니다
export class CreateOrderCommand {
  constructor(readonly userId: number, readonly items: OrderItem[]) {}
}

@CommandHandler(CreateOrderCommand)
export class CreateOrderHandler implements ICommandHandler<CreateOrderCommand> {
  constructor(private readonly repo: OrderRepository,
              private readonly publisher: EventPublisher) {}

  async execute(cmd: CreateOrderCommand) {
    const order = this.publisher.mergeObjectContext(Order.create(cmd));
    await this.repo.save(order);
    order.commit();                    // ★ 쌓인 도메인 이벤트를 한 번에 발행
    return order.id;
  }
}

// 조회 — 상태를 안 바꿉니다 (읽기 전용 모델·복제본을 써도 됩니다)
@QueryHandler(GetOrderListQuery)
export class GetOrderListHandler {
  async execute(q: GetOrderListQuery) {
    return this.readDb.query(...);     // ★ 정규화를 깬 뷰 테이블도 가능
  }
}

// 이벤트 — 부수 효과
@EventsHandler(OrderCreatedEvent)
export class SendMailOnOrderCreated implements IEventHandler<OrderCreatedEvent> {
  handle(e: OrderCreatedEvent) { this.queue.add("mail", { id: e.orderId }); }
}

동적 모듈 · 커스텀 프로바이더

// 사내 공통 모듈을 만들 때의 표준 형태
@Module({})
export class TracingModule {
  static forRootAsync(options: TracingAsyncOptions): DynamicModule {
    return {
      module: TracingModule,
      global: true,
      imports: options.imports ?? [],
      providers: [
        {
          provide: TRACING_OPTIONS,
          useFactory: options.useFactory,
          inject: options.inject ?? [],
        },
        TracingService,
      ],
      exports: [TracingService],
    };
  }
}

// ConfigurableModuleBuilder — 위 보일러플레이트를 자동 생성 (Nest 9+)
export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } =
  new ConfigurableModuleBuilder<TracingOptions>().setClassMethodName("forRoot").build();

export class TracingModule extends ConfigurableModuleClass {}

// 요청 컨텍스트 전파 — REQUEST 스코프보다 훨씬 빠릅니다
import { ClsModule, ClsService } from "nestjs-cls";

ClsModule.forRoot({
  global: true,
  middleware: {
    mount: true,
    setup: (cls, req) => {
      cls.set("requestId", req.headers["x-request-id"] ?? randomUUID());
      // ★ 여기서 req.user 는 아직 없습니다 — 미들웨어는 가드(인증)보다 먼저 돕니다.
      //   userId 는 인증 가드나 인터셉터에서 cls.set("userId", ...) 로 넣으세요
    },
  },
});

// 어디서든 꺼내 씁니다 (매개변수로 안 넘겨도 됩니다)
constructor(private readonly cls: ClsService) {}
this.logger.log({ requestId: this.cls.get("requestId") }, "주문 생성");
// ★ 내부적으로 AsyncLocalStorage 를 씁니다 (🟩 Node n16)
// ★ 트랜잭션 전파(s12)도 같은 원리입니다

옛 아키텍처 — 브리지

[JS 스레드]        [브리지]        [네이티브 UI 스레드]
  React 로직   ──JSON 직렬화──>   실제 화면 그리기
              <──비동기·배치───

문제
  · 모든 통신이 JSON 직렬화 → 비용이 큼
  · 완전 비동기 → 스크롤 중 흰 화면이 보이는 원인
  · JS 스레드가 막히면 → 터치·애니메이션이 전부 멈춤

New Architecture — 이제 이것만 남았습니다

[JS]  ←── JSI (직접 호출) ──→  [C++ / 네이티브]
                                  ↓
        Fabric (새 렌더러) · TurboModules (지연 로딩)

달라진 점
  · JSI — JS 가 네이티브 함수를 직접 호출 (직렬화 없음)
  · Fabric — 동기 레이아웃 가능 → 흰 화면 감소
  · TurboModules — 쓰는 모듈만 로딩 → 시작 속도 개선
  · Hermes V1 — 0.84 부터 기본. 시작 속도·런타임 성능·메모리가 다시 개선됐습니다

여기까지 온 길
  0.68  New Architecture 실험적으로 공개 (옵트인)
  0.76  기본값으로 전환 — 끄는 것도 아직 가능
  0.82  ★ New Architecture 만 남음 (Legacy 를 켤 수 없음)
  0.83  ★ Legacy 코드가 저장소에서 삭제 (Expo SDK 55)
  0.84  Hermes V1 이 기본 엔진
  0.85  Node 20.19.4 이상 요구
  0.86  현재 — Expo SDK 57 이 이 버전을 씁니다 (React 19.2)

웹 React 와 다른 점

import { View, Text, Pressable, StyleSheet } from "react-native";

export default function Hello({ name }: { name: string }) {
  return (
    <View style={styles.box}>
      <Text style={styles.title}>안녕하세요 {name}님</Text>
      <Pressable style={styles.btn} onPress={() => console.log("탭")}>
        <Text style={styles.btnText}>눌러 보세요</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  box:   { padding: 16, gap: 12 },          // ★ gap 지원 (0.71+)
  title: { fontSize: 18, fontWeight: "600" },
  btn:   { backgroundColor: "#2563eb", padding: 12, borderRadius: 8 },
  btnText: { color: "#fff", textAlign: "center" },
});

비교

# 시작
npx create-expo-app@latest my-app --template
cd my-app && npx expo start           # QR 찍으면 실기기에서 바로 확인

# 네이티브 폴더가 필요해지면 (되돌릴 수 있습니다)
npx expo prebuild                      # ios/ android/ 생성

# 빌드 · 배포
npx eas build --platform all
npx eas submit --platform ios

프로젝트 구조 (Expo Router 기준)

app/                       ★ 파일 = 화면 (Next.js 방식)
  _layout.tsx              공통 레이아웃
  index.tsx                → /
  (tabs)/                  탭 그룹
    _layout.tsx
    home.tsx
    profile.tsx
  orders/
    [id].tsx               → /orders/123
  +not-found.tsx
components/                재사용 UI
hooks/                     커스텀 훅
lib/                       api · storage · util
constants/                 색상 · 크기
assets/                    이미지 · 폰트
app.json                   앱 설정 (이름·아이콘·권한)
eas.json                   빌드 프로필

// app.json — 자주 만지는 부분
{
  "expo": {
    "name": "내 앱",
    "slug": "my-app",
    "version": "1.0.0",
    "orientation": "portrait",
    "scheme": "myapp",                    // 딥링크 myapp://
    "ios": { "bundleIdentifier": "com.company.myapp",
             "buildNumber": "1" },
    "android": { "package": "com.company.myapp",
                 "versionCode": 1,
                 "adaptiveIcon": { ... } },
    "plugins": ["expo-router", "expo-secure-store"]
  }
}

기본 컴포넌트

type Props = {
  title: string;
  subtitle?: string;
  onPress: () => void;
  disabled?: boolean;
};

export function Card({ title, subtitle, onPress, disabled }: Props) {
  return (
    <Pressable
      onPress={onPress}
      disabled={disabled}
      // ★ 눌림 상태에 따라 스타일을 함수로 줄 수 있습니다
      style={({ pressed }) => [
        styles.card,
        pressed && styles.pressed,
        disabled && styles.disabled,
      ]}
      // ★ 접근성 — 스토어 심사와 사용자 경험에 중요합니다
      accessibilityRole="button"
      accessibilityLabel={title}
      hitSlop={8}                       // 터치 영역 확대
    >
      <Text style={styles.title}>{title}</Text>
      {subtitle ? <Text style={styles.sub}>{subtitle}</Text> : null}
      {/* ★ subtitle && … 로 쓰면 빈 문자열 "" 일 때 Text 밖 문자열 에러 (아래 0 함정과 같은 원리) */}
    </Pressable>
  );
}

플랫폼 분기

import { Platform } from "react-native";

// ① 값 분기
const padding = Platform.OS === "ios" ? 20 : 16;

// ② select
const shadow = Platform.select({
  ios: { shadowColor: "#000", shadowOpacity: 0.1, shadowRadius: 8 },
  android: { elevation: 4 },
  default: {},
});

// ③ 파일 분기 — 확장자로 자동 선택
//   Button.ios.tsx / Button.android.tsx / Button.tsx

// 버전 확인
if (Platform.OS === "android" && Platform.Version >= 33) { ... }

자주 만나는 실수

// ❌ Text 밖의 문자열 → 즉시 에러
<View>안녕하세요</View>
// ✅
<View><Text>안녕하세요</Text></View>

// ❌ 조건부 렌더링에서 0 이 그대로 렌더링됨
{items.length && <List />}          // 0 이면 "0" 이 화면에 찍힙니다
// ✅
{items.length > 0 && <List />}

// ❌ 이미지에 크기가 없으면 안 보입니다 (원격 이미지)
<Image source={{ uri }} />
// ✅
<Image source={{ uri }} style={{ width: 100, height: 100 }} />

// ❌ 인라인 스타일 객체는 매 렌더마다 새로 생성됩니다
<View style={{ padding: 16 }} />
// ✅ StyleSheet.create 로 밖에서 (r12 성능)

상태를 네 가지로 나누세요

// 훅 기본
const [count, setCount] = useState(0);
setCount(c => c + 1);                  // ★ 이전 값 기반은 함수형으로

// 비싼 계산 캐시
const sorted = useMemo(() => items.toSorted(cmp), [items]);

// 함수 재생성 방지 (자식이 memo 일 때 의미 있음)
const onPress = useCallback((id: string) => navigate(id), [navigate]);

// 부수 효과 — ★ 정리 함수를 꼭 반환하세요
useEffect(() => {
  const sub = AppState.addEventListener("change", handler);
  return () => sub.remove();           // 안 지우면 메모리 누수
}, []);

Zustand — 전역 상태

import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
import AsyncStorage from "@react-native-async-storage/async-storage";

type AuthState = {
  user: User | null;
  login: (u: User) => void;
  logout: () => void;
};

export const useAuth = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      login: (user) => set({ user }),
      logout: () => set({ user: null }),
    }),
    {
      name: "auth",
      storage: createJSONStorage(() => AsyncStorage),
      partialize: (s) => ({ user: s.user }),      // ★ 저장할 것만
    },
  ),
);

// 사용 — ★ 필요한 조각만 구독해야 불필요한 리렌더가 없습니다
const user = useAuth(s => s.user);
const logout = useAuth(s => s.logout);

// ❌ 전체를 구독하면 아무 값이나 바뀔 때마다 리렌더됩니다
const { user, logout } = useAuth();

웹 CSS 와 다른 점

· 기본 flexDirection 이 column  (웹은 row)
· 모든 View 가 이미 display:flex
· 단위가 없습니다 — 숫자는 dp (밀도 독립 픽셀)
· 상속이 없습니다 — 부모의 fontSize 가 자식에 안 내려감
  (단, Text 안의 Text 는 예외)
· 축약형이 제한적 — margin: "0 auto" 같은 문자열 불가
· % 는 일부만 지원, calc() 없음
· position: fixed 없음 (absolute 만)
· z-index 대신 렌더 순서 + elevation(안드로이드)

const styles = StyleSheet.create({
  container: {
    flex: 1,                        // ★ 남은 공간 다 쓰기
    flexDirection: "row",
    justifyContent: "space-between",// 주축 정렬
    alignItems: "center",           // 교차축 정렬
    gap: 12,                        // 0.71+ 지원
    padding: 16,
  },
  card: {
    flex: 1,                        // 형제끼리 균등 분할
    aspectRatio: 16 / 9,            // 비율 고정
    borderRadius: 12,
    overflow: "hidden",             // ★ iOS 는 이게 있어야 자식이 잘림
  },
  // 그림자는 플랫폼마다 다릅니다
  shadow: Platform.select({
    ios: { shadowColor: "#000", shadowOffset: { width: 0, height: 2 },
           shadowOpacity: 0.1, shadowRadius: 8 },
    android: { elevation: 4 },
  }),
});

화면 크기 대응

import { useWindowDimensions } from "react-native";
import { useSafeAreaInsets } from "react-native-safe-area-context";

function Screen() {
  const { width, height } = useWindowDimensions();   // ★ 회전에 반응
  const insets = useSafeAreaInsets();                // 노치·홈바 여백
  const isTablet = width >= 768;

  return (
    <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
      <View style={{ width: isTablet ? "50%" : "100%" }} />
    </View>
  );
}

// ❌ Dimensions.get("window") 는 회전 시 갱신되지 않습니다

키보드 대응 — 실무 필수

<KeyboardAvoidingView
  behavior={Platform.OS === "ios" ? "padding" : "height"}
  keyboardVerticalOffset={headerHeight}
  style={{ flex: 1 }}
>
  <ScrollView keyboardShouldPersistTaps="handled">
    <TextInput ... />
  </ScrollView>
</KeyboardAvoidingView>

// ★ keyboardShouldPersistTaps="handled" 가 없으면
//   키보드가 열린 상태에서 버튼을 한 번에 못 누릅니다 (첫 탭은 닫기만)

ScrollView 를 쓰면 안 되는 이유

ScrollView  — 자식을 "전부" 렌더링하고 메모리에 유지
FlatList    — 화면에 보이는 것 + 약간의 여유분만 (가상화)

항목 1,000개일 때
  ScrollView  → 1,000개 컴포넌트 생성 → 수 초간 멈춤 → 메모리 폭발
  FlatList    → 약 15개만 → 즉시 렌더링

기준: 항목이 20개를 넘거나 개수를 모르면 → FlatList

<FlatList
  data={orders}
  keyExtractor={(item) => item.id}            // ★ 안정적인 고유 키
  renderItem={({ item }) => <OrderRow order={item} />}

  // 성능 옵션
  initialNumToRender={10}
  maxToRenderPerBatch={10}
  windowSize={5}                               // 화면 단위 (기본 21)
  removeClippedSubviews                        // 안드로이드에서 효과 큼

  // 높이가 고정이면 ★ 이게 가장 큰 최적화입니다
  getItemLayout={(_, index) => ({
    length: ROW_HEIGHT, offset: ROW_HEIGHT * index, index,
  })}

  // 무한 스크롤
  onEndReached={fetchNextPage}
  onEndReachedThreshold={0.5}
  ListFooterComponent={isFetching ? <ActivityIndicator /> : null}

  // 당겨서 새로고침
  refreshControl={<RefreshControl refreshing={isRefetching} onRefresh={refetch} />}

  // 빈 상태 · 구분선
  ListEmptyComponent={<Empty message="주문이 없습니다" />}
  ItemSeparatorComponent={() => <View style={styles.sep} />}
/>

항목 컴포넌트 최적화

// ★ memo 로 감싸야 스크롤 시 재렌더가 줄어듭니다
const OrderRow = memo(function OrderRow({ order }: { order: Order }) {
  return (
    <View style={styles.row}>
      <Text>{order.title}</Text>
    </View>
  );
});

// ❌ 인라인 함수 — 매 렌더마다 새 함수 → memo 가 무의미해짐
<FlatList renderItem={({ item }) => <Row onPress={() => go(item.id)} />} />

// ✅ 밖으로 빼고 useCallback
const renderItem = useCallback(
  ({ item }: { item: Order }) => <OrderRow order={item} onPress={onPress} />,
  [onPress],
);

import { FlashList } from "@shopify/flash-list";

<FlashList
  data={orders}
  renderItem={({ item }) => <OrderRow order={item} />}
/>

Expo Router — 파일이 곧 경로

// app/_layout.tsx — 루트 스택
import { Stack } from "expo-router";

export default function RootLayout() {
  return (
    <Stack screenOptions={{ headerShown: true }}>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="orders/[id]" options={{ title: "주문 상세" }} />
      <Stack.Screen name="login" options={{ presentation: "modal" }} />
    </Stack>
  );
}

// app/(tabs)/_layout.tsx — 탭
import { Tabs } from "expo-router";
<Tabs>
  <Tabs.Screen name="home" options={{ title: "홈",
    tabBarIcon: ({ color }) => <Icon name="home" color={color} /> }} />
  <Tabs.Screen name="profile" options={{ title: "내 정보" }} />
</Tabs>

// 이동하기
import { router, useLocalSearchParams, Link } from "expo-router";

router.push("/orders/123");
router.replace("/login");            // 뒤로가기 스택에서 교체
router.back();

<Link href="/orders/123" asChild><Pressable>...</Pressable></Link>

// 파라미터 받기 — app/orders/[id].tsx
const { id } = useLocalSearchParams<{ id: string }>();

인증 흐름 — 실무 패턴

// app/_layout.tsx
export default function RootLayout() {
  const { user, isLoading } = useAuth();
  const segments = useSegments();
  const router = useRouter();

  useEffect(() => {
    if (isLoading) return;
    const inAuthGroup = segments[0] === "(auth)";

    if (!user && !inAuthGroup) router.replace("/(auth)/login");
    else if (user && inAuthGroup) router.replace("/(tabs)/home");
  }, [user, segments, isLoading]);

  if (isLoading) return <SplashScreen />;      // ★ 깜빡임 방지
  return <Stack />;
}

딥링크 · 뒤로가기

// app.json 의 scheme 으로 myapp://orders/123 이 동작합니다
// 웹 링크(Universal Link)는 별도 설정 필요

// 안드로이드 하드웨어 뒤로가기 제어
useEffect(() => {
  const sub = BackHandler.addEventListener("hardwareBackPress", () => {
    if (hasUnsavedChanges) { confirmExit(); return true; }  // 기본 동작 막기
    return false;
  });
  return () => sub.remove();
}, [hasUnsavedChanges]);

직접 관리하면 이렇게 됩니다

const [data, setData] = useState();
const [loading, setLoading] =
  useState(false);
const [error, setError] = useState();

useEffect(() => {
  let cancelled = false;
  setLoading(true);
  fetchOrders()
    .then(d => !cancelled && setData(d))
    .catch(e => !cancelled && setError(e))
    .finally(() => setLoading(false));
  return () => { cancelled = true; };
}, []);
// 캐시·재시도·중복요청·
// 화면 복귀 갱신은? 전부 직접

const { data, isLoading, error }
  = useQuery({
    queryKey: ["orders"],
    queryFn: fetchOrders,
  });
// 캐시 · 중복 제거 · 재시도 ·
// 백그라운드 갱신 · 취소
// 전부 포함 ★

const client = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60_000,          // 1분간은 캐시를 신선하다고 봄
      gcTime: 5 * 60_000,
      retry: 2,
      refetchOnWindowFocus: false, // RN 에서는 AppState 로 대체
    },
  },
});

<QueryClientProvider client={client}><App /></QueryClientProvider>

실무 사용

// 무한 스크롤
const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
  queryKey: ["orders", filter],
  queryFn: ({ pageParam }) => api.getOrders({ cursor: pageParam, ...filter }),
  initialPageParam: null,
  getNextPageParam: (last) => last.nextCursor ?? undefined,
});
const items = data?.pages.flatMap(p => p.items) ?? [];

// 변경 + 낙관적 업데이트 (즉시 반영 후 실패 시 되돌리기)
const { mutate } = useMutation({
  mutationFn: api.toggleLike,
  onMutate: async (id) => {
    await qc.cancelQueries({ queryKey: ["orders"] });
    const prev = qc.getQueryData(["orders"]);
    qc.setQueryData(["orders"], (old) => toggle(old, id));   // ★ 즉시 반영
    return { prev };
  },
  onError: (_e, _v, ctx) => qc.setQueryData(["orders"], ctx.prev),  // 롤백
  onSettled: () => qc.invalidateQueries({ queryKey: ["orders"] }),
});

// 모바일 특화 — 네트워크·앱 상태 연동
import { onlineManager, focusManager } from "@tanstack/react-query";
import NetInfo from "@react-native-community/netinfo";

onlineManager.setEventListener((setOnline) =>
  NetInfo.addEventListener((state) => setOnline(!!state.isConnected)));

AppState.addEventListener("change", (s) =>
  focusManager.setFocused(s === "active"));    // ★ 앱 복귀 시 자동 갱신

무엇을 어디에

// MMKV — 동기라 코드가 단순해집니다
import { MMKV } from "react-native-mmkv";
export const storage = new MMKV({ id: "app", encryptionKey: "..." });

storage.set("theme", "dark");
storage.getString("theme");            // 동기 ★
storage.set("onboarded", true);
storage.getBoolean("onboarded");
storage.delete("theme");

// 토큰은 반드시 SecureStore
import * as SecureStore from "expo-secure-store";
await SecureStore.setItemAsync("refreshToken", token);
const token = await SecureStore.getItemAsync("refreshToken");
await SecureStore.deleteItemAsync("refreshToken");

오프라인 지원

// TanStack Query 캐시를 디스크에 저장 → 오프라인에서도 마지막 데이터 표시
import { persistQueryClient } from "@tanstack/react-query-persist-client";
import { createSyncStoragePersister } from "@tanstack/query-sync-storage-persister";

persistQueryClient({
  queryClient,
  persister: createSyncStoragePersister({
    storage: {
      getItem: (k) => storage.getString(k) ?? null,
      setItem: (k, v) => storage.set(k, v),
      removeItem: (k) => storage.delete(k),
    },
  }),
  maxAge: 24 * 60 * 60 * 1000,
});

// 오프라인에서 한 작업을 나중에 전송 (큐)
type PendingAction = { id: string; type: string; payload: unknown };

async function enqueue(action: PendingAction) {
  const q = JSON.parse(storage.getString("queue") ?? "[]");
  storage.set("queue", JSON.stringify([...q, action]));
}

// 온라인이 되면 순서대로 전송 — ★ 서버가 멱등해야 안전합니다
NetInfo.addEventListener(async (s) => {
  if (!s.isConnected) return;
  const q: PendingAction[] = JSON.parse(storage.getString("queue") ?? "[]");
  for (const a of q) await api.send(a);      // 실패하면 남겨 두기
  storage.set("queue", "[]");
});

권한 요청 패턴

import * as ImagePicker from "expo-image-picker";

async function pickImage() {
  const { status, canAskAgain } =
    await ImagePicker.requestMediaLibraryPermissionsAsync();

  if (status !== "granted") {
    if (!canAskAgain) {
      // ★ "다시 묻지 않음"을 누른 상태 — 설정 앱으로 보내야 합니다
      Alert.alert("사진 권한 필요",
        "설정에서 사진 접근을 허용해 주세요",
        [{ text: "취소" },
         { text: "설정 열기", onPress: () => Linking.openSettings() }]);
    }
    return;
  }

  const result = await ImagePicker.launchImageLibraryAsync({
    mediaTypes: ["images"],
    quality: 0.7,                      // ★ 원본은 너무 큽니다
    allowsEditing: true,
  });
  if (!result.canceled) setImage(result.assets[0].uri);
}

// app.json — 권한 설명 문구 (iOS 는 없으면 심사 반려)
{
  "ios": {
    "infoPlist": {
      "NSCameraUsageDescription": "프로필 사진 촬영에 사용합니다",
      "NSPhotoLibraryUsageDescription": "사진 첨부에 사용합니다",
      "NSLocationWhenInUseUsageDescription": "주변 매장을 찾는 데 사용합니다"
    }
  },
  "android": {
    "permissions": ["CAMERA", "ACCESS_FINE_LOCATION"]
  }
}

푸시 알림

import * as Notifications from "expo-notifications";

// ① 권한 + 토큰 발급
const { status } = await Notifications.requestPermissionsAsync();
if (status !== "granted") return;

const token = (await Notifications.getExpoPushTokenAsync({
  projectId: Constants.expoConfig?.extra?.eas?.projectId,
})).data;
await api.registerPushToken(token);          // ★ 서버에 저장

// ② 안드로이드는 채널이 필요합니다
if (Platform.OS === "android") {
  await Notifications.setNotificationChannelAsync("default", {
    name: "기본", importance: Notifications.AndroidImportance.HIGH,
  });
}

// ③ 수신 처리
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true, shouldPlaySound: true, shouldSetBadge: true,
  }),
});

// ④ 알림 탭 → 해당 화면으로 (딥링크)
Notifications.addNotificationResponseReceivedListener((res) => {
  const { orderId } = res.notification.request.content.data;
  if (orderId) router.push(`/orders/${orderId}`);
});

자주 쓰는 네이티브 모듈

왜 Reanimated 인가

[내장 Animated]  JS 스레드에서 값 계산 → 네이티브로 전달
   → JS 가 바쁘면 애니메이션이 끊깁니다
   → useNativeDriver: true 로 일부만 개선 가능
      (transform·opacity 만 지원, width·색상 불가)

[Reanimated]  worklet 이 UI 스레드에서 직접 실행
   → JS 스레드가 아무리 바빠도 60fps 유지 ★
   → 모든 속성 애니메이션 가능

import Animated, {
  useSharedValue, useAnimatedStyle, withSpring, withTiming,
} from "react-native-reanimated";

function Box() {
  const offset = useSharedValue(0);        // ★ UI 스레드에 사는 값

  const style = useAnimatedStyle(() => ({
    transform: [{ translateX: offset.value }],
  }));                                      // ★ 이 함수는 UI 스레드에서 실행됩니다

  return (
    <>
      <Animated.View style={[styles.box, style]} />
      <Button title="이동" onPress={() => {
        offset.value = withSpring(100, { damping: 15 });
      }} />
    </>
  );
}

제스처 — 스와이프 삭제

import { Gesture, GestureDetector } from "react-native-gesture-handler";
import { runOnJS } from "react-native-reanimated";

function SwipeRow({ onDelete }: { onDelete: () => void }) {
  const x = useSharedValue(0);

  const pan = Gesture.Pan()
    .onUpdate((e) => { x.value = Math.min(0, e.translationX); })
    .onEnd(() => {
      if (x.value < -120) {
        x.value = withTiming(-400);
        runOnJS(onDelete)();          // ★ UI 스레드 → JS 함수 호출
      } else {
        x.value = withSpring(0);
      }
    });

  const style = useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={style}>{/* 내용 */}</Animated.View>
    </GestureDetector>
  );
}

레이아웃 애니메이션 — 가장 쉬운 방법

import Animated, {
  FadeIn, FadeOut, LinearTransition,
} from "react-native-reanimated";
// ★ 예전 이름이던 Layout 은 폐기됐습니다 → LinearTransition 을 쓰세요

// 나타나고 사라질 때 자동으로 애니메이션
<Animated.View entering={FadeIn.duration(200)} exiting={FadeOut}
               layout={LinearTransition.springify()}>
  <Text>{item.title}</Text>
</Animated.View>
// ★ 코드 한 줄로 목록 추가·삭제 애니메이션이 붙습니다

// 리스트 항목이 자리를 옮길 때(정렬·필터·삭제)도 한 줄이면 됩니다
<Animated.FlatList
  data={items}
  keyExtractor={(it) => it.id}
  itemLayoutAnimation={LinearTransition}
  renderItem={({ item }) => <Row item={item} />}
/>

원인 대조표

// ① 리렌더 줄이기
const Row = memo(RowComponent);                        // 자식 메모
const handler = useCallback(() => {}, []);             // 함수 고정
const value = useMemo(() => compute(data), [data]);    // 계산 캐시

// ② 입력은 로컬 상태로 두고, 무거운 갱신은 뒤로 미룹니다
const [text, setText] = useState("");
const deferredText = useDeferredValue(text);
//  ★ 디바운스가 아닙니다 — "정해진 시간만큼 기다렸다 한 번"이 아니라
//    입력 렌더를 먼저 처리하고 이 값을 쓰는 렌더를 "낮은 우선순위"로 돌립니다.
//    입력이 계속되면 뒤 렌더는 중단(재시작)되고, 한가해지면 따라잡습니다.
useEffect(() => { search(deferredText); }, [deferredText]);

// ③ 이미지 — expo-image 로 (캐시·placeholder 내장)
import { Image } from "expo-image";
<Image source={{ uri }} style={{ width: 100, height: 100 }}
       contentFit="cover" transition={200}
       cachePolicy="memory-disk" />

// ④ 무거운 계산은 전환 이후로
InteractionManager.runAfterInteractions(() => heavyWork());

측정하기

# 개발 메뉴 (실기기 흔들기 · 시뮬레이터 Cmd+D)
Perf Monitor          # JS·UI 스레드 FPS 확인 ★
                      # UI FPS 는 높은데 JS FPS 가 낮다 → JS 스레드가 원인

# React DevTools Profiler — 어느 컴포넌트가 자주 렌더되는지
npx react-devtools

# 번들 크기 분석
npx expo export && npx source-map-explorer dist/**/*.js

# Hermes 프로파일러 (실제 함수별 시간)
# 개발 메뉴 → Enable Sampling Profiler

시작 속도 개선

• Hermes 사용 확인 (기본값이지만 확인해 두세요)
• 초기 화면에 필요 없는 모듈은 지연 import
• 스플래시 화면을 준비될 때까지 유지 (SplashScreen.preventAutoHideAsync)
• 큰 JSON·폰트는 필요할 때 로딩
• 앱 시작 시 API 를 여러 개 동시에(Promise.all) — 순차 호출 금지

언제 필요한가

• 사내 SDK(결제·인증·보안 솔루션)를 연동해야 할 때
• 기존 네이티브 앱의 일부만 RN 으로 교체할 때
• 블루투스·NFC·특수 하드웨어처럼 패키지가 없는 기능
• 성능 때문에 C++ 로 처리해야 할 때

# Expo 모듈로 만들기 (가장 편합니다)
npx create-expo-module my-native-module

# 로컬 모듈 (앱 안에서만 쓸 때)
npx create-expo-module --local my-module

// android/src/main/java/.../MyModule.kt
class MyModule : Module() {
  override fun definition() = ModuleDefinition {
    Name("MyModule")

    Function("getDeviceName") {
      return@Function Build.MODEL          // 동기 함수
    }

    AsyncFunction("readSensor") { promise: Promise ->
      // 오래 걸리는 작업
      promise.resolve(mapOf("value" to 42))
    }

    Events("onSensorChange")               // 이벤트 발행
  }
}

Swift 쪽과 JS 쪽

// ios/MyModule.swift
public class MyModule: Module {
  public func definition() -> ModuleDefinition {
    Name("MyModule")

    Function("getDeviceName") { () -> String in
      UIDevice.current.model
    }

    AsyncFunction("readSensor") { () -> [String: Any] in
      ["value": 42]
    }
  }
}

// src/index.ts — JS 쪽 타입 정의
import { requireNativeModule } from "expo-modules-core";

declare class MyModuleType {
  getDeviceName(): string;
  readSensor(): Promise<{ value: number }>;
}

export default requireNativeModule<MyModuleType>("MyModule");

// 사용
import MyModule from "my-native-module";
const name = MyModule.getDeviceName();
const { value } = await MyModule.readSensor();

EAS 빌드

// eas.json
{
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"        // 팀 내부 배포
    },
    "preview": {
      "distribution": "internal",
      "android": { "buildType": "apk" }  // 설치 파일로 바로 공유
    },
    "production": {
      "autoIncrement": true,             // ★ 빌드 번호 자동 증가
      "env": { "API_URL": "https://api.example.com" }
    }
  },
  "submit": { "production": { ... } }
}

eas build --profile production --platform all
eas submit --platform ios              # App Store Connect 로 업로드
eas submit --platform android

# OTA 업데이트 — ★ JS 만 바뀌었다면 심사 없이 즉시 반영
eas update --branch production --message "버그 수정"

심사에서 자주 반려되는 이유

• 권한 설명 문구 누락·불충분 — “왜 필요한지” 구체적으로 (r10)
• 테스트 계정 미제공 — 로그인이 필요한 앱은 심사자용 계정 필수
• 결제 우회 — 디지털 재화를 외부 결제로 유도하면 즉시 반려
• 계정 삭제 기능 없음 — 회원가입이 있으면 앱 내 삭제가 의무입니다
• 크래시 — 심사자 기기에서 죽으면 바로 반려
• 개인정보 처리방침 URL 누락
• 미완성 기능·플레이스홀더 화면

출시 체크리스트

☐ 릴리스 빌드에서 전체 흐름 테스트
☐ 크래시 리포팅 연동 (Sentry)
☐ 저사양 안드로이드에서 확인
☐ 다크 모드 · 큰 글씨 설정에서 깨지지 않는지
☐ 오프라인·느린 네트워크에서 동작
☐ 딥링크 · 푸시 알림 동작
☐ 앱 아이콘 · 스플래시 · 스크린샷 준비
☐ 버전·빌드 번호 증가
☐ API 주소가 운영으로 되어 있는지 ★
☐ 콘솔 로그·디버그 코드 제거

두 개의 세계

프로젝트 구조

my-app/
  src/
    main/                    ★ Node 환경
      index.ts               앱 시작 · 창 생성
      ipc/                   IPC 핸들러 (기능별로 분리)
        file.handler.ts
        db.handler.ts
      services/              실제 로직
      windows/               창 관리
    preload/
      index.ts               ★ contextBridge 로 API 노출
    renderer/                ★ 브라우저 환경 (React 등)
      App.tsx
      index.html
  electron-builder.yml       패키징 설정
  package.json

# 요즘 표준 템플릿 (Vite 기반 — HMR 이 됩니다)
npm create @quick-start/electron@latest
# 또는
npx create-electron-vite

# 옛 방식(electron-forge + webpack)보다 빌드가 훨씬 빠릅니다

메인 프로세스

import { app, BrowserWindow, shell } from "electron";
import path from "node:path";

let mainWindow: BrowserWindow | null = null;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1200, height: 800,
    minWidth: 940, minHeight: 600,
    show: false,                              // ★ 준비될 때까지 숨김
    titleBarStyle: process.platform === "darwin" ? "hiddenInset" : "default",
    webPreferences: {
      preload: path.join(__dirname, "../preload/index.js"),
      contextIsolation: true,                 // ★ 반드시 true (e04)
      nodeIntegration: false,                 // ★ 반드시 false
      sandbox: true,
    },
  });

  // ★ 흰 화면 깜빡임 방지
  mainWindow.once("ready-to-show", () => mainWindow?.show());

  // 외부 링크는 기본 브라우저로 (앱 안에서 열면 보안 위험)
  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
    shell.openExternal(url);
    return { action: "deny" };
  });

  if (process.env.NODE_ENV === "development") {
    mainWindow.loadURL("http://localhost:5173");
    mainWindow.webContents.openDevTools();
  } else {
    mainWindow.loadFile(path.join(__dirname, "../renderer/index.html"));
  }
}

앱 생명주기 — OS 마다 다릅니다

app.whenReady().then(() => {
  createWindow();

  // ★ macOS — 독 아이콘 클릭 시 창이 없으면 다시 만듭니다
  app.on("activate", () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

// ★ macOS 는 창을 닫아도 앱이 살아 있는 것이 관례입니다
app.on("window-all-closed", () => {
  if (process.platform !== "darwin") app.quit();
});

// 단일 인스턴스 — 두 번 실행되지 않게 (거의 항상 필요합니다)
if (!app.requestSingleInstanceLock()) {
  app.quit();
} else {
  app.on("second-instance", () => {
    if (mainWindow) {
      if (mainWindow.isMinimized()) mainWindow.restore();
      mainWindow.focus();
    }
  });
}

// 종료 전 정리
app.on("before-quit", async (e) => {
  if (hasUnsavedWork) {
    e.preventDefault();
    const ok = await confirmQuit();
    if (ok) { hasUnsavedWork = false; app.quit(); }
  }
});

요청-응답 (가장 많이 씁니다)

// ① 메인 — 핸들러 등록
import { ipcMain, dialog } from "electron";

ipcMain.handle("file:read", async (event, filePath: string) => {
  // ★ 반드시 검증하세요 (e04)
  const safe = path.resolve(DATA_DIR, filePath);
  if (!safe.startsWith(path.resolve(DATA_DIR) + path.sep)) {
    throw new Error("잘못된 경로입니다");
  }
  return fs.readFile(safe, "utf8");
});

ipcMain.handle("dialog:openFile", async () => {
  const { canceled, filePaths } = await dialog.showOpenDialog({
    properties: ["openFile"],
    filters: [{ name: "엑셀", extensions: ["xlsx", "csv"] }],
  });
  return canceled ? null : filePaths[0];
});

// ② 프리로드 — 화면에 노출할 API 만 정의
import { contextBridge, ipcRenderer } from "electron";

const api = {
  readFile: (p: string) => ipcRenderer.invoke("file:read", p),
  openFile: () => ipcRenderer.invoke("dialog:openFile"),
};
contextBridge.exposeInMainWorld("api", api);
export type Api = typeof api;                 // ★ 타입을 렌더러에서 재사용

// ③ 렌더러 — 그냥 함수처럼 씁니다
const path = await window.api.openFile();
if (path) {
  const text = await window.api.readFile(path);
}

메인 → 렌더러 (진행률·알림)

// 메인에서 보내기
mainWindow.webContents.send("job:progress", { done: 30, total: 100 });

// 프리로드 — 구독 API 를 만들어 줍니다
const api = {
  onProgress: (cb: (p: Progress) => void) => {
    const listener = (_e: unknown, p: Progress) => cb(p);
    ipcRenderer.on("job:progress", listener);
    return () => ipcRenderer.off("job:progress", listener);   // ★ 해제 함수 반환
  },
};

// 렌더러 (React)
useEffect(() => {
  const off = window.api.onProgress(setProgress);
  return off;                                  // ★ 언마운트 시 해제 (누수 방지)
}, []);

타입 안전하게 쓰기

// renderer/global.d.ts
import type { Api } from "../preload";

declare global {
  interface Window { api: Api; }               // ★ 자동완성이 됩니다
}
export {};

왜 위험한가

nodeIntegration: true 로 두면
  화면(웹 페이지)에서 require("child_process") 가 됩니다.
  → 표시하는 콘텐츠에 XSS 가 하나라도 있으면
  → 공격자가 사용자 PC 에서 "무슨 명령이든" 실행합니다

위험이 들어오는 경로
  · 외부 웹사이트를 iframe·webview 로 표시
  · 서버에서 받은 HTML 을 innerHTML 로 넣기
  · 사용자가 입력한 마크다운 렌더링
  · 취약한 npm 패키지 (🧬 전문가 d13)

// ★ 안전한 기본 설정 — 이대로 두세요
webPreferences: {
  contextIsolation: true,       // 프리로드와 페이지의 컨텍스트 분리
  nodeIntegration: false,       // 페이지에서 Node 사용 불가
  sandbox: true,                // 렌더러를 샌드박스에
  webSecurity: true,            // ★ 개발 편의로도 끄지 마세요
  allowRunningInsecureContent: false,
  preload: path.join(__dirname, "preload.js"),
}

안전한 API 노출

contextBridge
 .exposeInMainWorld("api", {
   fs: require("fs"),
   exec: require("child_process")
          .exec,
   ipc: ipcRenderer,   // 무엇이든
 });                   // 호출 가능

contextBridge
 .exposeInMainWorld("api", {
   readConfig: () =>
     ipcRenderer.invoke("config:read"),
   saveReport: (data) =>
     ipcRenderer.invoke("report:save",
                        data),
 });   // 정해진 동작만

// 메인 쪽에서도 반드시 검증합니다 (프리로드는 우회될 수 있습니다)
ipcMain.handle("report:save", async (event, data: unknown) => {
  // ① 발신자 확인
  if (event.senderFrame?.url !== expectedUrl) throw new Error("거부");

  // ② 입력 검증 (Zod)
  const parsed = ReportSchema.parse(data);

  // ③ 경로·권한 검증
  const docs = path.resolve(app.getPath("documents"));
  const target = path.resolve(docs, parsed.filename);
  //  ★ + path.sep 까지 붙여 비교 — 없으면 "Documents-evil\x" 같은 형제 폴더가 통과합니다
  if (!target.startsWith(docs + path.sep)) throw new Error("거부");

  await fs.writeFile(target, JSON.stringify(parsed));
});

보안 체크리스트

• ☐ contextIsolation: true · nodeIntegration: false
• ☐ CSP 헤더 설정 (인라인 스크립트 차단)
• ☐ 외부 링크는 shell.openExternal 로만
• ☐ will-navigate 로 예상 밖 이동 차단
• ☐ 원격 콘텐츠를 로드한다면 반드시 HTTPS
• ☐ DB 접속 정보·API 키를 앱에 넣지 않기 — 디컴파일하면 다 보입니다
• ☐ npm audit · Electron 최신 버전 유지 (Chromium 취약점 패치)

애플리케이션 메뉴

import { Menu, shell, app } from "electron";

const isMac = process.platform === "darwin";

const template: Electron.MenuItemConstructorOptions[] = [
  ...(isMac ? [{ role: "appMenu" as const }] : []),
  {
    label: "파일",
    submenu: [
      { label: "새로 만들기", accelerator: "CmdOrCtrl+N",
        click: () => mainWindow?.webContents.send("menu:new") },
      { label: "열기…", accelerator: "CmdOrCtrl+O", click: openFile },
      { type: "separator" },
      isMac ? { role: "close" } : { role: "quit" },
    ],
  },
  { role: "editMenu" },              // 복사·붙여넣기 (★ 이거 없으면 Cmd+C 가 안 됩니다)
  { role: "viewMenu" },
  {
    label: "도움말",
    submenu: [{ label: "문서 보기",
                click: () => shell.openExternal("https://docs.example.com") }],
  },
];

Menu.setApplicationMenu(Menu.buildFromTemplate(template));

트레이 · 컨텍스트 메뉴 · 단축키

import { Tray, Menu, nativeImage, globalShortcut } from "electron";

// 트레이 (백그라운드 상주 앱에 필수)
const tray = new Tray(nativeImage.createFromPath(iconPath));
tray.setToolTip("내 앱");
tray.setContextMenu(Menu.buildFromTemplate([
  { label: "창 열기", click: () => mainWindow?.show() },
  { label: "동기화", click: sync },
  { type: "separator" },
  { label: "종료", click: () => app.quit() },
]));
tray.on("click", () => mainWindow?.isVisible()
  ? mainWindow.hide() : mainWindow?.show());

// 전역 단축키 — 앱이 배경에 있어도 동작합니다
app.whenReady().then(() => {
  const ok = globalShortcut.register("CmdOrCtrl+Shift+K", () => {
    mainWindow?.show();
    mainWindow?.webContents.send("shortcut:quickOpen");
  });
  if (!ok) log.warn("단축키 등록 실패 — 다른 앱이 사용 중");
});

app.on("will-quit", () => globalShortcut.unregisterAll());   // ★ 정리 필수

// 창을 닫아도 트레이에 남기기 (백그라운드 앱 패턴)
let isQuitting = false;
app.on("before-quit", () => { isQuitting = true; });

mainWindow.on("close", (e) => {
  if (!isQuitting) {
    e.preventDefault();
    mainWindow?.hide();
    return false;
  }
});

파일 선택 · 저장

// 열기
ipcMain.handle("dialog:open", async () => {
  const { canceled, filePaths } = await dialog.showOpenDialog(mainWindow!, {
    title: "데이터 파일 선택",
    properties: ["openFile", "multiSelections"],
    filters: [
      { name: "스프레드시트", extensions: ["xlsx", "xls", "csv"] },
      { name: "모든 파일", extensions: ["*"] },
    ],
    defaultPath: app.getPath("documents"),
  });
  return canceled ? [] : filePaths;
});

// 저장
ipcMain.handle("dialog:save", async (_e, defaultName: string) => {
  const { canceled, filePath } = await dialog.showSaveDialog(mainWindow!, {
    defaultPath: path.join(app.getPath("downloads"), defaultName),
    filters: [{ name: "엑셀", extensions: ["xlsx"] }],
  });
  return canceled ? null : filePath;
});

// 확인 대화상자
const { response } = await dialog.showMessageBox(mainWindow!, {
  type: "warning",
  buttons: ["취소", "삭제"],
  defaultId: 0, cancelId: 0,
  message: "정말 삭제하시겠습니까?",
  detail: "이 작업은 되돌릴 수 없습니다.",
});
if (response === 1) doDelete();

앱 데이터 위치 · 드래그 앤 드롭

// ★ 설치 폴더에는 쓰지 마세요 — 권한이 없을 수 있습니다
app.getPath("userData");     // 설정·DB (앱 전용, 자동 생성됨)
app.getPath("documents");    // 사용자 문서
app.getPath("downloads");
app.getPath("temp");
app.getPath("logs");

// 예: Windows → C:\Users\이름\AppData\Roaming\내앱\
//     macOS   → ~/Library/Application Support/내앱/

// 렌더러 — 드래그 앤 드롭
function DropZone() {
  return (
    <div
      onDragOver={(e) => e.preventDefault()}
      onDrop={async (e) => {
        e.preventDefault();
        // Electron 32+ 는 webUtils 로 실제 경로를 얻습니다
        const paths = [...e.dataTransfer.files]
          .map(f => window.api.getPathForFile(f));
        await window.api.processFiles(paths);
      }}
    >파일을 여기로 끌어다 놓으세요</div>
  );
}

// preload
import { webUtils } from "electron";
getPathForFile: (file: File) => webUtils.getPathForFile(file),

설정 — electron-store

import Store from "electron-store";

type Config = {
  theme: "light" | "dark";
  serverUrl: string;
  recentFiles: string[];
};

const store = new Store<Config>({
  defaults: { theme: "light", serverUrl: "", recentFiles: [] },
  schema: {                                  // ★ 검증 스키마
    theme: { type: "string", enum: ["light", "dark"] },
    serverUrl: { type: "string", format: "uri" },
  },
  encryptionKey: "obfuscation-only",         // ⚠️ 난독화 수준일 뿐입니다
  migrations: {                              // 버전 업 시 데이터 이전
    "1.1.0": (s) => s.set("recentFiles", []),
  },
});

store.get("theme");
store.set("theme", "dark");
store.onDidChange("theme", (newV) => applyTheme(newV));

// OS 수준 암호화 (Electron 내장)
import { safeStorage } from "electron";

if (safeStorage.isEncryptionAvailable()) {
  const enc = safeStorage.encryptString(token);
  store.set("token", enc.toString("base64"));
  // 복호화
  const dec = safeStorage.decryptString(Buffer.from(store.get("token"), "base64"));
}

데이터가 많으면 SQLite

import Database from "better-sqlite3";
import path from "node:path";

const db = new Database(path.join(app.getPath("userData"), "app.db"));
db.pragma("journal_mode = WAL");             // ★ 동시 읽기 성능

db.exec(`
  CREATE TABLE IF NOT EXISTS records (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    amount INTEGER NOT NULL,
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
  );
  CREATE INDEX IF NOT EXISTS idx_created ON records(created_at);
`);

// 준비된 문장 — 반복 실행이 빠릅니다
const insert = db.prepare("INSERT INTO records (name, amount) VALUES (?, ?)");
const findAll = db.prepare("SELECT * FROM records ORDER BY id DESC LIMIT ?");

// 대량 삽입은 트랜잭션으로 (수십 배 빨라집니다)
const insertMany = db.transaction((rows: Row[]) => {
  for (const r of rows) insert.run(r.name, r.amount);
});
insertMany(rows);

라이브러리 없이 — 내장 node:sqlite

// Electron 42 는 Node 24.15 를 내장하므로 SQLite 가 런타임에 이미 있습니다.
// 의존성도, 네이티브 재빌드(electron-rebuild)도 필요 없습니다 —
// Electron 을 올릴 때마다 better-sqlite3 를 다시 빌드하던 고생이 사라집니다.
import { DatabaseSync } from "node:sqlite";
import path from "node:path";

const db = new DatabaseSync(path.join(app.getPath("userData"), "app.db"));
db.exec("PRAGMA journal_mode = WAL");
db.prepare("INSERT INTO records (name, amount) VALUES (?, ?)").run(name, amount);
db.prepare("SELECT * FROM records ORDER BY id DESC LIMIT ?").all(50);

창 여러 개 다루기

const windows = new Map<string, BrowserWindow>();

function openDetailWindow(id: string) {
  const existing = windows.get(id);
  if (existing) { existing.focus(); return existing; }   // ★ 중복 방지

  const win = new BrowserWindow({
    width: 800, height: 600,
    parent: mainWindow!,          // 부모 지정 (항상 위에 뜸)
    modal: false,
    webPreferences: { preload, contextIsolation: true, nodeIntegration: false },
  });

  win.loadURL(`${baseUrl}#/detail/${id}`);
  win.on("closed", () => windows.delete(id));            // ★ 정리
  windows.set(id, win);
  return win;
}

// 모든 창에 브로드캐스트
function broadcast(channel: string, payload: unknown) {
  for (const w of BrowserWindow.getAllWindows()) {
    w.webContents.send(channel, payload);
  }
}

창 간 상태 공유

// ★ 상태의 원본은 "메인 프로세스"에 두세요
class AppState {
  private data: State = initialState;

  update(patch: Partial<State>) {
    this.data = { ...this.data, ...patch };
    broadcast("state:changed", this.data);     // 모든 창에 알림
  }
  get() { return this.data; }
}

ipcMain.handle("state:get", () => appState.get());
ipcMain.handle("state:update", (_e, patch) => appState.update(patch));

// 렌더러 — 훅으로 감싸면 편합니다
function useAppState() {
  const [state, setState] = useState<State | null>(null);

  useEffect(() => {
    window.api.getState().then(setState);
    return window.api.onStateChanged(setState);   // 구독 + 해제
  }, []);

  return [state, window.api.updateState] as const;
}

그 밖의 창 기능

win.setAlwaysOnTop(true, "floating");     // 항상 위
win.setFullScreen(true);
win.flashFrame(true);                      // 작업 표시줄 깜빡임 (알림)
win.setProgressBar(0.5);                   // ★ 독·작업표시줄 진행률
win.setOverlayIcon(icon, "3개 알림");       // Windows 배지

// 프레임 없는 창 (커스텀 타이틀바)
new BrowserWindow({ frame: false, titleBarStyle: "hidden",
                    titleBarOverlay: { color: "#0b0f1a", symbolColor: "#fff" } });

electron-updater

import { autoUpdater } from "electron-updater";
import log from "electron-log";

autoUpdater.logger = log;
autoUpdater.autoDownload = false;            // ★ 사용자에게 먼저 묻기

app.whenReady().then(() => {
  autoUpdater.checkForUpdates();
  setInterval(() => autoUpdater.checkForUpdates(), 4 * 60 * 60 * 1000);  // 4시간
});

autoUpdater.on("update-available", async (info) => {
  const { response } = await dialog.showMessageBox({
    type: "info",
    buttons: ["나중에", "지금 받기"],
    message: `새 버전 ${info.version} 이 있습니다`,
    detail: info.releaseNotes?.toString().slice(0, 500),
  });
  if (response === 1) autoUpdater.downloadUpdate();
});

autoUpdater.on("download-progress", (p) =>
  mainWindow?.setProgressBar(p.percent / 100));

autoUpdater.on("update-downloaded", async () => {
  const { response } = await dialog.showMessageBox({
    buttons: ["나중에", "지금 재시작"],
    message: "업데이트 준비 완료",
  });
  if (response === 1) autoUpdater.quitAndInstall();
});

autoUpdater.on("error", (e) => log.error("업데이트 실패", e));

배포 채널 설정

# electron-builder.yml
publish:
  provider: github          # 또는 s3 · generic(사내 서버)
  owner: my-org
  repo: my-app

# 사내 서버를 쓴다면
publish:
  provider: generic
  url: https://updates.company.internal/my-app/

업데이트 서버에 올라가는 파일
  latest.yml           버전 정보 · 파일 해시 (Windows)
  latest-mac.yml       macOS
  my-app-1.2.0.exe     설치 파일
  my-app-1.2.0.exe.blockmap   ★ 차등 다운로드용

blockmap 이 있으면 "바뀐 부분만" 받아 업데이트가 훨씬 빠릅니다.

electron-builder 설정

# electron-builder.yml
appId: com.company.myapp
productName: 내 업무 도구
copyright: Copyright © 2026 회사

directories:
  output: release
  buildResources: build

files:
  - "dist/**"
  - "!**/*.map"                    # 소스맵 제외 (용량·보안)
  - "!node_modules/**/{test,__tests__,*.md}"

asar: true                         # 소스를 하나로 묶음 (★ 완전한 보호는 아닙니다)
asarUnpack:
  - "**/*.node"                    # 네이티브 모듈은 풀어 둬야 동작

win:
  target: [{ target: nsis, arch: [x64] }]
  icon: build/icon.ico
nsis:
  oneClick: false                  # 설치 경로를 고를 수 있게
  allowToChangeInstallationDirectory: true
  createDesktopShortcut: true
  shortcutName: 내 업무 도구

mac:
  target: [{ target: dmg, arch: [x64, arm64] }]
  category: public.app-category.productivity
  hardenedRuntime: true            # ★ 공증에 필요
  entitlements: build/entitlements.mac.plist

linux:
  target: [AppImage, deb]

빌드 · 서명

# 빌드
npm run build && npx electron-builder --win --x64
npx electron-builder --mac --arm64 --x64
npx electron-builder -mwl                 # 전부 (각 OS 에서 실행해야 함)

# ★ 크로스 빌드는 제약이 많습니다
#   macOS 앱은 macOS 에서만 서명·공증할 수 있습니다
#   → CI(GitHub Actions)에서 OS 별 러너를 쓰는 것이 정석입니다

# .github/workflows/build.yml
jobs:
  build:
    strategy:
      matrix:
        os: [windows-latest, macos-latest, ubuntu-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24, cache: npm }
      - run: npm ci
      - run: npm run build
      - run: npx electron-builder --publish always
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CSC_LINK: ${{ secrets.CSC_LINK }}          # 인증서
          CSC_KEY_PASSWORD: ${{ secrets.CSC_PASSWORD }}
          APPLE_ID: ${{ secrets.APPLE_ID }}          # 공증
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_PW }}

시작 속도

• show: false + ready-to-show — 흰 화면 제거(e02)
• 렌더러 번들을 작게 — 큰 라이브러리는 지연 로딩
• 메인에서 동기 파일 I/O 금지 — 창 뜨는 시간이 그대로 늘어납니다
• DB·업데이트 확인은 창을 띄운 뒤에
• v8 코드 캐시 활용 (electron-builder 의 electronLanguages 정리 포함)

// ❌ 앱 시작을 막는 코드
app.whenReady().then(async () => {
  await loadHugeConfig();        // 2초
  await checkForUpdates();       // 3초
  createWindow();                // ← 5초 뒤에야 창이 뜸
});

// ✅ 창부터 띄우고 나머지는 뒤에서
app.whenReady().then(() => {
  createWindow();
  setImmediate(async () => {
    await loadHugeConfig();
    autoUpdater.checkForUpdates();
  });
});

메모리 관리

// 프로세스별 메모리 확인
const metrics = app.getAppMetrics();
metrics.forEach(m => log.info(m.type, m.memory.workingSetSize, "KB"));

// 백그라운드 창의 렌더링 억제
win.webContents.setBackgroundThrottling(true);   // 기본값 (숨겨지면 타이머 감속)

// 안 쓰는 창은 destroy
win.destroy();                                    // close 와 달리 즉시 해제

무거운 작업 분리

// ★ 메인 프로세스도 싱글 스레드입니다 — 여기가 막히면 UI 도 멈춥니다
import { utilityProcess } from "electron";

const child = utilityProcess.fork(path.join(__dirname, "heavy-worker.js"));
child.postMessage({ type: "parse", filePath });
child.on("message", (msg) => {
  if (msg.type === "progress") mainWindow?.webContents.send("job:progress", msg);
  if (msg.type === "done") child.kill();
});

// 또는 Node 의 worker_threads (🟩 Node 탭 n09)

① 프로토콜 등록 + 단일 인스턴스

import { app, BrowserWindow } from 'electron';
import path from 'node:path';

// 1) 내 앱이 myapp:// 를 담당한다고 OS 에 등록
if (process.defaultApp) {
  // 개발 중(electron . 로 띄울 때)은 실행 인자까지 함께 등록해야 한다
  if (process.argv.length >= 2)
    app.setAsDefaultProtocolClient('myapp', process.execPath,
                                   [path.resolve(process.argv[1])]);
} else {
  app.setAsDefaultProtocolClient('myapp');
}

// 2) 두 번째 실행을 막는다 — 실패하면 '내가 두 번째'라는 뜻
const primary = app.requestSingleInstanceLock();
if (!primary) {
  app.quit();                 // 인자는 이미 첫 번째 프로세스로 전달됐다
} else {
  app.on('second-instance', (_e, argv) => {
    // Windows · Linux: 두 번째 실행의 argv 가 여기로 넘어온다
    const url = argv.find(a => a.startsWith('myapp://'));
    focusMain();
    if (url) route(url);
  });

  // macOS: argv 가 아니라 open-url 이벤트로 온다
  app.on('open-url', (e, url) => { e.preventDefault(); focusMain(); route(url); });

  app.whenReady().then(() => {
    createWindow();
    // Windows · Linux 첫 실행: 시작 인자에 딥링크가 섞여 있다
    const url = process.argv.find(a => a.startsWith('myapp://'));
    if (url) route(url);
  });
}

② URL 을 화면 이동으로 — 검증이 먼저

function focusMain() {
  const win = BrowserWindow.getAllWindows()[0];
  if (!win) return createWindow();
  if (win.isMinimized()) win.restore();
  win.show();
  win.focus();
}

// 딥링크는 '외부에서 들어온 입력'이다 — 화이트리스트로 받는다
const ROUTES = {
  room:    (id: string) => `/rooms/${encodeURIComponent(id)}`,
  ticket:  (id: string) => `/tickets/${encodeURIComponent(id)}`,
} as const;

function route(raw: string) {
  let u: URL;
  try { u = new URL(raw); } catch { return; }
  if (u.protocol !== 'myapp:') return;

  const kind = u.hostname;                       // myapp://room/42 → 'room'
  const id   = u.pathname.replace(/^\//, '');
  const make = ROUTES[kind as keyof typeof ROUTES];
  if (!make) return;                             // 모르는 경로는 조용히 버린다

  BrowserWindow.getAllWindows()[0]
    ?.webContents.send('deeplink:navigate', make(id));
}

③ 파일 연결 · 자동 시작 · 최근 항목

// 파일 더블클릭으로 내 앱이 열리게 (.myproj 연결)
// macOS
app.on('open-file', (e, filePath) => { e.preventDefault(); openProject(filePath); });
// Windows · Linux — 경로가 argv 로 들어온다 (딥링크와 같은 통로)

// 로그인 시 자동 시작 — '조용히' 트레이로만 뜨게
app.setLoginItemSettings({
  openAtLogin: true,
  openAsHidden: true,                       // macOS
  args: ['--hidden'],                       // Windows 에서 우리가 직접 해석
});

// 최근 파일 (Windows 점프리스트 · macOS 독 메뉴에 자동 반영)
app.addRecentDocument(filePath);

// Windows 작업 표시줄 진행률 · 배지
win.setProgressBar(0.42);                   // -1 이면 숨김
app.setBadgeCount(3);                       // macOS · 일부 Linux

④ 상용 앱이 실제로 하는 것

// 닫기 = 종료가 아니라 숨기기 (트레이 상주형 앱의 표준)
let quitting = false;
app.on('before-quit', () => { quitting = true; });

win.on('close', (e) => {
  if (quitting) return;                     // 진짜 종료
  e.preventDefault();
  win.hide();
  if (process.platform === 'darwin') app.dock?.hide();
});

왜 spawn 이 아니라 pty 인가

npm i node-pty @xterm/xterm @xterm/addon-fit
# node-pty 는 네이티브 모듈 → Electron ABI 로 다시 빌드해야 한다
npm i -D @electron/rebuild && npx electron-rebuild

메인 프로세스 — 세션 관리

import * as pty from 'node-pty';
import { app, ipcMain, BrowserWindow } from 'electron';
import os from 'node:os';

const shell = process.platform === 'win32'
  ? (process.env.COMSPEC ?? 'powershell.exe')
  : (process.env.SHELL   ?? '/bin/bash');

const sessions = new Map<string, pty.IPty>();

ipcMain.handle('term:create', (e, { cols, rows, cwd }) => {
  const id = crypto.randomUUID();
  const p = pty.spawn(shell, [], {
    name: 'xterm-color', cols, rows,
    cwd: cwd ?? os.homedir(),
    env: { ...process.env, TERM: 'xterm-256color' },
  });

  // ── 흐름 제어: 출력을 모아서 보낸다 ──────────────────
  // 빌드 로그는 초당 수천 줄이 나온다. 한 줄마다 IPC 를 태우면
  // 렌더러가 먼저 죽는다. 16ms(한 프레임) 단위로 묶어 보낸다.
  let buf = '', timer: NodeJS.Timeout | null = null;
  const wc = BrowserWindow.fromWebContents(e.sender)!.webContents;
  p.onData(chunk => {
    buf += chunk;
    if (buf.length > 512 * 1024) buf = buf.slice(-512 * 1024);  // 폭주 방어
    timer ??= setTimeout(() => {
      wc.send(`term:data:${id}`, buf); buf = ''; timer = null;
    }, 16);
  });

  p.onExit(({ exitCode }) => {
    wc.send(`term:exit:${id}`, exitCode);
    sessions.delete(id);
  });

  sessions.set(id, p);
  return id;
});

ipcMain.on('term:input',  (_e, id, data)       => sessions.get(id)?.write(data));
ipcMain.on('term:resize', (_e, id, cols, rows) => sessions.get(id)?.resize(cols, rows));
ipcMain.on('term:kill',   (_e, id)             => sessions.get(id)?.kill());

// 창이 닫히면 자식 프로세스도 정리한다 — 안 하면 유령 셸이 남는다
app.on('before-quit', () => { for (const p of sessions.values()) p.kill(); });

렌더러 — xterm.js 연결

import { Terminal } from '@xterm/xterm';
import { FitAddon } from '@xterm/addon-fit';
import '@xterm/xterm/css/xterm.css';

const term = new Terminal({
  fontFamily: 'JetBrains Mono, Consolas, monospace',
  fontSize: 13,
  scrollback: 5000,                 // 무제한으로 두면 메모리가 계속 큽니다
  theme: { background: '#0b1220' },
});
const fit = new FitAddon();
term.loadAddon(fit);
term.open(document.getElementById('term')!);
fit.fit();

const id = await window.api.term.create({ cols: term.cols, rows: term.rows });

term.onData(d => window.api.term.input(id, d));       // 키 입력 → pty
window.api.term.onData(id, d => term.write(d));       // pty 출력 → 화면

// 창 크기가 바뀌면 pty 에도 알려 줘야 줄바꿈이 안 깨진다
const ro = new ResizeObserver(() => {
  fit.fit();
  window.api.term.resize(id, term.cols, term.rows);
});
ro.observe(document.getElementById('term')!);

터미널을 열어 준다는 것의 무게

ipcMain.handle('run', (_e, cmd) =>
  exec(cmd));            // 렌더러가 시키는 대로 다 한다

const TASKS = {
  build:  ['npm', ['run', 'build']],
  deploy: ['node', ['scripts/deploy.js']],
} as const;
const run = promisify(execFile);   // node:util

ipcMain.handle('run', async (_e, key: keyof typeof TASKS) => {
  const t = TASKS[key];
  if (!t) throw new Error('unknown task');
  const { stdout } = await run(t[0], [...t[1]], { shell: false });
  return stdout;   // ★ ChildProcess 객체는 IPC 로 못 넘깁니다 — 결과만 돌려줍니다
});

• 셸을 통하지 않기 — execFile + shell:false
• 작업 목록은 메인에 상수로 — 렌더러는 키만 보냅니다
• 자유 터미널이 꼭 필요하면 기능 자체를 설정으로 잠글 수 있게 두세요
• cwd 는 앱이 정한 작업 폴더로 고정 — 사용자 입력 경로는 검증

① 확장 호스트 띄우기

import { utilityProcess, MessageChannelMain } from 'electron';
import path from 'node:path';

let host: Electron.UtilityProcess | null = null;

function startHost() {
  const { port1, port2 } = new MessageChannelMain();

  host = utilityProcess.fork(path.join(__dirname, 'ext-host.js'), [], {
    serviceName: 'extension-host',
    // 확장은 앱 권한을 그대로 물려받으면 안 된다 — 환경 변수부터 줄인다
    env: { NODE_ENV: process.env.NODE_ENV ?? 'production' },
  });

  host.postMessage({ type: 'init' }, [port1]);   // 포트를 넘겨 직접 통신
  wireRenderer(port2);

  host.on('exit', (code) => {
    log.warn('extension host exited', code);
    if (code !== 0) setTimeout(startHost, 1000);  // 죽으면 되살린다
  });
}

② 매니페스트 + 지연 활성화

{
  "name": "csv-preview",
  "version": "1.2.0",
  "engines": { "myapp": "^3.0.0" },
  "main": "./out/index.js",
  "activationEvents": [
    "onLanguage:csv",
    "onCommand:csv.preview"
  ],
  "contributes": {
    "commands":  [{ "command": "csv.preview", "title": "CSV 미리보기" }],
    "menus":     { "editor/title": [{ "command": "csv.preview" }] },
    "settings":  { "csv.delimiter": { "type": "string", "default": "," } }
  },
  "permissions": ["workspace.read"]
}

③ 확장에게 주는 API — 좁게, 검사하며

// ext-host.js — 확장이 import 하는 것은 '내가 만든 객체' 하나뿐
function makeApi(manifest: Manifest) {
  const can = (p: string) => manifest.permissions?.includes(p) ?? false;

  return Object.freeze({
    commands: {
      register(id: string, fn: () => void) {
        if (!id.startsWith(manifest.name + '.'))     // 남의 이름표 도용 금지
          throw new Error('command id must be prefixed');
        registry.set(id, guard(manifest, fn));
      },
    },
    workspace: {
      readFile: (p: string) => {
        if (!can('workspace.read')) throw new Error('permission denied');
        return rpc('workspace.readFile', p);          // 실제 IO 는 메인이 한다
      },
    },
    window: { showMessage: (m: string) => rpc('window.showMessage', m) },
  });
}

// 오래 잡아먹는 확장은 표시해 둔다 (VS Code 의 '확장 성능' 화면과 같은 원리)
function guard(m: Manifest, fn: Function) {
  return async (...a: unknown[]) => {
    const t = performance.now();
    try { return await fn(...a); }
    finally {
      const ms = performance.now() - t;
      if (ms > 100) telemetry.slowExtension(m.name, ms);
    }
  };
}

④ 설계할 때 미리 정해 둘 것

• API 는 한 번 공개하면 못 지웁니다. 처음엔 다섯 개로 시작하세요 — 늘리는 건 쉽고 줄이는 건 불가능합니다
• 버전 범위를 매니페스트에 강제(engines) — 안 맞으면 로드 거부하고 이유를 보여 줍니다
• 확장 전용 저장소를 주세요(ctx.storagePath). 아니면 남의 설정 파일을 건드립니다
• UI 는 직접 그리게 하지 마세요. DOM 접근을 열면 격리가 무의미해집니다 — 선언(메뉴·명령·뷰 타입)만 받고 그리는 것은 앱이 합니다
• 느린 확장·죽은 확장 목록을 사용자에게 보여 주세요. “앱이 느리다”의 원인을 사용자가 스스로 찾습니다

창 위치 복원 — 모니터 검증이 핵심

import { screen, BrowserWindow } from 'electron';
import Store from 'electron-store';

const store = new Store<{ win: Rect & { max: boolean } }>();

function restoreBounds() {
  const s = store.get('win');
  const def = { width: 1280, height: 800 };
  if (!s) return def;

  // ★ 저장된 좌표가 '지금도 존재하는 화면' 안인지 확인한다.
  //   노트북에서 외부 모니터를 빼면 창이 화면 밖에 놓여 영영 안 보인다.
  const visible = screen.getAllDisplays().some(d => {
    const w = d.workArea;
    return s.x >= w.x - 40 && s.y >= w.y - 40 &&
           s.x + 80 <= w.x + w.width && s.y + 40 <= w.y + w.height;
  });
  return visible ? s : def;                 // 안 보이면 기본 위치로
}

const win = new BrowserWindow({ ...restoreBounds(), show: false });
if (store.get('win')?.max) win.maximize();
win.once('ready-to-show', () => win.show());   // 흰 화면 깜빡임 방지

// 저장은 몰아서 — resize 이벤트는 드래그 중 초당 수십 번 옵니다
let t: NodeJS.Timeout;
const save = () => {
  clearTimeout(t);
  t = setTimeout(() => {
    if (win.isDestroyed()) return;
    store.set('win', { ...win.getNormalBounds(), max: win.isMaximized() });
  }, 400);
};
win.on('resize', save);
win.on('move', save);
// ★ 닫을 때는 즉시 — 400ms 뒤에는 창이 이미 없어서 위의 save 로는 저장되지 않습니다
win.on('close', () => {
  clearTimeout(t);
  store.set('win', { ...win.getNormalBounds(), max: win.isMaximized() });
});

세션 복원 — 무엇을 되살릴 것인가

import { safeStorage } from 'electron';

// OS 가 제공하는 암호화 (Keychain · DPAPI · libsecret)
function saveToken(t: string) {
  if (!safeStorage.isEncryptionAvailable()) return;   // 리눅스는 없을 수 있다
  store.set('tok', safeStorage.encryptString(t).toString('base64'));
}
function loadToken(): string | null {
  const b = store.get('tok');
  if (!b) return null;
  try { return safeStorage.decryptString(Buffer.from(b, 'base64')); }
  catch { store.delete('tok'); return null; }   // 다른 PC 로 복사된 경우
}

Windows — SmartScreen 을 넘는 법

• 서명이 없으면 — “Windows 의 PC 보호” 파란 창. 사용자의 90%가 여기서 포기합니다
• OV 인증서(연 20~40만원대) — 서명은 되지만 평판이 쌓일 때까지 경고가 계속 뜹니다
• EV 인증서 · Azure Trusted Signing — 즉시 신뢰. 2023년 6월부터 코드 서명 키는 HSM·클라우드 보관이 의무라 pfx 파일을 CI 에 두는 방식은 끝났습니다

# electron-builder.yml — Azure Trusted Signing (요즘 가장 현실적)
win:
  target: [{ target: nsis, arch: [x64, arm64] }]
  azureSignOptions:              # ★ win 아래에 둡니다 (최상위에 두면 설정 오류)
    publisherName: "MyCompany Inc."
    endpoint: "https://eus.codesigning.azure.net"
    certificateProfileName: "myapp-profile"
    codeSigningAccountName: "myapp-signing"
nsis:
  oneClick: false                # 설치 경로를 고를 수 있게
  perMachine: false              # 관리자 권한 없이 설치 (사내 배포에 유리)
  allowToChangeInstallationDirectory: true

macOS — 서명 + 공증은 한 세트

mac:
  hardenedRuntime: true          # 공증의 전제 조건
  gatekeeperAssess: false
  entitlements: build/entitlements.mac.plist
  notarize: true                 # electron-builder 26+ 는 이 한 줄
  target: [{ target: dmg, arch: [x64, arm64] }]

<!-- build/entitlements.mac.plist — 필요한 것만 켠다 -->
<key>com.apple.security.cs.allow-jit</key><true/>
<key>com.apple.security.cs.allow-unsigned-executable-memory</key><true/>
<!-- 마이크·카메라를 쓴다면 (음성 채팅·화면 공유) -->
<key>com.apple.security.device.audio-input</key><true/>

# CI 환경 변수 (App Store Connect API 키 방식이 표준)
APPLE_API_KEY=./AuthKey_XXXX.p8
APPLE_API_KEY_ID=XXXXXXXX
APPLE_API_ISSUER=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# 결과 확인 — 공증이 붙었는지 최종 확인
xcrun stapler validate dist/MyApp.dmg
spctl -a -vv -t install dist/MyApp.app

배포 채널 · 점진적 롤아웃

import { autoUpdater } from 'electron-updater';

// 채널: latest(안정) · beta · alpha — 버전에 -beta.1 을 붙이면 자동 인식
autoUpdater.channel = store.get('updateChannel', 'latest');
autoUpdater.autoDownload = false;          // 사용자에게 먼저 묻는다

autoUpdater.on('update-available', async (info) => {
  const { response } = await dialog.showMessageBox({
    type: 'info',
    message: `새 버전 ${info.version} 이 있습니다`,
    detail: releaseNotesText(info),
    buttons: ['지금 받기', '나중에'],
  });
  if (response === 0) autoUpdater.downloadUpdate();
});

// 받아 두고 '다음 실행 때' 적용 — 작업 중 강제 재시작은 최악의 경험
autoUpdater.on('update-downloaded', () => {
  showRestartBanner(() => autoUpdater.quitAndInstall(false, true));
});

# 서버의 latest.yml 에 넣으면 일부에게만 먼저 나갑니다
version: 3.4.0
stagingPercentage: 10       # 10% 에게만 → 문제 없으면 100 으로
path: MyApp-3.4.0.exe
sha512: ...

GitHub Actions — 3 OS 동시 빌드

jobs:
  build:
    strategy:
      matrix:
        os: [windows-latest, macos-latest, ubuntu-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: 24, cache: npm }
      - run: npm ci
      - run: npx electron-builder --publish always
        env:
          GH_TOKEN:         ${{ secrets.GITHUB_TOKEN }}
          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
          CSC_LINK:         ${{ secrets.CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}

• macOS 는 macOS 러너에서만 서명·공증됩니다 — 교차 빌드로는 안 됩니다
• Windows arm64 도 함께 내세요 — Copilot+ PC 사용자가 늘고 있습니다
• Linux 는 AppImage + deb 두 개면 대부분 커버됩니다
• 서명 키는 절대 저장소에 넣지 말 것 — Secrets 또는 클라우드 서명 서비스

아웃박스 패턴 — 보낼 것을 DB 에 적는다

-- 로컬 SQLite (better-sqlite3 · node:sqlite)
CREATE TABLE messages (
  id          TEXT PRIMARY KEY,     -- 클라이언트가 만든 UUID
  room_id     TEXT NOT NULL,
  body        TEXT NOT NULL,
  created_at  INTEGER NOT NULL,
  server_seq  INTEGER,              -- NULL 이면 아직 서버가 모르는 것
  state       TEXT NOT NULL         -- pending | sent | failed
);
CREATE INDEX idx_msg_room ON messages(room_id, created_at);

CREATE TABLE outbox (
  id        TEXT PRIMARY KEY,
  op        TEXT NOT NULL,          -- create.message · update.doc ...
  payload   TEXT NOT NULL,          -- JSON
  tries     INTEGER NOT NULL DEFAULT 0,
  next_at   INTEGER NOT NULL        -- 지수 백오프용 시각
);

// 전송 = '로컬에 쓰기' 한 트랜잭션. 네트워크는 나중 일이다
const send = db.transaction((roomId: string, body: string) => {
  const id = crypto.randomUUID();
  db.prepare(`INSERT INTO messages
      (id,room_id,body,created_at,state) VALUES (?,?,?,?,'pending')`)
    .run(id, roomId, body, Date.now());
  db.prepare(`INSERT INTO outbox (id,op,payload,next_at) VALUES (?,?,?,?)`)
    .run(id, 'create.message', JSON.stringify({ id, roomId, body }), Date.now());
  return id;
});

// 화면은 로컬 DB 만 봅니다 — 네트워크 상태와 무관하게 항상 그려집니다

플러시 루프 · 재연결

const BACKOFF = [1_000, 2_000, 5_000, 15_000, 60_000];

async function flush() {
  const now = Date.now();
  const rows = db.prepare(
    `SELECT * FROM outbox WHERE next_at <= ? ORDER BY next_at LIMIT 20`).all(now);

  for (const r of rows) {
    try {
      await api(r.op, JSON.parse(r.payload));       // 서버는 id 로 멱등 처리
      db.prepare(`DELETE FROM outbox WHERE id = ?`).run(r.id);
      db.prepare(`UPDATE messages SET state='sent' WHERE id = ?`).run(r.id);
    } catch (e) {
      const tries = r.tries + 1;
      const wait  = BACKOFF[Math.min(tries - 1, BACKOFF.length - 1)];
      // 4xx 는 재시도해도 소용없다 — 실패로 확정하고 사용자에게 알린다
      const fatal = e instanceof HttpError && e.status >= 400 && e.status < 500;
      if (fatal || tries > 12) {
        db.prepare(`DELETE FROM outbox WHERE id=?`).run(r.id);
        db.prepare(`UPDATE messages SET state='failed' WHERE id=?`).run(r.id);
      } else {
        db.prepare(`UPDATE outbox SET tries=?, next_at=? WHERE id=?`)
          .run(tries, now + wait, r.id);
      }
    }
  }
}

// 네트워크가 돌아오면 즉시 한 번 — 이벤트는 렌더러에서 받아 메인으로 넘긴다
setInterval(flush, 3_000);
ipcMain.on('net:online', () => flush());

충돌 — 무엇을 고를 것인가

델타 동기화 — 매번 전부 받지 않기

// 서버는 단조 증가하는 seq(또는 커서)를 준다
async function pull() {
  const since = db.prepare(`SELECT COALESCE(MAX(server_seq),0) s FROM messages`)
                  .get().s;
  const { changes, nextSeq, reset } = await api('sync.pull', { since });

  if (reset) return fullResync();     // 서버가 '너무 오래됐다'고 하면 전체 재동기화

  db.transaction(() => {
    for (const c of changes) {
      if (c.deleted) db.prepare(`DELETE FROM messages WHERE id=?`).run(c.id);
      else db.prepare(`INSERT INTO messages (id,room_id,body,created_at,server_seq,state)
             VALUES (@id,@roomId,@body,@createdAt,@seq,'sent')
             ON CONFLICT(id) DO UPDATE SET
               body=excluded.body, server_seq=excluded.server_seq`).run(c);
    }
    db.prepare(`UPDATE meta SET cursor=?`).run(nextSeq);
  })();
}

// 실시간은 WebSocket, 재연결 직후엔 반드시 pull() 한 번
ws.on('open',    () => pull());        // 끊긴 동안의 변경분을 메운다
ws.on('message', (m) => applyChange(JSON.parse(m)));

• 재연결 직후 pull 을 빼먹는 것이 “가끔 메시지가 안 보여요”의 정체입니다
• 로컬 DB 는 영원히 커집니다 — 오래된 방은 정리 정책을 두세요
• 스키마가 바뀌면 마이그레이션이 필수입니다(user_version 활용)
• 동기화 상태(대기 N건 · 마지막 동기화 시각)를 UI 에 항상 보여 주세요

설계 단계

• ☐ 정말 데스크탑 앱이어야 하는가? 웹으로 되는 일이면 웹이 배포·유지보수가 훨씬 쉽습니다. 로컬 파일·프린터·시리얼 포트·오프라인이 필요할 때만 가치가 있습니다
• ☐ DB 에 직접 붙지 않기 — 접속 정보가 앱에 들어가면 사용자 PC 에서 DB 전체가 열립니다. 반드시 서버 API 를 거치세요
• ☐ 인증은 서버에서 — 앱 안의 검사는 우회됩니다
• ☐ 지원할 OS·버전 범위 확정 (Windows 10 이상? 맥 인텔도?)
• ☐ 코드 서명 인증서 확보 계획 (e09)

개발 단계

• ☐ contextIsolation: true · nodeIntegration: false (e04)
• ☐ IPC 채널마다 입력 검증
• ☐ 설정·DB 는 userData 에 (설치 폴더 X)
• ☐ 단일 인스턴스 잠금
• ☐ 창 크기·위치 기억
• ☐ 로그를 파일로 — 사용자 PC 에서 무슨 일이 났는지 알 유일한 방법

배포 · 운영

// 로그 파일 — 사내 도구에서 가장 중요한 기능입니다
import log from "electron-log/main";

log.initialize();
log.transports.file.level = "info";
log.transports.file.maxSize = 10 * 1024 * 1024;   // 10MB 로테이션
log.errorHandler.startCatching();                  // 크래시 자동 기록

// 사용자에게 로그 위치 알려 주기 (문의 대응이 10배 쉬워집니다)
ipcMain.handle("log:open", () =>
  shell.showItemInFolder(log.transports.file.getFile().path));

// 크래시 리포팅
import * as Sentry from "@sentry/electron/main";
Sentry.init({ dsn: process.env.SENTRY_DSN, release: app.getVersion() });

• ☐ 자동 업데이트 동작 확인 (구버전 → 신버전 실제 테스트)
• ☐ 백신 오탐 확인 — 서명 없는 exe 는 자주 차단됩니다
• ☐ 사내 프록시·인증서 환경에서 API 호출이 되는지
• ☐ 오프라인·네트워크 끊김 상황 처리
• ☐ 사용자 매뉴얼 + 로그 보내는 법 안내

VS Code 식 — 프로세스로 격리

┌─────────────────────────────────────────┐
│ Main (Node)                             │  창·메뉴·업데이트만
│  가볍게 유지 — 여기가 막히면 전부 멈춤    │
└──┬───────────┬──────────────┬───────────┘
   │ IPC       │ MessagePort  │ fork
   ▼           ▼              ▼
┌────────┐ ┌──────────────┐ ┌────────────┐
│Renderer│ │ Extension    │ │ 파일검색·  │
│  UI만  │ │ Host         │ │ Git·LSP    │
│        │ │ (확장 격리)   │ │ (유틸리티) │
└────────┘ └──────────────┘ └────────────┘

핵심 원칙
 ① UI 스레드에서 무거운 일을 절대 하지 않는다
 ② 남의 코드(확장·플러그인)는 별도 프로세스에 가둔다
 ③ 하나가 죽어도 앱 전체가 죽지 않는다

Discord 식 — 미디어를 네이티브로

┌──────────────┐
│  Renderer    │  React UI · 오디오 제어
└───┬──────────┘
    │ MessagePort (고빈도·저지연 · v03)
    ▼
┌──────────────────────────────┐
│  Native Voice Engine (C++)   │  ★ JS 밖에서 도는 부분
│   Opus 인코딩 · 지터버퍼      │
│   에코 제거(AEC) · 노이즈 억제 │
│   디바이스 I/O (WASAPI 등)    │
└──────────────────────────────┘

왜 네이티브인가
 · 오디오는 10ms 단위 실시간 — GC 멈춤을 못 견딤
 · OS 오디오 API 는 JS 에서 못 건드림
 · 인코딩·DSP 는 SIMD 로 몇 배 차이

기본 IPC 의 비용

ipcRenderer.invoke 의 실제 경로

렌더러 → [구조화 복제 직렬화] → 메인 IPC 큐
       → 메인 스레드에서 처리 → [다시 직렬화] → 렌더러

비용이 커지는 지점
 ① 구조화 복제 — 객체가 크고 깊을수록 급증
 ② 메인 스레드 경유 — 메인이 바쁘면 전부 대기
 ③ 초당 수백 회 호출 시 큐가 밀림

체감 기준 (대략)
 · 작은 객체 · 초당 수십 회      → 그냥 invoke 로 충분
 · 수 MB 데이터 · 초당 수백 회   → MessagePort 로
 · 오디오·비디오 프레임 (연속)   → 공유 메모리 · 네이티브로

MessagePort — 메인을 건너뛰기

// 메인 — 워커와 렌더러를 직접 연결해 줍니다
import { MessageChannelMain } from "electron";

const { port1, port2 } = new MessageChannelMain();

worker.postMessage({ type: "port" }, [port1]);          // 워커에 한쪽
mainWindow.webContents.postMessage("port:worker", null, [port2]);  // 렌더러에 반대쪽

// ★ 이후 워커 ↔ 렌더러 통신은 메인 스레드를 전혀 거치지 않습니다

// 프리로드 — 포트를 받아 렌더러에 전달
ipcRenderer.on("port:worker", (e) => {
  const port = e.ports[0];
  port.start();
  contextBridge.exposeInMainWorld("workerPort", {
    send: (msg: unknown) => port.postMessage(msg),
    onMessage: (cb: (m: unknown) => void) => {
      port.onmessage = (ev) => cb(ev.data);
    },
  });
});

대용량 — 복사 없이 넘기기

// ① Transferable — 소유권 이전 (복사 0)
const buf = new ArrayBuffer(16 * 1024 * 1024);
port.postMessage({ type: "frame", buf }, [buf]);
// ★ 넘긴 쪽에서는 buf 가 즉시 사용 불가(detached)가 됩니다

// ② SharedArrayBuffer — 양쪽이 동시에 접근 (링 버퍼에 적합)
//    렌더러에서 쓰려면 교차 출처 격리 헤더가 필요합니다
session.defaultSession.webRequest.onHeadersReceived((d, cb) => {
  cb({ responseHeaders: {
    ...d.responseHeaders,
    "Cross-Origin-Opener-Policy": ["same-origin"],
    "Cross-Origin-Embedder-Policy": ["require-corp"],
  }});
});

시작하기

# Cargo.toml
[package]
name = "my_native"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
napi = { version = "2", features = ["napi8", "async", "tokio_rt"] }
napi-derive = "2"
tokio = { version = "1", features = ["fs"] }   # 아래 hash_file 의 tokio::fs
blake3 = "1"                                   # 아래 hash_file 의 해시

[build-dependencies]
napi-build = "2"

[profile.release]
lto = true
codegen-units = 1
opt-level = 3

// src/lib.rs
#![deny(clippy::all)]
use napi_derive::napi;

#[napi]
pub fn sum_squares(data: &[f32]) -> f64 {
  data.iter().map(|&x| (x as f64) * (x as f64)).sum()
}

// ★ 자동으로 Promise 가 됩니다 — 스레드 풀에서 실행
#[napi]
pub async fn hash_file(path: String) -> napi::Result<String> {
  let bytes = tokio::fs::read(&path).await
      .map_err(|e| napi::Error::from_reason(e.to_string()))?;
  Ok(blake3::hash(&bytes).to_hex().to_string())
}

// 구조체도 그대로 오갑니다
#[napi(object)]
pub struct Stats { pub count: u32, pub mean: f64 }

#[napi]
pub fn analyze(data: Vec<f64>) -> Stats {
  let n = data.len() as u32;
  let mean = data.iter().sum::<f64>() / n as f64;
  Stats { count: n, mean }
}

콜백 · 타입 · 배포

use napi::threadsafe_function::{
  ThreadsafeFunction, ThreadsafeFunctionCallMode, ErrorStrategy,
};

#[napi]
pub fn watch_level(
  callback: ThreadsafeFunction<f64, ErrorStrategy::Fatal>,
) -> napi::Result<()> {
  std::thread::spawn(move || {
    loop {
      let level = capture_level();
      // ★ C++ 의 ThreadSafeFunction 과 같은 역할인데 훨씬 짧습니다
      callback.call(level, ThreadsafeFunctionCallMode::NonBlocking);
      std::thread::sleep(std::time::Duration::from_millis(16));
    }
  });
  Ok(())
}

// ★ index.d.ts 가 자동 생성됩니다 — 타입을 직접 쓸 필요가 없습니다
export function sumSquares(data: Float32Array): number
export function hashFile(path: string): Promise<string>
export function analyze(data: Array<number>): Stats
export interface Stats { count: number; mean: number }

# CI — OS·아키텍처별 바이너리를 미리 만들어 배포합니다
strategy:
  matrix:
    settings:
      - host: windows-latest
        target: x86_64-pc-windows-msvc
      - host: macos-latest
        target: aarch64-apple-darwin
      - host: macos-latest
        target: x86_64-apple-darwin
      - host: ubuntu-latest
        target: x86_64-unknown-linux-gnu
# → my-native-win32-x64-msvc 같은 패키지로 나뉘어 게시되고,
#   설치 시 해당 플랫폼 것만 내려받습니다 (optionalDependencies)

FFI — DLL·dylib 를 직접 호출

import koffi from "koffi";

// Windows API 를 직접 부르는 예 — 애드온 빌드가 전혀 필요 없습니다
const user32 = koffi.load("user32.dll");

const MessageBoxW = user32.func(
  "int __stdcall MessageBoxW(void* hwnd, str16 text, str16 caption, uint type)"
);
MessageBoxW(null, "안녕하세요", "알림", 0);

// 구조체도 다룰 수 있습니다
const POINT = koffi.struct("POINT", { x: "long", y: "long" });
const GetCursorPos = user32.func("bool __stdcall GetCursorPos(_Out_ POINT* p)");

const pt = {};
GetCursorPos(pt);
console.log(pt.x, pt.y);