[JSTS-012][실무] 타입으로 지키는 작은 상태 확인 서비스 만들기 > IT 기술 공유

• 목록

[이번 수업]

TypeScript로 `/health` 주소에 JSON을 돌려주는 작은 서비스를 만듭니다. 타입, 입력 분기, HTTP 응답, 빌드와 실행을 한 프로젝트로 연결합니다.

[선수지식]

JSTS-005의 비동기 처리, JSTS-006의 npm, JSTS-007의 타입, JSTS-009의 Node.js, JSTS-011의 입력 검증을 알면 좋습니다.

[학습목표]

1. 응답 모양을 TypeScript 타입으로 정의한다.
2. 요청 메서드와 경로를 확인해 상태 코드를 나눈다.
3. 잠금 파일을 이용해 빌드 가능한 프로젝트를 재현한다.

[핵심개념]

미니 서비스도 입력→검증→처리→응답의 경계를 가집니다. 여기서 입력은 HTTP 메서드와 경로입니다. 허용한 `GET /health`에는 200, 나머지에는 404를 보냅니다. 리터럴 타입 `"ok"`는 status가 다른 문자열로 바뀌는 실수를 컴파일 단계에서 잡도록 돕습니다. `strict` 설정은 더 엄격한 타입 검사를 켭니다.

package.json은 실행 명령과 직접 의존성을, package-lock.json은 설치할 의존성 트리를 기록합니다. 처음 `npm install`로 잠금 파일을 만든 뒤 저장소에 포함하고, 새 환경에서는 `npm ci`로 그 기록을 따릅니다.

[따라하기]

빈 폴더에 package.json을 저장하세요. 확인한 버전을 정확히 고정했습니다.
```json
{
  "private": true,
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  },
  "devDependencies": {
    "@types/node": "25.9.5",
    "typescript": "7.0.2"
  }
}
```

tsconfig.json도 만듭니다.
```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "types": ["node"]
  }
}
```

src 폴더의 server.ts입니다.
```typescript
import { createServer } from "node:http";

type HealthResponse = {
  status: "ok";
  checkedAt: string;
};

const server = createServer((request, response) => {
  response.setHeader("content-type", "application/json; charset=utf-8");
  if (request.method !== "GET" || request.url !== "/health") {
    response.writeHead(404);
    response.end(JSON.stringify({ error: "not_found" }));
    return;
  }
  const body: HealthResponse = {
    status: "ok",
    checkedAt: new Date().toISOString(),
  };
  response.writeHead(200);
  response.end(JSON.stringify(body));
});

server.listen(3000, "127.0.0.1", () => {
  console.log("http://127.0.0.1:3000/health");
});
```

모든 운영체제에서 `npm install`, `npm run build`, `npm start` 순서로 실행합니다. 다른 터미널에서 `curl http://127.0.0.1:3000/health`를 입력하세요. Windows PowerShell에서는 `Invoke-RestMethod http://127.0.0.1:3000/health`도 됩니다. 예상 결과는 status가 ok이고 checkedAt이 현재 시각인 JSON입니다. 서버는 Ctrl+C로 끝냅니다. 잠금 파일이 생긴 뒤 깨끗한 환경에서는 `npm ci`로 확인합니다.

[흔한 실수]

모든 값을 `any`로 두면 타입의 이점이 사라집니다. 404 응답 뒤 return을 빼거나 Content-Type을 생략하지 마세요. 빌드가 성공해도 실제 주소를 호출해 응답을 확인해야 합니다.

[보안 주의]

예제는 본인 소유 로컬 환경에서만 실행하고 127.0.0.1 바인딩을 외부 주소로 바꾸지 않습니다. 낯선 패키지는 설치 전에 출처와 설치 스크립트를 확인하세요. 요청 본문, 인증, 외부 공개가 필요한 서비스는 별도 검증과 제한을 설계해야 합니다.

[직접 해볼 과제]

`GET /ready`에 `{"ready": true}`를 반환하는 타입과 분기를 추가하세요. 다른 경로는 계속 404인지 확인합니다.

[확인문제]

1. status를 일반 string 대신 `"ok"`로 제한하면 무엇이 좋아지나요?
2. package-lock.json과 npm ci는 재현성에 어떻게 도움이 되나요?
3. 허용하지 않은 메서드나 경로에 404를 보내는 이유는 무엇인가요?

[다음 학습]

WEB-012에서 이 서비스와 연결할 수 있는 접근 가능한 반응형 화면을 만듭니다.

[공식 참고 자료]

https://www.typescriptlang.org/tsconfig/strict.html
https://www.typescriptlang.org/docs/handbook/2/narrowing.html
https://nodejs.org/api/http.html
https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json/
https://docs.npmjs.com/cli/v11/commands/npm-ci/