Next.js app router로 api 함수 작성하기

 

목차

1. 전체 구조

2. api.ts : url 상수

3. handlerServerError.ts : 서버 에러 핸들러

4. safeFetch.ts : 안전한 fetch

5. articles의 route.ts

---

1. 전체 구조

우선 articles에서 다뤄야 하는 데이터들은 다음과 같다.

Next.js의 app router에서는 보이는 스웨거 구조를 그대로 폴더 구조로 만들면 된다.

물론 이 때 이 폴더들은 모두 각각의 route.ts를 포함한다.

요러케

 

폴더 구조를 잡은 후에는 각 파트에서 필요한 함수를 작성한다.

articles

• export async function POST() { ... }

• export async function GET() { ... }

[articleId]

• export async function GET() { ... }

• export async function PATCH() { ... }

• export async function DELETE() { ... }

like

• export async function POST() { ... }

• export async function DELETE() { ... }

 

이 중 articles의 POST로 전체 구조를 보면 다음과 같다.

import { NextRequest, NextResponse } from 'next/server';
import { API } from '@/constants/api';
import { handlerServerError } from '@/utils/handlerServerError';
import { safeFetch } from '@/utils/safeFetch';

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { image, title, content } = body;
    const payload = {
      image,
      title,
      content,
    };

    const data = await safeFetch(`${API.ARTICLES}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });

    return NextResponse.json({
      message: 'post article',
      data: data,
    });
  } catch (err: unknown) {
    return handlerServerError(err, 'Failed to post articles');
  }
}

 

우선 import하고 있는 API, handlerServerError, safeFetch부터 보자.

 

---

2. api.ts : url 상수

constants/api.ts에서는 url 상수를 정의하고 있다.

const BASE_URL = process.env.NEXT_PUBLIC_API_BASE_URL;

export const API = {
  BASE: BASE_URL,
  USERS: `${BASE_URL}/users/`,
  PROFILE: `${BASE_URL}/profiles/`,
  NOTIFICATION: `${BASE_URL}/notifications/`,
  IMAGE: `${BASE_URL}/images/upload/`,
  COMMENT: `${BASE_URL}/comments/`,
  AUTH: `${BASE_URL}/auth/`,
  ARTICLES: `${BASE_URL}/articles/`,
};

.env 파일에 서버 주소를 작성하여 BASE_URL로 주었고, API 객체를 정의하여 스웨거에서 확인할 수 있는 url들을 정의했다.

 

---

3. handlerServerError.ts : 서버 에러 핸들러

src/utils/handlerServerError.ts에서는 서버 에러를 다룬다.

try문에서 에러를 잡았을 때 에러를 처리하는 코드가 반복되어 작성해봤다.

import { NextResponse } from 'next/server';

export function handlerServerError(err: unknown, msg: string) {
  if (err instanceof Error) {
    console.error('[ServerError]', err.message); // 서버 콘솔에 출력되는 에러
    return NextResponse.json({ error: msg }, { status: 500 }); // 클라이언트에 출력되는 에러
  } else {
    console.error('[UnknownError]', err);
    return NextResponse.json({ error: msg }, { status: 500 });
  }
}

console.error는 서버 콘솔에만 출력되고, NextResponse는 클라이언트 콘솔에 출력된다.

서버 에러의 경우, 클라이언트 측에 보일 필요가 없기 때문에 

에러 메세지를 확인할 수 있는 err.message는 console.error로,

직접 지정한 메세지인 msg는 NextResponse로 보냈다.

 

 

---

4. safeFetch.ts : 안전한 fetch

* fetch란? : 네트워크 요청을 보내고 응답을 받는 브라우저/Node API

src/utils/safeFetch.ts는 fetch 요청을 안전하게 수행하고, 실패 시에 서버/클라이언트용 에러 메세지를 구분한다.

export async function safeFetch(url: string, options?: RequestInit) {
  try {
    const res = await fetch(url, options);

    // 안전하게 fetch 요청 수행: 응답 상태 코드가 200~299(요청 성공)인지 확인
    if (!res.ok) {
      throw new Error(`Request failed with status ${res.status}`);
    }

    const data = await res.json();
    return data;
  } catch (err: unknown) {
    console.error(err instanceof Error ? err.message : err); // 서버용 에러 메세지
    throw new Error('Server request failed'); // 클라이언트용 에러 메세지
  }
}

요청 url과 옵션을 props로 받는다.

• RequestInit : fetch 함수에 옵션을 줄 때 쓰는 타입으로, HTTP 메서드, 헤더, body 등의 요청 설정을 담는 객체이다.
• res.ok : 응답 상태 코드가 200~299(요청 성공)인지 확인한다.
  • 코드가 200~299 내 범위라면 요청은 성공했다는 걸 의미한다. 이후 에러 발생은 서버 에러로 처리된다.
  • 코드가 200~299 외 범위라면 요청이 실패했다는 뜻으로, 클라이언트에게 알린다. (404 등)
• data : res.ok를 무사히 통과하면 응답을 data에 넘기고 리턴한다. 이후 발생하는 에러는 서버 에러로,
  서버에게는 console.error로 서버용 에러 메세지를 보이고, 클라이언트에게는 Error로 클라이언트용 에러 메세지를 보인다.

 

 

---

5. articles의 route.ts

그럼 다시 articles의 route.ts를 보자.

POST : articles

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const { image, title, content } = body;
    const payload = {
      image,
      title,
      content,
    };

    const data = await safeFetch(`${API.ARTICLES}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });

    return NextResponse.json({
      message: 'post article',
      data: data,
    });
  } catch (err: unknown) {
    return handlerServerError(err, 'Failed to post articles');
  }
}

게시글을 등록하면 articles에 POST된다.

동작 순서대로 보면 다음과 같다.

1. 클라이언트로부터 요청을 받아 body에 넘김
2. body를 image, title, content로 객체구조분해함
3. 서버에 데이터를 보낼 객체인 payload에 image, title, content를 묶어서 담음
4. API.ARTICLES 주소로 options에 따라 safeFetch함수로 fetch를 진행하여 응답을 data에 전달
5. NextResponse.json()에 예쁜 모양으로 data를 전달
6. 중간에 에러 발생 시 handlerServerError()로 에러 처리 (이 에러들은 서버 에러임. 왜냐하면 클라이언트 에러는 safeFech에서 잡음)

 

GET : articles

export async function GET(request: NextRequest) {
  try {
    const { searchParams } = new URL(request.url);

    const page = searchParams.get('page') ?? '1'; // 페이지 번호
    const pageSize = searchParams.get('pageSize') ?? '10'; // 페이지 당 게시글 수
    const orderBy = searchParams.get('orderBy') ?? 'recent'; // 정렬 기준
    const keyword = searchParams.get('keyword') ?? ''; // 검색 키워드

    const query = new URLSearchParams({
      page,
      pageSize,
      orderBy,
    });
    if (keyword) query.append('keyword', keyword);

    const data = await safeFetch(`${API.ARTICLES}?${query.toString()}`);

    return NextResponse.json({
      message: 'get article',
      data: data,
    });
  } catch (err: unknown) {
    return handlerServerError(err, 'Failed to get articles');
  }
}

아까 POST에서는 request.json()으로 body를 얻어 객체를 따왔다면,

1. 이번 GET에서는 request.url로부터 파라미터를 읽어온다.

 

payload로 서버에 보낼 객체를 구성했다면,

2. query로 서버에 요청할 문자열을 구성한다.

 

3. API.ARTICLES 뒤에 구성한 쿼리 문자열을 붙여 safeFetch로 요청을 하고, 응답을 data에 담는다.

4. data를 예쁘게 클라이언트에게 보여준다.

 

 

---

6. [articleId]의 route.ts

이번에는 articleId를 보자.

articleId는 이전과 다르게 id라는 params를 가진다. 또한 PATCH, DELETE를 가진다.

근데 딱 이것들 말고는 article과 거의 동일한 방식으로 작성하면 된다.

 

type Params = {
  articleId: string;
};

// articleId 안전하게 number로 전환
function parseArticleId(articleId: string) {
  const id = parseInt(articleId, 10);
  if (isNaN(id) || id <= 0) {
    throw new Error('Invalid articleId');
  }
  return id;
}

함수를 작성하기에 앞서 파라미터 타입과 공통 함수를 작성해주었다.

params은 문자열로 들어오는데 서버에서는 id를 number로 정의하여, 안전하게 number로 바꿔주는 함수이다.

 

GET articleId

export async function GET(_request: NextRequest, { params }: { params: Promise<Params> }) {
  try {
    const { articleId } = await params; //** await을 붙여서 params를 먼저 가져와야 한다
    const id = parseArticleId(articleId);

    const data = await safeFetch(`${API.ARTICLES}${articleId}`);
    return NextResponse.json({
      message: `ArticleID: ${articleId}`,
      data: data,
    });
  } catch (err) {
    return handlerServerError(err, 'Failed to get article');
  }
}

request가 현재는 쓰이지 않고 있어서 _를 붙여줬다.

 

여기서 중요한 게 Next.js 15부터는 params가 비동기로 변경되어(type이 Promise), params에 접근할 때 await으로 먼저 접근해야하는 것이다.

 

 

1. 파라미터로부터 articleId를 가져온다.

2. id를 API.ARTICLES 뒤에 붙여서 safeFetch를 한다.

3. 받아온 데이터를 넘긴다.

 

articles에서는 여러 게시글을 조회하기 때문에 페이지, 정렬, 검색어같은 쿼리파라미터를 url에서 읽기 위해 request.url이 사용되었다.

하지만 articleId는 동적 경로( [articleId] )로 필요한 Id를 이미 받고 있어 url을 읽을 필요가 없어 request가 쓰이지 않는다.

 

PATCH articleId

export async function PATCH(request: NextRequest, { params }: { params: Params }) {
  try {
    const articleId = parseArticleId(params.articleId);

    const body = await request.json();
    const { image, title, content } = body;
    const payload = { image, title, content };

    const data = await safeFetch(`${API.ARTICLES}${articleId}`, {
      method: 'PATCH',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload),
    });
    return NextResponse.json({
      message: `ArticleID: ${articleId} updated`,
      data: data,
    });
  } catch (err: unknown) {
    return handlerServerError(err, 'Failed to patch article');
  }

PATCH는 기존 내용을 수정하는 거여서 request.json()으로 기존 내용인 body를 읽어온다.

method로 'PATCH'를 날려서 서버한테 이 요청이 수정 요청임을 알린다.

 

 

DELETE articleId

export async function DELETE(_request: NextRequest, { params }: { params: Params }) {
  try {
    const articleId = parseArticleId(params.articleId);
    const data = await safeFetch(`${API.ARTICLES}${articleId}`, { method: 'DELETE' });

    return NextResponse.json({
      message: `ArticleID: ${articleId} deleted`,
      data: data,
    });
  } catch (err) {
    return handlerServerError(err, 'Failed to delete article');
  }
}

delete는 method로 'DELETE'를 날려서 삭제 요청을 보낸다.

 

 

 

 

참고

-