NextJS API: next/server

next/server는 미들웨어 및 Edge API 라우트에서 사용할 수 있는 서버 전용 도우미를 제공합니다.

NextRequest

NextRequest 객체는 기존 Request 인터페이스를 확장하여 다음과 같은 추가 메서드와 속성을 가집니다.

• cookies - Request에서 쿠키를 담은 RequestCookies 인스턴스입니다. 요청의 Cookie 헤더를 읽거나 수정합니다. 미들웨어에서 쿠키 사용하기를 참조하세요.

  • get - 쿠키 이름을 인자로 받아 해당 쿠키의 이름과 값을 가진 객체를 반환합니다. 해당 이름의 쿠키를 찾을 수 없으면 undefined를 반환합니다. 여러 개의 쿠키가 일치하는 경우 첫 번째 일치하는 것만 반환합니다.
  • getAll - get과 비슷하지만, 모든 해당 이름의 쿠키 목록을 반환합니다. 이름을 지정하지 않으면 사용 가능한 모든 쿠키를 반환합니다.
  • set - W3C CookieStore API 명세의 CookieListItem 속성을 가진 객체를 인자로 받습니다.
  • delete - 쿠키 이름 또는 이름 목록을 인자로 받아 일치하는 쿠키를 제거합니다. 삭제된 쿠키는 true, 삭제되지 않은 쿠키는 false를 반환합니다.
  • has - 쿠키 이름을 인자로 받아 해당 쿠키가 존재하는지 여부에 따라 불리언 값을 반환합니다.
  • clear - 인자를 받지 않고 Cookie 헤더를 효과적으로 제거합니다.

• nextUrl: Next.js 특정 속성인 pathname, basePath, trailingSlash 및 i18n에 액세스할 수 있는 확장된 파싱된 URL 객체를 포함합니다. 다음과 같은 속성을 가집니다.

  • basePath (string)
  • buildId (string || undefined)
  • defaultLocale (string || undefined)
  • domainLocale
    • defaultLocale: (string)
    • domain: (string)
    • http: (boolean || undefined)
    • locales: (string[] || undefined)
  • locale (string || undefined)
  • url (URL)

• ip: (string || undefined) - 요청의 IP 주소를 가지고 있습니다. 이 정보는 호스팅 플랫폼에서 제공됩니다.

• geo - 요청의 지리적 위치를 가지고 있습니다. 이 정보는 호스팅 플랫폼에서 제공됩니다. 다음과 같은 속성을 가집니다.

  • city (string || undefined)
  • country (string || undefined)
  • region (string || undefined)
  • latitude (string || undefined)
  • longitude (string || undefined)

NextRequest 객체를 사용하여 요청을 조작하는 방법을 보다 세밀하게 제어할 수 있습니다.

NextRequest는 다음과 같이 next/server에서 가져올 수 있습니다.

import type { NextRequest } from 'next/server';

NextFetchEvent

NextFetchEvent 객체는 기본 FetchEvent 객체를 확장하여 waitUntil() 메서드를 포함하고 있습니다.

waitUntil() 메서드는 기타 백그라운드 작업을 수행해야하는 경우 함수의 실행을 연장하는 데 사용할 수 있습니다.

import { NextResponse } from 'next/server';
import type { NextFetchEvent, NextRequest } from 'next/server';

export function middleware(req: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://my-analytics-platform.com', {
      method: 'POST',
      body: JSON.stringify({ pathname: req.nextUrl.pathname }),
    })
  );

  return NextResponse.next();
}

NextFetchEvent 객체는 next/server에서 가져올 수 있습니다.

import type { NextFetchEvent } from 'next/server';

NextResponse

NextResponse 클래스는 다음과 같은 기본 응답 인터페이스를 확장합니다.

Public 메서드

공개 메서드는 NextResponse 클래스의 인스턴스에서 사용할 수 있습니다. 사용 사례에 따라 인스턴스를 만들고 변수에 할당한 다음 다음 공개 메서드에 액세스할 수 있습니다.

• cookies - 응답에서 가져온 쿠키를 포함하는 ResponseCookies 인스턴스입니다. 응답의 Set-Cookie 헤더를 읽거나 수정합니다. Middleware에서 쿠키 사용 방법도 참조하십시오.
  • get - 쿠키 이름을 인수로 사용하여 이름과 값이 포함된 객체를 반환하는 메서드입니다. 해당 이름의 쿠키가 없으면 undefined를 반환합니다. 여러 쿠키가 일치하는 경우 첫 번째 일치 항목만 반환됩니다.
  • getAll - get과 유사하지만 일치하는 이름의 모든 쿠키 목록을 반환합니다. 이름이 지정되지 않으면 사용 가능한 모든 쿠키를 반환합니다.
  • set - W3C CookieStore API 사양에서 정의된 CookieListItem 속성을 가진 객체를 인수로 사용하는 메서드입니다.
  • delete - 쿠키 이름 또는 이름 목록을 인수로 사용하며 해당 이름과 일치하는 쿠키를 제거합니다. 삭제된 경우 true를 반환하고 삭제되지 않은 경우 false를 반환합니다.

Static 메서드

다음 정적 메서드는 NextResponse 클래스에서 직접 사용할 수 있습니다.

• redirect() - 리디렉션을 설정한 NextResponse를 반환합니다.
• rewrite() - 리라이트를 설정한 NextResponse를 반환합니다.
• next() - 미들웨어 체인을 계속 진행하는 NextResponse를 반환합니다.
  위의 메서드를 사용하려면 반환된 NextResponse 객체를 반환해야합니다. NextResponse는 next/server에서 가져올 수 있습니다.

import { NextResponse } from 'next/server';

userAgent

userAgent 도우미는 요청의 user agent 객체와 상호 작용할 수 있게 해줍니다. 이는 네이티브 Request 객체에서 추상화되었으며, 선택적으로 사용할 수 있는 기능입니다. 다음과 같은 속성이 있습니다:

• isBot: (boolean) 요청이 알려진 봇에서 왔는지 여부
• browser
  • name: (string || undefined) 브라우저의 이름
  • version: (string || undefined) 동적으로 결정된 브라우저 버전
• device
  • model: (string || undefined) 동적으로 결정된 기기 모델
  • type: (string || undefined) 브라우저의 유형으로, 다음 값 중 하나일 수 있습니다: console, mobile, tablet, smarttv, wearable, embedded 또는 undefined
  • vendor: (string || undefined) 동적으로 결정된 기기의 공급 업체
• engine
  • name: (string || undefined) 브라우저 엔진의 이름으로, 다음 값 중 하나일 수 있습니다: Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, KHTML, Links, Lynx, NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit 또는 undefined
  • version: (string || undefined) 동적으로 결정된 브라우저 엔진 버전 또는 undefined
• os
  • name: (string || undefined) 운영 체제의 이름으로 undefined일 수 있습니다.
  • version: (string || undefined) 동적으로 결정된 운영 체제의 버전 또는 undefined
• cpu
  • architecture: (string || undefined) CPU의 아키텍처로 다음 값 중 하나일 수 있습니다: 68k, amd64, arm, arm64, armhf, avr, ia32, ia64, irix, irix64, mips, mips64, pa-risc, ppc, sparc, sparc64 또는 undefined

userAgent는 다음을 통해 next/server에서 가져올 수 있습니다:

import { userAgent } from 'next/server';
import { NextRequest, NextResponse, userAgent } from 'next/server';

export function middleware(request: NextRequest) {
  const url = request.nextUrl;
  const { device } = userAgent(request);
  const viewport = device.type === 'mobile' ? 'mobile' : 'desktop';
  url.searchParams.set('viewport', viewport);
  return NextResponse.rewrite(url);
}

FAQ

왜 redirect는 307과 308을 사용하나요?

redirect()를 사용할 때 일시적인 리디렉션에는 307을, 영구적인 리디렉션에는 308을 사용한다는 것을 알 수 있습니다. 일반적으로 일시적인 리디렉션에는 302가 사용되었고, 영구적인 리디렉션에는 301이 사용되었습니다. 그러나 많은 브라우저들은 302를 사용하는 경우 리디렉션이 POST 요청에서 GET 요청으로 변경되어버렸습니다.

/users에서 /people로 리디렉션하는 경우, 새로운 사용자를 만들기 위해 /users로 POST 요청을 한 경우, 302 일시적인 리디렉션을 준수하는 경우, 요청 방법이 POST에서 GET 요청으로 변경됩니다. 이것은 올바르지 않습니다. 새로운 사용자를 만들기 위해서는 POST 요청을 /people로 해야 합니다.

307 상태 코드가 도입되면 요청 방법이 POST로 보존됩니다.

• 302 - 일시적인 리디렉션, 요청 방법을 POST에서 GET으로 변경합니다.
• 307 - 일시적인 리디렉션, 요청 방법을 POST로 보존합니다.
  redirect() 메서드는 기본적으로 307을 사용합니다. 따라서 요청이 항상 POST 요청으로 보존됩니다.
  POST 요청에 대한 GET 응답을 유도하려면 303을 사용하면 됩니다.

HTTP 리디렉션에 대해 더 알아보세요.

환경 변수에 어떻게 액세스할 수 있나요?

process.env를 사용하여 Edge 미들웨어에서 환경 변수에 액세스할 수 있습니다. 이는 next 빌드 중에 평가됩니다.

작동 방식	작동하지 않는 방식
console.log(process.env.MY_ENV_VARIABLE)	const getEnv = name => process.env[name]
const { MY_ENV_VARIABLE } = process.env
const { "MY-ENV-VARIABLE": MY_ENV_VARIABLE } = process.env