ルータは表一つだ

한 줄 요약

프레임워크의 라우터는 마법이 아니라 표 하나다. 메서드와 경로를 키로, 핸들러를 값으로 두고 찾는다. 그 표가 무엇을 구분하느냐가 API 의 성격을 정한다.

왜 필요한가 — 404 와 405 는 다른 사건이다

/items 에 DELETE 를 보냈다고 하자. 경로는 있는데 그 메서드를 안 받는 것이다. 여기서 404 를 돌려주면 클라이언트는 "그런 자원이 없구나" 로 읽고 경로를 의심한다. 405 를 돌려주면 "자원은 있는데 이 동작은 안 되는구나" 로 읽는다. 디버깅에 걸리는 시간이 여기서 갈린다.

프레임워크를 쓰면 이 구분이 공짜로 온다. 그래서 직접 만들어 보지 않으면 그런 구분이 있다는 것조차 모르고 지나간다.

표를 어떻게 두는가

const routes = [
  { method: 'GET',  path: /^\/healthz$/,     handler: health },
  { method: 'GET',  path: /^\/items$/,       handler: listItems },
  { method: 'POST', path: /^\/items$/,       handler: createItem },
  { method: 'GET',  path: /^\/items\/(\d+)$/, handler: getItem },
];

찾는 순서가 둘로 나뉜다. 먼저 경로가 맞는 것을 전부 모으고, 그중에 메서드가 맞는 것을 고른다. 경로가 하나도 안 맞으면 404, 경로는 맞는데 메서드가 없으면 405 다. 한 번에 method + path 로 찾으면 이 구분이 사라진다.

현장에서

Nest 든 Express 든 이 표를 데코레이터나 app.get() 으로 채울 뿐 구조는 같다. 그래서 라우팅이 안 먹을 때 볼 곳도 같다 — 등록 순서와 패턴의 범위다. 넓은 패턴(/*)을 위에 두면 아래 규칙은 영원히 닿지 않는다. Envoy 실습에서 본 것과 정확히 같은 함정이고, 실제로 가장 흔한 신고다.

프레임워크를 처음 읽을 때는 라우터부터 본다. 그것이 그 프레임워크가 세상을 나누는 방식이기 때문이다.