[Nuxt3] Server

server 디렉토리 구조

server 디렉토리는 다음과 같은 하위 디렉토리로 구성됩니다:

• server/api: API 라우트를 정의하는 디렉토리 (/api 접두사 자동 추가)
• server/routes: 사용자 정의 라우트를 정의하는 디렉토리 (/api 접두사 없음)
• server/middleware: 요청 처리 전에 실행되는 미들웨어를 정의하는 디렉토리
• server/plugins: Nitro 플러그인을 정의하여 서버 기능을 확장하는 디렉토리
• server/utils: 커스텀 헬퍼 함수를 정의하는 디렉토리

---

API 라우트 (server/api)

자동으로 /api 접두사가 붙어 경로가 생성됩니다:

// server/api/hello.ts
export default defineEventHandler(() => ({ message: "Hello Nuxt!" }));

사용자 정의 라우트 (server/routes)

/api 접두사 없이 경로 생성 가능.

// server/routes/hello.ts
export default defineEventHandler(() => 'Hello World!');

서버 미들웨어 (server/middleware)

미들웨어는 응답을 직접 반환하지 않고 컨텍스트만 확장하거나 오류를 발생시키는 용도로 사용됩니다.

// server/middleware/log.ts
export default defineEventHandler((event) => {
  console.log('새로운 요청:', getRequestURL(event));
});

// server/middleware/auth.ts
export default defineEventHandler((event) => {
  event.context.auth = { user: 123 };
});

 

서버 플러그인 (server/plugins)

Nitro 런타임 동작을 확장하고 라이프사이클 이벤트를 활용할 수 있습니다.

// server/plugins/nitroPlugin.ts
export default defineNitroPlugin((nitroApp) => {
  console.log('Nitro 플러그인 등록', nitroApp);
});

서버 유틸리티 (server/utils)

커스텀 헬퍼 함수를 정의하여 코드의 재사용성과 가독성을 높일 수 있습니다.

// server/utils/handler.ts
import type { EventHandler, EventHandlerRequest } from 'h3';

export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D>(
  handler: EventHandler<T, D>
): EventHandler<T, D> =>
  defineEventHandler<T>(async event => {
    try {
      const response = await handler(event);
      return { response };
    } catch (err) {
      return { err };
    }
  });

서버 타입 설정 (server/tsconfig.json)

이 설정은 IDE에서 타입 힌트를 개선하는 데 도움이 됩니다 (Nuxt 3.5 이상).

{
  "extends": "../.nuxt/tsconfig.server.json"
}

 

다양한 서버 라우트 활용법

HTTP 메서드 라우팅

// server/api/item.get.ts
export default defineEventHandler(() => ({ message: "GET 요청 처리" }));

// server/api/item.post.ts
export default defineEventHandler(() => ({ message: "POST 요청 처리" }));

동적 파라미터 라우팅

// server/api/user/[id].ts
export default defineEventHandler((event) => ({ id: getRouterParam(event, 'id') }));

Catch-all 라우트

// server/api/foo/[...slug].ts
export default defineEventHandler((event) => `Slug: ${event.context.params.slug}`);

요청 본문 및 쿼리 처리

// server/api/query.get.ts
export default defineEventHandler(event => getQuery(event));

// server/api/submit.post.ts
export default defineEventHandler(async event => ({ body: await readBody(event) }));

환경 변수와 런타임 설정

.env 파일과 함께 런타임 설정을 관리할 수 있습니다:

NUXT_PUBLIC_API_BASE=https://api.example.com

// server/api/env.ts
export default defineEventHandler(() => useRuntimeConfig().public.apiBase);

 

외부 API 서버 프록시 설정하기

직접 구현한 API와 프록시 API를 혼용하여 활용 가능합니다.

// server/api/courses/index.get.ts (직접 구현)
export default defineEventHandler(() => ([{ id: 1, name: 'Nuxt 3 강좌' }]));

// server/api/[...].ts (외부 API 프록시)
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig();
  const path = event.context.params?._;
  const url = `${config.public.apiBase}/${path}`;

  try {
    return await proxyRequest(event, url);
  } catch (error) {
    throw createError({
      status: 502, // Bad Gateway 등의 적절한 상태코드 사용
      statusMessage: '외부 API 요청 실패',
    });
  }
});

 

proxyRequest()

• Nitro(unjs/h3)에서 제공하는 내장 유틸리티로, 외부 API 호출을 매우 쉽게 프록시할 수 있도록 해줍니다.
• 외부 API로 요청을 보낼 때, 현재 요청(event)의 메서드(GET, POST 등), 헤더, 바디, 쿼리 파라미터를 별도 가공 없이 그대로 외부 API에 전달합니다.
• 응답도 별도의 가공 없이 그대로 클라이언트에 전달합니다.
• 따라서 프록시 전용으로 사용하는 경우엔, 메서드, 바디, 쿼리 파라미터를 직접 설정하지 않아도 자동으로 전달됩니다.