HS_Developer

[코드트리 후기] 북마크로 나만의 복습 루틴 만들기

HS0601 — Fri, 29 May 2026 10:02:02 +0900

코드트리에서 좋은 점은 북마크를 할 수 있다는 것이다

나는 북마크를 저장용으로 쓰기 보다, 다음 날 다시 풀 문제를 모두 담아두는 오답노트그릇으로 사용하고 있다

문제를 풀다보면 한 번에 이해한 것 같아도 다음 날 다시 풀면 반복문 범위, 조건 처리, 출력 형식 같은 부분에서 또 헷가릴 때가 있는데 다시 봐야 할 문제는 북마크에 넣어두고 다음 날 바로 복습하는 방식으로 활용한다

북마크 기능이 없다면 어제 풀었던 문제를 다시 찾는 과정이 번거로웠을 것 같다 하지만 북마크에 담아두면 다시 풀 문제만 모아서 볼 수 있어서 복습 흐름이 끊기지 않는다

이번에 느낀 점은 코딩테스트 훈련은 문제를 N개 푸는 만큼 내가 헷갈린 문제를 다시 풀어보는 과정도 중요하다는 것이다

앞으로도 코드트리 커리큘럼을 따라가면서 어려웠던 문제는 북마크에 모아두고 다음 날 복습하는 루틴을 이어가려고 한다

다시 풀어본 문제

북마크 해두고 다시 풀어본 문제는 배열의 값을 3배로! 문제다

간략하게, 3행 3열의 배열을 입력 받고

각 값을 3배로 만들어서 출력하는 문제

다시 풀면서 2차원 배열에서는 바깥 반복문이 행을 담당하고

안쪽 반복문이 열을 담당한다는 점을 다시 확인할 수 있었다

또 배열에 값을 저장한 뒤 출력할 수 있지만 이 문제처럼 입력받은 값을 바로 3배로 계산해서 출력하는 방식도 가능하다는 점이다

import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        // Please write your code here.
    Scanner sc = new Scanner(System.in);

     int[][] array = new int[3][3];

     for(int i = 0; i < 3; i++){
        for(int j = 0; j < 3; j++){
            array[i][j] = sc.nextInt();

             System.out.print(array[i][j] * 3 + " ");
        }
        System.out.println();
     }
    }
}

[Redis] DB 부하를 줄이기 위한 Redis

HS0601 — Fri, 22 May 2026 18:11:12 +0900

Redis란 무엇인가
왜 Redis를 쓰는가 (기존 DB와 차이)
Redis 자료구조 6가지
TTL (Time To Live)
영속성 (Persistence) RDB vs AOF
싱글 스레드인데 왜 빠른가
캐싱 전략 4가지
메모리 관리 (Eviction Policy)
Spring Boot에서 Redis 사용하기

Redis란?

레디스는 Remote Dictionary Server의 약자다

2009년 이탈리아 개발자 Salvatore Sanfilippo 가 MySQL 기반 실시간 로그 분석 시스템이 너무 느린 걸 해결하고자 만들었다 처음엔 개인 프로젝트였는데 오픈소스로 공개되면서 전세계적으로 퍼졌다

한줄로 정의하면 RAM에 데이터를 저장하는 Key-Value 기반 데이터 저장소

Key              Value
post:views:42    200
user:session:abc {"id": 1, "name": "민수"}

Key로 데이터를 저장하고 Key로 데이터를 꺼낸다 그래서 구조가 단순하기 때문에 빠르다

왜 Redis를 쓰는가?

MySQL 같은 일반 DB와 비교

MySQL은 데이터를 디스크(HDD/SSD)에 저장한다 Redis는 데이터를 RAM에 저장한다

RAM이 디스크보다 얼마나 빠르냐면

	접근 속도
HDD	~10ms
SSD	~0.1ms
RAM	~0.0001ms

숫자로 보면 RAM이 SSD보다 1000배 빠르다 이게 Redis가 빠른 근본적인 이유다

근데 MySQL이 있는데 왜 Redis를 쓰냐면 MySQL 혼자로도 물론 동작은 한다 근데 트래픽이 많아지면 문제가 생긴다

예를들어 게시글 조회수를 MySQL에 바로 쓴다고 가정해보자

사용자 1000명이 동시에 같은 게시글을 조회한다
→ MySQL에 UPDATE 쿼리 1000개 동시 발생
→ MySQL 락 경쟁
→ 처리 지연
→ 서비스 느려짐

즉 Redis는 RAM에 저장하고 원자적으로 처리하니까 이 1000개를 빠르게 소화할 수 있다

정리하면, Redis는 MySQL을 대체하는 게 아니라 MySQL의 부하를 줄이기 위해 앞단에 두는 것이다

[Spring Boot 서버] → [Redis 서버] (별도 프로세스, 보통 도커)
→ [MySQL 서버] (별도 프로세스)

Redis 자료구조 6가지

Redis가 단순 캐시랑 다른 점이 여기서 나온다 Key - Value저장이 아니라 Value에 다양한 자료구조를 지원한다

1. String 단순한 값 하나

가장 기본 자료구조로 문자열, 숫자 모두 저장이 가능하다

SET  name  "민수"
GET  name           → "민수"

SET  count  0
INCR count          → 1   (원자적 +1)
INCRBY count 5      → 6   (원자적 +N)
DECR count          → 5   (원자적 -1)

INCR이 중요한 이유는 원자적으로 실행된다는 것

동시에 1000명이 INCR을 쳐도 누락 없이 정확히 1000개 증가한다 MySQL에서 UPDATE count = count +1 동시에 치면 Lost Udpate 발생하는 것과 대조된다

주요 사용처 : 조회수 카운터, 세션 토큰 저장, 캐시

2. List 순서가 있는 목록, 양쪽 끝에서 넣고 뺄 수 있음

순서가 있는 문자열 목록으로 양쪽 끝에서 push/pop 가능하다

RPUSH  queue  "작업1"      → [작업1]
RPUSH  queue  "작업2"      → [작업1, 작업2]
LPUSH  queue  "긴급작업"   → [긴급작업, 작업1, 작업2]

LPOP   queue              → "긴급작업"
RPOP   queue              → "작업2"

LRANGE queue 0 -1         → ["작업1"]  (전체 조회)

L은 Left의 앞, R은 Right 뒤

주요 사용처 : 작업 큐, 최근 방문 기록, 알림 목록

3. Hash 하나의 키 안에 필드-값 쌍 여러 개

하나의 Key 안에 필드 - 값 쌍을 여러 개 저장하는 것으로 Java의 Map이랑 비슷하다

HSET  user:1  name  "민수"
HSET  user:1  age   "30"
HSET  user:1  role  "backend"

HGET   user:1  name          → "민수"
HGETALL user:1               → {name: 민수, age: 30, role: backend}
HDEL   user:1  role          → role 필드 삭제

String으로 하면 user:1:name, user:1:age 키를 여러 개 만들어야 하는데 Hash는 하나의 키로 묶을 수 있다

주요 사용처 : 사용자 세션 정보, 객체 캐싱

4. Set 중복 없는 집합, 순서 없음

중복을 허용하지 않는 문자열 집합으로 순서가 없다

SADD  tags  "java"
SADD  tags  "spring"
SADD  tags  "java"      → 이미 있어서 무시됨

SMEMBERS tags            → {"java", "spring"}
SISMEMBER tags "java"   → 1 (있음)
SISMEMBER tags "python" → 0 (없음)

SINTER tags1 tags2       → 교집합
SUNION tags1 tags2       → 합집합
SDIFF  tags1 tags2       → 차집합

주요 사용처 : 좋아요 누른 사용자 목록(중복방지), 팔로워 목록, 태그

5. Sorted Set (ZSet) 점수 있는 집합, 점수 기준 자동 정렬

Set인데 각 요소에 score(점수)가 있고 score 기준으로 자동 정렬된다

ZADD   ranking  100  "post:42"
ZADD   ranking  200  "post:7"
ZADD   ranking  50   "post:1"

ZINCRBY  ranking  1  "post:42"     → post:42 score = 101

ZREVRANGE ranking 0 2 WITHSCORES
→ [post:7(200), post:42(101), post:1(50)]  (높은 순)

ZRANGE ranking 0 2 WITHSCORES
→ [post:1(50), post:42(101), post:7(200)]  (낮은 순)

ZSCORE  ranking  "post:42"         → 101
ZRANK   ranking  "post:42"         → 1  (0부터 시작, 낮은 순 기준 순위)
ZREVRANK ranking "post:42"         → 1  (높은 순 기준 순위)

주요 사용처 : 인기글 랭킹, 리더보드, 인기순 정렬

6. HyperLogLog 고유 방문자 수 추정

정확한 값은 아니지만 메모리 극소로 고유 방문자 수를 추정하는 특수자료구조

PFADD  visitors  "user:1"
PFADD  visitors  "user:2"
PFADD  visitors  "user:1"   → 중복 무시

PFCOUNT visitors             → 2 (±0.81% 오차)

정확도는 99.19%인데 메모리는 항상 최대 12KB만 쓴다 정확한 숫자가 필요 없고 대략적인 UV(순방문자)만 필요할 때 쓴다

주요 사용처 : 순방문자 수 집계

TTL (Time To Live)

TTL은 데이터의 유효 기간이다 설정한 시간이 지나면 Redis가 해당 키를 자동으로 삭제한다

SET  token  "abc123"
EXPIRE  token  3600         → 3600초(1시간) 후 삭제

# 또는 처음부터 같이 설정
SET  token  "abc123"  EX  3600

TTL  token              → 3595  (남은 시간 초 단위)
TTL  token              → -1    (TTL 없음, 영구)
TTL  token              → -2    (키 존재하지 않음)

PERSIST  token          → TTL 제거 (영구 저장으로 변경)

주요 사용처 : JWT 리프레시 토큰, 이메일 인증코드 , 임시 캐시

영속성 (Persistence) - RDB vs AOF

Redis가 RAM에 저장하면 서버 재시작할 때 데이터 날아가는 거 아닌가싶은데 맞다 근데 Redis는 이걸 보완하는 두가지 방식을 제공하고 있다

1. RDB (Redis Database Snapshot)

특정 시점의 데이터를 통째로 스냅샷을 찍어서 디스크에 저장하는 방식이다

# redis.conf 설정
save 900 1      → 900초 안에 1번 이상 변경되면 저장
save 300 10     → 300초 안에 10번 이상 변경되면 저장
save 60 10000   → 60초 안에 10000번 이상 변경되면 저장

장점 : 파일 하나로 전체 복원가능, 성능 영향 적음
단점 : 마지막 스냅샷 이후 데이터 유실 가능 있음

2. AOF

모든 쓰기 명령어를 로그 파일에 순서대로 기록하는 방식이다

# redis.conf 설정
appendonly yes
appendfsync everysec   → 1초마다 디스크에 sync

장점 : 데이터 유실이 최대 1초치로 줄어든다
단점 : 파일이 계속 커진다, RDB보다 복원 느림

3. 어떻게 쓰냐

	RDB	AOF
데이터 유실	최대 수 분	최대 1초
성능 영향	적음	약간 있음
복원 속도	빠름	느림

실무에서는 RDB + AOF 둘 다 켜는 경우가 많다

싱글스레드인데 왜 빠른가?

Redis는 명령어 처리를 싱글 스레드로 한다 빠른 이유는 3가지

RAM 접근 자체가 빠르다 아무리 싱글 스레드여도 RAM에서 읽고 쓰는 속도가 디스크보다 압도적으로 빨라서다
I/O Multiplexing 네트워크 연결 자체는 멀티 플렉싱으로 여러 클라이언트가 동시에 처리한다
명령어 실행만 싱글 스레드(INCR, GET, ZADD 같은 실제 Redis 명령어를 실행하는 건 싱글스레드로 순서대로 하나씩 처리)
싱글 스레드가 오히려 장점이다 멀티 스레드면 락, 컨텍스트 스위칭 오버헤드가 생긴다 싱글스레드는 이 오버헤드가 없고 명령어가 순차처리되니까 원자성이 자동으로 보장된다

동시에 1000명이 INCR post:views:42 실행
→ Redis 내부: 1번, 2번, 3번 ... 순서대로 처리
→ 결과: 정확히 1000 증가, Lost Update 없음

MySQL에서 이걸 하려면 락이 필요한데 Redis는 싱글스레드 덕분에 락 없이 원자성을 보장한다

캐싱 전략 4가지

Redis를 캐시로 쓸 때 어떤 패턴으로 읽고 쓸 건지 결정해야 한다

1. Cache Aside (Look Aside)

앱이 직접 Redis와 DB를 관리하는 패턴이다

읽기:
1. Redis에서 먼저 조회
2. 있으면 (Cache Hit) → Redis 값 반환
3. 없으면 (Cache Miss) → DB 조회 → Redis에 저장 → 반환

쓰기:
1. DB에 바로 씀
2. Redis 캐시 삭제 (다음 읽기 때 DB에서 다시 로드)

장점 : Redis 장애 시 DB로 fallback 가능하다

단점 : Cache Miss 첫 요청은 느리며 DB와 Redis 일관성을 직접 관리해야 한다

2. Read Through

캐시가 DB 앞에서 프록시처럼 동작한다 앱은 항상 캐시에만 요청한다

앱 → Redis 요청
        Cache Hit  → 반환
        Cache Miss → Redis가 알아서 DB 조회 → 저장 → 반환

Cache Aside 랑 비슷한데 DB 조회 책임이 앱이 아니라 캐시 레이어에 있다

3. Write Through

DB에 쓸 때 Redis에도 동시에 쓴다

앱 → Redis 쓰기 → DB 쓰기 (동기)

장점 : 항상 Redis = DB 일관성 보장한다
단점 : 쓸 때마다 두 곳에 쓰니까 느리다 안 읽히는데 데이터도 캐시에 쌓인다

4. Write Back (Write Behind) — 인기수에 쓰는 패턴

Redis에 먼저 쓰고 나중에 배치로 DB에 반영한다

앱 → Redis만 씀 (즉시)
        ↓
스케줄러 (주기적으로)
        → Redis 값 읽어서 DB 반영

장점 : DB 쓰기 횟수 대폭 감소, 고빈도 쓰기에 최적
단점 : Redis 장애 시 미반영 데이터 유실 가능

메모리 관리 (Eviction Policy)

Redis는 RAM을 쓴다 RAM은 무한하지 않으니까 꽉 차면 어떻게 할 건지 정책을 설정해야 한다

# redis.conf
maxmemory 256mb              → 최대 256MB 사용
maxmemory-policy allkeys-lru → 꽉 차면 LRU 기준으로 삭제

Eviction Policy 종류

정책	설명
noeviction	꽉 차면 에러 반환 (기본값)
allkeys-lru	전체 키 중 최근에 안 쓴 거 삭제
volatile-lru	TTL 있는 키 중 최근에 안 쓴 거 삭제
allkeys-random	전체 키 중 랜덤 삭제
volatile-ttl	TTL 가장 짧은 거 먼저 삭제

캐시 용도면 allkeys-lru 가 일반적이며 자주 쓰는 데이터는 남고, 안 쓰는 데이터는 알아서 지워진다

Spring Boot에서 Redis 사용하기

implementation 'org.springframework.boot:spring-boot-starter-data-redis'

위 의존성만 추가해도 자동으로 RedisTemplate 빈을 만들어준다 (Auto Configuration)

spring:
  data:
    redis:
      host: localhost
      port: 6379

Spring Boot에서는 Redis 의존성과 접속 정보를 설정한 뒤 RedisTemplate 등을 통해 Redis를 사용할 수 있다
중요한 것은 Redis를 단순 캐시로만 보는 것이 아니라, 조회수 카운터, 세션 저장, 인기글 랭킹처럼 목적에 맞는 자료구조와 캐싱 전략을 선택하는 것이다

[Troubleshooting]FULLTEXT 인덱스 누락

HS0601 — Thu, 21 May 2026 20:49:34 +0900

1. 문제

부하테스트 시나리오 B 개선하여 merge 후, 운영 환경에서 게시글 검색 API 호출 시 500이 떴다

(시나리오 B 분석 내용은 여기서 확인할 수 있다)

GET <https://api.coreboard-api.xyz/posts/search?keyword=image&page=0&size=10> 500 (Internal Server Error)

게시글 전체 조회는 정상이었기 때문에 프론트 요청 문제는 아니었다 검색 API 내부에서 터지는 거라고 판단했다

2. 분석 - 원인 좁히기

검색 쿼리를 먼저 확인했다

MATCH(p.title, p.content) AGAINST(:keyword IN BOOLEAN MODE)

MATCH ... AGAINST 구문은 대응하는 FULLTEXT 인덱스가 있어야 동작한다 운영 DB 인덱스를 확인했다

SHOW INDEX FROM post;

결과

PRIMARY
uk_post_title
FK7ky67sgi7k0ayf22652f7763r
idx_post_board_status_created_at

FULLTEXT 인덱스가 없었다 원인은 여기였다

3. 원인

코드에서는 title, content를 대상으로 전문 검색을 하도록 짜여 있었는데, 운영 DB에는 그에 대응하는 인덱스가 없었다

검색 쿼리: MATCH(title, content) AGAINST(...)
운영 DB: FULLTEXT(title, content) 인덱스 없음
결과: 쿼리 실행 실패 → 500

4. 해결

로컬 DB에서 먼저 검증했다

CREATE FULLTEXT INDEX ft_post_title_content
ON post (title, content);

curl -i "http://localhost:8080/posts/search?keyword=test&page=0&size=10"

HTTP/1.1 200

방향이 맞는 걸 확인했으니, 운영 DB를 직접 수정하는 대신 Flyway migration 파일로 반영했다

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

위처럼 파일(Flyway)을 생성하여 아래 코드를 넣어주었다

CREATE FULLTEXT INDEX ft_post_title_content
ON post (title, content);

배포 후 migration이 정상 적용됐는지 확인했다

SELECT installed_rank, version, description, success
FROM flyway_schema_history
ORDER BY installed_rank DESC
LIMIT 5;

installed_rank: 3
version: 20260521.02
description: add fulltext index post title content
success: 1

인덱스도 확인했다

SHOW INDEX FROM post WHERE Key_name = 'ft_post_title_content';

내부랑 외부 둘 다 확인했다

curl -i "http://localhost:8080/posts/search?keyword=test&page=0&size=10"
curl -i "https://api.coreboard-api.xyz/posts/search?keyword=test&page=0&size=10"

둘 다 
HTTP/1.1 200

5. 성과 및 배운 점

API 코드가 멀쩡해도 운영 DB 스키마가 따라오지 않으면 500이 난다 로컬에서는 FULLTEXT 인덱스를 직접 만들어서 쓰고 있었으니 당연히 로컬에선 안 터졌다

그리고 운영 DB를 직접 건드리는 대신 Flyway migration으로 남겨두면, 나중에 새 환경에 배포해도 동일한 스키마가 자동으로 재현된다. 이번에 Flyway를 도입한 이유가 바로 이거다

검색 500 확인
→ 검색 쿼리 확인
→ 운영 DB 인덱스 확인
→ FULLTEXT 인덱스 누락 확인
→ 로컬 검증
→ Flyway migration으로 반영
→ 배포 후 migration 적용 확인
→ 내부/외부 200 확인

[Troubleshooting]Flyway 도입 후 기존 운영 DB에서 배포 실패 해결

HS0601 — Thu, 21 May 2026 20:35:09 +0900

https://winwin0219.tistory.com/332

[DB] Flyway — ddl-auto=update와 무엇이 다른가

Flyway란?Spring Boot 프로젝트를 운영하다 보면 DB 스키마가 변할 일이 생긴다 post 테이블에 view_count 추가users 테이블에 인덱스 추가 새로운 attachment 테이블 생성이걸 개발자가 직접 운영 DB에 접속해

winwin0219.tistory.com

1. 문제

GitHub Actions를 통해 CoreBoard를 GCP 서버에 배포하던 중, 배포 마지막 단계에서 실패가 발생했다

빌드와 jar 업로드는 완료되었지만, 서버 재시작 이후 healthcheck 단계에서 localhost:8080에 연결하지 못했다

curl: (7) Failed to connect to localhost port 8080 after 0 ms: Couldn't connect to server
Waiting for CoreBoard... (1/60)
Waiting for CoreBoard... (2/60)
...

처음에는 Spring Boot가 아직 8080 포트를 열지 못한 문제처럼 보였다 하지만 localhost:8080 연결 실패는 원인이 아니라 결과였다

실제 문제는 서버 내부에서 Spring Boot 애플리케이션이 정상 기동하지 못하고 있던 것이었다

2. 분석 - 원인 좁히기

GCP 서버에 접속해 로그를 확인했다

sudo systemctl status coreboard --no-pager
sudo journalctl -u coreboard -n 100 --no-pager

Spring Boot가 Flyway 초기화 단계에서 죽고 있었다

Found non-empty schema(s) `coreboard` but no schema history table.
Use baseline() or set baselineOnMigrate to true to initialize the schema history table.

coreboard DB에는 이미 테이블이 있다
근데 flyway_schema_history는 없다
Flyway 입장에서는 이 DB가 어떤 상태인지 알 수 없다

[실제 흐름]
기존 운영 DB에 이미 테이블 존재
→ Flyway 신규 도입
→ flyway_schema_history 없음
→ Flyway가 DB 상태 판단 불가 → 초기화 실패
→ Spring Boot 기동 실패
→ 8080 포트가 열리지 않음
→ GitHub Actions healthcheck 실패

또한 VM 사양이 작다 보니 가끔 프로세스가 죽는 일이 있어서 Restart=always를 걸어뒀는데, 이번엔 Flyway 오류로 죽는 거라
5초마다 재시작 → 같은 오류 → 또 죽는 루프가 반복됐다

로그가 계속 새로 쌓인 이유가 그것이었다

Restart=always
RestartSec=5

3. 원인

기존 운영 DB에 Flyway를 뒤늦게 도입하면서 기준점이 없었던 것이 문제였다

운영 DB에는 이미 테이블이 있었다

board
post
users
comments
attachment
...

Flyway를 처음 도입했으니 당연히 flyway_schema_history는 없었으며

Flyway가 이 상태에서 임의로 migration을 실행하면 기존 테이블과 충돌하기 때문에, 안전하게 실행을 멈춘 것이었다

4. 해결

/etc/coreboard.env에 baseline 설정을 추가했다

SPRING_FLYWAY_BASELINE_ON_MIGRATE=true
SPRING_FLYWAY_BASELINE_VERSION=0

설정	의미
SPRING_FLYWAY_BASELINE_ON_MIGRATE=true	기존 테이블이 있는 DB를 Flyway 관리 대상으로 등록
SPRING_FLYWAY_BASELINE_VERSION=0	현재 운영 DB 상태를 0번 기준점으로 간주

baseline은 이미 테이블이 있는 DB에 Flyway를 처음 도입할 때만 필요한 설정이다 로컬은 Flyway 도입 시점에 새로 구성했기 때문에 해당하지 않아서 운영 서버에서만 따로 관리하기로 판단했다

sudo systemctl restart coreboard

이후 Flyway 문제는 해결되었지만, 2차 문제가 있었다

GCP 저사양 VM에서 Spring Boot 기동 시간이 너무 길었다

Started CoreBoardApplication in 323.497 seconds

약 5분이 걸렸다

기존 healthcheck는 최대 10분을 기다리도록 짜여 있었는데, ssh-action 자체 실행 제한 시간과 맞물리면 실패 로그조차 제대로 못 보고 끊길 수 있었다

command_timeout과 healthcheck 횟수를 함께 늘렸다

command_timeout: 20m

for i in {1..90}; do
  if curl -fsS <http://localhost:8080/actuator/health> > /dev/null; then
    echo "CoreBoard is healthy"
    exit 0
  fi

  echo "Waiting for CoreBoard... ($i/90)"
  sleep 10
done

healthcheck 최대 대기 시간: 90회 × 10초 = 15분
ssh-action 최대 실행 시간: 20분

둘 다 200 반환. 배포 성공.

5. 성과 및 배운 점

겉으로는 healthcheck 실패처럼 보였지만 실제 원인은 Flyway baseline 설정 누락이었다

운영 서버 로그를 직접 확인하지 않았다면 원인을 한참 헤맸을 것이다

이번에 확인한 것들

기존 운영 DB에 Flyway를 뒤늦게 도입할 때는 baseline 설정이 필요하다
GitHub Actions healthcheck 실패는 원인이 아니라 결과일 수 있다
배포 실패 시 Actions 로그만 보면 안 된다 서버의 journalctl까지 봐야 한다
Restart=always는 운영 복구엔 유용하지만 반복 실패 상황에서는 로그 분석을 어렵게 만든다
healthcheck 대기 시간은 로컬 기준이 아니라 실제 운영 서버 기준으로 잡아야 한다

배포 실패
→ journalctl 확인
→ Flyway 초기화 실패
→ baseline 설정 추가
→ healthcheck 대기 시간 조정
→ 배포 성공

[DB] Flyway — ddl-auto=update와 무엇이 다른가

HS0601 — Thu, 21 May 2026 20:11:22 +0900

Flyway란?

Spring Boot 프로젝트를 운영하다 보면 DB 스키마가 변할 일이 생긴다

post 테이블에 view_count 추가
users 테이블에 인덱스 추가
새로운 attachment 테이블 생성

이걸 개발자가 직접 운영 DB에 접속해서 SQL 날리면 어떻게 될까?

누가 언제 어떤 SQL을 실행했는지 기록이 없다
로컬 DB랑 운영 DB랑 구조가 달라지는 시점도 모른다
팀이면 더 심각해진다 (누군가 이미 실행한 걸 또 실행할 수도 있다)

Flyway는 이 문제를 해결하는 도구이며 SQL 파일을 버전 번호로 관리한다

V1__create_post_table .sql
V2__add_view_count_column.sql
V3__add_post_title_index.sql

그리고 애플리케이션이 실행될 때 자동으로 이 파일들을 순서대로 실행해준다

ddl-auto = update가 하는 일

Hibernate가 엔티티 클래스를 보고 이 컬럼이 없네? 추가해줄게하고 자동으로 ALTER TABLE을 날린다

// 엔티티에 필드 추가
private String thumbnailUrl;

// Hibernate가 알아서 
ALTER TABLE post ADD COLUMN tumbnail_url VARCHAR(255);

그런데 문제가 있다

ddl-auto = update의 치명적인 한계

1. 컬럼 삭제를 못한다

// 이 필드를 지우면
private String thumbnailUrl; // 삭제

Hibernate는 컬럼을 절대 DROP하지 않는다 안전 때문에 설계 자체가 그러한데, 그래서 엔티티에서 필드를 지워도 DB 컬럼은 그대로 남는다 운영 DB가 서서히 엔티티랑 달라지기 시작한다

2. 데이터 변환 로직을 못 쓴다

예를들어 이런 작업이 필요하다고 가정해보자

-- status 컬럼 타입을 VARCHAR -> INT로 바꾸면서 
-- 기존 데이터도 변환해야 한다 
UPDATE post SET status_code = CASE
	WHEN status = 'ACTIVE' THEN 1
	WHEN status = 'DELETED' THEN 0
END;

Hibernate는 이런 데이터 마이그레이션 로직을 실행할 수가 없다

엔티티 타입 바꿨다고 기존 데이터를 알아서 변환해주진 않는다

3. 어떤 변경이 언제 실행됐는지 기록이 없다

팀프로젝트라면 더 심각해진다

A가 배포함 → 컬럼 추가됨
B가 배포함 → 또 다른 컬럼 추가됨
근데 로컬 DB에는 어떤 게 적용됐는지 아무도 모른다

Flyway는 flyway_schema_history에 전부 기록되니까 지금 DB가 어떤 상태인지 명확하게 알 수 있다

4. 운영 환경에서 udpate 자체가 위험하다

예기치 않는 DDL이 운영 DB에 자동으로 날아가는 구조다 그래서 실무에서는 운영 환경 ddl-auto는 무조건 none 또는 validate로 설정하고 스키마 변경은 반드시 직접 검토한 SQL로만 한다

	ddl-auto = update	Flyway
컬럼 추가	자동	SQL로 명시
컬럼 삭제	안 됨	SQL로 명시
데이터 변환	안 됨	SQL로 명시
변경 이력 관리	없음	history 테이블
운영 안전성	위험	안전

따라서 ddl-auto = update는 로컬 개발 편의용이며 Flyway는 운영 DB 변경을 안전하게 관리하는 도구다

flyway_schema_history 테이블

Flyway가 어디까지 실행했는지 기억하는 방법이 있어야한다 그 기억 장소가 바로 flyway_schema_history 테이블.

Flyway가 처음 실행되면 이 테이블을 DB에 만들고 SQL 파일을 실행될 때마다 아래처럼 기록한다

version	description	success
1	create post table	true
2	add view count column	true

다음에 애플리케이션을 재시작하면 Flyway가 이 테이블을 보고 V1, V2는 이미 실행됐으니까 V3부터 실행하면 되겠다~고 판단한다

만일 기존 운영 DB에 Flyway를 뒤늦게 도입하면 어떻게 될까?

여기서 문제가 생긴다 (참고로 내가 겪은 문제다)

처음부터 Flyway를 쓴 게 아니라 중간에 도입하면 운영 DB 안에는 이미 board, post, users같은 테이블이 있다

근데 flyway_schema_history 테이블은 없다 (한 번도 Flyway를 쓴 적이 없으니까)

Flyway 입장에서 생각해보면,

DB이 이미 있네?
근데 내가 관리한 기록이 없잖아?
아니 대체 이게 V1 이전 상태야? V3 이후 상태야? 나는 알 수가 없어!
만약 내가 V1 SQL을 실행하면 이미 존재하는 테이블에 또 CREATE TABLE하는 건데 그럼 에러 터지잖아!

그래서 Flyway는 나는 모르겠으니가 실행 안 할게~하고 멈춰버린다

baseline이란?

이 상황을 해결하는 Flyway옵션이 바로 baseline이다

지금 이 DB 상태를 Flyway의 시작점 (0번)으로 인정해줘
여기서부터 내가 관리할게

SPRING_FLYWAY_BASELINE_ON_MIGRATE=true   → 기존 DB를 시작점으로 인정해줘
SPRING_FLYWAY_BASELINE_VERSION=0         → 그 시작점을 0번으로 등록해줘

이렇게하면 Flyway는 flyway_schema_history 테이블을 생성하고 현재 상태를 0번으로 기록한 뒤 V1부터 관리를 시작한다

파일 네이밍 규칙과 위치

Flyway가 SQL 파일을 찾는 기본 경로는 아래와 같다

src/
└── main/
    └── resources/
        └── db/
            └── migration/        ← 여기
                ├── V1__create_users_table.sql
                ├── V2__create_post_table.sql
                └── V3__add_view_count_column.sql

이 경로는 Flyway가 약속으로 정해놓은 기본 값이다 별도 설정 없이 이 경로에 파일을 넣으면 자동으로 인식한다

파일 이름 규칙도 정해져 있다 대표적으로 두 가지 방식이 있는데

1. 순번 방식

V1__create_users_table.sql
V2__create_post_table.sql
V3__add_view_count_column.sql

2. 날짜 기반 방식 ← 이게 내가 사용한 방식이다

V20260521_01__create_users_table.sql
V20260521_02__add_fulltext_index_post_title_content.sql
V20260522_01__add_attachment_table.sql

즉 버전 번호는 V1, V2처럼 순번으로 쓸 수 있고 V20260521_01처럼 날짜 기반으로 쓸 수도 있다

팀 프로젝트에서는 날짜기반이 버전 충돌을 피하기 더 유리하다

[순번 방식에서 충돌이 생기는 상황]

A랑 B가 같은 프로젝트에서 동시에 작업 중이라고 가정해보자

현재 최신 마이그레이션 : V4__...sql

A : 새 기능 개발 중 → V5__add_alarm_table.sql 작성

B : 다른 기능 개발 중 → V5__add_report_table.sql 작성

둘 다 V5로 만든 것. 각자 로컬에서는 문제 없이 돌아간다 근데 둘 다 머지하면

V5__add_alarm_table.sql
V5__add_report_table.sql
← 버전 번호가 같은 파일이 두 개

Flyway는 같은 버전 번호가 두 개면 오류 내고 실행 자체를 거부한다

그렇다면 왜 날짜기반은 충돌이 안 날까?

A: V20260521_01__add_alarm_table.sql
B: V20260521_02__add_report_table.sql

같은 날 작업했어도 그 날의 순번이 다르면 버전이 다르기 때문에. 물론 같은 날 같은 순번을 동시에 만드는 극단적인 경우는 있을 수 있는데, 순번 방식보다 충돌 가능성이 훨씬 낮다

[코테 공부] 잔디 심기로 코딩테스트 1일 1문제 습관 형성하기 (feat. 코드트리)

HS0601 — Wed, 20 May 2026 20:41:35 +0900

코테 때문에 훈련한다기 보단, 사고력을 기르려고 꾸준히 노력하고 있다

그런데 그 꾸준히가 잘 안 되는 성격이라서 코드트리의 청약 챌린지에 합류하게 되었다

코드트리에서 문제를 풀면 학습 기록이 남고, 깃허브와 연동하면 내가 공부한 흔적이 잔디처럼 쌓인다 그래서 오늘공부했다~로 끝내는 게 아니라 눈에 보이는 기록으로 남기 때문에 하루를 그냥 넘기기 아깝다는 생각이 들었다 특히 깃허브 잔디는 개발 공부를 하는 입장에서 익숙한 기록 방식이라 더 체감이 컸다

예전에는 코딩테스트 공부를 할 때 문제 하나를 오래 붙잡다가 지치거나 며칠 쉬면 다시 시작하기 어려웠다 그런데 코드트리에서는 난리도와 챕터가 나뉘어 있어서 오늘은 1문제만 풀자처럼 작게 시작하기 좋다 문제를 많이 푸는 것보다 중요한 건 끊기지 않는 흐름이라고 느꼈다

다른 학습 서비스는 강의나 문제 풀이 자체에 집중되는 경우가 많았는데 코드트리는 학습 리마인더나 깃허브 연동처럼 계속 돌아오게 만드는 장치가 있다는 점이 좋았다

앞으로도 하루에 최소 1문제라도 풀면서 코테 감각을 유지하려고 한다 처음부터 완벽하게 풀기보다 매일 문제를 읽고 생각하는 시간을 만드는 것이 목표다 코드트리와 깃허브 잔디를 같이 활용하면 코딩테스트 독학도 조금 더 루틴처럼 이어갈 수 있을 것 같다

Bottleneck Analysis

HS0601 — Wed, 20 May 2026 11:15:30 +0900

왜 느린가를 바로 단정하지 않고 응답 지연 발생 구간을

서버 전체 → 특정 API → 특정SQL → 특정 SQL 연산비용 순서로 좁혀가야 한다

원인 좁히는 순서

1 단계 : 전체 서버 문제인지 확인

서버 전체가 느린가, 특정 API만 느린가?

테스트 결과

검색목록 조회 API 평균 19초, p95 20초
상세 조회 API p95 12ms

→ 전체 서버 장애나 네트워크 문제라기 보다 검색 목록 조회 API에 병목이 집중되어있다

이게 첫번째 관찰

2단계 : 서버 자원 부족인지 확인

서버자원 (CPU, JVM Memory, DB Connection) 부족인지 확인해야 한다

CPU 지속적으로 높지 않았음
JVM Memory 급격한 증가없음
DBPending Connection 0 커넥션 기다리는 요청 없음

(만약 CPU가 높은 수준으로 지속되지 않았고 Heap Memory 급증/OOM 징후도 없고 DB Pending Connection도 0이라면)

→ 서버 자원 포화나 커넥션 풀 부족 보다는 특정 요청 내부의 처리 비용이 큰 상황으로 본다

3단계 : 애플리케이션 로직 문제인지 DB 쿼리 문제인지 확인

검색 API 1번 호출 할 때 실제로 어떤 SQL이 나가는지 확인했다 Page 기반 조회라서 SQL이 2개 나간다

목록 조회 SQL(실제 게시글 데이터)
count query (전체 몇 건인지 세는 SQL)

이 두개를 EXPLAIN으로 실행 계획을 봐야 한다

확인 대상	보는 이유
목록 조회 SQL	검색 조건이 어떻게 SQL로 나가는지 확인
count query	Page 조회 때문에 전체 개수 계산이 붙는지 확인
SQL 개수	N+1 또는 불필요한 반복 쿼리 확인
SQL 실행 시간	진짜 오래 걸리는 SQL 특정

4단계 : 실행 계획으로 DB 내부 비용 확인

SQL을 확인했으면 바로 EXPLAIN을 봐야 한다

EXPLAIN 항목	의미
key	어떤 인덱스를 썼는지
type	접근 방식이 괜찮은지
rows	대략 몇 건을 검사할지
Extra	filesort, temporary 같은 추가 비용이 있는지
filtered	조건 통과 비율 추정

만약 검색 목록 조회 시 SQL 인덱스를 탔으나 row가 많고 Using temporary; Using filesort라면

→ 인덱스 미사용 문제가 아니라 인덱스를 사용했음에도 검색 조건과 정렬 조건을 처리하기 위해 너무 많은 후보 행을 검사하고 정렬하는 문제다

인덱스를 탔다 = 찾기 시작할 위치를 잡았다정도다 근데 다음부터가 문제다

인덱스가 board_id, status, created_at 순으로 되어있는데

board_id = 2

status = 'PUBLISHED'까지는 인덱스로 어느정도 범위를 잡았음 근데 그 결과가 70만건

5단계 : count qeury 비용도 같이 볼 것

Page 조회면 보통 목록 조회 쿼리만 나가는 게 아니라 count query도 나간다

→ 응답 지연은 목록 조회 sql 하나만의 문제가 아니라 목록 조회 sql과 count query가 함께 많은 후보 행을 검사하면서 발생하는 것으로 판단한다

LOWER(title) LIKE '%test%' OR content LIKE '%test%'

이 조건으로 걸러내야 하는데 LIKE '%test%'는 앞에 %가 붙어있어서 인덱스로 범위를 줄이는 게 불가능하다

왜냐하면 B-tree 인덱스는 앞에서부터 일치하는 거만 빠르게 찾을 수 있기 때문이다

test로 시작하는 거라면 인덱스로 찾겠는데 %test%는 어디서든 나올 수 있으니까 결국 다 뒤져야 한다

목록 조회는 ORDER BY created_at DESC 정렬이 있다 근데 인덱스 구조상 keyword 조건 처리 때문에 인덱스 순서 그대로 정렬 결과를 뽑는 게 안 된다

그래서 DB가 따로 정렬 작업을 수행해야 한다 이게 Using filesort

이름이 file이라서 파일에 저장하는 것처럼 보이는데 그냥 인덱스 순서만으로 정렬을 못 끝내고 별도 정렬 처리를 했다는 뜻이다

용어	뜻
병목	전체 흐름을 느리게 만드는 가장 느린 구간
p95	요청 100개 중 느린 쪽 5개를 제외했을 때의 상위 응답 시간
Pending Connection	DB 커넥션을 못 받아서 기다리는 요청 수
Count Query	전체 데이터 개수를 세는 쿼리
EXPLAIN	DB가 쿼리를 어떻게 실행할지 보여주는 실행 계획
rows	DB가 검사할 것으로 예상하는 행 수
filesort	인덱스 순서만으로 정렬하지 못해 별도 정렬 작업을 수행하는 것
temporary	중간 결과를 임시 테이블 형태로 만들어 처리하는 것

[코드트리] 반복문을 반복하며 중첩 반복문 약점 극복하기

HS0601 — Sun, 17 May 2026 21:15:45 +0900

오늘은 중첩반복문에 대해 한문제 풀 예정이다

약수가 세 개인 수

[문제]
두 정수 start와 end가 주어집니다.
정수의 약수란, 그 수를 나누었을 때 나머지가 없이 떨어지는 양의 정수를 뜻합니다. 예를 들어, 6의 약수는 1, 2, 3, 6으로 총 네 개입니다.
start 이상 end 이하인 정수 중에서, 약수가 정확하게 세 개인 수의 개수를 구하는 프로그램을 작성해보세요.

[입력]
첫 줄에 두 정수 start와 end가 공백으로 구분되어 주어집니다
제한조건 : 1 <= start <= end <= 1000

[출력]
첫 줄에 조건을 만족하는 정수의 개수를 출력합니다

[예제 설명]
예제 1에서, 조건을 만족하는 수는 4가 유일합니다
3의 약수 : {1, 3}
4의 약수 : {1, 2, 4}
5의 약수 : {1, 5}
6의 약수 : {1, 2, 3, 6}
7의 약수 : {1, 7}

예제 3에서, 조건을 만족하는 수는 4, 9, 25, 49로 총 4개가 있습니다

[입력 예제 1]
입력 : 3 7
출력 : 1
[입력 예제 2]
입력 : 9 16
출력 : 1
[입력 예제 3]
입력 : 1 50
출력 : 4

[내가 한 풀이]

소수제곱 카운트하면되는 문제라는 거까지는 알아냈는데 아직은 간단한 for과 if문 정도만 할 줄 알아서 반복문으로 풀었다

*소수제곱 즉, 2의 제곱, 3의 제곱, 5의 제곱 이런 식인 셈.

num을 start ~ end까지 하나씩 검사하기
각 num마다 약수 개수를 저장할 divisorCount를 0으로 초기화하기
i를 1~num까지 나눠보기
num % i == 0이면 i는 num의 약수
약수가 3개면 answer 증가
마지막에 answer 출력

반복문 두 번 필요

1. 바깥 반복문 : start~end까지 숫자를 하나씩 꺼내기 위한 반복문

2. 안쪽 반복문 : 현재 숫자 num의 약수가 몇 개인지 세기 위한 반복문

import java.util.Scanner;

public class Main{
	public static void main(String[] args){
    	Scanner sc = new Scanner(System.in);
        int start = sc.nextInt();
        int end = sc.nextInt();
        int answer = 0;
        
        for(int num = start; num <= end; num++){
        	int divisorCount = 0;
            for(int i = 1; i <= num; i++){
            	if(num % i == 0){
                	divisorCount++;
                }
            }
            if(divisorCount == 3){
            	answer++;
            }
        }
    	System.out.println(answer);
    }
}

풀이하면서 헷갈렸던 점

약수의 개수를 어디서 초기화해야 하는지

전체 범위에서 약수 개수를 계속 세는 것처럼 생각했는데 실제로는 숫자마다 약수 개수를 따로 세어야 했다

예를 들어 3의 약수 개수와 4의 약수 개수는 서로 다른 값이다 그래서 divisorCount는 바깥 반복문 안에서 매번 0으로 초기화해야 했다

학습하면서 느낀 점

중첩 반복문 문제는 for문을 두 번 쓰는 문법이 아니라 반복해야 하는 일이 두 단계로 나뉘어 있을 때 사용하는 구조라는 것을 알게되었다

1. start~end까지 숫자를 하나씩 확인하는 것

2. 각 숫자마다 1부터 자기자신까지 나누어보며 약수 개수를 세는 것

이 두 작업이 겹쳐있기 때문에 중첩 반복문이 필요했다

코드트리의 커리큘럼은 기본 개념을 먼저 보고, 그 다음 비슷한 유형의 문제를 풀면서 직접 적용해 보는 구조라서 내가 어디서 막히는지 확인하기 좋았다

이번 문제를 통해 반복문 문제를 풀 때 바로 코드를 쓰기 보다 무엇을 반복해야 하는가를 나누어 생각해야 한다는 점을 배웠다

앞으로 반복문 문제를 풀 때 다음 순서로 할 것

1. 입값이 무엇인지 확인한다

2. 반복해야 하는 범위가 어디인지 찾는다

3. 반복문 안에서 매번 초기화해야 하는 값이 있는지 확인한다

4. 조건을 만족하면 어떤 값을 증가시킬지 정한다

5. 출력 위치가 반복문 안인지 밖인지 확인한다

[Transactional] 전파(Propagation) & 격리 수준(Isolation Level)

HS0601 — Fri, 15 May 2026 16:51:06 +0900

트랜잭션의 기본 개념과 Spring 동작 방식
트랜잭션 전파: Propagation
주요 전파 옵션별 동작과 실무 사용 기준
트랜잭션 격리 수준: Isolation Level
실무 설계 기준
자주 하는 실수

1. 트랜잭션의 기본 개념과 Spring 동작 방식

트랜잭션이 뭔뒈!

트랜잭션은 안전벨트다 DB 작업 여러 개를 하나의 작업처럼 묶는 것이다
예를들어 은행 송금을 생각해보자

A 계좌에 만원 차감
B 계좌에 만원 추가

이건 사실 DB입장에서는 작업이 2개다

A 계좌 잔액 update
B 계좌 잔액 update

그런데 1번은 성공하고 2번에서 서버가 터지면 A 돈은 빠졌는데 B 돈은 안 들어가는 대참사가 생긴다 그래서 트랜잭션이 필요하다
둘 다 성공하면 commit, 하나라도 실패하면 rollback

@Transactional을 붙이면 Spring은 대충 이런 식으로 움직인다

@Transactional
public void transfer() {
    accountA.minus(10000);
    accountB.plus(10000);
}

transfer() 호출 → Spring이 트랜잭션 시작 → A 계좌 차감 → B 계좌 증가 → 문제 없으면 commit. 문제 생기면 rollback

그러니까 @Transactional은 DB 변경 작업의 생명줄이다

그렇다면 @Transactional 붙이면 무조건 안전할까?
정확히는 트랜잭션 범위 안에 들어온 DB 작업만 안전하게 묶인다 그리고 Spring은 보통 프록시 방식으로 @Transactional을 적용한다 Spring 공식문서는 프록시 모드에서는 프록시를 통해 들어오는 외부 메서드 호출만 가로챈다고 설명한다
그래서 같은 클래스 안에서 자기 메서드를 직접 호출하면 트랜잭션이 기대대로 안 걸릴 수 있다

@Service
public class OrderService {

    public void order() {
        pay(); // 같은 클래스 내부 호출
    }

    @Transactional
    public void pay() {
        // 트랜잭션 걸릴 것 같지만 기대대로 안 걸릴 수 있음
    }
}

위 코드는 조금 위험하다 왜냐하면 order()에서 pay()를 부를 때 Spring 프록시를 거치지 않고 그냥 자기 내부 메서드를 바로 호출하기 때문이다

Spring 프록시 = 입구 보안요원
외부에서 들어오면 보안요원이 체크함
근데 건물 안에서 옆방으로 바로 가면 보안요원을 안 만남

그래서 @Transactional은 보통 public 서비스 메서드의 외부 호출 경계에 붙인다고 이해하면 된다

2. 트랜잭션 전파: Propagation

전파. 영어로 Propagation.
Propagation - 이미 트랜잭션이 있는데 너도 같이 탈래?
어떤 메서드가 실행될 때, 이미 진행 중인 트랜잭션이 있다면 이 메서드는 그 트랜잭션에 같이 들어갈까?
아니면 자기만의 새 트랜잭션을 만들까?
아니면 트랜잭션 없이 실행할까?라고 이해하면 된다
예를들어

@Transactional
public void order() {
    saveOrder();
    pay();
    sendMessage();
}

여기서 order()는 이미 트랜잭션을 시작했다 그런데 안에서 pay()를 호출한다

@Transactional
public void pay() {
    paymentRepository.save(...);
}

이때 질문은 이렇다 pay()는 order()가 만든 트랜션에 같이 들어갈까? 아니면 pay()만 따로 새 트랜잭션을 만들까?
이거를 결정하는 게 Propagation이다
Spring 공식문서는 transactional propagation을 설명하면서 REQUIRED, REQUIRES_NEW, NESTED 같은 전파 옵션을 구분해서 설명한다
특히 REQUIRES_NEW는 항상 독립적인 물리 트랜잭션을 사용하고 NESTED는 하나의 물리 트랜잭션 안에서 savepoint를 사용한다고 설명한다

물리 트랜잭션이란?

실제 DB connection에서 돌아가는 진짜 트랜잭션

논리 트랜잭션란?

Spring 메서드 단위로 보이는 트랜잭션 범위

suspend란?

기존 트랜잭션을 잠깐 멈춰두는 것

savepoint란?

트랜잭션 중간에 찍어두는 저장 지점

Propagation 옵션을 여러 개 있지만 4개정도만 제대로 알면 된다
1. REQUIRED : 기본값 있으면 같이 타고, 없으면 새로 만든다
2. REQUIRES_NEW : 무조건 새 트랜잭션을 만든다
3. MANDATORY : 기존 트랜잭션이 반드시 있어야 한다
4. NESTED : 기존 트랜잭션 안에 중간 저장점 savepoint를 만든다

3. 주요 전파 옵션별 동작과 실무 사용 기준

1. REQUIRED는 기본값이다

@Transactional
public void order() {
    saveOrder();
    pay();
}

위 코드는 사실

@Transactional(propagation = Propagation.REQUIRED)
public void order() {
}

이거랑 같다고 보면 된다 이미 트랜잭션이 있으면 거기에 참여한다 없으면 새로 만든다
즉, 같이 한 배 타기

2. REQUIRES_NEW 이름 그대로, 새 트랜잭션이 필요하다

@Transactional(propagation = Propagation.REQUIRES_NEW)
public void saveLog() {
    logRepository.save(...);
}

기존 트랜잭션이 어도 무시하고 내 트랜잭션을 새로 만든다

[흐름]
order() 시작
→ 트랜잭션 A

시작 saveLog() 호출
→ 트랜잭션 A 잠깐 멈춤
→ 트랜잭션 B 새로 시작
→ 로그 저장
→ 트랜잭션 B commit

order()로 복귀
→ 트랜잭션 A 계속 진행

언제 쓸까?
대표적으로 로그 저장.
예를 들어 주문은 실패해서 rollback되어도 주문 실패 로그는 남기고 싶을 수 있다

@Transactional
public void order() {
    try {
        paymentService.pay();
    } catch (Exception e) {
        logService.saveFailLog(); // 이건 남기고 싶음
        throw e;
    }
}

이때 로그 저장이 REQUIRED면 주문 트랜잭션이 rollback될 때 로그도 같이 날아갈 수 있다
그래서 로그 쪽을 이렇게 분리한다

@Transactional(propagation = Propagation.REQUIRES_NEW)
public void saveFailLog() {
    logRepository.save(...);
}

그러면 주문이 실패해서 rollback되어도 로그는 별도 트랜잭션에서 commit될 수 있다
하지만 조심해야 한다
Spring 공식문서는 REQUIRES_NEW가 독립적인 물리 트랜잭션을 사용하며 내부 트랜잭션이 별도 DB connection을 얻기 때문에 connection pool 크기에 주의해야 한다고 설명한다

쉽게말하면, 바깥 트랜잭션이 DB 연결 1개 잡고 있음, 안쪽 REQUIRES_NEW가 DB 연결 1개 더 필요함
그래서 동시 요청이 많으면 DB 연결이 부족해질 수 있다
즉, 혼자 새 배 타기

3. MANDATORY는 필수라는 뜻이다

@Transactional(propagation = Propagation.MANDATORY)
public void someInnerWork() {
}

기존 트랜잭션이 반드시 있어야 하며 없으면 예외를 터뜨린다 즉, 이 메서드는 혼자 실행되면 안 된다는 뜻이다
비유해보자면, 이 작업은 반드시 큰 작업의 일부로만 실행되어야 한다 단독 실행 금지

예를 들어 어떤 내부 작업이 반드시 바깥 트랜잭션과 한 묶음이어야 한다면 MANDATORY를 고려할 수 있다
즉, 혼자 못 감. 반드시 누군가의 트랜잭션 안에서만 감
4. NESTED는 중첩이라는 뜻이다
NESTED는 REQUIRES_NEW처럼 완전히 새 트랜잭션을 만드는 게 아니다
공식문서에 따르면 PROPAGATION_NESTED는 하나의 물리 트랜잭션 안에서 여러 savepoint를 사용하고 안쪽 범위만 부분 rollback 할 수 있게 한다

쉽게말하면, 전체 트랜잭션 안에 중간 저장 지점을 찍어둔다 안쪽 작업이 실패하면 그 저장 지점까지만 되돌린다

게임으로 비유하면
큰 미션 시작 → 중간 저장 → 작은 미션 실패 → 중간 저장 지점으로 돌아감 → 큰 미션은 계속 진행

@Transactional
public void order() {
    saveOrder();

    try {
        couponService.useCoupon();
    } catch (Exception e) {
        // 쿠폰 실패해도 주문은 계속 진행하고 싶음
    }

    saveResult();
}
@Transactional(propagation = Propagation.NESTED)
public void useCoupon() {
    couponRepository.save(...);
}

order() 트랜잭션 A 시작
주문 저장

useCoupon() 호출
→ 트랜잭션 A 안에 savepoint 생성
→ 쿠폰 처리 실패
→ savepoint까지만 rollback

주문 작업 계속
트랜잭션 A commit

이때 중요한 차이점은

REQUIRES_NEW : 진짜 새 트랜잭션
NESTED : 같은 트랜잭션 안의 중간 저장점

그래서 바깥 트랜잭션이 최종 rollback되면? NESTED 안쪽 작업도 결국 같이 rollback된다 왜냐하면 같은 물리 트랜잭션 안에 있었기 때문이다
즉, 같은 배 안에서 중간 저장 지점 만들기

4. 트랜잭션 격리 수준: Isolation Level

Isolation Level : 동시에 DB를 볼 때, 어디까지 보여줄 거야? - 격리 수준
Propagation은 메서드끼리 트랜잭션을 어떻게 나눌지였다 Isolation은 완전히 다른 문제다

동시에 여러 사람이 DB를 읽고 쓰면 한 사람이 아직 확정하지 않은 변경을 다른 사람이 봐도 될까?
같은 데이터를 두 번 읽었는데 중간에 값이 바뀌어도 될까?

Spring 공식문서도isolation을 이 트랜잭션이 다른 트랜잭션의 작업으로부터 얼마나 격리되는가?의 정도라고 설명한다
예를 들어 다른 트랜잭션의 commit되지 않은 쓰기를 볼 수 있는가?같은 문제다

격리 수준을 이해하려면 먼저 동시에 일어나면 생기는 이상한 현상 3개를 봐야 한다

1. Dirty Read

트랜잭션 A: 상품 가격을 10,000원에서 1,000원으로 바꿈
트랜잭션 A: 아직 commit 안 함

트랜잭션 B: 상품 가격을 읽음
트랜잭션 B: 1,000원이라고 봄

트랜잭션 A: 아 실수였다. rollback

그러면 B는 실제로 확정된 적 없는 가격을 읽은 거다 이게 DirtyRead
즉, 아직 확정 안 된 남의 임시 작업을 읽어버림
이건 거의 허용하면 안 된다

2. Non-repeatable Read

트랜잭션 A 시작
A: 상품 id=1 조회 → 가격 10,000원

트랜잭션 B 시작
B: 상품 id=1 가격을 12,000원으로 수정
B: commit

A: 상품 id=1 다시 조회 → 가격 12,000원

A입장에서는 같은 트랜잭션 안에서 같은 상품을 읽었는데 값이 바뀌었다
즉, 같은 row를 다시 읽었는데 값이 달라짐

3. Phantom Read

트랜잭션 A 시작
A: 가격 10,000원 이상 상품 조회 → 5개

트랜잭션 B 시작
B: 가격 15,000원 상품 추가
B: commit

A: 가격 10,000원 이상 상품 다시 조회 → 6개

A 입장에서는 처음에 없던 row가 갑자기 유령처럼 나타났다
즉, 같은 조건으로 조회했는데 행 개수가 달라짐

Isolation Level 옵션

READ_UNCOMMITTED
READ_COMMITTED
REPEATABLE_READ
SERIALIZABLE

아래 순서로 갈수록 격리 수준이 강해진다

READ_UNCOMMITTED < READ_COMMITTED < REPEATABLE_READ < SERIALIZABLE

격리 수준이 낮으면 동시 처리는 잘 되지만 이상한 읽기가 생길 수 있다
반대로 격리 수준이 높으면 데이터는 더 안전하지만 대신 대기, 충돌, 성능 비용이 커질 수 있다

1. READ_UNCOMMITTED
다른 트랜잭션이 commit 안 한 데이터도 읽을 수 있다 즉, DirtyRead가 가능하다
남이 연필로 적어둔 임시 메모를 최종 결재 문서인 줄 알고 읽는것
근데 거의 안씀

2. READ_COMMITTED
다른 트랜잭션이 commit 한 데이터만 읽을 수 있다 DirtyRead는 막는다
PostgreSQL 공식문서는 Read Committed가 PostgreSQL의 기본 격리 수준이며 이 수준에서 SELECT는 쿼리가 시작되기 전에 commit된 데이터만 보고 commit 되지 않는 데이터는 보지 않는다고 설명한다

하지만 Non-repeatable Read는 가능하다
왜냐하면 같은 트랜잭션 안에서도 두 번째 SELECT를 실행할 때 그 사이에 다른 트랜잭션이 commit한 데이터는 보일 수 있기 때문이다

첫 번째 조회 시점에는 가격 10,000원
그 후 누가 commit함
두 번째 조회 시점에는 가격 12,000원

즉, 확정된 것만 읽긴 하는데 다시 읽으면 바뀔 수 있음

3. REPEATABLE_READ
같은 트랜잭션 안에서 같은 row를 다시 읽으면 같은 값이 보이도록 함

MySQL InnoDB 공식문서는 InnoDB가 4가지 격리 수준을 제공하며 기본 격리 수준은 REPEATABLE READ라고 설명한다

트랜잭션 A 시작
A: 상품 id=1 조회 → 가격 10,000원

트랜잭션 B:
상품 id=1 가격 12,000원으로 수정
commit

A: 상품 id=1 다시 조회

REPEATABLE_READ에는 A가 여전히 10,000원을 볼 수 있다
비유해보자면, 트랜잭션을 시작할 때 DB 사진을 한 장 찍어둠 근데 그 트랜잭션 안에서는 그 사진 기준으로 계속 봄
즉, 내 트랜잭션 안에서는 같은 row가 흔들리지 않게 함

4. SERIALIZABLE
이건 가장 강하다 동시에 실행되더라도 결과가 마치 하나씩 줄 세워 실행한 것처럼 보이게 한다
비유해보자면, 사람들이 동시에 계산대에 몰려와도 직원이 한 명씩 줄 세워 처리하는 것

안정성은 강하지만 비용도 크다

대기 증가
충돌 증가
성능 저하 가능성
재시도 필요 가능성

그럼 가장 높은 SERIALIZABLE 쓰면 끝 아냐?
그건 아니다 격리 수준은 약 같은 것
증상에 맞는 약을 써야지 무조건 제일 센 약을 매일 먹으면 몸이 망가진다 DB도 똑같다 데이터 정합성은 좋아질 수 있지만 동시에 처리할 수 있는 양이 줄고 대기가 늘 수 있다

구분	Propagation 트랜잭션의 경계 문제	Isolation 트랜잭션끼리의 거리두기 문제
한국말 느낌	전파	격리
핵심 질문	트랜잭션을 같이 쓸까, 새로 만들까?	동시에 실행될 때 남의 변경이 보일까?
보는 대상	메서드 호출 관계	DB 동시성 상황
대표 옵션	REQUIRED, REQUIRES_NEW, NESTED	READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE
초보자 비유	같은 배 탈지, 새 배 탈지	다른 사람이 작업 중인 종이를 볼 수 있는지

5. 실무 설계 기준

@Transactional
public void writeSomething() {
    // 저장, 수정, 삭제
}

대부분은 이 경우 이정도로 시작한다 조회는 보통 이렇게 한다

@Transactional(readOnly = true)
public Something getSomething() {
    // 조회
}

그리고 특별한 이유가 있을 때에만 propagation이나 isolation을 명시한다

기본값이 뭐지?

@Transactional

대략 이렇게 이해하면 된다

@Transactional(
    propagation = Propagation.REQUIRED,
    isolation = Isolation.DEFAULT
)

REQUIRED는 Spring 기본값이고 DEFAULT는 DB 기본 격리 수준을 따르겠 다는 뜻이다
Spring 공식문서의 @Transactional 설정 표에서도 isolation 기본값 DEFAULT,
propagation의 기본값은 REQUIRED로 정리되어있다

즉, 같은 Spring 코드라도 DB가 다르면 격리 동작이 다를 수 있다

언제 REQUIRED를 쓰는가?

쓰기 작업 하나를 하나의 비즈니스 작업으로 묶고 싶을 때 사용한다
아무 데나 막 붙여라가 아니라 하나의 비즈니스 작업 단위에 붙이라는 뜻이다

언제 REQUIRES_NEW를 쓰는가?

정말 독립적으로 commit되어야 하는 작업일 때 쓴다

실패 로그
감사 로그
알림 발송 기록
별도 이력 저장

근데 남발하면 안됨
그 이유는

전체 원자성이 깨질 수 있음
DB connection을 추가로 씀
장애 상황에서 일부 데이터만 남을 수 있음

즉 바깥 작업이 실패해서 rollback돼도 이 데이터는 반드시 남아야 하나?
그렇다면 REQUIRES_NEW 후보 아니면 대부분 REQUIRED

언제 Isolation을 직접 지정하나?

@Transactional
@Transactional(readOnly = true)

위 코드로도 충분한 경우가 많다 직접 지정하는 경우는 이런 때다

동시에 여러 요청이 같은 데이터를 건드림
재고, 포인트, 잔액, 예약 수량처럼 틀리면 안 됨
같은 트랜잭션 안에서 반복 조회 결과가 흔들리면 안 됨

[재고 차감 상황]
현재 재고 1개

사용자 A 구매
사용자 B 구매

둘 다 동시에 재고 있네?라고 판단하면 문제

이런 건 단순히 @Transational만 붙인다고 끝나지 않을 수 있다 격리 수준, 락, update 쿼리, 재시도 정책까지 같이 봐야 한다
즉, Isolation은 모든 동시성 문제를 마법처럼 해결하지 않는다
특히 조회수 증가, 재고 차감, 쿠폰 선착순 같은 건 isolation만 볼 게 아니라 락/ 원자적/ update/ 중복 방지 까지 같이 봐야 한다

자주하는 실수

실수 2. private 메서드에 붙이기

@Transactional
private void saveSomething() {
}

프록시 기반에서는 기대대로 안 먹는다고 보면 된다

실수 2. 같은 클래스 내부 호출

public void outer() {
    inner();
}

@Transactional
public void inner() {
}

이것 또한 프록시를 안 거칠 수 있다

실수 3. REQUIRES_NEW를 안전장치처럼 남발

@Transactional(propagation = Propagation.REQUIRES_NEW)

이건 더 안전함이 아니라 트랜잭션을 분리해야 한다 분리하면 일부만 commit 될 수 있다

실수 4. 격리 수준을 무조건 높이기

@Transactional(isolation = Isolation.SERIALIZABLE)

제일 센 격리지만 제일 좋은 기본값은 아니다

정합성 ↑
동시성 ↓
대기/충돌 가능성 ↑

실수 5. 외부 API 호출을 트랜잭션 안에서 오래 붙잡기

@Transactional
public void process() {
    repository.save(...);

    externalApi.call(); // 오래 걸릴 수 있음
}

이러면 DB 트랜잭션이 열린 상태로 외부 API응답을 기다린다
문제는

DB connection 오래 점유
lock 오래 유지
응답 지연
장애 전파

그래서 외부 시스템 호출은 트랜잭션 안에 넣을지 진짜 신중해야 한다

[Devlog] CoreBoard 성능 테스트 계획 및 결과 정리

HS0601 — Wed, 13 May 2026 17:51:52 +0900

테스트 개요 (Overview)

1. 테스트 목적

CoreBoard의 주요 사용 흐름에서 API 응답 지연과 병목 구간을 확인한다.

API를 하나씩 단독 호출하는 방식이 아니라, 프론트 화면에서 사용자가 실제로 이동하는 순서를 기준으로 JMeter 시나리오를 구성한다.

확인 사항

주요 조회 API의 응답 시간
검색 조건이 들어갔을 때의 성능 변화
읽기/쓰기 요청이 섞였을 때의 DB connection 상태
첨부파일 메타데이터 조회가 상세 조회 성능에 미치는 영향
부하 상황에서 CPU, JVM memory, DB connection, Swap 사용량 변화
Redis 기반 조회수 기록이 게시글 상세 조회 응답 시간에 미치는 영향
Redis ZSET 기반 인기글 조회 성능
조회수 delta 적립 후 DB 동기화 흐름의 안정성

2. 테스트 대상 시스템

Spring Boot API 서버
MySQL
Nginx
게시판/게시글/댓글/첨부파일/조회수/인기글 관련 API
Redis

3. 테스트 환경

1차 테스트 : 로컬 또는 테스트 환경

로컬 또는 별도 테스트 환경에서는 비교적 강한 부하를 주어 병목 후보를 확인한다.

JMeter로 Step Load 방식의 부하 테스트 수행
Prometheus / Grafana로 서버 지표 확인
API 응답 시간, JVM memory, CPU, DB connection 상태 관찰

2차 검증 : GCP 배포 서버

GCP 배포 서버에서는 낮은 부하로만 정상 동작을 확인한다.

HTTPS → Nginx → Spring Boot → MySQL 경로 검증
운영 서버 장애 방지
GCP 비용 증가 방지
Stress Load는 수행하지 않음

4. 성능 지표 및 목표

1. 처리량

초기 목표 : 10 ~ 30 RPS 구간에서 안정 동작 확인
해당 수치는 최대 처리량을 증명하기 위한 기준이 아니라, CoreBoard의 현재 서버 규모와 테스트 목적을 고려한 초기 관찰 기준선이다.

2. 응답 시간

응답 시간은 시나리오 성격에 따라 다르게 판단한다.

평균 응답 시간은 전체적인 경향을 보기 위한 지표로 사용하고,
p95 응답 시간은 일부 요청이 지연되는 구간을 확인하기 위한 핵심 지표로 본다.

응답 시간 목표는 절대적인 성능 보장 수치가 아니라, API 성격과 서버 규모를 고려한 초기 기준선이다.
테스트 결과가 누적되면 실제 측정값을 기준으로 목표치를 다시 조정한다.

시나리오	기준
시나리오 A - 비로그인 게시판 탐색	평균 500ms 이하 / p95 1초 이하
시나리오 B - 검색 흐름	평균 800ms 이하 / p95 1.5초 이하
시나리오 C - 로그인 후 글 작성 및 댓글 작성	평균 1초 이하 / p95 2초 이하
시나리오 D - 첨부파일이 있는 게시글 조회	평균 800ms 이하 / p95 1.5초 이하
시나리오 E - Redis 조회수 및 인기글 흐름	평균 800ms 이하 / p95 1.5초 이하

공통 중단 기준 : p95 응답 시간이 3초를 초과하는 상태가 지속되면 테스트를 중단하고 병목 분석으로 전환한다.

오류율

5xx 에러율 : 0%
예상된 4xx
- 인증 없는 쓰기 요청 → 401
- 권한 없는 삭제/관리자 접근 → 403
- 잘못된 요청 데이터 → 400
확인 대상
- CPU 80% 이상 지속
- Memory available 급감
- Swap 사용량 급증
- HikariCP pending connection 발생

자원 사용률

다음 상황이 지속되면 테스트를 중단한다.

CPU 80% 이상 지속 시 중단
Memory available 급감 시 중단
Swap 사용량 급증 시 중단
HikariCP pending connection 발생 시 중단

5. 부하 시나리오

1. 시나리오 A — 비로그인 사용자의 게시판 탐색

목적 : 가장 기본적인 읽기 흐름에서 게시판 목록, 게시글 목록, 상세 조회, 댓글 조회 성능을 확인한다

게시글 목록 조회는 Page 기반 조회라 count query, 정렬, 작성자 조회에서 병목이 생길 수 있다

사용자 행동 흐름

메인 접속
→ 게시판 목록 조회
→ 특정 게시판 진입
→ 게시글 목록 조회
→ 페이지 이동
→ 게시글 상세 조회
→ 댓글 목록 조회

대상 API

GET /boards
GET /boards/{boardId}/posts?page=0&size=10&direction=DESC
GET /boards/{boardId}/posts?page=1&size=10&direction=DESC
GET /posts/{id}
GET /posts/{postId}/comments

성능 목표
- 평균 응답 시간 : 500ms 이하
- p95 응답시간 : 1초 이하
- p95 3초 초과가 지속되면 테스트 중단

2. 시나리오 B — 검색 사용자의 흐름

목적 : 검색 조건이 들어갔을 때 게시글 목록 조회 성능이 어떻게 달라지는지 확인한다

검색은 일반 목록 조회보다 조건 필터링 비용이 커질 수 있으므로 응답 시간 변화를 비교한다

사용자 행동 흐름

게시판 진입
→ 검색어 입력
→ 검색 결과 목록 조회
→ 검색 결과 게시글 상세 조회

대상 API

GET /boards/{boardId}/posts/ search? keyword=test&page=0&size=10
GET /posts/{id}

성능 목표
- 평균 응답 시간 : 800ms 이하
- p95 응답시간 : 1.5초 이하
- p95 3초 초과가 지속되면 테스트 중단

3. 시나리오 C — 로그인 사용자의 글 작성 및 댓글 작성

목적 : 읽기와 쓰기가 섞인 상황에서 API 응답 시간, DB connection, 트랜잭션 처리 상태를 확인한다

쓰기 API는 인증, 검증, 트랜잭션, INSERT가 포함되므로 DB connection 점유 시간이 길어질 수 있다

사용자 행동 흐름

로그인
→ 게시판 목록 조회
→ 게시글 작성
→ 작성한 게시글 상세 조회
→ 댓글 작성
→ 댓글 목록 조회

대상 API

POST /auth/token
GET /boards
POST /boards/{boardId}/posts
GET /posts/{id}
POST /posts/{postId}/comments
GET /posts/{postId}/comments

성능 목표
- 평균 응답 시간 : 1초 이하
- p95 응답시간 : 2초 이하
- p95 3초 초과가 지속되면 테스트 중단

주의

쓰기 API는 DB 상태를 계속 변경하므로 로컬/테스트 환경에서만 강하게 실행한다
GCP 배포 서버에서는 낮은 부하로만 검증한다

4. 시나리오 D — 첨부파일이 있는 게시글 조회

목적 : 게시글 상세 조회 시 첨부파일 조회가 응답 시간에 미치는 영향을 확인한다

첨부파일이 있는 게시글 상세 조회는 게시글, 댓글 외에 첨부파일 메타데이터 조회가 추가되므로 일반 상세 조회와 비교한다

사용자 행동 흐름

첨부파일이 있는 게시판 진입
→ 게시글 목록 조회
→ 첨부파일이 있는 게시글 상세 조회
→ 댓글 목록 조회

대상 API

GET /boards/{boardId}/posts
GET /posts/{id}
GET /posts/{postId}/comments

성능 목표
- 평균 응답 시간 : 800ms 이하
- p95 응답시간 : 1.5초 이하
- p95 3초 초과가 지속되면 테스트 중단

5. 시나리오 E — Redis 조회수 및 인기글 흐름

목적 : 게시글 상세 조회 시 Redis 기반 조회수 기록이 응답 시간에 미치는 영향과, Redis ZSET 기반 인기글 조회 성능을 확인한다

게시글 상세 조회는 기존에는 DB 조회 후 응답하는 흐름이었지만, 조회수 기능 추가 이후 Redis 중복 조회 방지 키 저장, 조회수 delta 증가, 인기글 점수 증가가 함께 수행된다

따라서 상세 조회 응답 시간이 Redis 기록 로직 때문에 유의미하게 증가하는지 확인한다

사용자 행동 흐름

게시글 상세 조회
→ 동일 게시글 반복 조회
→ 여러 게시글 상세 조회
→ 인기글 목록 조회

대상 API

GET /posts/{id}
GET /posts/popular?size=10

성능 목표
- 평균 응답 시간 : 800ms 이하
- p95 응답 시간 : 1.5초 이하
- p95 3초 초과가 지속되면 테스트 중단

6. 부하 형태

1. 로컬/테스트 환경

로컬 또는 테스트 환경에서는 Step Load 방식으로 부하를 증가시킨다.

동시 사용자 5명 → 10명 → 20명 → 30명

각 단계는 다음 기준으로 실행한다

Ramp-up: 60초
Duration: 3분

목적은 최대 트래픽을 자랑하는 것이 아니라, 부하가 증가할 때 어떤 API 또는 자원이 먼저 병목으로 나타나는지 확인하는 것이다.

2. GCP 배포 서버

GCP 배포 서버에서는 낮은 부하로만 검증한다.

동시 사용자 5명 → 10명 → 20명
각 1~3분

배포 서버에서는 Stress Load를 수행하지 않는다 저사양 서버이므로 장애와 비용 증가 위험이 크기 때문이다

7. 시나리오 비중

JMeter 테스트 시나리오의 비중은 실제 사용 흐름을 기준으로 다음과 같이 설정한다.

시나리오	비중
게시판 탐색	40%
검색	20%
게시글 상세 + 댓글 조회	15%
인기글 조회	15%
로그인 / 글 작성 / 댓글 작성	10%

읽기 요청이 대부분의 사용 흐름에서 더 자주 발생하므로 게시판 탐색, 검색, 상세 조회, 인기글 조회의 비중을 높게 둔다

인기글 조회는 Redis 기반 조회수 기능 추가 이후 새로 생긴 읽기 흐름이므로 별도 비중으로 분리한다

쓰기 요청은 DB 상태를 변경하므로 낮은 비중으로 제한한다

8. 테스트 도구 및 인프라

부하테스트 도구

JMeter

모니터링 도구

Spring Boot Actuator
Prometheus
Grafana

9. 최종 테스트 전략

CoreBoard 프론트 화면의 주요 사용 흐름을 기준으로 JMeter 부하 시나리오를 설계한다.
Prometheus와 Grafana를 통해 HTTP 응답 시간, JVM memory, CPU 사용률, DB connection 상태를 관찰한다.
Repository 실행 시간은 직접 계측이 필요하므로, 초기 테스트에서는 API 응답 시간과 DB connection 지표를 통해 병목 후보를 추정한다.
운영 서버에는 직접 고부하를 주지 않고, 테스트 환경에서 병목을 재현한 뒤 배포 서버에서는 제한된 부하로 정상 동작을 검증한다.

10. 시나리오별 테스트 완료 결과

시나리오	확인한 병목	개선 내용	최종 결과
Scenario A - 비로그인 게시판 탐색	게시글 목록 조회 지연	목록 조회에서 user 조인 제거	통과
Scenario B - 검색 흐름	검색 목록 조회 지연	검색 조회 최적화	통과
Scenario C - 글 작성 및 댓글 작성	게시글 작성 지연	post.title UNIQUE INDEX 적용	통과
Scenario D - 첨부파일 게시글 조회	게시글 목록 조회 지연	Page → Slice, 복합 인덱스 적용	통과

11. 최종 판단

Scenario A, B, C, D 테스트를 모두 완료했다.

각 시나리오에서 발견된 병목은 별도 Bottleneck Analysis 문서로 정리했다.

개선 후 재측정 결과, 모든 시나리오는 정의한 중단 기준을 초과하지 않았다.

따라서 CoreBoard의 주요 사용자 흐름은 로컬 테스트 기준에서 안정적으로 동작한다고 판단한다.

[Trouble Shooting] 배포 서버 API 응답 지연

HS0601 — Wed, 13 May 2026 17:00:57 +0900

문제 — 배포 서버 API 응답이 갑자기 8초 이상 지연됨
원인 분석 — 내부 호출과 외부 호출을 비교하고 서버 자원 상태를 확인함
원인 — apt 자동 점검과 swap 부재로 인한 메모리 압박 발생
해결 — apt timer 비활성화, swap 1GB 추가, 애플리케이션 재시작
배운 점 — Health Check만으로는 운영 상태를 판단할 수 없음

문제

CoreBoard 배포 서버의 API 응답이 갑자기 전반적으로 느려졌다

처음에는 프론트 문제처럼 보였지만, 서버 내부에서 직접 API를 호출해도 약 8초가 걸렸다

time curl -s -o /dev/null -w "status=%{http_code} total=%{time_total}\n" \
http://127.0.0.1:8080/boards?page=0\&size=10\&direction=DESC

응답

status=200 total=8.242320

외부 도메인으로 호출해도 비슷했다

status=200 total=8.241890

따라서 Nginx나 HTTPS만의 문제가 아니라, 서버 내부 자원 문제일 가능성이 높다고 판단했다

원인 분석

애플리케이션은 살아 있었지만, 서버 자원이 비정상적으로 부족했다

health 확인 결과 애플리케이션과 DB 연결은 UP 상태였다

curl -i http://127.0.0.1:8080/actuator/health

하지만 top, free -h 확인 결과 서버 상태가 좋지 않았다

load average: 15.22
CPU wa: 68.3%
Mem: 969Mi total, 938Mi used
Swap: 0B

또한 apt-get 자동 점검 프로세스가 실행 중이었다

ps -ef | grep apt

apt-get --just-print -qq full-upgrade
apt-get check -qq
apt.systemd.daily

원인

1GB 메모리 서버에서 apt 자동 점검 작업이 실행되면서 Spring Boot, MariaDB와 자원 경쟁이 발생한 것이 원인이었다.

정리하면 다음 흐름이다

1GB RAM 서버
→ swap 없음
→ apt-daily 자동 점검 실행
→ Java, MariaDB와 자원 경쟁
→ 메모리 압박 및 IO wait 증가
→ 전체 API 응답 지연

health가 UP이어도 응답 속도까지 정상이라는 뜻은 아니었다

해결

apt 자동 작업을 중지하고, swap 1GB를 추가했다

실행 중인 apt 프로세스를 종료했다

sudo kill <apt-get PID>

apt 상태를 복구했다

sudo dpkg --configure -a
sudo apt-get -f install

자동 apt timer를 비활성화했다

sudo systemctl disable --now apt-daily.service apt-daily.timer 
apt-daily-upgrade.service apt-daily-upgrade.timer

swap 1GB를 추가했다

swap이란?
RAM이 부족할 때 디스크 일부를 임시 메모리처럼 쓰는 공간이다

RAM = 작업대
디스크 = 창고
swap = 작업대가 꽉 찼을 때 잠깐 창고 일부를 작업대처럼 쓰는 공간

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

재부팅 후에도 적용되도록 등록했다

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

이후 애플리케이션을 재시작했다

sudo systemctl restart coreboard

결과

내부 API 응답 시간이 약 8초에서 0.03초 수준으로 개선되었다.

조치 전:

status=200 total=8.242320

조치 후:

status=200 total=0.033635

외부 HTTPS 호출도 약 0.3초 수준으로 회복되었다.

total=0.29791

배운 점

서버가 살아 있는 것과 정상 성능으로 동작하는 것은 다르다

health가 UP이어도 CPU, 메모리, IO wait, 응답 시간을 함께 확인해야 한다

또한 저사양 서버에서는 운영체제의 자동 작업도 애플리케이션 성능에 영향을 줄 수 있다

이번 문제를 통해 서버 운영 시 다음 항목을 함께 확인해야 한다는 점을 배웠다

애플리케이션 health
내부 API 응답 시간
외부 도메인 응답 시간
CPU / Memory / IO wait
자동 백그라운드 작업 여부

앞으로는 자동 apt 업데이트를 비활성화하고, 주기적으로 수동 점검하기로 했다

sudo apt update
sudo apt list --upgradable

필요할 때만 직접 업데이트를 수행한다

sudo apt upgrade

top란?
서버가 지금 얼마나 바쁜지 보는 명령어
CPU, 메모리, 실행 중인 프로세스를 본다

free -h란?
서버 메모리 상태를 보는 명령어
Mem = 실제 RAM
Swap = 보조 메모리 공간
available = 지금 새 작업에 쓸 수 있는 메모리

Load Average란?
서버에 일이 얼마나 밀려있는지 보여주는 값

load average: 15.22, 14.16, 12.55
// 최근 1분 / 5분 / 15분 동안 CPU를 쓰려고 기다리는 작업이 얼마나 많았는가

IO wait / wa란?
CPU가 디스크나 메모리 작업이 끝나길 기다리는 시간

wa 68.3%
// CPU 시간의 68.3%가 계산이 아니라 대기 상태

Swap이란?
RAM이 부족할 때 디스크 일부를 임시 메모리처럼 쓰는 공간

RAM : 빠른 작업대
디스크 : 창고
swap : 작업대가 꽉 찼을 때 임시로 쓰는 창고 공간

swap은 RAM보다 훨씬 느리다 그래서 swap은 성능 향상용이 아니라 서버가 메모리 부족으로 흔들리는 걸 막는 완충장치다

kswapd란?
리눅스가 메모리를 정리할 때 사용하는 커널 프로세스다
메모리가 부족하면 kswapd가 바빠진다

apt란?
리눅스에서 프로그램을 설치하거나 업데이트하는 도구다

apt 가 관리하는 것들은 대개 이런 것이다

nginx
mariadb
openssl
curl
보안 패치
시스템 라이브러리

apt-daily란?
서버가 자동으로 apt 점검을 하도록 예약된 작업
저사양 서버에서 이 자동 작업도 CPU와 메모리를 꽤 먹을 수 있다

systemd timer란?
리눅스의 예약 실행 기능
윈도우의 작업 스케줄러처럼 생각하면 된다

[Network] 브라우저가 도메인을 IP로 찾는 과정 — DNS 동작 원리

HS0601 — Wed, 13 May 2026 13:47:18 +0900

DNS가 왜 필요한가?
DNS의 계층 구조
브라우저가 도메인을 IP로 찾는 전체 흐름
TTL과 캐시 — DNS 전파 지연이 왜 생기는가
주요 DNS 레코드 종류
전체 흐름 정리

DNS가 왜 필요한가?

인터넷에서 컴퓨터끼리 통신할 때 IP주소를 사용한다

IP( Internet Protocol)주소란?
인터넷에서 장치나 서버를 찾기 위해 사용하는 숫자 기반 주소다
IP 주소는 그 프로토콜에서 목적지를 식별하기 위해 사용하는 주소값이다

그런데 매번 35.202.68.192 같은 숫자를 외워서 접속하기는 불가능하다 그래서 사람이 읽기 쉬운 이름 즉, 도메인을 만들었다

도메인(Domain) 이란?
사람이 기억하기 쉬운 인터넷 이름이다
DNS는 이 도메인 이름을 실제 접속에 필요한 IP 주소로 변환해준다

google.com, naver.com 같은 형식이다

브라우저 주소창에 google.com 을 입력하면 브라우저는 이걸 어딘가에서 IP주소로 변환해야 한다 그 변환을 담당하는 세스템이 바로 DNS다

DNS(Domain Name System)란?
The Domain Name System (DNS) is a simple query-response protocol whose messages in both directions have the same format. - 공식문서링크
도메인 이름을 IP주소로 변환해주는 시스템이다 인터넷의 전화번호부라고 생각하면 된다
구글이요? → 5.190.27.1 로 전화하세요 같은 역할을 한다

DNS의 계층 구조

DNS는 한 서버가 모든 도메인을 다 알고 있는 게 아니다 계층적으로 분산되어 있다

루트 네임서버 (.)
    ↓
TLD 네임서버 (.com / .kr / .xyz 등)
    ↓
권한 네임서버 (google.com / coreboard-api.xyz 등)

각각 어떤 역할을 하는지 알아보자

1. 루트 네임서버 (Root Name Server)

DNS 계층의 최상위 서버다

전 세계에 13그룹(A~M)이 있고 실제 서버는 수백 대가 분산 운영된다

The authoritative name servers that serve the DNS root zone, often known simply as the “root servers”, are a network of hundreds of servers in many countries around the world.
They are configured in the DNS root zone as 13 named authorities.

루트 네임서버는 모든 도메인의 IP를 알고 있는 게 아니다

.com은 이쪽 서버에 물어봐
.xyz는 저쪽 서버에 물어봐

TLD 네임서버의 위치만 알려준다

2. TLD 네임서버 (Top Level Domain Name Server)

TLD(Top Level Domain)이란?
도메인의 맨 끝 부분이다 google.com에서 .com, naver.co.kr에서 .kr이 TLD다

.com, .kr, .xyz같은 최상위도메인 별로 서버가 따로 있다 TLD네임서버는 해당 TLD 아래에 있는 도메인들의 권한 네임서버 위치를 알고 있다

google.com? 그건 구글 권한 네임서버에 물어봐~

3. 권한 네임서버(Authoritative Name Server)

권한 네임서버(Authoritative Name Server)란?
특정 도메인의 실제 DNS 정보를 가지고 있는 서버다 가비아에서 도메인을 샀다면 가비아의 네임서버가 권한네임 서버다
여기서 A 레코드를 등록하면 이 서버가 이 도메인의 IP는 이거야라고 확실하게 답해준다

이 서버가 최종 정답을 가지고 있다

권한 네임서버에서 정상 조회되면 DNS 설정 자체는 맞는 것이다

nslookup api.coreboard-api.xyz ns.gabia.co.kr

브라우저가 도메인을 IP로 찾는 전체 흐름

google.com을 입력했을 때 무슨 일이 일어나는지 단계별로 본다.

브라우저 주소창에 google.com 입력
          ↓
  1. 브라우저 캐시 확인
          ↓ 없으면
  2. OS 캐시 확인 (hosts 파일 포함)
          ↓ 없으면
  3. 로컬 DNS 리졸버에 질의 (ISP 서버)
          ↓ 모르면
  4. 루트 네임서버에 질의
          ↓
  5. TLD 네임서버에 질의 (.com)
          ↓
  6. 권한 네임서버에 질의 (google.com)
          ↓
  7. IP 반환 → 캐시 저장 → 접속

1단계: 브라우저 캐시 확인

브라우저는 한 번 조회한 도메인의 IP를 자체 캐시에 저장한다 google.com에 오늘 이미 접속했다면, 브라우저는 저장해둔 IP를 바로 꺼내 쓴다. DNS 조회를 생략하는 것이다

캐시(Cache) 란?
자주 쓰는 데이터를 빠르게 꺼내 쓰려고 임시로 저장해두는 공간이다 매번 처음부터 찾는 것보다 훨씬 빠르다

2단계: OS 캐시 확인 + hosts 파일

브라우저 캐시에 없으면 운영체제(OS) 레벨 캐시를 확인한다 그리고 hosts 파일도 함께 확인한다

hosts 파일이란?
컴퓨터에 직접 이 도메인은 이 IP야~라고 수동으로 적어두는 파일이다
Windows 기준 C:\Windows\System32\drivers\etc\hosts 에 있다
DNS 서버보다 먼저 확인하기 때문에, 여기에 적힌 내용이 우선이다
로컬 개발할 때 127.0.0.1 myapp.local 같은 식으로 쓰기도 한다

3단계: 로컬 DNS 리졸버에 질의

OS 캐시에도 없으면 로컬 DNS 리졸버에 질의한다

로컬 DNS 리졸버(Local DNS Resolver)란?
ISP(인터넷 서비스 제공자, 즉 KT, SKT, LGU+ 등)가 운영하는 DNS 서버다
내 컴퓨터가 인터넷에 연결되면 자동으로 이 서버를 사용하도록 설정된다
나 대신 DNS 조회를 대행해주는 서버라고 보면 된다
Google의 8.8.8.8, Cloudflare의 1.1.1.1도 이 역할을 한다.

로컬 DNS 리졸버도 캐시를 가지고 있다 다른 사용자가 최근에 같은 도메인을 조회했다면 캐시에서 바로 응답한다

캐시가 없으면 이 서버가 아래 4~6단계를 대신 수행해준다이 과정을 재귀 쿼리라고 부른다.

재귀 쿼리(Recursive Query)란?
클라이언트가 로컬 DNS 리졸버에 google.com의 IP 알아와줘~라고 부탁하면,
리졸버가 루트 → TLD → 권한 네임서버까지 직접 돌아다니며
결과를 가져오는 방식이다 클라이언트는 기다리기만 하면 된다

4단계: 루트 네임서버에 질의

로컬 DNS 리졸버가 루트 네임서버에 google.com의 IP가 뭐야? 라고 물어본다

루트 네임서버는 IP는 모른다. 대신 이렇게 답한다

.com 담당 TLD 네임서버는 여기야 → TLD 서버 주소 반환

5단계: TLD 네임서버에 질의

.com TLD 네임서버에 google.com의 IP가 뭐야? 라고 물어본다

TLD 네임서버도 IP는 모른다 대신 이렇게 답한다

google.com 담당 권한 네임서버는 여기야 → 구글 권한 네임서버 주소 반환

6단계: 권한 네임서버에 질의

구글의 권한 네임서버에 google.com의 IP가 뭐야? 라고 물어본다

여기서 최종 답이 나온다

google.com → 142.250.196.110 → IP 반환

7단계: IP 반환 후 캐시 저장

로컬 DNS 리졸버가 받은 IP를 클라이언트(내 컴퓨터)에게 돌려준다 동시에 이 결과를 TTL 동안 캐시에 저장해둔다

브라우저는 받은 IP로 서버에 접속한다

TTL과 캐시 — DNS 전파 지연이 왜 생기는가

이전 트러블슈팅에서 겪은 DNS 전파 지연이 왜 생기는지가 보인다 가비아에서 A 레코드를 새로 등록하거나 수정하면, 권한 네임서버(가비아)에는 즉시 반영된다

그런데 전 세계 로컬 DNS 리졸버들은 각자 이전에 조회한 결과를 TTL만큼 캐시에 들고 있다 그 TTL이 만료되기 전까지는 변경된 값을 알 수가 없다

가비아 권한 네임서버: IP 변경 완료 
KT DNS 리졸버: 이전 캐시 TTL 남음, 아직 모름 
Google DNS (8.8.8.8): 이전 캐시 TTL 남음, 아직 모름

각 리졸버의 TTL이 제각각이라서, 사람마다 다른 시점에 변경된 DNS를 보게 된다 이게 DNS 전파 지연이다. 최대 48시간이 걸리는 이유도 이거다

주요 DNS 레코드 종류

권한 네임서버 안에는 도메인에 대한 여러 정보가 레코드로 저장된다

DNS 레코드란?
권한 네임서버에 저장되는 도메인 관련 정보다. 종류마다 역할이 다르다

레코드	역할	예시
A	도메인 → IPv4 주소	api.coreboard-api.xyz → 35.202.68.192
AAAA	도메인 → IPv6 주소	IPv6 환경용
CNAME	도메인 → 다른 도메인	www.example.com → example.com
MX	도메인 → 메일 서버 주소	이메일 수신 담당
NS	도메인 → 권한 네임서버 주소	ns.gabia.co.kr
TXT	도메인에 텍스트 정보 첨부	도메인 소유 인증, SPF 등

A 레코드는 도메인을 IP로 직접 연결하는 가장 기본적인 레코드다

CNAME이란?
도메인을 다른 도메인으로 연결하는 레코드다
www.coreboard.com → coreboard.com 같은 식으로, 별칭을 만들 때 쓴다
Vercel 배포할 때 CNAME → cname.vercel-dns.com 처럼 설정하는 것도 이거다

전체 흐름 정리

브라우저에 google.com 입력
          ↓
  [브라우저 캐시] → 있으면 바로 사용
          ↓ 없으면
  [OS 캐시 / hosts 파일] → 있으면 바로 사용
          ↓ 없으면
  [로컬 DNS 리졸버] → 캐시 있으면 바로 응답
          ↓ 없으면 (재귀 쿼리 시작)
  [루트 네임서버] → .com TLD 서버 주소 알려줌
          ↓
  [.com TLD 네임서버] → google.com 권한 네임서버 주소 알려줌
          ↓
  [google.com 권한 네임서버] → 142.250.196.110 반환
          ↓
  리졸버가 결과 캐시 (TTL만큼)
          ↓
  브라우저에 IP 전달 → 서버 접속

[Trouble Shooting] HTTPS로 연결하며 마주한 배포 트러블슈팅

HS0601 — Wed, 13 May 2026 12:21:16 +0900

문제 상황: Mixed Content 차단
해결 방향: 백엔드도 HTTPS로
트러블슈팅 1: DNS 전파 지연
트러블슈팅 2: Swagger API 문서 요청에서 Gateway Time-out 발생
트러블슈팅 3: Certbot 설치 중 apt lock
트러블슈팅 4: SSH 접속 불가
트러블슈팅 5: SSL 적용 후 502 Bad Gateway
결론과 회고

문제 상황 : Mixed Content 차단

CoreBoard는 Spring Boot 백엔드와 React 프론트엔드로 구성된 프로젝트다.

백엔드는 GCP Compute Engine에 먼저 배포해 두었고, 이후 프론트엔드를 Vercel에 배포하면서 두 서버를 연결하는 작업을 시작했다.

로컬 개발 환경에서는 API 호출이 정상이었다.

그런데 Vercel 배포 환경에서 브라우저를 열자마자 모든 API 요청이 차단되었다.

Mixed Content: The page at 'https://coreboard-web-drht.vercel.app/' 
was loaded over HTTPS, but requested an insecure XMLHttpRequest 
endpoint 'http://35.202.68.192:8080/boards?page=0&size=10&direction=DESC'. 
This request has been blocked; the content must be served over HTTPS.

에러 직역
혼합 콘텐츠: 'https://coreboard-web-drht.vercel.app/' 페이지는 HTTPS로 로드되었는데,
보안되지 않은 XMLHttpRequest 엔드포인트 'http://35.202.68.192:8080/...'를 요청했습니다.
이 요청은 차단되었습니다. 콘텐츠는 HTTPS로 제공되어야 합니다.

왜 이런 에러가 발생하는가?

브라우저는 Mixed Content(혼합 콘텐츠) 를 차단한다

Mixed Content란?

HTTPS로 로드된 페이지에서 HTTP 리소스(API, 이미지 등)를 요청하는 상황을 말한다.

HTTPS 페이지는 보안된 연결을 보장하는데, 거기서 HTTP 요청이 나가면 그 보안이 깨진다.

그래서 브라우저는 이를 허용하지 않고 강제로 차단한다.

처음에는 Vercel 환경변수 설정 문제를 의심했다. API 주소가 제대로 들어갔는지, 빌드에 반영됐는지 확인했다.

하지만 에러 메시지를 자세히 보면, 문제는 API 주소가 비어있는 게 아니었다.

주소는 잘 들어갔다. 다만 그 주소 자체가 http:// 로 시작하는 것이 문제였다.

따라서 해결책은 axios 설정을 고치는 것이 아니다.

백엔드 API 자체를 HTTPS로 접근 가능하게 만들어야 했다.

해결 방향: 백엔드 API도 HTTPS로

백엔드 API를 HTTPS로 제공하기 위한 구조를 설계했다.

클라이언트 (Vercel, HTTPS)
    ↓  https://api.coreboard-api.xyz
  Nginx (443 포트, SSL 처리)
    ↓  http://localhost:8080
  Spring Boot 애플리케이션

api.coreboard-api.xyz -> 35.202.68.192

구체적인 계획은 다음과 같다.

GCP VM에 고정 IP를 연결하고, api.coreboard-api.xyz 도메인의 A 레코드를 해당 IP로 설정한다.
Spring Boot에 SSL을 직접 붙이지 않고, 앞단에 Nginx 를 두어 HTTPS를 처리하게 한다.
Certbot 으로 무료 SSL 인증서를 발급받아 Nginx에 적용한다.

A 레코드란?

DNS(도메인 네임 시스템)에서 도메인 이름을 IP 주소로 연결하는 설정이다.

api.coreboard-api.xyz → 35.202.68.192 같은 식이다.

브라우저가 도메인을 입력받으면 DNS에서 A 레코드를 조회해서 실제 IP를 찾아낸다.

Nginx란?

웹 서버 소프트웨어다. 아파치(Apache)와 함께 가장 많이 쓰인다.

단독으로 정적 파일을 서빙하거나, 다른 서버 앞에서 중계 역할(Reverse Proxy)을 할 수 있다.

Reverse Proxy란?

클라이언트 요청을 먼저 받아서, 뒤쪽의 실제 서버로 대신 전달해주는 서버를 말한다.

클라이언트는 Nginx하고만 통신하고, Spring Boot가 뒤에 있다는 사실을 모른다.

SSL Termination이란?

HTTPS 암호화/복호화 처리를 Nginx 같은 앞단 서버에서 끝내고, 내부 애플리케이션 서버로는 평문 HTTP로 전달하는 방식이다.

Spring Boot가 암호화 처리까지 직접 할 필요가 없어진다.

Upstream이란?

Nginx뒤쪽에 있는 실젲 애플리케이션 서버. 이번 경우에는 SpringBoot가 Upstream이다

Certbot이란?

Let's Encrypt라는 무료 인증기관에서 SSL 인증서를 자동으로 발급받고 갱신해주는 도구다

최종 목표: 프론트엔드가 https://api.coreboard-api.xyz 주소로 API를 호출하도록 만드는 것.

트러블슈팅 1: DNS 전파 지연

문제 발생

도메인의 A 레코드를 GCP VM 고정 IP로 설정한 뒤, 바로 api.coreboard-api.xyz 로 접근을 시도했다.
설정을 저장했으니 바로 될 것이라고 생각했지만, 도메인이 정상 조회되지 않았다.

이때 확인한 증상: NXDOMAIN

NXDOMAIN이란?

DNS에서 이런 도메인은 없다(Non-Existent Domain)는 응답이다.

도메인 자체가 등록되지 않았거나, DNS에 아직 반영되지 않은 경우에 발생한다.

원인 분석

처음에는 A 레코드를 잘못 입력했거나, 저장이 안 된 줄 알았다. 그래서 권한 네임서버 를 직접 지정해서 조회해봤다.

nslookup api.coreboard-api.xyz ns.gabia.co.kr

nslookup이란?

도메인이 어떤 IP로 연결되는지 확인하는 명령어다.

두 번째 인자로 특정 DNS 서버를 지정할 수 있다.

권한 네임서버(Authoritative Name Server)란?

도메인 설정의 원본을 가지고 있는 서버다.

가비아에서 도메인을 구매했다면, 가비아의 네임서버가 권한 네임서버다.

여기서 정상 조회되면 도메인 설정 자체는 올바르게 저장된 것이다.

결과: 권한 네임서버에서는 api.coreboard-api.xyz → 35.202.68.192 로 정상 조회됐다.

하지만 Google DNS(8.8.8.8)나 Cloudflare DNS(1.1.1.1) 에서는 아직 같은 결과가 나오지 않았다.

이 차이를 보고 문제 범위를 좁혔다.

도메인 설정 자체가 틀렸다면, 권한 네임서버에서도 조회되지 않아야 한다.
권한 네임서버에서는 정상 조회됐다. 따라서 설정 자체는 맞다.
문제는 외부 DNS 서버들이 아직 변경 내용을 모른다는 것이다.

원인

DNS 전파 지연(DNS Propagation Delay) 이었다.

DNS 전파란?

도메인 설정 변경이 전 세계 DNS 서버들에 반영되기까지 걸리는 시간이다.

권한 네임서버에 설정이 반영되더라도, 각 ISP나 구글·클라우드플레어 같은 외부 DNS 서버들은 자신이 캐시에 저장해둔 이전 정보를 일정 시간 동안 그대로 사용한다.

보통 수 분에서 최대 48시간까지 걸릴 수 있다.

해결

A 레코드 설정을 다시 건드리지 않고, 권한 네임서버 기준으로 정상 등록된 것을 확인한 뒤 기다렸다.

배운 점

DNS 문제를 확인할 때는 조회 기준을 분리해야 한다. 내 PC에서 조회가 안 된다고 바로 설정을 바꾸면 안 된다.

순서는 이렇다.

권한 네임서버(가비아 등)에서 먼저 조회한다.
권한 네임서버에서 정상이면 → 설정은 맞다. 전파를 기다린다.
권한 네임서버에서도 안 되면 → 설정 자체를 다시 확인한다.

트러블슈팅 2: Gateway Time-out

문제 발생

Nginx를 설정한 뒤 Swagger UI 페이지 자체는 열렸다. 그래서 Nginx와 Spring Boot 연결이 어느 정도 된다고 생각했다.

그런데 Swagger UI에서 API 명세를 가져오는 /v3/api-docs 요청이 응답하지 않았다.

이때 화면에서 확인한 에러: 504 Gateway Time-out

504 Gateway Time-out이란?

앞단 서버(Nginx)가 뒤쪽 서버(Spring Boot)로부터 정해진 시간 안에 응답을 받지 못했을 때 발생한다.

원인 분석

처음에는 Nginx reverse proxy 설정 문제를 의심했다. Nginx를 막 설정한 상태였고, timeout 값이 너무 짧을 수도 있다고 생각했다.

하지만 바로 Nginx 문제로 단정하지 않았다. 외부 요청에서만 느린 건지, Spring Boot 자체가 느린 건지 먼저 분리해야 했다.

그래서 서버 내부에서 Spring Boot를 직접 호출해봤다.

curl -i -m 120 http://localhost:8080/v3/api-docs
# 결과: 120초 동안 응답 없음

curl이란?

터미널에서 HTTP 요청을 보낼 수 있는 명령어다.

브라우저 없이 서버가 제대로 응답하는지 확인할 때 자주 쓴다.

i는 응답 헤더를 같이 보여달라는 옵션, m 120은 최대 120초 기다리라는 옵션이다.

여기서 문제 범위가 좁혀졌다.

Nginx를 통할 때만 느렸다면 → Nginx 설정, 방화벽, proxy timeout 의심
localhost:8080 직접 호출도 120초 응답 없음 → Spring Boot 내부 문제

이후 Spring Boot 로그를 확인했다.

Init duration for springdoc-openapi is: 390994 ms
# 390994ms = 약 6분 31초

springdoc-openapi란?

Spring Boot에서 자동으로 Swagger API 명세를 생성해주는 라이브러리다.

애플리케이션이 시작된 뒤, 첫 /v3/api-docs 요청이 들어오면 전체 API를 스캔해서 문서를 만든다.

이 초기화 과정이 오래 걸릴 수 있다.

원인

springdoc-openapi 초기화 지연이었다.

Nginx는 요청을 Spring Boot로 잘 넘겼지만, Spring Boot가 /v3/api-docs 를 처리하는 데 6분 이상 걸렸다.

Nginx의 기본 timeout 설정 안에 응답이 오지 않으니 Gateway Time-out이 발생한 것이다.

해결

Nginx를 건드리지 않고, 일단 springdoc-openapi 초기화가 완료될 때까지 기다렸다.

초기화가 끝난 뒤에는 /v3/api-docs 요청이 정상적으로 응답했다.

배운 점

Gateway Time-out을 만났을 때 확인 순서:

서버 내부에서 curl localhost:8080/{해당 경로} 로 직접 호출해본다.
내부 직접 호출도 느리다 → Spring Boot 내부 문제 (로그 확인)
내부 직접 호출은 빠른데 외부만 느리다 → Nginx, 방화벽, proxy 설정 의심

에러 메시지만 보고 Nginx 설정부터 수정하면 안 된다.

트러블슈팅 3: Certbot 설치 중 apt lock 발생

문제 발생

HTTPS를 위해 Certbot을 설치하려는데 다음 에러가 발생했다.

/var/lib/dpkg/lock-frontend held by PID 381771 apt-get check -qq

에러 직역

/var/lib/dpkg/lock-frontend 파일이 PID 381771번 프로세스(apt-get check -qq)에 의해 점유되어 있습니다.

원인 분석

처음에는 Certbot 설치 명령어를 잘못 입력한 줄 알았다.

하지만 에러 메시지를 보면 문제는 Certbot이 아니었다.

apt란?

Ubuntu/Debian 계열 Linux에서 프로그램을 설치·업데이트·삭제하는 패키지 관리자다.

apt install certbot 처럼 사용한다.

apt lock이란?

Linux에서는 apt 작업이 동시에 여러 개 실행되면 충돌이 생길 수 있다.

그래서 한 apt 프로세스가 실행 중이면 lock 파일을 잡고, 다른 apt 작업이 시작되지 못하게 막는다.

/var/lib/dpkg/lock-frontend가 그 lock 파일이다.

PID란?

Process ID. Linux에서 실행 중인 모든 프로세스에 붙는 고유 번호다.

PID 381771이라고 하면 381771번 프로세스라는 뜻이다.

즉, Certbot 설치가 실패한 이유는 이미 다른 apt 프로세스가 실행 중이었기 때문이다.

원인

기존에 실행 중이던 apt 관련 프로세스(자동 업데이트 등)가 lock을 점유하고 있었다.

해결

lock을 잡고 있는 프로세스를 확인하고 종료했다.

이후 dpkg 상태를 복구한 뒤 Certbot 설치를 다시 진행했다.

dpkg란?

apt 아래에서 실제 패키지 설치/관리를 담당하는 하위 도구다.

apt가 고장나거나 중간에 끊기면 dpkg 상태도 같이 깨질 수 있어서 복구가 필요하다.

배운 점

SSL 인증서 설정이라고 해서 Nginx나 도메인만 보면 되는 게 아니다.

Certbot을 설치하려면 서버의 패키지 관리자 상태도 정상이어야 한다.

배포 트러블슈팅에서는 애플리케이션, 프록시, 인증서뿐 아니라 OS 레벨 상태까지 확인해야 한다.

트러블슈팅 4: SSH 접속 불가

문제 발생

HTTPS 설정 작업 중 서버에 SSH로 접속이 되지 않는 문제가 발생했다.

PowerShell에서 직접 SSH 접속 시도

ssh: connect to host 35.202.68.192 port 22: Connection timed out

에러 직역

35.202.68.192의 22번 포트로 연결 시도: 연결 시간 초과

Cloud Identity-Aware Proxy를 통한 연결 실패 코드: 4003
이유: failed to connect to backend

에러 직역

백엔드 연결 실패

Cloud Shell에서 포트 상태 확인

Connection refused
22 closed

SSH란?

Secure Shell. 원격 서버에 터미널로 접속하는 방법이다.

서버를 직접 앞에 두지 않고도 인터넷을 통해 명령어를 실행할 수 있게 해준다.

기본 포트는 22번이다.

GCP IAP SSH란?

Google Cloud Platform의 Identity-Aware Proxy를 통한 SSH 접속 방법이다.

22번 포트를 직접 열지 않아도 GCP 내부 네트워크를 통해 서버에 접근할 수 있는 방식이다.

이마저 안 된다면 서버 접근 경로 자체에 문제가 있다는 신호다.

원인 분석

이 문제는 Nginx나 Spring Boot가 응답을 못 하는 문제가 아니었다.

내가 서버 내부 상태를 확인하기 위한 접근 경로 자체가 막힌 문제였다.

일반 SSH 접속과 IAP SSH 접속이 모두 실패했고, 포트 확인 결과도 22 closed였다.

단순한 클라이언트 문제로 볼 수 없었다.

원인

IAP SSH 접근에 필요한 GCP 방화벽 규칙이 열려 있지 않았고, 서버 내부 SSH 상태도 복구가 필요한 상황이었다.

방화벽 규칙(Firewall Rule)이란?

서버에 들어오는 트래픽을 어떤 포트, 어떤 IP로부터 허용할지 결정하는 규칙이다.

GCP에서는 Compute Engine 인스턴스마다 방화벽 규칙을 설정할 수 있다.

IAP SSH도 GCP 내부 IP 대역(35.235.240.0/20)에서 22번 포트로 들어오는 트래픽을 허용해야 동작한다.

해결

IAP SSH 방화벽 규칙을 추가하고, startup-script 를 통해 SSH 접근을 복구했다.

startup-script란?

GCP VM이 부팅될 때 자동으로 실행되는 스크립트다.

SSH가 막혀서 직접 들어갈 수 없는 상황에서도, 인스턴스를 재시작하면서 스크립트를 주입해 복구할 수 있다.

systemd란?

Linux에서 서비스(백그라운드 프로세스)를 관리하는 시스템이다.

Spring Boot를 서버에서 서비스로 등록해두면, 서버가 재시작되거나 프로세스가 죽어도 자동으로 재실행된다.

배운 점

애플리케이션이 정상인지 확인하려면 로그를 봐야 하고, Nginx 설정을 고치려면 서버에 들어가야 한다.

SSH가 막히면 원인 분석 자체가 불가능해진다.

서버 접근 경로도 운영의 일부로 관리해야 한다.

트러블슈팅 5: 502 Bad Gateway

문제 발생

Certbot으로 SSL 인증서를 발급한 뒤, HTTPS API 호출이 정상 동작하는지 확인했다.

curl -i https://api.coreboard-api.xyz/actuator/health

응답

HTTP/1.1 502 Bad Gateway
Server: nginx/1.22.1

에러 직역

502 Bad Gateway: Nginx가 뒤쪽 서버로부터 유효한 응답을 받지 못했습니다.

502 Bad Gateway란?

앞단 서버(Nginx)가 뒤쪽 서버(Spring Boot)로 요청을 전달하려 했으나, 연결 자체가 실패했을 때 발생한다.

504는 응답이 너무 늦게 왔다이고,

502는 연결 자체가 안 됐다에 가깝다.

/actuator/health란?

Spring Boot Actuator가 제공하는 엔드포인트로, 애플리케이션이 정상 동작 중인지 확인할 수 있다.

{"status":"UP"} 같은 응답이 오면 정상이다.

원인 분석

처음에는 Nginx 설정이 잘못됐거나 Spring Boot가 죽은 것이라고 생각했다.

그래서 서버 내부에서 Spring Boot를 직접 호출해봤다.

curl -i http://localhost:8080/actuator/health

응답

curl: (7) Failed to connect to localhost port 8080 after 0 ms: Couldn't connect to server

에러 직역
localhost의 8080 포트로 연결하는 데 실패했습니다. 서버에 연결할 수 없습니다.

이 결과가 중요했다.

HTTPS 도메인으로 호출했을 때 502가 발생하면 Nginx 설정 문제처럼 보인다.

하지만 localhost:8080 직접 호출도 연결이 안 된다면, Spring Boot가 아직 8080 포트에서 요청을 받을 준비가 안 된 것이다.

즉, HTTPS 요청은 Nginx까지 도달했는데 Nginx가 뒤쪽 Spring Boot로 연결하려는 순간 8080 포트에 아무것도 없었던 것이다.

이후 journalctl로 서비스 로그를 확인했다.

Starting CoreBoardApplication

journalctl이란?

systemd로 관리되는 서비스의 로그를 확인하는 명령어다.

journalctl -u coreboard -f 처럼 사용하면 특정 서비스의 로그를 실시간으로 볼 수 있다.

Spring Boot가 아직 시작 중이었다. 서버 메모리 상태도 확인했다.

free -h

Mem: 969Mi total, used 913Mi, available 56Mi
Swap: 0B

메모리 부족 + Swap 없음 + springdoc-openapi 초기화 지연까지 겹쳐서 기동이 오래 걸리고 있었다.

Swap이란?

실제 메모리(RAM)가 부족할 때 임시로 사용하는 디스크 공간이다.

Swap: 0B는 Swap이 설정되지 않은 상태를 의미한다.

메모리 여유가 56MB밖에 없는데 Swap도 없으면, Spring Boot 기동이 크게 느려질 수 있다.

원인

SSL 인증서 발급 문제가 아니었다.

Nginx는 HTTPS 요청을 정상적으로 받았지만, upstream인 Spring Boot가 아직 8080 포트에서 요청을 받을 수 없는 상태였다.

이 502는 Spring Boot 기동 지연 때문에 발생한 문제였다.

해결

curl localhost:8080/actuator/health 로 Spring Boot가 실제로 응답 가능한 상태인지 확인
journalctl 로 애플리케이션 시작 로그 확인
free -h 로 서버 메모리 상태 확인
Spring Boot가 완전히 기동된 뒤 다시 HTTPS health check 요청

최종응답

HTTP/1.1 200
Server: nginx/1.22.1
Content-Type: application/vnd.spring-boot.actuator.v3+json

배운 점

502 Bad Gateway를 만났을 때 바로 Nginx 설정을 보면 안 된다.

먼저 upstream인 Spring Boot가 실제로 포트를 열고 응답 가능한 상태인지 확인해야 한다.

502 확인 순서

curl localhost:8080/{경로} → Spring Boot 응답 가능 여부 확인
안 된다면 journalctl -u {서비스명} 로 기동 로그 확인
free -h 로 메모리 여유 확인
그래도 원인을 모르겠다면 그때 Nginx 설정(/etc/nginx/sites-available/) 확인

결론과 회고

최종적으로 HTTPS 백엔드 API 호출이 정상화되었다

curl -i https://api.coreboard-api.xyz/actuator/health

응답 결과

HTTP/1.1 200
Server: nginx/1.22.1
Content-Type: application/vnd.spring-boot.actuator.v3+json

Actuator health 응답에서도 애플리케이션 상태가 UP으로 확인되었다

해결한 문제들 요약

트러블슈팅	에러	실제 원인	핵심 확인 방법
1	NXDOMAIN	DNS 전파 지연	권한 네임서버로 먼저 조회
2	504 Gateway Time-out	springdoc-openapi 초기화 지연	localhost 직접 curl로 분리 확인
3	apt lock	기존 apt 프로세스 충돌	lock 잡은 PID 확인 후 종료
4	SSH 접속 불가	IAP 방화벽 규칙 미설정	startup-script로 복구
5	502 Bad Gateway	Spring Boot 기동 지연	localhost curl + journalctl

가장 크게 배운 것

에러 메시지만 보고 원인을 단정하면 안 된다.

배포 문제는 계층이 있다.

브라우저
  ↓
DNS
  ↓
Nginx (Reverse Proxy)
  ↓
Spring Boot
  ↓
OS (메모리, 프로세스, 방화벽)

에러 메시지는 항상 가장 앞단에서 발생한다.

그래서 실제 원인은 훨씬 아래 계층에 있는 경우가 많다.

Gateway Time-out이 발생했을 때 Nginx 문제처럼 보였지만 실제로는 Spring Boot 내부 지연이었다.

502가 발생했을 때 SSL 문제처럼 보였지만 실제로는 Spring Boot가 아직 켜지지도 않은 상태였다.

확인 방법은 항상 계층을 분리해서 각각 확인이다.

외부에서 안 되면 내부에서 직접 호출해본다. 내부에서도 안 되면 더 아래 계층을 본다.

[Trouble Shooting]운영 배포 후 첨부파일 엔티티 변경으로 JPA 스키마 검증 실패

HS0601 — Mon, 11 May 2026 23:27:03 +0900

문제

CoreBoard에 게시글 첨부파일 생명주기 기능과 검색 기능을 추가한 뒤, dev 브랜치의 변경사항을 main으로 병합하고 운영 서버에 배포했다

배포 자체는 진행된 것처럼 보였지만, 브라우저에서 Swagger 주소로 접속하자 다음과 같은 화면이 나타났다

사이트에 연결할 수 없음
ERR_CONNECTION_REFUSED

처음에는 8080 포트나 GCP 방화벽 문제처럼 보였다
하지만 서버 내부에서 직접 확인해보니 외부 접속 문제가 아니었다

curl -i http://localhost:8080/actuator/health

결과는 다음과 같았다

curl: (7) Failed to connect to localhost port 8080 after 0 ms: Couldn't connect to server

즉, 외부 방화벽 문제가 아니라 서버 내부에서도 Spring Boot 애플리케이션이 8080 포트로 정상 기동되지 않은 상태였다

분석

먼저 systemd 상태를 확인했다

sudo systemctl status coreboard

결과만 보면 서비스는 active (running) 상태로 보였다

Active: active (running)
ExecStart=/usr/bin/java -jar /home/ggksthf29/apps/coreboard/app.jar

하지만 systemctl에서 프로세스가 살아 있다고 해서 애플리케이션이 정상적으로 HTTP 요청을 받을 준비가 끝났다는 뜻은 아니다

그래서 로그를 확인했다

sudo journalctl -u coreboard -n 300 --no-pager

로그에는 Spring Boot가 시작되다가 JPA EntityManagerFactory 초기화 단계에서 실패한 흔적이 있었다

Failed to initialize JPA EntityManagerFactory
Unable to build Hibernate SessionFactory
Schema-validation: missing column [deleted_at] in table [attachment]

이후 HikariCP가 종료되고 Tomcat도 중지되었다

HikariPool-1 - Shutdown initiated
HikariPool-1 - Shutdown completed
Stopping service [Tomcat]
Application run failed

즉, 애플리케이션은 실행을 시도했지만, JPA 스키마 검증 단계에서 실패했고 그 결과 Tomcat이 완전히 뜨지 못했다 그래서 8080 포트가 열리지 않았다

원인

원인은 엔티티 변경사항이 운영 DB 스키마에 반영되지 않은 상태에서 배포했기 때문이었다

이번 작업에서 Attachment 엔티티에 deletedAt 필드를 추가했다

@Column
private LocalDateTime deletedAt;

또한 첨부파일 상태에도 DELETED를 추가했다

public enum AttachmentStatus {
    TEMP,
    CONFIRMED,
    DELETED
}

코드 기준으로는 게시글 삭제 또는 수정 중 제거된 첨부파일을 바로 물리 삭제하지 않고 DELETED 상태로 전환한 뒤, 일정 기간이 지나면 스케줄러가 정리하는 구조로 바뀌었다 실제 변경사항에도 deletedAt 필드 추가, DELETED 상태 추가, markDeleted() 메서드 추가가 포함되어 있었다

하지만 운영 DB의 attachment 테이블에는 아직 deleted_at 컬럼이 없었다

운영 환경의 JPA 설정은 ddl-auto: validate 방식이었다. 이 방식은 엔티티를 기준으로 DB 테이블을 자동 수정하지 않고, 엔티티와 실제 DB 스키마가 일치하는지만 검사한다

그래서 Hibernate가 애플리케이션 기동 중 다음 검증을 수행했다

Attachment 엔티티에는 deletedAt 필드가 있음
→ attachment 테이블에는 deleted_at 컬럼이 없음
→ 스키마 검증 실패
→ EntityManagerFactory 생성 실패
→ Spring Boot 기동 실패

추가로, DB의 status 컬럼도 기존에는 다음 상태만 허용하고 있었다

enum('CONFIRMED','TEMP')

하지만 코드에는 DELETED 상태가 추가되었기 때문에, 이 역시 운영 DB에 반영해야 했다

정리하면 원인은 두 가지였다

1. attachment 테이블에 deleted_at 컬럼이 없었다.
2. attachment.status enum에 DELETED 값이 없었다.

해결

운영 DB에 접속해서 attachment 테이블 스키마를 직접 수정했다

먼저 DB에 접속했다

mysql -u root -p coreboard

이후 deleted_at 컬럼을 추가했다

ALTER TABLE attachment
ADD COLUMN deleted_at datetime(6) NULL;

적용 후 테이블 구조를 확인했다

DESC attachment;

확인 결과 deleted_at 컬럼이 추가되었다

| deleted_at | datetime(6) | YES | | NULL |

그 다음 status 컬럼에 DELETED 상태를 추가했다

ALTER TABLE attachment
MODIFY COLUMN status enum('TEMP','CONFIRMED','DELETED') NOT NULL;

다시 확인하니 status 컬럼이 다음처럼 변경되었다

enum('TEMP','CONFIRMED','DELETED')

DB 스키마를 수정한 뒤 애플리케이션을 재시작했다

sudo systemctl restart coreboard

처음에는 바로 curl을 날렸을 때 여전히 연결되지 않았다

curl -i http://localhost:8080/actuator/health

하지만 로그를 보니 애플리케이션이 죽은 것이 아니라, 기동 시간이 오래 걸리고 있었다 실제로 로그에는 Tomcat 초기화, JPA 초기화, HikariCP 연결 생성이 순서대로 진행되고 있었다

조금 더 기다린 뒤 최신 로그를 확인했다

sudo journalctl -u coreboard --since "2026-05-11 14:14:30" --no-pager

결과는 다음과 같았다

Initialized JPA EntityManagerFactory for persistence unit 'default'
Tomcat started on port 8080 (http) with context path '/'
Started CoreBoardApplication

즉, JPA 스키마 검증을 통과했고 Spring Boot 애플리케이션이 정상 기동되었다

성과

이번 문제를 통해 서버가 안 뜬다가 아니라, 운영 배포에서 코드 변경과 DB 스키마 변경의 순서가 중요하다는 점을 확인했다

특히 운영 환경에서 ddl-auto: validate를 사용하는 경우, Hibernate는 DB를 자동으로 바꿔주지 않는다 엔티티와 DB 스키마가 다르면 애플리케이션 기동을 막는다 이 덕분에 잘못된 스키마 상태로 서버가 떠서 런타임 중 더 큰 문제가 발생하는 것은 막을 수 있었지만, 배포 전에 스키마 변경을 먼저 반영하지 않으면 서비스 자체가 기동되지 않는다는 것도 알게 되었다

이번 트러블슈팅으로 확인한 운영 관점의 교훈은 다음과 같다

엔티티에 필드가 추가되면 운영 DB에도 컬럼 추가가 필요하다
enum 값이 추가되면 DB enum 컬럼도 함께 수정해야 한다
ddl-auto: validate 환경에서는 DB 스키마 변경을 자동으로 기대하면 안 된다
배포 후 ERR_CONNECTION_REFUSED가 보이면 방화벽보다 먼저 서버 내부 curl과 애플리케이션 로그를 확인해야 한다
systemctl active 상태만으로 애플리케이션 정상 기동을 확정하면 안 된다
Tomcat started, Started Application 로그까지 확인해야 실제 기동 완료로 볼 수 있다

최종적으로 다음 SQL을 반영해 문제를 해결했다

ALTER TABLE attachment
ADD COLUMN deleted_at datetime(6) NULL;

ALTER TABLE attachment
MODIFY COLUMN status enum('TEMP','CONFIRMED','DELETED') NOT NULL;

그리고 애플리케이션 로그에서 다음 메시지를 확인하며 정상 기동을 검증했다

Tomcat started on port 8080
Started CoreBoardApplication

이번 장애는 첨부파일 생명주기 기능을 운영에 반영하면서 발생한 DB 스키마 불일치 문제였다
앞으로는 엔티티 변경이 포함된 배포에서는 코드 배포 전에 운영 DB 변경사항을 먼저 정리하고, 최소한의 마이그레이션 SQL을 배포 체크리스트에 포함해야 한다

[JVM] Java는 실행될 때 메모리를 어떻게 나눠 쓸까?

HS0601 — Mon, 11 May 2026 17:35:07 +0900

JVM Run-Time Data Areas

JVM Run-Time Data Areas는 JVM이 Java 프로그램을 실행하는 동안 사용하는 메모리 영역들이며, 대표적으로 Method Area, Heap, JVM Stack 등이 있다

지난 주에 JVM에 대해 공부를 했었다

JVM은 자바 버츄얼 머신의 약자로, Java 프로그램을 실행해주는 가상 실행기계.

컴퓨터는 Java 코드를 쓴다고 바로 CPU가 알아듣는 게 아니라 .java파일을 javac가 .class파일로 바꾸고 JVM이 이 .class파일을 읽고 실행한다고 했었다

그리고 이때 이 .class파일 안에 들어 있는 것이 바로 bytecode라고 한다

어떤 클래스가 있는지
어떤 메서드가 있는지
new로 만든 객체가 뭔지
지금 어떤 메서드를 실행 중인지
지역변수 값이 뭔지

그래서 JVM은 실행 중 메모리를 여러 보관함으로 나눠쓴다 공식문서는 이걸 Run-Time Data Areas라고 부른다

JVM 런타임 데이터 영역, 쉽게 말하면 JVM이 프로그램 실행 중 사용하는 메모리 영역들이다

그래서 오늘 볼 핵심 보관함은 3개만 다뤄보겠다

Method Area

Method Area는 JVM의 런타임 데이터 영역 중 하나로, 클래스별 구조를 저장하는 영역이며 클래스 정보, 필드/메서드 데이터, 런타임 상수 풀, 메서드/생성자 코드, static 변수와 관련 있다

공식문서 핵심 문장으론 아래와 같다

It stores per-class structures such as the run-time constant pool, field and method data, and the code for methods and constructors.

Method Area는 클래스별 구조를 저장하고, 그 안에는 런타임 상수 풀, 필드/메서드 데이터, 메서드와 생성자 코드가 포함된다

클래스 정보 보관함, 공식문서에서는 Method Area가 클래스별 구조를 저장한다고 설명한다 예를 들면 런타임 상수 풀, 필드/메서드 데이터, 메서드와 생성자 코드 같은 것들을 말한다

class Student {
    String name;
    static String schoolName = "소초초등학교";

    void sayHello() {
        System.out.println("안녕");
    }
}

JVM은 Student클래스를 읽으면 이런 정보를 알아야 한다

이 클래스 이름은 Student구나
필드는 name, schoolName이 있구나
schoolName은 static이구나
sayHello()라는 메서드가 있구나

이런 클래스 단위 정보가 Method Area쪽과 관련이 있다 이때 명확히 구분해서 기억해야 한다

Method Area는 객체 보관함이 아니라 클래스 설명서 보관함이다

Heap

Heap은 JVM의 런타임 데이터 영역 중 하나로, 모든 클래스 인스턴스와 배열이 할당되는 영역이며, new로 생성한 객체와 인스턴스 변수가 저장되고 GC의 관리 대상이다

공식문서 핵심 문장은

The heap is the run-time data area from which memory for all class instances and arrays is allocated.

Heap은 모든 클래스 인스턴스와 배열의 메모리가 할당되는 런타임 데이터 영역이다

Heap은 new로 만든 객체가 들어가는 곳이다 공식문서도 Heap을 모든 클래스 인스턴스와 배열의 메모리가 할당되는 런타임 데이터영역이라고 설명한다 쉽게 말해 객체와 배열 저장소다

Student a = new Student();
Student b = new Student();

이 코드를 실행하면 new Student() 때문에 객체가 2개 생긴다

Heap

Student 객체 a
- name = null

Student 객체 b
- name = null

그 다음엔

a.name = "철수";
b.name = "영희";

이렇게하면 Heap 안에 각 객체 상태가 달라진다

Heap

Student 객체 a
- name = "철수"

Student 객체 b
- name = "영희"

여기서 중요한 포인트는 인스턴스 변수 name은 객체마다 따로 있으며 a.name과 b.name은 다를 수 있다는 점이다

JVM Stack

JVM Stack은 각 스레드마다 따로 생성되는 메서드 실행 공간이며, 메서드가 호출될 때마다 Stack Frame이 생성되고 그 안에 지역변수, 매개변수, operand stack, 중간 계산 결과가 저장된다

공식문서 핵심은

A new frame is created each time a method is invoked...

메서드가 호출될 때마다 새로운 frame이 생성된다

Static은 지금 실행 중인 메서드들의 작업 공간이다 공식문서에서는 각 JVM 스레드가 private JVM stack을 가지고 메서드 호출마다 frame이 만들어진다고 설명한다 그리고 frame은 지역변수와 부분 결과 등을 저장한다고 되어있다

쉽게 말해 JVM stack = 메서드 실행 기록 보관함이다

public static void main(String[] args) {
    int result = add(1, 2);
}

static int add(int a, int b) {
    int sum = a + b;
    return sum;
}

실행 흐름
main() 실행 시작 → main()용 작업 공간이 Stack에 생김 add(1, 2) 호출 → add()용 작업 공간이 Stack 위에 생김 add() 끝남 → add() 작업 공간 사라짐 main() 끝남 → main() 작업 공간 사라짐

그래서 Stack에는 보통 이런 것들이 들어간다고 보면 된다

현재 실행 중인 메서드
지역변수
매개변수
중간 계산 결과

[Java] static은 도대체 어디에 저장되고 언제 사라질까?

HS0601 — Mon, 11 May 2026 17:13:31 +0900

static은 객체 것이 아니라 클래스 것이다

공식문서 기준에서 나온 핵심은 이거다

static keyword to create fields and methods that belong to the class, rather than to an instance of the class.

static 키워드는 필드와 메서드를 객체(instance)가 아니라 클래스에 속하게 만든다

class는 붕어빵틀이고 object는 그 틀로 찍어낸 붕어빵 하나다

class Student {
    String name;
    static String schoolName = "소초초등학교";
}
// 학생마다 이름은 다르다
// 하지만 학교 이름은 모두 같다

Student a = new Student();
Student b = new Student();

a.name = "철수";
b.name = "영희";
// 철수의 이름
// 영희의 이름

근데 schoolName은? 소초초등학교

이건 학생 한 명의 것이 아니라 Student라는 클래스 전체의 것

static이 아닌 변수

String name; 이건 붕어빵마다 따로 들어가는 팥이다

철수 붕어빵 안의 팥
영희 붕어빵 안의 팥
민수 붕어빵 안의 팥

객체마다 따로 있다 공식문서도 이렇게 말한다

they each have their own distinct copies of instance variables.

같은 클래스로 객체를 여러 개 만들면, 각 객체는 인스턴스 변수를 자기 것 따로 가진다

static String schoolName;

이건 붕어빵마다 들어가는 팥이 아니라, 붕어빵 틀 옆에 붙어있는 공통 표지판

Student 클래스 공통 표지판 : 소초초등학교

그래서 학생이 100명이든 1000명이든 schoolName은 하나만 있다

공식문서에서도 이 문장이 핵심이다

there is exactly one copy of this variable in existence, regardless of how many times the class has been instantiated.

클래스가 몇 번 객체로 만들어지든, static 변수는 정확히 하나만 존재한다

static은 객체마다 따로 생기는 게 아니라 클래스에 하나만 붙는 것이다

인스턴스 변수란?

객체마다 따로 가지는 변수

static이란?

객체가 아니라 클래스에 붙는 것

static 변수란?

클래스가 하나만 가지는 공통 변수

static 메서드는 왜 객체 없이 호출 가능할까?

static 메서드도 변수랑 똑같다 객체 것이 아니라 클래스 것이다

공식문서 기준으로는 이렇게 말한다

A method that is declared static is called a class method.

static으로 선언된 메서드는 클래스 메서드라고 부른다

A class method is always invoked without reference to a particular object.

클래스 메서드는 특정 객체를 참조하지 않고 호출된다

class Calculator {
    static int add(int a, int b) {
        return a + b;
    }
}

이 메서드는 어떤 계산기 객체의 기능이 아니다

Calculator calculator = new Calculator();
calculator.add(1, 2);

이렇게 객체를 만들어서 부를 필요가 없다 그냥 클래스 이름으로 부르면 된다

Calculator.add(1, 2);

왜냐면 add()는 계산기 한 대의 상태를 쓰지 않는다

철수 계산기의 add()
영희 계산기의 add()
민수 계산기의 add()

이렇게 따로 있을 필요가 없다 그냥 공통 기능 하나면 된다

Calculator 클래스의 add()

그래서 static 메서드는 객체 없이 호출할 수 있다

static 메서드 안에서는 왜 인스턴스 변수를 바로 못 쓸까?

class Student {
    String name;
    static String schoolName = "소초초등학교";

    static void printSchool() {
        System.out.println(schoolName);
    }
}

이건 가능하다 왜냐하면 schoolName도 static이고 printSchool()도 static이기 때문이다

즉 둘 다 클래스 소속이다

그런데 이건 안 된다

class Student {
    String name;

    static void printName() {
        System.out.println(name); // 오류
    }
}

왜냐하면 name은 객체마다 다르기 때문이다

철수.name = 철수
영희.name = 영희
민수.name = 민수

그런데 printName()은 객체 없이 호출된다

Student.printName();

그러면 자바 입장에서는 누구 이름을 출력하라는거니? 철수? 영희? 민수? 아직 객체도 없는데?? 가 된다

그래서 static 메서드 안에서는 인스턴스 변수를 그냥 바로 쓸 수 없다

공식문서에서도 static메서드에서는 현재 객체를 가리키는 this나 super를 사용할 수 없다고 말한다

즉, static메서드는 지금 이 객체라는 개념을 기본으로 가지지 않는다

static은 JVM 메모리에서 어디와 관련 있을까?

객체는 객체 보관함에 들어간다
static은 클래스 보관함 쪽에 붙는다

쉽게 말하면 이건데 조금 더 개발자스럽게 말해보면

new로 만든 객체 → Heap
static 변수의 실제 값 → Java 8+에선 Heap
클래스 메타데이터 → Metaspace (Method Area)

Student a = new Student();
Student b = new Student();

이렇게하면 a, b 객체는 각각 따로 만들어진다

Heap

Student 객체 a
- name = 철수
Student 객체 b
- name = 영희

그런데 static 변수는 객체마다 복사되지 않는다

static String schoolName = "소초초등학교";

이건 클래스 쪽에 하나만 있다

Class 정보 쪽

Student 클래스
- static schoolName = 소초초등학교

그래서 객체가 100개 생겨도 schoolName은 100개가 아니라 1개다

인스턴스 변수는 객체마다 Heap에 따로 생기고, static 변수는 클래스가 로딩될 때 클래스 단위로 하나만 관리된다

Heap이란?

new로 만든 객체가 주로 저장되는 공간

Method Area란?

JVM이 클래스 메타데이터를 관리하는 메모리 영역 클래스 이름, 필드 구조, 메서드 구조 같은 클래스 단위 정보와 관련 있 (Java 8+에서 static 변수의 실제 값은 Heap에 저장됨)

그럼 static 변수는 언제 준비될까?

static 변수는 객체를 만들 때마다 생기는 것이 아니라, 해당 클래스가 JVM에 로딩될 때 클래스 단위로 준비된다
예를 들어

Student a = new Student();

를 실행하면 JVM은 Student 클래스를 먼저 읽고, 그 클래스 정보와 static 변수 schoolName을 클래스 단위로 준비한다

그 다음에 a 객체가 Heap에 만들어진다
그래서 static 변수는 객체보다 먼저 준비될 수 있다. 객체를 100개 만들어도 static 변수는 100개 생기는 것이 아니라, 클래스가 로딩될 때 준비된 하나를 계속 공유한다

그럼 static 변수는 언제 사라질까?

static 변수는 일반 객체처럼 특정 객체 하나가 사라진다고 같이 사라지지 않는다

객체 a가 사라져도 Student 클래스의 static 변수 schoolName은 그대로 남아 있다

static 변수는 해당 클래스가 JVM에서 더 이상 사용되지 않아 언로드될 때 함께 정리될 수 있다

일반적인 Spring Boot 애플리케이션에서는 서버가 실행되는 동안 주요 클래스들이 계속 사용되기 때문에, static 값도 보통 애플리케이션이 종료될 때까지 남아 있다고 이해하면 된다

Spring Boot 앱이 종료되면 JVM 프로세스가 끝나고, 그 JVM 메모리 안에 있던 static 값도 사라진다고 이해하면 됨

static을 남발하면 왜 테스트와 유지보수가 어려울까?

static은 편하다 객체 안 만들어도 바로 쓸 수 있으니까.

JwtUtil.createToken(...)
PasswordUtil.encrypt(...)
DateUtil.now()

근데 문제가 있다 너무 쉽게 아무 데서나 접근할 수 있다

class DiscountPolicy {
    static int discountRate = 10;
}

DiscountPolicy.discountRate = 50;

10에서 50으로 바꾼다고 가정하면 전부 영향을 받는다

A 테스트는 10% 할인을 기대함
B 테스트가 static 값을 50%로 바꿈
A 테스트가 갑자기 실패함

이런 식으로 static값은 공유 상태가 되기 쉽다 공유 상태란 쉽게 말해 여러 사람이 같이 쓰는 화이트보드와 같다

누가 뭘 지웠는지 누가 뭘 바꿨는지 모르면 나중에 찾기 어렵다 그래서 static은 특히 이런 경우 조심해야 한다

값이 바뀌는 static 변수
외부 API를 호출하는 static 메서드
현재 시간, 랜덤값, 토큰 생성처럼 테스트마다 결과가 달라지는 static 메서드

이런 것들은 테스트에서 가짜 객체로 바꾸기 어렵다

Spring에서 무조건 static으로 안 만드는 이유

Spring에서는 객체를 직접 만들지 않고 Spring이 객체를 관리한다 이 객체를 Spring Bean이라고 부른다

@Service
public class PostService {
    private final PostRepository postRepository;

    public PostService(PostRepository postRepository) {
        this.postRepository = postRepository;
    }
}

여기서 PostService는 static으로 만들지 않는다 PostService는 혼자 일하는 게 아니라 PostRepository가 필요하다

즉, 의존성이 있다

PostService는 PostRepository가 필요함
PostRepository는 DB 접근을 담당함

Spring은 이런 필요한 객체들을 대신 연결해준다

PostService 만들 때 → PostRepository 넣어줌 → 필요한 설정 넣어줌 → 테스트할 때 가짜 Repository로 바꿀 수도 있음

그런데 static으로 만들면 Spring이 관리하는 흐름에서 벗어나기 쉽다

public class PostService {
    public static void createPost() {
        // repository를 어떻게 넣을 건데?
    }
}

static메서드는 객체 없이 호출되기 때문에 생성자를 통해 의존성을 주입받는 구조와 잘 맞지 않는다 그래서 Spring에서는 이렇게 생각한다

공통 상수 → static final 가능
상태 없는 단순 유틸 → static 가능
비즈니스 로직, DB 접근, 외부 연동 → Spring Bean으로 관리

공유 상태란?

여러 코드가 같이 바라보고 바꿀 수 있는 값

Spring Bean이란?

Spring이 대신 만들고 관리하는 객체

의존성 주입(DI)이란?

어떤 객체가 필요한 다른 객체를 직접 만들지 않고 외부에서 받는 방식

정리하면 static은 객체마다 따로 생기는 값이 아니라 클래스 단위로 하나만 관리되는 값 또는 기능이다

그래서 공통 상수나 상태 없는 유틸 메서드에는 사용할 수 있지만, 값이 바뀌는 공유 상태나 DB 접근, 비즈니스 로직에는 남발하면 테스트와 유지보수가 어려워질 수 있다

Spring에서는 이런 비즈니스 객체를 static으로 만들기보다 Bean으로 등록하고, 필요한 의존성을 생성자를 통해 주입받는 방식이 더 자연스럽다

[코드트리 후기] 코딩테스트 준비, 갭체크부터 시작하기

HS0601 — Sun, 10 May 2026 14:44:02 +0900

코드트리에서 챌린지를 한다고 해서 참여를 해보려고 한다

아래 질문을 길잡이 삼아, 떠오르는 생각들을 편하게 들려주세요.

갭체크를 응시하면서 어떤 생각이 드셨나요? 문제 난이도는 어땠나요?
- 사용자의 수준에 맞춰서 문제가 나오는 것 같았다
갭체크가 알려준 내 강점과 약점은 어떤 부분이었나요?
- 문제가 조금만 길어져도 금방 포기해버리는 습관이 가장 큰 약점인 것 같고
- 아는 문제가 나오면 빠르게 풀어버리는 게 강점인 것 같다
  - 아마 꾸준한 반복훈련이 동반된다면, 누구보다 빠르게 풀 가능성이 보였다
추천 학습 경로를 따라가 보니 어떤 점이 도움이 됐나요?
- 아마 처음부터 어려운 문제나, 응용문제랍시고 새로운 문법을 요구한다면 포기했을 것 같은데,
  문법부터 차근차근 쌓아올라가는 게 큰 도움이 될 것 같다 기대가된다
다른 학습 서비스와 비교해서 어떤 점이 좋았거나 아쉬웠나요?
- 다른 학습 서비스는 문법을 익히는 시간은 주지 않는다 스스로 학습된 사용자만이 문제를 풀 수 있다는 점이 아쉬웠으며
  코드트리의 가장 마음에 드는 점은, 커리큘럼과 진척도가 한 눈에 보인다는 점이다
- 아쉬운 점은 내 의지력인 것 같다 문장이 길어지면 의도를 파악하기가 매우 힘들고 이때 스스로가 문해력이 많이 딸리나?싶다 문제에 대한 해설풀이(문제의도?)가 있다면 좋을 것 같기도 하다
- 또한 두번째 아쉬운 점은, 잔디심기다 연달아서 문제를 풀다보면, 다음 날 문제를 풀지 않았더라도 잔디가 심어진다

위 결과물 또한, 1번부터 12초 소요시간이 걸렸다고 되어있는데 ㅋㅋㅋ 긴 문장일수록 빠른 포기를 해버린다

[Java]String은 왜 불변인가 — StringBuilder, StringBuffer와 차이

HS0601 — Fri, 8 May 2026 15:26:21 +0900

String은 왜 불변인가

Java 공식문서에서 String을 이렇게 정의한다

Strings are constant; their values cannot be changed after they are created.

쉽게 말하면, String 객체는 한번 만들어지면 내부 값을 절대 못 바꾼다

String s = "안녕";
s = "안녕하세요"; // 바꾼 거 아닌가?라는 의문이 들텐데

바꾼 게 아니라 s라는 변수가 다른 객체를 가리키도록 바뀐 것이다 "안녕"이라는 객체 자체는 그대로 메모리에 살아있다

"안녕"      ← 이 객체는 그대로 존재함
"안녕하세요" ← 새로 만들어진 객체
s           ← 이제 "안녕하세요"를 가리킴

왜 불변으로 만들었냐

1. String Pool

공식문서에 이런 말이 있다

The Java language provides special support for the string concatenation operator, and for conversion of other objects to strings. String objects are cached in a pool.

Java는 String을 특별하게 취급해서, 같은 문자열이면 객체를 새로 만들지 않고 공유한다

String a = "민수";
String b = "민수";

System.out.println(a == b); // true (같은 객체!)

s랑 b가 같은 민수 객체를 공유하고 있다 근데 만약 String이 불변이 아니라면?

a.setValue("진우"); // 만약 이게 된다면?
System.out.println(b); // "진우" 나와버림 ← 대참사

a를 바꿨는데 공유하고 있으니까 b도 바뀌어버리는 것.

그래서 공유하려면 절대 못 바꾸게 해야 한다

2. 보안

DB 연결할 때 자주 보는 코드가 있다

String url = "jdbc:mysql://localhost:3306/mydb";
connect(url);

connect() 메서드 안에 url을 몰래 바꿔버릴 수 있으면 큰일이라서 String이 불변이면 어디서도 못 바꾸니까 안전해진다

3. hashCode 캐싱

String은 HashMap의 key로 엄청 많이 쓰인다 hashCode()를 매번 계산하면 느리니까, 한번 계산한 hashCode를 내부에 저장해둔다 불변이라서 값이 안 바뀌고 그래서 캐싱이 가능한 것이다

그럼 String 더하기는 어떻게 되냐

String s = "안녕";
s = s + " 민수";

이게 내부에서 어떻게 동작하는가?

1. 안녕 객체 존재

2. 민수 객체 존재

3. 둘을 합친 안녕민수 객체를 새로 만듦

4. s가 새 객체를 가리킴

5. 기존 안녕은 아무도 참조 안 하면 GC 대상

즉, 더하기 한 번 할 때마다 새 객체가 만들어진다 그래서 아래 같은 코드는 위험하다

String result = "";
for (int i = 0; i < 10000; i++) {
    result += i; // 매 반복마다 새 객체 생성
}

만 번 반복하면 객체가 만 개 만들어지는 거라 메모리 낭비 + 느려진다

그래서 나온 게 StringBuilder

공식문서에서 StringBuilder를 이렇게 설명한다

A mutable sequence of characters. Provides an API compatible with StringBuffer, but with no guarantee of synchronization.

변경 가능한 문자 시퀀스. StringBuffer와 호환되는 API를 제공하지만, 동기화를 보장하지 않는다.

핵심은, mutable(변경 가능)이다 append() 할 때마다 새로운 String 결과 객체를 계속 만들지 않고, 내부의 변경 가능한 버퍼에 문자를 누적한다

StringBuilder sb = new StringBuilder();
for (int i = 0; i < 10000; i++) {
    sb.append(i); // 같은 객체에 이어붙임
}
String result = sb.toString();

이러면 객체 하나로 끝나며 훨씬 빠르다

공식문서에서 StringBuffer를 이렇게 설명한다

A thread-safe, mutable sequence of characters.

변경 가능하지만 thread-safe다. 여러 스레드가 동시에 건드릴 수 있는 상황을 고려한 클래스다

	StringBuilder	StringBuffer
동기화(thread-safe)	없음	있음
속도	빠름	느림
언제 씀	단일 스레드	멀티 스레드

공식문서도 이렇게 말한다

Where possible, it is recommended that this class be used in preference to StringBuffer as it will be faster under most implementations.

가능한 경우, 대부분의 구현에서 더 빠르기 때문에 StringBuffer보다 StringBuilder를 쓰는 걸 권장한다

즉, 멀티 스레드 환경 아니면 StringBuilder를 쓴다

하지만 문자열을 반복해서 이어붙이면 매번 새 String 객체가 만들어질 수 있어서 성능과 메모리 측면에서 비효율적이다

그래서 String은 불변이라 반복 연결 시 새 객체가 계속 생겨 비효율적이므로, 단일 스레드에서는 StringBuilder, 여러 스레드가 같은 버퍼를 공유하는 경우에는 동기화되는 StringBuffer를 고려한다

[JPA]영속성 컨텍스트

HS0601 — Thu, 7 May 2026 12:52:39 +0900

분량이 꽤 많아보이는데, 프로젝트에 접목시키며 이해하는 게 재밌어서 추가추가하다보니 목차만 열여덟개다 ^0^/

영속성 컨텍스트
EntityManager와 영속성 컨텍스트의 관계
영속성 컨텍스트의 핵심 특징 1: 같은 id는 같은 객체다
영속성 컨텍스트의 핵심 특징 2: 1차 캐시
영속성 컨텍스트의 핵심 특징 3: 엔티티 생명주기 관리
Dirty Checking: 왜 save 없이 UPDATE가 나가나
Flush: DB에 실제 SQL이 나가는 시점
Flush는 언제 일어나나
Flush와 Commit은 다르다
쓰기 지연: INSERT/UPDATE/DELETE를 바로 안 보내는 이유
findById 후 save를 또 부르면 왜 어색한가
merge는 detached 객체를 다시 managed로 붙이는 것이 아니다
영속성 컨텍스트는 트랜잭션 범위와 강하게 묶인다
@Transactional이 없으면 왜 수정이 안 되나
영속성 컨텍스트와 지연 로딩
영속성 컨텍스트가 너무 커지면 문제다
트랜잭션 안에서 조회한 값은 DB 최신값이 아닐 수도 있다
영속성 컨텍스트와 DB 트랜잭션 격리 수준은 다른 개념이다

공식문서에서는 이렇게 말한다

Every instance of EntityManager has an associated persistence context.

모든 EntityManager 인스턴스는 연결된 영속성 컨텍스트를 가진다

A persistence context is a set of entity instances in which for any given persistent entity identity there is a unique entity instance.

영속성 컨텍스트는 엔티티 인스턴스들의 집합이며, 특정 영속 엔티티 식별자마다 유일한 엔티티 인스턴스가 존재한다

Within the persistence context, the entity instances and their lifecycle are managed.

영속성 컨텍스트 안에서 엔티티 인스턴스와 그 생명주기가 관리된다

즉, EntityManager는 영속성 컨텍스트를 다루는 API이고, 영속성 컨텍스트는 실제로 엔티티 객체들을 붙잡고 관리하는 공간이다

EntityManager란?

엔티티를 저장, 조회, 삭제, 병합하는 JPA 핵심 API

개발자가 직접 영속성 컨텍스트를 만지는 게 아니라, EntityManager라는 객체가 그 방의 문을 열고 닫고 안에 뭔가 넣고 꺼내는 역할을 한다

Persistence Context란?

EntityManager가 관리하는 엔티티 보관/추적 공간

영속성 컨텍스트

영속성 컨텍스트는 @Transactional 안에서 JPA가 엔티티 객체를 추적 가능한 상태로 올려두는 메모리 공간이다

@Transactional
public void updatePost(Long postId, String title) {
    Post post = postRepository.findById(postId)
            .orElseThrow();

    post.changeTitle(title);
}

save()를 안 불렀는데도 UPDATE가 나가는 이유는, post가 조회되는 순간 영속성 컨텍스트에 들어가서 managed상태가 되기 때문이다

Hibernate 공식 Javadoc도 이걸 정확히 말한다

Persistent instances are held in a managed state by the persistence context.

영속 인스턴스들은 영속성 컨텍스트에 의해 관리 상태로 유지된다

Any change to the state of a persistent instance is automatically detected and eventually flushed to the database.

영속 인스턴스 상태의 모든 변경은 자동으로 감지되고 결국 DB로 flush된다.

This process of automatic change detection is called dirty checking…

이 자동 변경 감지 과정을 dirty checking이라고 부른다

Managed란?

영속성 컨텍스트가 관리 중인 상태

영속성 컨텍스트란?

JPA가 엔티티 객체들을 담아두는 임시 방, 이 방 안에 들어온 엔티티는 JPA가 감시한다. 값이 바뀌면 JPA가 알아채고, 나중에 DB에 자동으로 반영해줌

EntityManager와 영속성 컨텍스트의 관계

EntityManager는 영속성 컨텍스트를 조작하는 손잡이다

Jakarta Persistence 공식 API 문서에서는 이렇게 말한다

The EntityManager API is used to perform operations that affect the state of the persistence context, or that modify the lifecycle state of individual entity instances.

EntityManager API는 영속성 컨텍스트의 상태에 영향을 주거나 개별 엔티티 인스턴스의 생명주기 상태를 변경하는 작업에 사용된다

entityManager.persist(post);
entityManager.find(Post.class, 1L);
entityManager.remove(post);
entityManager.merge(post);
entityManager.flush();
entityManager.clear();

이런 메서드들은 전부 DB를 직접 만진다기보다, 우선 영속성 컨텍스트 안의 엔티티 상태를 바꾸는 명령으로 이해해야 한다

아래 코드를 보자

entityManager.persist(post);

이 코드를 호출했다고 항상 그 자리에서 즉시 INSERT SQL이 나가는 게 아니다

Hibernate 문서에 따르면 SQL은 보통 persist()나 remove() 같은 메서드와 동기적으로 바로 실행되지 않는다 flush 때 DB와 동기화된다

영속성 컨텍스트의 핵심 특징 1: 같은 id는 같은 객체다

공식문서에서 제일 중요한 부분은 이거다

for any given persistent entity identity there is a unique entity instance

특정 영속 엔티티 식별자마다 유일한 엔티티 인스턴스가 존재한다

예를들어 DB에 posts.id = 1인 row가 있다고 하자

Post post1 = entityManager.find(Post.class, 1L);
Post post2 = entityManager.find(Post.class, 1L);

System.out.println(post1 == post2); // true

같은 트랜잭션, 같은 영속성 컨텍스트 안에서는 post1과 post2가 같은 Java 객체다

이게 왜 중요하냐면, 같은 DB row를 Java 객체 여러 개로 들고 있으면 데이터가 꼬인다

예를들어 이런 일이 생길 수 잇다

Post a = findPost(1L); // DB row #1을 표현하는 객체 A
Post b = findPost(1L); // DB row #1을 표현하는 객체 B (다른 객체)

a.changeTitle("제목 A");
b.changeTitle("제목 B");
// 어떤 값이 DB에 반영돼야 해??

만약, a와 b가 서로 다른 객체라면 마지막에 어떤 값이 DB에 반영되어야 하는지 헷갈린다 그래서 영속성 컨텍스트는 같은 id는 같은 객체 하나로 유지한다

Hibernate공식 소개 문서도 이걸 1차 캐시 관점에서 설명한다

A persistence context is a sort of cache; we sometimes call it the "first-level cache" ...

영속성 컨텍스트는 일종의 캐시이며, 때때로 “first-level cache”라고 부른다

the context holds a unique mapping from the identifier of the entity instance to the instance itself.

컨텍스트는 엔티티 식별자에서 엔티티 인스턴스 자체로 가는 유일한 매핑을 가진다

JPA는 이걸 방지하려고 하나의 id → 하나의 객체 보장을 함. 이게 동일성 보장

영속성 컨텍스트의 핵심 특징 2: 1차 캐시

동일성 보장이 작동하는 이유는 바로 1차 캐시때문이다

영속성 컨텍스트 내부에는 이런 형태로 Map이 있다고 생각하면된다

Map<식별자, 엔티티 객체>
예: { 1L → Post#1 객체, 2L → Post#2 객체 }

그리고 흐름을 보자

// 1. 첫 번째 조회
Post post1 = entityManager.find(Post.class, 1L);
// → Map에 {1L: post1}이 없음 → DB에 SELECT 쿼리 실행 → 결과를 Map에 저장

// 2. 두 번째 조회
Post post2 = entityManager.find(Post.class, 1L);
// → Map에 {1L: post1}이 이미 있음 → DB 안 가고 post1 반환

Jakarta API 문서도 find()에 대해 이렇게 말한다

If the entity instance is contained in the persistence context, it is returned from there.

엔티티 인스턴스가 영속성 컨텍스트에 포함되어 있으면, 거기서 반환된다.

1차 캐시는 성능 최적화 용도도 있지만, 본질은 같은 트랜잭션 안에서 엔티티 동일성을 보장하는 저장소다 중복 조회 줄이는 건 덤으로 얻는 효과

영속성 컨텍스트의 핵심 특징 3: 엔티티 생명주기 관리

JPA 공식문서는 엔티티 생명주기를 이렇게 나눈다

An entity instance can be characterized as being new, managed, detached, or removed.

엔티티 인스턴스는 new, managed, detached, removed 상태로 구분될 수 있다

// 항상 네 가지 상태 중 하나
New(Transient) → Managed → Detached
                        ↘ Removed

1. New / Transient 상태 : JPA 모르는 순수 Java 객체

A new entity instance has no persistent identity, and is not yet associated with a persistence context.

new 엔티티 인스턴스는 영속 식별자가 없고, 아직 영속성 컨텍스트와 연결되어 있지 않다

Post post = new Post("title", "content");

이 상태는 그냥 Java 객체다 DB와도 관계없고 영속성 컨텍스트도 모른다 이떄 값을 바꿔도 JPA는 관심없다

post.changeTitle("new title");

아무 SQL도 안 나간다

Persistent identity란?

DB에서 엔티티를 식별하는 값. 보통 @Id

2. Managed 상태 : 영속성 컨텍스트가 감시 중인 상태

A managed entity instance is an instance with a persistent identity that is currently associated with a persistence context.

managed 엔티티 인스턴스는 영속 식별자를 가지고 현재 영속성 컨텍스트와 연결된 인스턴스다

쉽게 말해, 영속성 컨텍스트의 방에 들어온 상태다 값이 바뀌면 JPA가 알아채고 flush 시점에 자동으로 SQL 생성한다

Managed가 되는 두 가지 방법

// 방법 1. persist() — 새 엔티티를 저장 예약
entityManager.persist(post);

// 방법 2. find() 또는 findById() — 조회하면 자동으로 managed
Post post = entityManager.find(Post.class, 1L);
Post post = postRepository.findById(1L).orElseThrow(); // Spring Data JPA

조회된 엔티티는 자동으로 managed 상태가 된다 이게 dirty checking 의 전제.

3. Detached 상태 : JPA 관리가 끊긴 상태

Detached entity instances continue to live outside of the persistence context in which they were persisted or retrieved.

detached 엔티티 인스턴스는 자신이 저장되거나 조회되었던 영속성 컨텍스트 밖에서도 계속 존재한다

Their state is no longer guaranteed to be synchronized with the database state.

그 상태는 더 이상 DB 상태와 동기화된다고 보장되지 않는다

트랜잭션이 끝나면 영속성 컨텍스트도 닫힌다 그러면 그 안에 있던 엔티티들은 전부 datached 상태가 된다

@Transactional
public Post getPost(Long id) {
    return postRepository.findById(id).orElseThrow();
} // ← 이 중괄호 넘어가는 순간 트랜잭션 종료, post는 detached가 됨

밖에서 값을 바꿔도

Post post = postService.getPost(1L); // 이미 detached
post.changeTitle("수정");             // JPA가 추적 안 함 → UPDATE 안 나감

4. Removed 상태 : 삭제 예약된 상태

공식문서의 remove() 설명은 이렇다

Mark a managed entity instance as removed, resulting in its deletion from the database when the persistence context is synchronized with the database.

managed 엔티티 인스턴스를 removed로 표시하고, 영속성 컨텍스트가 DB와 동기화될 때 DB에서 삭제되게 한다

중요한 포인트는 remove() 호출 즉시 DELETE SQL이 나간다는 뜻이 아니다 삭제 예정 상태로 표시되고, flush 때 DELETE가 나간다

Post post = entityManager.find(Post.class, 1L);
entityManager.remove(post);
// → 즉시 DELETE SQL이 나가는 게 아니라, "삭제 예정" 표시만 함
// → flush 시점에 DELETE SQL 생성됨

Dirty Checking: 왜 save 없이 UPDATE가 나가나

Dirty Checking은 영속성 컨텍스트가 managed 엔티티의 변경을 감지하는 기능이다

Hibernate 공식 Javadoc에서

Any change to the state of a persistent instance is automatically detected and eventually flushed to the database.

persistent 인스턴스 상태의 변경은 자동으로 감지되고 결국 DB로 flush된다라고 말하고 있다

This process of automatic change detection is called dirty checking…

이 자동 변경 감지 과정을 dirty checking이라고 한다

@Transactional
public void updateTitle(Long postId, String newTitle) {
    Post post = postRepository.findById(postId).orElseThrow();
    post.changeTitle(newTitle);
    // save() 어디에도 없음!
}

근데 UPDATE SQL이 왜 나갈까?

흐름

1. @Transactional → 트랜잭션 시작, 영속성 컨텍스트 열림
2. findById() → DB에서 Post 조회
3. Post를 영속성 컨텍스트에 저장 (managed 상태)
4. 이 시점의 Post 상태를 "스냅샷"으로 따로 기억해둠
5. post.changeTitle(newTitle) → Java 객체 값 변경 (아직 SQL 없음)
6. 메서드 끝 → 트랜잭션 commit 직전에 flush 실행
7. flush: 현재 Post 상태 vs 스냅샷 비교 → 달라졌으면 UPDATE SQL 생성
8. DB에 UPDATE 실행
9. commit → 확정

스냅샷이 핵심이다. JPA는 엔티티를 영속성 컨텍스트에 넣을 때, 그 순간의 상태를 복사해서 따로 저장한다

flush할 때 현재 상태랑 비교해서 뭐가 바뀌었는지 알아내는 것이다 이게 바로 Dirty Checking.

Hibernate User Guide도 UPDATE 생성 시점을 이렇게 말한다

The UPDATE statement is generated by EntityUpdateAction during flushing if the managed entity has been marked modified.

managed 엔티티가 modified로 표시되면 flush 중에 EntityUpdateAction에 의해 UPDATE 문이 생성된다

The dirty checking mechanism is responsible for determining if a managed entity has been modified since it was first loaded.

dirty checking 메커니즘은 managed 엔티티가 처음 로드된 이후 수정되었는지 판단하는 책임이 있다

단, managed 상태에서만 작동한다

Post post = new Post();        // new → dirty checking 없음
post.changeTitle("A");         // 추적 안 됨

entityManager.detach(post);   // detached → dirty checking 없음
post.changeTitle("B");         // 추적 안 됨

Post post = entityManager.find(Post.class, 1L); // managed!
post.changeTitle("C");         // 이건 추적됨

Flush: DB에 실제 SQL이 나가는 시점

Flush는 영속성 컨텍스트의 변경 사항을 DB SQL로 동기화하는 과정이다 Hibernate 공식문서에서는 아래처럼 말하고 있다

Flushing is the process of synchronizing the state of the persistence context with the underlying database.

flush는 영속성 컨텍스트의 상태를 underlying database와 동기화하는 과정이다

그리고 정말 중요한 문장으론,

The persistence context acts as a transactional write-behind cache, queuing any entity state change.

영속성 컨텍스트는 transactional write-behind cache처럼 동작하며, 엔티티 상태 변경을 큐에 쌓는다

changes are first applied in-memory and synchronized with the database during flush time.

변경은 먼저 메모리에 적용되고, flush 시점에 DB와 동기화된다

The flush operation takes every entity state change and translates it to an INSERT, UPDATE or DELETE statement.

flush 작업은 각 엔티티 상태 변경을 INSERT, UPDATE, DELETE 문으로 변환한다

postRepository.save(post);

post.changeTitle("수정");

이 순간 DB가 바로 바뀐다고 생각하면 안 된다

[영속성 컨텍스트] → flush → [DB에 SQL 전송] → commit → [DB 확정]

flush는 SQL을 DB로 보내는 것, commit은 그 트랜잭션을 최종 확정하는 것

Write-behind란?

변경 SQL을 즉시 실행하지 않고 모아뒀다가 flush 때 실행하는 방식

Flush는 언제 일어나는 세가지 시점

1. 트랜잭션 commit 직전 (기본)
2. JPQL/HQL 쿼리 실행 직전 (필요할 때)
3. entityManager.flush() 직접 호출

Post post = new Post("title", "content");
entityManager.persist(post); // 저장 예약, 아직 DB에 없음

// 이 쿼리 결과에 방금 persist한 Post가 포함되어야 함
List<Post> posts = entityManager
    .createQuery("select p from Post p", Post.class)
    .getResultList();

만약, flush 없이 쿼리를 날리면 DB에는 아직 INSERT가 안 됐으니까 방금 만든 Post가 결과에 안나온다

그래서 Hibernate가 쿼리 결과에 영향을 줄 수 있으면, 쿼리 전에 flush를 먼저 실행한다

Flush와 Commit은 다르다

구분	의미
flush	영속성 컨텍스트 변경을 SQL로 DB에 보냄
commit	트랜잭션을 확정함
rollback	트랜잭션 변경을 취소함

@Transactional
public void test() {
    Post post = new Post("title", "content");
    entityManager.persist(post);
    
    entityManager.flush(); // ← SQL은 DB에 전송됨
    
    throw new RuntimeException(); // ← 예외 발생
    // 메서드가 예외로 끝나면 @Transactional이 rollback 처리
}

이 경우

flush() 때 INSERT SQL이 DB로 전송됨
하지만 RuntimeException 때문에 @Transactional이 rollback 처리
최종적으로 DB에 저장 안 됨

즉, flush가 됐어도 commit 전에 rollback되면 원상보구다

쓰기 지연: INSERT/UPDATE/DELETE를 바로 안 보내는 이유

영속성 컨텍스트 내부에는 쓰기 지연 저장소(Action Queue) 가 있다

@Transactional
public void createMany() {
    entityManager.persist(new Post("A")); // INSERT 예약
    entityManager.persist(new Post("B")); // INSERT 예약
    entityManager.persist(new Post("C")); // INSERT 예약
    // 아직 SQL 안 나감
} // ← 여기서 commit 직전에 flush → INSERT A, B, C 한꺼번에 나감

특징

SQL을 모아서 한꺼번에 보낼 수 있어 (DB round-trip 줄임)
Hibernate가 Batch Insert 최적화 적용 가능

예외, ID 생성 전략이 IDENTITY이면 (@GeneratedValue(strategy = IDENTITY))

persist() 직후에 즉시 INSERT가 나간다

왜냐면 DB가 INSERT를 실행해야 PK를 알 수 있어서, JPA가 1차 캐시에 저장하려면 id를 먼저 알아야 한

findById 후 save를 또 부르면 왜 어색한가

// 어색한 패턴
@Transactional
public void updatePost(Long id, String title) {
    Post post = postRepository.findById(id).orElseThrow();
    post.changeTitle(title);
    postRepository.save(post); // ← 이게 왜 어색하냐
}

findById()로 조회한 post는 이미 managed 상태다 managed 엔티티는 dirty checking 대상이라, changeTitle()만 해도 flush 때 자동으로 UPDATE가 나간다

그래서 save()가 불필요한 경우가 많다 Spring Data JPA의 save()는 내부에서 이미 managed면 merge를 시도하는데, merge는 아래에서 설명하지만 생각보다 위험하

// 자연스러운 패턴
@Transactional
public void updatePost(Long id, String title) {
    Post post = postRepository.findById(id).orElseThrow();
    post.changeTitle(title);
    // save() 없어도 flush 때 UPDATE 나감
}

단, 신규 저장에는 당연히 save() 써야한다

Post post = new Post("title", "content"); // new 상태
postRepository.save(post); // persist() 호출 → managed 상태로 전환

merge는 detached 객체를 다시 managed로 붙이는 것이 아니다

이게 무슨 말이냐면, 공식문서부터 보자

The merge operation allows for the propagation of state from detached entities onto persistent entities managed by the entity manager.

merge 작업은 detached 엔티티의 상태를 EntityManager가 관리하는 persistent 엔티티로 전파할 수 있게 한다

If X is a detached entity, the state of X is copied onto a pre-existing managed entity instance X'…

X가 detached 엔티티이면, X의 상태는 같은 식별자의 기존 managed 엔티티 X'에 복사된다

중요한 건 detached 객체 자체가 managed로 바뀌는 게 아니라, 그 상태가 managed 객체로 복사된다는 점이다

Post detachedPost = new Post();
detachedPost.setId(1L);
detachedPost.changeTitle("수정된 제목");

Post managedPost = entityManager.merge(detachedPost);
// ↑ 반환값이 중요함!

merge의 실제 동작

detachedPost의 id(1L)로 DB에서 또는 1차 캐시에서 Post#1을 조회
조회된 Post#1 (managed) 에 detachedPost의 값을 복사함
그 managed 엔티티를 반환

detachedPost 자체가 managed로 바뀌는 게 아니

detachedPost.changeTitle("A"); // 추적 안 됨
managedPost.changeTitle("B");  // 추적됨

merge의 위험성: DTO처럼 일부 필드만 있는 객체를 merge하면

Post dto = new Post();
dto.setId(1L);
dto.setTitle("수정된 제목");
// content 필드는 null

entityManager.merge(dto);
// → DB의 Post#1의 content가 null로 덮어써짐

그래서 일반적으로 권장하는 패턴

// DB에서 managed 엔티티 조회 후 필요한 필드만 직접 변경
Post post = postRepository.findById(id).orElseThrow();
post.changeTitle("수정된 제목");
// dirty checking으로 UPDATE

영속성 컨텍스트는 트랜잭션 범위와 강하게 묶인다

영속성 컨텍스트는 트랜잭션이 시작될 때 열리고, 트랜잭션이 끝날 때 닫힌다.

@Transactional 시작 → 영속성 컨텍스트 열림
@Transactional 종료 → 영속성 컨텍스트 닫힘 → 모든 엔티티 detached

공식문서도 이걸 그대로 말한다

The persistence context ends when the associated JTA transaction commits or rolls back

연결된 트랜잭션이 commit 또는 rollback되면 영속성 컨텍스트가 끝난다

all entities that were managed by the EntityManager become detached.

EntityManager가 관리하던 모든 엔티티는 detached가 된다

코드로 보면 이렇다

@Transactional
public void updatePost(Long id, String title) {
    // 영속성 컨텍스트 열려 있음
    Post post = postRepository.findById(id).orElseThrow(); // managed
    post.changeTitle(title); // 변경 감지됨
}
// ← 여기서 트랜잭션 종료
//   → flush → UPDATE → commit → 영속성 컨텍스트 닫힘 → post는 detached

반대로 @Transactional이 없으면, findById() 호출 순간에만 짧게 영속성 컨텍스트가 열렸다 바로 닫혀버린다

그러면 반환된 post는 이미 detached라서 changeTitle()을 해도 JPA가 추적하지 못하고 UPDATE가 나가지 않는다

@Transactional이 없으면 왜 수정이 안 되나

// @Transactional 없음
public void updatePost(Long id, String title) {
    Post post = postRepository.findById(id).orElseThrow();
    post.changeTitle(title);
    // UPDATE 안 나감
}

이유

@Transactional이 없으면, findById() 호출할 때 짧게 살다 사라지는 영속성 컨텍스트가 열리고 닫혀
메서드 밖에서 changeTitle()을 호출하는 시점엔 이미 영속성 컨텍스트가 닫혀 있어서 post는 detached
dirty checking이 작동 안 함

그래서 수정이 필요한 서비스 메서드에는

@Transactional
public void updatePost(...) {
    ...
}

반대로 조회 전용이라면

@Transactional(readOnly = true)
public PostResponse getPost(...) {
    ...
}

를 고려한다 Hibernate 공식문서도 read-only mode에서는 dirty-check가 필요 없다고 말한다

It’s not necessary to dirty-check an entity instance in read-only mode.

read-only mode의 엔티티 인스턴스는 dirty-check할 필요가 없다

영속성 컨텍스트와 지연 로딩

Hibernate Javadoc

When an associated entity has not yet been fetched from the database, references to the unfetched entity are represented by uninitialized proxies.

연관 엔티티가 아직 DB에서 fetch되지 않았으면, 가져오지 않은 엔티티 참조는 초기화되지 않은 proxy로 표현된다

The state of an unfetched entity is automatically fetched from the database when a method of its proxy is invoked, if and only if the proxy is associated with an open session.

가져오지 않은 엔티티의 상태는 proxy 메서드가 호출될 때 자동으로 DB에서 fetch되는데, 단 proxy가 열린 session과 연결되어 있을 때만 가능하다

@ManyToOne(fetch = LAZY) 같은 지연 로딩 관계는 처음에 프록시 객체로 채워져 있어서 실제 데이터는 그 필드에 접근하는 순간 DB에서 가져온다

@Transactional
public void getComment(Long id) {
    Comment comment = commentRepository.findById(id).orElseThrow();
    // comment.user는 지금 proxy 객체 (실제 데이터 아직 없음)
    
    String nickname = comment.getUser().getNickname();
    // ↑ getNickname() 호출하는 순간 영속성 컨텍스트를 통해 DB SELECT 실행
}

트랜잭션 끝난 뒤에 지연 로딩 시도하면

Comment comment = commentService.getComment(id); // 트랜잭션 끝남, detached

comment.getUser().getNickname(); //  LazyInitializationException

이때 proxy가 열려 있는 영속성 컨텍스트와 연결되어 있지 않으면 LazyInitializationException이 날 수 있다

LazyInitializationException: could not initialize proxy - no Session
프록시를 초기화할 수 없음 - Session(영속성 컨텍스트)이 없음

이게 N+1 이슈로도 이어지는 문제

https://winwin0219.tistory.com/314

[JPA]N+1 이슈

Fetching은 성능에 직접적인 영향을 준다https://docs.hibernate.org/orm/5.2/userguide/html_single/chapters/fetching/Fetching.html FetchingFetching, essentially, is the process of grabbing data from the database and making it available to the appl

winwin0219.tistory.com

영속성 컨텍스트가 너무 커지면 문제다

영속성 컨텍스트는 관리하는 엔티티를 계속 참조한다

Hibernate Javadoc

A persistence context holds hard references to all its entities and prevents them from being garbage collected.

영속성 컨텍스트는 모든 엔티티에 대한 hard reference를 가지고 있어 GC 대상이 되지 않게 한다

Therefore, a Session is a short-lived object, and must be discarded as soon as a logical transaction ends.

따라서 Session은 짧게 살아야 하는 객체이며, 논리 트랜잭션이 끝나면 버려져야 한다

운영관점에서 중요하다 예를들어 10만 건을 한 트랜잭션에서 전부 조회/수정하면

@Transactional
public void updateAll() {
    List<Post> posts = postRepository.findAll(); // 10만 건 조회
    for (Post post : posts) {
        post.changeSomething();
    }
} // flush 시 10만 건 dirty check + UPDATE

영속성 컨텍스트가 10만 개 엔티티를 붙잡는다

문제

메모리에 10만 개 엔티티 올라옴 (OutOfMemory 위험)
flush 때 10만 개 다 dirty check
트랜잭션이 길어짐 → DB lock 오래 잡음
롤백 발생 시 비용 큼

Hibernate 문서도 flushing은 비용이 있을 수 있다고 말한다

Since flushing is a somewhat expensive operation (the session must dirty-check every entity in the persistence context)…

flush는 다소 비싼 작업인데, session이 영속성 컨텍스트의 모든 엔티티를 dirty-check해야 하기 때문이다

그래서 대량 처리에서는 보통 batch 단위로 끊고 아래처럼 고려한다

해결

// 배치 단위로 처리
for (batch in batches) {
    processBatch(batch);
    entityManager.flush();
    entityManager.clear(); // 영속성 컨텍스트 비워서 메모리 해방
}

트랜잭션 안에서 조회한 값은 DB 최신값이 아닐 수도 있다

영속성 컨텍스트는 같은 id를 한 번 관리하기 시작하면, 다시 조회해도 그 객체를 반환한다

Post post1 = entityManager.find(Post.class, 1L);
// → DB에서 title = "원래 제목"을 가져옴 → 1차 캐시에 저장

// [다른 트랜잭션에서 title을 "바뀐 제목"으로 UPDATE + commit]

Post post2 = entityManager.find(Post.class, 1L);
// → 1차 캐시에 이미 Post#1 있음 → DB 안 가고 post1 반환
// post2.getTitle() 여전히 "원래 제목" ← 최신값 아님

최신 DB 값을 다시 읽으려면

entityManager.refresh(post1); // DB에서 강제 재조회

영속성 컨텍스트와 DB 트랜잭션 격리 수준은 다른 개념이다

트랜잭션 격리수준은 다음에 다뤄질 내용이라서 짧게만 말해보겠다

개념	담당
영속성 컨텍스트	Java 애플리케이션 메모리 안에서 엔티티 객체 관리
DB 트랜잭션	DB 변경의 원자성, 격리성, commit/rollback 관리
DB isolation level	다른 트랜잭션의 변경을 어느 수준까지 볼지 결정

영속성 컨텍스트는 애플리케이션 레벨의 객체 관리 공간이며 DB 트랜잭션은 DB 레벨의 작업 단위다

하지만 둘은 같이 움직인다

@Transactional 시작 → EntityManager/영속성 컨텍스트 연결 → 엔티티 조회/수정 → flush → DB transaction commit → 영속성 컨텍스트 종료 → 엔티티 detached

[Devlog] 댓글 목록 조회에서 숨은 추가 쿼리를 제거하기

HS0601 — Wed, 6 May 2026 15:52:07 +0900

댓글 목록 조회를 구현하면서 처음에는 댓글과 작성자 nickname을 응답하면 된다고만 생각했다

하지만 목록 조회 API에서는 단순히 값이 나오느냐보다, 요청 한 번에 DB 쿼리가 몇 번 실행되는지도 중요하다 댓글 수가 늘어날수록 작성자 조회 쿼리도 함께 늘어난다면, API 응답 시간과 DB 부하를 예측하기 어려워진다

이번 글은 댓글 목록 조회에서 작성자 nickname을 가져오는 흐름을 점검하고, user를 fetch join하여 해당 조회 경로의 쿼리 수를 예측 가능하게 만든 기록이다

https://winwin0219.tistory.com/314

[JPA]N+1 이슈

winwin0219.tistory.com

앞선 JPA N+1 정리 글에서 확인한 것처럼, 목록 조회 후 DTO 변환 과정에서 LAZY 연관관계에 반복 접근하면 N+1 가능성이 생길 수 있다

CoreBoard 댓글 목록 응답에는 작성자 nickname이 항상 필요하다 기존 구조에서는 Comment 목록을 조회한 뒤 GetAllCommentResponse로 변환하는 과정에서 comment.getUser().getNickname()에 접근했다

Comment.user는 LAZY 연관관계이기 때문에, user가 함께 로딩되지 않은 상태라면 댓글 수만큼 작성자 조회가 추가로 발생할 수 있다 문제는 nickname이 필요한 것 자체가 아니라, 목록 조회에서 항상 필요한 작성자 정보를 조회 시점에 함께 가져오지 않고 DTO 변환 시점까지 미뤄둔 구조였다

그래서 댓글 목록 조회에서는 user를 fetch join하여 Comment와 작성자 정보를 함께 로딩하도록 변경했다

@Query("""
    select c
    from Comment c
    join fetch c.user
    where c.post.id = :postId
    and c.status = :status
    """)
Slice<Comment> findByPostIdAndStatusWithUser(
        @Param("postId") Long postId,
        @Param("status") CommentStatus status,
        Pageable pageable
);

이 변경으로 해당 조회 경로에서는 comment.getUser().getNickname() 접근이 추가 user 조회로 이어지지 않는다

댓글 목록 조회에서 작성자 nickname 접근으로 발생할 수 있는 N+1 가능성을 제거한 것이다

DTO projection도 고려할 수 있었다 필요한 필드가 commentId, content, nickname, createdDate처럼 명확한 읽기 전용 조회이기 때문에 projection이 더 좁은 최적화가 될 수 있다

다만 JPQL constructor expression은 DTO의 전체 패키지 경로가 쿼리에 들어가 가독성과 유지보수성이 떨어진다고 판단했다

DTO projection = 필요한 필드만 DTO 형태로 조회하는 방식

그 구현 방법 중 하나 = JPQL constructor expression

DTO projection
├─ JPQL constructor expression
│  └─ select new com.example.CommentResponse(...)
├─ interface projection
│  └─ select c.id as commentId, u.nickname as nickname ...
└─ QueryDSL projection
   └─ Projections.constructor(...) / @QueryProjection 등

현재 단계에서는 필요한 연관 엔티티가 Comment.user 하나이고 ManyToOne 관계이므로, fetch join으로 문제를 해결하는 것이 더 단순하고 설명 가능하다고 봤다

후보	장점	단점	판단
기존 LAZY 유지	코드 변경이 거의 없음	DTO 변환 중 user.nickname 접근으로 N+1 가능성 있음	x
fetch join	기존 DTO 변환 구조 유지 가능, 해당 조회 경로의 추가 user 조회 방지	필요한 컬럼만 조회하는 방식은 아님	선택
DTO projection	필요한 필드만 조회 가능	조회 모델이 응답 DTO/쿼리에 강하게 묶일 수 있음 (repository 쿼리가 dto의 생성자를 알고있음)	x

DTO projection은 필요한 필드만 조회할 수 있어 더 좁은 최적화가 될 수 있다

하지만 JPQL constructor expression 방식으로 구현하면 Repository 쿼리가 응답 DTO의 생성자 구조를 직접 알게 된다

응답 DTO의 필드 추가나 타입 변경이 Repository 쿼리 변경으로 이어질 수 있어, 이번 단계에서는 기존 DTO 변환 구조를 유지하면서 N+1 가능성을 제거할 수 있는 fetch join을 선택했다

정리하면 현재 선택은 다음과 같다

지금 댓글 목록 조회: fetch join
트래픽 증가 또는 조회 필드 최소화 필요: interface projection 또는 QueryDSL 고려

이번 변경의 핵심은 단순히 fetch join을 적용했다는 것이 아니다

댓글 목록 응답에 필요한 데이터가 무엇인지 먼저 확인하고, 그 데이터가 DTO 변환 시점에 뒤늦게 조회되지 않도록 조회 경로를 명확히 만든 것이다

이를 통해 댓글 목록 조회에서 작성자 nickname 접근으로 발생할 수 있는 추가 쿼리를 제거하고, API 요청당 쿼리 수를 더 예측 가능하게 만들었다

[JPA]N+1 이슈

HS0601 — Wed, 6 May 2026 15:30:48 +0900

Fetching은 성능에 직접적인 영향을 준다

공식문서는 이렇게 말한다

Fetching, essentially, is the process of grabbing data from the database and making it available to the application.

fetching은 DB에서 데이터를 가져와 애플리케이션이 사용할 수 있게 만드는 과정이다 즉, JPA에서 객체를 다룬다고 해도 결국 내부에서는 어떤 데이터를 언제 DB에서 가져올지 결정해야 한다

Tuning how an application does fetching is one of the biggest factors in determining how an application will perform.

애플리케이션이 데이터를 어떻게 가져오도록 설계하느냐가 성능을 결정하는 큰 요소 중 하나라는 뜻이다 N+1 이슈도 결국 필요한 데이터를 언제, 몇 번의 쿼리로 가져올 것인가의 문제다

N+1이라는 이름은 어디서 왔는가

N+1은 공식 스펙에서 정해진 에러 이름이라기 보단, ORM을 사용할 때 자주 발생하는 조회 패턴을 설명하는 말이다

N+1 = 1번의 목록 조회 쿼리 + 목록 안의 N개의 데이터를 각각에 대해 추가 조회하는 쿼리

예를 들어, 댓글 10개를 조회했는데, 각 댓글의 작성자 정보를 가져오느라 user 조회가 10번 더 나가면 다음과 같은 구조가 된다

댓글 목록 조회 1번 + 댓글 작성자 조회 10번 = 총 11번 쿼리

그래서 이름이 N+1인 것이다. (여기서 N은 목록에서 조회된 데이터 개수)

어떤 코드가 문제의 발단이 되는가?

댓글 목록 API를 만든다고 가정해보자, 댓글 목록 응답에는 댓글 내용뿐 아니라 작성자 nickname도 필요하다

응답 DTO는 이런 형태일 수 있다

public record GetAllCommentResponse(
        Long commentId,
        String content,
        String nickname,
        LocalDateTime createdDate
) {
    public static GetAllCommentResponse from(Comment comment) {
        return new GetAllCommentResponse(
                comment.getId(),
                comment.getContent(),
                comment.getUser().getNickname(),
                comment.getCreatedDate()
        );
    }
}

처음 보면 이 코드는 자연스럽다

comment.getUser().getNickname()

하지만, 여기서 중요한 점이 있다 Comment 엔티티의 user가 보통 이런 식으로 매핑되어있다.

@ManyToOne(fetch = FetchType.LAZY)
private Users user;

LAZY는 연관 객체를 처음부터 무조건 가져오지 않고 실제로 접근할 때마다 가져오겠다는 전략이다

we recommend that you use lazy fetching

대부분의 연관관계를 처음부터 무조건 가져오기보단, 기본적으로는 필요할 때 가져오는 lazy fetching을 쓰라는 뜻이다

특히 @ManyToOne(fetch = FetchType.LAZY)같은 방식을 예시로 들고 있다.

즉, LAZY 자체가 문제가 아니다 오히려 불필요한 조인을 줄이기 위한 정상적인 전략이다

문제는 목록 조회에서 nickname이 항상 필요한데도, user 조회를 DTO 변환 시점까지 미뤄둔 구조다

Hibernate의 기본 lazy fetching

공식문서에서 lazy association에 대해 이렇게 설명한다

By default, Hibernate uses lazy select fetching for collections and lazy proxy fetching for single-valued associations.

Hibernate는 기본적으로 컬렉션 연관관계에는 lazy fetching을, 단일 연관관계에는 lazy proxy fetching을 사용한다

즉, 연관된 객체를 처음부터 무조건 가져오기 보단, 필요한 시점에 가져오는 방식을 기본적으로 사용한다는 뜻이다

그리고 바로 뒤에 batch fetching이라는 최적화도 언급하고 있다

If you set hibernate.default_batch_fetch_size, Hibernate will use the batch fetch optimization for lazy fetching.

lazy fetching을 사용할 때도 default_batch_fetch_size를 설정하면 Hibernate가 여러 lazy 조회를 묶어서 가져오는 batch fetch 최적화를 사용할 수 있다는 의미다

즉, lazy자체가 나쁜 것은 아니지만, lazy로 인한 추가 조회를 어떻게 제어할지가 중요하다

왜 LAZY가 문제로 이어질 수 있는가

LAZY는 나쁜 전략이 아니다 오히려 대부분의 상황에서 합리적이다

모든 API가 항상 연관객체를 필요로 하는 것은 아니다 어떤 화면에서는 댓글 내용만 필요하고 작성자 정보는 필요없을 수 있다 이때 매번 작성자까지 가져오면 불필요한 조회가 된다

문제는 목록 API처럼 연관 데이터가 항상 필요한 상황이다

댓글 목록 응답에 nickname이 항상 필요하다.
그런데 조회 쿼리는 Comment만 가져온다.
이후 DTO 변환에서 User에 접근한다.
그러면 User 조회가 댓글 개수만큼 추가될 수 있다.

개선 전 흐름은 다음과 같다

1. 댓글 목록 조회

select * from comments where post_id = ?

2. DTO 변환 중 작성자 접근

  comment.getUser().getNickname()

3. 작성자 추가 조회

   select * from users where id = ?
   select * from users where id = ?
   select * from users where id = ?
   ...

여기서 핵심은 user_id를 알고 있다는 것과 user.nickname()을 이미 가졎왔다는 것이 다르다는 점이다

comments.user_id를 조회했다 ≠ users.nickname을 조회했다

운영 관점에서 왜 문제가 되는가

N+1이 무서운 이유는 쿼리가 조금 더 나간다가 아니다 API 요청 하나가 DB에 몇 번 접근하는지 예측 가능해야 하는데

댓글 50개 → 댓글 목록 조회 1번 + 작성자 조회 최대 50번 = 총 51번

즉, 데이터 개수가 늘어날수록 DB쿼리 수가 같이 늘어난다

이문제는 다음으로 이어질 수 있다

DB 부하 증가
API 응답 시간 증가
커넥션 사용량 증가
트래픽 증가 시 병목 발생
장애 상황에서 원인 파악 어려움

특히 목록 API는 자주 호출될 수 있다

게시글 상세 페이지에 들어갈 때마다 댓글 목록을 불러온다면 댓글 조회 API는 생각보다 자주 실행된다

그래서 N+1은 나중에 성능 좀 안 좋을 수 있음정도가 아니라 API 요청당 DB 접근 횟수를 예측하기 어렵게 만드는 문제다

해결 방향 1: fetch join

가장 먼저 고려할 수 있는 해결책은 fetch join이다

@Query("""
    select c
    from Comment c
    join fetch c.user
    where c.post.id = :postId
""")
List<Comment> findByPostIdWithUser(Long postId);

이 쿼리는 comment를 조회하면서 User도 함께 가져오라고 명시한다

즉, 기존에는 댓글 조회 1번당 작성자 조회1번이었다면 fetch join을 사용하여 댓글 + 작성자 join 조회 1번이 된다

Vlad Mihalcea 글에서도 엔티티 쿼리에서 N+1을 피하는 방법으로 JOIN FETCH를 언급한다

참고로 Vlad Mihalcea는 Hibernate/JPA 성능 쪽에서 유명한 분이다

But, if you want to use post association, then you can use JOIN FETCH to avoid the N+1 query problem

연관 객체가 필요한 조회라면 JOIN FETCH를 사용하여 N+1 문제를 피할 수 있다는 의미

다만, fetch join은 필요한 컬럼만 가져오는 방식은 아니다 엔티티와 연관 데이터를 함께 로딩하는 방식이다

fetch join → Comment 엔티티 + User 엔티티를 함께 조회

따라서 쿼리 수를 줄이는 해결에는 적합하지만, 조회 컬럼을 최소화하는 해결책은 아니다

해결 방향 2: DTO Projection

조회 API에서 필요한 필드가 명확하다면 DTO Projection도 많이 사용한다

예를들어 응답에 필요한 값이 아래 뿐이라면,

commentId
content
nickname
createdDate

엔티티 전체를 가져오지 않고 필요한 값만 조회할 수 있다

Spring Data JPA 공식문서는 projection을 이렇게 설명한다

Spring Data allows modeling dedicated return types, to more selectively retrieve partial views of the managed aggregates.

Spring Data는 관리되는 엔티티 전체가 아니라 특정 속성만 선택적으로 조회하기 위한 반환 타입을 모델링할 수 있게 해준다는 의미

즉, 목록 조회처럼 필요한 필드가 정해진 경우 projection을 사용할 수 있다

@Query("""
    select new com.example.CommentResponse(
        c.id,
        c.content,
        u.nickname,
        c.createdDate
    )
    from Comment c
    join c.user u
    where c.post.id = :postId
""")
List<CommentResponse> findCommentResponses(Long postId);

단점도 있다

JPQL constructor expression을 쓰면 DTO의 전체 패키지 경로를 쿼리에 넣어야 해서 코드가 지저분할 수 있다 그래서 실무에서는 interface projection을 쓰거나 QueryDSL같은 도구를 쓰는 경우도 있다

해결 방향 3: EntityGraph

spring Data JPA에서는 @EntityGraph도 사용할 수 있다 Spring Data JPA API문서는 @EntityGraph를 이렇게 설명하고 있다

EntityGraph (Spring Data JPA Parent 4.0.5 API)

The name of the EntityGraph to use.

docs.spring.io

Annotation to configure the JPA 2.1 EntityGraphs that should be used on repository methods.

Repository 메서드에서 사용할 JPA EntityGraph를 설정하는 애노테이션이라는 뜻인데, 쿼리 메서드에 어떤 연관관계를 함께 가져올지 지정할 수 있다는 말이다

@EntityGraph(attributePaths = "user")
List<Comment> findByPostId(Long postId);

Spring Data JPA 문서는 dynamic EntityGraph도 언급한다

Since 1.9 we support the definition of dynamic EntityGraphs by allowing to customize the fetch-graph via attributePaths() ad-hoc fetch-graph configuration.

Spring Data JPA 1.9부터는 attributePaths()를 이용해서, 미리 이름 붙인 EntityGraph를 만들지 않아도 Repository 메서드에서 바로 가져올 연관 필드를 지정할 수 있다는 뜻

EntityGraph는 fetch join보다 Repository 메서드 선언이 깔끔할 수 있다. 다만 복잡한 조건, 정렬, 페이징, 여러 연관관계가 얽히면 JPQL fetch join이나 projection이 더 명확할 때도 있다

EntityGraph란?

fetch join이랑 목적이 비슷하다, 이번 조회에서는 Comment만 가져오지 말고 Comment.user도 같이 가져와

근데 fetch join은 아래처럼 쓰는데

@Query("""
    select c
    from Comment c
    join fetch c.user
    where c.post.id = :postId
""")
Slice<Comment> findByPostIdAndStatusWithUser(...);

EntityGraph는 쿼리문에 join fetch를 직접 안 쓰고 메서드 위에 이렇게 붙임

@EntityGraph(attributePaths = "user")
Slice<Comment> findByPostIdAndStatus(Long postId, CommentStatus status, Pageable pageable);

차이점
fetch join → JPQL 안에 join fetch를 직접 적음
EntityGraph → Repository 메서드 위에 @EntityGraph(attributePaths = "...")로 적음

다만 복잡한 조건이나 정렬, 직접 작성한 JPQL과 함께 조회 의도를 명확히 드러내고 싶다면 fetch join을 사용하는 편이 더 직관적일 수 있다

해결 방향 4: Batch Fetching

Batch fetching은 N개의 추가조회를 1개씩 날리는 대신, 묶어서 가져오는 방식이다

If you set hibernate.default_batch_fetch_size, Hibernate will use the batch fetch optimization for lazy fetching.

hibernate.default_batch_fetch_size를 설정하면 Hibernate가 lazy 로딩 대상들을 묶어서 조회하는 최적화를 사용할 수 있다는 뜻

예를 들어, 댓글 100개의 작성자를 하나씩 조회하는 대신, 여러 id를 IN조건으로 묶어서 조회할 수 있다

select *
from users
where id in (?, ?, ?, ?, ...)

Batch fetching은 전역으로 lazy 조회 비용을 완화할 수 있다는 장점이 있다

하지만 특정 목록 API에서 반드시 필요한 연관 데이터를 명확히 가져오는 방식은 아니다

fetch join → 이 조회에서 필요한 연관 데이터를 처음부터 함께 가져온다
batch fetching → lazy 조회가 발생하더라도 여러 건을 묶어서 가져오도록 완화한다

보편적으로 어떻게 다루는가

N+1 해결은 하나의 정답으로 고정되지 않는다 보통 다음과 같은 기준으로 선택한다

1. 목록 조회에서 연관 데이터가 항상 필요하다

이 경우 fetch join, EntityGraph, projection 중 하나를 고려한다

예: 댓글 목록에 작성자 nickname이 항상 필요하다.

이때는 조회 시점에 작성자 정보를 함께 가져오는 것이 자연스럽다

2. 필요한 필드가 명확한 읽기 전용 API다

이 경우 DTO projection이 좋은 선택이 될 수 있다

예: 목록 응답에 id, title, nickname, createdDate만 필요하다.

엔티티 전체를 가져오는 것보다 필요한 컬럼만 조회할 수 있기 때문이다.

3. 도메인 로직을 수행해야 한다

이 경우 엔티티 조회가 자연스럽다

예: 댓글 수정, 삭제, 권한 검증, 상태 변경

이런 작업은 응답용 필드만 필요한 것이 아니라 엔티티의 상태와 행위가 필요하다. 따라서 projection보다 엔티티를 조회하고 필요한 연관관계를 명시적으로 가져오는 방식이 더 적절할 수 있다.

4. 여러 API에서 비슷한 lazy 조회가 반복된다

이 경우 batch fetching도 고려할 수 있다

예: 여러 곳에서 User, Category 같은 단일 연관 객체를 자주 참조한다.

공식문서 기반으로 정리하면 다음과 같다

1. 기본 연관관계는 불필요한 로딩을 피하기 위해 LAZY로 두는 것이 일반적이다
2. 특정 조회에서 연관 데이터가 필요하다면 fetch join이나 EntityGraph로 가져올 대상을 명시한다
3. 읽기 전용 목록 API에서는 projection으로 필요한 필드만 조회할 수 있다
4. 반복적인 lazy 조회는 batch fetching으로 완화할 수 있다

문제는 목록 조회에서 발생한다

목록을 조회한다
각 항목을 DTO로 변환한다
DTO 변환 중 LAZY 연관관계에 접근한다
그 결과 항목 개수만큼 추가 조회가 발생할 수 있다.

N+1의 본질은 이것

필요한 데이터가 무엇인지 이미 알고 있었는데, 조회 시점에 함께 가져오지 않고, 사용 시점에 하나씩 가져오게 둔 것

해결도 fetch join을 쓰자가 아니라, 조회 목적에 따라 달라진다

연관 엔티티 자체가 필요하다
→ fetch join 또는 EntityGraph
응답 필드만 필요하다
→ DTO/interface projection
여러 lazy 조회를 전역적으로 완화하고 싶다
→ batch fetching
도메인 상태 변경이 필요하다
→ 엔티티 조회 유지

보충 : 컬렉션 연관관계(OneToMany, ManyToMany) fetch join

Hibernate 공식문서에는

When limits or pagination are combined with a fetch join, Hibernate must retrieve all matching results from the database and apply the limit in memory!

limit이나 pagination이 fetch join과 함께 사용되면, Hibernate가 DB에서 조건에 맞는 결과를 모두 가져온 뒤 메모리에서 limit을 적용해야 할 수 있다는 뜻이다 즉 DB에서 limit 10으로 딱 10개만 가져오는 게 아니라, 애플리케이션 메모리에서 잘라낼 수 있다

Care should be taken when fetch joining a collection-valued association…

컬렉션 값을 가지는 연관관계, 예를 들면 @OneToMany, @ManyToMany를 fetch join 할 때 조심해야 한다는 뜻

This almost certainly isn’t the behavior you were hoping for, and in general will exhibit terrible performance characteristics.

대부분 개발자가 기대한 동작이 아니고, 일반적으로 매우 나쁜 성능 특성을 보일 수 있다

이 부분 때문에 fetch join + pagination 조심해라는 말이 나오는 것이다

OneToMany + 페이징이 필요하다면? → Batch Fetching 또는 쿼리 분리 방식

[Docker] WSL Integration 중단으로 테스트가 불안정했던 문제

HS0601 — Wed, 6 May 2026 12:33:28 +0900

Docker Desktop에서 다음과 같은 메시지가 나타났다.

이후 Docker가 켜져 있는 것처럼 보이는데도, Docker가 필요한 테스트가 실패하거나 컨테이너 실행/접속이 불안정해졌다.
이전에도 종종 같은 문제가 있었고, 매번 명령어를 다시 찾는 게 번거로워 트러블슈팅 기록으로 남긴다.

원인

https://www.docker.com/

Docker: Accelerated Container Application Development

Docker is a platform designed to help developers build, share, and run container applications. We handle the tedious setup, so you can focus on the code.

www.docker.com

With Docker Desktop running on WSL 2, users can leverage Linux workspaces...

즉 Docker Desktop은 WSL 2 환경과 연결되어 동작할 수 있다. :contentReference[oaicite:0]{index=0}

이번 문제는 Docker Desktop과 `Ubuntu-22.04` WSL 배포판 사이의 integration 프로세스가 비정상적으로 중단된 상황으로 보인다.

이 상태에서는 Docker Desktop UI는 떠 있어도 실제로는 다음 문제가 생길 수 있다.

- Docker 명령 실행 불안정
- 컨테이너 생성/접속 실패
- Testcontainers 기반 테스트 실패
- 전체 테스트가 환경 상태에 따라 성공/실패를 반복하는 것처럼 보임

해결 : Docker가 의존하는 WSL 실행 환경을 통째로 리셋

wsl --shutdown

https://learn.microsoft.com/en-us/windows/wsl/basic-commands

Basic commands for WSL

Reference for the basic commands included with Windows Subsystem for Linux (WSL).

learn.microsoft.com

Immediately terminates all running distributions and the WSL 2 lightweight utility virtual machine.

즉 실행 중인 WSL 환경을 통째로 종료하는 명령이다.

이번 문제에서는 wsl --shutdown으로 Docker Desktop이 의존하는 WSL 실행 환경을 종료한 뒤 Docker Desktop을 다시 실행했다.
그 결과 WSL/Docker 연결이 재초기화되어 Docker가 필요한 테스트도 정상 실행됐다.

정리

이번 문제는 애플리케이션 코드 문제가 아니라 개발 환경 의존성 문제였다.

Docker Desktop의 WSL integration이 중단되면 Docker가 필요한 테스트가 랜덤하게 실패하는 것처럼 보일 수 있다.
이 경우 wsl --shutdown으로 WSL 실행 환경을 종료한 뒤 Docker Desktop을 다시 실행하면, WSL/Docker 연결이 재초기화되어 문제가 해결될 수 있다.

[Java] Java는 컴파일 언어일까, 인터프리터 언어일까?

HS0601 — Tue, 5 May 2026 22:32:54 +0900

처음에는 단순히 자바는 컴파일언어고 자바스크립트는 인터프리터언어라고만 외웠다

구글링

결론부터 말하면, Java는 보통 컴파일 언어로 분류된다 하지만 Java는 C처럼 소스코드를 바로 운영체제와 CPU가 실행할 수 있는 실행 파일로 만드는 방식은 아니다

Java는 .java 소스코드를 javac가 .class 바이트코드로 컴파일하고, JVM이 그 바이트코드를 읽어 실행한다 그리고 JVM은 바이트코드를 단순히 한 줄씩 해석만 하는 것이 아니라, 처음에는 인터프리터로 실행하다가 자주 실행되는 코드는 JIT 컴파일러를 통해 기계어로 바꿔 더 빠르게 실행한다 즉 Java는 이렇게 정리할 수 있다

Java 소스코드 .java
  ↓ javac
바이트코드 .class
  ↓ JVM
인터프리터 실행 또는 JIT 컴파일
  ↓
기계어 실행

즉 자바는 소스코드를 바이트코드로 컴파일하고 JVM이 그 바이트코드를 인터프리터와 JIT 컴파일러를 사용해 실행하는 언어

컴파일이란?

컴파일은 사람이 작성한 소스코드를 다른 실행 환경이 이해할 수 있는 형태로 미리 변환하는 과정이다 C/C++에서는 보통 운영체제와 CPU가 직접 실행할 수 있는 실행 파일을 만든다

반면 Java에서는 JVM이 실행할 수 있는 .class 바이트코드 파일을 만든다.

GCC 공식문서는 컴파일 과정을 이렇게 설명하고 있다

Compilation can involve up to four stages: preprocessing, compilation proper, assembly and linking

한국어로 풀면, 컴파일은 전처리, 좁은 의미의 컴파일, 어셈블리, 링킹 같은 여러 단계를 포함할 수 있다는 뜻이다

C 언어를 예로 들면 이런 흐름이다
소스코드
  ↓
전처리
  ↓
컴파일
  ↓
어셈블리
  ↓
오브젝트 파일
  ↓
링킹
  ↓
실행 파일

예를 들어 C에서는 이런 코드를 작성한다.

#include <stdio.h>

int main() {
    printf("hello");
    return 0;
}

이 코드는 바로 실행되는 것이 아니라, 컴파일러가 먼저 처리해서 실행 파일을 만든다

gcc main.c -o app
./app

여기서 중요한 점은 C/C++은 보통 최종적으로 운영체제와 CPU가 직접 실행할 수 있는 실행 파일을 만든다

하지만 Java는 다르다 Java의 javac 컴파일은 최종 실행 파일을 만드는 과정이 아니라, JVM이 실행할 수 있는 .class 바이트코드 파일을 만드는 과정이다

컴파일 언어란?

컴파일 언어는 보통 실행 전에 소스코드를 다른 형태로 변환하는 과정이 중심인 언어를 말한다 컴파일 언어의 특징은 대략 이렇다

실행 전에 번역 과정을 거친다.
컴파일 결과물이 만들어진다.
문법 오류나 타입 오류를 실행 전에 많이 잡을 수 있다.
실행 시점에는 이미 변환된 결과물을 사용한다.

다만 여기서 조심해야 한다 컴파일 결과물이 항상 운영체제와 CPU가 직접 실행하는 실행 파일인 것은 아니다

C/C++은 보통 네이티브 실행 파일을 만들지만, Java는 JVM이 실행하는 바이트코드 파일을 만든다

즉 Java도 컴파일을 한다 하지만 그 결과물이 C의 실행 파일과는 다르다

인터프리터란?

인터프리터는 실행 시점에 코드를 읽고 해석하면서 실행하는 프로그램이다

컴파일 언어가 실행 전에 변환 결과물을 만들어두는 방식에 가깝다면, 인터프리터 방식은 런타임이 프로그램을 읽고 해석하며 실행하는 방식에 가깝다

예를 들어 JavaScript는 보통 브라우저나 Node.js 같은 실행 환경에서 실행된다

<script src="app.js"></script>

여기서 app.js를 운영체제나 CPU가 직접 실행하는 것은 아니다 브라우저 안의 JavaScript 엔진이 JavaScript 코드를 읽고 실행한다 그래서 JavaScript는 전통적으로 인터프리터 언어로 설명되는 경우가 많다 다만 현대 JavaScript 엔진은 단순히 인터프리터만 사용하는 것이 아니라, 성능을 높이기 위해 JIT 컴파일러도 함께 사용한다

MDN 공식문서는 JavaScript를 이렇게 설명한다

JavaScript (JS) is a lightweight interpreted (or just-in-time compiled) programming language

한국어로 풀면, JavaScript는 가벼운 인터프리터 또는 JIT 컴파일 언어라는 뜻이다

즉 요즘 언어와 런타임은 단순하게 컴파일만 한다, 인터프리터만 쓴다로 나뉘지 않는 경우가 많다

컴파일 언어와 인터프리터 언어의 가장 큰 차이

컴파일 언어

→ 실행 전에 소스코드를 다른 형태로 변환한다
→ 문법 오류나 타입 오류를 실행 전에 많이 잡을 수 있다
→ 실행 시점에는 변환된 결과물을 사용한다

인터프리터 언어

→ 런타임이 코드를 읽고 해석하며 실행하는 방식이 중심이다
→ 별도의 실행 파일을 미리 만들지 않고 바로 실행하는 경우가 많다
→ 특정 코드 경로의 문제는 실행 중에 드러나는 경우가 많다

여기서 에러가 언제 나느냐도 중요한 차이다

컴파일 언어에서는 문법이 틀리거나 타입이 맞지 않으면 실행 전에 컴파일 단계에서 막히는 경우가 많다

예를 들어 Java에서 이런 코드는 컴파일되지 않는다

int age = "스무살";

int에는 숫자가 들어가야 하는데 문자열을 넣었기 때문이다 이런 경우 .class 파일이 제대로 만들어지지 않으므로 실행 자체가 되지 않는다 반면 실행 중에 드러나는 문제도 있다

int result = 10 / 0;

이 코드는 문법 자체는 맞다 그래서 컴파일은 될 수 있다 하지만 실제 실행 중 이 코드에 도달하면 예외가 발생한다

즉 Java에서도 에러는 두 종류로 나눠 생각해야 한다

컴파일 에러
→ 실행 전에 잡힘
→ 문법 오류, 타입 오류 등

런타임 예외
→ 실행 중에 발생
→ 0으로 나누기, null 접근, 배열 범위 초과 등

그래서 컴파일 언어는 실행 전에만 에러가 나고, 인터프리터 언어는 실행 중에만 에러가 난다라고 단정하면 안 된다

더 정확히는 이렇게 말해야 한다

컴파일 언어는 실행 전에 많은 오류를 잡을 수 있다.
하지만 컴파일이 성공해도 실행 중 예외는 발생할 수 있다.

Java는 컴파일 언어냐 인터프리터 언어냐?

Java는 보통 컴파일 언어로 분류한다 Oracle javac 공식문서는 이렇게 설명한다

The javac command reads class and interface definitions, written in the Java programming language, and compiles them into bytecode class files

한국어로 풀면, javac 명령은 Java 언어로 작성된 클래스와 인터페이스 정의를 읽고, 그것을 바이트코드 class 파일로 컴파일한다는 뜻이다

즉 Java는 컴파일을 한다

Hello.java
  ↓ javac
Hello.class

하지만 여기서 중요한 점이 있다 .class 파일은 CPU가 직접 실행하는 일반적인 실행 파일이 아니다 .class 파일은 JVM이 읽고 실행하는 바이트코드 파일이다

JVM 공식 스펙은 class 파일에 대해 이렇게 설명한다

Each class file contains the definition of a single class or interface.

한국어로 풀면, 각 class 파일은 하나의 클래스나 인터페이스 정의를 담고 있다는 뜻이다

즉 Java의 실행 흐름은 이렇다

Java 소스코드 .java
  ↓ javac
바이트코드 .class
  ↓ JVM
인터프리터 실행
  ↓
자주 실행되는 코드는 JIT 컴파일
  ↓
기계어 실행

그래서 Java는 소스코드를 바로 실행하는 언어가 아니다 실행 전에 .java 파일을 .class 파일로 컴파일한다 다만 Java의 컴파일 결과물은 CPU가 바로 실행하는 실행 파일이 아니라, JVM이 실행할 바이트코드다 그래서 Java는 컴파일 언어로 분류되지만, 실행 단계에서는 JVM의 인터프리터와 JIT 컴파일러가 함께 관여한다

정리하면 이렇다

Java = 컴파일 언어로 분류
이유 = .java 파일을 javac가 .class 바이트코드로 컴파일하기 때문

하지만 실제 실행 = JVM이 .class 바이트코드를 읽고 실행
추가로 JVM은 인터프리터와 JIT 컴파일러를 함께 사용

JVM이 왜 필요한가?

C 같은 언어는 보통 특정 운영체제와 CPU에 맞는 실행 파일을 만든다 그런데 Java는 .class 바이트코드를 만들고, 각 환경에 설치된 JVM이 그 바이트코드를 실행한다

같은 Hello.class
  ↓
Windows JVM
Linux JVM
macOS JVM

운영체제마다 JVM은 다르지만, JVM이 같은 바이트코드를 실행해준다 그래서 Java는 특정 OS/CPU용 실행 파일을 직접 만드는 방식과 다르다 물론 실제 운영에서는 JVM 버전, 라이브러리 버전, OS 환경 차이 때문에 완전히 마법처럼 어디서나 똑같이 동작한다고 보면 안 된다 그래도 C/C++처럼 OS별 네이티브 실행 파일을 직접 따로 만드는 방식과는 다르다

JIT는 무엇인가?

JIT는 Just-In-Time Compilation의 약자다 뜻은 실행 중 필요한 시점에 컴파일한다는 의미다 Java의 .class 파일은 바이트코드다 바이트코드는 CPU가 직접 실행하는 기계어가 아니다

그래서 JVM은 이 바이트코드를 실행해야 한다 가장 단순한 방식은 인터프리터 방식이다.

바이트코드 한 명령 읽기
  ↓
해석
  ↓
실행
  ↓
다음 바이트코드 읽기

이 방식은 시작하기 쉽다 하지만 계속 반복 실행되는 코드를 매번 해석하면 비효율적일 수 있다

예를 들어 서버에서 이런 메서드가 있다고 하자

public int calculatePrice(int price, int quantity) {
    return price * quantity;
}

이 메서드가 요청마다 수천 번, 수만 번 호출된다면 JVM이 매번 바이트코드를 해석하는 것은 비효율적이다

그래서 JIT 컴파일러가 필요하다

JIT 컴파일러는 모든 코드를 처음부터 기계어로 바꾸지 않는다

대신 JVM은 실행 중 자주 호출되는 코드, 즉 hot code를 찾고, 그 부분을 기계어로 컴파일해 이후 실행을 빠르게 만든다

Java 실행 흐름을 다시 보면 이렇다

처음 실행
  ↓
JVM 인터프리터가 바이트코드를 해석하며 실행
  ↓
자주 실행되는 코드 감지
  ↓
JIT 컴파일러가 해당 코드를 기계어로 컴파일
  ↓
다음부터는 컴파일된 기계어를 더 빠르게 실행

중요한 점은 이것이다

JIT가 있다고 Java가 인터프리터 언어가 되는 것은 아니다
JIT는 JVM이 바이트코드를 더 빠르게 실행하기 위한 최적화 방식이다

Java는 바이트코드로 컴파일된 뒤, JVM에서 인터프리터와 JIT 컴파일러를 함께 사용해 실행된다

JavaScript와 비교하면?

JavaScript는 전통적으로 인터프리터 언어로 설명되는 경우가 많다 하지만 현대 JavaScript 엔진도 단순히 코드를 읽고 실행하는 것에서 끝나지 않는다

Chrome과 Node.js에서 사용하는 V8 엔진은 인터프리터와 최적화 컴파일러를 함께 사용한다

V8 공식 블로그의 Launching Ignition and TurboFan 글에서는 V8의 새로운 실행 파이프라인을 이렇게 설명한다

built upon Ignition, V8’s interpreter, and TurboFan, V8’s newest optimizing compiler

한국어로 풀면, V8은 Ignition이라는 인터프리터와 TurboFan이라는 최적화 컴파일러 위에 만들어졌다는 뜻이다

즉 JavaScript도 실제 실행 내부를 보면 인터프리터와 JIT 컴파일이 섞여 있다

대략 이런 흐름이다

JavaScript 소스코드
  ↓
파싱
  ↓
바이트코드
  ↓
Ignition 인터프리터가 실행
  ↓
자주 실행되는 코드 감지
  ↓
TurboFan이 최적화 컴파일
  ↓
기계어로 빠르게 실행

정리하면 이렇다

JavaScript = 전통적으로 인터프리터 언어로 설명됨
- 이유 = 브라우저나 Node.js 같은 런타임이 코드를 읽고 실행하기 때문
하지만 실제 실행 = 현대 JavaScript 엔진은 인터프리터와 JIT 컴파일러를 함께 사용

그래서 Java와 JavaScript 모두 현대 런타임에서는 컴파일, 인터프리팅, JIT 최적화가 섞인다

다만 분류 기준이 다르다

Java
→ javac가 .java를 .class 바이트코드로 컴파일한다.
→ 그래서 보통 컴파일 언어로 분류한다.

JavaScript
→ 브라우저나 Node.js 런타임이 코드를 읽고 실행하는 방식이 중심이다.
→ 그래서 전통적으로 인터프리터 언어로 설명된다.

백엔드 관점에서 왜 중요할까?

서버 개발자가 실행 방식을 알아야 하는 이유는 운영할 때 확인해야 할 지점이 달라지기 때문이다 Java 서버는 보통 jar를 배포하고 JVM으로 실행한다

java -jar app.jar

Node.js 서버는 JavaScript 소스코드와 Node.js 런타임을 함께 고려한다

node app.js

그래서 장애가 났을 때 확인하는 지점도 다르다

Java
- JVM 버전
- heap
- GC
- jar
- classpath
- JIT warm-up

Node.js
- Node 버전
- npm 패키지
- 이벤트 루프
- V8 메모리

또한 JIT 기반 런타임은 실행 초반과 어느 정도 지난 뒤의 성능이 다를 수 있다 Java 서버도 처음 뜬 직후에는 클래스 로딩, JIT 최적화, 캐시 준비 등으로 초반 성능이 흔들릴 수 있다

그래서 운영에서는 이런 질문이 생긴다

서버 시작 직후 바로 트래픽을 받아도 되는가?
헬스체크는 단순 200 응답만 보면 되는가?
초기 요청에서 응답 시간이 튀는가?
JVM warm-up이 필요한가?

또한 컴파일 단계에서 잡히는 오류와 실행 중 특정 코드 경로에서 드러나는 오류가 다르기 때문에 테스트 전략에도 영향을 준다

Java에서는 타입이 맞지 않거나 문법이 틀리면 컴파일 단계에서 에러가 발생한다

반면 JavaScript에서는 문법 오류는 파싱 단계에서 잡히더라도, 타입이나 특정 코드 경로의 문제는 실제 실행 중에 드러나는 경우가 많다

그래서 이렇게 볼 수 있다

정적 타입 + 컴파일 
→ 컴파일러가 1차 방어선 역할을 한다
동적 타입 + 런타임 실행 중심 
→ 테스트가 더 많은 실행 경로를 커버해야 한다

Spring과 SpringBoot

HS0601 — Tue, 5 May 2026 16:30:22 +0900

Spring공식문서는 이렇게 말한다

The Spring Framework provides a comprehensive programming and configuration model for modern Java-based enterprise applications

Spring Framework는 현대적인 Java 기반 엔터프라이즈 애플리케이션을 만들기 위한 프로그래밍 모델과 설정 모델을 제공한다.

영역	Spring이 해주는 일
객체 관리	객체를 직접 new 하지 않고 Spring Container가 관리
의존성 주입	Service가 Repository를 직접 만들지 않고 주입받게 함
트랜잭션	@Transactional로 DB 작업 단위를 관리
웹 MVC	Controller, DispatcherServlet, RequestMapping 등 제공
데이터 접근	JDBC, ORM, JPA 연동 지원
테스트	Spring Context 기반 통합 테스트 지원
AOP	공통 관심사, 예: 트랜잭션, 로깅, 보안 처리

공식문서도 Spring Framework의 기능을 dependency injection, events, resources, i18n, validation, data binding, type conversion, SpEL, AOP, transactions, DAO support, JDBC, ORM, Spring MVC 등으로 나눠서 설명한다.

자바 객체들을 잘 조립하고, 웹/DB/트랜잭션 같은 서버 애플리케이션의 반복 인프라를 대신 관리해주는 기반 프레임워크다.

Spring의 핵심은 IoC Container

공식문서

ApplicationContext가 Spring IoC 컨테이너를 대표한다.

ApplicationContext란?

Spring IoC Container의 대표 인터페이스

Bean이란?

Spring Container가 생성하고 관리하는 객체

PostRepository postRepository = new PostRepository();
PostService postService = new PostService(postRepository);
PostController postController = new PostController(postService);

자바는 위 코드처럼 한다 즉 개발자가 객체를 직접 만들고 연결한다 그러나 Spring에서는 보통 아래와 같이 한다

@Service
public class PostService {
    private final PostRepository postRepository;

    public PostService(PostRepository postRepository) {
        this.postRepository = postRepository;
    }
}

겉으로 보면 new PostRepository()가 안 보인다 그렇다면 누가 만들었을까?

Spring Container가 만든다

공식문서에 따르면 ApplicationContext는 Bean을 instantiating, configuring, and assembling하는 책임을 가진다. 즉 객체를 생성하고, 설정하고, 서로 조립한다.

눈으로 보는 숨은 구조

내 코드
  ├─ Controller 클래스
  ├─ Service 클래스
  ├─ Repository 클래스
  └─ Config 클래스

Spring ApplicationContext
  ├─ 어떤 클래스를 Bean으로 만들지 읽음
  ├─ 필요한 의존성 관계를 파악함
  ├─ 객체를 생성함
  ├─ 생성자에 필요한 객체를 넣어줌
  └─ 완성된 애플리케이션 구조를 실행 가능하게 만듦

Bean은 Spring이 관리하는 객체다

Spring IoC 컨테이너

In Spring, the objects that form the backbone of your application and that are managed by the Spring IoC container are called beans.

Spring에서 애플리케이션의 뼈대를 이루고 Spring IoC 컨테이너가 관리하는 객체를 Bean이라고 부른다.

일반 객체	Bean
내가 new로 만듦	Spring이 만듦
내가 생명주기 관리	Spring이 생명주기 관리
의존성 직접 연결	Spring이 의존성 연결
테스트에서 직접 조립 필요	Spring Context에서 주입 가능
프록시 적용 어려움	트랜잭션/AOP 프록시 적용 가능

예를들어

@RestController
public class PostController { }

@Service
public class PostService { }

@Repository
public interface PostRepository extends JpaRepository<Post, Long> { }

이런 것들은 Spring이 Bean으로 관리하는 대상이 된다.

@Service를 붙이는 이유는 서비스니까 예쁘게 표시하려고가 아니라, Spring Container가 이 클래스를 애플리케이션 구성 요소로 인식하고 관리하게 하기 위해서다.

DI는 Spring이 객체를 대신 연결해주는 방식이다

Spring의존성관련 문식문서

Dependency injection (DI) is a process whereby objects define their dependencies

DI는 객체가 자신에게 필요한 의존성을 정의하고, 컨테이너가 그 의존성을 넣어주는 과정이다.

public class CommentService {
    private final CommentRepository commentRepository;

    public CommentService(CommentRepository commentRepository) {
        this.commentRepository = commentRepository;
    }
}

여기서 CommentService는 " 나는 CommentRepository가 필요해. 근데 내가 직접 만들지는 않을게. 누군가 넣어줘~”

이 구조의 장점은 공식문서에서 이렇게 설명한다

DI를 쓰면 객체가 자기 의존성을 직접 찾지 않고 의존성의 위치나 구체 클래스를 몰라도 되기 때문에 테스트하기 쉬워진다.

특히 인터페이스나 추상 클래스에 의존하면 stub/mock 구현을 사용할 수 있다

그래서 Mockito 테스트에서 겪는 구조와 연결된다

@Mock
CommentRepository commentRepository;

@InjectMocks
CommentService commentService;

이건 Spring Container를 안 띄우는 대신, Mockito가 비슷하게 가짜 Repository를 Service에 넣어주는 거다

상황	누가 의존성 주입함?
실제 Spring 실행	Spring Container
단위 테스트 Mockito	Mockito
직접 Java 코드	개발자

Spring MVC는 Spring 안에 있는 웹 프레임워크다

SpringMVC공식문서

Spring Web MVC is the original web framework built on the Servlet API

Spring Web MVC는 Servlet API 위에 만들어진 Spring의 원래 웹 프레임워크다.

즉 Spring MVC는 Spring Framework 전체 중 웹 요청 처리 담당 부분이다

브라우저 / Postman
   ↓ HTTP 요청
DispatcherServlet
   ↓
Controller
   ↓
Service
   ↓
Repository
   ↓
DB

여기서 Spring MVC가 주로 해주는 일

기능	예시
URL 매핑	@GetMapping("/posts")
요청 파라미터 바인딩	@RequestParam, @PathVariable
JSON 요청 변환	@RequestBody
JSON 응답 변환	@ResponseBody, ResponseEntity
예외 처리	@ControllerAdvice, @ExceptionHandler
인터셉터	인증/인가 전처리
메시지 컨버터	Java 객체 ↔ JSON 변환

그래서 controller 테스트 시 MockMvc를 쓰는 건 단순히 메서드 테스트가 아니라 Spring MVC 요청 처리 흐름 일부를 흉내내는 테스트라고 보면된다

그럼 Spring Boot는 뭐냐

SpringBoot 공식문서

Spring Boot helps you to create stand-alone, production-grade Spring-based applications

Spring Boot는 독립 실행 가능하고 운영 수준에 가까운 Spring 기반 애플리케이션을 만들도록 도와준다.

핵심 3단계

1. stand-alone : 혼자 실행 가능하다는 뜻

예전 Spring MVC 애플리케이션은 보통 WAR로 만들고, 외부 Tomcat에 배포했다.

외부 Tomcat 설치
  └─ WAR 배포
      └─ Spring MVC 애플리케이션 실행

Spring Boot는

java -jar app.jar
  └─ 내장 Tomcat 같이 뜸
      └─ Spring 애플리케이션 실행

공식문서도 Spring Boot 애플리케이션은 java -jar로 시작할 수 있다고 설명한다. 그래서 EC2에서 app.jar 실행하고 systemd로 관리했던 구조다.

2. production-grade : 운영 수준이라는 뜻

Spring Boot 공식문서의 목표에는 embedded servers, security, metrics, health checks, externalized configuration 같은 비기능 요구사항을 제공한다는 내용이 있다.

Externalized Configuration란?

application.yml, 환경변수, command line args 등으로 설정을 코드 밖에서 관리하는 방식

Embedded Server란?

애플리케이션 안에 포함된 Tomcat/Jetty/Undertow 같은 서버

이때, 비기능 요구사항이란

기능 요구사항	비기능 요구사항
게시글 작성	서버가 죽었는지 확인
댓글 조회	응답 시간이 느린지 확인
로그인	설정을 dev/prod로 분리
게시판 생성	로그/메트릭/헬스체크 제공

즉, Spring Boot는 게시글 CRUD를 쉽게 만든다가 전부가 아니라 애플리케이션을 실행, 배포, 관찰하기 쉽게 만들어준다

이게 바로 운영 관점에서의 Spring Boot의 가치

3.Spring-based : Spring 기반이라는 뜻

Spring Boot는 Spring 없이 독립적으로 존재하는 프레임워크가 아니다

Spring Boot 공식문서도 Spring Boot를 Spring-based applications를 만들도록 돕는다고 표현한다.

구조

Java
  ↓
Spring Framework
  ├─ IoC Container
  ├─ DI
  ├─ AOP
  ├─ Transaction
  ├─ Spring MVC
  └─ Data Access 지원
      ↓
Spring Boot
  ├─ Auto Configuration
  ├─ Starter Dependencies
  ├─ Embedded Tomcat
  ├─ Externalized Configuration
  ├─ Actuator
  └─ Executable Jar

Auto Configuration란?

classpath, 설정값, Bean 존재 여부 등을 보고 Boot가 자동으로 설정 Bean을 등록하는 기능

Spring Boot가 해주는 핵심 1: 자동 설정

SpringBoot 공식문서에서는 이렇게 말한다

Auto-configuration is non-invasive.

Auto-configuration은 침투적이지 않다. 즉 네가 직접 설정하면 Boot 기본 설정은 물러난다.

Spring Boot는 프로젝트 상태를 보고 판단한다. 예를들어

implementation 'org.springframework.boot:spring-boot-starter-web'

이걸 넣으면 Boot는 대충 이런 판단을 한다

어? spring-webmvc가 classpath에 있네?
어? Servlet 기반 웹 애플리케이션이겠네?
그럼 Tomcat 띄우고
DispatcherServlet 등록하고
Jackson 메시지 컨버터 넣고
기본 Error 처리도 넣자.

Classpath란?

현재 애플리케이션이 사용할 수 있는 라이브러리/클래스 경로

그런데, 직접 Bean을 등록하면 boot는 아, 사용자가 직접 만들었네 그럼 내 기본값은 빠질게~라는 식으로 동작한다

@Bean
public ObjectMapper objectMapper() {
    return new ObjectMapper();
}

공식문서에서도 직접 DataSource Bean을 추가하면 기본 embedded database 지원이 물러난다고 설명한다.

그래서 Boot를 잘 쓰려면

기본값으로 빠르게 시작한다.
문제가 생기면 어떤 자동 설정이 적용됐는지 확인한다.
필요한 부분만 직접 Bean으로 덮어쓴다.

Spring Boot가 해주는 핵심 2: Starter

Starters are a set of convenient dependency descriptors

Starter는 편리한 의존성 묶음이다.

예를 들어 Boot 없이 Spring MVC를 직접 구성한다고 생각해볼 때, 웹 서버 만들려면 대충 이런 것들을 알아서 골라야 한다

spring-web
spring-webmvc
jackson
validation
tomcat
logging
...

근데 Spring Boot에서는 보통 이거 하나 넣는다

implementation 'org.springframework.boot:spring-boot-starter-web'

그러면 필요한 의존성들이 같이 들어온다.

spring-boot-starter-web은 대충 이런 의도를 가진 묶음이다

웹 MVC 애플리케이션 만들 거지?
그러면 MVC, JSON 변환, 내장 Tomcat, 검증, 로깅 같은 기본 묶음 넣어줄게.

spring-boot-starter-data-jpa는 이런 의도

JPA로 DB 접근할 거지?
그러면 Spring Data JPA, Hibernate, JDBC 관련 기본 묶음 넣어줄게.

즉, Starter는 라이브러리 하나라기보다 필요한 라이브러리 조합을 Spring Boot 팀이 추천 세트로 묶어둔 것에 가깝다

Spring Boot가 해주는 핵심 3: 의존성 버전 관리

공식문서에 따르면 Spring Boot는 각 릴리스마다 지원하는 의존성 목록을 제공하고, 실제로는 빌드 설정에서 이런 의존성들의 버전을 직접 적지 않아도 Boot가 관리한다. 또한 Spring Boot를 업그레이드하면 관련 의존성들도 일관된 방식으로 업그레이드된다.

implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

버전을 안 적는다. 왜냐면 Spring Boot플러그인과 BOM이 이 Boot 버전에서는 이 라이브러리 버전 조합이 맞다를 관리해주기 때문이다

Spring Boot가 해주는 핵심 4: 내장 서버

SpringBoot 공식문서에서는 이렇게 말한다

Embed Tomcat, Jetty or Undertow directly

Tomcat, Jetty, Undertow를 애플리케이션 안에 직접 포함할 수 있다.

이게 Spring과 Spring Boot 차이 중 하나다

예전방식

1. 서버에 Tomcat 설치
2. WAR 파일 생성
3. Tomcat webapps에 배포
4. Tomcat이 애플리케이션 실행

Boot 방식

1. JAR 파일 생성
2. java -jar app.jar
3. JAR 안의 내장 Tomcat이 같이 실행

그래서 EC2에서 java -jar app.jar 혹은 systemd로 ExecStart=/usr/bin/java -jar /home/ubuntu/apps/coreboard/app.jar

이런 식으로 운영할 수 있었던 것이다

Spring Boot가 해주는 핵심 5: @SpringBootApplication

SpringBoot 공식문서에서는 이렇게 말한다

Spring Boot에서 가장 많이 보는 게 아래 코드다

@SpringBootApplication
public class CoreBoardApplication {
    public static void main(String[] args) {
        SpringApplication.run(CoreBoardApplication.class, args);
    }
}

공식문서에 따르면 @SpringBootApplication 하나로 auto-configuration, component scan, extra configuration 정의를 활성화할 수 있다.

Component Scan란?

@Component, @Service, @Controller 등을 찾아 Bean으로 등록하는 과정

실제로 이 애노테이션은 크게 세 가지 의미를 합친 것

구성	의미
@SpringBootConfiguration	이 클래스가 설정 클래스임
@EnableAutoConfiguration	Boot 자동 설정 켬
@ComponentScan	현재 패키지 기준으로 컴포넌트 스캔

공식문서도 @ComponentScan은 애플리케이션이 위치한 패키지에서 @Component scan을 활성화한다고 설명한다

그래서 패키지 위치가 중요하다.

com.example.coreboard
 ├─ CoreBoardApplication.java
 └─ domain
     ├─ post
     ├─ comment
     ├─ board
     └─ users

나쁜구조

com.example
 ├─ post
 └─ app
     └─ CoreBoardApplication.java

왜냐면 @SpringBootApplication이 붙은 클래스의 패키지를 기준으로 하위 패키지를 스캔하기 때문이다. Boot 공식문서도 main application class를 root package에 두는 것을 권장한다고 설명한다.

SpringApplication.run()은 뭐 하는 애냐

SpringApplication.run(CoreBoardApplication.class, args);

이 한 줄은 단순히 main 메서드 실행이 아니다.

1. 애플리케이션 타입 판단
   - Servlet 웹인가?
   - Reactive 웹인가?
   - 일반 애플리케이션인가?
2. ApplicationContext 생성
   - Spring IoC Container 준비
3. Environment 준비
   - application.yml
   - profile
   - command line args
   - OS 환경변수
4. BeanDefinition 로딩
   - @Component
   - @Service
   - @Repository
   - @Controller
   - @Configuration
   - @Bean
5. Auto Configuration 적용
   - classpath와 조건 기반으로 자동 설정 적용
6. Bean 생성 및 의존성 주입
   - Controller → Service → Repository
7. 내장 웹 서버 실행
   - Tomcat 등
8. 애플리케이션 준비 완료

그래서 Boot 애플리케이션을 실행했을 때 로그에 이런 게 뜨는 것이다.

Started CoreBoardApplication in ... seconds

그리고 만약 8080 포트가 이미 사용 중이면 Boot는 실패 분석 메시지를 제공한다. 공식문서에서도 port 8080이 이미 사용 중일 때 APPLICATION FAILD TO START와 함께 원인과 조치를 보여주는 예시를 든다.

이게 Spring Boot의 운영 친화적인 부분이다

Spring과 SpringBoot의 차이를 한 장으로 정리

구분	Spring	Spring Boot
정체	기반 프레임워크	Spring 기반 애플리케이션을 쉽게 만드는 도구층
핵심	IoC, DI, AOP, MVC, Transaction	Auto Configuration, Starter, Embedded Server, Actuator
설정 방식	직접 설정이 많음	기본 설정 자동 제공
실행 방식	외부 WAS 배포가 흔했음	java -jar 단독 실행 가능
의존성 관리	개발자가 조합 관리	Boot가 권장 버전 조합 관리
운영 기능	직접 붙여야 함	Actuator, metrics, health 등 제공
대체 관계	기반	Spring 위에서 동작
예시	ApplicationContext, @Service, @Transactional	@SpringBootApplication, starter, auto config

Actuator란?

health check, metrics 등 운영용 기능을 제공하는 Spring Boot 모듈

Spring Boot를 쓰면 Spring을 몰라도 되냐?

No.

오히려 알아야 한다고 본다 왜냐면 Boot가 해주는 자동 설정의 결과물이 결국 Spring Bean이기 때문이다

예를들어

@Service
public class PostService { }

위 코드는 Spring 개념이다

implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

위 코드는 Boot 개념이다

@Transactional
public void createPost(...) { }

위 코드는 Spring transactional/AOP 개념이다

spring:
  datasource:
    url: jdbc:mysql://...

위 코드는 Boot external configuration 개념이다

@Repository
public interface PostRepository extends JpaRepository<Post, Long> { }

위 코드는 Spring Data JPA + Boot 자동 설정이 같이 얽힌 구조다

Spring을 모르면
- 어노테이션 붙였는데 왜 안 되지?

Spring Boot만 모르면
설정은 어디서 자동으로 된 거지?

둘 다 알면
이 Bean은 component scan으로 등록됐고,
DataSource는 Boot auto-configuration으로 잡혔고,
TransactionManager는 JPA 설정 기반으로 등록됐고,
@Transactional은 프록시로 감싸져서 동작하겠네.

[Devlog]CoreBoard pagination 뜯어고쳐!

HS0601 — Tue, 5 May 2026 15:40:05 +0900

댓글 전체조회 기능을 구현하려고 하다가 페이지네이션에서 한 번 멈췄다. 처음에는 페이지네이션을 단순히 이렇게 이해하고 있었다.

Offset
Keyset
Slice

그런데 공부하다 보니 이 분류가 정확하지 않았다.

Page와 Slice는 Spring Data가 조회 결과를 어떤 형태로 반환할지에 대한 모델이고, Offset과 Keyset은 DB에서 데이터를 어떤 방식으로 가져올지에 대한 조회 방식이었다.

이 내용은 따로 정리해두었다.

https://winwin0219.tistory.com/309

Page, Slice, Offset, Keyset

댓글 전체조회 기능을 구현하려고 하다가 페이지네이션에서 한 번 멈췄다.처음에는 페이지네이션 종류를 이렇게 이해하고 있었다.OffsetKeysetSlice 근데 공부하다 보니 이 분류가 정확하지 않았다.

winwin0219.tistory.com

이걸 다시 공부하고 나니 CoreBoard의 페이지네이션 전략도 다시 봐야 했다. 처음에는 게시글 목록에 Keyset pagination을 적용했다. 이유는 단순했다.

Offset보다 Keyset이 빠르다.
깊은 페이지로 갈수록 Offset 비용이 커질 수 있다.
그러면 게시글 목록도 Keyset으로 가는 게 낫지 않을까?

성능만 보면 틀린 판단은 아니었다. 하지만 문제는 게시글 목록의 사용 흐름이었다.

CoreBoard의 게시글 목록은 무한스크롤 피드라기보다는 일반적인 게시판 목록에 가깝다.

사용자는 게시판 목록에서 1페이지, 2페이지처럼 특정 페이지로 이동할 수 있고, 전체 게시글 수나 전체 페이지 수가 필요할 수 있다. 예를 들면 이런 흐름이다.

1 2 3 4 5 다음

이런 화면에서는 단순히 다음 데이터가 더 있는가?만으로는 부족하다. 전체 데이터가 몇 개인지, 전체 페이지가 몇 개인지 알아야 페이지 번호 기반 UI를 만들 수 있다.

그래서 게시글 목록은 Offset + Page가 더 자연스럽다고 판단했다.

게시글 목록
=> Offset + Page

Offset은 page와 size를 기준으로 몇 개를 건너뛰고 몇 개를 가져올지 정한다.

SELECT *
FROM post
ORDER BY id DESC
LIMIT 10 OFFSET 20;

Page는 가져온 데이터와 함께 전체 개수, 전체 페이지 수를 응답한다.

{
  "content": [
    {
      "postId": 1,
      "title": "게시글 제목"
    }
  ],
  "pageInfo": {
    "page": 2,
    "size": 10,
    "totalElements": 53,
    "totalPages": 6
  }
}

물론 Offset 방식은 깊은 페이지로 갈수록 비용이 커질 수 있다. 다만 게시판 목록에서는 페이지 번호 이동이라는 UX가 중요하므로, 무조건 Keyset을 적용하는 것보다 Offset을 사용하고 정렬 기준에 인덱스를 적용하는 쪽이 더 맞다고 판단했다.

너무 깊은 페이지 접근은 검색이나 필터로 유도하는 것이 더 현실적이라고 봤다.

댓글은 Page가 아니라 Slice가 맞다

반대로 댓글 목록은 게시글 목록과 사용 흐름이 다르다. 댓글에서 사용자가 정말 궁금한 것은 보통 이게 아니다.

댓글이 총 몇 페이지인가?보다 댓글을 더 볼 수 있는가?에가깝다.

즉 댓글은 전체 페이지 수보다 다음 댓글 존재 여부가 더 중요하다. 그래서 댓글 전체조회는 Offset + Slice로 가는 것이 맞다고 판단했다.

Slice<Comment> findByPostId(Long postId, Pageable pageable);

Slice는 전체 개수와 전체 페이지 수를 알려주지 않는다. 대신 현재 목록과 다음 데이터 존재 여부를 알려준다.

응답도 이런 형태면 충분하다.

{
  "content": [
    {
      "commentId": 1,
      "content": "댓글 내용"
    }
  ],
  "pageInfo": {
    "page": 0,
    "size": 10,
    "hasNext": true
  }
}

여기서 핵심은 hasNext다.

hasNext = true
=> 다음 댓글이 더 있음

hasNext = false
=> 더 이상 불러올 댓글이 없음

댓글 화면에서 필요한 건 전체 댓글 페이지 수가 아니라 더보기 버튼을 보여줄지 말지다. 그래서 Page보다 Slice가 더 자연스럽다.

PageInfo를 그대로 재사용하지 않기로 했다

기존에 Page 응답을 위해 PageInfo를 사용하고 있었다.

public class PageInfo {
    private final int page;
    private final int size;
    private final long totalElements;
    private final int totalPages;
}

이 구조는 Page 응답에는 잘 맞는다. totalElements와 totalPages가 있기 때문이다.

하지만 Slice 응답에는 이 두 값이 필요 없다. Slice의 관심사는 전체 개수가 아니라 다음 데이터 존재 여부다.

PageInfo
=> page, size, totalElements, totalPages

SliceInfo
=> page, size, hasNext

처음에는 PageInfo를 상속해서 SliceInfo를 만들 수도 있지 않을까 생각했다. 하지만 그렇게 하면 Slice인데도 totalElements, totalPages를 억지로 들고 있어야 한다.

Slice인데 totalElements가 있다?
Slice인데 totalPages가 있다?

그럼 이 값은 0이라는 뜻인가?
아니면 모른다는 뜻인가?

의미가 애매해진다. 그래서 이건 상속 문제가 아니라 설계 의미의 문제라고 봤다. SliceInfo는 PageInfo의 하위 개념이 아니다.

둘은 비슷해 보이지만 목적이 다르다.

PageInfo
=> 전체 개수와 전체 페이지 수를 아는 응답 정보

SliceInfo
=> 다음 데이터 존재 여부만 아는 응답 정보

그래서 Slice 응답용 정보는 따로 분리하기로 했다.

public class SliceInfo {
    private final int page;
    private final int size;
    private final boolean hasNext;

    public SliceInfo(int page, int size, boolean hasNext) {
        this.page = page;
        this.size = size;
        this.hasNext = hasNext;
    }

    public int getPage() {
        return page;
    }

    public int getSize() {
        return size;
    }

    public boolean isHasNext() {
        return hasNext;
    }
}

그리고 Slice 응답은 이런 식으로 구성한다.

public class SliceResponse<T> {
    private final List<T> content;
    private final SliceInfo pageInfo;

    public SliceResponse(List<T> content, SliceInfo pageInfo) {
        this.content = content;
        this.pageInfo = pageInfo;
    }

    public List<T> getContent() {
        return content;
    }

    public SliceInfo getPageInfo() {
        return pageInfo;
    }
}

이렇게 분리하면 Page 응답과 Slice 응답의 의미가 명확해진다. Page 응답은 전체 개수와 전체 페이지 수를 포함한다.

Slice 응답은 다음 데이터 존재 여부만 포함한다.

Keyset은 버린 게 아니라 분리했다

이번에 게시글 목록을 Offset + Page로 바꾼다고 해서 Keyset을 버린 것은 아니다.

Keyset은 여전히 장점이 있다.

특히 최신글 더보기나 무한스크롤처럼 계속 아래로 이어서 조회하는 화면에서는 Keyset이 잘 맞는다.

예를 들어 마지막으로 본 게시글 ID가 100이라면 다음 데이터는 이런 식으로 가져올 수 있다.

SELECT *
FROM post
WHERE id < 100
ORDER BY id DESC
LIMIT 10;

이 방식은 페이지 번호 이동에는 약하지만, 이어보기에는 좋다.

따라서 Keyset은 일반 게시판 목록에 억지로 적용하지 않고, 최신글 더보기나 무한스크롤 API가 필요해졌을 때 별도 API로 제공하는 방향이 더 맞다고 판단했다.

최종 결정

정리하면 CoreBoard의 페이지네이션 전략은 이렇게 가져간다.

조회	대상	전략이유
게시글 목록	Offset + Page	페이지 번호 이동, 전체 개수, 전체 페이지 수가 필요함
댓글 목록	Offset + Slice	전체 페이지 수보다 다음 댓글 존재 여부가 중요함
최신글 더보기 / 무한스크롤	Keyset 별도 API	마지막으로 본 기준값 이후 데이터를 이어서 조회하는 흐름에 적합함

처음에는 빠른 방식 하나를 고르면 된다고 생각했다. 하지만 다시 보니 페이지네이션은 성능만의 문제가 아니었다.

사용자가 목록을 어떤 방식으로 탐색하는지, 응답에 어떤 정보가 필요한지, 그 정보를 만들기 위해 DB가 어떤 비용을 부담하는지를 같이 봐야 했다.

그래서 모든 목록 조회에 하나의 페이지네이션 전략을 적용하지 않기로 했다.

게시글 목록은 Offset + Page.

댓글 목록은 Offset + Slice.

최신글 더보기나 무한스크롤은 필요할 때 Keyset 별도 API.

이렇게 조회 목적에 따라 분리하는 쪽이 더 자연스럽다고 판단했다.

정리

이번 결정의 핵심은 이거다.

Offset이 느릴 수 있으니 무조건 Keyset을 쓰자가 아니다.
조회 목적에 따라 Offset + Page, Offset + Slice, Keyset을 나눠야 한다.

게시글 목록은 페이지 번호 기반 탐색이 중요하다.

댓글은 전체 페이지 수보다 다음 데이터 존재 여부가 중요하다.

최신글 더보기는 마지막으로 본 기준값 이후 데이터를 이어서 가져오는 흐름이 중요하다.

따라서 페이지네이션 전략은 하나로 고정하는 것이 아니라, 조회 목적과 사용자 흐름에 맞게 나누는 것이 맞다.

[JPA]Page, Slice, Offset, Keyset

HS0601 — Tue, 5 May 2026 15:32:04 +0900

댓글 전체조회 기능을 구현하려고 하다가 페이지네이션에서 한 번 멈췄다.

처음에는 페이지네이션 종류를 이렇게 이해하고 있었다.

Offset
Keyset
Slice

근데 공부하다 보니 이 분류가 정확하지 않았다.

정확히는 페이지네이션을 볼 때 두 가지를 나눠서 봐야 했다.

1. DB에서 데이터를 어떻게 가져올 것인가?
   - Offset
   - Keyset

2. 가져온 결과를 어떤 형태로 응답할 것인가?
   - Page
   - Slice
   - List
   - Window

즉, Offset, Keyset은 조회 방식이고, Page, Slice는 Spring Data가 제공하는 반환 타입에 가깝다. 처음에는 Page = Offset, Slice = Keyset 같은 느낌으로 이해했는데 아니었다.

Page는 전체 개수와 전체 페이지 수를 포함하는 반환 모델이고, Slice는 다음 데이터가 있는지만 알려주는 반환 모델이다.

반대로 Offset은 앞에서 몇 개를 건너뛰고 가져오는 방식이고, Keyset은 마지막으로 본 값을 기준으로 다음 데이터를 가져오는 방식이다.

[클라이언트 요청]  →  Pageable  →  [DB 조회]  →  Slice / Page  →  [응답]
                     ↑ 입력                           ↑ 출력
                  "몇 번째 페이지,                 "결과 데이터 +
                   몇 개씩 줘"                      hasNext/totalPage"

공식문서에서 확인한 내용

Spring Data Commons 공식문서는 Pageable, Sort, Limit 같은 타입을 인식해서 쿼리에 pagination, sorting, limiting을 동적으로 적용할 수 있다고 설명한다.

the infrastructure recognizes certain specific types like Pageable, Sort and Limit, to apply pagination, sorting and limiting to your queries dynamically.

한국어로 풀면, Repository 메서드 파라미터에 Pageable 같은 타입을 넣으면 Spring Data가 그 정보를 보고 페이징, 정렬, 제한을 쿼리에 적용해준다는 뜻이다.

예를 들어 공식문서에도 이런 형태가 나온다.

Page<User> findByLastname(String lastname, Pageable pageable);

Slice<User> findByLastname(String lastname, Pageable pageable);

같은 Pageable을 받더라도 반환 타입을 Page로 할 수도 있고, Slice로 할 수도 있다. 이 말은 곧 Pageable = Page 전용이 아니라는 뜻이다. Pageable은 요청 정보다.

page
size
sort

이런 정보를 담는다.

반면 Page와 Slice는 응답 모델이다.

Page란 무엇인가?

Page는 데이터 목록뿐 아니라 전체 개수와 전체 페이지 수까지 알려주는 반환 타입이다. 예를 들면 이런 응답이다.

{
  "content": [
    {
      "postId": 1,
      "title": "제목"
    }
  ],
  "pageInfo": {
    "page": 0,
    "size": 10,
    "totalElements": 53,
    "totalPages": 6
  }
}

여기서 중요한 값은 이 두 개다.

totalElements
totalPages

totalElements는 조건에 맞는 전체 데이터 개수다.
totalPages는 전체 데이터를 size 기준으로 나눴을 때 몇 페이지가 나오는지다.

예를 들어 전체 게시글이 53개이고 한 페이지에 10개씩 보여준다면 전체 페이지 수는 6페이지가 된다.

53 / 10 = 5.3
=> 올림해서 6페이지

문제는 DB가 이 값을 그냥 알고 있는 게 아니라는 점이다. 현재 페이지 데이터 10개를 가져오는 쿼리는 이런 식이다.

SELECT *
FROM post
ORDER BY id DESC
LIMIT 10 OFFSET 0;

이 쿼리는 현재 페이지에 필요한 데이터 10개만 가져온다. 하지만 이 쿼리만으로는 전체 게시글이 53개인지, 530개인지, 5만 개인지 알 수 없다. 그래서 전체 개수를 알려면 DB에 따로 물어봐야 한다.

SELECT COUNT(*)
FROM post;

이게 count query다. Spring Data 공식문서도 Page는 전체 element 수와 전체 page 수를 알고, 이를 계산하기 위해 infrastructure가 count query를 실행한다고 설명한다.

A Page knows about the total number of elements and pages available. It does so by the infrastructure triggering a count query to calculate the overall number.

한국어로 풀면, Page는 전체 데이터 수와 전체 페이지 수를 알아야 하므로 Spring Data가 전체 개수를 계산하기 위한 count query를 실행한다는 뜻이다.

즉 Page는 단순히 데이터만 가져오는 게 아니라, 전체 개수를 계산하는 작업까지 포함할 수 있다. 공식문서도 이 count query가 비용이 클 수 있다고 말한다.

As this might be expensive (depending on the store used), you can instead return a Slice.

한국어로 풀면, 저장소나 쿼리 상황에 따라 전체 개수를 세는 작업이 비쌀 수 있으므로, 대신 Slice를 반환할 수 있다는 뜻이다.

그래서 Page는 이런 화면에 어울린다.

전체 게시글 수가 필요할 때
전체 페이지 수가 필요할 때
1, 2, 3, 4 같은 페이지 번호 UI가 필요할 때
관리자 화면처럼 정확한 총 개수가 중요할 때

Slice란 무엇인가?

Slice는 전체 개수와 전체 페이지 수를 알려주지 않는다. 대신 현재 데이터 목록과 다음 데이터가 있는지 여부만 알려준다.

예를 들면 이런 응답이다.

{
  "content": [
    {
      "commentId": 1,
      "content": "댓글 내용"
    }
  ],
  "pageInfo": {
    "page": 0,
    "size": 10,
    "hasNext": true
  }
}

여기서 핵심은 hasNext다.

hasNext = 다음 데이터가 더 있는가?

공식문서도 Slice는 다음 Slice가 있는지만 안다고 설명한다.

A Slice knows only about whether a next Slice is available

한국어로 풀면, Slice는 다음 조각이 존재하는지만 알고 있다는 뜻이다.

즉 Slice는 전체 데이터가 몇 개인지는 모른다. 대신 프론트가 더보기 버튼을 보여줄지 말지만 판단할 수 있게 해준다.

hasNext = true
=> 더보기 버튼 보여줌

hasNext = false
=> 더보기 버튼 숨김

그래서 Slice는 이런 화면에 어울린다.

더보기
무한스크롤
다음 목록 불러오기
전체 개수보다 다음 데이터 존재 여부가 중요한 화면

왜 Slice는 size + 1개를 조회할까?

처음에 이 부분이 제일 헷갈렸다.

요청 size가 10이면 그냥 10개만 가져오면 되는 거 아닌가 싶었다.

근데 10개만 가져오면 다음 데이터가 있는지 알 수 없다.

예를 들어 사용자가 10개를 요청했다고 해보자.

요청 size = 10

DB에서 정확히 10개가 조회됐다.

조회 결과 = 10개

이때 서버 입장에서는 애매하다.

정말 전체 데이터가 딱 10개라서 끝인 건지
아니면 뒤에 데이터가 더 있는데 이번에 10개만 가져온 건지
알 수 없다.

그래서 Slice는 보통 요청한 size보다 1개를 더 조회해본다. Spring Data 공식문서의 표에도 Slice<T>는 Pageable.getPageSize() + 1만큼 가져온다고 되어 있다.

예를 들어 size가 10이면 실제로는 11개를 조회해본다.

요청 size = 10
실제 확인 = 11개

만약 11개가 조회되면?

사용자에게 줄 10개 외에 뒤에 최소 1개가 더 있다는 뜻
=> hasNext = true

응답으로는 11개를 다 주지 않고 10개만 내려준다.

{
  "content": ["10개"],
  "hasNext": true
}

반대로 10개 이하만 조회되면?

뒤에 더 이상 데이터가 없다는 뜻
=> hasNext = false

정리하면 이렇다.

Page는 전체 개수를 세어서 전체 페이지 수를 계산한다.
Slice는 전체 개수를 세지 않고, 1개를 더 조회해서 다음 데이터 존재 여부만 판단한다.

이건 N+1 문제와는 다르다.

N+1은 연관 엔티티를 가져오느라 쿼리가 여러 번 추가로 나가는 문제다.

반면 Slice의 size + 1은 쿼리를 여러 번 날리는 게 아니라, 한 번 조회할 때 row를 1개 더 가져와서 다음 데이터 존재 여부를 확인하는 방식이다.

Page와 Slice 비교

구분	Page	Slice
목적	전체 페이지 기반 조회	더보기/다음 존재 여부 조회
전체 개수	있음	없음
전체 페이지 수	있음	없음
다음 데이터 여부	있음	있음
count query	보통 필요	보통 불필요
적합한 화면	게시글 목록, 관리자 목록, 검색 결과	댓글, 알림, 피드, 더보기

Offset과 Keyset은 반환 타입이 아니라 조회 방식이다

여기서 다시 한 번 정리해야 한다.

Page, Slice는 반환 타입이다.

반면 Offset, Keyset은 DB에서 데이터를 가져오는 방식이다.

Offset

Offset은 앞에서 몇 개를 건너뛰고 가져오는 방식이다.

예를 들어 page = 2, size = 10이면 앞에서 20개를 건너뛰고 10개를 가져온다.

SELECT *
FROM post
ORDER BY id DESC
LIMIT 10 OFFSET 20;

즉 Offset의 관심사는 이거다.

몇 개를 건너뛰고
몇 개를 가져올 것인가?

Spring Data에서 Pageable을 사용하면 보통 이 Offset 기반 조회와 연결된다.

공식문서의 표에서도 Slice<T>와 Page<T> 모두 Pageable.getOffset()에서 시작해 limit을 적용한다고 설명한다.

즉 아래 코드는 보통 Offset + Page에 가깝다.

Page<Post> findByBoardId(Long boardId, Pageable pageable);

그리고 아래 코드는 보통 Offset + Slice에 가깝다.

Slice<Comment> findByPostId(Long postId, Pageable pageable);

같은 Offset 기반 조회라도 반환 타입을 Page로 할 수도 있고, Slice로 할 수도 있다.

Keyset

Keyset은 앞에서 몇 개를 건너뛰는 방식이 아니다. 마지막으로 본 데이터의 기준값을 이용해서 다음 데이터를 가져오는 방식이다.

예를 들어 마지막으로 본 게시글 ID가 100이라면 다음 요청은 이런 식이 된다.

SELECT *
FROM post
WHERE id < 100
ORDER BY id DESC
LIMIT 10;

Offset은 이렇게 생각한다.

앞에서 100개 건너뛰고 10개 가져와.

Keyset은 이렇게 생각한다.

내가 마지막으로 본 id가 100이니까,
id 100보다 작은 데이터 중에서 10개 가져와.

그래서 Keyset의 관심사는 이거다.

마지막으로 본 기준값이 무엇인가?
그 기준값 이후/이전 데이터를 어떻게 가져올 것인가?

Spring Data JPA 공식문서의 Scrolling 부분에서도 scrolling은 stable sort, scroll type, result limiting으로 구성된다고 설명한다.

Scrolling consists of a stable sort, a scroll type (Offset- or Keyset-based scrolling) and result limiting.

한국어로 풀면, 스크롤링 방식으로 큰 결과를 나눠서 볼 때는 안정적인 정렬 기준, Offset 또는 Keyset 같은 스크롤 방식, 한 번에 가져올 개수 제한이 필요하다는 뜻이다.

또한 공식문서는 Offset-based scrolling과 Keyset-based scrolling을 구분하고, Keyset 기반 조회는 적절한 인덱스 구조가 필요하다고 설명한다.

그래서 하나만 정하면 되는 게 아니었다

처음에는 Page를 쓸까? Slice를 쓸까?만 정하면 되는 줄 알았다. 근데 정확히는 두 가지를 같이 정해야 했다.

1. 조회 방식
   - Offset
   - Keyset

2. 반환 타입
   - Page
   - Slice
   - CursorResponse
   - Window

예를 들면 이런 식이다.

Offset + Page
=> page/size로 건너뛰어 조회하고, 전체 개수와 전체 페이지 수까지 응답한다.

Offset + Slice
=> page/size로 건너뛰어 조회하되, 전체 개수는 세지 않고 다음 데이터 존재 여부만 응답한다.

Keyset + Slice 스타일 응답
=> 마지막으로 본 기준값 이후/이전 데이터를 조회하고, 다음 데이터 존재 여부와 다음 cursor를 응답한다.

즉 Page = Offset이 아니고, Slice = Keyset도 아니다. Offset / Keyset은 데이터를 가져오는 방식이고, Page / Slice는 가져온 결과를 어떤 정보와 함께 내려줄지에 대한 응답 모델이다.

[Devlog] CoreBoard에서 기능보다 먼저 설계 기준을 세운 이유

HS0601 — Mon, 4 May 2026 16:45:39 +0900

https://winwin0219.tistory.com/300

[회고] CoreBoard 프로젝트, 왜 만들었는가

CoreBoard 기획했을 때로 거슬러 올라가자 때는 2025년 9월 말. Momentix에서 느꼈던 부담감이 있었다. 부트캠프의 문제점이자 나의 약점(비전공자)이었던 동작은 하지만 얕은 이해도였다. 요즘 현업에

winwin0219.tistory.com

[Devlog] API 예외를 직접 정의한 이유

CoreBoard를 만들면서 생각보다 빨리 마주친 문제가 있다. 바로 예외처리다. 처음에는 단순하게 생각했다.

잘못된 요청이면 400
권한 없으면 403
없으면 404
중복이면 409

이 정도만 정하면 되는 줄 알았다. 근데 실제로 코드를 짜다 보니 문제가 생겼다. 컨트롤러마다, 서비스마다 예외 메시지를 직접 쓰기 시작하면 금방 지저분해진다.

throw new RuntimeException("존재하지 않는 게시판입니다.");
throw new RuntimeException("권한이 없습니다.");
throw new RuntimeException("이미 존재하는 이름입니다.");

근데 기능이 늘어나면 어느 순간부터 이게 관리가 안 된다. 메시지를 바꾸고 싶으면 서비스 코드를 뒤져야 하고, 같은 404인데 응답 모양이 다를 수도 있고, 프론트 입장에서는 어떤 에러인지 안정적으로 분기하기 어렵다.

그래서 CoreBoard에서는 Custom Exception을 직접 정의했다.

공식문서에서 본 기준

Spring 공식문서에서는 @ControllerAdvice와 @ExceptionHandler를 이용해서 컨트롤러에서 발생한 예외를 처리할 수 있다고 설명한다.

@Controller and @ControllerAdvice classes can have @ExceptionHandler methods to handle exceptions from controller methods라고 되어 있다.

한국어로 풀면, 컨트롤러마다 try-catch를 두는 게 아니라, 공통 예외 처리 클래스를 두고 특정 예외가 발생했을 때 한 곳에서 처리할 수 있다는 뜻이다.

CoreBoard의 예외 구조

CoreBoard에서는 예외를 그냥 문자열로 던지지 않았다. 대신 공통 부모 예외를 두고, 각 도메인별 예외가 그 구조를 따르게 했다.

ErrorException
 ├── AuthErrorException
 ├── BoardErrorException
 ├── PostErrorException
 └── ...

그리고 에러 정보는 enum으로 관리했다.

AuthErrorCode.UNAUTHORIZED
BoardErrorCode.BOARD_NOT_FOUND
PostErrorCode.POST_NOT_FOUND

왜 RuntimeException 하나로 끝내지 않았는가?

RuntimeException 하나로도 기능은 돌아간다. 근데 CoreBoard의 목표는 돌아가는 코드가 아니라 왜 이렇게 나눴는지 설명 가능한 코드였다.

RuntimeException만 쓰면 이런 문제가 있다.

1. 어떤 도메인에서 발생한 예외인지 흐려진다.

2. HTTP 상태코드와 메시지 관리가 흩어진다.

3. 프론트가 안정적으로 에러를 분기하기 어렵다.

4. 테스트에서 어떤 예외가 터져야 하는지 명확히 검증하기 어렵다.

반대로 Custom Exception을 두면 이런 장점이 있다.

1. 예외의 의미가 코드에 드러난다.
2. 도메인별 에러 정책을 분리할 수 있다.
3. GlobalExceptionHandler에서 공통 응답으로 변환하기 쉽다.
4. 테스트에서 기대 예외를 명확히 검증할 수 있다.

CoreBoard에서 중요하게 본 것

서비스 코드를 읽었을 때,

throw new BoardErrorException(BoardErrorCode.BOARD_NOT_FOUND);

이 한 줄만 보고도 게시판이 없어서 터진 예외구나를 바로 알 수 있게 만들고 싶었다. 그리고 응답은 항상 같은 형태로 내려가게 만들고 싶었다.

{
  "success": false,
  "message": "존재하지 않는 게시판입니다.",
  "data": {
    "code": "404",
    "errors": [
      {
        "field": "BOARD_NOT_FOUND",
        "reason": "존재하지 않는 게시판입니다."
      }
    ]
  }
}

[Devlog] RESTful하게 API를 설계하려고 한 이유

처음 API를 만들 때는 URL을 거의 감으로 지었다.

api/auth 이런식

근데 API가 늘어나면 문제가 생긴다. URL에 동사가 계속 붙고, 같은 자원을 다루는데도 규칙이 흔들린다. 그래서 CoreBoard에서는 최대한 RESTful하게 API를 설계하려고 했다.

RESTful을 지키려 한 이유

RESTful하게 설계한다는 건 거창하게 말하면 어렵지만, 내가 이해한 기준은 이거였다.

URL은 자원을 표현하고, 행위는 HTTP Method로 표현한다.

GET /boards          게시판 목록 조회
GET /boards/{id}     게시판 단건 조회
POST /admin/boards   게시판 생성
PATCH /admin/boards/{id} 게시판 수정
DELETE /admin/boards/{id} 게시판 삭제

공식문서에서 본 기준

HTTP 공식 명세인 RFC 9110에서는 멱등성에 대해 설명한다.

A request method is considered "idempotent" if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request.
Of the request methods defined by this specification, PUT, DELETE, and safe request methods are idempotent.

한국어로 풀면, 같은 요청을 여러 번 보내도 서버에 남는 결과가 한 번 보낸 것과 같으면 멱등하다는 뜻이다.

이게 API 설계에서 중요했다.

예를 들어 DELETE /boards/{id}는 여러 번 호출되어도 그 게시판이 삭제된 상태라는 결과는 같다. 반대로 POST /boards는 호출할 때마다 새 게시판이 생길 수 있으니 멱등하다고 보기 어렵다.

즉, HTTP Method는 단순한 장식이 아니라 클라이언트와 서버가 요청의 의미를 약속하는 방식이다.

CoreBoard에서 RESTful을 지키며 고민한 부분

CoreBoard에서는 관리자와 일반 사용자의 행위가 섞여 있다. 예를 들어 게시판 생성은 일반 사용자가 하는 일이 아니다.

그래서 단순히 POST /boards로 둘 수도 있었지만, CoreBoard에서는 관리자 기능이라는 의미를 드러내기 위해 아래처럼 잡았다.

POST /admin/boards
PATCH /admin/boards/{boardId}
DELETE /admin/boards/{boardId}

반면 일반 사용자가 게시글을 조회하거나 작성하는 흐름은 게시판 자원과 게시글 자원의 관계를 드러내려고 했다.

GET /boards/{boardId}/posts
POST /boards/{boardId}/posts
GET /posts/{postId}

이 요청은 어떤 자원에 대한 요청인가?
이 요청은 조회인가, 생성인가, 수정인가, 삭제인가?
이 요청은 관리자 권한이 필요한가?

RESTful이 항상 정답은 아니었다

RESTful을 절대 규칙으로 보지는 않았다 물론 RESTful하게 만들겠다고 모든 API를 억지로 끼워 맞추면 오히려 이상해질 수 있다.
특히 인증 API는 애매하다.
회원가입은 보통 /signup, 로그인은 /login처럼 행위 중심으로 많이 표현한다.

실제 서비스에서도 /auth/login 같은 URL은 흔하게 볼 수 있다.

하지만 CoreBoard에서는 이 부분도 가능하면 자원 중심으로 해석해보려고 했다.

회원가입은 가입한다는 행위보다 사용자 자원을 생성한다는 관점으로 보고 POST /users로 설계했다.
로그인도 로그인한다는 행위보다 인증 정보를 검증한 뒤 토큰 자원을 발급받는다는 관점으로 보고 POST /token으로 설계했다.

즉, CoreBoard에서는 /signup, /login처럼 동사를 URL에 직접 넣기보다, 서버에서 생성되거나 발급되는 자원을 기준으로 API를 표현하려고 했다.

인증 API처럼 행위성이 강한 요청은 언제든지 실무 관례와 팀 컨벤션에 따라 다르게 설계될 수 있다.

다만 CoreBoard는 RESTful 설계를 연습하는 프로젝트였기 때문에, 가능한 범위 안에서 URL은 자원, 행위는 HTTP Method라는 기준을 끝까지 적용해보려고 했다.

API를 사용하는 사람 입장에서 덜 헷갈리게 만들고, HTTP Method의 의미와 URL의 역할을 코드와 문서에 맞추기 위해서였다.

[Devlog] JWT를 선택한 이유

JWT는 JSON Web Token의 약자다.

공식 RFC 7519에서는 JWT를

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties.

한국어로 풀면, 두 주체 사이에서 사용자 정보 같은 claim을 전달하기 위한 작고 URL-safe한 토큰 형식이라는 뜻이다.

CoreBoard에서는 JWT 안에 이런 정보를 담았다.

userId
username
role
type(access / refresh)

즉, 서버는 요청이 들어올 때 토큰을 읽고, 이 사용자가 누구인지, 어떤 권한인지, 이 토큰이 access token인지 refresh token인지 판단할 수 있다.

왜 세션이 아니라 JWT였는가?

세션 방식은 서버가 로그인 상태를 저장한다. 사용자가 로그인하면 서버는 세션 저장소에 로그인 정보를 저장하고, 클라이언트는 세션 ID를 쿠키로 들고 다닌다.

반면 JWT 방식은 토큰 자체에 필요한 정보를 담고, 서버는 요청이 들어올 때마다 토큰을 검증한다. CoreBoard에서 JWT를 선택한 이유는 단순히 Spring Security를 사용하지 않았기 때문이 아니다.

Spring Security를 사용하더라도 JWT 기반 인증 구조는 충분히 선택할 수 있다. 내가 JWT를 선택한 이유는 CoreBoard의 인증 방식을 서버 세션 기반이 아니라 토큰 기반으로 설계하고 싶었기 때문이다. 게시판 API는 로그인 이후 여러 요청에서 사용자를 식별하고 권한을 확인해야 한다.

이때 JWT를 사용하면 access token 안에 사용자 식별자와 권한 정보를 담고, 서버는 요청마다 토큰을 검증해서 누가 요청했는지, 어떤 권한을 가진 사용자인지를 판단할 수 있다.

CoreBoard에서 JWT를 선택한 이유

CoreBoard에서 JWT를 선택한 이유는 세 가지였다.

서버가 세션 상태를 직접 들고 있지 않는 토큰 기반 인증 구조를 적용해보고 싶었다.
access token / refresh token 구조를 분리해서 인증 흐름을 설계하고 싶었다.
role claim을 통해 인증 이후 인가 흐름까지 연결하고 싶었다.

여기서 중요한 건 JWT 자체가 무조건 세션보다 좋다는 뜻이 아니다.

세션은 서버에서 로그인 상태를 통제하기 쉽고, JWT는 요청마다 토큰을 검증하면서 서버의 세션 의존도를 줄일 수 있다. 대신 JWT는 한 번 발급된 토큰을 어떻게 만료시키고, 어디에 저장하고, 탈취 위험을 어떻게 줄일지 같이 고민해야 한다.

즉, CoreBoard에서 JWT를 선택한 건 요즘 많이 쓰니까가 아니라, 인증 상태를 서버 세션에 저장하는 방식과 토큰으로 증명하는 방식의 차이를 직접 설계해보기 위한 선택이었다.

인증 방식 후보군

1. Session 기반 인증

Session 기반 인증은 서버가 로그인 상태를 저장하는 방식이다.

사용자가 로그인하면 서버는 세션 저장소에 사용자 정보를 저장하고, 클라이언트는 세션 ID를 쿠키로 들고 다닌다.

이후 요청이 들어오면 서버는 세션 ID를 기준으로 저장된 로그인 정보를 찾는다.

Client → Session ID 전달
Server → Session Store에서 사용자 정보 조회

이 방식의 장점은 서버가 로그인 상태를 직접 관리할 수 있다는 점이다.

예를 들어 특정 사용자를 강제로 로그아웃시키거나, 세션을 즉시 만료시키는 처리가 비교적 명확하다.

다만 서버가 로그인 상태를 저장해야 하므로, 서버 인스턴스가 여러 대로 늘어날 경우 세션 저장소를 어떻게 공유할지 고민해야 한다.

2. JWT 기반 인증

JWT 기반 인증은 서버가 로그인 상태를 세션 저장소에 저장하지 않고, 클라이언트가 토큰을 가지고 요청하는 방식이다.

사용자가 로그인하면 서버는 사용자 식별자와 권한 같은 정보를 담아 토큰을 발급한다.

이후 클라이언트는 API 요청마다 토큰을 함께 보낸다.

서버는 요청이 들어올 때마다 토큰의 서명과 만료 시간을 검증하고, 토큰 안의 정보를 읽어 사용자를 식별한다.

Client → JWT 전달
Server → JWT 검증 후 사용자 정보 확인

이 방식의 장점은 서버가 매 요청마다 세션 저장소를 조회하지 않아도 된다는 점이다.

또 access token 안에 userId, role 같은 정보를 담으면 요청마다 사용자를 식별하고 권한을 판단할 수 있다.

다만 토큰이 탈취되면 만료 전까지 악용될 수 있으므로, 만료 시간과 refresh token 저장 방식, 재발급 정책을 함께 설계해야 한다.

비교	Session 기반 인증	JWT 기반 인증
개념	서버가 로그인 상태를 저장하고, 클라이언트는 세션 ID를 쿠키로 전달하는 방식	서버가 토큰을 발급하고, 클라이언트가 요청마다 JWT를 전달하는 방식
상태 저장 위치	서버가 세션 저장소에 로그인 상태를 저장한다.	클라이언트가 토큰을 보관하고, 서버는 요청마다 토큰을 검증한다.
요청 처리 방식	요청이 들어오면 서버가 세션 ID로 세션 저장소에서 사용자 정보를 조회한다.	요청이 들어오면 서버가 JWT의 서명, 만료 시간, claim을 검증한다.
장점	서버가 로그인 상태를 직접 관리할 수 있다. 특정 사용자의 세션 만료나 강제 로그아웃 처리가 비교적 명확하다.	서버가 매 요청마다 세션 저장소를 조회하지 않아도 된다. 토큰 안에 userId, role을 담아 인증과 인가 흐름을 연결하기 쉽다.
단점	서버가 세션 상태를 저장해야 한다. 서버가 여러 대로 늘어나면 세션 저장소 공유 문제가 생긴다.	한 번 발급된 토큰은 만료 전까지 유효하다. 토큰 무효화가 세션보다 까다롭고, 토큰 크기가 커질 수 있다.
주의점	세션 ID가 탈취되면 해당 세션으로 요청할 수 있다. 세션 저장소 장애가 인증 장애로 이어질 수 있다.	토큰이 탈취되면 만료 전까지 악용될 수 있다. 민감한 정보를 토큰에 넣으면 노출 위험이 있다.
해결방안	쿠키에 httpOnly, secure, sameSite를 적용한다. 서버 확장 시 Redis 같은 외부 세션 저장소를 사용해 세션을 공유한다.	access token은 짧게 가져가고 refresh token으로 재발급한다. refresh token은 쿠키에 저장하면서 httpOnly, secure, sameSite를 고려한다. 필요하면 refresh token을 DB/Redis에 저장해 로그아웃과 재발급 제어를 보완한다.
CoreBoard 선택 관점	서버가 로그인 상태를 직접 들고 있는 구조라서, 이번 CoreBoard의 토큰 기반 인증 설계 방향과는 다소 거리가 있었다.	요청마다 토큰을 검증해 사용자 식별과 권한 확인을 연결할 수 있고, access token / refresh token 구조를 설계하기에 적합하다고 판단했다.

[Devlog] 왜 토큰 검증을 Controller가 아니라 Interceptor에서 처리했는가?

CoreBoard에서는 Spring Security를 사용하지 않았다.

따라서 Spring Security가 제공하는 Filter Chain 기반 인증/인가 흐름을 그대로 사용할 수 없었다. 하지만 JWT를 사용하는 이상, 요청마다 토큰을 검증하는 과정은 필요했다. 처음에는 Controller에서 Authorization 헤더를 읽고 토큰을 검증하는 방식도 생각할 수 있었다.

@GetMapping("/posts")
public ResponseEntity<?> getPosts(@RequestHeader("Authorization") String token) {
    jwtUtil.validate(token);
    ...
}

하지만 이 방식은 금방 문제가 생긴다. 인증이 필요한 API마다 아래 로직이 반복된다.

Authorization 헤더 확인
Bearer 토큰 파싱
토큰 만료 여부 확인
토큰 서명 검증
사용자 식별 정보 추출
권한 확인

이 로직이 Controller마다 들어가면 Controller는 더 이상 요청과 응답을 처리하는 역할에만 집중하지 못한다. 그래서 CoreBoard에서는 JWT 검증을 Controller 앞단으로 분리했다.

Spring MVC에서 Interceptor는 Controller가 실행되기 전에 요청을 가로챌 수 있다.

callback before the actual handler is run that returns a boolean.

공식문서에서도 preHandle()은 실제 handler가 실행되기 전에 호출되고, false를 반환하면 이후 실행 체인을 중단해 handler가 호출되지 않는다고 설명한다. 쉽게 말하면, Controller에 들어가기 전에 요청을 검사하고 막을 수 있는 위치라는 뜻이다.

CoreBoard에서는 이 특성을 이용해 인증 검증을 Interceptor에 배치했다.

Client
 → Interceptor에서 Authorization 헤더 확인
 → JWT 검증
 → 인증 실패 시 401/403 응답
 → 인증 성공 시 Controller 진입
 → Service 호출

이 구조로 두면 인증 실패 요청은 비즈니스 로직까지 들어가지 않는다.

Controller는 요청 DTO를 받고 Service를 호출하는 역할에 집중할 수 있고, Service는 게시글 생성, 수정, 삭제 같은 비즈니스 규칙에 집중할 수 있다.

즉, Interceptor를 선택한 이유는,

CoreBoard에서는 인증 검증이 여러 API에 반복되는 공통 관심사였고, Controller 진입 전에 처리하는 것이 레이어 책임을 더 명확하게 나눈다고 판단했기 때문이다.

Spring Security Filter와 CoreBoard Interceptor의 차이

비교	Spring Security Filter	ChainCoreBoard Interceptor
위치	Servlet Filter 계층	Spring MVC HandlerMapping 이후, Controller 실행 전
역할	인증/인가, 세션, CSRF, 보안 컨텍스트 등 전체 보안 흐름 처리	CoreBoard에서 JWT 헤더 확인과 토큰 검증을 직접 처리
적용 이유	Spring Security가 제공하는 표준 보안 구조	Spring Security 없이 인증 흐름을 직접 구현하기 위한 선택
주의점	설정과 개념이 복잡하지만 보안 기능이 풍부함	직접 구현한 만큼 예외 처리, 우회 경로, 권한 체크를 스스로 관리해야 함

CoreBoard에서 Interceptor를 사용한 이유는 JWT를 Controller마다 검증하지 않기 위해서였다. Spring Security가 있었다면 보통 Filter Chain 기반으로 인증 흐름을 구성했을 것이다.

하지만 CoreBoard는 Spring Security 없이 인증 구조를 직접 구현했기 때문에, Spring MVC에서 Controller 실행 전에 공통 처리를 할 수 있는 Interceptor를 선택했다.

결국 이 선택의 핵심은 Security가 없어서 어쩔 수 없이 Interceptor를 썼다가 아니라, 인증 검증이라는 공통 책임을 Controller 밖으로 분리하고, 비즈니스 로직 진입 전에 요청을 걸러내기 위해 Interceptor를 사용했다는 점이다.

[Devlog] Testcontainers를 사용한 이유

테스트를 작성하면서 제일 찝찝했던 부분은 DB였다. 처음에는 H2를 쓰면 되는 줄 알았다. 빠르고, 가볍고, 설정도 쉽다.

근데 문제는 CoreBoard의 실제 DB가 MySQL이라는 점이었다. 테스트에서는 H2로 통과했는데 실제 MySQL에서는 다르게 동작할 수 있다.

왜 H2만으로 부족하다고 느꼈는가?

H2는 테스트하기 좋다. 하지만 실제 운영 DB와 완전히 같지는 않다.

예를 들어 SQL 문법, 인덱스 동작, 제약조건, 트랜잭션 처리, 타입 처리에서 차이가 날 수 있다.

CoreBoard는 메서드 하나가 호출되는지만 보는 프로젝트가 아니었다. DB 제약조건, JPA 동작, 트랜잭션 흐름까지 실제와 가깝게 확인하고 싶었다.

그래서 Testcontainers를 사용했다.

공식문서에서 본 기준

Testcontainers for Java is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.

한국어로 풀면, H2는 서버 모드나 임베디드 모드로 사용할 수 있고, 디스크 기반 DB 또는 인메모리 DB로 사용할 수 있다는 뜻이다.

Testcontainers 공식문서는 Testcontainers를 JUnit tests를 지원하고, Docker container에서 실행 가능한 데이터베이스나 메시지 브로커 같은 의존성을 가볍고 일회용으로 제공하는 Java 라이브러리라고 설명한다.
테스트할 때 진짜 MySQL 같은 외부 의존성을 Docker 컨테이너로 띄웠다가 테스트가 끝나면 버릴 수 있게 해주는 도구라는 뜻이다.

가짜 DB가 아니라 실제 MySQL에 가까운 환경에서 테스트하고 싶다.
하지만 매번 수동으로 DB를 만들고 지우고 싶지는 않다.

CoreBoard에서 Testcontainers를 쓴 이유

CoreBoard에서 Testcontainers를 쓴 이유는 세 가지였다.

 실제 MySQL 기준으로 JPA 동작을 검증하기 위해 
 테스트마다 깨끗한 DB 상태를 만들기 위해 
 로컬/CI 환경에서도 같은 방식으로 테스트하기 위해

특히 Testcontainers를 쓰면 내 컴퓨터에서는 됐는데 CI에서는 안 됨 같은 문제를 줄일 수 있다. 테스트가 직접 MySQL 컨테이너를 띄우기 때문에, 테스트 환경이 코드에 가까워진다.

단점

물론 Testcontainers가 무조건 좋은 건 아니다.

H2보다 느리다.
Docker가 필요하다.
CI 환경에서도 Docker 실행 조건을 신경 써야 한다.

그래서 모든 테스트를 Testcontainers로 돌리는 건 부담일 수 있다. CoreBoard에서는 테스트 성격을 나눠서 생각했다.

단순 계산/분기 → 단위 테스트
Spring MVC 요청/응답 → Controller 테스트
DB/JPA/트랜잭션 검증 → Testcontainers 기반 통합 테스트

즉 Testcontainers는 모든 테스트를 대체하는 도구가 아니라, 실제 DB 검증이 필요한 곳에 사용하는 도구라고 봤다.

기준

비교	H2	Testcontainers
간략 개념	Java 기반의 가벼운 관계형 데이터베이스다. 테스트에서는 주로 인메모리 DB로 사용한다.	테스트 실행 시 Docker 컨테이너로 실제 DB를 띄워 사용하는 방식이다.
실행 방식	애플리케이션 안에서 빠르게 실행할 수 있다. 별도 DB 서버를 띄우지 않아도 된다.	테스트가 시작될 때 MySQL 같은 실제 DB 컨테이너를 띄우고, 테스트가 끝나면 제거한다.
장점	빠르고 설정이 간단하다. 단위 테스트나 간단한 Repository 테스트에 부담이 적다.	실제 운영 DB와 같은 종류의 DB로 테스트할 수 있다. MySQL 문법, 제약조건, 트랜잭션 동작을 더 현실적으로 검증할 수 있다.
단점	실제 운영 DB가 MySQL이라면 H2와 문법이나 동작 차이가 생길 수 있다. 테스트에서는 통과했는데 실제 MySQL에서는 실패할 수 있다.	H2보다 느리다. Docker가 필요하다. CI 환경에서도 Docker 실행 조건을 신경 써야 한다.
주의점	H2 테스트 통과가 실제 MySQL 통과를 보장하지 않는다. 특히 SQL 방언, 타입, 제약조건, 인덱스 동작 차이를 조심해야 한다.	테스트 속도가 느려질 수 있으므로 모든 테스트에 무조건 적용하면 부담이 커진다.
해결방안	단순한 단위 테스트나 빠른 검증에는 H2를 사용할 수 있지만, DB 호환성이 중요한 테스트는 실제 DB 기반으로 보완한다.	DB/JPA/트랜잭션/제약조건 검증이 필요한 통합 테스트에 집중해서 사용한다. 단순 로직 테스트는 Mockito 같은 단위 테스트로 분리한다.
CoreBoard 선택 관점	빠르다는 장점은 있지만, CoreBoard의 실제 DB가 MySQL이므로 DB 차이로 인한 테스트 신뢰도 문제가 남는다고 봤다.	실제 MySQL 컨테이너로 테스트할 수 있어 CoreBoard의 JPA, 제약조건, 트랜잭션 흐름을 더 현실적으로 검증할 수 있다고 판단했다.

[스케줄링]Spring Scheduler로 임시 첨부파일 정리하기

HS0601 — Sat, 25 Apr 2026 12:04:26 +0900

Spring 스케줄링

https://docs.spring.io/spring-framework/reference/integration/scheduling.html

Task Execution and Scheduling :: Spring Framework

All Spring cron expressions have to conform to the same format, whether you are using them in @Scheduled annotations, task:scheduled-tasks elements, or someplace else. A well-formed cron expression, such as * * * * * *, consists of six space-separated time

docs.spring.io

Spring 스케줄링은 쉽게 말해 서버가 켜져있는 동안, 내가 정한 시간마다 특정 메서드를 자동 실행하게 만드는 기능이다

Spring아, 이 프로젝트에서 @Scheduled붙은 메서드를 찾아서 자동 실행해줘 -> @EnableScheduling

@Configuration
@EnableScheduling
public class SchedulingConfig {
}

공식문서에서는 "To enable support for @Scheduled … add @EnableScheduling to one of your @Configuration classes."라고 나와있다 즉 @Scheduled 기능을 사용하려면 설정 크랠스 중 하나에 @EnableScheduling을 추가하라는 말이다

@Configuration : Spring 설정 파일 역할을 하는 클래스라는 표시

@EnableScheduling : Spring에게 스케줄링 기능 켜라라고 알려주는 어노테이션 - 스위치

이 메서드를 매일 새벽 3시에 자동 실행해줘 -> @Scheduled

@Component
public class AttachmentCleanupScheduler {

    @Scheduled(cron = "0 0 3 * * *")
    public void deleteOldTempAttachments() {
        // 오래된 임시 첨부파일 삭제
    }
}

공식문서에서는 "You can add the @Scheduled annotation to a method, along with trigger metadata."라고 나와있다

즉, 메서드에 @Scheduled를 붙이고 언제 실행할지에 대한 실행 조건도 같이 적을 수 있다는 말이다 여기서 중요한 건 컨트롤러처럼 사용자의 요청이 들어와야 실행되는 게 아니라는 것.

서버 켜짐
→ 정해진 시간이 됨
→ Spring이 알아서 메서드 실행

trigger metadata : 언제 실행할지 알려주는 초기값 (cron, fixedDelay, fixedRate)

아래 메서드는 5초마다 실행해줘 -> fixedDelay

@Scheduled(fixedDelay = 5000)
public void doSomething() {
    // something that should run periodically
}

공식문서에서는 이 메서드가 이렇게 동작한다고 설명하고 있다 "the period is measured from the completion time of each preceding invocation." 다음 실행까지의 시간은 이전 실행이 끝난 시점부터 계산된다는 말이다

예를들면

12:00:00 작업 시작
12:00:03 작업 끝남
fixedDelay = 5초
12:00:08 다음 작업 시작

Spring 스케줄링의 기본 선택지

1. fixedDelay
2. fixedRate
3. cron
+ initialDelay

1. fixedDelay

https://docs.spring.io/spring-framework/docs/4.2.7.RELEASE/spring-framework-reference/html/scheduling.html

33. Task Execution and Scheduling

In addition to the TaskExecutor abstraction, Spring 3.0 introduces a TaskScheduler with a variety of methods for scheduling tasks to run at some point in the future. The simplest method is the one named 'schedule' that takes a Runnable and Date only. That

docs.spring.io

fixedDelay는 이전 작업이 끝난 뒤 정해진 시간만큼 기다렸다가 다음 작업을 실행하는 방식이다 위에서 다룬 것처럼, 공식문서에서는 " The fixedDelay attribute … makes sure that there is a delay of five seconds between the finish time of an execution and the start time of the next execution."라고 설명하고 있다 fixedDelay는 한 번 실행이 끝난 시점과 다음 실행이 시작되는 시점 사이에 5초 간격으로 보장한다는 말이다

@Scheduled(fixedDelay = 5000)
public void cleanup() {
    // 작업 실행
}

12:00:00 작업 시작
12:00:03 작업 끝
5초 기다림
12:00:08 다음 작업 시작

장점

이전 작업이 끝난 뒤 다음 작업이 시작되는 거라 안전하다 작업 시간이 길어져도 끝나고 나서 다시 시작이라는 흐름이 덜 꼬이기 때문이다

단점

정확히 매 5초 매 1분 같은 고정시각을 보장하지는 않는다

작업 시간이 길어지면 전체 실행 간격도 밀린다

작업 3초 + 대기 5초 = 다음 실행은 8초 뒤
작업 10초 + 대기 5초 = 다음 실행은 15초 뒤

언제 사용하는 게 적절할까? 했을 땐 외부 API동기화, 파일 정리, DB정ㄹ, 메일 재시도, 로그 정리 등에 적절해 보인다

2. fixedRate

fixedRate는 작업 시작 시각을 기준으로 일정 간격마다 실행하려는 방식이다

@Scheduled(fixedRate = 5000)
public void collectMetrics() {
    // 작업 실행
}

공식문서에서 fixedRate도 주기 실행 속석으로 제시되고 있다 Spring @Scheduled javadoc은 반복 작업에서 cron, fixedDelay, fixedRate 중 하나를 지정한다고 설명한다

12:00:00 작업 시작
12:00:05 다음 작업 시작 예정
12:00:10 다음 작업 시작 예정

즉, 시작 기준으로 5초마다라고 생각하면 이해하기 쉽다

장점

일정한 주기로 계속 실행하려는 작업에 좋다 예를들어 10초마다 현재 서버 상태를 수집하기 같은 건 시작 간격이 중요하다

단점

작업이 오래 걸리면 밀리거나 겹침 문제가 생길 수 있다

Spring 공식문서는 같은 메서드에 여러 스케줄 선언이 있으면 독립적으로 처리되고 서로 겹쳐 병렬 실행되거나 바로 이어 실행될 수 있으니 겹치지 않게 주의하라고 말하고 있다

"such co-located schedules may overlap and execute multiple times in parallel or in immediate succession"

언제 사용하는 게 적절할까? 했을 땐 10초마다 메트릭 수집, 1분마다 상태 체크, 일정주기로 캐시 갱신 시도 등에 적절해 보인다

3. cron

몇 초, 몇 분, 몇 시, 몇 일, 몇 월, 무슨 요일에 실행할지를 식으로 정리하는 방식이다

@Scheduled(cron = "0 0 3 * * *")
public void cleanupOldTempFiles() {
    // 매일 새벽 3시 실행
}

" A well-formed cron expression, such as * * * * * *, consists of six space-separated time and date fields, each with its own range of valid values. " Spring 공식문서는 cron 표현식이 정해진 형식을 따라야 한다고 설명하고 있다

cron 표현식은 6개의 칸으로 표현된다는 말이다

초 분 시 일 월 요일
0  0  3  *  *  * -> 매일 03:00:00

장점

사람이 이해하기 쉬운 운영 시간 기준으로 실행할 수 있다

예를들어 매일 새벽3시, 매주 월요일 오전 9시, 매달 1일 0시, 평일 18시.

이런 식의 달력 기준 작업에 좋다

단점

표현식이 익숙하지 않으면 헷갈린다

0 0 3 * * *

처음보면 뭔 소린지 모른다

두번째로, 작업이 오래 걸릴 경우 다음 실행 시점과 겹칠 수 있는지 고려해야 한다 특히 서버가 여러대면 중요해진다

서버 1대 → 새벽 3시에 1번 실행
서버 2대 → 각 서버에서 새벽 3시에 실행될 수 있음

EC2 한 대면 단순하지만, 나중에 서버가 여러 대가 되면 중복 실행 방지도 고민해야 한다

언제 사용하는 게 적절할까? 라고 했을 땐 정해진 시각에 실행해야 하는 운영 작업인 경우에 적절해 보인다

4. initialDelay

initialDelay는 서버 켜진 뒤 바로 실행하지 말고 처음 실행만 조금 늦추는 옵션이다

@Scheduled(initialDelay = 10000, fixedDelay = 60000)
public void cleanup() {
    // 서버 시작 10초 후 첫 실행
    // 이후 이전 작업 종료 후 60초마다 실행
}

공식문서 javadoc은 initialDelay를 이렇게 설명하고 있다

"Number of units of time to delay before the first execution" 첫번째 실행 전에 얼마나 기다릴지 정하는 값이라는 뜻이다

https://github.com/spring-projects/spring-framework/blob/main/spring-

context/src/main/java/org/springframework/scheduling/annotation/Scheduled.java

spring-framework/spring-context/src/main/java/org/springframework/scheduling/annotation/Scheduled.java at main · spring-project

Spring Framework. Contribute to spring-projects/spring-framework development by creating an account on GitHub.

github.com

장점

서버 시작 직후 무거운 작업이 바로 도는 걸 막을 수 있다

서버가 막 켜져있을 때는 애플리케이션 초기화, DB 연결, 캐시 준비 등으로 바쁠 수 있따 그때 스케줄러까지 바로 돌면 부담이 될 수 있다

단점

단독으로 반복 주기를 정하는 핵심 방식은 아니다 대부분 fixedDelay나 fixedRate와 같이 쓴다

방식	기준	장점	단점	어울리는 작업
fixedDelay	이전 작업 종료 후	이전 작업 끝난 뒤 실행이라 안전함	정확한 시각 실행은 아님	파일 정리, 재시도, DB 정리
fixedRate	이전 작업 시작 후	일정 주기로 실행하려 할 때 좋음	작업이 오래 걸리면 밀림/겹침 고려	메트릭 수집, 상태 체크
cron	달력/시각	매일 3시 같은 운영 시간 설정 가능	표현식이 헷갈리고 중복 실행 고려 필요	새벽 정리, 통계, 정산
initialDelay	첫 실행 전	서버 시작 직후 부담 방지	반복 방식 자체는 아님	fixedDelay, fixedRate 보조

[Devlog] Spring Profile, 환경마다 yml을 분리한 이유

HS0601 — Mon, 23 Mar 2026 13:45:20 +0900

https://winwin0219.tistory.com/300

[회고] CoreBoard 프로젝트, 왜 만들었는가

winwin0219.tistory.com

처음에 application.yml 하나만 사용했었다. 근데 로컬 개발할 때랑 EC2 올릴 때 DB 주소가 다르고 테스트 돌릴 때 실제 DB 건드리면 안되고 신경을 써야 한다는 것을 알았다.

로컬에서는 DB가 내 컴퓨터 안에 있으니까 localhost로 접속하지만, EC2에 올리면 앱이 서버 위에서 돌아가기 때문에 localhost는 EC2 자기 자신을 가리켜서 DB를 못 찾는다. 즉, 실행되는 환경이 달라지면 DB 주소도 달라질 수밖에 없다.

스프링 프로필이란?

스프링 프로필은 환경별로 세팅해놓은 yml 또는 properties를 일컫는다.

CoreBoard 왜 이렇게 나누었는가?

application.yml          ← 공통 (앱 이름만)
application-local.yml    ← 로컬 개발
application-dev.yml      ← 개발 서버
application-prod.yml     ← 운영 (EC2)
application-test.yml     ← 테스트

바로 본론부터 말해보자면, 시크릿 키가 유출되면 대형사고가 발생할 수 있기 때문에 환경변수를 .env에 담아 깃이그노어에 설정해놓는 게 국룰이다.

그러나 스프링 프로필에 대해 알게되면 단순하게만 생각하던 것들이 정말 얕은 지식이었구나를 느낀다.

1. application.yml

공통으로 들어가는 것들 모음이다.

2. application-local.yml

로컬 즉, 개발자가 개발하는 환경을 의미하는데 이곳에서는 협업을 진행해야 해서 시크릿키를 공유해야 한다.

CoreBoard는 이런 상황을 가정하여 프로필을 설정했다.

회사망에서만 개발 가능
깃허브 레포는 private

그래서 해당 로컬 야물 파일에는 jwt와 aes등 키가 들어있지만 임시키고, prod에서 실제 쓰이는 키와 다르다.

3. application-dev.yml

dev는 CI/CD 파이프라인에서 자동 배포 후 동작 확인용 환경이다. 운영(prod)처럼 민감한 환경변수 처리가 필요하진 않지만, 운영에 올리기 전 검증하는 역할을 한다.

show_sql은 끄고, ddl-auto는 validate로 설정했다 — 스키마를 자동으로 건드리지 않겠다는 뜻.

4. application-prod.yml

핵심은 prod 야물이다. 절대 유출되어선 안 되기 때문에 환경변수로 사용하고 있고 ec2환경에서 따로 관리되고 있다. 그래서 CoreBoard는 클론을 받더라도 .env를 할 필요가 없다.

5. application-test.yml

테스트 전용 프로필이다 핵심은 두가지.

ddl-auto : create-drop
테스트가 실제 실행될 때 스키마를 새로 만들고, 테스트가 끝나면 전부 날린다. 실제 DB를 건드리지 않고 매 테스트마다 깨끗한 상태로 시작할 수 있다.
bcrypt strength : 4
기본값은 10인데 숫자가 클수록 해싱에 걸리는 시간이 길어진다. 테스트에서 보안보다 속도가 우선이기 때문에 최솟값인 4로 설정했다.

[Devlog] 코드 짜기 전에 기반부터 — 공통 응답 포맷 설계

HS0601 — Wed, 18 Mar 2026 14:32:57 +0900

https://winwin0219.tistory.com/300

[회고] CoreBoard 프로젝트, 왜 만들었는가

winwin0219.tistory.com

GlobalExceptionHandler 와 ApiResponse(공통 응답 포맷)에 대해 말해보려고 한다.

이 글에서 다루는 것

왜 공통 응답 포맷이 필요한가?
ApiRespones 설계 - success, message, data (제네릭)
왜 GlobalExceptionHandler가 필요한가?
- @RestControllerAdvice + @ExceptionHandler 동작원리
에러가 터졌을 때 ApiResponse로 어떻게 감싸서 내려보내는가?

1) 왜 공통 응답 포맷이 필요한가?

Momentix에서 ApiResponse는 전혀 생각하지도 못했다. 백엔드 개발자는 서버와 데이터베이스 그리고 프론트엔드와 소통해야 한다. 근데 실제로 어떻게 소통해야 하는지, 프론트엔드에게 예의를 갖추려면 어떤 방식으로 해야 하는지 등에 대해서 부캠에서 알려주진 않는다.
사용자 화면에 어떤 아이템을 렌더링할 것인지 직접적으로 관여하는 사람은 백엔드가 아니라 프론트엔드 개발자다. 그래서 우리는 프론트엔드 개발자가 이해하기 좋게 그리고 렌더링하기 편하게 공통응답으로 보내줘야 함을 깨달았다.

2) ApiRespones 설계 - success, message, data (제네릭)

{
  "success": false,
  "message": "제목은 필수입니다.",
  "data": {
    "code": "400",
    "errors": {
      "field": "title",
      "reason": "제목은 필수입니다."
    }
  }
}

위 response는 실제 CoreBoard 깃허브 레포에도 나와있는 응답 포맷이다.

success는 boolean으로 프론트가 분기처리하기 편하게, data는 제네릭으로 어떤 타입이든 담을 수 있게 설계했다.
이게 무슨 말이냐면, 예를들어 auth와 board 응답을 보면 아래와 같다

// 게시글 조회 응답
public class ApiResponse {
    private boolean success;
    private String message;
    private Board data;  // Board 타입 고정
}

// 유저 조회 응답
public class ApiResponse {
    private boolean success;
    private String message;
    private User data;  // User 타입 고정
}

즉, 기능마다 ApiResponse 클래스를 새로 만들어야 하는데 이러면 완전 비효율적이다 그래서 제네릭을 사용하게되면 클래스 하나로 어떤 타입이든 다 담을 수 있게 된다.

ApiResponse<Board> boardResponse = new ApiResponse<>(true, "조회 성공", board);
ApiResponse<User> userResponse = new ApiResponse<>(true, "조회 성공", user);
ApiResponse<List<Board>> listResponse = new ApiResponse<>(true, "조회 성공", boards);

3) 왜 GlobalExceptionHandler가 필요한가?

간단하다. CoreBoard만 해도 예외처리된 게 엄청 많은데 예외핸들러가 없게되면 try-catch문이 수백개가 될 수도 있다. 이 경우 가독성 뿐만 아니라 관리도 쉽지 않게 된다.

다시 정리해보면,
1. 중복 코드 엄청 생김
2. 컨트롤러가 예외 처리 책임까지 떠안 게 되어 SRP 위반임

3-1) @RestControllerAdvice + @ExceptionHandler 동작원리

이때 내가 잘못 이해했던 부분이 Filter나 Interceptor처럼 앞단에서 가로채는 건 줄 알았는데 예외가 controller 밖으로 탈출한 후에 잡는 것이었다. 즉, 예외 발생 위치는 어디든 상관이 없다.

Controller 안에서 throw  ─┐
Service 안에서 throw     ─┤→ 아무도 안 잡으면 → Controller 밖 탈출
Repository 안에서 throw  ─┘        ↓
                          @RestControllerAdvice가 여기서 낚아챔

DispatcherServlet이 예외를 받으면 직접 처리하지 않고 ExceptionHandlerExceptionResolver한테 위임한다.
@RestControllerAdvice붙은 Bean을 뒤져서 터진 예외 타입과 일치하는 @ExceptionHandler 메서드를 찾아 실행한다.

4) 에러가 터졌을 때 ApiResponse로 어떻게 감싸서 내려보내는가?

먼저 CoreBoard의 예외 구조를 이해해야 한다. ErrorException이라는 추상 클래스가 있다.
status(HTTP 상태코드), code(숫자), message(메시지), errors(FieldError 목록)
이 네 가지를 들고 있는 공통 부모 클래스다.
그리고 도메인별로 이 클래스를 상속한 예외 클래스가 있다. auth쪽은 AuthErrorException, board쪽은 BoardErrorException이다.
직접적으로 throw하지 않고 enum을 하나 더 둔다. AuthErrorCode라는 enum인데 여기에 발생할 수 있는 에러 케이스를 전부 정의해놓는다.

UNAUTHORIZED(HttpStatus.UNAUTHORIZED, 401, "다시 로그인해 주세요.", ...)
NOT_FOUND(HttpStatus.NOT_FOUND, 404, "존재하지 않는 사용자입니다.", ...)

이렇게 하는 이유는 에러 메시지나 코드를 한 곳에서 관리하기 위해서다.
나중에 메시지 수정이 필요할 때 각 서비스 파일을 다 뒤질 필요 없이 AuthErrorCode만 수정하면 된다.

실제 throw하는 방식은 이렇다

throw new AuthErrorException(AuthErrorCode.NOT_FOUND);

그러면 GlobalExceptionHandler가 이 예외를 받아서 아래처럼 처리한다

@ExceptionHandler(ErrorException.class)
public ResponseEntity<ApiResponse<ErrorResponse>> handleFailException(ErrorException e) {
    ErrorResponse detail = new ErrorResponse(String.valueOf(e.getCode()), e.getErrors());
    return ResponseEntity
            .status(e.getStatus())
            .body(ApiResponse.fail(e.getMessage(), detail));
}

AuthErrorException은 ErrorException을 상속했기 때문에 @ExceptionHandler(ErrorException.class) 하나로 auth와 board 예외를 전부 잡을 수 있다. 최종적으로 프론트가 받는 응답은 이렇다

{
  "success": false,
  "message": "존재하지 않는 사용자입니다.",
  "data": {
    "code": "404",
    "errors": [
      {
        "field": "USER NOT FOUND",
        "reason": "존재하지 않는 사용자입니다."
      }
    ]
  }
}

[Devlog] SequenceDiagram

HS0601 — Wed, 18 Mar 2026 10:04:02 +0900

https://winwin0219.tistory.com/300

[회고] CoreBoard 프로젝트, 왜 만들었는가

winwin0219.tistory.com

이전 글에서 프로젝트의 등장배경에 대해 설명했으니 CoreBoard의 0단계였던 시퀀스다이어그램에 대해 쓰려고 한다.

시퀀스다이어그램은 부트캠프에서 알려주진 않는다. 그저 ERD와 API명세서 정도만 알려주는데 실제로 스웨거API가 다 해주기 때문에 시간을 많이 잡아먹는 API명세서는 삽질처럼 보인다 ^^

먼저, 구글링해보면 어려운 그림들만 등장하는데 사실 그렇게 어려운 것도 아닌데 이때는 좀 어렵게 느껴졌었다.

이때 내가 한 삽질

1. 시퀀스다이어그램이 왜 필요하지?라는 생각에 구현부터 하려고 했음

2. 근데 TDD에서 막힘. 말 그대로 Test Driven Development 즉, 테스트 먼저 한 다음에 green으로 맞추기

3. 그러면 TDD부터 해야겠네? 싶은데 이땐 테스트코드가 왜 중요한 지 몰라서 인증 인가부터 구현하려고 함

4. 근데 시큐리티 없이 하려니 아주 죽을 맛임

즉, 또 Momentix 때로 뇌가 움직이기 시작했다.

이렇게 며칠이 지나도록 기능구현 하나 못하자 더는 안 되겠다싶어서 제일 먼저 했던 게 시퀀스다이어그램의 개념과 필요성에 대해 알아보자였다.

먼저, 그림부터 보자.

내가 직접 그림

이해를 돕고자 아주 간략하게만 그려보면 이러한데, 사용자의 어떠한 행위로 인해 HTTP 요청이 발생되고 이를 Application 안에서 어떻게 동작하는지 시각적으로 그려놓은 docs다.

SequenceDiagram의 개념과 중요한 이유

1. 프론트엔드와 개발자의 소통

이게 무슨 말이냐면, 어떤 요청을 보내야 하고 어떤 응답이 오는지 한 눈에 보이고 API명세서 보다 흐름이 잘 보여서 협업 시 오해가 준다는 의미다

2. 테스트 코드 작성에 유리

흐름이 그러져있으면 여기서 이 값이 들어왔을 때, 어떤 결과 혹은 에러가 나와야 하는가 등, 촘촘하게 설계할 수 있다.

즉, 테스트 케이스 도출이 쉬워진다.

3. 레이어 역할 분리

이 로직이 controller 책임인지 service 책임인지를 코드 짜기 전에 고민할 수 있어서 좋다

즉, SRP 위반 최소화할 수 있다.

4. 복잡한 흐름의 사전 검증

특히 인증 / 인가처럼 레이어를 여러 개 거치는 흐름에서 머릿속으로만 생각해서 놓쳤던 케이스를 다이어그램 그리면서 발견하게 되어 좋다

개인적으로 특히 3번이 핵심인 것 같다. 왜냐면 그 당시 3번을 놓쳐서 레이어 위반을 엄청나게 했기 때문이다.

(예를들어, DB 조회가 필요없는 로직이 service에 있다거나)

시퀀스다이어그램 별 거 없다. 이 다이어그램 덕분에 어디부터 짜야하는지, 어떤 DTO가 있어야 하는지, TDD로 무엇을 검증해야 하는지 전부 알 수 있게 해준 반드시 필요한 docs다.

Momentix 때 하던 설계/기획은 미완성이라는 것을 더더욱 체감하게 되는 순간이었다.

[회고] CoreBoard 프로젝트, 왜 만들었는가

HS0601 — Wed, 18 Mar 2026 09:27:59 +0900

CoreBoard 기획했을 때로 거슬러 올라가자

때는 2025년 9월 말.

Momentix에서 느꼈던 부담감이 있었다. 부트캠프의 문제점이자 나의 약점(비전공자)이었던 동작은 하지만 얕은 이해도였다.

요즘 현업에서는 AI로 코드 짜는 게 당연해졌다지만, 배우는 입장에서 나는 그렇게 하고 싶지 않았다.

비전공자가 개발할 때 AI에 의지하여 복붙만 해서 쓴다라는 건 성장할 의지가 없다와 같은 말처럼 들렸다.

부트캠프에서 내가 기대한 바는 언어와 친해지기, 팀프로젝트, 개발자 인사이트를 얻는 것 이렇게 3개였는데 실제로는 데드라인에 맞춰 말도 안 되는 깊이를 모두 때려넣었어야 했다. 회사에 들어가게되면 일상이겠지만, 배우는 단계에서는 정말 최악이다.

부트캠프에서 하나만 파자라는 생각으로 임하긴 했는데 왜인지는 모르겠지만 인증 / 인가만 담당해왔다. 그러나 Spring Security에 대해 이해하지 못한 채 수료해버렸다. 근데 생각해보면, 신입에게 인증 / 인가 업무를 주진 않을텐데 ㅋㅋㅋㅋ 아마 그때, 내가 생각하기에 중요해 보이는 것 보다는 가장 어려워 보이는 걸 팠던 것 같다.

그래서 등장한 게 CoreBoard.

CoreBoard의 핵심 목표

1. Lombok이 숨겨주는 코드를 직접 작성하면서, 의존성 주입 구조와 결합도를 눈으로 확인하기 위해 Lombok 사용을 금할 것

2. SequenceDiagram이 왜 중요한지

3. Spring MVC 요청 처리 흐름( Spring MVC Request Lifecycle)에 대해 이해할 것

4. 레이어 계층 간 역할 분리 (SRP)

5. TDD의 역할

6. Spring Security가 해준 기능 이해하고 직접 구현(Security금지)해볼 것

7. 전체 조회(FindAll) 설계 시 페이지네이션 필요성과 성능 문제 직접 체감하기

8. CRUD 구현 시 AI 안 쓰고 구글링 & 공식문서 보고 할 것 (공부할 때만 AI 씀)

이걸 직접 구현해 보면서 느낀 점이 AI없이는 진짜 아무것도 못하는구나 싶었다. 진행하는 동안에 굉장히 쓴 피맛이었다.

너무너무 무지했고 광범위했고 .. 그래도 일을 벌렸으니 해야지 어떡해라는 마인드로 진지하게 임했다.

참고로 CoreBoard는 애정이 많은 프로젝트다

이 프로젝트를 만드는 동안에 일단 살고봐야 해서 블로그에 기록하는 시간을 제한했었는데, 기억을 되짚어보며 회고록을 끄적이기로 했다.

회고록에는 어떠한 문제를 마주했고 왜 이렇게 해결했는지 왜 고민했는지 그리고 약간의 한탄까지 ㅎㅎ 덧붙여서 할 예정이다

나중에 내가 이 글을 다시 보게될 경우까지 고려해서 작성 할 예정이다

[Momentix] Redis TTL 기반 이메일 인증 상태 관리 설계

HS0601 — Wed, 11 Feb 2026 10:49:32 +0900

왜 Redis를 썼는가?

Momentix에서 이메일 인증은 잠깐 유지되었다가 사라져야 하는 상태다

인증코드
인증 완료 토큰
재전송 쿨다운 상태

이 정보들은 영구 저장 대상이 아니다 일정 시간이 지나면 자동으로 만료되어야 한다 그래서 DB 대신 TTL이 있는 Redis를 사용했다

DB 대신 Redis를 선택한 이유

1. 자동 만료가 필요했기 때문

DB에 저장한다면?

만료된 데이터 삭제 로직을 따로 구현해야 한다
스케줄러나 배치 작업이 필요하다

Redis는 Key에 TTL을 걸면 자동 삭제된다 → 별도 정리 로직이 필요 없다

2. 인증은 임시 상태이기 때문

이메일 인증 정보는 짧게 존재해야 하며 일정 시간 후 의미 없어지고 재사용을 방지 필요하다

이 성격은 영구 저장소보다 임시 저장소에 가깝다

3. 조회 속도가 중요하기 때문

인증은 로그인/회원가입과 같이 자주 발생한다 Redis는 메모리 기반이라 조회가 빠르다 DB 접근 없이 상태 확인이 가능하다

Momentix의 실제 구조

Momentix에서는 인증 상태를 3개로 나눴다

1) 인증 코드 (5분 유지)

Key: momentix:email:code:{email}
Value: 6자리 코드
TTL: 300초

사용자가 입력해야 하는 코드다 5분 후 자동 삭제된다 코드가 맞으면 즉시 삭제해서 재사용을 막는다

2) 검증 토큰 (15분 유지)

Key: momentix:email:verified:{token}
Value: email
TTL: 900초

코드를 통과하면 UUID 기반 토큰을 발급한다 이 토큰은 이 이메일은 방금 인증을 완료했다는 증명 역할이다 회원가입 API는 이 토큰을 Redis에서 확인한다

3) 재전송 쿨다운 (45초)

Key: momentix:email:cooldown:{email}
TTL: 45초

이 키가 존재하면 인증 코드 재요청을 막는다

→ 메일 폭탄 방지

→ 남발 방지

[깨알정리] 5분/15분/45초 시간 설정 기준 정리

항목	TTL	기준
인증 코드	5분	사용자 입력 시간 + 보안 고려
검증 토큰	15분	가입 폼 작성 시간 고려
쿨다운	45초	남발 방지 + 사용자 불편 최소화

[깨알정리] 왜 인증상태를 3개로 나누었는가?

구분	목적	분리한 이유
인증 코드	사용자가 직접 입력해야 하는 비밀값	보안 민감도가 높고 1회성 처리 필요
검증 토큰	코드 통과 이후 상태 유지	가입 폼 작성 등 후속 단계 연결 필요
쿨다운	재요청 빈도 제한	인증 로직과 목적이 완전히 다름

이 설계의 핵심

만료 데이터 정리 로직이 필요 없다
인증 단계가 명확히 분리된다
남발 방지가 간단해진다
서버가 여러 대여도 상태 공유가 가능하다

결론

Momentix에서는 이메일 인증을 영구 데이터가 아니라 시간이 지나면 사라져야 하는 상태로 정의했다

그래서 Redis + TTL을 사용했다

[부하테스트] GET /board p95 1.66s, 이게 정상일까? (→ 369ms)

HS0601 — Tue, 10 Feb 2026 20:54:21 +0900

문제 상황

CoreBoard에 게시글 더미 데이터 10만 건을 생성한 뒤 GET /board(목록 조회) API에 k6로 부하테스트를 수행했다

그 결과 p95 응답 시간이 약 1.66s까지 상승했고 내가 설정한 기준인 p95<500ms Threshold를 통과하지 못했다

왜 느린지 원인을 확인하고 개선하는 것이 목표

왜 평균(ms)을 안 보고 p95를 보는가?

평균은 몇 개의 엄청 느린 요청(꼬리 지연) 때문에 체감이랑 안 맞을 때가 많다 p95는 대부분 유저가 겪는 체감 + 느린 꼬리를 같이 보기에 좋음

원인 분석 — DB EXPLAIN 확인하기

우선, GET /board 에서 실행되는 SQL이 DB에서 어떤 방식으로 처리되고 있는지 확인한다

1) 인덱스 현황 확인

SHOW INDEX FROM board;

확인 결과, board 테이블에는 PRIMARY KEY(id)만 존재했고 ORDER BY title에 사용되는 title 컬럼에는 인덱스가 없었다

2) 목록 조회 쿼리 EXPLAIN

EXPLAIN
select ...
from board
order by title
limit 0, 10;

EXPALIN 결과는 다음과 같았다

type = ALL → 테이블 전체 스캔
key = NULL → 인덱스 사용 못 함
rows = 100,000 → 매 요청마다 10만 건 조회
Extra = Using filesort → 인덱스로 정렬하지 못해 filesort 발생

즉, 10개만 가져오는 요청인데도 DB가 매번 10만 건을 읽고 정렬하고 있었고 이 구조가 부하 상황에서 p95를 크게 끌어올리고 있었다

개선 방법 — 정렬 인덱스 추가

문제의 핵심은 ORDER BY title 정렬이 인덱스를 전혀 활용하지 못하고 있다는 점이었다

그래서 title 기준 정렬을 인덱스로 처리할 수 있도록 다음과 같이 복합 인덱스를 추가했다

CREATE INDEX idx_board_title_id ON board (title, id);

title — 정렬 대상 컬럼

id — 동일 title 값이 많을 때 정렬 안정성 확보용

인덱스 적용 후 EXPLAIN

인덱스 추가 후 동일한 쿼리를 다시 확인했다

EXPLAIN
select ...
from board
order by title
limit 0, 10;

결과는 명확하게 달랐다

key = idx_board_title_id → 인덱스 사용
rows = 10 → 필요한 만큼만 조회
Using filesort 사라짐

개선 결과 — 부하테스트 재실행

동일한 조건으로 k6 부하테스트를 다시 실행했다

결과는 다음과 같았다

p95: 1.66s → 369ms
Threshold(p95 < 500ms) 통과
HTTP 에러 0%

[부하테스트-1] k6 스모크 테스트: /board 200 확인 + Grafana로 요청 유입 검증

HS0601 — Tue, 10 Feb 2026 12:18:38 +0900

왜 스모크 테스트를 먼저 했는가?

부하테스트를 바로 돌리기 전에 요청이 서버에 정상 유입되고 응답이 200으로 떨어지는지 먼저 확인했다 이 단계가 없으면 부하테스트 결과가 이상해도 서버 문제인지 / 테스트 스크립트 문제인지 / 모니터링 연결 문제인지 구분이 안 되기 때문이다

k6 스모크 테스트 실행

목적

/board API가 200으로 정상 응답하는지 확인

실행

import http from "k6/http";
import { check, sleep } from "k6";

export const options = {
  stages: [
    { duration: "10s", target: 10 },
    { duration: "40s", target: 10 },
    { duration: "10s", target: 0 },
  ],
  thresholds: {
    http_req_failed: ["rate<0.01"],
  },
};

const BASE_URL = "http://3.38.144.47:8080";

export default function () {
  const res = http.get(`${BASE_URL}/board?page=0&size=10`);
  check(res, { "status is 200": (r) => r.status === 200 });
  if (res.status !== 200) console.log(`status=${res.status}, url=${res.url}, body=${res.body?.slice(0, 120)}`);

  sleep(1);
}

기대결과

http_req_faild가 0%에 가까움
상태코드가 200으로만 떨어짐

Grafana

k6를 실행한 시간대에 맞춰 Grafana Drilldown에서 확인했다

1) 요청이 실제로 유입됐나?

지표 : http_server_request_seconds_count

의미 : 서버가 받은 HTTP 요청 수 (카운트)

→ k6 실행 구간에 그래프가 튀면 요청 유입이 확인된다

2) 내가 떄린 엔드포인트가 맞나?

Breakdown → uri

의미 : 어떤 URL로 요청이 들어왔는지

확인 : /board가 잡히면 OK

참고 : /actuator/prometer 가 같이 보이는데 이건 Prometheus가 메트릭 수집하느라 호출하는 관측용 트래픽이다

3) 결과가 정상인가?

Breakdown → status

의미 : 응답코드별 요청 수

확인 : 200만 있으면 정상

Breakdown → outcome

의미 : 결과 분류(SUCCESS/CLIENT_ERROR/SERVER_ERROR)

확인 : SUCCESS만 있으면 정상

k6 스모크 태스트로 /board가 200으로 정상 응답했고 Grafana에서 요청 유입(요청량), URI(/board), 결과(200/SUCCESS)까지 확인했다 이제 다음 단계를 진행해도 된다

[Trouble Shooting] Prometheus + Grafana (EC2) 2

HS0601 — Mon, 9 Feb 2026 13:06:09 +0900

2. 막혔던 포인트 —
Target이 unknown이었던 이유

문제 상황

Prometheus 컨테이너는 정상적으로 실행 중이었다

$ docker ps
CONTAINER ID   IMAGE              STATUS
af86f99da74a   prom/prometheus    Up

Prometheus UI도 정상 접근 가능했다

http://<EC2_PUBLIC_IP>:9090

Spring Boot 애플리케이션 역시 실행 중이었고, Actuator endpoint도 직접 호출하면 정상 응답을 반환했다

$ curl <http://127.0.0.1:8080/actuator/prometheus>
# HELP application_ready_time_seconds ...

하지만 /targets 화면에서는 상태가 달랐다

State: UNKNOWN
Last scrape: 0001-01-01T00:00:00Z

즉,

Prometheus 서버는 살아 있음
Spring Boot도 살아 있음
/actuator/prometheus도 열림
그런데 Prometheus는 긁지 못하고 있음

가설 4가지

가설 1. Spring Boot가 실제로 안 떠 있는 것 아닐까?

브라우저 / curl 모두 정상 응답 → 탈락

Prometheus의 scrape 대상은 단순히 프로세스가 떠 있는지가 아니라 지정한 endpoint가 실제로 응답을 반환하는지 여부다 이미 /actuator/prometheus가 curl 기준으로 정상적인 메트릭 텍스트를 반환하고 있었기 때문에 SpringBoot 자체가 내려가 있었을 가능성은 배제하였다

가설 2. Actuator / Micrometer 설정 문제?

/actuator/prometheus가 이미 메트릭을 출력 중 → 탈락

Actuator나 Micrometer 설정 문제였다면, Prometheus가 scrape를 시도했을 때 HTTP 404, 403 혹은 매트릭 포맷 오류가 발생했을 것이다 히지만 /actuator/prometheus endpoint는

정상적인 텍스트 포맷을 반환하고 있음
Micrometer 지표들도 함께 노출되고 있음

따라서 지표 생성 단계의 문제라기 보단 Prometheus가 해당 endpoint에 도달하지 못하고 있을 가능성이 더 높다고 판단했다

가설 3. 보안 그룹 문제?

Prometheus는 같은 EC2 내부에서 접근 (외부 노출 포트와 무관) → 탈락

Prometheus는 외부에서 StringBoot로 접근하는 구조가 아니라 같은 EC2 내부에서 애플리케이션을 scrape 하는 구조다 즉 이 시점의 문제는

외부 → 내부 통신 문제가 아님
내부 → 내부 통신 문제였음

가설 4. Prometheus가 실제로 scrape를 시도했는지 확인이 필요하다

UI의 unknown 상태만으로는 왜 실패했는지 알 수 없다 그래서 Prometheus의 내부 상태 API를 직접 확인했다

/api/v1/targets 를 본 이유

Prometheus는 scrape 결과를 내부 API로 노출한다

$ curl <http://localhost:9090/api/v1/targets>

여기서 내가 집중해서 본 필드는 아래 네 가지다

"lastError" -> Prometheus 내부 기준으로 이 target을 정상(up)으로 판단하는지 여부
"lastScrape" -> 실제 scrape가 수행된 적 있는지, 있었다면 언제였는지 확인하기 위함
"lastScrapeDuration" -> scrape 시도가 실제로 실행되었는지, 혹은 네트워크 단계에서 막혔는지 판단하기 위함
"health"-> scrape 실패의 직접적인 원인 메시지를 확인하기 위함

즉, 이 네 가지를 통해 Prometheus가 시도조차 하지 않앗는지 시도는 했지만 어디에서 실패했는지를 구분하려고 했다

결과 → 문제 시점

"lastError": "dial tcp 127.0.0.1:8080: connect: connection refused"
"lastScrape": "0001-01-01T00:00:00Z"
"health": "down"

핵심 단서 → lastError 값을 보고

HTTP 요청 단계까지 가지도 못했고 TCP 연결 자체가 성립되지 않았다는 뜻이다
- Prometheus 설정 파일이 잘못 로드되었거나 endpoint 경로가 틀린 문제가 아님
- 네트워크 레벨에서 해당 주소에 접근할 수 없다는 의미 ㅇㅇ

설정 파일이 안 먹었다가 아니라 네트워크 관점에서 접근 자체가 실패 하고 있었다

컨테이너 안에서의 127.0.0.1은 누구인가?

Prometheus 컨테이너에서 보는 127.0.0.1은 EC2의 127.0.0.1과 같은가???

→ 답은 NO

SpringBoot → EC2 호스트에서 8080 포트로 실행 중

Prometheus → Docker 컨테이너 내부에서 실행 중

Prometheus 컨테이너 기준 127.0.0.1 = Prometheus 컨테이너 자신
그래서 Prometheus 입장에서는
127.0.0.1:8080 → 컨테이너 내부에 8080 서버가 없음 → connection refused

[깨알공유] 컨테이너 안에서의 127.0.0.1

Prometheus target이 unknown일 때 설정 파일부터 의심하기 보다

lastError가 네트워크 에러인지부터 확인하는게 훨씬 빠르다

해결 2가지

방법 1. Docker 네트워크 브리지 + 호스트 IP 사용

EC2 사설 IP 지정
Docker 네트워크 구성

방법 2. Prometheus를 host 네트워크로 실행 V

컨테이너가 호스트 네트워크를 그대로 사용

[방법 2 채택 이유]

현재목표는 네트워크 개념을 단순화한 상태에서 Prometheus와 SpringBoot의 연결 관계를 명확히 이해하는 것이었기 때문이다

브리지 네트워크 + 사설 IP 방식은 더 유연하고 실무에서는 더 자주 사용되지만

초기 모니터닝 구조를 이해하는 단계에서는 컨테이너가 곧 호스트처럼 동작한다는 가정이 문제 원인을 추적하는 데 훨씬 명확하다고 판단하였다

적용한 설정

Prometheus 실행 방식 변경

docker run -d \\
  --name prometheus \\
  --net=host \\
  -v ~/monitoring/prometheus.yml:/etc/prometheus/prometheus.yml \\
  prom/prometheus

또는 doker-compose 기준

services:
  prometheus:
    image: prom/prometheus
    network_mode: host

상태 변화 확인

재기동 후 다시 확인했다

$ curl <http://localhost:9090/api/v1/targets>

"lastError": ""
"lastScrape": "2026-02-09T03:12:12Z"
"health": "up"

Prometheus + Grafana (EC2) 1

HS0601 — Mon, 9 Feb 2026 12:29:08 +0900

1. 전체 구조와 연결 흐름

모니터링은 설정이 아니라 연결을 이해하는 과정이다

CI/CD 배포까지 끝났지만, 서버가 실제로 어떻게 동작하는지 알 수 없었다 CPU때문인지, 메모리때문인지, API 때문인지 감이 아니라 지표를 보고 싶었다

Spring Boot (Actuator)
 → /actuator/prometheus
 → Prometheus (scrape)
 → Grafana (visualize)

Prometheus는 보는 도구가 아니라 긁어오는 서버다 Grafana는 Prometheus를 대신 조회하는 화면이다

SpringBoot 설정

Actuator 의존성

    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    implementation 'io.micrometer:micrometer-registry-prometheus'

/actuator/prometheus 노출
Micrometer가 중간에서 지표를 변환해줌

설정에서 막혔던 포인트

docker-compose.monitoring.yml 위치 문제
컨테이너 안에서 127.0.0.1의 의미
target가 unknown → up으로 바뀌는 과정
/api/v1/targets로 상태 확인한 이유

보안그룹

- 9090: Prometheus
- 3000: Grafana

Prometheus는 서버 내부 수집용,
Grafana만 외부 접근이 필요했다.

Prometheus는 애플리케이션과 같은 서버 내부에서만 통신하므로 외부에 노출할 필요가 없었다

포트를 열어서 접근하면 아래 사진처럼 뜬다

[IDE] Coverage Gutters - VSCode에서 Spring Boot(JaCoCo) 커버리지 초록/빨강으로 표시하는 법

HS0601 — Mon, 9 Feb 2026 11:40:41 +0900

Spring Boot + Gradle 프로젝트에서 텍스트 커버리지를 확인하려고 JaCoCo HTML 리포트를 열어보면 브라우저로 들어가야 하고 파일 이동도 불편해서 개발 중에 꽤 스트레스였다

이 글은 VSCode 안에서 바로 커버리지를 초록/빨강으로 표시하는 방법을 정리했다

VSCode 코드 왼쪽 줄 번호 옆(gutter)

초록: 커버된 라인
빨강: 커버 안 된 라인

준비물
Gradle 기반 Spring Boot 프로젝트
JaCoCo 사용 가능 상태(대부분 기본 세팅으로 가능)
VSCode 확장: Coverage Gutters

1. JaCoco 커버리지 리포트(XML) 생성하기

프로젝트 루트에서 실행

./gradlew test jacocoTestReport

생성되면 아래 루트대로 파일이 있어야 한다

build/reports/jacoco/test/jacocoTestReport.xml

HTML이 아니라 XML 파일을 Coverage Gutters가 읽는다

2. VSCode 확장 설치

VSCode → Extensions (Ctrl + Shift + X)
Coverage Gutters 검색
설치 후 Reload가 뜨면 Reload

3. settings.json에 커버리지 파일 경로 등록

VSCode 설정은 탐색기에서 파일을 찾는 게 아니라, 명령으로 열어야 빠르다

settings.json 여는 법

Ctrl + Shift + P
Open Settings (JSON) 입력
Enter

열린 JSON에 아래 설정을 추가한다:

{
  "coverage-gutters.coverageFileNames": [
    "build/reports/jacoco/test/jacocoTestReport.xml"
  ],
  "coverage-gutters.showLineCoverage": true
}

그리고 저장:

Ctrl + S

설정 적용을 위해 VSCode 리로드:

Ctrl + Shift + P → Reload Window

4. 커버리지 표시 실행

Ctrl + Shift + P
coverage 입력
Coverage Gutters: Display Coverage 클릭

이제 코드 왼쪽 여백에 초록/빨강이 뜬다.

[Trouble Shooting] CI/CD 구축 중 JAR 배포 반복 실패

HS0601 — Sun, 8 Feb 2026 11:58:37 +0900

0. 시도한 목표와 초기 상태

Spring Boot 프로젝트를 GitHub Actions로 빌드한 뒤 EC2 서버에 JAR 파일을 배포하고 systemd로 실행하는 CI/CD를 구성하려고 했다 의도한 전체 흐름은 단순했다

GitHub push
Actions에서 Gradle build
생성된 JAR를 EC2로 복사
서버에서 app.jar로 교체
서비스 재시작

하지만 실제로는 빌드 이후 배포 단계에서 계속 실패했다

1. 첫 번째 벽 — 서버에 JAR가 없다는 에러

처음 워크플로우를 작성했을 때, 배포 단계에서 다음 에러가 발생했다

ls: cannot access '*-SNAPSHOT.jar': No such file or directory
mv: cannot stat '': No such file or directory

이 에러가 의미하는 것

빌드는 끝났는데 서버에 접속한 뒤 -SNAPSHOT.jar를 찾지 못했다

즉, JAR가 아예 없거나 / 있긴 한데 내가 보고 있는 위치에 없다는 뜻이었다

2. 1차 추론 — 문제는 빌드가 아니라 전송 이후

여기서 중요한 전제 하나를 확인했다

GitHub Actions 로그에서 build/libs/*.jar 생성은 정상
즉, 빌드는 성공

그래서 문제 후보를 두 가지로 좁혔다

후보군 A

JAR 파일이 서버로 전송되지 않았다

후보군 B

JAR 파일은 전송됐지만, 내가 생각한 위치와 다르다

빌드가 성공했다는 점 때문에 A보다는 B가 더 가능성이 높아 보였다

3. 서버 직접 확인 — 결정적인 단서

CI/CD 실패 직후, EC2 서버에 직접 접속해서 파일을 탐색했다

find /home/ubuntu/apps/coreboard -type f -name"*.jar"

결과는 다음과 같았다

/home/ubuntu/apps/coreboard/app.jar
/home/ubuntu/apps/coreboard/build/libs/CoreBoard-0.0.1-SNAPSHOT.jar

여기서 모든 게 설명됐다

JAR 파일은 분명 서버에 있음
하지만 /home/ubuntu/apps/coreboard/ 바로 아래가 아니라 build/libs/ 경로를 그대로 포함한 채 업로드되어 있었다

즉, 서버에서 실행한

ls *-SNAPSHOT.jar

이 실패하는 건 당연한 상황이었다

후보군 B가 확정

4. 왜 이런 일이 발생했는가 — scp 전송 방식의 오해

CI에서 사용한 설정은 다음과 같은 형태였다

source:build/libs/*-SNAPSHOT.jartarget:/home/ubuntu/apps/coreboard

나는 이 설정을 이렇게 이해하고 있었다

JAR 파일 하나만 target 디렉토리에 떨어질 것이다

하지만 실제 동작은 달랐다

실제 동작

build/libs/... 경로 구조 자체를 유지한 채 서버로 복사됨
결과적으로 서버에는 이런 구조가 생김

/home/ubuntu/apps/coreboard/build/libs/CoreBoard-0.0.1-SNAPSHOT.jar

즉, CI에서 생각한 경로와 서버에서 가정한 경로가 어긋나 있었다

5. 첫 번째 해결 시도 — 서버 쪽에서 찾게 만들기 (실패)

처음에는 이렇게 생각했다

그럼 서버에서 build/libs까지 내려가서 찾으면 되지 않을까?

그래서 SSH 스크립트에서 ls, find 등을 써서 JAR 파일을 동적으로 찾는 방식을 고려했다

하지만 곧 문제가 보였다

배포 스크립트가 점점 복잡해짐
파일 구조가 바뀌면 또 깨질 가능성
CI/CD가 추론하는 시스템이 되어버림

이 방식은 근본 해결이 아니라고 판단했다

6. 방향 전환 — 서버가 아니라 CI에서 고쳐야 한다

여기서 관점을 바꿨다

❌ 서버에서 JAR 위치를 추론하게 만들지 말자

✅ CI 단계에서 결과물의 위치를 고정하자

즉, 서버는 항상 여기, 이 이름의 파일이 온다고 가정 불확실성은 CI 쪽에서 제거

7. 두 번째 해결 — 경로를 제거하고 파일만 배포

CI 설정에서 경로를 제거하는 옵션을 적용했다

이로 인해 build/libs/ 경로는 제거되고 JAR 파일만 target 디렉토리에 바로 복사되었다

결과적으로 서버에는 항상 다음 상태가 보장되었다

/home/ubuntu/apps/coreboard/CoreBoard-0.0.1-SNAPSHOT.jar

8. 그런데 또 다른 에러 — 이번엔 mv가 실패한다

이제 서버에 JAR는 있었다 그런데 이번엔 이런 에러가 발생했다

mv: cannot stat 'CoreBoard-0.0.1-SNAPSHOT.jar': No such file or directory

다시 추론

이 시점에서 가능한 후보는 두 가지였다

A. JAR 이름이 내가 생각한 것과 다르다
B. 현재 작업 디렉토리가 내가 생각한 곳이 아니다

서버에서 다시 확인해보니 JAR는 build/libs 아래에 존재 SSH 스크립트는 상위 디렉토리에서 실행 중

이번에도 원인은 경로 불일치

9. 최종 해결 — 경로와 이름을 완전히 고정

이 문제를 해결하면서 정한 최종 원칙은 이것이다

서버 스크립트에서는 절대 추론하지 않는다

그래서 최종적으로 다음과 같이 정리했다

CI 단계에서 JAR를 정해진 위치로 보냄
서버에서는 정해진 경로의 파일을 그대로 app.jar로 교체

mv -f build/libs/CoreBoard-0.0.1-SNAPSHOT.jar app.jarsudo systemctl restart coreboard

이후 CI/CD 성공, 서비스 정상 실행, 재시도 없이 안정적으로 배포 가능

10. 이 트러블슈팅에서 얻은 핵심 교훈

이 문제의 본질은 도구 문제가 아니었다

핵심 원인

파일 흐름을 추론에 맡긴 구조

배운 점

CI/CD에서 가장 중요한 건 결과물의 위치와 이름을 고정하는 것 ls, find가 많아질수록 파이프라인은 불안정해진다

문제는 대부분 빌드가 아니라, 전송 이후 상태에서 발생한다

[네트워크] 회선 교환 방식과 패킷 교환 방식

HS0601 — Fri, 6 Feb 2026 22:49:58 +0900

회선 교환은 전화 통화에 최적화된 방식,
패킷 교환은 인터넷과 서버 통신을 위해 만들어진 방식

백엔드 개발자가 다루는 HTTP, TCP/IP, REST, API, DB 통신은 전부 패킷 교환 방식 위에서 동작한다 그래서 이 차이를 이해하지 못하면 지연, 타임아웃, 재시도, 부하, 장애를 감으로만 다루게 된다

회선교환 방식(Circuit Switching이란?

통신을 시작하기 전에, 송신자와 수신자 사이의 물리적 경로를 미리 확보하고 통신이 끝날 때까지 그 경로를 독점적으로 사용하는 방식이다

동작 흐름

통신 요청
중간 교환기들이 하나의 고정 경로를 설정
통신 시작
통신 종료 후 회선 해제

왜 안정적일까?

경로 고정임
대역폭 보장됨
중간에 다른 트래픽이 끼어들 수 없음

그래서 지연(Iatency)과 품질(QoS)이 예측 가능하다

단점이 치명적인 이유

데이터를 보내지 않아도 회선은 계속 점유됨
사용하지 않는 시간도 자원 낭비됨
동시에 많은 사용자를 수용하기 어려움

대표 사례

유선 전화망 (PSTN)
초기 이동 통신 음성 통화

패킷 교환 방식(Packet Switching)이란?

패킷 교환 방식은 데이터를 작은 단위(패킷)로 나누어 보내고 각 패킷이 독립적으로 최적의 경로를 찾아 이동하는 방식이다

동작 흐름

메시지를 여러 패킷으로 분할
각 패킷에 목적지 정보(헤더) 추가
라우터가 패킷마다 최적 경로 선택
목적지에서 패킷 재조립

왜 효율적인가?

통신 중일 때만 네트워크 자원 사용
여러 사용자가 하나의 네트워크를 공유 가능
특정 경로가 막혀도 우회 가능

이 구조 덕분에 인터넷이 대규모로 확장될 수 있다

단점

패킷마다 헤더가 붙어 오버헤드 발생
패킷 순서 뒤바뀜 가능
경로 탐색으로 인한 지연 발생 가능

회선 교환 VS 패킷 교확 비교

구분	회선 교환	패킷 교환
경로	통신 전 고정	패킷마다 유동
자원 사용	항상 점유	전송 시만 사용
안정성	매우 높음	상대적으로 낮음
확장성	낮음	매우 높음
대표 예	전화망	인터넷

[React]리액트에서 성능 최적화를 위해 적용할 수 있는 방법들

HS0601 — Fri, 6 Feb 2026 22:39:33 +0900

useMemo, useCallback, Code Splitting

리액트 애플리케이션이 커질수록 화면이 느려지거나, 불필요하게 다시 렌더링되는 문제가 발생한다 성능 최적화는 이런 문제를 느낌이 아니라 구조적으로 줄이기 위한 작업이다

리액트 성능 이슈는 보통 다음 세 가지 상황에서 발생한다

필요 없는 리렌더링이 반복되는 경우
한 번 렌더링할 때 계산이나 DOM 작업이 너무 무거운 경우
초기 로딩 시 번들 크기가 커서 화면이 늦게 뜨는 경우

리액트의 성능 최적화는 이 원인에 맞춰 대응하는 것이 핵심이다

1. 불필요한 리렌더링 줄이기

React.memo를 활용한 컴포넌트 메모이제이션

리액트에서 컴포넌트는 부모가 리렌더링되면 함께 다시 렌더링된다 하지만 props가 실제로 변경되지 않았는데도 자식 컴포넌트가 계속 렌더링되는 경우가 많다 이때 사용할 수 있는 것이 React.memo이다 React.memo는 컴포넌트를 감싸서 이전 props와 현재 props를 비교한 뒤, 변경되지 않았다면 이전 렌더 결과를 그대로 재사용한다

이 방법은 특히 다음과 같은 경우에 효과적이다

부모 컴포넌트는 자주 렌더링되지만 자식 컴포넌트의 props는 거의 바뀌지 않고 자식 컴포넌트의 렌더링 비용이 큰 경우

다만 React.memo는 props의 값이 같아 보이는지가 아니라 참조(reference)가 같은지를 기준으로 판단한다 그래서 매번 새 객체나 새 함수를 props로 전달하면 메모이제이션 효과가 사라진다

useCallback으로 함수 재생성 방지

리액트 컴포넌트는 렌더링될 때마다 내부에 선언된 함수도 새로 만들어진다 이 함수가 자식 컴포넌트의 props로 전달되면, 자식 입장에서는 props가 변경된 것으로 인식된다 useCallback은 이 문제를 해결하기 위한 훅이다 useCallback을 사용하면 함수 자체를 메모이제이션하여 의존성이 변경되지 않는 한 같은 함수 참조를 유지할 수 있다

이렇게 하면 React.memo로 감싼 자식 컴포넌트가 불필요하게 리렌더링되는 것을 막을 수 있다 중요한 점은 useCallback의 목적이 함수를 빠르게 만드는 것이 아니라 리렌더링의 원인이 되는 참조 변화를 막는 것이라는 점이다

상태 위치 조정으로 리렌더 범위 줄이기

성능 최적화에서 가장 효과적인 방법은 훅을 추가하는 것이 아니라 상태를 어디에 두느냐를 조정하는 것이다 상태가 상위 컴포넌트에 있으면 그 상태가 변경될 때마다 하위 컴포넌트들이 전부 리렌더링된다 해결 방법은 간단하다

해당 상태가 필요한 컴포넌트 가까이에 상태를 두기
공통 상태라면, 실제로 필요한 컴포넌트만 영향을 받도록 분리하기

이 방식은 추가적인 최적화 도구 없이도 리렌더링 범위를 크게 줄일 수 있다

2. 렌더링 비용 자체를 줄이기

useMemo로 값의 재계산 방지

컴포넌트 내부에서 정렬, 필터링, 변환처럼 계산 비용이 큰 작업을 수행하는 경우가 있다 이런 계산은 렌더링이 발생할 때마다 반복되는데, 입력 값이 바뀌지 않았다면 같은 결과를 다시 계산할 필요는 없다 useMemo는 이러한 계산 결과를 메모이제이션하여 의존성이 변경되지 않는 한 이전 결과를 재사용한다 다만 모든 계산에 useMemo를 사용하는 것은 바람직하지 않다 계산 비용이 크지 않다면, 메모이제이션 자체가 오히려 부담이 될 수 있다

리스트 렌더링 최적화

리스트는 리액트 성능 문제의 주요 원인 중 하나다

key 값을 안정적으로 부여하지 않으면 리액트가 기존 DOM을 재사용하지 못하고 불필요한 렌더링이 발생한다
긴 리스트를 한 번에 렌더링하면 DOM 노드 수가 급격히 증가한다

이런 경우에는 화면에 보이는 항목만 렌더링하는 방식으로 렌더링 비용을 줄일 수 있다

3. 초기 로딩 속도 개선하기

코드 스플리팅(Code Splitting)

애플리케이션이 커질수록 초기 로딩 시 다운로드해야 할 자바스크립트 파일도 커진다 코드 스플리팅은 애플리케이션을 여러 개의 작은 청크로 나누어 실제로 필요한 코드만 그 시점에 로드하는 방식이다 리액트에서는 React.lazy와 Suspense를 사용해 컴포넌트를 동적으로 로드할 수 있다

이 방법을 적용하면 초기 로딩 속도를 크게 개선할 수 있다

4. 성능 최적화의 전제는 측정

성능 최적화는 추측으로 하면 실패한다

어떤 컴포넌트가 자주 렌더링되는지
왜 렌더링이 발생하는지
실제로 시간이 오래 걸리는 지점이 어디인지

이런 정보는 측정 도구를 통해 확인한 뒤 판단해야 한다 불필요한 최적화는 코드 복잡도만 높이고 실제 성능 개선 효과는 없을 수 있다

[React] 리액트의 props와 state

HS0601 — Fri, 6 Feb 2026 22:22:15 +0900

props

props는 부모 컴포넌트가 자식 컴포넌트에 전달하는 데이터다 읽기 전용으로, 자식 컴포넌트는 props를 수정할 수 없다

function ChildComponent(props){
	props.name = "new name";
	return <div>{props.name}</div>
}

이를 통해 컴포넌트 간의 데이터 흐름을 예측 가능하게 만들고 컴포넌트의 재사용성을 높인다

state

state는 컴포넌트 내부에서 관리되는 데이터다 동적으로 변경될 수 있으며 컴포넌트의 렌더링에 영향을 미친다 state를 변경하면 컴포넌트는 다시 렌더링되며 UI가 업데이트된다 state는 주로 사용자 입력이나 네트워크 요청의 응답에 따라 변하는 데이터를 관리할 때 사용된다

props가 자식 컴포넌트에서 변하지 않는 이유는?

props가 자식 컴포넌트에서 변하지 않는 이유는 리액트의 단방향 데이터 흐름 원칙 때문이다

리액트는 부모 컴포넌트가 자식 컴포넌트에 데이터를 전달할 때 단방향으로 전달하도록 설계되었다 이렇게하면 컴포넌트 간의 데이터 흐름을 예측 가능하고 일관성있게 만들 수 있어 애플리케이션 상태 관리가 간단해진다

props는 읽기 전용이기 때문에 부모 컴포넌트에서 전달된 값이 자식 컴포넌트 내에서 임의로 변경되지 않는다

이로 인해 특정 상태가 어디서 어떻게 변했는지를 예측할 수 있어 버그 발생 가능성을 줄이고 디버깅을 쉽게 한다

만약 props가 변경될 수 있다면

자식 컴포넌트는 독립적으로 동작하지 않게 되고 재사용이 어려워질 수 있다 props가 불변으로 유지됨으로써 컴포넌트는 외부 입력에 의존할 뿐 내부적으로 변경하지 않아 재사용성이 높아지고 코드의 캡슐화가 강화된다

만약, 자식 컴포넌트가 부모로부터 받은 props를 변경해야 한다면, 부모 컴포넌트에서 상태로 해당 데이터를 관리하고 상태 변경 함수를 자식 컴포넌트로 전달하는 방식으로 구현해야 한다 이렇게 하면 데이터는 여전히 단방향으로 흐르고 상태는 부모 컴포넌트가 관리하므로 일관성을 유지할 수 있다 이러한 기법을 상태 끌어올리기라고 한다

[JavaScript] 이벤트 루프

HS0601 — Fri, 6 Feb 2026 22:21:42 +0900

자바스크립트가 싱글 스레드 기반 언어임에도 불구하고
비동기 작업을 처리할 수 있게 해주는 중요한 메커니즘이다

자바스크립트는 기본적으로 한 번에 하나의 작업만 처리할 수 있다

하지만 이벤트 루프가 콜 스택과 데스크큐를 매개하면서 비동기 작업이 완료되면 그 결과를 처리할 수 있게 도와준다 여기서 콜 스택은 현재 실행 중인 함수들이 쌓여있는 곳이고 태스크 큐는 비동기 작업이 완료될 때 그 결과를 대기시키는 곳이다

이벤트 루프의 동작을 설명하기 위해 간단한 예로

setTimeout(callback, 0)

을 들어보겠다

setTimeout을 호출하면 이 콜백 함수는 바로 실행되는 것이 아니라 웹 API에 의해 타이머가 설정되고 그 타이머가 0밀리초 후에 만료되면 콜백 함수가 태스크 큐에 추가된다 그 후 콜 스택이 비어 있는 시점에 이벤트 루프가 태스크 큐에서 대기 중인 callback을 꺼내서 실행한다

따라서 setTimeout을 호출해도 현재 실행 중인 모든 동기 작업들이 완료된 후에야 그 콜백이 실행된다

이때문에 setTimeout을 사용하면 코드의 실행을 다음 이벤트 루프 사이클로 미뤄진다

이와 같이 이벤트 루프는 자바스크립트의 비동기 작업을 처리하는데 있어서 매우 중요한 역할을 한다 이벤트 루프 덕분에 자바 스크립트는 UI 업데이트나 사용자 입력 처리를 수행하면서도 비동기 작업을 블로킹 없이 효율적으로 처리할 수 있다

[JavaScript] 클로저

HS0601 — Fri, 6 Feb 2026 22:20:52 +0900

클로저는 함수가 선언될 때의 스코프를 기억하며 함수가 생성된 이후에도 그 스코프에 접근할 수 있는 기능이다

비유하자면, 함수가 자신이 생성된 환경을 기억하는 것이라고 할 수 있다 클로저는 자바스크립트의 함수가 일급 객체라는 특성과 렉시컬 스코프의 조합으로 만들어진다

예시화 함께 클로저 동작을 설명하겠다

클로저 예시 코드

function outerFunction(outerVariable) {
  return function innerFunction(innerVariable) {
    console.log('Outer Variable: ' + outerVariable);
    console.log('Inner Variable: ' + innerVariable);
  };
}

const newFunction = outerFunction('outside');
newFunction('inside');

여기서 innerFunction은 outerFunction의 내부에 정의되어 있다 innerFunction은 자신이 생성된 스코프, 즉 outerFunction의 스코프를 기억하고, outerFunction의 호출이 완료된 이후에도 그 스코프에 접근할 수 있다 그리고 이에 따라 innerFunction은 outerVariable에도 접근할 수 있다 이것이 클로저가 동작하는 방식이다

클로저는 언제 활용하나요?

클로저는 변수와 함수의 접근 범위를 제어하고 특정 데이터와 상태를 유지하기 위해 자주 활용됩니다. 크게 세 가지 대표적인 사용 사례로 나누어 설명할 수 있다

첫째, 데이터 은닉에 활용된다. 클로저는 외부에서 접근할 수 없는 비공개 변수와 함수를 만들 수 있다 이를 통해 데이터를 은닉하여 외부 접근을 막고, 데이터 무결성을 유지할 수 있다 예를 들어, 특정 함수 내부에서만 접근 가능한 변수를 생성하고, 이를 조작할 수 있는 함수만 외부로 노출하여 안전하게 데이터를 관리할 수 있다

둘째, 비동기 작업에 활용된다 클로저는 비동기 작업에서 이전의 실행 컨텍스트를 유지해야 할 때 유용하다 콜백 함수가 비동기적으로 실행될 때 클로저를 사용하면 함수 실행 시점의 변수를 참조할 수 있다

function createLogger(name) {
  return function() {
    console.log(`Logger: ${name}`);
  };
}

const logger = createLogger('MyApp');
setTimeout(logger, 1000); // 1초 후에 'Logger: MyApp' 출력

위의 예시에서 클로저가 name 변수('MyApp')를 저장하여 1초 후에도 해당 값이 유지되어 출력된다

셋째, 모듈 패턴을 구현하는 데 활용된다 모듈 패턴은 특정 기능을 캡슐화하고, 외부에 공개하고자 하는 부분만 선택적으로 노출하여 코드의 응집력을 높이고, 유지보수성을 향상시키는 패턴이다 클로저를 활용하면 필요한 함수와 데이터만 외부로 노출함으로써 모듈 패턴을 쉽게 구현할 수 있다

[모니터링·관측성] Micrometer

HS0601 — Fri, 6 Feb 2026 19:52:00 +0900

어떤 일이 일어나는지 수치로 측정/모니터링(라이브러리)

[Spring Boot]
   └ Actuator   ← 서버 내부 상태를 숫자로 공개
       └ Micrometer ← 숫자 포맷 표준화
            ↓
      Prometheus ← 주기적으로 긁어감 (저장)
            ↓
        Grafana ← 그래프로 보여줌

Micrometer란?

Micrometer는 벤더 중립적인 메트릭 계측 라이브러리로, 애플리케이션에서 무슨 일이 실제로 벌어지고 있는지를 숫자로 측정한다 단순히 서버가 느린 것 같다, 요청이 많아진 것 같다라는 감이 아니라, 요청이 많아졌을 때 CPU 때문인지, DB 때문인지 응답이 느릴 때 어느 API가 병목인지를 지표로 확인하기 위해 사용된다.

CoreBoard에서는 배포 후 서버가 느려지거나 문제가 생겼을 때, 그 원인을 코드가 아니라 수치로 설명할 수 있어야 한다 는 목적 때문에 Micrometer를 도입했다

Micrometer는 CPU 사용량, 메모리 소비, HTTP 요청 처리 시간, 커스텀 이벤트 등의 지표를 지속적으로 수집한다

Spring Boot Actuator와 Micrometer의 관계

Spring Boot Actuator는 애플리케이션의 상태, 헬스 체크, 로그, 환경 정보 등 운영 중인 서버를 관찰하기 위한 관리 엔드포인트를 제공한다

CoreBoard처럼 배포 이후 실제로 서버를 띄워두고 부하 테스트나 운영 시나리오를 실험하려는 경우 애플리케이션 내부 상태를 외부에서 확인할 수 있는 창구가 필요하다

내부적으로 Actuator는 Micrometer를 사용해 JVM, HTTP 요청, DB 커넥션 풀 등의 메트릭을 수집한다

즉 역할은 명확히 나뉜다

Micrometer
→ 실제 수치를 측정하는 계측 엔진
Actuator
→ 그 측정 결과를 /actuator/** 형태로 외부에 노출하는 인터페이스

Micrometer가 재고를 쌓아두는 역할이라면, Actuator는 그 재고를 밖에서 볼 수 있게 진열하는 역할이다

Micrometer로 무엇을 측정하는가?

Micrometer는 지표의 성격에 따라 다음과 같이 측정한다

메트릭 종류 의미

Counter	누적 증가 값 (예: 총 HTTP 요청 수)
Timer	처리 시간 측정 (예: API 응답 시간, 퍼센타일)
Gauge	현재 상태 값 (예: 활성 세션 수, 메모리 사용량)

이 지표들은 단순한 숫자가 아니라, 서버에서 어떤 일이 벌어지고 있는지 설명하는 근거가 된다

예를 들어 CoreBoard 기준으로 보면

Counter
→ 특정 API가 예상보다 많이 호출되고 있는지
Timer
→ 게시글 조회/생성 중 어떤 API가 느린지
Gauge
→ DB 커넥션 풀이 고갈되고 있는지

를 눈으로 확인할 수 있다

이렇게 수집된 지표는 Actuator를 통해 노출되고, Prometheus 같은 모니터링 시스템이 주기적으로 수집(scrape)한다

[IDE] IntelliJ에서는 되는데 VS Code에서는 안 되던 Spring Profile 미적용 문제

HS0601 — Fri, 6 Feb 2026 19:07:50 +0900

[IntelliJ에서는 되고 VS Code에서는 안 되는 이유 바로가잣!]

VSCode에서 Spring Boot 실행 시 애플리케이션 부팅 중단되었다

로그에서 보인 문구

No active profile set, falling back to 1 default profile: "default"
Failed to configure a DataSource: 'url' attribute is not specified
Failed to determine a suitable driver class

원인

프로젝트는 application.yml과 application-local.yml로 분리되어 있음

하지만 VS Code에서 Run Java/Debug Java 방식으로 실행하면 spring.profile.active=local이 전달되지 않아 default 프로필로 부팅된다

그 결과 application-local.yml이 로딩되지 않고 datasource 설정(url, driver-class-name 등)이 없어 DataSource 생성 실패한다

해결

컨트롤 + 시프트 + D

launch.json 파일 만들기 클릭

VS Code에서 실행 시 JVM 옵션으로 프로필을 명시하도록 launch.json 실행 구성을 추가하면 된다

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "CoreBoard (local)",
      "request": "launch",
      "mainClass": "com.example.coreboard.CoreBoardApplication",
      "projectName": "CoreBoard",
      "vmArgs": "-Dspring.profiles.active=local"
    }
  ]
}

이후 실행 및 디버그에서 CoreBoard(local) 구성으로 실행한다

결과(검증)

로그에서 No active profile set... 문구가 사라지고 Started CoreBoardApplication까지 정상 가동되었다

회고 / 재발 방지

IDE마다 실행 구성(프로필/VM 옵션)을 전달하는 방식이 다르며 IntelliJ는 Run Configuration UI에 숨겨져 있으며

VS Code는 launch.json으로 명시해야 한다

설정 파일을 프로필별로 분리했다면 실행 프로필 활성화 여부를 로그로 먼저 확인하는 습관이 필요하다

왜 IntelliJ에서는 되는가?

결론부터 말하자면, Spring Profile은 IDE가 아니라 JVM 옵션으로 결정된다 IntelliJ는 JVM을 띄울 때 옵션을 자동으로 넣어주고 VS Code는 명시하지 않으면 아무 옵션도 넣지 않는다

Spring Boot는 언제 프로필을 결정할까?

JVM이 시작된 직후, 정확히는 SpringApplication이 초기화되기 전에 JVM 시스템 프로퍼티에서 아래 값을 읽는다

spring.profiles.active

이 값의 출처는 총 3가지이며 아래 순서대로 조회된다

1. JVM 시스템 프로퍼티

-Dspring.profiles.active=local

[깨알공유] JVM 시스템 프로퍼티와 application.properties는 다름!

JVM 시스템 프로퍼티는 application.properties / application.yml 보다 상위에서 결정되는 값이다
그래서 역할도 다르고, 적용 시점도 다르다

-Dspring.profiles.active=local
→ JVM 자체에 주입되는 전역 설정
Java 프로그램이 시작되자마자 즉시 사용 가능
Spring보다 훨씬 앞단에 존재한다

실제 흐름은 다음과 같다

[JVM 시작]  ← 여기서 이미 존재
   ↓
SpringApplication 생성
   ↓
Spring이 프로퍼티 조회

[반면, application.properties(application.yml)는?]

Spring Boot가 자기 자신을 로딩하면서 읽는 설정 파일
Spring 컨텍스트 내부에서만 의미가 있다
JVM 입장에서는 그냥 클래스패스에 있는 리소스 파일일 뿐이다

[JVM 시작]
   ↓
SpringApplication 시작
   ↓
설정 파일 로딩 (application.yml)

프로필을 결정하는 단계에는 아직 설정 파일이 읽히지 않았다

2. OS 환경 변수

SPRING_PROFILES_ACTIVE=local

[깨알공유] OS 환경변수란?

운영체제(OS) 프로그램 실행할 때 같이 넘겨주는 이름=값형태의 설정값이다

Spring Boot는 실행할 때 이 값을 읽어서 프로필을 결정할 수 있다 launch.json 의 -Dspring.profiles.active=local과 같은 목적이고 코드 밖에서 설정을 바꾸는 통로다

3. 설정 파일 내부

(예: spring.profiles.default, 또는 드물게 spring.profiles.active)

기술적으로는 가능하지만, 프로필을 결정하기 위해 다시 설정 파일을 읽어야 하는 구조이므로 실무에서는 거의 사용하지 않는다

IntelliJ애서는 왜 됐는가?

IntelliJ에서 Spring Boot를 실행하면, 실제로는 내부적으로 다음과 같은 JVM 커맨드를 구성한다

java -Dspring.profiles.active=local \
     -classpath ... \
     com.example.coreboard.CoreBoardApplication

Run Configuration에 설정된 VM Options, Enviroment Variavles가 자동으로 JVM 실행 명령에 포함되기 때문이다

그래서 아무것도 설정 안 했는데? 라고 느껴지지만 실제로는 JVM에는 옵션이 이미 전달된 상태였던 것.

[여기서 중요한 점]

JVM 입장에서는 VS Code든 IntelliJ든 아무 차이가 없다는 것이다
차이는 누가 JVM 옵션을 만들어 주느냐에 있다

왜 launch.json이 해결책이었나?

"vmArgs": "-Dspring.profiles.active=local"

VS Code에게 이렇게 지시한 것과 같다

JVM을 띄울 때 이 옵션을 반드시 포함시켜라.

결과적으로 VS Code는 JVM을 이렇게 띄운다

java -Dspring.profiles.active=local \
     -agentlib:jdwp=... \
     -classpath ... \
     com.example.coreboard.CoreBoardApplication

JVM이 시작되자마자 spring.profiles.active=local 값을 인식하고 Spring Boot는 application-local.yml을 로딩하여 DataSource 생성에 성공한다

[ubuntu]수동배포 - CI/CD 대응되는 포인트

HS0601 — Thu, 5 Feb 2026 11:52:41 +0900

[CI/CD 대응되는 포인트 모아보기 바로가잣!]

git clone 받고 배포해보자
- 나중에 어떻게 했더라~ 다시 보려고 정리함
왜 수동 배포를 먼저 했는가
처음부터 CI/CD를 붙이면 편하다는 건 알고 있었다.
하지만 편리함이 무엇을 대체해 주는지 이해하지 못한 상태에서 자동화를 쓰는 건 공허하다고 느꼈다.

접속을 원한다면 8080 포트 열면 됨

3. 페어키 미리 다운로드 받음

1. 서버 열기
내 선택: .pem + ED25519

위 사진에서 .pem or .ppk 골라야 하는데 난 .pem 선택했다

(참고로 사진에는 RSA 체크되어있는데 ED25519 체크했으니 당황 놉!!)

.pem + ED25519 선택 이유

— 로컬은 Windows지만, 실제 접속/배포/CI 환경은 OpenSSH 기반이므로 .pem + ED25519를 선택했다.

OpenSSH 기준으로 바로 쓸 수 있는 키 포맷이냐?

powerShell/Window Terminal의 ssh
Linux 서버의 sshd
GitHubActions/CI 러너

→ 전부 OpenSSH.pem→ 변환 불필요→ PuTTY 전용 포맷

→ CI/Linux 서버에서는 직접 쓸 수 없음
.ppk
→ OpenSSH 가 그대로 읽는다
핵심 판단 기준

1. 수동 배포(윈도우)에서 PuTTY를 쓸 거면 .ppk가 편해서 PuTTYgen 씀
2. 윈도우 powerShell의 ssh로 접속할 거면 .pem 이면 끝난다

[접속 방식 A]

PowerShell/Window Terminal로 ssh 키 : .pem

장점 : PuTTY/PuTTYgen 필요 없음, 가장 표준

단점 : 처음엔 권한/경로 때문에 에러를 한 번쯤 봄

[접속 방식 B]

PuTTY로 접속 키 : .ppk

장점 : GUI 라 직관적

단점 : PuTTYgen / 변환이 귀찮음

CICD 하더라도 보통 .pem 택해야 함

러너가 리눅스에서 돌아가고 SSH는 OpenSSH를 쓴다 그래서 개인키는 pem파일 내용 또는 -----BEGIN OPENSSH PRIVATE KEY----- 형태의 OpenSSH 개인 키 텍스트를 Secret에 넣는 게 일반적이다

.ppk 가 필요한 경우는?
CI/CD 파이프라인 안에서 PuTTY/pscp/plink 같은 PuTTY 도구를 일부러 쓰는 경우

[깨알공유] OpenSSH란?

SecureShell은 인터넷/네트워크로 다른 컴퓨터 서버에 안전하게 접속하는 프로토콜인데 그 SSH를 진짜로 실행해주는 오픈 소스다

구성
- 클라이언트: ssh, scp, sftp
- 서버(ec2): sshd (SSH데몬=서버에서 접속을 받아주는 프로그램)

왜 OpenSSH랑 .pem이랑 엮을까?

파일 확장자가 핵심이 아니라 키 포맷이 핵심이다

OpenSSH는 개인키를 OpenSSH형식으로 읽는 게 일반적이다
.pem 을 주면 보통 바로 쓴다
- 반면 .ppk는 PuTTY 전용 포맷이라 OpenSSH가 그대로 못 쓰는 경우가 많아서 변환이 필요함 그래서 이전에 이거 모르고 .ppk로 했다가 설치한 흔적이 있다 ㅠ

2. 서버와 연결 (배포)

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@         WARNING: UNPROTECTED PRIVATE KEY FILE!          @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

위 에러에서 권한이 없다고 에러가 난 것

나: “pem넣어서 접속할게”
SSH : “OK, 키 보자”
SSH : “엥? 이 키 파일을 너 말고도 다른 사용자/그룹이 읽을 수 있네???” → 위험하다!
→ 키 무시 → 인증 실패

그래서

 ssh -i "$env:USERPROFILE\\\\.ssh\\\\study-ec2-ssh.pem" ubuntu@15.165.161.222

이렇게 env:USERPROFILE 해줘야 함

참고로 해당 루트에 .ssh가 있어야 한다 Users/user

[CI/CD 대응되는 포인트]

수동 배포	CI/CD
개발자가 SSH로 접속	CI/CD Runner가 서버에 접근
사람이 직접 명령 실행	자동화된 Job 실행

2-1) 우분투에서 프로그램 설치 목록 최신으로 갱신하는 명령어

sudo apt update

2-2) java 버전도 확인해줘야 함

java --version

없다면 설치해줘야 한다

sudo apt install -y openjdk-17-jdk

apt: 우분투 패키지 관리자
install: 설치하겠다
y: “설치 중에 나오는 질문 전부 yes로 자동 응답”
openjdk-17-jdk: 설치할 대상

아래처럼 버전이 나온 걸 확인했다

openjdk version "17.0.18" 2026-01-20
OpenJDK Runtime Environment (build 17.0.18+8-Ubuntu-124.04.1)
OpenJDK 64-Bit Server VM (build 17.0.18+8-Ubuntu-124.04.1, mixed mode, sharing)

[CI/CD 대응되는 포인트]

수동 배포	CI/CD
서버 상태 직접 관리	Docker / Runner 환경 고정
매번 수동 설치	미리 정의된 실행 환경

2-3) git 버전도 확인해줘야 한다

git --version

[깨알공유] 만일, git -version 으로 했다면 아래처럼 뜰 것이다

-version는 옵션까지 모른다

이렇게 뜬다면 git 설치는 되어있는 상태인 거다 그래도 다시 한 번 정확하게 버전을 확인해보자

unknown option: -version
usage: git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--config-env=<name>=<envvar>] <command> [<args>]

git --version

2-4) git clone 받기

mkdir -p ~/apps
cd ~/apps
git clone <YOUR_PRIVATE_REPO_URL> no-cicd-deploy
cd no-cicd-deploy

여기서 생기는 문제점이 있다

브랜치를 잘못 받으면?
최신 코드인지 헷갈린다
커밋 기준이 애매하다

[CI/CD 대응되는 포인트]

수동 배포	CI/CD
git clone 직접 실행	checkout step
어떤 커밋인지 직접 확인	특정 commit SHA 기준 실행

[깨알공유] 이때 apps으로 이동하는 이유

~/apps = /home/ubuntu/apps 폴더

apps에 두면

재배포가 쉽다
파일/폴더 안 흩어진다
권한/보안이 단순해진다
서버에 여러 프로젝트 올릴 때 확장된다

mkdir -p는 왜 붙일까? 폴더 없으면 만들고 이미 있으면 에러 없이 넘어가게 하려고 -p = 있으면 그냥 통과
즉, ubuntu 계정이 관리하는 앱/프로젝트 폴더라고 보면 된다
~ = 지금 로그인한 사용자의 홈 디렉토리. 보통 /home/ubuntu

2-5) 빌드(Gradle)

chmod +x ./gradlew
./gradlew clean build -x test
ls -al build/libs

여기서 가장 큰 피로를 느꼈다

빌드 실패 → 원인 추적
성공해도 이게 맞는 결과물인가? 불안
로컬과 서버 결과가 다를 수도 있음

[CI/CD 대응되는 포인트]

수동 배포	CI/CD
서버에서 직접 빌드	build job
성공/실패 수동 확인	pipeline status

2-6) dev 프로필로 실행 (백그라운드)

nohup java -jar build/libs/*.jar --spring.profiles.active=dev > app.log 2>&1 &
tail -f app.log

2-7) 로그 확인

tail -f app.log

만일 아래처럼 뜬다면 성공

 :: Spring Boot ::                (v4.0.2)

2026-02-04T11:42:12.686Z  INFO 3814 --- [           main] c.e.n.NoCicdDeployApplication            : Starting NoCicdDeployApplication v0.0.1-SNAPSHOT using Java 17.0.18 with PID 3814 (/home/ubuntu/apps/no-cicd-deploy/build/libs/no-cicd-deploy-0.0.1-SNAPSHOT.jar started by ubuntu in /home/ubuntu/apps/no-cicd-deploy)
2026-02-04T11:42:12.699Z  INFO 3814 --- [           main] c.e.n.NoCicdDeployApplication            : The following 1 profile is active: "dev"
2026-02-04T11:42:14.119Z  INFO 3814 --- [           main] o.s.boot.tomcat.TomcatWebServer          : Tomcat initialized with port 8080 (http)
2026-02-04T11:42:14.145Z  INFO 3814 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2026-02-04T11:42:14.147Z  INFO 3814 --- [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/11.0.15]
2026-02-04T11:42:14.189Z  INFO 3814 --- [           main] b.w.c.s.WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 1365 ms
2026-02-04T11:42:14.749Z  INFO 3814 --- [           main] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 8080 (http) with context path '/'
2026-02-04T11:42:14.783Z  INFO 3814 --- [           main] c.e.n.NoCicdDeployApplication            : Started NoCicdDeployApplication in 2.919 seconds (process running for 3.596)

위 메시지 중

The following 1 profile is active: "dev"
Tomcat started on port 8080 (http) with context path '/'
Started NoCicdDeployApplication

직역하면

dev 프로필 적용됨 (application-dev.yml이 로드됨)
서버가 8080 포트에서 떠 있음
앱이 죽지 않고 계속 실행 중

여기서 만약, 에러가 난다면? 이것도 치명적인 문제로 느꼈다

에러가 코드 문제인지 배포 문제인지 구분이 안된다는 점이다

[CI/CD 대응되는 포인트]

수동 배포	CI/CD
서버에 접속해서 로그 확인	Job log
실패 원인 추적 어려움	단계별 실패 지점 명확

 curl -i <http://localhost:8080>

마지막으로 파워쉘에 위 명령어를 입력하면

HTTP/1.1 404
Content-Type: application/json
Transfer-Encoding: chunked
Date: Wed, 04 Feb 2026 11:43:47 GMT

{"timestamp":"2026-02-04T11:43:47.456Z","status":404,"error":"Not Found","path":"/"}

이렇게 뜰텐데 서버는 살아잇는데 / 경로를 처리하는 컨트롤러가 없어서 404 뜬 것이다

HTTP/1.1 404
{"status":404,"error":"Not Found","path":"/"} 직역하면
“서버는 응답했는데, /에 해당하는 페이지(엔드포인트)가 없다”
즉 네트워크/포트/톰캣/앱 기동은 전부 성공

3. 확인

확인용 api 하나 만들었다

@GetMapping("/ok")
public ResponseEntity<String> ok(){
        return ResponseEntity.ok("ok");
}

그리고 수동 배포니까 코드 업데이트를 해야 한다

코드 업데이트

1) pull

cd ~/apps/no-cicd-deploy
git pull

2) build

여기까지 오면 대충 눈치 챘겠지만, pull 땡기고 build하고 실행하는 중인 것!

./gradlew clean build -x test

이 프로젝트를 깨끗하게 다시 빌드하되 테스트는 건너뛸 거다라는 의미

3) PID 찾기 (프로세스 ID)

ps -ef | grep no-cicd-deploy

PID(Process ID) : 실행 중인 프로그램(프로세스)을 식별하는 고유 번호 이전에

[1] 3814

이렇게 생긴 걸 봤을텐데 이것이 PID .

ubuntu      3814    1263  1 11:42 pts/0    00:00:08 java -jar build/libs/no-cicd-deploy-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev
ubuntu      3938    1263  0 11:52 pts/0    00:00:00 grep --color=auto no-cicd-deploy

이렇게 뜰텐데 직역하면

ubuntu 3814 ... java -jar ... → 이게 진짜 서버(스프링 부트 앱) 프로세스
ubuntu 3938 ... grep --color=auto no-cicd-deploy → 이건 너가 입력한 검색 명령(grep) 이 잠깐 실행된 것

3814 는 지금 실행중인 앱이라서 kill 해주고 다시 빌드해야 한다

빌드까지했다면 실행해주면 된다

 nohup java -jar build/libs/no-cicd-deploy-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev > app.log 2>&1 &

그럼 사용중인 PID가 뜰 것이고 GET 요청을 해보면 된다

이게 진짜 불편했다

이전 프로세스가 남아 있으면?
포트 충돌 나면?
백그라운드 실행 관리가 번거롭다

[CI/CD 대응되는 포인트]

수동 배포	CI/CD
java -jar 직접 실행	deploy step
프로세스 직접 관리	스크립트/컨테이너 기반 실행

3-1) GET 요청

curl -i <http://localhost:8080/api/ok>

그리고 아래처럼 뜬다면 성공이다

HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 2
Date: Wed, 04 Feb 2026 11:56:30 GMT

[결론]CI/CD 부재를 체감하기 위한 수동 배포 실험 회고

[실험 환경]
Spring Boot 단일 애플리케이션
EC2 + 수동 배포
Git push 이후 자동화 없음
빌드 / 실행 / 검증 전 과정 수동

문제의 본질은 “단계가 많다”가 아니었다 개발 중 사고 흐름이 배포 절차에 의해 계속 끊긴다는 점이었다.

코드 변경 → 결과 확인 사이에 불확실한 구간이 생긴다

CI/CD 가 없는 상태에서는 코드를 수정한 뒤 결과를 보기까지 다음을 사람이 직접 보장해야 한다

jar가 정말 방금 수정한 코드인지
기존 프로세스가 완전히 내려갔는지
새 프로세스가 정상 기동했는지
요청이 새 코드로 처리되고 있는지

즉, 결과를 해석하기 전에 이 결과가 신뢰가능한가?를 먼저 판단해야 하는 상태가 되었다

1. 결과가 틀렸을 때 원인이 코드인지 배포인지 즉시 알 수 없다

API 응답이 기대와 다를 때 요청이 아예 안 들어올 때 이게 코드 로직 문제인지 jar 교체 실패인지(근데 이건 아닌듯) 포트/프로세스 문제인지 이전 버전이 아직 떠있는 건지 전부 추론해야 했다

2. 배포가 수단이 아니라 주의 대상이된다

가장 인상 깊었던 점은 어느 순간부터 이 코드가 맞나?보다 지금 서버 상태가 맞나?를 더 자주 확인하고 있었다는 점이다

CI/CD가 없으면 개발자는 코드를 디버깅하기 전에 먼저 배포가 제대로 됐는지를 디버깅하게 된다

[CI/CD 대응되는 포인트 모아보기]

1. EC2 서버 접속 (SSH)

ssh -i my-key.pem ubuntu@xx.xx.xx.xx

서버에 직접 접속해야 한다
배포할 때마다 같은 작업을 반복한다
실수하면 서버 상태가 꼬인다

수동 배포	CI/CD
개발자가 SSH로 접속	CI/CD Runner가 서버에 접근
사람이 직접 명령 실행	자동화된 Job 실행

CI/CD는 사람 대신 서버가 배포 명령을 실행하게 만드는 구조다

2. 서버 환경 세팅 (Java, Git 설치)

sudo apt update sudo apt install openjdk-17-jdk git

서버가 바뀌면 다시 설치해야 한다

버전이 달라지면 문제가 생긴다
이 서버는 어떤 상태인가?를 기억해야 한다

수동 배포	CI/CD
서버 상태 직접 관리	Docker / Runner 환경 고정
매번 수동 설치	미리 정의된 실행 환경

CI/CD는 서버 상태를 기억하지 않아도 되게 만드는 장치다

3. Git Clone & 코드 가져오기

git clone https://github.com/xxx/project.git cd project

브랜치를 잘못 받으면?
최신 코드인지 헷갈린다
커밋 기준이 애매하다

수동 배포	CI/CD
git clone 직접 실행	checkout step
어떤 커밋인지 직접 확인	특정 commit SHA 기준 실행

CI/CD는 항상 동일한 코드 상태로 배포되게 보장한다

4. 빌드 (Gradle)

./gradlew build

빌드 실패 → 원인 추적
성공해도 “이게 맞는 결과물인가?” 불안
로컬과 서버 결과가 다를 수도 있음

수동 배포	CI/CD
서버에서 직접 빌드	build job
성공/실패 수동 확인	pipeline status

CI/CD는 빌드 결과를 신뢰할 수 있게 만드는 장치다

5. 애플리케이션 실행

java -jar build/libs/app.jar

이전 프로세스가 남아 있으면?
포트 충돌 나면?
백그라운드 실행 관리가 번거롭다

수동 배포	CI/CD
java -jar 직접 실행	deploy step
프로세스 직접 관리	스크립트/컨테이너 기반 실행

CI/CD는 실행까지 포함한 배포 흐름을 책임진다

6. 로그 확인 & 검증

curl http://server/api/health tail -f log.txt

여기서 가장 치명적인 문제를 느꼈다.

에러가 코드 문제인지, 배포 문제인지 구분이 안 된다

수동 배포	CI/CD
서버에 접속해서 로그 확인	Job log
실패 원인 추적 어려움	단계별 실패 지점 명확

CI/CD는 문제의 위치를 바로 알 수 있게 만든다

GET

HS0601 — Mon, 19 Jan 2026 17:43:33 +0900

{
"success": true,
"message": "목록 조회 성공",
"data": {
    "items": [
        { "postId": 1, "title": "a", "content": "..." },
        { "postId": 2, "title": "b", "content": "..." }
        ],
            "page": 0,
            "size": 20,
            "totalElements": 132,
            "totalPages": 7,
            "hasNext": true
        }
}

메서드 : GET
URL 전체 목록 : GET /posts
특정 조건 목록(검색/필터) : GET /posts?keyword=…&status=…
내 글만 : GET /users/{userId}/posts 또는 GET /posts?authorId=…
GET은 RequestBody 거의 안 쓴다 대부분 Query Parameter로 조건을 전달한다

전체 조회에서 거의 무조건 필요한 3종 세트!

1) Pagination

전체를 진짜 다 주면 DB / 네트워크 터질 수 있어서 보통은 페이지 단위로 잘라서 준다

예를들어 GET /posts?page=0&size=20

page : 몇 번째 페이지(보통 0)
size : 한 페이지에 몇 개

2) Sort

예를들어 GET /posts?sort=createdAt, desc

createdAt 기준 내림차순

3) Filter/Search

예를들어 GET /posts?keyword=spring&authorId=3

응답 형태

내가 주로 만드는 공통 응답 포맷에 맞춰서 한다면,

{
  "success": true,
  "message": "목록 조회 성공",
  "data": {
    "items": [ // items: 실제 목록 데이터 배열
      { "postId": 1, "title": "a", "content": "..." },
      { "postId": 2, "title": "b", "content": "..." }
    ],
    "page": 0,
    "size": 20,
    "totalElements": 132, // totalElements: 전체 데이터 개수
    "totalPages": 7, // totalPages: 전체 페이지 수
    "hasNext": true // hasNext: 다음 페이지 존재 여부
  }
}

spring MVC Controller 예시

@GetMapping
public ResponseEntity<ApiResponse<PageResponse<PostListItem>>> findALl(
	@RequestParam(defaultValue = "0") int page,
	@RequestParam(defaultValue = "20") int size,
	@RequestParam(required = false) String keywrod
){
	return ResponesEntity.ok(...);
}

RequestParam은 URL의 ?page=00&size=20같은 값을 받는 방법

defaultValue는 값 안 주면 기본 값

requried = false 는 없어도 되는 옵션 파라미터 (검색어 등)

다 필요 없고 내가 왜 어려워 했냐면, 응답 포맷이 안그려져서다

HTTP/1.1 200 OK
Content-Type: application/json

이때 공통 응답 포맷 없이 그냥 반환 할 경우

{
  "items": [
    { "postId": 1, "title": "a" },
    { "postId": 2, "title": "b" }
  ],
		"page": 0,
		"size": 20,
		"totalElements": 132,
		"totalPages": 7
	}
}

쉽게 말해, 132개의 게시글(totalElements)을 size 20개 단위로 한다면 7페이지(totalPages)다

totalPages = ceil(132 / 20) = ceil(6.6) = 7

기억하자

{
  "items": [...],
  "page": 0,
  "size": 20,
  "totalElements": 132,
  "totalPages": 7
}

[아키텍처 패턴] CQRS

HS0601 — Mon, 19 Jan 2026 17:23:07 +0900

명령쿼리 책임 분리 패턴

상태를 변경하기 위한 명령을 위한 모델과 상태를 제공하는 조회(Query)를 위한 모델을 분리하는 패턴을 의미한다

예를들어 Order라는 리소스를 Order(명령용), OrderData(조회용) 2개의 모델로 나누어서 관리할 수 있다

Order — 명령용

OrderData — 조회용

이때 OrderData를 이용해서 표현계층에 데이터를 출력하는 데 사용하고

애플리케이션에서는 Order를 활용해 변경을 수행할 수 있다

CQRS 한 줄 정의

쓰기 (command)와 읽기 (Query)를 같은 모델/같은 설계로 억지로 처리하지 말고 아예 분리해서 각각 최적화하자는 패턴

Command : 주문 취소, 결게, 회원가입처럼 상태가 바뀜
Query : 주문서 조회, 사용자 목록처럼 상태를 읽기만 함

핵심은 책임 분리 (모델/코드/DB까지도 분리될 수 있음)

장단점

CQRS 패턴을 따르면, 소프트웨어의 유지보수성을 높일 수 있고 모델 별로 성능이나 요구사항에 맞는 데이터베이스나 데이터 접근 기술을 사용할 수 있다

예를들어 명령 모델은 트랜잭션이 지원되는 RDB를 사용하고 조회 모델은 조회 성능이 높은 NoSQL을 사용할 수 있다

왜 NoSQL은 조회를 잘 할까?

무조건 빠르다는 아니고 조회 패턴에 따라 유리한 경우가 많다는 말이다

조회가 빠를 수 있는 대표적인 이유로는

조인을 줄이고
수평 확장 — 샤딩
특정 목적 최소화
1. Redis — 메모리 기반 키-값 → 초고속 조회 / 캐시
2. Elasticsearch — 검색 / 집계에 최적화된 인덱스 구조

즉, 조회 전용 저장소를 조회에 맞게 설계 하면 빨라질 가능성이 큼

단, 해당 방식은 명령 모델의 변경을 조회 모델로 전파하여 동기화시켜야 할 필요가 있다 또 다른 예시로, 단일 데이터베이스의 테이블에 대해 CQRS 패턴을 사용한다고 가정할 때는 명령 모델은 도메인 모델을 구현하는 데 유리한 JPA를 사용하고 조회 모델에서는 SQL 데이터 조회에 유리한 MyBatis를 사용할 수 있다

하지만 CQRS 패턴은 구현 코드가 많고 더 많은 구현 기술이 필요하다는 점이 단점이다

단일 모델을 사용할 때 발생하는 복잡함 때문에 발생하는 구현 비용과 조회 전용 모델을 만들 때 발생하는 복잡함 때문에 발생하는 구현 비용을 비교해서 신중하게 도입을 결정해야 한다

장점: 책임 분리 → 변경이 덜 번짐 → 유지보수/확장/성능 튜닝에 유리
단점: 설계/코드/운영이 늘어남 → 팀/서비스 규모에 따라 오버엔지니어링 될 수 있음

[서버 라이프사이클] Graceful Shutdown

HS0601 — Mon, 19 Jan 2026 17:22:15 +0900

서버를 끌 때, 갑자기 꺼버리지 말고 안전하게 정리하고 꺼라

우아한 종료란

애플리케이션이 종료될 때 바로 종료하는 것이 아니라 현재 처리하고 있는 작업을 마무리하고 리소스를 정리한 이후 종료하는 방식을 의미한다

서버 애플리케이션에서 일반적인 Graceful Shutdown는 SIGTERM 신호를 받았을 때 새로운 요청은 차단하고 기존 처리 중인 요청을 모두 완료한 뒤에 프로세스를 종료한다

만약 서버 애플리케이션이 요청을 처리하는 중에 즉각적으로 애플리케이션을 종료한다면 트랜잭션 비정상 종료, 데이터 손실, 사용자 경험 저하 문제가 발생할 수 있다

SIGTERM VS SIGKILL

유닉스 및 리눅스 운영체제에서 사용되는 프로세스 종료 시그널이다

SIGKILL은 프로세스를 강제 종료하는 신호다 프로세스가 종료하기 전에 수행되어야 하는 절차들을 실행하지 않고 즉시 종료한다

SIGTERM은 프로세스가 해당 시그널을 핸들링할 수 있다

따라서 프로세스가 종료하기 이전에 수행되어야 하는 절차들을 안전하게 수행할 수 있다

OS(리눅스)가 프로세스(자바 앱)에게 끝내라~라고 말하는 방식이 시그널이고 그 종류가 SIGTERM / SIGKILL이다

SIGTERM — 15번

종료해줘 라는 요청에 가깝다

앱이 이 신호를 받아서 새 요청을 막고 진행 중인 요청 마무리하고 리소스 정리같은 걸 할 수 있다

SIGKILL — 9번

즉시 죽어라는 강제 종료다

앱이 절대 핸들링을 못한다 그 순간 바로 프로세스가 사라진다

그래서 Graceful Shotdown은 보통 SIGTERM을 받았을 때 동작하도록 설계한다

Graceful Shutdown이 실제로 서버에서 하는 일

SIGTERM이 들어오면 즉시 종료 대신 보통 이런 순서로 한다

새로운 요청을 더 이상 받지 않는다
- 로드밸런서/프록시가 빼주거나, 앱 자체가 커넥션/요청을 거절하도록 전환
이미 처리 중인 요청은 끝까지 처리한다
- 예를들어 DB 트랜잭션 commit/rollbace 마무리
리소스 정리한다
- DB 커넥션 풀, 스레드 풀, 메시지 소비자, 파일 핸들 등 close
프로세스 종료

Spring에서 Graceful Shutdown을 하는 방법은?

server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=20s // 타임 아웃

스프링은 Graceful Shutdow 설정을 지원해준다

단, 한가지 유의해야 할 부분이 있는데 기존 처리 중인 요청에서 데드락이나 무한 루프가 발생하면 프로세스가 종료되지 않을 수 있다 스프링은 이러한 상황을 예방하기 위해 타임아웃 설정을 지원한다

server.shutdown=graceful

스프링 부트(내장톰캣/제티/언더토우)가 종료 모드를 바꾼다

immediate — 기본이었던 시절

종료 신호 오면 바로 닫아버림 (진행 중 요청도 끊길 수 있다)

graceful — 종료 신호 오면 새 요청은 막고 진행 중 요청을 기다렸다가 종료

즉, 톰캣이 종료할 때 사용자 요청을 배려하는 모드로 바꿔라임

spring.lifecycle.timeout-per-shutdown-phase=20s

스프링은 종료할 때 내부적으로 단계를 나눠서 컴포넌트들을 순서대로 내린다

웹서버, 메시지 리스너, 스케줄러 등

근데 문제가 있다

어떤 요청이 무한루프
어떤 락이 풀리지 않아 데드락
외부 API가 안 돌아와서 계속 대기

근데 생각해보면 이런 설정 따로 안해줘도 잘만 됐다

스프링 부트 기본 종료 동작이랑 IDE/도커/쿠버네티스가 보내는 시그널 차이를 웹에서 확인해서 정리해보도록 한다

SpringBoot 4.0.1에서는 Graceful ShutDown이 기본 활성화다