*다음 우편번호 서비스 가이드 https://postcode.map.daum.net/guide

1. 스크립트 추가하기

먼저 다음 주소검색 스크립트를 불러와야 한다.

<script src="//t1.daumcdn.net/mapjsapi/bundle/postcode/prod/postcode.v2.js"></script>

이 스크립트를 불러오면 window.daum.Postcode 를 사용할 수 있다.

2. TypeScript 전역 타입 선언하기

다음 주소검색은 npm 패키지를 import 해서 쓰는 방식이 아니라, 외부 스크립트를 로드한 뒤 window.daum.Postcode 전역 객체를 사용하는 방식이다.

그래서 별도 import는 필요 없고, TypeScript에서는 아래처럼 전역 타입 선언을 추가해두면 된다

declare global {
  interface Window {
    daum?: {
      Postcode: new (options: {
        oncomplete: (data: DaumPostcodeData) => void;
        onclose?: (state: "FORCE_CLOSE" | "COMPLETE_CLOSE") => void;
      }) => {
        open: () => void;
      };
    };
  }
}

any 로 넓게 선언할 수도 있지만, 실제로 사용하는 Postcode 구조만 명시해두면 자동완성과 타입 체크 측면에서 더 안전하다.

3. 기본 사용법

주소 검색은 아래처럼 열 수 있다.

new window.daum.Postcode({
  oncomplete: (data) => {
    console.log(data);
  },
}).open();

4. 유틸 함수로 분리하기

type SelectedRegion = {
  addressLabel: string | null;
  region1DepthName: string | null;
  region2DepthName: string | null;
  region3DepthName: string | null;
};

type OpenDaumAddressSearchParams = {
  onSelect: (region: SelectedRegion) => void;
};

export const openDaumAddressSearch = ({
  onSelect,
}: OpenDaumAddressSearchParams) => {
  if (!window.daum?.Postcode) {
    throw new Error("Daum Postcode script is not loaded.");
  }

  new window.daum.Postcode({
    oncomplete: (data) => {
      onSelect({
        addressLabel: data.roadAddress || data.jibunAddress || null,
        region1DepthName: data.sido || null,
        region2DepthName: data.sigungu || null,
        region3DepthName: data.bname || null,
      });
    },
  }).open();
};

5. 컴포넌트에서 사용하기

버튼 클릭 시 주소검색을 열고, 선택한 값을 상태에 반영하면 된다.

const handleOpenAddressSearch = async () => {
  try {
    openDaumAddressSearch({
      onSelect: (selectedRegion) => {
        setField("mainRegion", {
          ...selectedRegion,
          // 사용자에게 따로 입력받을 상세 주소
          detailAddress: mainRegion?.detailAddress ?? null,
        });
      },
    });
  } catch (error) {
    console.error(error);
    alert("주소 검색 창을 열지 못했습니다.");
  }
};

6. 정리

다음 주소검색 사용 흐름은 단순하다.

1. 스크립트 로드
2. window.daum 전역 타입 선언
3. new window.daum.Postcode() 생성
4. open() 으로 팝업 열기
5. oncomplete 에서 선택 결과 받기
6. 필요한 형태로 상태 저장

주소를 직접 입력받는 것보다 훨씬 안정적이고, 폼에서도 재사용하기 좋다.

Next.js 프로젝트를 진행하면서 데이터베이스를 코드로 다루기 위해 Prisma를 사용했다. Prisma는 Node.js 와 TypeScript 환경에서 사용할 수 있는 ORM이며, 타입 안전한 데이터 접근, 스키마 기반 모델링, 마이그레이션 관리, GUI 기반 데이터 확인 도구까지 함께 제공한다. Prisma 공식 문서에서도 Prisma ORM을 타입 안전한 데이터 접근, 마이그레이션, 시각적 데이터 편집 기능을 제공하는 ORM으로 설명한다.

*ORM(Object Relational Mapping) : RDBMS의 테이블을 코드 상의 객체처럼 다룰 수 있게 해주는 기술

*마이그레이션(Migration) : DB 스키마 변경 사항을 기록하고 적용하는 작업

*GUI(Graphical User Interface) : 아이콘, 버튼, 창 같은 시각적 요소를 통해 사용자가 기능을 쉽게 조작할 수 있도록 만든 인터페이스

Prisma ORM 공식 문서

Prisma란 무엇인가

Prisma는 공식적으로 Node.js와 TypeScript를 위한 차세대 ORM으로 소개된다. PostgreSQL, MySQL, SQL Server, MongoDB, CockroachDB 등 여러 데이터베이스를 지원하며, 핵심 구성은 보통 세 가지로 나뉜다. Prisma Client, Prisma Migrate, Prisma Studio가 대표적이다.

각 역할은 다음과 같다.

• Prisma Client: Prisma schema를 기반으로 생성되는 타입 안전한 ORM 인터페이스. 코드에서 findMany, create, update 같은 방식으로 DB를 다룰 수 있다.
• Prisma Migrate: 스키마 변경을 migration 파일로 관리하고, 개발 및 운영 환경에 반영하는 도구.
• Prisma Studio: 브라우저 기반 GUI에서 데이터를 조회하고 수정할 수 있는 도구.

즉, Prisma는 단순한 "Query 헬퍼" 가 아니라, 데이터 모델 정의부터 쿼리 실행, 변경 이력 관리까지 한 흐름으로 가져가는 도구로 취급한다.

Next.js 에서 Prisma를 쓰는 이유

Next.js는 프론트엔드 프레임워크처럼 보이지만, 실제로는 서버 컴포넌트, 서버 액션, Route Handler, API Route 등 서버 로직도 함께 다루는 풀스택 구조에 가깝다. Prisma는 이런 환경에서 특히 잘 맞는다. Prisma 공식 가이드도 Next.js에서 Prisma를 설정하고, 마이그레이션을 다루고, 배포하는 흐름을 별도로 제공한다.

해당 공식 문서

Prisma를 선택한 이유는 크게 네 가지다.

1. 타입 안정성이 좋다 💭

Prisma Client는 Prisma schema를 바탕으로 자동 생성된다. 그래서 모델 필드명이나 타입이 바뀌면 TypeScript에서 바로 감지할 수 있는 경우가 많다. 문자열 기반 쿼리를 직접 흩뿌리는 것보다 훨씬 안정적이다. Prisma는 Prisma Client를 auto-generated, type-safe ORM Interface로 설명한다.

2. 모델 구조를 코드로 관리할 수 있다 💭

Prisma에서는 schema.prisma 파일에 데이터 모델을 정의한다. 이 말은 즉, 데이터베이스 구조가 코드 레벨에서 관리된다는 뜻이다. 모델 정의가 프로젝트 안에 명시적으로 남기 때문에, 구조를 파악하기도 쉽고 팀원과 공유하기도 좋다. Prisma schema API는 datasource, generator, model 등을 Prisma schema 언어로 정의하도록 안내한다.

3. 마이그레이션 이력을 남길 수 있다 💭

스키마 변경이 생길 때마다 migration 파일을 생성해 이력을 남길 수 있다. 단순히 "테이블 바뀜"이 아닌 어떤 변경이 어떤 순서로 있었는지 Git에 함께 남길 수도 있다는 뜻이다. Prisma Migrate는 SQL migration 파일 히스토리를 생성하고, Git 저장소에서 관리할 수 있게 해 준다.

4. Next.js와 공식 가이드가 잘 갖춰져 있다💭

Prisma는 Next.js용 공식 가이드를 제공하고, App Router 환경과 배포 흐름까지 다룬다. 즉, 레퍼런스가 잘 정리되어 있고 문제가 생겼으 때 공식 자료를 찾기도 쉽다.

Prisma 기본 구조

Prisma를 처음 붙이면 보통 프로젝트 안에 prisma/schema.prisma 파일이 생긴다. 여기서 datasource, generator, model을 정의한다. Prisma 공식 문서는 prisma init 실행 시 Prisma 프로젝트 자산을 초기화하고, prisma.config.ts 역시 Prisma CLI 설정 파일로 사용할 수 있다고 설명한다.

예시 코드

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

이렇게 정의한 뒤 Prisma Client를 생성하면 코드에서 다음처럼 사용할 수 있다.

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

const users = await prisma.user.findMany();

const createdUser = await prisma.user.create({
  data: {
    email: "test@example.com",
    name: "Lui",
  },
});

Prisma Client는 schema를 기준으로 생성되기 때문에, 모델 이름과 필드에 맞춰 타입이 따라온다. 그게 Prisma를 사용하는 가장 크게 체감한 장점 중 하나다.

Prisma를 사용할 때의 기본 흐름

Next.js 프로젝트에서 Prisma를 사용할 때 보통 흐름은 아래와 같다.

1. Prisma 설치 및 초기화
2. schema.prisma 에 모델 정의
3. Prisma Client 생성
4. 스키마를 DB에 반영
5. 코드에서 Prisma Client 사용
6. 데이터 확인이 필요하면 Prisma Studio 실행

이 흐름은 Prisma CLI와 Next.js 공식 가이드에서 안내하는 전형적인 패턴과 맞닿아 있다.

db push 와 migrate dev 차이

npx prisma db push db push는 현재 Prisma schema 상태를 migration 없이 db에 반영한다. 이는 프로토타이핑이나 로컬 개발에 적합하다.

npx prisma migrate dev migrate dev는 스키마 변경을 기반으로 migration 파일 히스토리를 생성하고 개발 DB 스키마를 Prisma schema와 동기화 시켜준다.

즉, 협업이나 운영 배포까지 생각한다면 보통 migrate dev 가 더 적절하다. 빠른 실험은 db push , 이력 관리가 필요한 개발은 migrate dev 라고 구분하면 이해하기 쉽다.

*shadow database는 왜 생기나

Prisma를 쓰다 보면 migrate dev 실행 중 shadow database 관련 메시지를 볼 수 있다. 이건 Prisma가 문제를 일으키는 게 아니라, 스키마 드리프트나 잠재적인 데이터 손실 가능성을 감지하기 위해 임시 데이터베이스를 사용하는 동작이다. Prisma 문서에 따르면 shadow database는 prisma migrate dev 실행 시 자동 생성 및 삭제되며, migration 문제 감지에 사용된다.

사고를 미리 막기위해 검사하는 안전장치 정도로 이해하면 된다.

자주 쓰는 Prisma 명령어 정리 💭

1. Prisma 초기화

   npx prisma init

• Prisma 프로젝트 자산 초기화
• 보통 prisma/ 디렉터리와 기본 설정 파일들이 생성됨
• 프로젝트 셋업 명령

2. Prisma Client 생성

   npx prisma generate

• Prisma schema를 바탕으로 Prisma Client를 생성
• 모델 수정 후 Client를 다시 생성해야할 때 자주 사용
• artifacts 생성 명령

3. 스키마를 DB에 바로 반영

   npx prisma db push

• 마이그레이션 없이 스키마 상태를 DB에 반영
• 프로토타이핑이나 로컬 초기 개발에 유용

4. 개발용 migration 생성 및 적용

   npx prisma migrate dev

• 스키마 변경을 기준으로 마이그레이션 파일을 만들고 개발 DB에 적용한다.
• 개발 환경에서 가장 자주 쓰는 명령어 중 하나다.

5. 운영 환경에 migration 적용

npx prisma migrate deploy

• 이미 생성된 migration 파일들을 운영 데이터베이스에 적용한다.(supabase 같은)
• Prisma Migrate는 개발과 운영에서 migration history를 다루는 역할을 한다.

6. 데이터 GUI 확인

   npx prisma studio

• 브라우저 GUI에서 데이터를 조회/수정 가능
• 테이블 상태를 빨리 확인할 때 편하다

7. 현재 DB 기준으로 schema 가져오기

   npx prisma db pull

• 이미 존재하는 데이터베이스 구조를 기준으로 Prisma schema를 업데이트할 때 사용

8. schema 포맷 정리

   npx prisma format

• schema.prisma 파일을 포맷팅한다.

10. migration 차이 비교

npx prisma migrate diff

• migration 간 차이나 schema 차이를 비교할 때 사용한다.
• 스키마 상태 점검에 유용

실제 자주 쓰게 되었던 흐름

실제 개발에 사용해보니 이러한 흐름으로 가게 되었다.

• 모델을 수정한다.
• 빠르게 반영 -> npx prisma db push 사용
• 구조가 확정되었음 -> npx prisma migrate dev --name... 로 migration 파일을 남긴다
• 필요하면 npx prisma generate로 Client를 다시 생성하고, npx prisma studio 로 데이터를 눈으로 확인한다.

npx prisma init
npx prisma generate
npx prisma db push
npx prisma migrate dev --name init
npx prisma studio

마무리

Prisma를 사용하면서 가장 좋았던 점은, 코드와 함께 관리하는 구조로 바꿔준다는 점이었다.

모델을 schema로 정의하고, Client를 통해 타입 안전하게 접근하고, migration 파일로 이력을 남기고, Studio로 바로 데이터를 확인할 수 있다는 점이 Next.Js 프로젝트와 잘 맞았다.

특히 Next.js처럼 프론트와 서버 로직이 가까이 붙어있는 환경에서는 Prisma가 더 편하게 느껴졌다. DB 구조와 애플리케이션 코드가 따로 노는 게 아니라, 하나의 흐름으로 연결되었기 때문이다.

개인적으로는 DB를 처음부터 서버 환경에서만 직접 관리하는 방식보다, 로컬에서 먼저 검증하고 migration 파일로 변경 이력을 남기는 방식이 더 안정적이라고 느꼈다. 배포된 DB에 바로 둩어 수정하는 방식은 빠를 수는 있지만, 구조 변경이 누적될수록 추적과 관리가 어려워질 수 있다. Prisma를 사용한 이유도 바로 이런 점 때문이었고, 단순한 쿼리 편의성보다 스키마를 더 일관되게 관리할 수 있다는 점이 특히 크게 느껴졌다.

1. FullCalendar를 붙여보자

현재 프로젝트에서 기존 예약 관리 화면은 탭과 검색, 그리고 예약 카드 리스트 중심으로 구성되어 있었다. 탭별로 요청, 진행 중, 완료, 취소/거절 상태를 나눠 조회할 수 있었지만, 사용자는 예약을 시간 흐름으로 파악하기 어려웠다.

특히 다음과 같은 불편함이 있었다.

• 특정 날짜에 어떤 예약이 몰려 있는지 한눈에 보기 어렵다
• 탭을 바꿀 때마다 상태별 예약 흐름은 보이지만, 실제 일정 분포는 파악하기 힘들다
• 리스트만으로는 오늘/이번 달/특정 날짜 기준의 맥락이 약하다

그래서 예약 관리 화면에 월간 달력을 추가하고, 현재 탭/검색 조건에 맞는 예약을 달력에도 함께 표시하는 구조를 만들기로 했다.

2. 왜 react-day-picker 대신 FullCalendar를 선택했는가

처음에는 단순한 날자 선택기 성격의 라이브러리도 고려했지만, 원하는 UI는 단순한 date picker가 아니었다.

내가 원한건:

• 달력이 화면에서 어느정도 비중 있게 보일 것
• 날짜마다 예약 일정이 표시될 것
• 날짜 클릭 시 해당 날짜의 예약만 리스트에서 다시 볼 수 있을것
• 일정 클릭 시 기존 예약 상세 모달까지 연결될 것

즉, 단순히 날짜를 고르는 컴포넌트보다 일정을 보여주는 월간 캘린더가 필요했다.

그래서 날짜 선택기보다는 이벤트 렌더링이 중심인 FullCalendar가 더 적합하다고 판단했다.

3. FullCalendar 사용법

1) 설치

npm install @fullcalendar/core @fullcalendar/react @fullcalendar/daygrid @fullcalendar/interaction

이번 구현에서는 월간 달력이 필요했기 때문에 daygrid 플러그인을 사용했고, 날짜 클릭 기능을 위해 interaction 플러그인도 함께 설치했다.

core : 캘린더 자체의 기본 동작 기반 react : React 컴포넌트로 화면에 렌더 daygrid : 월간 달력 UI 표시(initialView="dayGridMonth) interaction : 날짜 클릭, 이벤트 클릭 같은 동작 연결

2) 기본 import

import FullCalendar from "@fullcalendar/react";
import dayGridPlugin from "@fullcalendar/daygrid";
import interactionPlugin, {
  type DateClickArg,
} from "@fullcalendar/interaction";
import koLocale from "@fullcalendar/core/locales/ko";
import type { EventClickArg, EventInput } from "@fullcalendar/core";

• FullCalendar : React에서 실제로 렌더링할 캘린더 컴포넌트
• dayGridPlugin : 월간 달력처럼 칸 형태로 보여주는 뷰
• interactionPlugin : 날짜 클릭, 선택 같은 상호작용 처리
• koLocale : 달력을 한국어로 표시하기 위한 locale
• EventInput, EventClickArg, DateClickArg : 이벤트 데이터와 클릭 핸들러 타입 정의

3) 기본 렌더링 방식

FullCalendar는 <FullCalendar /> 컴포넌트 옵션을 props 형태로 전달해 사용하는 구조다.

<FullCalendar
  plugins={[dayGridPlugin, interactionPlugin]}
  locales={[koLocale]}
  locale="ko"
  initialView="dayGridMonth"
  height="auto"
  events={events}
  dateClick={handleDateClick}
  eventClick={handleEventClick}
  headerToolbar={{
    left: "prev,next today",
    center: "title",
    right: "",
  }}
  buttonText={{
    today: "오늘",
  }}
  dayMaxEvents={2}
  fixedWeekCount={false}
/>

여기서 자주 사용한 옵션은 다음과 같다.

• plugins : 사용할 플러그인 등록
• initialView : 처음 보여줄 달력 형태 지정 (dayGridMonth)
• events : 달력에 표시할 이벤트 데이터 배열
• dateClick : 날짜 칸 클릭 시 실행할 함수
• eventClick : 일정 클릭 시 실행할 함수
• headerToolbar : 상단 이전/다음/오늘 버튼과 제목 배치
• dayMaxEvents : 한 날짜에 일정이 많을 때 최대 몇 개까지 보여줄지 설정
• fixedWeekCount : 항상 6주를 채우지 않고 실제 주 수만큼만 렌더링

즉, FullCalendar는 정적인 달력 컴포넌트가 아니라 옵션과 데이터로 동작을 조합하는 캘린더 엔진에 가깝다.

4) 날짜 클릭과 이벤트 클릭은 어떻게 쓰는가

이번 구현에서는 클릭 이벤트를 두 가지로 나눠서 사용했다.

날짜 클릭

날짜 칸 제체를 클릭하면, 그 날짜를 선택된 날짜 상태로 저장하고 리스트에서는 그 날짜의 예약만 다시 보여주도록 했다.

const handleDateClick = (arg: DateClickArg) => {
  const clickedDate = arg.dateStr;
  onSelectDate(selectedDate === clickedDate ? null : clickedDate);
};

즉, 날짜를 한 번 클릭하면 해당 날짜로 필터링되고, 같은 날짜를 다시 클릭하면 선택이 해제되도록 만들었다.

이벤트 클릭

달력 안에 표시된 일정 이벤트를 클릭하면 기존에 카드 클릭 시 사용하던 예약 상세 모달을 그대로 열도록 연결했다.

const handleEventClick = (arg: EventClickArg) => {
  const reservationId = Number(arg.event.extendedProps.reservationId);

  if (Number.isNaN(reservationId)) return;

  onClickEvent(reservationId);
};

여기서 reservationId는 이벤트 생성 시 extendedProps에 넣어둔 값을 다시 꺼낸 것이다.

해당 방식 덕분에 두 경우 모두 같은 예약 상세 흐름을 재사용할 수 있었다.

5) 예약 리스트와 달력 연결

이번 구현에서 가장 중요했던 건 달력과 리스트가 같은 데이터를 봐야 한다는 점이었다. 그래서 예약 데이터는 아래 순서로 가공했다.

1. viewItems : 탭, 날짜 범위 검색, 정렬까지 반영된 최종 예약 목록
2. calendarEvents : viewItems를 FullCalendar용 이벤트 배열로 변환한 값
3. visibleItems : 사용자가 달력에서 특정 날짜를 선택했을 때 - 그 날짜에 해당하는 예약만 다시 걸러낸 목록

예시 코드

const viewItems = useMemo(() => {
  // 탭 + 검색 + 정렬 적용
  return items;
}, [...]);

const calendarEvents = useMemo(() => {
  return toReservationCalendarEvents(viewItems);
}, [viewItems]);

const visibleItems = useMemo(() => {
  if (!selectedDate) return viewItems;

  return viewItems.filter(
    (item) =>
      pickYmdFromLocalDateTime(item.timeSlot.startDt) === selectedDate,
  );
}, [viewItems, selectedDate]);

이렇게 구성하면

• 달력은 월 전체 예약 맥락을 보여주고
• 리스트는 선택된 날짜 기준으로 더 좁게 보여줄 수 있다

즉, 같은 데이터를 두 방식으로 보여주되 역할은 다르게 나누는 구조가 된다.

4. 해당 프로젝트 화면에서 FullCalendar가 맡은 역할

FullCalendar는 단순히 달력 UI만 담당한 것이 아니라, 예약 관리 화면 안에서 다음 역할을 맡도록 설계했다.

• 현재 탭/검색 조건에 맞는 예약을 달력에 이벤트로 표시
• 날짜 클릭 시 해당 날짜의 예약만 리스트에 표시
• 이벤트 클릭 시 기존 예약 상세 모달 열기
• 달력 접기/펼치기 상태 제어

즉, 기존 리스트형 화면에 달력을 하나 더 붙인 것이 아니라 같은 예약 데이터를 다른 방식으로 시각화하는 보조 뷰로 사용했다.

5. 컴포넌트 구조를 어떻게 나눴는가

처음부터 페이지 안에 FullCalendar를 직접 넣기보다, 달력 섹션을 별도 컴포넌트로 분리했다.

분리한 이유

예약 관리 페이지는 이미 다음 책임을 가지고 있었다.

• 탭 상태 관리
• 검색 조건 관리
• 예약 리스트 조회
• 예약 상세 모달 상태 관리

여기에 달력까지 직접 넣으면 페이지 컴포넌트가 너무 비대해지기 때문에 역할을 나눴다. 심지어 유저와 아티스트의 페이지가 나눠져있어 동일한 컴포넌트를 사용해야했었기 때문에 분리는 더욱 필요했다.

구조

• ArtistReservationPage / MyReservationPage

  • 탭, 검색, 선택 날짜, 모달 상태 관리
  • 예약 데이터를 필터링/정렬
  • 달력에 넘길 이벤트 배열 생성

• ReservationCalendarSection

  • FullCalendar 렌더링
  • 날짜 클릭, 이벤트 클릭 전달
  • 접기/펼치기 UI 담당

• reservationCalendarUtils

  • 예약 DTO를 FullCalendar 이벤트 형식으로 변환

Page : 상태와 데이터 가공에 집중 Component : 표현과 인터랙션에 집중

6. 예약 데이터를 달력 이벤트로 바꾸는 과정

FullCalendar는 이벤트 데이터를 다음과 같은 형태로 받는다.

{
  id: "1",
  title: "확정 · 트럼펫 레슨",
  start: "2026-04-15T10:00:00",
  end: "2026-04-15T11:00:00"
}

하지만 내가 갖고 있던 예약 데이터는 예약 도메인 중심 DTO였다. 그래서 예약 응답을 FullCalendar 이벤트 형식으로 변환하는 유틸을 만들었다.

변환 시 사용한 값들은 기본적으로 예약 아이디, 상태, 레슨 제목, 시작일, 종료일이었고, 기존 상태칩 UI에서 쓰던 상수와 컬러그룹을 재사용해 달력 이벤트 색상도 예약 상태와 일관되게 맞췄다.

7. 구현 중 타입 문제

처음에는 캘린더 유틸의 인자 타입을 ArtistReservationSummaryResp[] 정도로 고정해두었다. 하지만 유저 예약화면에는 쓰이지 않는 타입이라 타입 에러가 발생했다.

문제는 캘린더가 실제로 필요한 필드는 많지 않은데, 유틸 설계를 특정 화면의 DTO에 너무 치우쳐 설계되었다는 점이다. 그래서 상단에 언급한 값들을 들고가며 캘린더에 필요한 최소 공통 필드만 가지는 타입으로 유틸 입력을 일반화시켰다.

이 과정을 통해 "화면용 DTO를 그대로 유틸에 사용"하는 것보다 "실제로 필요한 최소 구조를 기준으로 타입을 설계하는 것"이 공통 요소에서는 더 낫다는것을 느꼈다.

8. 날짜 클릭과 이벤트 클릭은 어떻게 연결했는가

이번 구현에서 FullCalendar의 인터렉션은 두 가지였다.

1) 날짜 클릭

날짜를 클릭하면 selectedDate 상태를 바꾸고, 리스트에서는 이 날짜와 일치하는 예약만 다시 보여주도록 했다.

즉,

• 달력 = 월 전체 일정 맥락 제공
• 리스트 = 선택한 날짜 기준 상세 목록 제공

이런 역할 분리가 되도록 구성했다.

2) 이벤트 클릭

달력에 표시된 예약 이벤트를 클릭하면 기존에 카드 클릭 시 열리던 예약 상세 모달을 그대로 재사용했다.

이벤트의 extendeedProps 에 reservationId를 넣어두고, 이 값을 이용해 기존 예약 상세 흐름과 연결했다.

이렇게 하니 카드에서 보든 달력에서 보든 결국 같은 상세 모달로 진입하게 되어 UX가 자연스러워 졌다.

마무리

이번 작업은 단순히 달력을 하나 붙이는 작업이라기보다, 기존 예약 리스트를 시간 흐름으로 다시 보여주는 구조를 만드는 과정에 가까웠다. FullCalendar를 처음 적용해보면서 생각보다 고려할 부분이 많았지만, 그 과정 덕분에 데이터 가공 기준과 공통 컴포넌트 분리에 대해 더 많이 정리해볼 수 있었다. 다음에는 이번 흐름을 바탕으로 특정 레슨 일정 강조나 시간 충돌 확인 같은 기능도 붙여보려고 한다.

Next.js를 사용하게 된 이유

현재 진행하려는 프로젝트에 대해 조금 고민이 있었다.

1. 일단, 새로운걸 접해보고 싶었다. 음악 전공에서 디자인 업무, 그리고 그 시작점에서 개발 공부까지 1년째. 개발과는 너무나도 머나먼 여정을 걸어온 나에게 빡센 공부였지만, 계속 사용하던 프레임워크만 사용할 수는 없었다.

2. 가성비 (?) 원래 백엔드를 GO로, 프론트는 원래 하던대로 React - ts를 사용할 예정이었지만 따지고보면 그렇게 큰 프로젝트는 아니라는 생각에 Next.js로 퉁치는게 가성비가 좋다고 느꼈다. 가성비가 좋다는것은, 백엔드를 전혀 모르는 언어로 구성하고 아는것을 붙이는것보다, 차라리 아는것을 응용하고 현업에서 요구하는 스택을 쌓는게 더 낫지 않느냐의 문제였다.

React와 Next.js는 뭐가 다른가

React

React는 UI를 컴포넌트로 만드는 라이브러리다.

예를 들면:

• 버튼 컴포넌트
• 카드 컴포넌트
• 화면 컴포넌트

이런 식으로 UI를 조립하는 도구라고 보면 된다.

Next.js

Next.js는 React를 기반으로 페이지 구조와 앱 기능을 더 쉽게 관리하게 해주는 프레임 워크다.

즉 비유하면:

• React = 부품 만들기
• Next.js = 부품으로 집 짓는 규칙까지 포함한 설계 도구

그래서 Next.js 안에서는 React 컴포넌트를 그대로 쓰지만,(jsx, tsx) 추가로 "페이지는 어디에 두는지", "URL은 어떻게 생기는지" 같은 규칙이 생긴다.\

오늘 한 일

1. Next 프로젝트 생성 처음에 npx create-next-app@latest 프로젝트 명 으로 프로젝트를 만들었다.

이 과정에서:

• React
• Next
• TypeScript
• Tailwind
• ESLint

같은 기본 세팅이 같이 설치된다. 즉, 그냥 빈 폴더를 만든 게 아니라 Next.js 개발을 시작할 수 있는 기본 환경을 만들었다.

2. 개발 서버 실행 기존 React 프로젝트와 동일하게 npm run dev 로 서버를 실행했고, 이걸 켜면 localhost:3000 에서 지금 만든 앱을 바로 볼 수 있다.

3. app 폴더 확인 Next.js App Router를 쓰면 app 폴더가 핵심이 된다.

여기서 중요한건:

• app/page.tsx
• app/plan/page.tsx
• app/summary/page.tsx

같이 폴더 구조 자체가 URL 경로가 된다는 점이다. 이게 React Router랑 다른 핵심 포인트 중 하나다.

4. features 폴더 구성 그 다음에 features 폴더를 만들었다.

이건 Next.js가 강제하는 구조는 아니고, 내가 프로젝트를 보기 좋게 정리하기 위해 직접 만든 구조다.

예를 들면:

• features/landing
• features/plan
• features/summary
• features/pdf

이렇게 기능 단위로 나누면, 나중에 파일이 많아져도 덜 헷갈린다.

Next.js에서 제일 중요한 개념: page.tsx

page는 무엇인가 해당 경로에서 실제로 보여줄 페이지 컴포넌트 파일이다.

예를 들어

app/
  page.tsx
  plan/
    page.tsx
  summary/
    page.tsx

이 구조는 URL로 보면 이렇게 된다.

• app/page.tsx → /
• app/plan/page.tsx → /plan
• app/summary/page.tsx → /summary

즉 폴더 이름이 URL이 되고, 그 안의 page.tsx 가 그 화면의 진입점이 되는것이다.

→ 결국은 폴더가 경로다 정도로 이해하고 넘어갔다.

그럼 page.tsx 안에 모든 걸 다 쓰나?

그렇진 않다.

page.tsx는 페이지의 입구 역할만 하게 두었다. 실제 화면 내용은 features폴더에 분리해서 넣는게 깔끔해보였다.

예를 들어 app/page.tsx

import LandingPage from "@/features/landing/components/LandingPage";
// @/ = 일종의 alias. 상대 경로를 적지 않아도 루트부터 시작하는 깔끔한 경로 표기

export default function Page() {
  return <LandingPage />;
}

여기서 실제 랜딩 화면은 LandingPage.tsx 가 담당한다.

즉 역할 분리는 이렇다.

• app/.../page.tsx = URL 연결용
• features/... = 실제 화면 구현

이렇게 분리하면 나중에 파일이 커져도 나름 뭐...OK

이번에 만든 폴더 구조에 대해서

app/
  page.tsx
  plan/page.tsx
  summary/page.tsx

features/
  landing/components/
  odyssey-plan/components/
  plan/model/
  plan/store/
  summary/components/
  summary/model/
  pdf/components/
  pdf/model/

app

라우트 진입점. 즉 URL 경로 담당.

features

기능별 묶음. 랜딩, 플랜 작성, 요약, PDF 같은 실제 도메인 단위.

componemts

화면 조각들 ex: LandingPage, SummaryPage, 카드, 버튼, 섹션 등.

model

타입, 상수, 계산 함수(Utils) 같은 것들.

store

zustand 같은 상태 관리 파일.

즉 한마디로 하면: app은 길 안내, features는 실제 방 구조라고 보면 된다.

Next.js를 처음 접하며 이해한 점

처음에는 page.tsx 가 여러개 생기고, app 폴더와 features 폴더가 도잇에 존재하는 구조가 낯설었다. React에서는 보통 라우팅을 직접 설정하고, 컴포넌트 파일을 자유롭게 배치하는 경우가 많았기 때문에 "왜 같은 이름의 파일이 여러 개 인가"라는 혼란이 있었다.

하지만 App Router 구조를 이해하고 나니 흐름이 정리됐다.

• app 폴더는 URL과 직접 연결되는 라우트 진입점
• page.tsx 는 각 경로에서 실제로 렌더링될 페이지
• features 폴더는 기능 단위로 화면과 로직을 정리하기 위한 사용자 정의 구조

즉 app은 경로를 연결하는 입구이고, features 는 실제 페이지 내용을 구성하는 공간이라는 점을 이해하면서 구조가 명확하게 보이기 시작했다.

1. 도입

검색 화면을 만들다 보면 생각보다 상태가 단순하지 않다. 처음에는 useState 로 검색어와 필터만 관리하면 될 것처럼 보이지만, 조건이 늘어날수록 문제가 생긴다.

예를들어 이런 것들이다.

• 사용자가 필터를 바꾸는 중인데 아직 검색은 실행하지 않은 상태
• 검색 결과에 실제 반영된 조건과 화면에 임시로 선택된 조건이 다른 상태
• 새로고침하거나 뒤로가기를 했을 때 검색 조건이 유지되어야 하는 문제
• 서버에서 받아온 검색 결과는 어떤 상태로 봐야 하는지에 대한 문제

이번 글에서는 개인 프로젝트에서 검색 기능을 구연하며 검색 조건, URL 상태, 서버 상태를 각각 어떻게 나눠서 관리했는지 정해보려 한다.

2. 왜 상태를 나눠서 생각해야 했을까

처음에는 검색 조건을 모두 하나의 state 로 관리하면 된다고 생각했다. 하지만 실제로 구현하다 보니 이 방식은 금방 한계가 드러났다.

검색 화면에는 크게 세 종류의 상태가 섞여 있었다.

1. 사용자가 지금 입력/선택 중인 값(Draft)
2. 실제로 검색에 적용된 값
3. 서버에서 받아온 검색 결과

이 셋을 하나로 묶어버리면 문제가 생긴다.

예를 들어 사용자가 드롭다운에서 악기를 이것저것 선택하는 순간마다 바로 서버 요청이 나가면 UX가 산만해진다.

반대로 적용 버튼을 두면, 지금 화면에 보이는 선택값과 실제 결과를 만든 조건이 달라질 수 있다,

즉, 검색 화면은 단순한 입력 폼이 아니라 "편집 중인 조건" 과 "적용된 조건" 이 공존하는 구조였다.

그래서 나는 상태를 다음처럼 분리했다.

• draft state: 사용자가 현재 수정 중인 검색 조건
• applied state: 실제 검색 요청에 반영된 조건
• server state: TanStack Query가 관리하는 검색 결과
• URL state: 새로고침, 공유, 뒤로가기까지 고려한 검색 조건의 표현

3. 어떤 상태를 어디에 둘지 기준 세우기

핵심은 "이 값은 누구의 책임인가?"를 먼저 정하는것이다.

3-1. draft state: 아직 확정되지 않은 사용자의 입력

검색창의 입력값, 드롭다운에서 선택 중인 값, 날짜 범위 등은 사용자가 아직 조정 중일 수 있다.

이 값들은 바로 서버 요청으로 이어질 필요가 없다. 그래서 로컬 상태로 두고, 사용자가 검색 버튼을 누르거나 적용 액션을 했을 때만 실제 검색 조건으로 반영되도록 했다.

이하 예시

const [draft, setDraft] = useState({
  keyword: "",
  instrumentCategory: "ALL",
  instIds: [],
  styleTagIds: [],
});

이 draft는 말 그대로 편집 중인 임시 상태다.

3-2. applied state: 실제 검색 요청 기준

검색 버튼을 눌렀을 때만 draft를 applied로 복사한다. 이 applied state가 실제 검색 결과를 만들 기준이 된다.

const [applied, setApplied] = useState({
  keyword: "",
  instrumentCategory: "ALL",
  instIds: [],
  styleTagIds: [],
});

const onSearch = () => {
  setApplied(draft);
};

이렇게 하면 사용자가 조건을 바꾸는 동안에는 결과가 흔들리지 않고, 원하는 시점에서만 검색을 다시 실행할 수 있다.

3-3. server state: 검색 결과는 TanStack Query에게 맡기기

검색 결과는 프론트 로컬 상태가 아니라 서버 상태다. 직접useState로 들고 있을 필요가 없다.

이런 데이터는 TanStack Query가 더 잘한다.

• 캐싱
• 로딩/에러 상태 관리
• 쿼리 키 기반 재요청
• 동일 조건 재방문 시 데이터 재사용

예를 들어 검색 결과는 applied state를 기준으로 쿼리 키를 구성할 수 있다.

const { data, isLoading, isError } = useQuery({
  queryKey: ["lessonSearch", applied],
  queryFn: () => getLessonsReq(applied),
});

이렇게 하면 "무슨 조건으로 조회한 결과인지"가 queryKey에 그대로 남는다. 즉, 결과 데이터의 책임은 TanStack Query가 가지게 된다.

4. URL까지 관리해야 했던 이유

여기서 끝내면 아쉬운 문제가 남는다. 사실 해당 글을 작성하게 된 가장 큰 요인이다.

검색 조건을 로컬 상태에만 두면 이런 일이 발생한다.

• 새로고침하면 조건이 사라진다
• 뒤로가기를 하면 이전 검색 상태가 복원되지 않는다
• 링크를 공유해도 같은 검색 결과를 재현할 수 없다

검색 페이지라면 이런 UX는 피할 수 있으면 피해야 한다고 생각한다. 사용자는 검색 결과를 하나의 "상태"가 아니라 거의 "페이지"처럼 인식하기 때문이다.

그래서 적용된 검색 조건은 URL 에도 반영하도록 했다.

예시

?keyword=flute&instrumentCategory=WOODWIND&instIds=1&instIds=2

이렇게 하면 URL만 봐도 현재 어떤 조건으로 검색 중인지 알 수 있고, 브라우저 히스토리와도 자연스럽게 연결된다.

5. draft는 로컬에, applied는 URL에 두는 구조

여기서 중요한 포인트는 모든 상태를 URL에 넣지 않았다는 점이다.

사용자가 드롭다운을 열고 이것저것 만지는 순간마다 URL이 계속 바뀌면 히스토리도 지저분해지고 UX도 좋지 않다.

그래서 기준을 이렇게 잡았다.

• draft state: 컴포넌트 로컬 상태
• applied state: URL과 동기화
• server state: Tanstack Query

즉, 사용자가 "검색 실행"을 한 시점의 조건만 URL에 반영했다.

흐름은 대략 이렇다.

1. 사용자가 draft를 수정한다
2. 검색 버튼을 누른다
3. draft를 applied로 확정한다
4. applied를 URLSearchParams로 직렬화한다
5. TanStack Query가 applied 기준으로 서버 요청을 보낸다

이 구조 덕분에 입력 중 상태와 적용된 상태를 깔끔하게 분리할 수 있었다.

6. 배열 필터는 특히 URL 설계가 중요했다

문자열 검색이 하나만 다루면 쉬운데, 실제 검색에서는 배열 조건이 꼭 등장한다.

내 경우에는 이런 값들이 있었다.

• instIds: number[]
• styleTagIds: number[]

이런 배열 조건은 URL에 어떻게 표현할지부터 정해야 한다. 나는 반복 키 방식으로 맞췄다.

instIds=1&instIds=2&instIds=3

이 방식은 프론트에서도 직관적이고, 백엔드에서 @RequestParam List<Long> 혹은 비슷한 구조로 받기도 편하다.

예를들어 qs 같은 라이브러리를 사용하면 이런 식으로 다룰 수 있다.

qs.stringify(
  { instIds: [1, 2, 3] },
  { arrayFormat: "repeat" }
);

배열 필터를 다루는 순간 URL 설계는 부가 기능이 아닌 검색 API와 프론트 상태 구조를 연결하는 인터페이스가 된다.

7. 이번 구조에서 얻은 장점

1. 검색 실행 시점이 명확해졌다 사용자가 입력하는 순간마다 서버 요청이 나가지 않고, 적용된 조건만 기준이 되니 동작이 안정적이었다.

2. 새로고침/뒤로가기/공유에 대응할 수 있었다 검색 조건이 URL에 남기 때문에 브라우저 히스토리와 사용 경험이 자연스럽게 연결되었다.

3. 상태의 책임이 분리되었다

• 편집 중인 값은 로컬 상태
• 적용된 조건은 URL
• 결과 데이터는 TanStack Query

이 구분 덕분에 코드의 역할도 선명해졌다.

마무리

검색 화면은 생각보다 상태가 많은 UI다. 특히 필터가 여러 개 붙고, URL 공유와 브라우저 히스토리까지 고려하기 시작하면 단순히 useState 몇 개로 끝나지 않는다.

이번 구현에서 내가 정리한 기준은

• 사용자가 편집 중인 값은 로컬 상태
• 실제로 검색에 반영된 값은 URL과 동기화
• 검색 결과는 TanStack Query가 관리

결국 중요한 건 상태를 많이 쓰느냐 적게 쓰느냐가 아니라, 각 상태의 책임을 어디까지로 볼 것인가였다.

검색 기능은 이전에도 구현해봤지만, 막상 구조를 제대로 생각해서 나누려고 하니 지저분해지는 영역이라는 생각이 들었다. 그래서 처음부터 역할을 나눠두고 상황을 고려하는것이 중요하다고 느껴졌다.

qs란,

객체(object)를 query string으로 변환하거나, query string 을 다시 객체로 파싱(parse)하는 라이브러리다.

쉽게 말하면 프론트에서 이렇게 관리하는 데이터를

{
  keyword: "전공",
  styleTagIds: [1, 2],
  instIds: [3, 7],
}

이런 URL 쿼리 형태로 바꿔주는 역할을 한다.

keyword=%ED%94%8C%EB%A3%BB&styleTagIds=1&styleTagIds=2&instIds=3&instIds=7

React에서 검색 필터를 구현하다 보면 검색 조건은 보통 객체 형태로 관리하지만, GET 요청을 보낼 때는 결국 query string 형태로 바꿔야한다.

처음에느 단순해 보이지만, 필터가 많아지고 배열 형태의 값이 생기면 직접 조립하는 코드가 지저분해진다.

qs를 쓰기 전: 직접 query string을 조립하던 코드(예시)

처음에는 URLSearchParams 로도 충분하다고 생각했다.

export const searchLessonReq = async (params: {
  keyword?: string;
  mode?: string;
  styleTagIds?: number[];
  instCategory?: string;
  instIds?: number[];
  from?: string;
  to?: string;
  daysOfWeek?: number[];
  timeParts?: string[];
}) => {
  const searchParams = new URLSearchParams();

  if (params.keyword) searchParams.append("keyword", params.keyword);
  if (params.mode) searchParams.append("mode", params.mode);
  if (params.instCategory) {
    searchParams.append("instCategory", params.instCategory);
  }
  if (params.from) searchParams.append("from", params.from);
  if (params.to) searchParams.append("to", params.to);

  params.styleTagIds?.forEach((id) => {
    searchParams.append("styleTagIds", String(id));
  });

  params.instIds?.forEach((id) => {
    searchParams.append("instIds", String(id));
  });

  params.daysOfWeek?.forEach((day) => {
    searchParams.append("daysOfWeek", String(day));
  });

  params.timeParts?.forEach((tp) => {
    searchParams.append("timeParts", tp);
  });

  return axios.get(`/api/lessons?${searchParams.toString()}`);
};

동작은 하지만,

• 조건이 하나 추가될 때마다 append() 를 직접 써야 한다
• 배열 필드는 전부 foreach 로 반복해야 한다
• 빈 값, 없는 값 처리까지 계속 신경 써야 한다
• 필터가 많아질수록 코드가 길어진다
• 결국 "검색 요청"보다 "문자열 조립" 코드가 더 눈에 들어온다

즉, 비즈니스 로직보다 직렬화 코드가 존재감이 더 커지는 상황이 발생한다.

qs 적용 후(예시)

해당 문제를 줄이기 위해 qs 를 도입했다.

npm i qs

적용 후 코드는 이렇게 바뀌었다.

export const searchLessonReq = async (params: {
  keyword?: string;
  mode?: string;
  styleTagIds?: number[];
  instCategory?: string;
  instIds?: number[];
  from?: string;
  to?: string;
  daysOfWeek?: number[];
  timeParts?: string[];
}) => {
  const query = qs.stringify(params, {
    arrayFormat: "repeat",
    skipNulls: true,
  });

  return axios.get(`/api/lessons?${query}`);
};

훨씬 간단해졌다.

이제는 query string을 직접 조립하지 않고, 검색 조건 객체를 만들고 qs.stringify()에 넘기는 것만으로 끝낸다.

이렇게 되면 조건이 늘어나도 params 만 관리하면 되고, 직렬화 방식은 라이브러리에 맡길 수 있다.

arrayFormat: "repeat" 를 사용한 이유

배열 파라미터가 많은 검색 API를 구현한다고 가정하자.

예를들어 styleTagIds: [1, 2] 를 query string으로 만들 때, 배열은 여러 방식으로 표현할 수 있다.

repat 방식

styleTagIds=1&styleTagIds=2

braket 방식

styleTagIds[]=1&styleTagIds[]=2

comma 방식

styleTagIds=1,2

이번에는 이 중에서 repeat 방식을 사용했다.

qs.stringify(
  { styleTagIds: [1, 2] },
  { arrayFormat: "repeat" }
);

해당 방식을 선택한 이유는 Spring 백엔드에서 다음과 같이 받고 있었기 때문이다.

@RequestParam(required = false) List<Long> styleTagIds
@RequestParam(required = false) List<Long> instIds
@RequestParam(required = false) List<Integer> daysOfWeek
@RequestParam(required = false) List<String> timeParts

즉, 프론트에서 같은 key를 반복하는 형태로 보내면 Spring이 List<T> 로 자연스럽게 바인딩할 수 있다.

skipNulls: true 도 같이 유용했다

검색 필터는 항상 모든 값이 다 들어오지 않는다.

예를 들면 이런 경우가 있다.

const params = {
  keyword: undefined,
  mode: undefined,
  styleTagIds: [1, 2],
  instIds: undefined,
};

이런 상태에서 필요 없는 값까지 query string에 포함 시키고 싶지는 않았다.

그래서 skipNulls: true 옵션도 같이 사용했다.

const query = qs.stringify(params, {
  arrayFormat: "repeat",
  skipNulls: true,
});

이렇게 하면 null 이나 undefined인 값은 제외되고, 실제로 검색에 들어온 값만 query string에 포함된다.

결과적으로 요청 자체가 더 깔끔해진다.

query-string & qs

비슷한 역할을 하는 라이브러리로 query-string도 있다.

둘 다 객체와 query string을 다룰 수 있지만, 사용감은 조금 다르다.

query-string

• 비교적 가볍다
• 프론트에서 URL 쿼리를 읽고 쓰기에 깔끔한 편이다
• 단순한 query string 처리에는 충분히 편하다

qs

• 배열 직렬화 옵션이 더 유연하다
• 중첩 객체나 복잡한 구조 대응력이 더 좋다
• 백엔드와 맞물리는 직렬화 제어에 더 강하다

이번 경우에는 단순히 주소창 쿼리를 다루는 것보다 배열 파라미터를 Spring 형식에 맞게 안정적으로 보내는 것이 더 중요했기 때문에 본인은 qs를 션택했다.

정리

이번에 qs를 도입하면서 좋아진 점은 분명했다.

• query string 조립 코드가 짧아졌다
• 배열 필드를 직접 반복문으로 처리하지 않아도 된다
• 검색 조건이 늘어나도 params 객체만 관리하면 된다
• Spring 백엔드와 맞는 형태로 배열 파라미터를 보낼 수 있다
• null, undifined 값도 깔끔하게 제외할 수 있다

검색 필터가 많아질수록 문제는 조건관리보다 그 조건을 query string으로 어떻게 직렬화할 것인가 쪽에서 더 자주 터진다.

이번에는 qs를 통해 그 부분을 훨씬 단순하게 정리할 수 있었다.

마무리

처음엔 URLSearchParams로도 충분해 보였다. 하지만 배열 필터가 늘어나고, 백엔드와 맞는 형태까지 고려해야 하니 코드가 금방 길어졌다.

qs를 도입한 뒤에는 직접 문자열을 조립하는 대신 객첸 중심으로 조건을 관리하고, 직렬화는 라이브러리에 맡기는 구조로 정리할 수 있었다.

QueryDSL을 적용하려고 했지만, 가장 먼저 막힌 부분은 QUser 같은 Q클래스가 보이지 않는 문제였다.

예를 들어 RepositoryImpl 에서 해당 코드를 쓰고 싶은데

QUser user = QUser.user;

IDE에서는 QUser 자체를 찾지 못했다.

처음에는 QueryDSL 문법 문제라고 생각했지만, 실제 원인은 Q 클래스 생성 자체가 안 된 것이었다.

원인 정리

문제를 추적해보니, 단순히 import 문제가 아니라 여러 설정이 겹쳐있었다.

1. 의존성 필요

   implementation 'com.querydsl:querydsl-jpa:5.1.0:jakarta'
   annotationProcessor 'com.querydsl:querydsl-apt:5.1.0:jakarta'
   annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
   annotationProcessor 'jakarta.persistence:jakarta.persistence-api'

2. Config 필요

@Configuration
public class QueryDslConfig {

    @PersistenceContext
    private EntityManager em;

    @Bean
    public JPAQueryFactory jpaQueryFactory() {
        return new JPAQueryFactory(em);
    }
}

3. 로컬 Java 환경변수 문제 가장 크게 시간을 잡아먹은 건 사실 로컬 Java 환경변수 문제였다.

Gradle 실행 시 아래와 같은 에러가 발생했다.

• JAVA_HOME is not set
• java command could not be found

즉, gradlew 는 실행됐지만, Java를 찾지 못하는 상태였다.

해결 과정

1. InteliJ에서 실제 JDK 경로 확인

2. JAVA_HOME 설정 사용자 환경 변수에 값을 추가했다

3. Path 설정 처음에는 %JAVA_HOME%\bin을 넣었지만, 환경에 따라 문자열 그대로 남아 Java를 찾지 못하는 문제가 있었다. 최종적으로는 절대경로를 직접 넣는 방식으로 해결했다.

4. Gradle 빌드 재실행 환경변수 설정 후 다음 명령으로 컴파일을 다시 수행했다.

   .\gradlew.bat clean compileJava --info

   그 결과 Q 클래스가 생성되었고, build/generated/sources/annotationProcessor/java/main 경로 아래에서 확인할 수 있었다.

느낀점

처음에는 QueryDSL 문법이 문제라고 생각했지만, 실제로는 다음 세 가지가 얽혀 있었다.

• Gradle 의존성 설정
• annotation processor 동작 여부
• Java 환경변수 설정

그 결과 Q 클래스가 생성되었고, build/generated/sources/annotationProcessor/java/main 경로 아래에서 확인할 수 있었다.

정리

이번 문제의 핵심은 QueryDSL Q 클래스가 자동 생성되지 않았다는 점이었다. 원인은 annotation processor 설정과 Java 환경변수 문제였고, Gradle 설정 수정 + JAVA_HOME/Path 설정 + 재빌드를 통해 해결할 수 있었다.

결과적으로 QueryDSL 자체보다도, 개발 환경과 빌드 시스템을 정확히 이해하는 과정이 더 중요하다는 걸 많이 배운 작업이었다.

QueryDSL은 JPA에서 문자열 기반 JPQL을 길게 작성하는 대신, Q타입을 이용해 자바 코드로 쿼리를 구성할 수 있도록 도와주는 라이브러리다.

즉, 쿼리를 문자열로 직접 조립하는 대신 코드로 안전하게 조건식을 만들고 조합할 수 있다.

기존 JPQL은 레퍼지토리에 이런식으로 문자열 쿼리를 작성한다.

@Query("""
select ap
from ArtistProfile ap
where (:applyKeyword = false or ...)
  and (:applyInstIds = false or ...)
""")

반면 QueryDSL은 조건을 코드로 조립한다.

.where(
    keywordCondition(req.keyword(), user, artistProfile),
    instCategoryCondition(req.instCategory(), artistInstrument, artistProfile),
    instIdsCondition(req.instIds(), artistInstrument, artistProfile),
    styleTagIdsCondition(req.styleTagIds(), artistStyleMap, artistProfile)
)

이렇게 하면 어떤 조건이 붙는지가 메서드 이름만으로도 드러난다.

왜 QueryDSL 사용을 고려했는가

검색 자체가 동적 검색이라는 점이 핵심이엇다. 모든 사용자가 같은 조건으로 검색하는 것이 아니라, 어떤 사용자는 키워드만 넣고, 어떤 사용자는 조건1, 조건2까지 함께 선택할 수 있었다.

즉, 조건이 고정된 조회가 아니라 있을 수도 있고 없을 수도 있는 조건이 많았다.

• keyword가 있으면 이름/전공명 검색
• instCategory가 있으면 해당 카테고리 악기 보유 여부 검색
• instIds가 있으면 해당 악기 보유 여부 검색
• styleTagIds가 있으면 해당 스타일 태그 보유 여부 검색

이런 경우 JPQL은 결국 문자열 안에 여러 분기 조건과 boolean 플래그가 들어가게 된다. 반면 QueryDSL은 조건을 메서드로 나눠서, 있으면 적용하고 없으면 제외하는 방식으로 구성할 수 있다.

그래서 검색 조건이 계속 늘어날 가능성이 있는 구조에서 유지보수가 가능한 형태를 만드는것에 더 가까운 선택을 한것이다.

사용 준비하기

QueryDSL은 먼저 몇 가지 준비가 필요하다.

의존성 추가

Gradle 기준으로 QueryDSL 관련 의존성을 추가했다.

implementation "com.querydsl:querydsl-jpa:5.0.0:jakarta"
annotationProcessor "com.querydsl:querydsl-apt:5.0.0:jakarta"
annotationProcessor "jakarta.annotation:jakarta.annotation-api"
annotationProcessor "jakarta.persistence:jakarta.persistence-api"

Q타입 생성 설정

QueryDSL은 엔티티를 기반으로 QUser , QArtistProfile 같은 Q타입을 생성해서 사용한다. 즉, 단순 라이브러리 추가만으로 끝나는 게 아니라 빌드 시 annotation processor가 Q클래스를 생성할 수 있도록 설정해야 했다.

이후 빌드를 수행하면 build/generated/... 아래에 Q타입이 생성되고, 코드에서는 이런 식으로 사용할 수 있다.

QArtistProfile artistProfile = QArtistProfile.artistProfile;
QUser user = QUser.user;

JPAQueryFactory 빈 등록

QueryDSL 쿼리를 작성하려면 JPAQueryFactory 가 필요해서 설정 클래스를 통해 Bean으로 등록했다.

@Configuration
public class QueryDslConfig {

    @PersistenceContext
    private EntityManager em;

    @Bean
    public JPAQueryFactory jpaQueryFactory() {
        return new JPAQueryFactory(em);
    }
}

Custom Repository 분리

기본 JpaRepository 만으로는 QueryDSL 커스텀 구현을 담기 어려워서, 검색 메서드는 별도의 Custom Repository 인터페이스와 구현 글래스로 분리했다.

예를 들어 구조는 다음처럼 잡았다.

• ArtistProfileRepository
• ArtistProfileRepositoryCustom
• ArtistProfileRepositoryImpl 해당 방식으로 분리하여 단순 CRUD와 검색용 동적 쿼리의 역할이 섞이지 않아 오히려 더 명확했다.

QueryDSL의 장점

이번 구현에서 체감한 장점은 다음과 같았다.

1. 동적 조건 분기가 자연스럽다 조건이 없으면 null 반환, 있으면 BooleanExpression 반환방식으로 작성할 수 있다. *BooleanExpression이란, QueryDSL 참/거짓 조건식이다. user.username.containsIgnoreCase(keyword) 해당 식을 SQL으로 보면 이렇다.

lower(username) like '%keyword%'

즉, where 절에 들어갈 수 있는 조건식 잭체이다.

2. 가독성이 좋다 검색 조건별 메서드를 분리할 수 있어서, 어떤 조건이 적용되는지 구조적으로 읽힌다.

3. 확장성이 좋다 나중에 다른 필터 조건을 추가할 때도 where(...)에 조건 메서드 하나 더 넣으면 된다.

Row DTO 를 분리했다

이번 구현에서는 최종 응답 DTO 하나만 사용하지 않고, 조회 과정에서 사용하는 중간 DTO를 따로 두었다.

예를 들어,

• ArtistSearchRow : 검색 결과의 기본 정보
• ArtistInstrumentRow : 카드에 붙일 악기 목록 정보
• ArtistSeachResponse : 최종 응답 DTO

해당 방식으로 나눈 이유는, 조회 시점의 데이터 구조와 최종 응답 구조가 완전히 같지 않았기 대문이다.

검색 1차 결과는 기본 정보 중심이었고, 악기 정보는 별도로 조회해 artistProfileId 기준으로 묶어야 했다. (검색 조건에 매칭된 정보만이 아니라, 아티스트가 보유한 악기 목록을 카드에 함께 보여줘야 했기 때문)

즉, 레퍼지토리에서는 DB 조회에 적합한 row 단위 DTO를 사용하고, 서비스에서는 그것들을 조립해서 최종 응답 DTO로 변환하는 식으로 역할을 분리했다.

사용하면서 느낀 아쉬운점

물론 QueryDSL이 만능은 아니다.

1. 처음에는 구조가 더 복잡해 보인다 JPQL은 Repository 메서드 하나에 바로 쓸 수 있지만, QueryDSL은 custom repository, impl 클래스, Q타입 생성 등 준비할 것이 더 많다. 즉, 단순 조회에서는 오히려 과한 선택이 될 수 있다.

2. 작은 조회까지 전부 QueryDSL로 갈 필요는 없다 조건이 거의 없고 고정된 조회라면 JPQL이나 Spring Data JPA 메서드 쿼리로도 충분하다.

프로젝트에서의 적용 의미

이번 검색 구현은 QueryDSL을 처음 직접 적용한 사례였다. 단순히 새로운 기술을 써봤다 보다, 검색 조건이 계속 늘어날 수 있는 구조에서 왜 이 도구가 필요한지를 실제로 체감한 작업이었다.

특히 JPQL로도 구현 가능한 상황이었지만, 이번에는 현재 기능뿐 아니라 추후 확장 가능성까지 고려해 선택한 설계라는 점에서 의미가 있었다.

@RequestParam 가독성 이슈

검색 기능을 만들면서 검색 조건이 점점 많아졌다.

처음에는 각각 @RequestParam 으로 받을 수도 있었지만, 조건이 늘어날수록 컨트롤러 메서드 시그니처가 복잡해지고 가독성이 떨어질 수 있었다.

예를 들면 이런 식이다.

@GetMapping
public ResponseEntity<?> searchArtists(
        @RequestParam(required = false) String keyword,
        @RequestParam(required = false) InstrumentCategory instCategory,
        @RequestParam(required = false) List<Long> instIds,
        @RequestParam(required = false) List<Long> styleTagIds
) {
    ...
}

검색 조건이 더 추가될 가능성까지 생각하면, 이 방식은 유지보수에 불리하다고 판단했다.

해결 방식

검색 조건을 하나의 DTO로 묶고, 컨트롤러에서는 @ModelAttribute 로 받도록 구성했다.

• DTO

  @GetMapping
  public ResponseEntity<?> searchArtists(
        @RequestParam(required = false) String keyword,
        @RequestParam(required = false) InstrumentCategory instCategory,
        @RequestParam(required = false) List<Long> instIds,
        @RequestParam(required = false) List<Long> styleTagIds
  ) {
    ...
  }

• Controller

  @GetMapping
  public ResponseEntity<List<ArtistSearchResponse>> searchArtists(
        @ModelAttribute ArtistSearchRequest req
  ) {
    return ResponseEntity.ok(artistSearchService.searchArtists(req));
  }

@ModelAttribute가 하는 일

@ModelAttribute 는 요청 파라미터를 보고 DTO 객체를 자동으로 바인딩해준다. 예를 들어 다음과 같은 GET 요청이 들어오면

GET /artists?keyword=플룻&instCategory=WOODWIND&instIds=1&instIds=2&styleTagIds=3

스프링은 이를 자동으로 다음과 같은 형태의 객체로 묶어준다.

new ArtistSearchRequest(
    "플룻",
    InstrumentCategory.WOODWIND,
    List.of(1L, 2L),
    List.of(3L)
)

즉, 검색 조건을 하나의 의미있는 객체로 관리할 수 있게 된다.

왜 @RequestBody 가 아닌 @ModelAttribute인가

이번 검색 API는 GET 요청 기반이다. 일반적으로 GET 요청 검색 조건은 body가 아니라 query parameter로 전달된다. 따라서 해당 조건에서는 @ModelAttribute가 더 자연스럽다.

언제 @RequestParam이 더 낫고, 언제 @ModelAttribute가 더 낫냐

@RequestParam 이 괜찮은 경우

• 파라미터 개수가 적음
• DTO 따로 만들기 애매함
• 검색 조건이 자주 안바뀜
• 빠르게 구현할 때

@ModelAttribute 가 더 Best 인 경우

• 검색 조건이 많음
• 앞으로 조건이 늘어날 가능성이 큼
• 컨트롤러 시그니처가 너무 길어짐
• 서비스/레포까지 검색 조건 객체를 그대로 넘기고 싶음

정리

이번 검색 API 에서는 @ModelAttribute 를 사용해 검색 조건을 하나의 DTO로 묶었다. 그 결과:

• 컨트롤러 메서드 시그니처가 단순해졌고
• 검색 조건 추가 시 확장성이 좋아졌으며
• 서비스, 레포지토리 계층으로 객체를 그대로 넘길 수 있어 구조도 더 명확해졌다.

검색 조건이 늘어나는 조회 API라면 @ModelAttribute는 실용적인 선택이었다고 판단한다.

Emotion 은 CSS를 JS/TS로 '모듈화' 해서 재사용하고, props/state 기반으로 조건부 스타일을 안전하게 걸 수 있도록 도와준다.

1) 설치 / 세팅

npm i @emotion/react @emotion/styled

@emotion/react : Emotion css 사용시 필수 @emotion/styled : styled 사용 시 import

폴더 구조 및 이유

컴포넌트-코로케이션

컴포넌트 폴더 안에 파일을 같이 둔다.

    Button/
      Button.tsx
      styles.ts

• styles.ts: Emotion css export만 맡는다.
• 다른 폴더 혹은 더 상위 폴더에 styles 파일을 둘 수도 있지만, 유지보수 및 관리 차원에서 한 컴포넌트당 하나의 styles.ts 파일을 추천한다.

css + css prop (styles.ts) 사용

일반적인 css 사용법과 비슷해 보이지만, 스타일을 함수/배열로 조합해서 바로 적용할 수 있어 로직의 가독성 향상을 기대할 수 있다.

Button/styles.ts 파일 예시

import { css } from "@emotion/react";

해당 import 문을 상단에 정의 후,

export const button = css`
  padding: 12px;
  border: 1px solid #ddd;
`;

해당 형식으로 아래에 css를 작성한다.

Button/Button.tsx 파일 예시

/** @jsxImportSource @emotion/react */
import * as s from "./styles";

항상 상단에 해당 import 문 두 줄을 넣는다. 같은 폴더 내 styles 파일을 가져와 별칭을 붙여 사용하기 때문에 필요하다.

export default function Button() {
  return <div css={s.button}>BUTTON</div>;
}

Button 컴포넌트쪽에서 className처럼 사용 가능하다.

styled 컴포넌트

클래스명 + 스타일 파일 + 연결을 Emotion이 컴포넌트 단위로 자동화 해주는 방식. CSS를 컴포넌트로 포장해서 재사용성이 좋다.

• 컴포넌트 자체가 스타일 덩어리(버튼/인풋/칩/카드)일 때 유리하다.

Button/styles.ts 파일 예시

import styled from "@emotion/styled";

해당 import 문을 상단에 정의 후,

export const Btn = styled.button`
  padding: 12px;
  border: 1px solid #ddd;
`;

• 여기서 styled.button의 button은 <button></button> 을 <S.Btn></S.Btn>으로 사용할 수 있도록 만들어준다.

  // 예시
  export const Container = styled.div`...`;
  export const Header = styled.div`...`;
  export const LiveButton = styled.button`...`;

  해당 컴포넌트만 사용하면, 요소와 CSS가 이미 포함된 상태에서 깔끔하게 로직 작성이 가능하다.
  

Button/Button.tsx 파일 예시

// S = 대문자
/** @jsxImportSource @emotion/react */ -> styled 방식은 css prop을 사용하지 않아 빼도 됨
import * as S from "./styles";

굳이 대문자 표식을 할 필요는 없으나, styled 컴포넌트들은 PascalCase로 export한다고 가정했을 때, 예시문이다.

export default function Button() {
  return <S.Btn>BUTTON</S.Btn>;
}

해당 방식으로 깔끔하게 CSS가 적용된다.

스타일링 방식 4가지 비교

• 일반 CSS (className + .css 파일)
  • 장점: 가장 표준적, 어디서나 동일하게 동작
  • 단점: 규모가 커지면 네이밍/전역 충돌/미사용 CSS관리 비용 커짐, 상태 조합 가독성 떨어짐
    
• Tailwind CSS (유틸리티 클래스 조합)
  • 장점: CSS 파일 작성 거의 없이 빠르게 UI 구현, 디자인 토큰(간격/색/폰트) 통일이 쉬움, 전역 충돌 적음
  • 단점: className이 길어져 JSX 가독성이 떨어질 수 있고, 팀 컨벤션(추상화 기준/컴포넌트화)이 없으면 난잡해짐
    
• Emotion css + css prop (styles.ts + css 배열 조합)
  • 장점: css={[base, cond && extra]}로 조건부 스타일이 깔끔함, 스타일/로직 분리로 PR 리뷰·충돌 감소, 컴포넌트 단위로 영향 범위가 좁음
  • 단점: 프로젝트 설정에 따라 css prop 세팅(pragma 등)이 필요할 수 있음
    
• Emotion styled (스타일 포함 컴포넌트)
  • 장점: <S.Button /> 처럼 캡슐화되어 재사용/확장(variant)에 강함, props 기반 동적 스타일이 자연스러움
  • 단점: 작은 레이아웃 조각까지 전부 styled로 만들면 컴포넌트 정의가 과밀해질 수 있어 css + css prop과 적절한 혼용이 필요

버튼은 UX/UI 일 뿐, RTMP 이벤트는 실제로 일어나야한다.

라이브 스트리밍에서 중요하게 여겨야 할 점 중 하나는 "지금 진짜 방송 중인가?" 를 시청자가 믿을 근거다. 그래서 방송 상태를 단순히 버튼 클릭으로 바꾸지 않고, RTMP 송출 이벤트로 LIVE/ENDED를 확정하는 방식으로 설계했다.

목표: 시청자가 믿을 수 있는 상태 만들기

스트리밍 상태를 아래처럼 단순한 상태 머신으로 정의했다.

• OFF: 방송 없음
• READY: 스트리머가 방송 제목/소개/카테고리 세팅 완료(송출 전)
• LIVE: 실제로 RTMP 송출이 시작됨 (OBS → RTMP 서버)
• ENDED: 실제 송출 종료됨 여기서 핵심은
• READY는 사람이 누르는 버튼 으로 만들 수 있다(의지)
• LIVE/ENDED는 실제 송출이 시작/종료됐다는 물리 이벤트로만 확정해야 한다.(사실)

즉, LIVE는 프론트 버튼만으로 바꾸면 신뢰도가 떨어진다. 유저는 "방송 시작"을 눌렀는데 OBS가 송출을 안 했을 수도 있고, RTMP 서버가 죽었을 수도 있고, 온갖 변수가 있다.

전체 흐름 요약

1. 스트리머가 방송 세팅 → 상태를 READY로 둔다.
2. OBS가 RTMP 서버로 송출 시작
3. RTMP 서버가 onPublish 훅 호출 -> 백엔드가 READY → LIVE 확정
4. 시청자는 상태 조회 API를 통해(status/statuses) LIVE인 채널만 라이브로 믿고 진입
5. 송출 종료 시 on_publish_done 훅 호출 → LIVE → ENDED

상태 전이 트리거: RTMP 훅을 백엔드 앤드포인트로 연결

백엔드는 RTMP 서버(Nginx-RTMP 등)에서 송출 시작/종료 이벤트가 발생하면 호출되는 엔드포인트를 제공한다.

RtmpController

   // OBS 송출 시작 시: READY -> LIVE 확정
    @PostMapping("/on_publish")
    public ResponseEntity<Void> onPublish(@RequestParam("channelId") Long channelId) {
        log.info("on_publish channelId={}", channelId);
        liveStreamingService.onPublish(channelId);
        return ResponseEntity.ok().build();
    }

    // OBS 송출 종료 시: LIVE -> ENDED
    @PostMapping("/on_publish_done")
    public ResponseEntity<Void> onDone(@RequestParam("channelId") Long channelId) {
        log.info("on_publish_done channelId={}", channelId);
        liveStreamingService.onDone(channelId);
        return ResponseEntity.ok().build();
    }
}

왜 channelId를 쿼리로 받나?

RTMP 훅이 호출될 때, 스트림명/키만으로는 "어떤 채널인지" 매핑이 애매해질 수 있다. 일단 MVP에서는 채널단위로 상태를 바꾸는게 가장 직관적이라 channelId를 직접 전달했다.

또한 스트림 키 기반 매핑(키 로테이션/만료/중복 처리 등)을 MVP에서 먼저 억지로 끌고 오면 복잡도가 커질 수 있다. 그래서 채널 단위 식별은 channelId로 단순화하고, 대신 streamKey를 함께 받아 이중 검증(채널의 streamKey = 요청 streamKey 일치 여부)을 수행했다.

• channelId: "어떤 채널의 상태를 바꿀지" 특정
• streamKey: 그 채널에 대한 송출이 맞는지 즉, channelId는 매핑용이고 streamKey 는 인증/검증용이다.

스트림 키를 검증하는 부분은 공통 메서드로 분리해서 중복 제거 + 정책(검증 규칙) 단일화 및 유지보수를 용이하게 만들었다.

    // 스트림키 검증 메서드
    private void verifyStreamKeyOrThrow(Channel ch, String reqStreamKey) {
        if (ch.getStreamKey() == null || !ch.getStreamKey().equals(reqStreamKey)) {
            throw new BusinessException(ErrorCode.INVALID_STREAM_KEY);
        }

서비스 단에서 "가드(guard)"로 상태 머신 지키기

컨트롤러는 그냥 RTMP 이벤트가 들어온 사실을 전달할 뿐이고, 상태 전이의 규칙은 서비스에서 강제해야 한다.

서비스 구현에서 반드시 지켜야 하는 최소 규칙:

• onPublish(channelId):

  • 현재 상태가 READY 일 때만 LIVE로 전이
  • OFF/ENDED/LIVE 에서 들어오면 무시하거나 예외

• onDone(channelId):

  • 현재 상태가 LIVE 일 때만 ENDED로 전이
  • OFF/ENDED/READY 에서 들어오면 무시하거나 예외

해당 가드가 없으면 상태 머신은 그냥 희망 사항이 된다. 현실에서는 이벤트 순서가 깨질 수도 있고 중복 호출 가능성도 있기 때문에 확실하게 처리해줘야한다. 실제 테스트 상황에서 해당 부분 일반 return 을 사용했기 때문에 200OK를 띄우는 문제가 발생해서 바로 예외처리 해주었다.

시청자/프론트가 믿는 근거: 상태 조회 API

RTMP 훅으로 LIVE를 확정했을 시, 프론트에서는 해당 상태를 믿고 UI를 분기하면 된다.

StreamStatusController

package com.example.going.domain.liveStreaming.controller;

import com.example.going.common.enums.StreamStatus;
import com.example.going.domain.liveStreaming.dto.StreamStatusRes;
import com.example.going.domain.liveStreaming.service.LiveStreamingService;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/streams")
public class StreamStatusController {

    private final LiveStreamingService liveStreamingService;

    // 방송 준비중 / 방송중 스트리밍 단일 조회
    @GetMapping("/{channelId}/status")
    public ResponseEntity<StreamStatus> getStatus(@PathVariable Long channelId) {
        StreamStatus status = liveStreamingService.getStatus(channelId);
        return ResponseEntity.ok(status);
    }

    // 방송 준비중 / 방송중 스트리밍 리스트 (+channelId 검색 가능)
    @GetMapping("/statuses")
    public ResponseEntity<List<StreamStatusRes>> getStatuses(
            @RequestParam(required = false) StreamStatus status,
            @RequestParam(required = false) List<Long> channelIds
    ) {
        return ResponseEntity.ok(liveStreamingService.getStatuses(status, channelIds));
    }
}

이렇게 해두면 프론트는:

• LIVE: 영상 + 채팅UI
• READY: 방송 준비중
• OFF/ENDED: 오프라인/종료 같이 상태 기반으로 정직하게 화면을 그릴 수 있다.

테스트 시나리오: "진짜 LIVE로 바뀌는지" 확인

1. RTMP 훅을 직접 로컬에서 실행

   POST http://localhost:8080/api/live-streaming/rtmp/on_publish?name=...
   POST http://localhost:8080/api/live-streaming/rtmp/on_publish_done?name=...

2. 상태 조회로 확인

   GET http://localhost:8080/api/streams/1/status

3. LIVE 리스트 조회

   GET http://localhost:8080/api/streams/statuses?status=LIVE
   GET http://localhost:8080/api/streams/statuses?status=LIVE&channelIds=1,2

정리: 왜 이 방식이 안전한가?

• 프론트 버튼은 "방송 의지" 만 표현한다 → READY
• 실제 송출 여부는 RTMP 서버가 제일 정확히 안다 → LIVE/ENDED
• 시청자는 상태 조회 API만 믿으면 된다
• 서비스 가드로 상태 머신을 강제하면, 이벤트가 이상하게 들어와도 시스템이 덜 죽는다.

해당 설계의 목표는 "시청자가 들어갔는데 방송이 없어서 서비스 품질이 깨지는 일을 줄이기" 이다.

• Safari: 브라우저 네이티브 HLS로 재생(<video src="m3u8">)
• Chrome/Edge/Firefox: hls.js(MSE) 로 재생
• 외부 m3u8 테스트 시 CORS 문제를 피하기 위해 Vite dev proxy로 우회

1) Safari가 아닌 상태에서 Safari native HLS로 찍힘

증상

Chrome에서 실행했는데 콘솔에 해당 로그가 뜸

• [MODE] Safari native HLS
• 또는 Native HLS(maybe)

원인

const canNativePlay = videoEl.canPlayType("application/vnd.apple.mpegurl");
if (canNativePlay) {
  // native...
}

canPlayType()은 반환값이 "" | "maybe" | "probably" 인데, Chrome 에서도 "maybe" 가 나오는 경우가 있어서 truthy로 판단되어 네이티브 분기로 들어가는 오탐이 발생했다.

해결

Safari일 때만 네이티브 분기로 고정한다.

const ua = navigator.userAgent;
const isSafari = /Safari/.test(ua) && !/Chrome|Chromium|Edg|OPR/.test(ua);

const canNativePlay = videoEl.canPlayType("application/vnd.apple.mpegurl");

if (isSafari && canNativePlay) {
  // Safari 네이티브
} else {
  // 나머지는 hls.js
}

point: 네이티브 가능 여부가 아니라 Safari 여부를 먼저 확정해서 우연 재생을 제거

2) Safari 분기 막고 hls.js로 타니 CORS 에러 발생

결국 CORS 에러가 발생해버렸는데...

증상

Chrome에서 hls.js(MSE)로 재생 시도하면 콘솔에 아래 에러:

• Access to XMLHttpRequest ... has been blocked by CORS policy
• [ERROR] networkError manifestLoadError 또는 manifestParsingError

모든 경로에서 에러가 나는건 아니었다. 나중에 프로젝트 상황에서 한번 더 지켜봐야 할듯.

원인

hls.js는 m3u8/세그먼트(ts, m4s)를 XHR/fetch로 직접 요청한다. 즉, 서버가 Access-Control-Allow-Origin 헤더를 제공하지 않으면 브라우저가 차단한다.

반면 <video src="...m3u8"> 네이티브 로딩은 브라우저 미디어 파이프라인에서 처리되어 겉보기엔 "되는 것처럼" 보이는 케이스가 생길 수 있는데, hls.js는 CORS가 필수다.

결론

운영/개발 모두 "브라우저에서 hls.js로 재생" 하려면:

• 서버가 CORS 허용을 해주거나
• 같은 origin으로 보이게 reverse proxy(프록시)를 둬야한다.

3) 해결 시도 - Bite dev proxy로 우회

개발 환경에서는 백엔드 없이도 Vite 서버가 프록시 역할을 할 수 있다.

설정: vite.config.js(프로젝트 루트에 생성)

import { defineConfig } from "vite";

export default defineConfig({
  server: {
    proxy: {
      "/hls-proxy": {
        target: "https://d2zihajmogu5jn.cloudfront.net",
        changeOrigin: true,
        secure: true,
        rewrite: (path) => path.replace(/^\/hls-proxy/, ""),
      },
    },
  },
});

사용법

원본 m3u8: https://d2zihajmogu5jn.cloudfront.net/bipbop-advanced/bipbop_16x9_variant.m3u8

프록시 경로로 변경: /hls-proxy/bipbop-advanced/bipbop_16x9_variant.m3u8

최종 정상 상태 - 계속 요청이 발생함

정상 패턴 (Network 탭)

재생이 정상이라면 요청이 계속 발생한다:

• prog_index.m3u8 (playlist) 반복 요청 (200/304 가능)
• 세그먼트 파일 요청 (200 또는 206 Range)
• 자막이 있으면 fileSequence*.webvtt 연속 요청

즉 HLS는 구조적으로 “m3u8(목차) + 조각(세그먼트)”를 계속 받아서 재생하므로 요청이 계속 생기는 게 정상이다.

운영 시 프록시 필요 여부

• 프록시는 CORS 우회를 위해 자주 사용
• 운영에서 보통
  1. CDN/미디어 서버에서 CORS 허용 헤더 설정(정석)
  2. 같은 도메인으로 /hls/* 경로를 reverse proxy(Nginx) 로 붙여서 CORS 회피
  3. 권한/토큰 기반이면 백엔드가 서명 URL 발급 또는 프록시로 보호

즉 "프록시 필수" 보다 브라우저가 접근 가능한 형태(CORS/동일 오리진)로 제공하는게 필수.

참고 사항

테스트 가능한 m3u8 경로

• https://bitdash-a.akamaihd.net/content/MI201109210084_1/m3u8s/f08e80da-bf1d-4e3d-8899-f0f6155f6efa.m3u8
• https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8
• https://mnmedias.api.telequebec.tv/m3u8/29880.m3u8
• http://184.72.239.149/vod/smil:BigBuckBunny.smil/playlist.m3u8
• http://www.streambox.fr/playlists/test_001/stream.m3u8

해당 경로는 CORS 관련 처리가 필요(버튼 누를 시 proxy 링크로 변환해서 들어감)

• https://d2zihajmogu5jn.cloudfront.net/bipbop-advanced/bipbop_16x9_variant.m3u8

HLS(HTTP Live Streaming)

애플이 2009년 공개한 HTTP 기반 적응형 비트레이트(ABR) 스트리밍 방식이다. 특별한 전용 프로토콜이 아니라 그냥 HTTP로 파일을받아 재생하는 구조라서 웹/모바일/미디어서버에서 널리 지원되고 지금도가장 대중적인 스트리밍 포맷 중 하나다.

HLS의 행심 아이디어는 영상 한 덩어리를 내려받는 대신,

• m3u8(플레이리스트) 파일을 먼저 받고
• 그 안에 적힌 조각(segment) 들을 순서대로 요청해서 재생하는 스트리밍 방식

즉, "재생목록(m3u8)을 따라가면서 segment들을 계속 가져와 재생하는 방식" 이라서

• 네트워크가 느려지면 낮은 화질 세그먼트로 바꾸고(ABR)
• 다시 빨라지면 높은 화질로 복귀하는 식의 끊김 최소화가 가능하다.

참고로 master.m3u8에는 여러 화질(variant)이 들어갈 수 있고, 플레이어는 상황에 따라 적절한 variant를 선택해 재생한다.

그래서 왜 필요한가?

Safari 는 HLS를 네이티브로 재생할 수 있지만(브라우저가 m3u8을 직접 이해함) Chrome/Edge/Firefox 는 기본 지원이 약해서 hls.js가 m3u8을 파싱하고 세그먼트를 받아 MSE(Media Source Extensions)로 video에 붙여 재생하게 된다.

• Js가 m3u8을 파싱
• 세그먼트 다운로드
• 디코딩 가능한 형태로 이어 붙여
• <video> 에 주입해야함

해당 과정을 구현해주는 라이브러리가 hls.js 이다.

그냥 mp4 를 내려받니 않고 HLS 를 쓰는 이유

라이브/스트리밍에서 HLS를 쓰는 이유는

1. 끊김을 줄이고
2. 네트워크에 맞춰 품질을 자동으로 바꾸고
3. 배포/운영을 쉽게 만들기 때문.

HLS는 "끊김 적게 + 빠른 시작 + 라이브에 최적 + CDN 운영 쉬움 + 품질/트랙 확장 쉬움" 때문에 사용한다. 그리고 그걸 브라우저에서 재생하려면 Safari는 네이티브로 되고, 나머지는 hls.js(MSE)가 필요하다.

hls.js 기본 사용 흐름

hls.js로 재생하는 기본 패턴은 거의 고정이다. 일단, hls.js 를 설치한다.

npm i hls.js
# 또는
yarn add hls.js
pnpm add hls.js

선택(있으면 편한것들)

• video.js: 기본 컨트롤/스킨/플러그인 생태계

npm i video.js
# (TS 프로젝트면 타입도 보통 같이 오지만, 필요하면 @types/video.js 확인)

하지만 hls.js 학습용 미니 프로젝트 상황에서는 굳이 설치하지 않고 순수 <video> + 커스텀 버튼으로 가서 이해하도록 하겠다.

• HLS 테스트용 로컬 서버 필요하면(m3u8/ts를 로컬에 두고 테스트 할 때 CORS/경로 문제 덜 겪게)

  npm i -D serve
  # 또는 vite dev server로 public 폴더에 두고 테스트 가능

  현재 상황에서는 해당 선택 파트를 제외하고 학습을 진행하도록 할것이다.

• Hls.isSupported() (MSE 되는 브라우저인지)

• hls.loadSource(m3u8)

• hls.attachMedia(videoEl)

Safari는 분기해서 네이티브로 처리한다.

import Hls from "hls.js";

function mountHls(videoEl, src) {
    // Safari: native HLS
  if (videoEl.canPlayType("application/vnd.apple.mpegurl")){
      videoEl.src = src;
    return() => {videoEl.src="";};
  }

  // Others: Hls.js via MSE
  if (Hls.isSupported()) {
      const hls = new Hls({
       // 학습용 디버그.로깅하기 좋은 옵션들
         enableWorker: true,
           lowLatencyMode: true, 
     });

    hls.loadSource(src);
    hls.attachMedia(videoEl);

    hls.on(Hls.Events.MANIFEST_PARSED, () => {
    // autoplay는 브라우저 정책상 실패 가능성 있어서 사용자 제스처 필요
        videoEl.play().catch(() => {});  
    });

    return () => hls.destroy();
  }

  console.warn("HLS가 해당 브라우저를 지원하지 않습니다.");
  return () => {};
}

화질(퀄리티) 선택하는 법

HLS에 여러 화질이 있으면, hls.levels에 들어온다.

• 자동(ABR): hls.currentLevel = -1
• 특정 화질 고정: hls.currentLevel = index

hls.on(Hls.Events.MANIFEST_PARSED, () => {
    console.log(hls.levels.map((l, i) => ({
    i,
      height: l.height,
      bitrate: l.bitrate,
    })));
});

// ex: 720p 고정
const idx = hls.levels.findIndex(l => l.height === 720);
if (idx >= 0) hls.currentLevel = idx;

// 자동 되돌리기
hls.currentLevel = -1;

Auto + 360/720/1080 드롭다운 정도만 있어도 학습상황에서 도움이 된다.

에러처리(복구) 패턴은 사실 정답이 있다.

hls.js는 에러 이벤트에서 fatal 여부를 준다

• 네트워크 계열 fatal → hls.startLoad() 재시도

• 미디어/디코딩 계열 fatal → hls.recoverMediaError()

• 그 외 → destroy() 이후 새로 로드 (상단에 이미 사용한 흔적 있음)

  hls.on(Hls.Events.ERROR, (event, data) => {
  console.log("HLS error:", data.type, data.details, "fatal:", data.fatal);
  
  if (!data.fatal) return;
  
  switch (data.type) {
   case Hls.ErrorTypes.NETWORK_ERROR:
     hls.startLoad();
     break;
   case Hls.ErrorTypes.MEDIA_ERROR:
     hls.recoverMediaError();
     break;
   default:
     hls.destroy();
  
  }
  })

  디버깅은 해당 순서로 보면 빠르다

  HLS 재생이 안된다 - 대부분 이쪽에서 걸림

1) m3u8이 네트워크로 받아지나?

• DevTools → Network에서 *.m3u8 요청 확인

2) 세그먼트 요청이 이어지나?

• *.ts / *.m4s 요청이 연달아 나가야 정상

3) CORS

• 가장 흔한 함정
• m3u8/세그먼트가 다른 도메인이면 CORS 헤더 필요

학습 시 목표 체크 리스트

• m3u8 URL 입력 → 재생
• Safari 네이티브 분기 처리
• Quality(Auto/고정) 드롭다운
• Error 상태 표시 + recover 동작 확인
• 이벤트 로그/Network로 흐름 추적 가능

1) Docker Desktop 준비

• docker run은 Docker 엔진이 켜져있어야 동작

2) Redis 컨테이너 실행

Redis 서버를 도커 컨테이너로 띄움

docker run -d --name going-redis -p 6379:6379 redis:7

--name going-redis : 컨테이너 이름 지정

-p 6379:6379 : 내 PC(host) 6379 → 컨테이너 6379 포트 연결

redis:7 : Redis 7 버전 이미지 사용 (버전 생략 가능)

3) 실행 확인

docker ps

• going-redis 컨테이너가 Up
• 포트도 매핑됨

→ 즉, 내 PC에서 localhost:6379 로 Redis 접근 가능한 상태

4) keys 명령 = redis-cli 안에서 처리할것

• Bash 창에 바로 치면 리눅스 쉘 명령으로 실행하게 됨.

5) redis-cli 접속

컨테이너 안의 Redis CLI로 들어감

docker exec -it going-redis redis-cli

그러면 프롬프트가

127.0.0.1:6379>

로 바뀌고, 이제부터 Redis 명령이 동작

연결됐는지 확인하려면 PING 명령어 치면 PONG 이 옴. 귀여움

6) Redis 데이터(키) 확인

redis-cli 안에서

KEYS *
KEYS refreshToken*

했을때, 전체 키가 나옴 (현재 refreshToken)

• Redis는 정상 동작 중
• refreshToken 관련 데이터가 저장되어있음
• 토큰값이 나오는건 아님

7) 토큰값을 확인하려면

TYPE refreshToken:test

• test는 키데이터 명

• string 일 때

GET refreshToken:test

• hash 일 때

HGETALL refreshToken:test

자주 사용하는 도커 관리 명령

• 컨테이너 로그

docker logs going-redis

• 컨테이너 중지/시작

docker stop going-redis
docker start going-redis

• 컨테이너 삭제

docker rm -f going-redis

추가 - 도커의 image란,

프로그램을 실행하기 위한 완제품 패키지(템플릿)

Redis를 예로 들면, Redis 서버를 실행하는 데 필요한 것들이 한 덩어리로 들어있는 설치본 + 실행환경

이미지(image) vs 컨테이너(container)

헷갈릴 수 있어서 정리하자면,

• Image = 레시피가 포함된 틀
  • Redis가 어떻게 설치돼 있고, 어떤 파일들이 있고, 기본 실행 명령이 뭔지 정의된 템플릿
  • 한 번 다운받아두면 계속 재사용 가능
• Container = 실제로 만들어진 제품(실행 중인 인스턴스)
  • 이미지를 실행(run) 해서 만들어진 실제 프로세스
  • 컨테이너를 여러 개 띄울 수도 있음(같은 이미지로 복제 가능)

docker run -d --name going-redis -p 6379:6379 redis

그래서 해당 명령어의 의미는

1. redis 이미지가 로컬에 없으면 다운로드하고
2. 그 이미지로 컨테이너(going-redis)를 하나 만들어서
3. 실행한다

이미지에 포함되는 것

• OS 파일 일부(최소한의 리눅스 기반)
• Redis 실행 파일(redis-server, redis-cli)
• 기본 설정 파일
• 컨테이너가 시작될 때 뭘 실행할지에 대한 기본 명령(ENTRYPOINT/CMD)

그래서 내 컴퓨터에 Redis를 따로 설치하지 않아도 이미지 안에 다 들어있으니까 바로 실행 가능

이미지 확인/관리 명령

• 내가 가진 이미지 목록 보기:

docker images

• 지금 실행 중인 컨테이너 보기:

docker ps

• redis 이미지가 정학히 어떤 태그인지 보기:

docker images redis

요약

이미지 = 실행 환경까지 포함된 프로그램 패키지(템플릿)

컨테이너 = 그 이미지를 실행해서 만들어진 실제 실행 중인 프로세스

list-style: none;

링크 밑줄 제거

text-decoration: none;

버튼/인풋 기본 테두리 제거

border: none;

포커스 테두리(아웃라인) 제거

outline: none;

배경 제거

background: none;

이미지/요소 드래그 방지(브라우저 드래그)

-webkit-user-drag: none;

스크롤바 숨기기(브라우저별)

/* Chrome/Safari */
::-webkit-scrollbar { display: none; }

/* Firefox */
scrollbar-width: none;

커서 숨기기

caret-color: transparent;

+ React에서 기본 브라우저 margin, padding 없애기

/*app.css*/

html,body {
  margin: 0;
  padding: 0;
}

더 깔끔하게 가고싶으면

*, *::before, *::after {
  box-sizing: border-box;
}

body {
  margin: 0;          /* body 기본 8px 제거 */
}

h1, h2, h3, p, ul, ol {
  margin: 0;          /* 제목/문단/리스트 기본 margin 제거 */
  padding: 0;         /* ul/ol 기본 padding 제거 */
}

사용자는 항상 내가 원하는 대로 동작하지 않는다. 내가 "로그인 버튼을 눌러서 로그인 하고 마이페이지는 드롭다운 내의 메뉴로 접근하세요" 라는 흐름을 만들어 놨어도 사용자가 주소창에 경로를 직접 입력해서 특정 페이지(ex.마이페이지)로 들어올 수 있다.

UI상에서는 숨겨져 있거나 버튼이 막혀있고, 백엔드에서 막아주고 있는 상태여도 URL 직접 접근은 언제든 가능하기 때문에 해당 문제들이 발생한다.

• 인증이 없는 상태에서 페이지가 렌더되며 내부 API가 연달아 호출됨
  • 401/403이 계속 발생하거나, 화면이 깨진 상태로 보임
    • 경우에 따라선 빈 화면 / 무한 로딩 / 에러 토스트 반복 같은 UX가 발생
    • "이 페이지는 접근 가능한가?" 라는 책임이 컴포넌트에 분산되어 각 페이지마다 인증 체크를 반복하게 됨

그래서 "이 경로는 로그인한 사용자만 접근 가능" 같은 규칙을 라우팅 레벨에서 중앙집중적으로 차단 하기위해 Route Guard를 사용한다.

"액션 가드" vs "라우트 가드"

액션 가드(Action Guard)

• "예약하기", "좋아요", "결제하기" 같은 행동 버튼 클릭 시점에 로그인 체크
• 로그인이 아니면 로그인 화면으로 보내고, 로그인 후 원래 화면으로 복귀

장점: 특정 기능만 보호 가능, UX가 직관적 단점: 라우트 자체는 접근 가능(페이지 단에서 한 번 더 막아야 완벽)

라우트 가드(Route Guard)

• 로그인 필수 페이지 접근 자체를 차단
• 보호된 라우트는 <ProtectedRoute><Page/></ProtectedRoute> 형태로 감싸서 진입을 막음

장점: 페이지 단에서 확실하게 막힘 하나만 사용하는 경우도 있지만, 결국에는 UX를 위해서는 프로젝트를 진행할때는 항상 2가지 전부 사용을 하는 모습이다.

ProtectedRoute 구현 (Zustand principal + bootstrap)

• 새로고침 직후엔 isAuthenticated = false 일 수 있다. → 토큰이 있으면 bootstrap() 으로 principal 복구 시도 후 판정해야 안정적
• redirect는 <Navigate /> 사용 (SPA 유지)
• state로 "원래 가려던 경로" 를 넘기면 로그인 후 자동 복귀 가능

<ProtectedRoute><Page/></ProtectedRoute> 형태로 사용하기 때문에

function ProtectedRoute({ children }: { children: React.ReactNode })

• children : 해당 props가 반드시 있고 그 값은 리액트가 렌더 할 수있는 무언가여야 한다.
• React.ReactNode : wrapper 컴포넌트에서 children 타입은 보통 이걸 쓰던데, 아래 요소들을 포함하기 때문이라고 한다.
  • JSX 엘리먼트 <div /> , <MyComp />
  • 문자열
  • 숫자
  • 배열
  • null

  const loc = useLocation();
// 인증 boolean
  const isAuthenticated = usePrincipalState((s) => s.isAuthenticated);
// 복구 시도 시 필요
  const bootstrap = usePrincipalState((s) => s.bootstrap);
  const [ready, setReady] = useState(false);

useEffect(() => {
    (async () => {
      await bootstrap(); // 토큰 존재 시 principal 복구 시도
      setReady(true);
    })();
  }, []); // 의존성 배열 없이 마운트 1회만

// 로딩중 화면
if (!ready) return <div style={{ padding: 16 }}>로딩중...</div>;

// 인증되지 않은 상황에서는 로그인 화면으로 넘기고, 로그인 후 원래 본인이 접근하려던 곳으로 보내줌
if (!isAuthenticated) {
    return <Navigate to="/signin" replace state={{ from: loc }} />;
  }

  return <>{children}</>;

라우터에 적용 (Page 전체 보호)

Page가 <Outlet /> 을 렌더한다면, 상위에서 한 번만 감싸면 하위 라우트가 전부 보호된다.

<Route
  element={
    <ProtectedRoute>
      <Page />
    </ProtectedRoute>
  }
>
// ...여기있는 라우트들은 보호 대상    
</Route>

+ (추가) 이미 로그인 했는데 로그인 화면이 다시 뜨는 문제

뒤로가기 등으로 로그인 페이지에 다시 접근 가능한 상황에서는 로그인 페이지 자체에서 "로그인 상태면 즉시 튕기기" 처리를 하면 된다.

const isAuthenticated = usePrincipalState((s) => s.isAuthenticated);

 useEffect(() => {
    if (isAuthenticated) {
      navigate(fromPath, { replace: true });
    }
  }, [isAuthenticated]);

Think

• URL 직접 접근 차단 : 버튼을 숨겨도 주소창으로 들어올 수 있으니 "페이지 단(라우팅 레벨)"에서 먼저 막기
• 새로고침/재접속 대응 : 토큰이 있어도 상태가 비어 있을 수 있어서 bootstrap() 으로 복구 후 판정(깜빡임 및 오판 방지)
• 원래 가려던 곳으로 복귀 : /signin으로 보낼 때 state.from 저장 → 로그인 성공 시 navigate(from, { replace:true })
• 뒤로가기 UX : 로그인 성공/리다이렉트는 replace:true로 히스토리에서 로그인 페이지 제거(뒤로가면 로그인창 재등장 방지)
• 이미 로그인인데 로그인 페이지 노출 방지 : 뒤로가기로 로그인 진입해도 로그인 상태면 즉시 from으로 튕기기
• 액션 가드도 같이 : "행동" 은 클릭 시점에도 한 번 더 체크(로그인 전인데 UI 플로우만 진행되는 것 방지)
• 로딩/에러 표현 최소화 : guard 판정 중엔 잛은 로딩(스켈레톤 혹은 text)만, alert 너무 많지 않게, 토스트 혹은 인라인 안내로

• N+1은 리스트 쿼리 1번(+1) 실행 후, 리스트 안의 각 엔티티에서 LAZY 연관 필드를 접근할 때마다 N번의 추가 쿼리가 나가는 현상이다.

• "부모 리스트 조회" 1번

• "자식/연관 엔티티 로딩" N번 → 총 1 + N(또는 1 + 2N, 1 + 3N ...) 쿼리가 발생한다.

N+1은 데이터 정합성을 깨는 동시성 문제라기보다, 요청당 DB 쿼리를 폭증시켜 지연/타임아웃을 유발하는 성능 문제다. 다만 지연이 커지면 사용자 재시도나 중복 요청을 유발해, 결과적으로 동시성 이슈가 더 잘 드러나는 환경을 만들 수 있다.

왜 생기는가(LAZY + 반복 접근 패턴)

JPA에서 연관관계를 LAZY로 두면, 연관 엔티티는 처음 조회 시점에서는 실제로 가져오지 않고 프록시(대리 객체) 만 넣어둔다.

그리고 코드에서 연관 필드를 "진짜로" 접근하는 순간에, 그제서야 DB에 쿼리를 날려서 로딩한다.

문제는 "리스트 조회 + 루프/스트림에서 연관 접근" 조합이 너무 흔하다는 것.

예시)

• 예약 리스트 10개 조회(1쿼리)
• 각 예약에서 timeSlot, lesson을 LAZY로 읽음 (각 10 쿼리)
• 결과: 1 + 10 + 10 = 21쿼리

EntityGraph와 Fetch Join

N+1을 해결하는 핵심은 단순하다. LAZY연관을 나중에 하나씩 가져오지 말고, 처음 조회할 때 필요한 연관을 같이 가져오면 된다. 이걸 대표적으로 해결하는 방법이 Fetch Join 과 @EntityGraph다.

Fetch Join(JPQL로 강제 함께 로딩)

fetch Joi은 JPQL에서 join fetch 를 직접 써서, 연관 엔티티를 무조건 같이 로딩하게 만드는 방식이다.

@Query("""
select r from LessonReservation r
join fetch r.timeSlot
join fetch r.lesson
where r.user.userId = :userId
""")
List<LessonReservation> findMyReservationsFetch(Long userId);

특징

• 어떤 연관을 가져올지 쿼리에 명시적으로 드러남
• 복잡한 조건/조인/튜닝이 필요하 경우 제어가 강함
• 대신 JPQL이 길어질 수 있고, 상황에 따라 distinct나 페이징 문제가 생길 수 있음(특히 컬렉션 조인)

@EntityGraph (조회 메서드에 '옵션'처럼 붙이는 방식)

@EntityGraph는 "이 메서드로 조회할 때는 이 연관들을 같이 가져와"를 Repository 메서드에 선언하는 방식이다.

@EntityGraph(attributePaths = {"timeSlot", "lesson"})
List<LessonReservation> findAllByUser_UserIdOrderByRequestedDtDesc(Long userId);

특징

• 기존 네이밍 쿼리(findAllBy...)를 유지하면서 N+1을 쉽게 막을 수 있음
• "해당 메서드는 항상 이 연관이 필요하다" 같은 경우에 가독성과 유지보수가 좋음
• 내부적으로는 JPA가 해당 연관을 한번에 로딩하도록 쿼리를 굿겅한다 (보통 join 형태)

둘의 차이 요약

@EntityGraph

• AKA fetch join의 간편 ver.
• 특정 API/List 에서는항상 필요한 연관이 고정되어 있음
• 메서드 네이밍 쿼리를 유지하고 싶음
• 특히 ManyToOne, OneToOne 같은 to-one 연관을 같이 로딩할 때 깔끔

Fetch Join

• 조건/조인 구조가 복잡해서 쿼리를 직접 컨트롤하고 싶음
• 성능 튜닝을 위해 "어떤 join을 하는지"를 코드에서 명확히 보고 싶음
• 필요할 때만 선택적으로 fetch 해야함

주의사항

to-one은 비교적 안전

• ManyToOne, OneToOne은 결과 row가 크게 뻥튀기 되지 않아서 @EntityGraph든 fetch join이든 적용이 상대적으로 안전하다.

to-many(컬렉션) fetch는 조심

• OneToMany같은 컬렉션을 fetch join 하면 결과 row가 중복되거나, 페이징이 깨질 수 있는 문제가 자주 생긴다.
• 이런 경우는 DTO 프로젝션, 배치 패치 사이즈, 별도 조회 등 전략을 같이 고려해야 한다.

결론

• 항상 필요한 to-one 연관을 같이 가져오겠다 → @EntityGraph가 가장 간단
• 쿼리를 직접 설계해서 가져오는 걸 통제해야겠다 → fetch join이 낫다

queryKey를 미리 설계하는 이유

React Query(TanstackQuery)는 단순히 "API 호출을 편하게 해주는 라이브러리" 가 아니라 서버 상태(server state)를 캐시로 관리하는 도구다.

그래서 React Query 를 조금 더 알고 쓰려면 useQuery 문법보다 먼저 이해해야하는게 있다.

queryKey = 캐시에 저장되는 데이터의 주소(식별자)

이 글에서는 React Query의 핵심 개념과, 특히 queryKey를 미리 세팅 (키 팩토리/컨벤션화) 해두면 얻는 장점을 정리해보려고 한다.

사실, 해당 내용을 인지하기 전 개인프로젝트에서 queryKey 관련으로 골머리 아픈 상황이 생겼고, 이를 방지하기 위해(다시는 그런 일을 겪지 않기 위해...) 정리하기로 마음 먹었다.

1) React Query가 다루는건 "서버 상태"다

프론트에서 상태는 크게 두 종류로 나뉜다.

• UI 상태: 모달 열림, 탭 선택, 입력 중인 폼 값, 드롭다운 오픈 등
• 서버 상태: 서버에서 받아온 목록/상세 데이터, 그리고 그 데이터의 최신성/동기화

React Query 는 후자인 서버 상태 를 캐시로 다루는 데 특화돼 있다.

• 같은 데이터를 여러 화면에 써도 캐시를 공유
• 필요할 때만 재조회(refetch)
• 수정/삭제/토글 후 invalidate로 다시 맞추기

2) queryKey는 "데이터 주소"다

React Query에서 queryKey는 어떤 데이터를 캐시에 저장할지 결정한다.

• 주소가 같으면 같은 캐시를 쓴다
• 주소가 다르면 캐시가 분리된다

그래서 queryKey를 대충 쓰면

• 캐시가 중복 저장되고
• invalidate가 제대로 안 먹고
• 화면마다 데이터가 제각각 보일 수 있다

반대로 queryKey를 잘 설계하면

• 데이터 흐름이 안정적이고
• 동기화가 명확해지고
• 코드도 읽기 쉬워진다

3) queryKey를 "미리 세팅" 하는 방법 : Keys Factory

나는 queryKey를 컴포넌트에서 직접 하드코딩하지 않고, 한 파일에 모아두는 방식을 사용했다.

export const lessonKeys = {
  // 내 레슨 목록(정렬 기준을 key에 포함)
  myList: (sort: LessonSort) => ["myLessons", sort] as const,

  // 내 레슨 상세
  myDetail: (lessonId: number) => ["lessons", "me", "detail", lessonId] as const,

  // 타임슬롯(기간 포함)
  myTimeSlots: (lessonId: number, from: string, to: string) =>
    ["lessons", "me", "detail", lessonId, "time-slots", from, to] as const,

  // 반복 규칙
  myRecurrence: (lessonId: number) =>
    ["lessons", "me", "detail", lessonId, "recurrence"] as const,
};

as const 를 붙이는 이유

• queryKey 타입이 "그냥 string[]"로 퍼지지 않게 고정해 준다.
• invalidate/setQueryData에서 키를 일관되게 쓰기 쉬워진다.

참고 *: 프로젝트 중간에 컨벤션을 도입하면 기존에 쓰던 키(prefix)와 섞이기 쉬운데, 이때 같은 데이터를 서로 다른 key로 캐싱하게 되면서 invalidate가 먹지 않는 문제가 생길 수 있다.

그런의미에서 초반에 잡아두고 가는것이 좋다고 판단되었다.

4) key를 미리 세팅해두면 얻는 장점

• 키가 곧 API 문서/도메인 구조가 된다 myList, myDetail, myTimeSlots 처럼 키 이름이 정리돼 있으면 프로젝트에서 어떤 데이터들이 존재하는지 한 눈에 보인다
• invalidate 범위를 설계하기 쉬워진다

예를 들어 내 레슨 목록만 갱신하고 싶다면

qc.invalidateQueries({ queryKey: lessonKeys.myList(sort) });

정렬 캐시를 한 번에 갱신하고 싶으면 prefix를 기준으로

qc.invalidateQueries({ queryKey: ["myLessons"] });

invalidate 전략을 코드로 설명가능하게 된다.

• 협업에서 실수(키 불일치)를 크게 줄인다 키를 하드코딩하면 사람이 늘어날수록 "미묘하게 다른 배열"이 생긴다. keys factory로 통일하면 팀 전체가 같은 key를 쓰게되면서 해당 문제를 줄일 수 있다.

• 리팩토링이 용이하다 나중에 key구조를 바꿔야 해도 한 파일만 수정하면 된다.

5) useQuery: 읽기(서버 -> 캐시)

키를 미리 세팅해두면 useQuery는 오히려 단순해진다.

export function useMyLessonList(sort: LessonSort) {
  return useQuery({
    queryKey: lessonKeys.myList(sort),
    queryFn: async (): Promise<LessonSummary[]> => {
      const resp = await getMyLessonsReq();
      return resp.data.data;
    },
  });
}

여기서 핵심은

• queryKey = 캐시 주소
• queryFn = 서버에서 가져오는 방법

6) useMutation: 쓰기(서버 변경 -> 캐시 동기화)

서버 데이터를 바꾸는 작업은 useMutation이 담당한다.

export function useToggleMyLessonStatus(sort: LessonSort) {
  const qc = useQueryClient();

  return useMutation({
    mutationFn: ({ lessonId, next }: { lessonId: number; next: LessonStatus }) =>
      updateMyLessonReq(lessonId, { status: next }),

    onSuccess: (_data, vars) => {
      // 목록 + 상세 캐시를 다시 최신화
      qc.v({ queryKey: lessonKeys.myList(sort) });
      qc.invalidateQueries({ queryKey: lessonKeys.myDetail(vars.lessonId) });
    },
  });
}

여기서 중요한 건 "쓰기 성공 이후 어떤 캐시를 갱신할지"가 key로 드러난다는 점이다.

정리

React Query를 "조금 더 알고" 사용한다는 말은 결국 이 말로 요약된다.

• 서버 상태는 캐시로 관리한다
• queryKey는 데이터의 주소다
• key를 미리 세팅(컨벤션화)하면 동기화/리팩토링/협업이 쉬워진다

여기서 나는 미리 세팅 혹은, keys를 파일로 분리할 생각을 하지 못했었고 코드와 파일이 늘어날 수록 이전에 설정해놓은 key를 다시 설정한다던가 하는 실수를 해서 상태를 최신화 시키지 못하는 상황이 일어났었다. 다시는 그로 인해 쓸데없이 정신력 깎아먹는 시간을 만들지 않도록 성장해야겠다!

끝

웹개발 수업으로 처음 스프링 프레임워크를 접했을 때, 수업은 JSP / MyBatis 위주로 진행되었다. DTO도 자연스럽게 class로 만들게 되었는데, 프레임워크의 편의성(JPA 같은 것들)보다 ‘뜨거운 커스텀의 맛’을 먼저 보는 바람에 당시에는 계속 “이게 뭔데…” 스탠스를 유지할 수밖에 없었다.

그러다 이후에 record로 DTO를 작성할 기회가 많아졌고, 문득 이런 생각이 들었다.

“예전엔 class로 만들었는데, 지금은 record로도 만들잖아? 그럼 둘은 정확히 뭐가 다르지?”

이 글은 class DTO와 record DTO의 차이, 그리고 내 프로젝트에서 어떤 기준으로 선택하면 좋은지를 정리해보는 글이다.

DTO

DTO(Data Transfer Object)는 말 그대로 데이터를 전달하기 위한 객체다. 여기서 중요한 포인트는 "객체"가 아닌 전달(Transfer)이다.

즉, DTO는 보통 이런 상황에서 등장한다.

• 클라이언트(프론트) <-> 서버(백엔드) 가 데이터를 주고받을 때
• 컨트롤러 <-> 서비스/도메인 사이에서 데이터를 옮길 때

DTO의 역할은 간단하다. "필요한 데이터만, 약속된 형태로, 안전하게 전달하기."

왜 DTO를 따로 만들까?

1. 필요 없는 정보까지 노출될 가능성 예: User 엔티티에 password, role, 내부 상태값이 있는데 응답으로 그대로 나가버릴 수도 있음
2. API 응답 스펙이 엔티티에 끌려다님 화면에 필요한 응답은 바뀌는데, 그때마다 DB 설계(Entity)를 건드릴 순 없음
3. 화면에 맞게 가공해서 보내기 어렵다 현재 진행하고있는 프로젝트에서 이름 + 악기 + 레슨 가격을 한 번에 내려줘야하는 상황이 있는데, 엔티티 구조가 그대로면 비효율적이다.

그래서 DTO는 "엔티티/도메인과 별개로" API 계약서 역할을 해준다.

택배 상자를 예로 들어보자.

엔티티가 "집 안의 물건 전체"라면, DTO는 "택배 상자" 같은 느낌이다.

• 집(서버 내부)에는 물건이 많고, 민감한 것도 있고, 정리도 제각각이다.
• 근데 택배(응답(Response)/요청(Request))로 보낼 때는
  • 필요한 것만
  • 정해진 포장 방식으로
  • 안전하게 보내야함 즉, DTO는 "택배 상자에 담을 목록 + 포장 규격"이다.

결론적으로, DTO는 "필요한 정보만 담는 약속된 그릇"이다.

• DTO = 데이터 전달 목적
• Entity = DB와 도메인 모델링이 목적

여기까지는 이해했고, 해당 목적에 맞게 프로젝트에 적용할 수 있다. 하지만 class vs record 사용방식 차이를 설명하라고 한다면? "편하니까 record." 라고 밖에 대답 못하겠다.

그래서 class DTO와 record DTO는 뭐가 다를까?

record를 사용하면 class 로 만들 때보다 코드가 짧아지고, getter 만들 필요도 없고, IDE가 자동으로 다 해주는 느낌이라 편리하다.

하지만 계속 증식하는 DTO를 바라보고 있자니 record가 편한 이유는 단순히 "짧아서"가 아니었다. DTO의 목적(전달/계약)에 더 잘 맞는 방향으로 코드를 강제하기 때문이다.

핵심 차이는 class DTO는 '가변 객체'가 되기 쉽고, record DTO는 불변 계약을 기본값으로 가진다.

1) 가장 큰 차이: “불변(Immutable)” vs “가변(Mutable)"

DTO는 아까 말했듯 "필요한 데이터만 약속된 형태로 전달" 하는 역할이다. 그 말은 곧, 한번 만들어진 DTO가 중간에 바뀌지 않는 게 안전하다는 뜻이기도 하다.

class DTO(가변이 되기 쉬움)

class는 기본적으로 setter를 열어두기 쉽다.

• 처음에는 "바인딩이 편하니까"
• 나중에는 "값 수정할 일이 있을 수도 있으니까"
• 그러다가 어느 순간 DTO가 중간에 값이 바뀌는 객체가 되어버린다.

이게 왜 문제냐면, DTO는 원래 "계약서"인데 계약서가 중간에 수정되면 어디서 값이 바뀌었는지 추적이 어려워진다.

record DTO(불변이 기본값)

record는 생성 시점에 값이 정해지고, 그 이후에는 바꿀 수 없다. 즉, DTO를 record로 작성하는 순간 코드 자체가 "이 DTO는 전달용이고, 한 번 만들어지면 변하면 안된다" 고 말하는 셈이다.

DTO목적에 딱 맞는 성질을 언어 차원에서 기본값으로 제공하는 게 record의 제일 큰 장점이다.

2) "계약서" 로서의 명확함 : 생성자 한 방에 스펙이 고정됨

class DTO는 필드가 많아질 수록 해당 패턴이 흔하다.

• 기본 생성자 만드로
• setter로 하나씩 채우고
• 값이 다 채워졌는지 확신은 없음 record는 생성자 한 번으로 스펙이 확정된다.
• 어떤 값이 DTO를 구성하는지 한 줄에 보이고
• 필수 값이 빠지면 컴파일/실행 단계에서 바로 티가 난다. "DTO는 계약" 이라는 관점에서 record가 훨씬 직관적이다.

3) 보일러플레이트: "짧아져서 편하다" 는 사실 맞다

record는 다음을 자동으로 제공한다

• getter(정확히는 component accessor)
• equals / hashCode
• toString
• canonical constructor 그래서 코드량이 줄고 실수 포인트도 줄어든다.

하지만 중요한건 "코드가 짧다"가 아니라 DTO가 DTO답게 유지되도록 돕는다는 점이다.(일관성 유지)

그럼에도 class DTO가 존재하는 이유

record로 대부분 커버가 되긴 하지만, 프로젝트를 진행하다 보면 DTO가 "계약서"가 아닌 상태/과정/확장에 가까워지는 순간이 잇다. 그럴때는 class가 더 자연스럽거나, 팀/도구 환경상 class가 편한 경우가 생긴다.

1) 단계적으로 채워지는 요청(임시저장 / Draft / Step Form)

예를 들어 신청서처럼

• 소개 먼저 저장
• 경력 나중에 저장
• 1선택 추가
• 2태그 추가 이런 식으로 값이 순차적으로 쌓이는 요청은, DTO가 이미 "완성된 계약" 이라기 보다 "작성 중인 문서"가 된다. record는 불변이라 매 단계마다 새 객체를 만들어야 하고, 경우에 따라 null/Optional이 많아져 오히려 복잡해질 수 있다. 이럴 땐 class가 더 자연스럽다.

2) 상속/버전 분기 같은 "확장 구조"가 필요할 때

record는 상속이 불가능하다. 공통 베이스 DTO를 두고 v1/v2 로 확장한다거나, 계증 구조를 활용하는 설계를 택하면 class를 써야한다.

3) DTO에 "변환/조립 책임"을 섞는 스타일일 때

예전에 내가 만들었던 DTO처럼 요청 DTO 안에 toUser(), toOAuth2User() 같은 변환 메서드를 넣는 경우가 있다. 이건 DTO가 순수 전달 객체라기보다 “조립/변환기” 역할까지 가지게 되는 형태라서, class로 두는 편이 자연스럽게 느껴질 수 있다. (물론 record에서도 메서드는 가능하지만, 설계 의도 자체가 달라진다.)

내가 이해한 결론

잘 쓰면 class DTO든 record DTO든 결과는 거의 같다. 생성자 한 번에 값을 채워서(new response 같은) "완성된 DTO"를 만들고, 이후에는 건드리지 않는다면 둘 다 안전하게 DTO 역할을 한다.

차이는 기능 차이보다 실수 방지(가드레일) 에 가깝다. record는 기본이 불변이라 setter 기반의 "미완성 DTO/중간 수정" 패턴이 구조적으로 나오기 어렵고, 코드만 봐도 "이건 계약/전달용 데이터 묶음" 이라는 의도가 명확하다.

반대로 class는 유연한 만큼 팀이 규칙을 안 세우면 DTO가 점점 "상태를 가진 객체" 처럼 변질되기 쉽다. 그래서 나는 기본값을 record로 두고, "작성 중" 흐름이 필요한 경우 class를 고려하기로 했다.

결국 record가 편한 이유도 “짧아서”라기보다, DTO를 DTO답게 유지하게 해주는 기본값이기 때문이다.

Spring Data JPA Auditing으로 createdAt / updatedAt 자동 채우기

엔티티마다 생성일/수정일 컬럼을 매번 넣기 귀찮을 때, 공통 베이스 클래스를 만들어두면 편하다.

@MappedSuperclass + @CreatedDate / @LastModifiedDate를 쓰면 저장/수정 시점에 시간이 자동으로 채워진다.

- 예시

@Getter
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class) // Auditing 동작 스위치
public abstract class BaseTimeEntity {

    @CreatedDate
    @Column(name = "create_dt", nullable = false, updatable = false)
    private LocalDateTime createDt;

    @LastModifiedDate
    @Column(name = "update_dt")
    private LocalDateTime updateDt;
}

- 사용방법

엔티티에서 상속만 하면, 해당 엔티티 테이블에 create_dt, update_dt 컬럼이 포함된다.

@Entity
public class Lesson extends BaseTimeEntity {
    @Id @GeneratedValue
    private Long lessonId;

    // ...
}

- 반드시 필요한 설정 : Auditing 활성화

Spring Boot에서 Auditing이 자동으로 돌려면 설정 클래스(또는 메인 클래스)에 아래를 추가해야 한다.

• 메인 클래스

  @EnableJpaAuditing
  @SpringBootApplication
  public class MuzinApplication { }

  혹은,

• 설정 클래스(config 파일 생성) 분리

  @Configuration
  @EnableJpaAuditing
  public class JpaConfig { }

주의할 점

• @MappedSuperclass는 테이블로 생성되지 않음 (상속받은 엔티티 테이블에 컬럼이 생김)
• @CreatedDate, @LastModifiedDate는 JPA Auditing 활성화(@EnableJpaAuditing)가 없으면 안 채워짐
• createDt는 updatable=false로 두는 게 일반적으로 안전 (생성일은 수정되면 안 되니까)