Previous
Next
Node.js 실전 글 모음 | 시리즈 목차·학습 경로

Node.js 실전 글 모음 | 시리즈 목차·학습 경로

· 18분 읽기 · 수정 초급 가이드
Node.js 실전 글 모음 | 시리즈 목차·학습 경로

이 글의 핵심

Node.js의 맥락(이벤트 루프·npm)과 함께, Compose→Redis→Nginx→CI/CD→K8s로 이어지는 운영 학습 지도를 설명하고 시리즈 목차로 연결합니다.

들어가며

이 페이지는 pkglog Node.js 카테고리의 통합 시리즈 인덱스입니다. 런타임·언어 기초(0103)에서 출발해 웹·데이터·보안·테스트(0408)로 확장하고, 배포·성능·운영 인프라(09~10 및 별도 운영 글)까지 한눈에 연결합니다.

학습 대상: 로컬에서 node와 npm을 써 본 분, 백엔드 API를 만들기 시작한 분, 그리고 “기능은 되는데 운영에서 버티게 하려면 무엇이 더 필요한가”를 단계적으로 보고 싶은 분입니다.

이 인덱스의 목표는 다음과 같습니다.

  • 시리즈 전체 로드맵을 한 장으로 본다.

  • 각 글의 핵심만 빠르게 훑고, 필요한 글만 깊게 읽는다.

  • 초급·중급·고급 경로와 주제별 분류로 자신에게 맞는 순서를 고른다.

  • 코드 스니펫 미리보기로 “이 글이 다루는 문법·패턴”을 미리 짐작한다.

  • 프레임워크·패키지 매니저·운영까지 실무 맥락을 잡는다.

시리즈 소개: Node.js 한 바퀴

Node.js(2009, Ryan Dahl)는 브라우저 밖에서 JavaScript로 I/O를 다루겠다는 실험에서 출발했습니다. 이벤트 루프 + 논블로킹 I/O는 대량 동시 연결·API 게이트웨이·BFF(Backend for Frontend) 같은 워크로드에 잘 맞고, npm 생태계가 커지면서 작은 서비스부터 마이크로서비스까지 연결 계층으로 자주 쓰입니다.

pkglog의 Node.js 시리즈는 문법 교과서 한 권이 아니라, “서버 애플리케이션으로서 Node가 갖춰야 할 층위”를 차례로 쌓는 구조입니다. 아래 목차는 기능 개발 → 데이터·보안 → 검증 → 실행 환경 → 트래픽 앞단 → 자동화 → 분산 순으로 책임의 반경을 넓혀 가는 지도입니다. 한 번에 다 읽을 필요는 없고, 지금 막힌 층부터 골라 올라가면 됩니다.

런타임·언어는 V8·libuv·모듈·비동기를 01·02·03에서 잡고, 애플리케이션은 HTTP·Express·파일·스트림을 04·05에서 다룹니다. 데이터·신뢰는 DB·인증·테스트가 06~08이고, 운영·확장은 배포·성능에 09·10, 그리고 Compose·Redis·Nginx·CI/CD·K8s를 묶은 운영 글 다섯 편으로 이어집니다.

flowchart LR

  subgraph core [핵심 런타임]

    A1[01 Intro] --> A2[02 Modules]

    A2 --> A3[03 Async]

  end

  subgraph app [앱 계층]

    B1[04 Express] --> B2[05 fs·Stream]

  end

  subgraph data [데이터·품질]

    C1[06 DB] --> C2[07 Auth]

    C2 --> C3[08 Test]

  end

  subgraph ops [운영·확장]

    D1[09 Deploy] --> D2[10 Performance]

    D2 --> E1[Compose·Redis·Nginx·CI·K8s]

  end

  A3 --> B1

  B2 --> C1

  C3 --> D1

제 학습 경로

나는 이렇게 읽었고, 이렇게 추천한다는 느낌으로 적어 둔다. 정답 표가 아니라 내가 다시 시작하면 대략 이 순서 정도.

초반에는 01 Intro → 02 Modules → 03 Async로 런타임 감을 잡고, 04 Express로 API 하나를 끝까지 밀어 본다. 그다음 08 Testing에서 최소 테스트라도 붙이는 쪽이 마음이 편했다. CRUD JSON이랑 GET /health 정도만 돌아가게 해 보는 실습이랑 잘 맞는다.

중반에는 05 Filesystem → 06 Database → 07 Auth 순이 자연스럽다. 배포 쪽은 09 Deployment로 PM2·Nginx·Docker 개념을 정리한 뒤, Docker Compose로 로컬 구성을 고정해 두면 “내 PC에서는 됐는데”가 줄어든다.

후반에는 10 Performance로 병목 감각을 잡고, Redis 캐싱 패턴 → Nginx → GitHub Actions CI/CD → minikube / K8s 순으로 운영 축을 넓혀 가면 된다. 부하 테스트·지표(에러율·p95) 없이 최적화부터 하지 말고, 10에서 말하는 측정 먼저를 기본값으로 두는 게 좋다.

팀 상황에 따라 순서는 바뀐다. 예를 들어 CI/CD만 급하면 GitHub Actions부터 봐도 된다.

Node.js 배우면서 삽질한 것들

  • 비동기 순서: console.log 찍은 줄 순서가 헷갈릴 때가 있다. 이벤트 루프·마이크로태스크 쪽을 03에서 한번 정리해 두지 않으면 나중에 레이스 잡을 때 비용이 크다.

  • CommonJS랑 ESM 혼용: 레거시는 require, 새 파일은 import만 쓰다가 터진 적이 있다. 02에서 package.json의 type이랑 해석 규칙을 프로젝트 기준으로 맞춰 두는 게 안전하다.

  • Express만 믿고 구조를 안 잡음: 미들웨어에 다 얹다 보면 파일이 길어지고 테스트가 괴로워진다. 시리즈 04는 “기준점”으로 읽고, 팀 규모가 커지면 아래 프레임워크 쪽을 같이 보라는 쪽이 현실적이다.

  • 배포를 맨 나중에: 로컬에서는 되는데 서버에서만 터지는 건 대부분 환경·프록시·타임아웃이다. 09랑 Compose를 너무 늦게 붙이지 않는 편이 덜 아프다.

  • 캐시 없이 DB만 때림: N+1이랑 연결 풀 고갈은 나중에 한꺼번에 온다. 06이랑 Redis를 “나중 문제”로 미루면 이자가 붙는다.

시리즈 각 편 상세 (01~10) + 운영 심화 글

Part A — 런타임·언어 기초

01 | Node.js 시작하기 — 설치, 설정, Hello World

한 줄 요약: Node가 무엇인지(V8·libuv), 로컬에서 어떻게 돌아가는지, npm과의 관계를 잡습니다.

다루는 내용: Node vs 브라우저 JavaScript, 이벤트 루프 직관, 설치·실행, 프로젝트 시작 흐름, V8·libuv가 맺는 경계.

이 편을 읽으면 좋은 사람: 처음 서버 사이드 JS를 쓰는 분, “싱글 스레드인데 왜 동시에 많이 처리하나?”가 궁금한 분.

코드 스니펫 미리보기


// 런타임이 무엇을 노출하는지 — 최소 실행

console.log('Node version:', process.version);

console.log('Platform:', process.platform);

02 | Node.js 모듈 시스템 — CommonJS와 ES Modules

한 줄 요약: require/module.exports와 import/export를 프로젝트 기준으로 정리하고, 혼용·해석 규칙을 이해합니다.

다루는 내용: 모듈 해석, package.json의 type, 순환 참조 대응, npm 의존성 트리와 잠금 파일의 역할.

이 편을 읽으면 좋은 사람: 레거시 CJS와 최신 ESM이 섞인 코드베이스를 다루는 분.

코드 스니펫 미리보기


// CommonJS

const express = require('express');

module.exports = { createApp };



// ES Modules (프로젝트 설정에 따라)

// import express from 'express';

// export function createApp() { /* ... */ }

03 | Node.js 비동기 프로그래밍 — Callback, Promise, async/await

한 줄 요약: 콜백·Promise·async/await와 이벤트 루프 관점에서의 실행 순서를 정리합니다.

다루는 내용: 에러 우선 콜백, Promise.all 병렬화, 타이머·마이크로태스크 직관, 스트림과 백프레셔 개념 연결.

이 편을 읽으면 좋은 사람: “로그 순서가 왜 이런가?”“await 이후가 언제 도는가?”를 명확히 하고 싶은 분.

코드 스니펫 미리보기


async function loadUser(id) {

  const res = await fetch(`https://api.example.com/users/${id}`);

  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  return res.json();

}

Part B — 웹·I/O

04 | Express.js 완벽 가이드 — Node.js 웹 프레임워크

한 줄 요약: 라우팅·미들웨어·JSON 파싱으로 REST API 서버의 뼈대를 만듭니다.

다루는 내용: 기본 서버, 라우트 구조, 공통 미들웨어 패턴, 템플릿·정적 파일과의 연계.

이 편을 읽으면 좋은 사람: 백엔드 첫 API를 Express로 올리려는 분.

코드 스니펫 미리보기


const express = require('express');

const app = express();

app.use(express.json());

app.get('/health', (_req, res) => res.json({ ok: true }));

app.listen(3000, () => console.log('listening on :3000'));

05 | Node.js 파일 시스템 — fs 모듈 완벽 가이드

한 줄 요약: fs로 읽기/쓰기·디렉터리·감시를 다루고, 대용량은 스트림으로 처리하는 흐름을 익힙니다.

다루는 내용: 동기 vs 비동기, fs.promises, 스트림 파이프, 실무에서의 동기 API 사용 범위(CLI·초기화).

이 편을 읽으면 좋은 사람: 업로드·로그·배치 작업처럼 디스크와 맞닿는 서버를 만드는 분.

코드 스니펫 미리보기


const fs = require('fs').promises;

async function readConfig(path) {

  const text = await fs.readFile(path, 'utf8');

  return JSON.parse(text);

}

Part C — 데이터·보안·품질

06 | Node.js 데이터베이스 연동 — MongoDB, PostgreSQL, MySQL

한 줄 요약: SQL/NoSQL 드라이버·ORM 관점에서 연결 풀·트랜잭션·쿼리 패턴을 다룹니다.

다루는 내용: Mongoose 등 ODM, Sequelize 등 ORM, Raw SQL 병행, 커넥션 풀 이유.

이 편을 읽으면 좋은 사람: Express 뒤에 실제 저장소를 붙이려는 분.

코드 스니펫 미리보기


const mongoose = require('mongoose');

async function connect() {

  await mongoose.connect(process.env.MONGODB_URI);

}

07 | Node.js 인증과 보안 — JWT, bcrypt, 세션, OAuth

한 줄 요약: 비밀번호 해시·세션·JWT·OAuth를 HTTP의 stateless 특성과 함께 정리합니다.

다루는 내용: bcrypt, 토큰 만료·리프레시, CSRF·CORS와의 관계(다른 글과 병행 권장).

이 편을 읽으면 좋은 사람: 로그인·권한 모델을 처음 설계하는 분.

코드 스니펫 미리보기


const bcrypt = require('bcrypt');

async function safeHash(password) {

  return bcrypt.hash(password, 12);

}

08 | Node.js 테스트 — Jest, Mocha, Supertest

한 줄 요약: 단위·통합 테스트로 회귀를 막고, HTTP는 Supertest로 검증합니다.

다루는 내용: Jest 기본, 비동기 테스트, Mock/Stub 개념, CI에 붙이기 전 마음가짐.

이 편을 읽으면 좋은 사람: 리팩터링과 배포 빈도를 올리고 싶은 분.

코드 스니펫 미리보기


const { add } = require('./math');

test('add', () => {

  expect(add(2, 3)).toBe(5);

});

Part D — 배포·성능·운영 인프라

09 | Node.js 배포 가이드 — PM2, Docker, AWS, Nginx

한 줄 요약: node app.js를 넘어 프로세스 관리·리버스 프록시·컨테이너까지 올리는 절차를 다룹니다.

다루는 내용: PM2, Nginx 앞단, Docker 이미지 관점, 클라우드 배포 시에 챙기면 좋은 것들.

이 편을 읽으면 좋은 사람: 첫 프로덕션 배포를 앞둔 분.

코드 스니펫 미리보기


pm2 start app.js --name api

pm2 reload api

10 | Node.js 성능 최적화 — 클러스터링, 캐싱, 프로파일링

한 줄 요약: CPU 병목 vs I/O 병목을 구분하고, 클러스터·캐시·프로파일링으로 대응합니다.

다루는 내용: cluster, PM2 클러스터, 캐시 적용 타이밍, 메모리 이슈 관찰.

이 편을 읽으면 좋은 사람: 트래픽 증가 후 지연·CPU 점유가 보이기 시작한 분.

코드 스니펫 미리보기


const cluster = require('cluster');

const os = require('os');

if (cluster.isPrimary) {

  for (let i = 0; i < os.cpus().length; i++) cluster.fork();

} else {

  require('./server.js');

}

운영 심화 — 프로덕션 스택을 한 번에 보는 다섯 글

이 다섯 편은 시리즈 01~10과 수직으로 맞물리는 운영 축이다. “API가 뜬다”에서 한 걸음 더 나아가 재현 가능한 환경·캐시·엣지·자동 배포·오케스트레이션을 다룬다.

  1. Docker Compose로 Node API·PostgreSQL·Redis 한 번에 띄우기 — 환경 선언으로 “내 PC에서는 됐는데”를 줄인다.

  2. Redis 캐싱 전략 패턴 5가지 — Cache-Aside 등 애플리케이션 레이어 캐시 설계.

  3. Nginx 리버스 프록시로 Node.js 서비스 앞단 구성하기 — TLS 종료·upstream·로그.

  4. GitHub Actions로 Node.js CI/CD 파이프라인 만들기 — 테스트·빌드·이미지·배포 자동화.

  5. Kubernetes minikube로 Node API 배포하기 — Deployment·Service·kubectl 입문.

flowchart TB

  A["Docker Compose"] --> B["Redis 패턴"]

  B --> C["Nginx 프록시"]

  C --> D["GitHub Actions"]

  D --> E["minikube / K8s"]

주제별로만 골라 읽을 때

기초(런타임·이벤트·비동기·모듈): 01·03로 이벤트 루프 감, 02로 모듈·패키지.

웹·API: 04가 중심이고, 배포와 엮으면 09랑 Nginx 글을 같이 보면 좋다.

DB·연동: 06이 본론이고, 스택 예시는 Docker Compose 글(PostgreSQL 등)이 실전에 가깝다.

파일·스트림: 05랑 03를 묶어서 읽으면 흐름이 이어진다.

테스트·CI: 08 다음에 GitHub Actions를 보면 “로컬에서 돌리던 것”이 파이프라인으로 이어지는 느낌이 난다.

성능·캐시: 10와 Redis 패턴이 한 세트다.

배포·운영: 09에 PM2·Docker를 두고, Compose·Redis·Nginx·CI·K8s는 위 운영 심화 다섯 글 흐름으로 보면 된다.

실전 프로젝트 예제 아이디어

1) REST API (CRUD + 인증)

구성: Express 라우트 · PostgreSQL 또는 MongoDB · JWT 로그인 · Jest+Supertest.

읽을 글: 04 → 06 → 07 → 08.

2) 실시간 앱 (채팅·알림 흉내)

구성: WebSocket 또는 SSE(별도 학습) + Redis pub/sub(운영 글·Redis와 연계).

읽을 글: 03 · 06 · Redis (캐시 외 패턴도 참고).

3) 파일 파이프라인 (업로드·배치)

구성: fs/stream으로 대용량 처리, 실패 시 재시도·아이들포턴트 키 설계.

읽을 글: 05 · 03.

4) “프로덕션에 가까운” 풀스택 데모

구성: Docker Compose로 API+DB+Redis → Nginx로 TLS·프록시 → GitHub Actions로 이미지 빌드.

읽을 글: Docker Compose → Nginx → Actions.

내 취향: Express는 이제 좀… NestJS나 Fastify를 봐라

솔직히 Express는 미들웨어 쌓는 방식과 예제 풍부함 때문에 입문·레거시에는 여전히 잘 맞는다. 다만 2020년대 신규 서비스에 “그냥 Express만 쓰자”는 나는 잘 안 고른다. 구조·검증·성능을 프레임워크가 앞에서 잡아 주는 쪽이 팀이 커질수록 싸움이 줄어든다.

Fastify는 스키마 기반 직렬화·플러그인 경계가 분명하고, 처리량·지연 쪽에서 Express보다 이점이 나오는 경우가 많다. I/O 집중 API에 특히 괜찮다는 인상이다.

NestJS는 Angular 티 나는 모듈/DI/테스트 구조가 싫은 사람도 있지만, “폴더는 어떻게 나누지”를 팀 약속으로 끌고 가기엔 익숙한 케이스가 많다. 대신 보일러플레이트와 러닝 커브는 감수해야 한다.

pkglog 시리즈 본문은 역사적으로 Express를 축에 두고 있으니, 04는 “Node로 웹을 처음 열 때의 공통어”로 읽고, 실제로 뭘 쓸지는 Fastify / Nest 후보를 같이 보는 쪽이 낫다고 본다. HTTP·비동기 I/O·테스트·배포는 어쨌든 다 같다.

도구 및 리소스: npm, yarn, pnpm, 디버깅

패키지 매니저: npm은 Node 기본이고 package-lock.json으로 재현성을 맞출 수 있다. yarn은 클래식과 Yarn Berry 정책이 갈리니 팀 룰을 보라. pnpm은 콘텐츠 주소 저장으로 디스크 효율이 좋고 node_modules 레이아웃이 엄격하다. 레포마다 매니저 하나로 통일하고, CI 캐시 키는 lockfile에 맞추는 게 정신 건강에 이롭다.

디버깅·관측: node --inspect에 Chrome DevTools로 브레이크·프로파일을 찍을 수 있고, 요청 단위 상관 ID는 게이트웨이·프록시·앱을 관통해 추적할 때 쓴다. 메트릭은 p50/p95 지연, 에러율, PM2·K8s에서의 프로세스 재시작 횟수 같은 것부터 보면 된다.

시리즈 운영 글(Nginx, Compose)은 로그·경로를 이해하는 데 도움이 된다.

실무 활용: 마이크로서비스, 서버리스

마이크로서비스

Node는 가벼운 API·BFF·어댑터로 자주 쓰인다. 나눌 때는 데이터 경계·배포 단위·장애 격리를 함께 정하는 게 좋다. 운영 글의 Compose → CI → K8s 순서는 “단일 배포에서 여러 프로세스로” 확장하는 사고 연습에 잘 맞는다.

서버리스 (Lambda, Cloud Functions 등)

특징: 짧은 요청·이벤트 기반에 강하고, 상태·콜드 스타트·로컬 재현이 과제다. 전통적 Node 서버(09)와 실행 모델이 다르므로, 동일 코드를 그대로 옮기기보다 입출력 경계를 다시 설계하는 편이 맞다.

내부 동작과 핵심 메커니즘 (요약)

이 글의 주제는 「Node.js 실전 글 모음 | 시리즈 목차·학습 경로」다. 요청 경로와 상태 전이를 기준으로 보면, “입력이 어디서 검증되고, 핵심 연산이 어디서 일어나며, 부작용(I/O·네트워크·디스크)이 어디서 터지는가”가 한눈에 드러난다.

처리 파이프라인(개념도)

flowchart TD

  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]

  B --> C[핵심 연산·상태 전이]

  C --> D[부작용: I/O·네트워크·동시성]

  D --> E[결과·관측·저장]

불변 조건으로 버퍼 경계, 프로토콜 상태, 트랜잭션 격리를 문장으로 적어 두면 디버깅이 덜 괴롭다. 순수한 층과 시간·네트워크에 의존하는 층을 나누면 테스트·장애 분석이 쉬워지고, 직렬화·syscall 횟수·락 경합처럼 누적 비용은 의심 목록에 넣어 두는 게 좋다.

프로덕션에서 자주 보는 것들

실서비스에서는 기능 구현과 함께 관측·배포·보안·비용이 동시에 요구된다. 아래는 팀에서 흔히 점검하는 축 정도다.

  • 관측성: 요청 단위 상관 ID, 에러율/지연 분위수, 주요 의존성 타임아웃이 보이는가.

  • 안전성: 입력 검증·권한·비밀 관리가 코드 경로마다 일관적인가.

  • 신뢰성: 재시도는 멱등한 연산에만 붙이는가, 서킷 브레이커·백오프가 있는가.

  • 성능: 캐시 계층·배치 크기·풀링·백프레셔가 데이터 규모에 맞는가.

  • 배포: 롤백 룬북, 카나리, 마이그레이션 호환이 문서로 남는가.

운영 환경에서는 “개발자 PC에서는 재현되지 않던 문제”가 시간·부하·데이터 크기 때문에 드러난다. 스테이징의 데이터 양·네트워크 지연을 가능한 한 현실에 가깝게 맞추는 게 중요하다.

문제 해결(Troubleshooting)

  • 간헐적 실패: 레이스, 타임아웃, 외부 의존성 흔들림이 흔한 원인이다. 최소 재현 스크립트를 만들고, 분산 트레이스·로그 상관관계를 본다.

  • 성능 저하: N+1, 동기 I/O, 락 경합, 과한 직렬화 등이 나온다. 프로파일러·APM으로 핫스팟을 잡고 한 가지씩 제거한다.

  • 메모리 증가: 캐시 무제한, 클로저/이벤트 구독 누수, 큰 객체의 불필요한 복사를 의심한다. 상한·TTL, 힙 덤프/트레이스로 비교해 본다.

  • 빌드·배포만 실패: 환경 변수·권한·플랫폼 차이를 본다. CI 로그와 로컬을 diff하고, 컨테이너/런타임 버전을 핀한다.

권장 순서는 (1) 최소 재현 (2) 최근 변경 범위 좁히기 (3) 의존성·환경 변수 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트 정도다.

추천 학습 방법

  • 실습: Compose로 띄운 뒤, 같은 API에 Redis를 붙이고 Nginx 앞에 두는 식으로 한 계층씩만 넣으면 디버깅이 쉽다.

  • 다음: CI에서 빌드한 이미지를 레지스트리에 올리고, 스테이징·프로덕션 브랜치 전략을 팀 규칙에 맞춘다.

자주 묻는 질문 (FAQ)

Q. Kubernetes까지 꼭 가야 해?

A. 아니, Compose + Nginx만으로도 소규모는 충분한 경우 많아. K8s는 복제·롤링·팀 표준이 필요해질 때 검토해봐. minikube 글은 입문용이야.

Q. 글 순서가 곧 실행 순서야?

A. 로컬에서 배우는 용도로는 위에 적어 둔 제 학습 경로가 자연스럽긴 해. 근데 팀에서 CI/CD만 급하면 GitHub Actions부터 봐도 돼.

Q. 시리즈 01~10이랑 운영 5편, 뭘 먼저 읽지?

A. 만들고·테스트하려면 0108 먼저, 프로덕션 올릴 준비되면 0910이랑 운영 5편을 묶어 봐. 운영 글은 본문을 재현 가능한 환경으로 잇는 축이야.

Q. 런타임 기초는 어디서 다뤄?

A. 01·03이 중심이야. 이 인덱스는 운영·인프라 실전 글도 한 페이지에 묶어 둔 거고.

Q. Redis 없이 시작해도 돼?

A. Compose 글에서 스택 올린 뒤, 부하·요구 생기면 캐싱 패턴으로 가면 돼.

Q. Express 말고 다른 프레임워크 써도 이 시리즈 도움 돼?

A. HTTP·비동기 I/O·테스트·배포는 다 같아. API만 다를 뿐, 04는 기준점으로 읽고 Fastify/Nest로 옮기면 돼. 위에서 말한 Express / Fastify / Nest 취향 절도 같이 봐.

Q. pnpm 써도 돼?

A. 응, 팀에서 lockfile이랑 CI 캐시만 통일하면 npm / yarn / pnpm 다 운영 사례 있어.

Q. 모놀리스랑 마이크로서비스는 어떻게 가르면 돼?

A. 팀 크기·배포 빈도·데이터 경계 먼저 봐. Node는 둘 다 쓰이고, 운영 다섯 편은 “나중에 쪼갤 수 있는 배포 습관” 익히기에 좋아.

같이 보면 좋은 글

이 글에서 다루는 키워드 (관련 검색어)

Node.js, 시리즈, 목차, 학습 경로, Express, 비동기, Jest, Docker, Redis, Nginx, CI/CD, Kubernetes 등으로 검색하시면 이 글이 도움이 됩니다.