API 응답 필드명을 프론트 기준으로 맞추면 달라지는 것

API를 만들 때 DB 컬럼명을 그대로 응답 필드로 내보내는 경우가 많다. created_at, user_id, is_active 같은 snake_case가 JSON에 그대로 들어오면 프론트에서는 camelCase로 변환하는 코드가 생긴다.

// 변환 코드가 필요한 상황
const createdAt = new Date(data.created_at);
const userId = data.user_id;

이 변환이 한두 곳이면 그냥 쓰는 게 낫다. 하지만 응답 타입이 많아지면 변환 코드가 여기저기 흩어진다.

프론트 기준으로 이름을 정하는 방법

백엔드에서 응답을 직렬화할 때 명시적으로 이름을 지정한다. NestJS라면 @Transform, class-transformer, 또는 단순한 객체 매핑으로 충분하다.

// 백엔드에서 응답 만들 때
return {
  id: user.id,
  createdAt: user.created_at,
  isActive: user.is_active,
};

Prisma를 쓴다면 select로 가져온 뒤 객체를 재구성하거나, 응답 DTO에서 명시적으로 camelCase 키를 쓴다.

실제로 어떤 차이가 생기는가

프론트에서 fetch로 데이터를 받아 타입을 선언할 때, 필드명이 이미 camelCase라면 타입 정의와 실제 사용이 그대로 이어진다.

interface User {
  id: string;
  createdAt: string;
  isActive: boolean;
}

const res = await fetch('/api/users/1');
const user: User = await res.json();
console.log(user.createdAt); // 변환 없이 바로 사용

응답을 curl로 먼저 확인하면 실제로 어떤 이름이 내려오는지 바로 볼 수 있다.

curl -i 'https://example.com/api/users/1'

일관성이 중요한 이유

필드명 규칙이 섞이면 타입 정의를 보고도 어느 게 camelCase이고 어느 게 snake_case인지 매번 확인해야 한다. API 설계 초기에 프론트에서 쓸 이름 기준을 정하고, 백엔드 응답에서 그 이름을 맞춰주면 이런 비용이 없어진다.

인증 헤더나 페이지네이션 파라미터도 같은 원칙이다. page_size가 아닌 pageSize, total_count가 아닌 totalCount로 내려주면 프론트 코드가 훨씬 깔끔해진다.