Next.js 13+ 라우트 매개변수는 async이다. (직접 구조분해의 위험성)

문제점

Next.js 13+ 라우트 핸들러를 사용할 때, 라우트 매개변수에 접근하는 방식에서 미묘하지만 중요한 문제가 발생할 수 있다. 다음 코드를 살펴보자:

// ⚠️ 문제가 될 수 있는 방식
export async function PATCH(
  request: Request,
  { params }: { params: { id: string } }
) {
  const id = parseInt(params.id);  // 로드 되지 전이라면 undefined이 될 수도?
  
}

얼핏 보기에는 완벽해 보이지만, URL에 ID 매개변수가 분명히 포함되어 있음에도 params.id가 정의되지 않는 예기치 않은 동작이 발생할 수 있다.

왜 이런 일이 발생하는지?

이 문제의 근본 원인은 Next.js 13+가 동적 라우트 매개변수를 처리하는 방식에 있다. 이러한 매개변수들은 비동기적으로 로드되는데, 함수 시그니처에서 { params }를 즉시 구조분해할 경우 Next.js가 로드를 완료하기 전에 값에 접근하려 할 수 있다.

해결책

올바른 접근 방식은 전체 context 객체를 받는 것이다:

// ✅ 안전한 방식
export async function PATCH(
  request: Request,
  context: { params: { id: string } }
) {
  const id = parseInt(context.params.id);  // context가 로드된 이후 접근함을 보장!
  
}

따라서!

Next.js 라우트 핸들러 작업 시:

1. 함수 시그니처에서 항상 전체 context 객체를 사용한다
2. context.params를 통해 매개변수에 접근한다
3. 매개변수가 유효하지 않을 수 있는 경우에 대한 적절한 오류 처리를 추가한다