Express에서 next()를 호출하지 않으면 어떻게 되나요?

해당 미들웨어 이후의 핸들러는 실행되지 않고 요청이 멈춥니다. 비동기 작업 후에는 반드시 next 또는 응답을 보내야 합니다.

에러 핸들러는 왜 인자가 4개인가요?

Express는 함수의 매개변수 개수(arity)로 에러 처리 미들웨어를 구분합니다. (err, req, res, next) 형태만 에러 레이어로 인식합니다.

프로덕션에서 trust proxy는 왜 켜나요?

리버스 프록시(Nginx 등) 뒤에서 실행할 때 X-Forwarded-* 헤더를 신뢰해 올바른 클라이언트 IP·프로토콜을 req.ip 등에 반영하기 위함입니다.

[2026] Express.js 완벽 가이드 — 내부 구조·미들웨어·라우팅·프로덕션

2026년 4월 7일 · 47분 읽기 · 수정 2026년 4월 7일 중급 tutorial

이 글의 핵심

Express의 미들웨어 스택·라우터·요청·응답 객체·에러 파이프라인을 내부 관점에서 이해하고, 프로덕션에서 통하는 운영 패턴까지 정리합니다.

들어가며

Express.js는 Node.js의 http 모듈 위에 얹힌 얇은(slim) 프레임워크입니다. 문서에서 말하는 “미들웨어”와 “라우팅”은 단순한 편의 API가 아니라, 스택(Stack)과 레이어(Layer) 라는 자료 구조로 구현된 요청 처리 파이프라인입니다. 이 글에서는 API 사용법만이 아니라, 요청이 들어온 뒤 어떤 순서로 어떤 함수들이 호출되는지 내부 관점에서 정리합니다. 그 위에 에러 전파 규칙과 프로덕션 운영 패턴을 덧붙입니다.

1. 미들웨어 체인 아키텍처

1.1 애플리케이션은 “함수 배열”에 가깝다

Express 애플리케이션(express())과 Router는 내부적으로 stack이라는 배열에 등록된 핸들러들을 순서대로 실행합니다. app.use(fn), app.get(path, fn) 등은 결국 이 스택에 레이어(Layer) 를 추가하는 연산입니다.

개념적으로는 다음과 같은 흐름입니다.

요청 → [ layer0 → layer1 → layer2 → … → 응답 또는 에러 ]

각 레이어는 하나의 미들웨어 함수(또는 라우트와 결합된 핸들러)를 감싸고, 경로 매칭 정보·정규식·이름 등 메타데이터를 붙입니다.

1.2 `next`의 의미: “다음 레이어로 제어 이동”

동기 미들웨어에서 next()를 호출하면, Express는 현재 레이어를 종료하고 스택의 다음 핸들러를 실행합니다. next(err)를 호출하면 일반 미들웨어 체인을 건너뛰고, 등록된 에러 처리 미들웨어(인자 4개)로 점프합니다. 이 동작이 Express 에러 모델의 핵심입니다.

아래는 의도적으로 단순화한 의사 코드입니다. 실제 구현은 버전에 따라 세부가 다르지만, “스택 순회 + next로 이동 + err면 에러 레이어” 라는 큰 그림은 동일합니다.

// 개념적 의사 코드 (실제 Express 소스와 다름)
function handle(req, res, stack, index = 0) {
  const layer = stack[index];
  if (!layer) return; // 스택 끝 — 응답 없으면 연결 유지/타임아웃 위험

  const fn = layer.handle;

  function next(err) {
    if (err) return handleError(err, req, res, stack);
    handle(req, res, stack, index + 1);
  }

  fn(req, res, next);
}

실무에서의 함정: async 미들웨어에서 await만 하고 next()를 호출하지 않거나, 조기 return으로 응답도·next도 호출하지 않으면 요청이 걸려(hang) 남을 수 있습니다. 반드시 “응답을 보냈는가, next를 호출했는가” 중 하나는 보장해야 합니다.

1.3 미들웨어 vs 라우트 핸들러

app.use로 넣은 함수와 app.get으로 넣은 함수는 실행 메커니즘은 동일합니다. 차이는 경로 매칭 규칙과 HTTP 메서드 필터링이 레이어에 어떻게 붙는지에 있습니다.

app.use('/api', r) : /api로 시작하는 경로에 대해 서브스택(또는 라우터)을 마운트합니다.
app.get('/users/:id', h) : GET + 경로 패턴이 일치할 때만 해당 레이어가 활성화됩니다.

그래서 “미들웨어는 위에서 아래로”라는 말은 등록 순서가 곧 우선순위라는 뜻이며, 인증·로깅·바디 파서 등은 라우트보다 위에 두는 것이 일반적입니다.

2. 라우팅 레이어 구현

2.1 `Router`는 작은 Express 앱

express.Router()로 만든 라우터는 독립된 미들웨어 스택을 가진 미니 애플리케이션입니다. app.use('/prefix', router)는 /prefix 아래로 들어온 요청에 대해 라우터 내부 스택을 추가로 순회합니다.

const express = require('express');
const app = express();
const api = express.Router();

api.use((req, res, next) => {
  req.requestId = Math.random().toString(36).slice(2);
  next();
});

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

app.use('/api/v1', api);

위에서 /api/v1/health는 앱 스택 → 라우터 마운트 레이어 → 라우터 내부 스택 순으로 탐색됩니다.

2.2 경로 매칭과 `path-to-regexp`

Express의 라우트 문자열('/users/:id', '/files/*' 등)은 내부적으로 정규식/토큰화된 경로 매처로 변환됩니다(전통적으로 path-to-regexp 계열). 그 결과가 레이어의 match 판단에 사용됩니다.

전문가 관점 체크리스트:

와일드카드·정규식 라우트는 디버깅이 어렵습니다. 가능하면 명시적 파라미터와 버전 프리픽스(/v1)로 표현을 단순화합니다.
라우트 순서: /users/new와 /users/:id를 함께 쓸 때, 구체적인 경로를 동적 세그먼트보다 위에 두지 않으면 잘못 매칭됩니다.
app.param: 특정 파라미터에 대한 로더를 붙일 수 있으나, 부수 효과와 캐싱 정책을 명확히 문서화하지 않으면 팀 협업에서 혼란을 줍니다.

2.3 `app.route()` — 메서드 체인과 동일 스택

app.route('/resource').get().post() 패턴은 동일 경로에 메서드별 핸들러를 한데 묶어 가독성을 높입니다. 내부적으로는 해당 경로에 대한 Route 객체 아래에 레이어가 정리됩니다.

3. Request / Response 객체 래핑

3.1 Node 코어 객체 위의 “믹스인”

Express의 req와 res는 Node.js HTTP의 IncomingMessage와 ServerResponse 인스턴스입니다. Express는 프로토타입에 메서드를 추가하는 방식(버전에 따라 세부 구현은 다름)으로 req.query, req.params, req.body, res.json, res.send 등을 제공합니다.

즉, Express는 새로운 HTTP 스택을 만든 것이 아니라, 코어 객체에 편의 API를 덧씌운 것에 가깝습니다.

3.2 `req.params`, `req.query`, `req.body`의 책임 분리

필드	일반적 공급원	비고
`req.params`	라우트 매칭	경로 세그먼트
`req.query`	URL의 쿼리스트링 파싱	`?a=1`
`req.body`	바디 파서 미들웨어	`express.json()` 등이 없으면 `undefined`

중요: req.body는 프레임워크 “마법”이 아니라 미들웨어가 req에 주입한 값입니다. 순서를 잘못 배치하면 컨트롤러까지 빈 바디가 전달됩니다.

3.3 응답 헬퍼와 헤더·상태 코드

res.json은 Content-Type을 설정하고 직렬화합니다. res.send는 타입에 따라 텍스트/HTML/Buffer 등을 처리합니다. 이미 응답이 전송된 뒤(res.headersSent) 다시 쓰기를 시도하면 오류가 나거나 무시될 수 있으므로, 미들웨어 체인에서는 이중 응답을 특히 주의합니다.

4. 에러 처리 메커니즘

4.1 arity(인자 개수)로 구분되는 에러 미들웨어

Express는 미들웨어 함수의 매개변수 개수로 일반 핸들러와 에러 핸들러를 구분합니다.

// 일반
app.use((req, res, next) => { /* ... */ });

// 에러 전용 — 반드시 4개
app.use((err, req, res, next) => {
  console.error(err);
  res.status(err.status || 500).json({ message: err.message });
});

next(err)가 호출되면 스택은 에러 처리 레이어를 찾아 내려갑니다. 에러 핸들러가 없으면 기본 동작(프로덕션에서는 민감 정보 노출 주의)으로 떨어집니다.

4.2 비동기 라우트와 에러 전파

콜백 스타일이 아닌 async 핸들러는 거부된 Promise가 자동으로 next에 연결되지 않습니다. 그래서 아래 중 하나가 필요합니다.

const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await findUser(req.params.id);
  if (!user) {
    const err = new Error('Not found');
    err.status = 404;
    throw err; // asyncHandler가 next(err)로 연결
  }
  res.json({ user });
}));

Express 5(실험/차기 계열)에서는 async 에러 처리가 개선되는 방향이 논의되어 왔으나, 현재 운영 코드베이스는 대부분 Express 4 계열이므로 위 패턴이 여전히 표준에 가깝습니다.

4.3 404와 에러 핸들러의 순서

app.use('/api', apiRouter);

// 404 — 모든 라우트 뒤
app.use((req, res) => {
  res.status(404).json({ error: 'NOT_FOUND' });
});

// 최종 에러 핸들러 — 가장 마지막
app.use((err, req, res, next) => {
  res.status(err.status || 500).json({ error: 'INTERNAL' });
});

404 미들웨어는 “매칭 실패”를 처리하고, 4개짜리 에러 핸들러는 예외·next(err)를 처리합니다. 순서를 바꾸면 디버깅이 어려운 상태가 됩니다.

5. 프로덕션 Express 패턴

5.1 `trust proxy`와 리버스 프록시

Nginx, Cloudflare, Kubernetes Ingress 등 앞단 프록시 뒤에서 Express를 띄울 때는 다음을 검토합니다.

app.set('trust proxy', 1); // 프록시 홉 수에 맞게 조정

trust proxy를 적절히 설정해야 req.ip, X-Forwarded-Proto 기반의 보안 리다이렉트, rate limit 키 등이 올바릅니다. 과도하게 넓게 신뢰하면 IP 스푸핑 위험이 있으므로, 인프라 홉 수에 맞춰 숫자 또는 신뢰 목록으로 제한합니다.

5.2 보안·관측·성능

const helmet = require('helmet');
const compression = require('compression');

app.disable('x-powered-by');
app.use(helmet());
app.use(compression());
app.use(express.json({ limit: '1mb' }));

helmet: 보안 관련 HTTP 헤더 세트.
compression: gzip 등 — CPU와의 트레이드오프이므로 대역폭이 병목일 때 효과적입니다.
바디 크기 제한: 대용량 JSON POST로 인한 메모리 압박을 완화합니다.

5.3 프로세스 관리·그레이스풀 셧다운

Node는 단일 스레드 이벤트 루프 모델입니다. CPU 바운드 작업은 전체 요청 처리를 막을 수 있으므로, 무거운 작업은 워커 큐(Bull, Cloud Tasks 등)로 넘기는 것이 안전합니다.

Kubernetes나 배포 파이프라인에서 SIGTERM을 보낼 때를 대비해, 진행 중인 연결을 마친 뒤 서버를 닫습니다.

const server = app.listen(process.env.PORT || 3000);

function shutdown(signal) {
  console.log(signal);
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(1), 10_000).unref();
}

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

5.4 구조화 로깅과 상관관계 ID

프로덕션에서는 console.log 대신 구조화 로그(JSON) 와 요청 ID를 권장합니다. 앞 절의 Router 예시처럼 req.requestId를 넣고, 에러 핸들러에서 동일 ID로 묶으면 추적이 쉬워집니다.

6. 빠른 참고 — 최소 앱 스켈레톤

const express = require('express');
const helmet = require('helmet');

const app = express();
app.disable('x-powered-by');
app.set('trust proxy', 1);
app.use(helmet());
app.use(express.json({ limit: '1mb' }));

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

// 404 + 에러 핸들러는 라우트 뒤에 배치
app.use((req, res) => res.status(404).json({ error: 'NOT_FOUND' }));
app.use((err, req, res, next) => {
  console.error(err);
  res.status(err.status || 500).json({ error: 'INTERNAL' });
});

const server = app.listen(process.env.PORT || 3000);

내부 동작과 핵심 메커니즘

이 글의 주제는 「[2026] Express.js 완벽 가이드 — 내부 구조·미들웨어·라우팅·프로덕션」입니다. 앞선 튜토리얼을 구현·런타임 관점에서 다시 압축합니다. 요청 경로와 상태 전이를 기준으로 “입력이 어디서 검증되고, 핵심 연산이 어디서 일어나며, 부작용(I/O·네트워크·디스크)·동시성이 어디서 터지는가”를 한 장면으로 그리면 장애 분석이 빨라집니다.

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

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

경계에서의 지연·실패(시퀀스 관점)

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(프로세스·런타임·게이트웨이)
  participant D as 의존성(외부 API·DB·큐)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

알고리즘·프로토콜·리소스 관점 체크포인트

불변 조건(Invariant): 각 단계가 만족해야 하는 조건(버퍼 경계, 프로토콜 상태, 트랜잭션 격리, 파일 디스크립터 상한)을 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 동일 입력에 동일 출력이 보장되는 순수 층과, 시간·네트워크·스레드 스케줄에 의해 달라질 수 있는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화/역직렬화, 문자 인코딩, syscall 횟수, 락 경합, GC·할당, 캐시 미스처럼 누적 비용을 의심 목록에 넣습니다.
백프레셔: 생산자가 소비자보다 빠를 때(소켓 버퍼, 큐 깊이, 스트림) 어디서 어떤 신호로 속도를 줄일지 정의합니다.

프로덕션 운영 패턴

실서비스에서는 기능과 함께 관측·배포·보안·비용·규제가 동시에 요구됩니다.

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율/지연 분위수(p95/p99), 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시 계층·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션 호환성·플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·파일 디스크립터·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 가능한 한 프로덕션에 가깝게 맞추는 것이 재현율을 높입니다.

확장 예시: 엔드투엔드 미니 시나리오

「[2026] Express.js 완벽 가이드 — 내부 구조·미들웨어·라우팅·프로덕션」을 실제 배포·운영 흐름으로 옮긴 체크리스트형 시나리오입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드 표를 API 또는 이벤트 경계에 둔다.
핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 한 화면(로그+메트릭+트레이스)에서 추적한다.
실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지(또는 피처 플래그) 확인한다.
부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값이 기대 범위인지 본다.

의사코드 스케치(프레임워크 무관)

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)        // 경계에서 거절
  authorize(validated, ctx)                  // 권한·테넌트
  result = domainCore(validated)             // 순수에 가까운 규칙
  persistOrEmit(result, idempotentKey)       // I/O: 멱등·재시도 정책
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성 불안정, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정이 로컬과 다름	프로필·시크릿·기본값, 지역 리전	단일 소스(예: 스키마 검증된 설정)와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

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

정리

Express는 스택 기반 미들웨어 파이프라인 위에 경로 매칭 레이어를 얹은 프레임워크입니다. next/next(err)는 그 파이프라인의 제어 흐름을 바꾸는 핵심이며, req/res는 HTTP 코어 객체에 헬퍼를 혼합한 형태입니다. 프로덕션에서는 trust proxy, 보안 헤더, 바디 제한, 그레이스풀 셧다운, 구조화 로깅이 운영 품질을 가릅니다.

더 깊게 파고들려면 공식 저장소의 lib/router/layer.js, lib/router/index.js, lib/application.js 흐름을 따라가며 스택 순회를 직접 추적해 보는 것을 권장합니다.