[/\/] Route Handler, Server-Action

지난 개인 과제부터 너무 헷갈리는 라우트 핸들러, 서버 액션

[기존 지식]

라우트 핸들러는 주로 클라이언트 컴포넌트에서 사용하며 GET, POST 등을 이용해서 서버로 요청을 보내고,
나의 로컬호스트 서버로 응답을 준다. 

서버 액션은 주로 서버 컴포넌트에서 사용하며 비동기 함수를 통해 요청하고 응답을 받는다.

정도로 알고 있었다.

 

둘의 차이점은 응답을 사용하는 부분에 있다고 생각했다.

• 라우트 핸들러 : 핸들러 -> 내 서버 함수 -> 실제 사용
• 서버 액션 : 함수 -> 실제 사용

둘의 특징을 확실히 비교해보고자 한다.

---

Route Handler

// app/api/hello/route.ts
import { NextResponse } from "next/server";

// 1. GET 요청을 처리하는 핸들러
export async function GET() {
  return NextResponse.json({ message: "Hello, Next.js API!" });
}

// 2. POST 요청을 처리하는 핸들러
export async function POST(request: Request) {
  const data = await request.json();
  return NextResponse.json({ received: data });
}

// 3. 로테이션 API 라우트 핸들러 + 필터
export const GET = async (): Promise<NextResponse> => {

    const res = await fetch(ROTATION_API_URL, {
      headers: {
        "X-Riot-Token": process.env.RIOT_API_KEY!,
      },
    };
    const data =  await res.json();
    return NextResponse.json();
  };

 

📍HTTP 요청 / 응답으로 동작하는 API 엔드포인트 구현

GET, POST, PATCH, DELETE 등의 HTTP 요청 메서드 별로 핸들러를 생성한다.

그를 통해 라우터 구조에 기반한 API 엔드포인트가 생성된다.

 

즉, 파일 구조가 app/api/rotation/route.ts 라면

API 엔드포인트는 'api/rotation' 이 되는 것이다. 

 

 

📍서버와 클라이언트의 명확한 통신 구조

서버에 요청한 값이 나의 라우터 구조에 따라 엔드포인트로 생성되기 때문에

서버 <-> 클라이언트로 요청 및 응답 구조가 확실하다

 

 

📍데이터 응답 값이 서버 -> 브라우저에 전달되기 때문에 민감한 정보 주의!

Api Key 같은 경우는 환경 변수로 설정하거나

Authorization, x-api-key 같은 민감한 정보를 서버 응답 헤더에 포함하지 않도록 처리.

 

 

📍App route 방식에서 사용하며 클라이언트에서 fetch 요청을 보낼 때만 실행

라우터 구조에 따라 엔드포인트가 생성되기 때문에 앱 라우트에서 사용한다.

페이지 라우터에서는 API Routes (pages/api/*.ts) 방식을 사용해야 한다.

 

생성된 API 엔드포인트를 페치 함수로 요청하는 로직이 있어야지 라우트 핸들러가 실행된다.

// 로테이션 라우트 핸들러 응답
export const getChampionRotation = async (): Promise<Champions[]> => {
  const res = await fetch("/api/rotation");
  const data = await res.json();

  return data;
};

 

 

 

Server Action

// 챔피언 목록 패칭
export async function fetchChampionList(): Promise<Champions[]> {
  const chamUrl = await CHAMPION_LIST_URL();
  const res = await fetch(chamUrl, { next: { revalidate: 86400 } });
  const { data } = await res.json();

  //해당 페이지로 에러 보내기
  if (!res.ok) {
    throw new Error("챔피언 목록 데이터를 불러오는 중 문제가 발생했습니다!");
  }
  return Object.values(data);
}

 

📍"use server" + 비동기 함수

파일 최상단에 "use server" 를 명시해주어야 Next가 해당 로직들을 서버에서 사용한다고 인식한다.

async - await 를 사용하는 비동기 함수를 사용하여 데이터를 페칭한다.

이때 꼭 fetch를 쓰지 않아도 되며 DB 접근, 파일 처리 등을 자유롭게 할 수 있다.

 

 

📍클라이언트에서 직접 서버 전용 함수 호출 가능

서버 액션은 서버에서 사용되는 함수이지만 클라이언트에서도 직접 호출이 가능하다.

직접 호출하여 그 응답값을 받아볼 수 있다.

 

 

📍별도의 API 라우터가 필요 없음

보통 API 요청을 할 때는 'pages/api/my-action.js'처럼 API 라우터 파일을 만들어야 클라이언트에서 해당 API를 호출할 수 있었다.

하지만 서버 액션은 라우터 없이 클라이언트에서 바로 호출이 가능하다.

서버 액션은 서버에서 직접 실행되고 자체적으로 네트워크 요청을 처리하기 때문이다.

 

 

📍함수 호출 형식

위 예시에서처럼 fetchChampionList 함수를 만들고,

사용하는 곳에서는 const data = await fetchChampionList(); 로 서버 액션 함수를 호출하여 응답 값을 받는다.

 

 

📍보안 강화

서버 액션은  서버 <-> 서버의 통신이기 때문에 응답 값이 브라우저에 오지 않는다.

따라서 민감한 정보 등을 노출시키지 않고 통신이 가능하다.

 

 

📍클라이언트에서 사용 시, POST 요청

보통 POST 요청은 body에 값을 담아 새로운 값을 추가하는 역할이다.

하지만 서버 액션에서는 어떤 작업을 서버에서 처리하고 결과를 반환하는 역할이다.

이 요청의 핵심은 서버에서 특정 로직을 실행하는 것이다.

1. 서버 액션에서 데이터 처리

"use server";

export async function processData(data: string) {
  // 서버에서 데이터 처리
  console.log("서버에서 데이터 처리:", data);
  const processedData = data.toUpperCase(); // 예: 대문자로 변환
  return processedData;
}

 

2. 외부 API 호출

"use server";

export async function fetchWeather(city: string) {
  const res = await fetch(`https://api.weather.com/v1/${city}`);
  const data = await res.json();
  return data;
}

 

 

📍서버 액션 함수의 인자가 요청 body에 담김

인자에 아무 값도 담기지 않는다면 요청에 따른 응답값을 받아오는 것이다.

하지만 인자에 어떤 값이 담긴 경우, 그 값이 body에 담겨서 요청이 된다. (개발자도구 > 네트워크 탭에서 확인)

1. 서버 액션 함수에 전달된 인자 활용

• 인자의 데이터를 기반으로 다양한 계산, 로직 실행 가능

"use server";

export async function processData(data: string, count: number) {
  // 클라이언트에서 받은 데이터와 count를 이용한 작업
  console.log("받은 데이터:", data);
  console.log("받은 숫자:", count);
  return `${data}의 길이는 ${data.length}이고, 숫자 ${count}는 ${count * 2}입니다.`;
}

 

2. 서버 액션 함수 호출 (클라이언트)

• 클라이언트에서 서버 액션을 활용할 때 인자 값을 넘겨줌
• 서버에서 이 값을 처리하고 그 결과를 클라이언트에 반환

"use client";
import { processData } from "./actions";

export default function MyComponent() {
  const handleClick = async () => {
    const data = "Hello, World!";
    const count = 5;
    const result = await processData(data, count);
    console.log(result); // 서버에서 처리된 결과를 출력
  };

  return <button onClick={handleClick}>서버 액션 실행</button>;
}

 

3. 인자를 이용한 다양한 실행

• 조건문을 사용하여 받은 데이터를 다르게 처리
• 데이터베이스 쿼리에 인자 활용
• 외부 API 호출에 인자 전달

4. 인자를 기반으로 동적인 실행

• actionType에 따라 서버에서 다른 작업 진행

"use server";

export async function handleAction(actionType: string, data: any) {
  if (actionType === "uppercase") {
    return data.toUpperCase();
  } else if (actionType === "reverse") {
    return data.split('').reverse().join('');
  } else {
    return "알 수 없는 작업";
  }
}

 

 

둘 중 어느 것이 좋고 나쁨을 따지는 것이 아닌 각자의 특성과 역할이 있으며

상황을 잘 파악하여 그에 맞는 방식을 선택하는 것이 중요하다고 생각한다.