Nitro

Nitro는 서버와 API를 구성하고 여러 실행 환경에 맞는 결과물을 만드는 서버 프레임워크다. 파일 기반 라우팅, 서버 빌드와 저장소·캐시 기능을 제공한다. Nuxt의 서버 기반으로도 알려져 있지만 독립 프로젝트에서 사용할 수도 있다.

서버 코드와 배포 대상

라우트 파일을 요청 경로에 연결하고 필요한 서버 코드를 빌드 결과물로 묶는다. 배포 프리셋은 Node.js 서버나 다른 플랫폼에 맞는 실행 형태를 정한다. 동일한 응용 로직을 옮기는 부담을 줄일 수 있지만, 파일 시스템·프로세스 수명·요청 제한처럼 플랫폼마다 다른 조건이 사라지는 것은 아니다.

장점은 서버 기능을 프런트엔드 빌드와 연결하고 배포 구조를 표준화하기 쉽다는 것이다. 작은 API와 렌더링 서비스를 함께 운영하는 데 편리하다. 한계는 프리셋·버전·상위 프레임워크의 관례를 구분해야 한다는 점이다. 최신 독립 Nitro의 routes 디렉터리와 Nuxt의 server/api 관례를 무심코 혼합하면 파일이 기대한 경로에 등록되지 않을 수 있다.

가상 도서 서비스의 상태 API

최신 독립 Nitro 프로젝트가 준비되어 있다고 가정한다. Nuxt 프로젝트에 그대로 넣는 예제가 아니다. routes/health.get.ts에 아래를 작성한다. 외부 서비스에 접속하지 않고 가상의 도서 서비스가 살아 있다는 정적인 응답만 반환한다.

import { defineHandler } from 'nitro';

export default defineHandler(() => ({
  service: 'library-catalog',
  status: 'ready',
}));

Node 서버 프리셋으로 빌드된 .output 디렉터리가 있으면 다음처럼 실행할 수 있다. 빌드 단계는 프로젝트에 설정된 Nitro 또는 Vite 명령을 사용하며, 아래는 빌드 이후의 실행 명령이다.

NITRO_HOST=127.0.0.1 NITRO_PORT=4340 node .output/server/index.mjs
# 다른 터미널에서 확인
curl http://127.0.0.1:4340/health

응답의 service와 status 필드를 확인할 수 있다. 다만 이 정적 응답은 DB나 외부 API의 준비 상태까지 증명하지 않는다. 프로세스 생존 검사와 실제 서비스 준비 검사를 나누어 설계하면 장애 원인을 더 정확하게 구분할 수 있다.

캐시와 상태의 주의점

캐시는 응답을 재사용해 비용을 줄이지만 사용자별 데이터를 잘못 공유하면 다른 사람의 정보가 섞일 수 있다. 인증 상태·권한·언어·질의 조건 중 결과를 바꾸는 요소를 캐시 키와 정책에 반영해야 한다. 저장소 기본값이 메모리라면 재시작 후 지속성이나 여러 인스턴스의 공유 상태를 기대하지 않는다.

Node 서버의 바인딩 주소와 포트는 배포 네트워크에 맞춰 결정한다. 서버 종료 시 진행 중 작업을 어떻게 마무리할지, 외부 저장소의 연결을 어떻게 정리할지도 확인한다. 서버를 묶어 주는 빌드 기능과 데이터의 내구성·업무 권한은 서로 다른 책임이다.

참고 자료