Node 표준 라이브러리로 API 를 세운다
목표
Nest 없이 Node 표준 라이브러리만으로 작은 주문 API 를 세웁니다. 라우팅 표, 입력 검증, 출력 모양, 의존성 주입, 이벤트 루프, 계약 시험까지 여덟 단계를 세우고, 마지막 아홉째 단계에서는 진짜 소켓을 연 주문 서버의 사건(어떤 요청은 영영 응답이 없다)을 풉니다.
왜 이렇게 하는가
실습 파드는 DNS 만 열려 있어 npm install 이 안 됩니다. 그런데 그 제약이
오히려 이 코스에 맞습니다 — 프레임워크가 대신해 주던 판단을 직접 내려 보면,
나중에 Nest 를 읽을 때 각 장치가 무엇을 대신하고 있는지 가 보입니다.
형식
/root/work/api/app.mjs 를 만들고 아래를 export 합니다.
handle(req)—req는{method, path, body, headers}, 돌려줄 것은{status, body}입니다. 진짜 소켓을 열지 않습니다.createApp({store})— 6단계에서 만듭니다.
소켓을 열지 않는 이유는 채점이 포트 충돌이나 기동 타이밍에 흔들리면 안 되기 때문입니다. 실패가 진짜 실패를 뜻해야 시험이 쓸모 있습니다.
단계
handle(req)의 뼈대와 /healthz- 라우팅 표 — 404 와 405 를 가른다
- 입력 검증 — 400 에 필드별 사유
- 내보내는 모양 — 허용 목록
- 없는 것에는 404
- 저장소를 주입으로
- 이벤트 루프를 막지 않는 느린 경로
- 서버를 띄우지 않는 계약 시험 — 채점기가 계약을 깨뜨린 판으로 다시 돌린다
- 사건 nd-hang — 진짜 소켓을 연 주문 서버의 세 경로가 어떤 요청에는 영영 답하지 않는다
참고
- 1~8단계는 소켓이 없으니
node -e 'import("/root/work/api/app.mjs").then(async m => console.log(await m.handle({method:"GET", path:"/items"})))'처럼 불러 보세요. - 9단계의 사건은 앞 단계와 무관하게 자급자족합니다. 응답이 「안 오는」 모양을
curl -v -m 2로 먼저 보세요. - 흔한 실수: 메서드부터 맞춰 405 를 잃기,
delete로 필드 빼기, 늘 통과하는 시험.
서버의 뼈대를 세운다
방향: 서버의 뼈대는 「요청 하나를 받아 응답 하나를 돌려주는 함수」 입니다 — 소켓은 그 바깥 일입니다. 도구: ES 모듈의 export async function, mkdir -p /root/work/api, node -e 로 불러 보기. 구체: /root/work/api/app.mjs 가 handle(req) 를 내보내고, req 는 {method, path, body, headers}, 돌려줄 것은 {status, body} 입니다. /healthz 만 200 과 {status:'ok'} 이면 됩니다.
handle('/healthz') 이 200 과 {status:'ok'} 를 돌려줍니다
라우팅 표를 만든다 — 404 와 405 를 가른다
방향: 404 와 405 는 다른 사건입니다 — 「그런 자원이 없다」 와 「자원은 있는데 그 동작은 안 된다」. 순서가 판정을 정합니다. 도구: {method, pattern, run} 을 담은 배열(라우팅 표), 정규식의 exec. 구체: 메서드부터 맞추면 405 를 낼 자리가 사라집니다. 먼저 경로가 맞는 항목을 모으고, 그중에서 메서드를 찾으세요. GET /items 는 배열입니다.
없는 경로는 404, 있는 경로의 다른 메서드는 405
입력을 검증하고 왜 틀렸는지 알려 준다
방향: 400 의 가치는 「어디를 고치면 되는지」 를 알려 주는 데 있습니다 — 틀렸다는 사실만으로는 클라이언트가 할 일이 없습니다. 도구: typeof, Number.isFinite, 오류를 모으는 배열. 구체: 첫 오류에서 멈추지 말고 필드마다 {field, reason} 을 모아 {errors: [...]} 로 400 을 돌려주세요. 받는 모양은 {name: string, qty: number}, 만들었으면 201 입니다.
qty 가 문자열이면 400 과 errors 에 qty, 정상이면 201
저장한 모양과 내보내는 모양을 가른다
방향: 저장한 모양과 내보내는 모양을 따로 두면, 컬럼이 늘어도 API 가 조용히 바뀌지 않습니다. 도구: 구조 분해로 필드를 고르는 작은 함수(예: ({id, name, qty}) => (...)), Array.prototype.map. 구체: delete item.secret 처럼 뺄 것을 세지 말고 내보낼 것을 세세요(허용 목록). 목록·단건·만든 직후 응답이 모두 그 함수 하나를 거치게 합니다.
GET /items 응답에 secret 이 없고 id·name·qty 는 있습니다
없는 것에는 404 를 준다
방향: 상태 코드가 계약입니다 — 클라이언트는 본문보다 상태를 먼저 읽습니다. 도구: 라우팅 표의 정규식 캡처(/^\/items\/(\d+)$/), Number(...), 저장소의 find. 구체: 없는 id 에 200 과 {error} 를 주면 클라이언트는 성공으로 처리합니다. 없으면 404, 있으면 200 과 그 항목(내보내는 모양으로)입니다.
없는 id 는 404, 있는 id 는 200 과 그 항목
저장소를 주입으로 받는다
방향: 바꿔 끼울 자리를 코드에 표시해 두는 것이 주입입니다 — 시험은 그 결과로 쉬워질 뿐입니다. 도구: 인자로 의존을 받는 함수(createApp({store})), 클로저. 구체: 핸들러 안에서 전역 저장소를 직접 부르는 줄이 하나라도 남으면 채점기가 넣은 가짜 저장소가 무시됩니다. 기본 handle 은 createApp({store: memoryStore}) 로 만들어 두세요.
createApp({store}) 에 넣은 저장소가 실제로 쓰이고 출력 모양도 유지됩니다
이벤트 루프를 막지 않는다
방향: 「느리다」 와 「막는다」 는 다릅니다 — 기다리는 동안 다른 일이 돌 수 있어야 합니다. 도구: setTimeout 을 감싼 Promise 와 await, 반대 사례로 while (Date.now() < t). 구체: GET /slow 는 40ms 이상 걸리되 그동안 이벤트 루프를 놓아 주어야 합니다. 바쁜 반복으로 시간을 태우면 채점기의 5ms 타이머가 멈춥니다(이 주제의 깊은 판은 node-event-loop 코스).
네 요청을 동시에 처리하는 동안 5ms 타이머가 계속 돕니다
서버를 띄우지 않고 계약을 시험한다
방향: 시험의 값은 「깨졌을 때 떨어지는가」 입니다 — 늘 통과하는 시험은 아무것도 지키지 않습니다. 도구: node:test 의 test, node:assert/strict, createApp 에 넣는 가짜 저장소. 구체: 채점기는 여러분의 app.mjs 를 감싸 계약을 하나씩 깨뜨린 판 셋(secret 이 샘·없는 id 에 200·qty 검증 꺼짐)으로 시험을 다시 돌려, 둘 이상에서 단언이 떨어지는지 봅니다. 출력 모양·404·400 을 각각 단언하세요. 시험은 ./app.mjs 를 상대 경로로 불러와야 채점기의 바꿔 낀 판이 적용됩니다. 포트는 열지 않습니다.
node --test 가 통과하고, 계약을 깨뜨린 판 셋 중 둘 이상에서 단언이 떨어집니다(서버는 띄우지 않음)
사건 — 어떤 요청은 영영 응답이 없다
incident nd-hang 을 실행하면 사건이 납니다. 주문 API(orders-api, 127.0.0.1:8090)의 세 경로 — order(GET /orders/), create(POST /orders), receipt(GET /orders//receipt) — 가 어떤 요청에는 끝내 답하지 않습니다(같은 경로의 다른 요청은 멀쩡하고, 서버도 죽지 않았습니다). 티켓과 /srv/nd-hang/timeouts.txt 에서 출발해 /srv/nd-hang/server.mjs 를 고치고 ndctl restart orders-api 로 다시 띄워, 세 경로 모두 /srv/nd-hang/API.md 의 상태 코드로 끝까지, 바로 답하게 합니다. 고칠 곳은 세 경로의 함수(getOrder·createOrder·getReceipt)와 요청 처리기(createServer 의 콜백)뿐이고, 기다림을 시간(타이머)으로 덮는 것은 고침으로 치지 않습니다. 채점기는 사건 때와 다른 값(없는 주문 번호·모르는 sku 등)으로도 보냅니다. /root/incident/nd-hang/report.txt 에 order: <code>, create: <code>, receipt: <code> 세 줄과, 경로마다 그 원인을 보여 주는 로그(/var/log/nd/orders-api.log)의 한 줄을 evidence-order: <line>, evidence-create: <line>, evidence-receipt: <line> 로 적습니다. 원인은 경로마다 따로 정해져 있어 같은 원인이 둘일 수도 있습니다. 서로 다른 원인 코드로 세 번 틀리면 사건이 거둬져 다시 내야 합니다. 코드는 다음 중 하나입니다: missed-event(이미 지나간 알림을 기다림), missing-end(응답을 끝내지 않은 분기), slow-upstream(느린 하위 서비스), swallowed-rejection(아무도 받지 않은 거부).
방향: 「응답이 안 온다」 에도 모양이 셋 있습니다 — 머리까지는 왔는데 끝이 안 오는가, 아무것도 안 오는데 로그에 오류가 남았는가, 아무것도 안 오고 오류도 없는가. 경로마다 따로 가르세요. 도구: curl -v -m 2(무엇이 몇 바이트 왔나), 로그의 aborted ... headersSent= 줄과 unhandledRejection: 줄, 시작 때 찍힌 줄들, 그 경로의 함수 하나(getOrder·createOrder·getReceipt). 구체: 머리가 나간 채 끊겼다면 그 분기의 마지막 호출을, 거부가 기록됐다면 그 값이 왜 비었는지를, 아무 흔적이 없다면 그 함수가 await 로 무엇을 기다리는지와 그것이 언제 일어났는지(시작 로그의 시각)를 보세요. 다시 띄우지 않으면 고친 코드는 읽히지 않습니다.