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
Express.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'));
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가 뜬다”에서 한 걸음 더 나아가 재현 가능한 환경·캐시·엣지·자동 배포·오케스트레이션을 다룹니다.
-
Docker Compose로 Node API·PostgreSQL·Redis 한 번에 띄우기 — 환경 선언으로 “내 PC에서는 됐는데”를 줄입니다.
-
Redis 캐싱 전략 패턴 5가지 — Cache-Aside 등 애플리케이션 레이어 캐시 설계.
-
Nginx 리버스 프록시로 Node.js 서비스 앞단 구성하기 — TLS 종료·upstream·로그.
-
GitHub Actions로 Node.js CI/CD 파이프라인 만들기 — 테스트·빌드·이미지·배포 자동화.
-
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를 보면 “로컬에서 돌리던 것”이 파이프라인으로 이어지는 흐름이 보입니다.
배포·운영: 09에서 PM2·Docker를 다루고, Compose·Redis·Nginx·CI·K8s는 위 운영 심화 다섯 글 흐름으로 보면 됩니다.
실전 프로젝트 예제 아이디어
REST API (CRUD + 인증)
구성: Express 라우트 · PostgreSQL 또는 MongoDB · JWT 로그인 · Jest+Supertest.
실시간 앱 (채팅·알림 흉내)
구성: WebSocket 또는 SSE(별도 학습) + Redis pub/sub(운영 글·Redis와 연계).
읽을 글: 03 · 06 · Redis (캐시 외 패턴도 참고).
파일 파이프라인 (업로드·배치)
구성: fs/stream으로 대용량 처리, 실패 시 재시도와 멱등(idempotent) 키 설계.
“프로덕션에 가까운” 풀스택 데모
구성: 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는 두 방식 모두에 쓰이며, 운영 다섯 편은 “나중에 쪼갤 수 있는 배포 습관”을 익히기에 좋습니다.