minwoo95 님의 블로그

캠프 수료 후기!!

minwoo95 — Tue, 19 May 2026 20:14:12 +0900

긴 여정의 종착점에 서서 이렇게 수료 후기를 쓰고 있으니, 아직도 실감이 나지 않습니다.

마지막 프로젝트를 시작할 때만 해도, 주어진 기간에 비해 우리가 너무 욕심을 부린 건 아닐까 하는 걱정이 컸습니다. 그 걱정을 메워준 건 결국 팀원들이었습니다. 평일 늦은 밤에도, 주말에도 누구 먼저 손을 놓지 않고 자리를 지켜주셨고, 그 시간들이 쌓여 지금의 결과물이 될 수 있었습니다.

결과물의 완성도를 떠나, 우리가 함께 성장했고 그 과정을 즐겁게 마무리할 수 있었다는 것. 저는 그것이 이번 프로젝트가 저에게 남겨준 가장 큰 자산이라고 생각합니다. 물론 튜터님들께서 주신 피드백을 바탕으로 부족했던 부분은 리팩토링을 통해 계속 보완해 나갈 예정입니다 ㅋㅋ

늘 적극적이고 긍정적인 에너지로 임해 주신 팀원분들과 함께할 수 있어 영광이었고, 부족한 팀장을 끝까지 믿고 따라와 주신 모든 팀원분들께 진심으로 감사드립니다. 이 팀이어서 다행이었습니다.

그리고 이 자리를 빌려, 항상 열정으로 이끌어 주신 성규 튜터님, 원빈 튜터님, 석훈 튜터님, 선용 튜터님께 진심 어린 감사의 인사를 드립니다. 또 늘 옆에서 묵묵히 서포트해 주신 주희 매니저님께도 정말 감사드립니다. 튜터님들과 매니저님이 들 계셔서 이탈 없이 끝까지 완주할 수 있었습니다. 세 분이 아니셨다면 지금의 저도, 우리 팀도 없었을 겁니다.

진심으로 감사드립니다!

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 20

minwoo95 — Mon, 18 May 2026 22:23:48 +0900

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

Contribute to Hot6-NovelCraft/Hot6-NovelCraft development by creating an account on GitHub.

github.com

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

Contribute to MinWoo1995/Hot6-NovelCraft-local development by creating an account on GitHub.

github.com

최종 프로젝트 마지막 TIL — 멘토님 피드백을 받고

6주간 달려온 최종 프로젝트가 드디어 마무리됐다. 발표가 끝나고 멘토님께 받은 피드백을 곱씹어보면서, 단순히 "잘했다, 못했다"를 넘어서 앞으로 어떤 개발자로 성장해야 하는지에 대한 방향을 잡을 수 있었다. 오늘은 그 피드백을 정리하고, 내가 무엇을 느꼈는지를 기록으로 남겨두려고 한다.

칭찬받았던 부분들 — 무엇이 잘 통했나

먼저 멘토님이 좋게 봐주신 지점들이 있다. 단순히 기분 좋자고 적어두는 게 아니라, "왜 이 부분이 좋게 평가받았는지"를 정확히 인지해야 다음 프로젝트에서도 재현할 수 있기 때문에 정리해둔다.

1. 트러블슈팅의 서술 구조

가장 인상 깊었던 피드백은 "트러블슈팅이 '문제 → 원인 → 해결 → 결과'로 빠짐없이 정리되어 있다"는 점이었다. 사실 이건 처음부터 의도한 건 아니었고, 매번 문제가 터질 때마다 노션에 디버깅 로그를 쌓다 보니 자연스럽게 굳어진 포맷이었다. 이게 면접·발표에서 강력하게 작동한다는 걸 이번에 확실히 체감했다. 앞으로 어떤 프로젝트를 하든 이 포맷은 가져가야겠다.

2. "캐시가 항상 정답은 아니다"를 직접 겪은 경험

벌크 캐싱을 도입했더니 오히려 21배 느려진 사례. 캐시 히트율은 100%인데 왜 느릴까를 추적하다가 결국 원인은 역직렬화 오버헤드였다는 걸 발견했고, 핫키 임계값 기반 선별 캐싱으로 전환했다. 멘토님은 이 과정에서 "캐시가 항상 정답은 아니다"를 몸으로 배웠다는 점을 좋게 봐주셨다. 책에서 읽은 지식과 직접 깨진 경험은 무게가 완전히 다르다는 걸 새삼 느꼈다.

3. @Transactional + 분산락 해제 순서 버그

200명 동시 요청에 101명 참여 성공이 떨어졌던 그 버그. 락 해제 시점과 트랜잭션 커밋 시점 불일치를 원인으로 짚고, 3가지 선택지를 비교한 뒤 A안(트랜잭션 책임 분리)을 선택한 의사결정 과정 자체를 칭찬해주셨다. "해결책이 여러 개일 때 비교하고 근거를 적은 흔적이 남아 있는가" — 이게 단순 구현자와 엔지니어를 가르는 지점이라는 걸 다시 한번 느꼈다.

4. 결제 재검증 배치 설계

"웹훅은 best-effort 이벤트이므로 수신 보장을 전제로 설계하면 SPOF가 된다"는 문제 정의가 좋았다고 해주셨다. 단순히 "웹훅이 안 와서 폴링 붙였다"가 아니라, 외부 의존성을 어떻게 방어할 것인가라는 설계 원칙으로 추상화해서 설명할 수 있다는 점이 핵심이었다.

5. AI 리뷰 v1 → v2 비동기 전환

v1 실패율 92%의 원인을 "Mock 응답 딜레이에 의한 톰캣 스레드풀 고갈"로 분석한 것, 비동기 전환 후에도 분산락 + Kafka 멱등성 + Spring Retry로 안정성을 쌓은 구조까지 좋게 봐주셨다.

6. Chaos Engineering 기반 Redis Sentinel 검증

K6 + Grafana 데이터로 뒷받침한 점, 그리고 Cluster vs Sentinel 중에서 Sentinel을 선택한 근거가 "적정 기술 선택의 좋은 예시"라고 평가받았다. chaos-fallback-test에서 "Redis가 죽어도 무조건 200이 떨어져야 한다"는 시나리오까지 작성해둔 점도 언급해주셨다.

받은 지적 — 그리고 내가 놓치고 있었던 것

여기서부터가 진짜다. 칭찬은 기분 좋지만, 성장은 결국 지적받은 곳에서 일어난다.

1. 정량 목표(SLO)가 없었다

이게 가장 뼈아픈 지적이었다. 멘토님 말씀을 그대로 옮기자면,

"SLO 없는 부하테스트는 채점 기준 없이 시험만 본 것과 같다."

이 한 문장에 머리를 한 대 맞은 기분이었다.

생각해보면 나는 부하테스트를 정말 열심히 돌렸다. 레포에 K6 스크립트만 수십 개고, 시나리오도 다양하게 짰다. 그런데 정작 "P95 293ms가 합격인가 불합격인가"를 판단할 기준이 없었다. 그냥 "전보다 빨라졌으니 좋아진 것"이라는 식으로만 결과를 해석했다.

SLI (Service Level Indicator): 측정 가능한 지표 (예: P95 응답시간, 에러율)
SLO (Service Level Objective): 우리가 보장하려는 목표치 (예: P95 ≤ 200ms, 가용성 99.9%)
SLA (Service Level Agreement): 외부와 맺는 계약

이 셋 중에서 부하테스트의 합격선이 되는 건 SLO다. SLO가 있어야:

테스트 결과가 합격인지 불합격인지 판단할 수 있고
어떤 API부터 최적화해야 하는지 우선순위가 정해지고
이미 SLO를 충족한 부분은 더 이상 시간을 쓰지 않아도 된다는 판단이 선다

다음 프로젝트에서는 기획 단계에서부터 "우리 서비스가 사용자에게 보장하는 성능 기준이 무엇인가"를 먼저 정의하고 들어가야겠다.

2. 비즈니스 맥락이 빠져 있었다

두 번째 지적은 더 근본적인 문제였다. "AI 리뷰를 왜 도입했는가"에 대한 비즈니스 맥락이 없다는 것.

멘토님의 예시가 강력했다.

AI 리뷰의 목적이 "멘토 피드백의 시간 지연을 보완하는 것"이라면 → 품질보다 속도, 가벼운 모델 + 비동기가 맞다
AI 리뷰의 목적이 "멘토를 대체하는 것"이라면 → 속도보다 품질, 무거운 모델 + 동기 처리도 감수 가능

같은 기능인데 비즈니스 목적이 달라지면 아키텍처 선택이 완전히 달라진다.

면접에서 "왜 Kafka를 썼나요?"라는 질문에,

비즈니스 맥락 없는 답변: "비동기가 필요해서요."
비즈니스 맥락 있는 답변: "멘토 피드백 대기 시간을 줄이는 게 핵심이라 즉시 응답이 필요했는데, AI 호출이 6초 걸려서 동기로 가면 UX가 깨졌습니다. 그래서 Kafka로 비동기 처리하고 분산락 + 멱등성으로 안정성을 확보했습니다."

전달되는 무게가 완전히 다르다.

멘토님이 마지막에 정리해주신 말씀이 계속 머릿속에 남는다.

"AI 시대에 CS·코딩 역량은 기본기일 뿐이고, 그 위에서 차이를 만드는 것은 자기가 만든 서비스의 비즈니스를 얼마나 깊이 이해했는가다."

기술적 의사결정의 품질은 비즈니스 이해도에 비례한다는 말. 6주간 쌓은 기술적 의사결정들을 비즈니스 맥락과 다시 한번 연결해서 정리하는 작업이 남았다.

그리고 — 더 큰 규모로 부하테스트를 해보고 싶다

사실 이번 프로젝트에서 가장 아쉬웠던 부분 중 하나가 부하테스트 규모였다. 솔직히 말하면, 10만 명, 20만 명, 그 이상으로 쭉쭉 올려서 시스템이 어디서 무너지는지 직접 보고 싶었다. "이론적으로는 이 정도 트래픽까지 버틸 수 있다"가 아니라 "실제로 돌려봤더니 N만 RPS에서 X라는 병목이 터졌다"까지 가보고 싶었다.

그런데 두 가지 벽에 막혔다.

AWS 비용: 부하 생성기 인스턴스를 충분히 띄우고, 그걸 받아낼 백엔드 인프라까지 스케일업하면 시간당 비용이 만만치 않았다. 학생 프로젝트 예산에서는 감당이 어려웠다.
로컬 장비의 한계: 그렇다고 로컬에서 K6를 돌리자니, 부하 생성기 자체가 먼저 죽어버렸다. 부하를 받는 쪽이 아니라 부하를 주는 쪽이 먼저 병목이 되는 상황이 반복됐다.

그래서 적당히 타협한 수치 안에서 테스트를 마무리했는데, 멘토님 피드백을 받고 나니 이 미련이 다시 살아났다.

특히 SLO 얘기를 들으면서 깨달은 게 있다. 목표 기준이 명확하면, 그 기준을 넘어서는 지점까지 부하를 올려보는 것 자체가 의미 있는 실험이 된다. 단순히 "더 많은 트래픽을 견뎠다"가 아니라, "SLO를 깨뜨리는 변곡점이 어디인가", "그 변곡점에서 무엇이 먼저 무너지는가", "그걸 해결하면 다음 변곡점은 어디로 이동하는가"를 추적하는 실험.

이건 단순한 자랑용 수치가 아니라 시스템을 이해하는 도구다.

비용 문제는 AWS 프리티어 + 스팟 인스턴스 + 짧은 시간 집중 실행 같은 방식으로 어느 정도 우회할 수 있을 것 같고, 부하 생성기 한계는 K6의 분산 실행 모드(k6-operator on k8s)나 여러 EC2를 워커로 묶는 방식으로 풀어볼 수 있을 것 같다. 이번 프로젝트를 사이드로 계속 끌고 가면서 한번 도전해봐야겠다.

6주를 마치며

피드백을 곱씹어볼수록, 멘토님이 하신 말씀의 핵심은 결국 하나로 모인다.

"기술 그 자체에 매몰되지 말고, 그 기술이 풀려는 문제와 그 문제 뒤의 비즈니스를 봐라."

지난 6주 동안 나는 분산락을 걸고, Kafka를 붙이고, Redis Sentinel을 도입하고, 비동기 전환을 했다. 각각의 기술적 의사결정은 분명히 근거가 있었다. 그런데 그 근거들이 "어떤 비즈니스 문제를 풀기 위해"라는 한 줄로 꿰어져 있었는지는 다시 돌아봐야 한다.

SLO를 세우는 것도 같은 맥락이다. SLO는 결국 "사용자에게 어떤 경험을 보장할 것인가"라는 비즈니스적 약속의 수치화다. 기술과 비즈니스가 만나는 가장 명확한 지점.

다음 프로젝트에서는 코드를 한 줄 짜기 전에 이걸 먼저 정의하고 시작하려고 한다.

이 서비스의 핵심 사용자 가치는 무엇인가
그 가치를 지키기 위한 SLO는 무엇인가
각 기술 선택은 어떤 SLO를 어떻게 지키기 위함인가

6주간 정말 많이 배웠다. 좋은 팀원들, 좋은 멘토님 만나서 운이 좋았다.

발표 끝나고 받은 "고생 많으셨습니다"라는 한마디가, 의외로 오래 남는다.

이제 정말 마지막 TIL이지만, 진짜 공부는 여기서부터 시작인 것 같다.

해야할일

1.아키텍쳐 새로 그리기

2.리드미 손보기

3.이력서 작성하기

4.포트폴리오 작성하기

5.대규모 트래픽 테스트 진행하기

6.인프라 기능 추가하여 고도화하기

7.AI 고도화 다시한번 확인하기

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 19

minwoo95 — Tue, 12 May 2026 22:26:16 +0900

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

Contribute to Hot6-NovelCraft/Hot6-NovelCraft development by creating an account on GitHub.

github.com

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

Contribute to MinWoo1995/Hot6-NovelCraft-local development by creating an account on GitHub.

github.com

1. 오늘 한 일 (추가)

어제 배포 파이프라인 구축에 이어 오늘은 App EC2의 안정성을 높이기 위한 스왑 메모리 설정과, 팀원 코드 업데이트에 따른 재배포 작업을 진행했다.

App EC2 스왑 메모리 2GB 설정
팀원 docker-compose.yml 업데이트 반영 (Redis Sentinel 재구성)
Jenkinsfile에 kafka-2, kafka-3 추가
전체 컨테이너 초기화 후 재배포
헬스체크 최종 확인

2. 트러블슈팅

2-1. 스왑 메모리 설정 중 디스크 100% 초과

문제 상황

t3.small은 RAM이 2GB밖에 안 돼서 컨테이너가 많아지면 메모리 부족으로 서버가 먹통이 되는 현상이 반복됐다. 이를 해결하기 위해 스왑 메모리를 설정하려 했는데, 처음에 4GB로 설정하려다 디스크가 100%가 되어버렸다.

dd: error writing '/swapfile': No space left on device

원인 분석

App EC2 디스크가 8GB인데 Docker 이미지, 시스템 파일 등으로 이미 5GB 이상 사용 중이었다. 여기에 4GB 스왑 파일을 만들려다 디스크가 꽉 찼다.

해결

기존 스왑 파일을 삭제하고 2GB로 다시 설정했다.

bash

# 기존 스왑 제거
sudo swapoff /swapfile
sudo rm /swapfile
sudo sed -i '/swapfile/d' /etc/fstab

# 2GB 스왑 재설정
sudo dd if=/dev/zero of=/swapfile bs=128M count=16
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile swap swap defaults 0 0' | sudo tee -a /etc/fstab

설정 후 free -h로 확인하면 Swap 2GB가 추가된 것을 볼 수 있다. 재부팅 후에도 /etc/fstab에 등록했기 때문에 자동으로 스왑이 활성화된다.

2-2. 팀원 코드 업데이트 후 Redis Sentinel 재배포 필요

문제 상황

팀원이 Redis Sentinel 관련 설정을 변경해서 기존 컨테이너를 전부 내리고 새로 올려야 했다. 기존에 떠있던 컨테이너/볼륨에 오래된 데이터가 남아 있어 충돌이 발생할 수 있었다.

해결

App EC2에서 전체 컨테이너와 볼륨을 깔끔하게 정리하고 재배포했다.

bash

sudo docker stop $(sudo docker ps -aq) 2>/dev/null
sudo docker rm $(sudo docker ps -aq) 2>/dev/null
sudo docker volume prune -f
sudo docker system prune -af

정리 후 Jenkins 빌드 트리거로 새로 배포했다.

2-3. kafka-2, kafka-3 미실행으로 Kafka 연결 실패

문제 상황

배포 후 앱 로그에 아래와 같은 경고가 반복됐다.

Connection to node -1 (localhost/127.0.0.1:9092) could not be established.
Bootstrap broker localhost:9093 (id: -2 rack: null) disconnected
Bootstrap broker localhost:9094 (id: -3 rack: null) disconnected

원인 분석

Jenkinsfile의 docker-compose up 명령에 kafka-1만 포함되어 있었는데, 코드에서 KAFKA_BOOTSTRAP_SERVERS에 9092, 9093, 9094 세 개의 브로커가 등록되어 있어 kafka-2, kafka-3에도 연결을 시도했다.

해결

App EC2에서 직접 kafka-2, kafka-3을 올리고, Jenkinsfile도 수정해서 다음 배포부터는 자동으로 올라오게 했다.

bash

sudo docker-compose up -d kafka-2 kafka-3

groovy

# Jenkinsfile 수정
docker-compose up -d redis-master redis-sentinel-1 redis-sentinel-2 redis-sentinel-3 kafka-1 kafka-2 kafka-3 postgres-vector

3. 최종 배포 구성

헬스체크 결과

json

{
  "status": "UP",
  "components": {
    "db": {"status": "UP", "details": {"database": "MySQL"}},
    "diskSpace": {"status": "UP"},
    "ping": {"status": "UP"},
    "redis": {"status": "UP", "details": {"version": "7.4.9"}}
  }
}

App EC2 최종 실행 컨테이너

컨테이너포트역할

redis-master	6379	Redis 마스터
redis-sentinel-1	26379	Sentinel (HA)
redis-sentinel-2	26380	Sentinel (HA)
redis-sentinel-3	26381	Sentinel (HA)
kafka-1	9092	Kafka 브로커 1
kafka-2	9093	Kafka 브로커 2
kafka-3	9094	Kafka 브로커 3
postgres-vector	5432	PGVector (AI 벡터 저장소)
novelcraft	8080	Spring Boot 앱

메모리 현황

Mem:  1.9Gi total, 스왑 2.0Gi 추가
Disk: 8GB 중 약 5.8GB 사용 (2.3GB 여유)

4. 느낀 점

스왑 메모리 설정은 RAM이 부족한 서버에서 임시방편으로 사용할 수 있는 좋은 방법이지만, 디스크 용량도 함께 고려해야 한다는 걸 오늘 직접 겪으면서 배웠다. 스왑을 너무 크게 잡으면 디스크가 꽉 차고, 너무 작게 잡으면 메모리 부족 문제가 해결이 안 되니 적절한 크기를 산정하는 것이 중요하다.

팀 프로젝트에서 한 사람이 인프라 설정을 바꾸면 다른 팀원들의 배포 환경에도 영향이 가기 때문에, 변경 사항을 팀원들과 공유하고 재배포 절차를 함께 맞춰가는 것이 중요하다는 것도 다시 한번 느꼈다.

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 18

minwoo95 — Mon, 11 May 2026 23:12:39 +0900

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

Contribute to Hot6-NovelCraft/Hot6-NovelCraft development by creating an account on GitHub.

github.com

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

Contribute to MinWoo1995/Hot6-NovelCraft-local development by creating an account on GitHub.

github.com

1. 오늘 한 일

오늘은 개인 배포 환경(AWS EC2)에서 Jenkins + Docker를 통한 CI/CD 파이프라인을 구축하고, 실제로 애플리케이션을 배포하는 작업을 진행했다. 단순히 배포 스크립트를 작성하는 수준이 아니라, 발생하는 문제들을 하나씩 직접 추적하고 해결하는 과정이었다.

Jenkins EC2 / App EC2 2대 구성으로 CI/CD 파이프라인 설계
Jenkinsfile 작성 (Docker Build → Docker Push → SSH 배포)
docker-compose.yml로 Redis Sentinel, Kafka, PGVector 인프라 구성
App EC2 보안그룹 인바운드 규칙 설정
GitHub Webhook 연동으로 push 시 자동 빌드 트리거
EC2 t3.small 메모리 부족으로 인한 컨테이너 최소화 작업
총 40여 회의 빌드 시도 끝에 배포 파이프라인 완성

2. 트러블슈팅

2-1. scp 전송 stuck 문제 (20분 이상 멈춤)

문제 상황

Jenkins에서 App EC2로 docker-compose.yml, monitoring, init 폴더를 scp로 전송하는 단계에서 20분 이상 아무 응답 없이 멈추는 현상이 반복됐다.

원인 분석

App EC2 자체가 메모리 과부하 상태였다. Redis Sentinel 3개 + Redis Slave 2개 + Kafka 3개 + JMX Exporter 3개 + Prometheus + Grafana + PGVector + 앱까지 t3.small(RAM 2GB)에 올리려다 보니 컨테이너들이 CPU/메모리를 전부 점유해 SSH 연결 자체를 처리할 수 없는 상태가 됐다.

해결

AWS 콘솔에서 App EC2를 재부팅하고, Jenkinsfile의 docker-compose up 명령에서 모니터링 관련 컨테이너(Prometheus, Grafana, JMX Exporter 3개)를 제외하고 핵심 인프라만 올리도록 변경했다.

groovy

# 변경 전
docker-compose up -d

# 변경 후
docker-compose up -d redis-master redis-sentinel-1 redis-sentinel-2 redis-sentinel-3 kafka-1 postgres-vector

2-2. App EC2 IP 변경으로 SSH 연결 실패

문제 상황

App EC2를 재부팅하자 퍼블릭 IP가 기존 15.165.232.231에서 43.202.163.88로 변경됐다. Jenkinsfile의 APP_EC2_IP 값이 이전 IP를 바라보고 있어서 SSH 연결이 계속 타임아웃됐다.

원인 분석

AWS EC2는 탄력적 IP(Elastic IP)를 붙이지 않으면 재부팅 시 퍼블릭 IP가 바뀐다. 또한 App EC2 보안그룹에 등록된 Jenkins EC2 IP도 함께 업데이트하지 않아 이중으로 연결이 막혔다.

해결

Jenkinsfile의 APP_EC2_IP를 43.202.163.88로 수정
App EC2 보안그룹 인바운드 규칙에서 Jenkins EC2 IP를 새 IP(15.165.208.252)로 업데이트
GitHub Webhook Payload URL도 새 Jenkins IP로 업데이트

2-3. monitoring 폴더가 파일 대신 디렉토리로 생성된 문제

문제 상황

scp로 monitoring 폴더를 전송할 때 아래 에러가 반복됐다.

dest open("/home/ec2-user/monitoring/prometheus.yml"): Failure
Uploading of file monitoring/prometheus.yml to /home/ec2-user/monitoring/prometheus.yml failed!
Couldn't setstat on "/home/ec2-user/monitoring": Permission denied

원인 분석

App EC2의 ~/monitoring/ 폴더 안에 prometheus.yml과 kafka-jmx-config.yml이 파일이 아니라 디렉토리로 생성되어 있었다. 이전에 잘못된 방식으로 폴더가 만들어진 것이 원인이었다.

bash

# 실제 상태 (파일이 아니라 디렉토리)
drwxr-xr-x. 2 root root 6 May 11 10:37 kafka-jmx-config.yml
drwxr-xr-x. 2 root root 6 May 11 10:37 prometheus.yml

해결

App EC2에서 해당 폴더를 삭제하고 Jenkins 재빌드로 정상 파일로 다시 전송했다.

bash

sudo rm -rf ~/monitoring
sudo rm -rf ~/init

2-4. EC2 재부팅 후 redis6 서비스 자동 시작으로 6379 포트 충돌

문제 상황

EC2 재부팅 후 docker-compose up 실행 시 아래 에러가 발생했다.

Error response from daemon: driver failed programming external connectivity on endpoint redis-master:
Error starting userland proxy: listen tcp4 0.0.0.0:6379: bind: address already in use

원인 분석

Amazon Linux 2023에는 redis6 패키지가 기본 설치되어 있으며, systemd 서비스로 등록되어 있다. EC2 재부팅 시 redis6 서비스가 자동으로 시작되면서 6379 포트를 선점하고, docker-compose의 redis-master 컨테이너가 같은 포트를 사용하려다 충돌이 발생했다.

해결

redis6 서비스를 중지하고 자동 시작을 비활성화했다.

bash

sudo systemctl stop redis6
sudo systemctl disable redis6

2-5. BankVerificationClient 빈 누락으로 앱 기동 실패

문제 상황

배포 후 애플리케이션 로그에 아래 에러가 반복됐다.

No qualifying bean of type 'BankVerificationClient' available:
expected at least 1 bean which qualifies as autowire candidate.

원인 분석

LocalBankVerificationClient 클래스에 @Profile({"dev", "local", "test"})가 붙어있었는데, prod 프로파일이 누락되어 있었다. prod 환경에서는 해당 빈이 등록되지 않아 BankAccountService 생성에 실패했다.

java

// 문제 코드
@Profile({"dev", "local", "test"})
public class LocalBankVerificationClient implements BankVerificationClient {

해결

@Profile에 prod를 추가했다.

java

// 수정 후
@Profile({"dev", "local", "test", "prod"})
public class LocalBankVerificationClient implements BankVerificationClient {

2-6. 환경변수 없이 컨테이너 수동 실행으로 JWT 키 누락

문제 상황

Jenkins 빌드가 충돌 문제로 컨테이너를 올리지 못해 수동으로 docker run을 실행했는데, -e 옵션 없이 실행해버려 아래 에러가 발생했다.

Could not resolve placeholder 'jwt.secret.key' in value "${jwt.secret.key}"

원인 분석

Jenkinsfile에는 JWT, DB, Redis, Kafka 등 28개의 환경변수가 -e 옵션으로 주입되는데, 수동으로 컨테이너를 올릴 때는 환경변수가 전혀 없는 상태였다.

해결

수동으로 올린 컨테이너를 삭제하고 Jenkins 빌드를 다시 트리거해서 환경변수가 모두 포함된 상태로 컨테이너를 올렸다.

bash

sudo docker stop novelcraft
sudo docker rm novelcraft
# Jenkins 지금 빌드 클릭

2-7. PGVector(postgres-vector) 미실행으로 vectorStore 연결 실패

문제 상황

앱 로그에 아래 에러가 반복됐다.

Error creating bean with name 'vectorStore': Failed to obtain JDBC Connection

원인 분석

Jenkinsfile의 docker-compose up 명령에서 postgres-vector를 누락했다. AI 채팅 기능의 vectorStore가 PGVector에 의존하는데, 해당 컨테이너가 떠있지 않아 JDBC 연결에 실패했다.

해결

App EC2에서 직접 postgres-vector를 올리고 앱을 재시작했다.

bash

sudo docker-compose up -d postgres-vector
sudo docker restart novelcraft

3. 주요 구현 내용

CI/CD 파이프라인 아키텍처

GitHub push
    ↓ Webhook
Jenkins EC2 (15.165.208.252)
    ├─ Checkout (GitHub)
    ├─ Docker Build (gradle:8.5-jdk17 → eclipse-temurin:17-jdk-jammy)
    ├─ Docker Push (DockerHub: jmw1995/novelcraft)
    └─ Deploy to App EC2 (SSH)
            ├─ scp: docker-compose.yml, monitoring, init 전송
            ├─ docker-compose up -d (핵심 인프라만)
            ├─ docker stop/rm novelcraft
            ├─ docker pull jmw1995/novelcraft:latest
            └─ docker run (환경변수 28개 주입)

App EC2 최종 실행 컨테이너 구성

컨테이너포트역할

redis-master	6379	Redis 마스터
redis-sentinel-1	26379	Sentinel (HA)
redis-sentinel-2	26380	Sentinel (HA)
redis-sentinel-3	26381	Sentinel (HA)
kafka-1	9092	Kafka 브로커
postgres-vector	5432	PGVector (AI 벡터 저장소)
novelcraft	8080	Spring Boot 앱

Prometheus, Grafana, JMX Exporter, Redis Slave, kafka-2, kafka-3은 t3.small 메모리 한계로 제외했다.

Jenkinsfile 환경변수 주입 구성

Jenkins Credentials에 등록된 28개의 민감정보를 배포 시 docker run에 -e 옵션으로 주입했다. DB URL/계정, Redis Sentinel 노드, Kafka Bootstrap Servers, JWT/AES 키, OAuth 클라이언트 ID/Secret, PortOne, CoolSMS, 외부 API 키 등이 포함됐다.

4. 느낀 점

오늘 하루 동안 40회가 넘는 빌드를 시도하면서 배포가 이렇게 험난한 과정인지 처음으로 체감했다. 로컬에서 잘 돌아가는 코드가 운영 환경에서는 전혀 다른 문제들을 만난다는 것을 직접 겪었다.

가장 고통스러웠던 부분은 t3.small 메모리 한계였다. RAM 2GB에 Redis, Kafka, PGVector, 모니터링까지 올리려 하다 보니 서버가 과부하 상태에서 SSH 연결조차 안 되는 상황이 반복됐다. 결국 모니터링 컨테이너를 제외하고 핵심 인프라만 올리는 방식으로 타협했는데, 운영 환경에서 스펙 산정이 얼마나 중요한지 뼈저리게 느꼈다.

또한 배포 자동화 스크립트는 작은 실수 하나가 큰 문제로 이어진다는 것도 배웠다. 수동으로 컨테이너를 올리면서 환경변수를 빠뜨린 것처럼, 자동화된 파이프라인이 아닌 수동 조작은 항상 실수의 여지가 있다. CI/CD 파이프라인의 중요성을 다시 한번 실감했다.

다음 단계로는 postgres-vector도 Jenkinsfile의 docker-compose up 명령에 포함시켜 완전 자동화하고, EC2 재부팅 시에도 컨테이너가 자동으로 올라올 수 있도록 restart 정책을 정비할 예정이다.

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 17

minwoo95 — Fri, 8 May 2026 22:00:21 +0900

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

Contribute to Hot6-NovelCraft/Hot6-NovelCraft development by creating an account on GitHub.

github.com

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

Contribute to MinWoo1995/Hot6-NovelCraft-local development by creating an account on GitHub.

github.com

1. 오늘 한 일

오늘은 AI 이미지 생성 SDK 연동과 Kafka 설정이 완료된 상태에서, 빠져있던 Grafana 모니터링 환경을 처음부터 끝까지 구축했다.

Spring Boot Actuator + Micrometer Prometheus 의존성 추가 및 application.yml 설정
docker-compose.yml에 Kafka JMX Exporter 3개 추가 (kafka-1 / kafka-2 / kafka-3)
Kafka 브로커 3개에 JMX 포트 환경변수 설정 (KAFKA_JMX_PORT: 9999, KAFKA_JMX_HOSTNAME)
monitoring/kafka-jmx-config.yml 작성 (JMX 메트릭 수집 룰 정의)
monitoring/prometheus.yml Kafka 스크랩 타겟 3개 추가
Prometheus → Grafana 데이터소스 연결 (http://prometheus:9090)
Grafana 대시보드 Import (Spring Boot 19004, Kafka 7589)
Prometheus Targets 전체 UP 상태 확인 (novelcraft / kafka-1 / kafka-2 / kafka-3)

2. 트러블슈팅

2-1. Spring Boot 3.3.5에서 management.endpoint.prometheus.enabled 빨간불

문제 상황

application.yml에 아래와 같이 Prometheus 설정을 작성했더니 IDE에서 빨간불이 들어왔다.

yaml

management:
  endpoint:
    prometheus:
      enabled: true

원인 분석

Spring Boot 3.3.x에서는 enabled 속성이 deprecated 되어 해당 키 자체가 제거됐다. micrometer-registry-prometheus 의존성이 classpath에 있으면 /actuator/prometheus 엔드포인트가 자동으로 활성화되기 때문에 별도로 enabled를 선언할 필요가 없어졌다.

해결

enabled 관련 설정을 전부 제거하고 아래와 같이 정리했다.

yaml

management:
  endpoints:
    web:
      exposure:
        include: health, prometheus, metrics, info
  endpoint:
    health:
      show-details: always
  metrics:
    tags:
      application: novelcraft

의존성만 있으면 자동 활성화된다는 점을 다시 한번 확인했다.

2-2. GRAFANA_ADMIN_PASSWORD 환경변수 누락으로 docker-compose 실행 실패

문제 상황

docker-compose up -d 실행 시 아래 에러가 발생했다.

error while interpolating services.grafana.environment.GF_SECURITY_ADMIN_PASSWORD:
required variable GRAFANA_ADMIN_PASSWORD is missing a value: set GRAFANA_ADMIN_PASSWORD

원인 분석

기존 docker-compose.yml의 Grafana 설정이 아래와 같이 환경변수를 필수로 강제하는 방식이었다.

yaml

GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:?set GRAFANA_ADMIN_PASSWORD}

로컬에 .env 파일이 없어서 해당 변수를 찾지 못해 실행 자체가 차단됐다.

해결

프로젝트 루트에 .env 파일을 생성하고 값을 추가했다.

GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=admin

.env 파일은 민감정보가 포함될 수 있으므로 .gitignore에 등록되어 있는지 반드시 확인해야 한다.

2-3. Prometheus Targets에서 Kafka 타겟이 보이지 않음

문제 상황

http://localhost:9095/targets 에 접속했을 때 novelcraft 타겟만 UP 상태로 보이고 Kafka 타겟은 아예 표시되지 않았다.

원인 분석

prometheus.yml의 Kafka 스크랩 타겟을 아래와 같이 host.docker.internal로 설정했는데, Kafka JMX Exporter는 도커 컨테이너 내부에 떠있기 때문에 host.docker.internal로는 접근이 불가능했다.

yaml

# 잘못된 설정
- job_name: 'kafka'
  static_configs:
    - targets: ['host.docker.internal:5556']

Spring Boot 앱은 도커 외부(로컬)에서 실행되므로 host.docker.internal이 맞지만, JMX Exporter는 도커 네트워크 내부 서비스이므로 컨테이너 서비스명으로 접근해야 했다.

해결

prometheus.yml을 아래와 같이 컨테이너 서비스명 기준으로 수정하고 Prometheus를 재시작했다.

yaml

scrape_configs:
  - job_name: 'novelcraft'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['host.docker.internal:8080']   # 앱은 로컬 실행이므로 host.docker.internal

  - job_name: 'kafka-1'
    static_configs:
      - targets: ['kafka-1-jmx-exporter:5556']   # JMX Exporter는 도커 내부 서비스명

  - job_name: 'kafka-2'
    static_configs:
      - targets: ['kafka-2-jmx-exporter:5556']

  - job_name: 'kafka-3'
    static_configs:
      - targets: ['kafka-3-jmx-exporter:5556']

bash

docker-compose restart prometheus

재시작 후 Targets 페이지에서 kafka-1 / kafka-2 / kafka-3 모두 UP 상태를 확인했다.

3. 주요 구현 내용

최종 모니터링 아키텍처

Spring Boot App (로컬:8080)
    └─ /actuator/prometheus
            ↓
        Prometheus (도커:9095)
            ├─ novelcraft job   → host.docker.internal:8080
            ├─ kafka-1 job      → kafka-1-jmx-exporter:5556
            ├─ kafka-2 job      → kafka-2-jmx-exporter:5556
            └─ kafka-3 job      → kafka-3-jmx-exporter:5556
                ↓
            Grafana (도커:3000)
                ├─ Spring Boot 3.x Statistics (ID: 19004)
                └─ Kafka Exporter Overview    (ID: 7589)

docker-compose.yml 변경 사항 (팀원 영향 최소화)

기존 구조를 최대한 유지하면서 아래 항목만 추가했다.

kafka-1 / kafka-2 / kafka-3 환경변수에 KAFKA_JMX_PORT: 9999, KAFKA_JMX_HOSTNAME 2줄 추가
kafka-1-jmx-exporter, kafka-2-jmx-exporter, kafka-3-jmx-exporter 서비스 3개 신규 추가
Prometheus depends_on에 JMX Exporter 3개 추가

신규 오픈 포트: 5556, 5557, 5558

monitoring/ 폴더 구조

monitoring/
├── prometheus.yml
└── kafka-jmx-config.yml

kafka-jmx-config.yml은 JMX 메트릭 수집 룰을 정의하는 파일로, 이 파일이 없으면 JMX Exporter 컨테이너가 뜨지 않는다. 팀원들이 docker-compose up 할 때 반드시 해당 파일이 있어야 하므로 함께 커밋했다.

Grafana 대시보드 결과

Spring Boot 3.x Statistics: Uptime, Heap Used(2.9%), Non-Heap Used(17.8%), CPU Usage, Load Average 등 실시간 수집 확인
Kafka Exporter Overview: 현재 메시지 발행/소비가 없어 No data 상태이며, 실제 트래픽 발생 시 데이터가 채워질 예정

4. 느낀 점

모니터링 환경 구축은 처음이라 설정 하나하나가 낯설었는데, 막상 Grafana 대시보드에 메트릭이 실시간으로 찍히는 걸 보니 뿌듯했다.

가장 헷갈렸던 부분은 도커 네트워크 개념이었다. Spring Boot 앱처럼 도커 외부에서 실행되는 서비스는 host.docker.internal로 접근해야 하고, JMX Exporter처럼 도커 내부 컨테이너는 서비스명으로 접근해야 한다는 점이 처음엔 직관적으로 와닿지 않았다. 타겟이 안 보이는 현상을 보고 직접 원인을 추적하면서 도커 네트워크 구조를 제대로 이해하게 됐다.

팀 프로젝트에서 docker-compose.yml을 수정할 때는 기존 구조를 얼마나 건드리지 않을 수 있느냐가 중요하다는 것도 느꼈다. 처음에는 과감하게 수정했다가 팀원 영향을 고려해서 최소한의 변경만 남기는 방향으로 다시 정리했는데, 공유 인프라 파일을 다룰 때는 항상 팀원 관점에서 먼저 생각해야 한다는 걸 다시 한번 깨달았다.

다음 단계로는 실제로 Kafka 메시지가 발행/소비될 때 Grafana 대시보드에서 Consumer Lag, Message In/Out per second 등이 어떻게 보이는지 확인해볼 예정이다.

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 16

minwoo95 — Thu, 7 May 2026 20:53:19 +0900

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

Contribute to Hot6-NovelCraft/Hot6-NovelCraft development by creating an account on GitHub.

github.com

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

Contribute to MinWoo1995/Hot6-NovelCraft-local development by creating an account on GitHub.

github.com

1. 오늘 한 일

오늘은 NovelCraft 프로젝트에서 AI 소설 표지 생성 기능을 동기 방식에서 Kafka 기반 비동기 처리로 고도화하고, 코드래빗 PR 리뷰를 반영하여 방어 로직을 강화했다.

Google Gemini API 연동 기반 AI 소설 표지 생성 기능 구현
동기 방식(30초 블로킹) → Kafka 비동기 처리로 개선 (응답 시간 30초 → 150ms)
CoverJob 엔티티 추가 (PENDING → PROCESSING → COMPLETED/FAILED 상태 추적)
CoverGenerationProducer 구현 (Kafka 토픽 발행)
CoverGenerationConsumer 구현 (Gemini 재시도 3회, S3 재시도 3회, 포인트 환불)
CoverJobEventRelay 구현 (@TransactionalEventListener(AFTER_COMMIT) 적용)
표지 생성 상태 조회 API 추가 (GET /api/ai/novels/cover/status/{jobId})
작가 권한 + 본인 소설 검증 + 300포인트 차감 로직 구현
코드래빗 리뷰 5개 항목 반영 (중복 이벤트 방어, 포인트 차감 플래그, 상태 전이 가드 등)
CoverService, CoverGenerationConsumer, CoverJob 단위 테스트 작성 (커버리지 100%)

2. AI 소설 표지 생성 기능 구현

기술 선택 - Gemini vs DALL-E 3

초기에는 DALL-E 3로 구현했으나 한국어 텍스트 렌더링이 깨지는 문제가 있었다. Google Gemini(gemini-2.5-flash-image)로 교체하자 한국어 제목과 작가명이 이미지에 완벽하게 렌더링됐다.

Gemini API는 이미지를 바이트 배열로 반환하는 구조라 DALL-E 3처럼 URL을 바로 반환하지 않는다. 따라서 S3에 직접 업로드하고 영구 URL을 반환하는 방식으로 구현했다.

프롬프트 설계

소설 DB에서 제목, 작가 닉네임, 장르, 줄거리를 자동으로 조회해 프롬프트에 주입한다.

java

String.format(
    "Create a professional Korean novel cover image. " +
    "The title '%s' must be written clearly and legibly at the top in large, stylish Korean typography. " +
    "Below the title, write the author name '%s 지음' in smaller Korean text. " +
    "Genre: %s. Story summary: %s. " +
    "Style: cinematic, high quality book cover art.",
    novel.getTitle(), authorName, novel.getGenre(), novel.getDescription()
)

3. Kafka 비동기 처리 고도화

왜 동기 방식이 문제였나

Gemini API 호출은 평균 20~30초가 소요된다. 동기 방식으로 처리하면 해당 스레드가 30초간 블로킹되어 톰캣 스레드 풀이 고갈될 위험이 있고, 다른 API 요청에도 영향을 미친다.

왜 @Async가 아닌 Kafka인가

단순 비동기 처리라면 @Async로도 가능하지만 Kafka를 선택한 이유는 세 가지다.

첫째, 메시지 영속성이다. 서버가 재시작되더라도 Kafka 브로커에 메시지가 남아있어 처리가 재개된다. @Async는 서버 재시작 시 처리 중인 작업이 유실된다.

둘째, 프로젝트에 Kafka가 이미 알림 시스템에 도입되어 있어 추가 인프라 없이 일관된 아키텍처를 유지할 수 있었다.

셋째, Consumer를 독립적으로 스케일아웃할 수 있는 구조다.

왜 AWS Lambda가 아닌 Kafka인가

Lambda도 좋은 선택지지만 이 프로젝트에서 Kafka를 선택한 이유는 다음과 같다. Lambda는 Cold Start 문제가 있어 첫 요청 시 수초의 지연이 발생할 수 있는데, Gemini API 자체가 이미 30초가 걸리는 상황에서 추가 지연은 부담이었다. 또한 Lambda + API Gateway + SQS 조합은 설정 복잡도가 높아 팀 프로젝트 일정상 Kafka가 현실적인 선택이었다.

처리 흐름

POST /api/ai/novels/{novelId}/cover
    ↓ 즉시 jobId 반환 (150ms)
CoverService → CoverJob 저장 → ApplicationEventPublisher.publishEvent()
    ↓ 트랜잭션 커밋 후
CoverJobEventRelay (@TransactionalEventListener AFTER_COMMIT)
    ↓
CoverGenerationProducer → Kafka 토픽 발행
    ↓
CoverGenerationConsumer
    → PENDING 상태 가드 (중복 이벤트 방어)
    → PROCESSING 상태 전이
    → Gemini 호출 (재시도 3회)
    → S3 업로드 (재시도 3회)
    → 포인트 차감 (isDeducted 플래그)
    → COMPLETED 상태 전이
    → 실패 시 FAILED + 포인트 환불 (차감된 경우에만)

GET /api/ai/novels/cover/status/{jobId}
    → PENDING / PROCESSING / COMPLETED / FAILED 조회

폴링 방식

현재는 클라이언트가 주기적으로 상태 조회 API를 호출하는 폴링 방식으로 구현했다. 개선 방향으로는 프로젝트에 이미 WebSocket이 알림 시스템에 도입되어 있으므로 서버에서 완료 시점에 Push하는 방식으로 전환할 수 있다.

4. 코드래빗 리뷰 반영

4-1. 중복 Kafka 이벤트 방어 (Major)

같은 jobId에 대한 중복 메시지가 도착할 경우 상태 검증 없이 모든 작업을 반복 실행하는 문제가 있었다. 포인트가 여러 번 차감될 수 있는 치명적인 버그다.

java

// 수정 전 - 가드 없음
job.processing();

// 수정 후 - PENDING 상태에서만 처리
if (job.getStatus() != CoverJobStatus.PENDING) {
    log.warn("[Cover] 이미 처리된 Job 스킵 jobId={} status={}", event.jobId(), job.getStatus());
    return;
}

4-2. 포인트 차감 전 실패 시 환불 방지 (Critical)

포인트 차감은 Gemini/S3 성공 후에 이루어지는데, 기존 catch 블록에서 차감 여부와 무관하게 무조건 charge()를 호출하고 있었다. Gemini/S3 단계에서 실패하면 차감도 안 됐는데 포인트가 그냥 증가하는 버그였다.

java

boolean isDeducted = false;

pointService.deduct(event.userId(), COVER_COST);
isDeducted = true;

// catch 블록에서
if (isDeducted) {
    pointService.charge(event.userId(), COVER_COST); // 차감된 경우에만 환불
}

4-3. complete/fail 시 반대 필드 정리 (Major)

complete() 호출 시 이전에 설정된 errorMessage가 남아있거나, fail() 호출 시 coverImageUrl이 남아있어 조회 응답에 혼합 상태가 노출될 수 있는 문제였다.

java

public void complete(String coverImageUrl) {
    this.status = CoverJobStatus.COMPLETED;
    this.coverImageUrl = coverImageUrl;
    this.errorMessage = null; // 추가
}

public void fail(String errorMessage) {
    this.status = CoverJobStatus.FAILED;
    this.errorMessage = errorMessage;
    this.coverImageUrl = null; // 추가
}

4-4. Kafka 발행 실패 시 PENDING 영구 정체 (Major)

Kafka 발행이 실패하면 Job이 PENDING 상태로 영구히 남는 문제가 있었다. 발행 실패를 상위로 전파하거나 즉시 FAILED로 전환해야 한다.

java

try {
    eventPublisher.publishEvent(new CoverJobCreatedEvent(jobId, novelId, userId));
} catch (Exception e) {
    job.fail("Kafka 발행 실패");
    coverJobRepository.save(job);
    throw e;
}

4-5. 트랜잭션 커밋 전 Kafka 발행 (Major)

CoverJob을 저장한 직후 Kafka를 발행하면, Consumer가 메시지를 소비했을 때 트랜잭션이 아직 커밋되지 않아 DB에서 jobId를 찾지 못하는 경우가 발생할 수 있다. 알림 시스템의 NotificationEventRelay 패턴을 참고해 @TransactionalEventListener(AFTER_COMMIT)으로 해결했다.

java

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onCoverJobCreated(CoverJobCreatedEvent event) {
    coverGenerationProducer.publish(
            new CoverGenerationEvent(event.jobId(), event.novelId(), event.userId())
    );
}

5. 트러블슈팅

5-1. Gemini 1.5 Flash로 변경했으나 404 오류

Gemini AI에게 "이미지 생성이 가능한 모델을 알려달라"고 물어보니 gemini-1.5-flash를 추천했다. 변경 후 테스트했으나 아래 오류가 발생했다.

404 Not Found. models/gemini-1.5-flash is not found for API version v1beta, 
or is not supported for generateContent.

Gemini 1.5 Flash는 텍스트 전용 모델이라 이미지 생성 자체가 불가능하다. 이미지 생성은 gemini-2.5-flash-image 모델을 사용해야 하며, 해당 모델은 무료 API 티어에서는 호출이 불가하다. AI Studio 웹 UI에서는 무료로 사용 가능하지만 API 호출은 별도 과금 구조다.

해결: Google AI Studio에서 결제 등록 후 gemini-2.5-flash-image 모델 사용

5-2. S3 업로드 후 Access Denied

S3 업로드는 성공했으나 이미지 URL 접근 시 Access Denied XML 응답이 반환됐다.

xml

<Error>
  <Code>AccessDenied</Code>
  <Message>Access Denied</Message>
</Error>

원인: 버킷 정책에 퍼블릭 GetObject 허용 설정이 누락됐다.

해결: S3 버킷 정책에 아래 내용 추가

json

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::hot6-novelcraft-minwoo/*"
        }
    ]
}

5-3. point_histories.type 컬럼 Data truncated 오류

AI_COVER 타입을 PointHistoryType enum에 추가했으나 실제 API 호출 시 500 에러가 발생했다.

SQL Error: 1265, SQLState: 01000
Data truncated for column 'type' at row 1

원인: point_histories.type 컬럼이 VARCHAR(10)으로 정의되어 있어 8자인 AI_COVER가 저장되지 않았다.

해결:

sql

ALTER TABLE point_histories MODIFY COLUMN type VARCHAR(20) NOT NULL;

엔티티에도 명시적으로 length 추가

java

@Column(nullable = false, length = 20)
@Enumerated(value = EnumType.STRING)
private PointHistoryType type;

5-4. 기존 CoverService 코드와 포인트 중복 차감

Consumer에서 포인트 차감을 처리하는데 CoverService에도 포인트 선차감 로직이 남아있어 이중 차감이 발생할 수 있었다.

해결: CoverService에서 포인트 차감 로직 전체 제거. 포인트 처리는 Consumer에서만 담당하도록 단일 책임 원칙을 적용했다.

5-5. CoverServiceTest - ArgumentCaptor가 값을 캡처하지 못하는 문제

No argument value was captured!
You might have forgotten to use argument.capture() in verify()

원인: CoverService가 CoverGenerationProducer를 직접 호출하는 방식에서 ApplicationEventPublisher를 통한 이벤트 발행 방식으로 변경됐는데, 테스트 코드의 Mock 및 검증 대상이 업데이트되지 않았다.

해결:

java

// 기존
@Mock private CoverGenerationProducer coverGenerationProducer;
verify(coverGenerationProducer).publish(any(CoverGenerationEvent.class));

// 수정
@Mock private ApplicationEventPublisher eventPublisher;
verify(eventPublisher).publishEvent(any(CoverJobCreatedEvent.class));

6. 오늘의 회고

오늘 하루 동안 단순한 AI API 연동에서 시작해 Kafka 비동기 처리까지 고도화하면서 여러 가지를 배웠다.

설계 관점에서 외부 API 호출처럼 시간이 오래 걸리는 작업은 동기 방식으로 처리하면 안 된다는 것을 다시 한번 체감했다. 30초 블로킹이 단순히 사용자 경험의 문제가 아니라 서버 자원 고갈로 이어질 수 있다는 점이 핵심이었다.

Kafka와 @Async의 차이에 대해서도 명확하게 정리됐다. @Async는 구현이 간단하지만 서버 재시작 시 메시지 유실이 발생한다. Kafka는 복잡도가 높지만 메시지가 브로커에 영속화되어 장애 상황에도 재처리가 가능하다. 어떤 것이 절대적으로 옳은 것이 아니라 상황에 따라 트레이드오프를 이해하고 선택하는 것이 중요하다.

코드래빗 리뷰에서 다섯 가지 문제를 지적받았는데, 그중 Critical 항목인 "차감 전 실패에도 무조건 환불" 버그는 실제 서비스라면 사용자 포인트가 의도치 않게 증가하는 치명적인 문제였다. 테스트 코드가 이런 엣지 케이스를 잡아낼 수 있도록 시나리오를 촘촘하게 작성하는 것의 중요성을 다시 깨달았다.

오늘의 AI 이미지 생성 연결 결과물!

프롬포트를 작성하는게 아니라, 이미 가지고 있는 소설 정보를 바탕으로 알아서 자동생성해주는 기능으로 구현완료!

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 15

minwoo95 — Wed, 6 May 2026 22:03:57 +0900

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

Contribute to Hot6-NovelCraft/Hot6-NovelCraft development by creating an account on GitHub.

github.com

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

Contribute to MinWoo1995/Hot6-NovelCraft-local development by creating an account on GitHub.

github.com

1. 오늘 한 일

오늘은 NovelCraft 프로젝트에서 AI 도메인 중 소설 표지 생성 기능을 담당하여 OpenAI DALL-E 3 API를 Spring Boot에 처음으로 도입했다.

AI 도메인 패키지 구조 설계 (ai/cover 독립 패키지)
OpenAI Java SDK 의존성 추가 및 API 키 설정
DallEClient 구현 (DALL-E 3 API 호출 전담)
CoverService 구현 (소설 정보 DB 조회 → 프롬프트 자동 생성 → 이미지 생성)
CoverController 구현 (POST /api/ai/novels/{novelId}/cover)
CoverExceptionEnum 구현 (공통 예외 패턴 적용)
Postman으로 로컬 테스트 완료 (DALL-E 응답 성공 확인)

2. 트러블슈팅

2-1. Optional.get()에 인덱스 인자를 넣어 컴파일 에러 발생

문제 상황

DallEClient에서 DALL-E 응답의 이미지 URL을 꺼내는 코드를 아래와 같이 작성했다.

java

return response.data().get(0).url()
        .orElseThrow(() -> CoverExceptionEnum.IMAGE_GENERATION_FAILED.toException());

컴파일 시 아래 에러가 발생했다.

method get in class Optional<T> cannot be applied to given types;
required: no arguments
found: int

원인 분석

OpenAI Java SDK에서 response.data()의 반환 타입이 List<Image>가 아닌 Optional<List<Image>>였다. Optional의 get()은 인자를 받지 않는데 인덱스 0을 넣어버리니 타입 불일치 에러가 발생한 것이다.

해결

response.data() 자체가 Optional이므로 먼저 orElseThrow()로 꺼낸 뒤 리스트 인덱스로 접근하도록 수정했다.

java

return response.data()
        .orElseThrow(() -> CoverExceptionEnum.IMAGE_GENERATION_FAILED.toException())
        .get(0)
        .url()
        .orElseThrow(() -> CoverExceptionEnum.IMAGE_GENERATION_FAILED.toException());

SDK를 처음 사용할 때는 반환 타입을 IDE에서 직접 확인하는 습관이 필요하다는 것을 느꼈다.

2-2. S3 업로드 403 에러 (The request signature does not match)

문제 상황

DALL-E 호출은 성공했지만 이후 S3 업로드 단계에서 아래 에러가 발생했다.

S3Exception: The request signature we calculated does not match the signature you provided.
Status Code: 403

원인 분석

로컬 테스트 환경에서 S3 액세스 키 권한 문제로 서명 불일치가 발생한 것이었다. DALL-E가 반환하는 임시 URL을 S3에 업로드하는 흐름이었는데, 로컬에서는 S3 연동 자체가 불필요한 상황이었다.

해결

로컬 테스트 단계에서는 S3 업로드 없이 DALL-E가 반환한 임시 URL을 그대로 반환하도록 수정했다. DALL-E URL은 1시간 후 만료되지만 로컬 테스트 목적으로는 충분하다. 실제 배포 시에는 S3 업로드 로직을 복구할 예정이다.

java

public CoverCreateResponse generateCover(Long novelId) {
    Novel novel = novelRepository.findByIdAndIsDeletedFalse(novelId)
            .orElseThrow(() -> CoverExceptionEnum.NOVEL_NOT_FOUND.toException());

    String prompt = buildPrompt(novel);
    String imageUrl = dallEClient.generateImage(prompt);  // DALL-E URL 바로 반환

    return CoverCreateResponse.of(novelId, imageUrl);
}

3. 주요 구현 내용

패키지 구조

ai/cover/
├── controller/  CoverController
├── service/     CoverService
├── client/      DallEClient
├── dto/
│   ├── request/   CoverCreateRequest
│   └── response/  CoverCreateResponse
└── exception/   CoverExceptionEnum

프롬프트 자동 생성 전략

클라이언트에서 별도 요청 파라미터 없이 novelId만 받아서 DB에서 소설 정보를 조회한 뒤 프롬프트를 자동으로 구성했다. no text, no letters 지시어를 반드시 포함해야 이미지에 깨진 글자가 생성되지 않는다는 점을 알게 됐다.

java

private String buildPrompt(Novel novel) {
    return String.format(
            "Create a professional Korean novel cover image. " +
            "Title: %s, Genre: %s. " +
            "Story summary: %s. " +
            "Style: cinematic, high quality book cover art, no text, no letters.",
            novel.getTitle(),
            novel.getGenre(),
            novel.getDescription()
    );
}

API 엔드포인트

POST /api/ai/novels/{novelId}/cover
Authorization: Bearer {JWT}

→ 응답
{
    "success": true,
    "status": "200",
    "message": "소설 표지가 성공적으로 생성되었습니다",
    "data": {
        "novelId": 1,
        "coverImageUrl": "https://..."
    }
}

4. 느낀 점

AI API를 Spring Boot에 처음 도입해봤는데 생각보다 구조 자체는 단순했다. 외부 API 클라이언트를 별도 client 레이어로 분리하니 서비스 코드가 깔끔하게 유지됐다.

DALL-E 3는 응답 시간이 평균 20초 이상 걸린다는 점이 인상적이었다. 실서비스라면 비동기 처리나 로딩 UX가 반드시 필요하다는 걸 체감했다.

이미지에 제목이나 작가명을 자연스럽게 넣는 것은 DALL-E만으로는 한계가 있다는 점도 알게 됐다. 실제 서비스에서는 배경 이미지 생성 후 프론트엔드에서 텍스트를 합성하는 방식이 가장 현실적이라는 결론을 팀원들과 공유했다.

AI 기능은 구현 자체보다 어떤 프롬프트를 어떻게 구성하느냐가 품질을 좌우한다는 것을 느꼈다. 앞으로 프롬프트 엔지니어링도 백엔드 개발자가 알아야 할 중요한 역량이 될 것 같다.

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 14

minwoo95 — Mon, 4 May 2026 21:22:39 +0900

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

Contribute to Hot6-NovelCraft/Hot6-NovelCraft development by creating an account on GitHub.

github.com

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

Contribute to MinWoo1995/Hot6-NovelCraft-local development by creating an account on GitHub.

github.com

오늘 작업 요약

NovelCraft 웹소설 창작 플랫폼 포트폴리오 증거 자료 확보를 위해 다음 항목들을 진행했다.

Prometheus + Grafana 모니터링 구축
이벤트 참여 동시성 부하테스트 (Redisson 분산락)
수익 환전 동시성 부하테스트 (Redis SETNX 분산락)
멘토링 멘티 수락 동시성 테스트 (낙관적 락)
멘토링 피드백 V1/V2 동시성 비교 (비관적 락)
revenues 인덱스 성능 비교
캐시 성능 비교 (이벤트 목록 / 수익 통계 / 도서 검색)
Redis Record 클래스 역직렬화 버그 수정

1. Prometheus + Grafana 모니터링 구축

배경

이벤트 참여 부하 테스트를 돌리면서 Grafana 대시보드로 실시간 지표를 캡처해 포트폴리오 증거 자료로 남기려고 구축했다. "동시 200명 요청, 정합성 100%, 평균 응답 Xms"를 Grafana 대시보드 스크린샷 한 장으로 증명하는 게 말 백 마디보다 강력하다.

구성도

Spring Boot (IntelliJ 실행)
    ↓ /actuator/prometheus 노출
Prometheus (Docker, 포트 9095)
    ↓ 15초마다 scrape
Grafana (Docker, 포트 3000)
    ↓ 시각화 대시보드

1단계: build.gradle 의존성 추가

gradle

implementation 'org.springframework.boot:spring-boot-starter-actuator'
runtimeOnly 'io.micrometer:micrometer-registry-prometheus'

2단계: application.yml 설정 추가

yaml

management:
  endpoints:
    web:
      exposure:
        include: health, prometheus, metrics
  endpoint:
    health:
      show-details: always
  metrics:
    tags:
      application: novelcraft

3단계: SecurityConfig + JwtFilter 수정

Actuator 엔드포인트가 Security 필터와 JwtFilter에 막혀 있어서 두 곳 모두 수정이 필요했다.

SecurityConfig .requestMatchers 부분에 추가:

java

, "/actuator/**"

JwtFilter shouldNotFilter 메서드에 추가:

java

|| path.startsWith("/actuator")

4단계: docker-compose.yml에 Prometheus + Grafana 추가

기존 Kafka 3노드 클러스터가 있는 docker-compose.yml에 두 컨테이너를 추가했다.

yaml

prometheus:
  image: prom/prometheus:latest
  container_name: prometheus
  ports:
    - "9095:9090"   # Kafka-2가 9093 포트를 사용해 9095로 설정
  volumes:
    - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
    - prometheus_data:/prometheus
  networks:
    - kafka-net

grafana:
  image: grafana/grafana:latest
  container_name: grafana
  ports:
    - "3000:3000"
  environment:
    GF_SECURITY_ADMIN_USER: admin
    GF_SECURITY_ADMIN_PASSWORD: admin
  volumes:
    - grafana_data:/var/lib/grafana
  depends_on:
    - prometheus
  networks:
    - kafka-net

5단계: prometheus.yml 설정

yaml

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'novelcraft'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['host.docker.internal:8080']

host.docker.internal은 Docker 컨테이너에서 Mac 로컬의 Spring Boot 앱에 접근할 수 있게 해주는 주소다.

6단계: Grafana 대시보드 구성

http://localhost:3000 접속 (admin/admin)
Connections → Data Sources → Prometheus 추가
URL: http://prometheus:9090 (컨테이너 내부 통신이라 localhost가 아닌 컨테이너 이름 사용)
Dashboards → Import → ID 4701 (Spring Boot 전용 대시보드) 임포트
Application 변수: Query에 label_values(application) 입력 → novelcraft 확인
Instance 변수: Query에 label_values(jvm_info, instance) 입력

트러블슈팅: Prometheus 포트 충돌

기본 포트 9090이 Kafka-2 브로커와 충돌할 수 있어 호스트 포트를 9095로 변경했다. Grafana에서 Prometheus 연결 시에는 내부 컨테이너 통신이라 prometheus:9090을 사용한다.

트러블슈팅: Grafana Application 변수 설정

4701 대시보드 임포트 후 Application 드롭다운에 아무것도 안 떴다. 변수 설정에서 Target data source가 비어 있어서 발생. Variables → Application → Target data source를 Prometheus로 선택하고 Query에 label_values(application) 입력 후 novelcraft가 나타나면 성공이다. Instance 변수도 동일하게 label_values(jvm_info, instance) 입력.

2. 이벤트 참여 동시성 부하테스트 (Redisson 분산락)

시나리오

maxParticipants=100인 이벤트에 200명이 동시에 참여 신청. 정확히 100명만 참여가 성공하는지 데이터 정합성 검증.

k6 시나리오 구성

두 가지 시나리오를 동시에 실행했다.

javascript

export const options = {
    scenarios: {
        // 시나리오 1: 동시 참여 신청 (200명 동시 요청)
        spike_participate: {
            executor: 'shared-iterations',
            vus: 200,        // 동시 가상 유저 200명
            iterations: 200, // 총 200번 요청 (유저당 1번)
            maxDuration: '60s',
            exec: 'participateTest',
        },
        // 시나리오 2: 조회 API 지속 부하 (Grafana 수치 확보용)
        sustained_read: {
            executor: 'constant-vus',
            vus: 50,         // 동시 가상 유저 50명
            duration: '30s', // 30초 동안 지속
            startTime: '0s',
            exec: 'readTest',
        },
    },
};

shared-iterations: 200개의 iteration을 200개의 VU가 나눠서 처리. 각 VU는 로그인 후 이벤트 참여 요청 1회 실행.
constant-vus: 50명이 30초 동안 계속 이벤트 목록/상세 조회를 반복해 Grafana에 의미 있는 트래픽 생성.

테스트 유저: loadtest1~200@test.com (200명, BCrypt 해싱 후 DB에 사전 삽입)

Before (분산락 버그 있는 버전)

문제: @Transactional과 Redisson 분산락 해제 순서 버그

java

// 잘못된 코드: 트랜잭션 커밋 전에 락이 해제됨
@Transactional
public void participate(Long eventId, Long userId) {
    RLock lock = redissonClient.getLock("event:" + eventId);
    lock.lock();
    try {
        // DB 로직...
    } finally {
        lock.unlock(); // 여기서 락 해제 → 트랜잭션은 아직 커밋 안 됨
    }
    // 메서드 종료 시 @Transactional이 커밋 → 이미 락 해제 후라 다른 요청이 진입 가능
}

결과: 101명 참여 → 정합성 깨짐

After (분산락 Fix)

해결: @Transactional 제거 후 락 안에서 별도 서비스 메서드 호출

java

// UserEventService - @Transactional 제거
public void participate(Long eventId, Long userId) {
    RLock lock = redissonClient.getLock("event:" + eventId);
    // leaseTime을 3초에서 10초로 증가
    boolean acquired = lock.tryLock(5, 10, TimeUnit.SECONDS);
    if (!acquired) throw new CustomException(ErrorCode.TOO_MANY_REQUESTS);
    try {
        eventParticipateService.execute(eventId, userId); // 별도 @Transactional 서비스
    } finally {
        lock.unlock(); // 트랜잭션 커밋 완료 후 락 해제
    }
}

// EventParticipateService - @Transactional 적용
@Transactional
public void execute(Long eventId, Long userId) {
    // DB 로직 처리 후 커밋 완료
}

부하테스트 결과 (After)

총 요청:    200명
참여 성공:  100명 (✅ maxParticipants와 정확히 일치)
참여 실패:  100명 (maxParticipants 초과)
정합성:     100% PASS

Grafana 관측 수치 (k6 실행 중)

지표수치

RPS (초당 요청 수)	약 40 req/s
CPU 사용률	74.3%
JVM 스레드 수	295개
GC Pause 시간	1.72ms

실행전

실행후

3. 수익 환전 동시성 부하테스트 (Redis 분산락)

시나리오

잔액 100만원인 작가가 동시에 10번 전액 환전 요청. 정확히 1건만 성공해야 한다.

k6 시나리오 구성

javascript

spike_withdrawal: {
    executor: 'shared-iterations',
    vus: 10,        // 동시 가상 유저 10명 (같은 유저가 10번)
    iterations: 10,
    maxDuration: '30s',
}

방어 메커니즘

1차 방어: Redis SETNX 분산락

java

String lockKey = "lock:withdrawal:" + authorId;
String lockValue = UUID.randomUUID().toString();
Boolean acquired = redisTemplate.opsForValue()
    .setIfAbsent(lockKey, lockValue, 5, TimeUnit.SECONDS);

단순 get 후 delete는 비원자적이라 다른 요청의 락을 실수로 해제할 수 있다. Lua Script로 비교와 삭제를 하나의 원자적 연산으로 처리했다.

lua

if redis.call('get', KEYS[1]) == ARGV[1] then
    return redis.call('del', KEYS[1])
else
    return 0
end

2차 방어: PENDING 상태 중복 체크

결과

총 요청:    10건
환전 성공:  1건 (✅)
환전 실패:  9건 (잔액 부족)
잔액:       0원
정합성:     100% PASS

4. 멘토링 멘티 수락 동시성 테스트 (낙관적 락)

시나리오

멘토 1명(maxMentees=3)에게 PENDING 상태의 멘토십 10개에 대해 동시에 수락 요청.

k6 설정

javascript

spike_accept: {
    executor: 'shared-iterations',
    vus: 10,
    iterations: 10,
    maxDuration: '30s',
}

동작 원리 (낙관적 락)

java

@Entity
public class Mentor {
    @Version
    private Integer version;
}

10건이 동시에 같은 Mentor 엔티티의 version(0)을 읽고, 첫 번째 커밋만 성공하면서 version이 1로 증가한다. 나머지 9건은 version 불일치로 OptimisticLockingFailureException이 발생해 실패한다.

결과

ACCEPTED: 1건 (✅)
PENDING:  9건
maxMentees: 2 (1 차감됨)
version: 1 (낙관적 락 버전 증가 확인)

재시도 로직이 없어 1건만 성공했지만 슬롯 초과 없이 정합성이 100% 유지됐다.

포트폴리오 스토리

동시 10건 수락 요청에서 낙관적 락(@Version)이 동시성 충돌을 감지하여 1건만 성공. maxMentees 초과 없이 정합성 100% 유지.

5. 멘토링 피드백 V1/V2 동시성 비교 (비관적 락)

시나리오

멘토가 ACCEPTED 상태의 멘토십에 동시에 5건 피드백 작성. sessionNumber(회차 번호) 중복 없이 순서대로 저장되는지 확인.

k6 설정

javascript

spike_feedback: {
    executor: 'shared-iterations',
    vus: 5,
    iterations: 5,
    maxDuration: '30s',
}

V1 결과 (동시성 보호 없음)

총 요청: 5건
피드백 성공: 1건
피드백 실패: 4건 (유니크 제약 위반으로 400 에러)
오류 메시지: "데이터 저장에 실패하였습니다" (모호한 에러)

문제: 5건이 모두 같은 sessionNumber(1)로 저장 시도. DB 유니크 제약에 의해 첫 번째만 통과하고 나머지는 모호한 에러가 반환된다. 사용자 입장에서 왜 실패했는지 알 수 없다.

V2 결과 (비관적 락 적용)

총 요청: 5건
피드백 성공: 5건 (✅)
sessionNumber: 1, 2, 3, 4, 5 (중복 없이 순서대로)
totalSessions: 5

해결: findByIdWithLock()으로 멘토링 row에 SELECT FOR UPDATE(비관적 락)를 걸어 요청을 직렬화. 각 요청이 이전 요청의 커밋 후 totalSessions를 읽어 다음 sessionNumber를 계산한다.

Before/After 비교

항목V1V2

성공 건수	1	5
실패 이유	유니크 제약 위반 → 모호한 에러	-
sessionNumber 처리	중복 시도 → DB가 막음	비관적 락으로 직렬화
사용자 경험	4건 "데이터 저장 실패"	모두 정상 처리

Before 결과

After 결과

6. revenues 인덱스 성능 비교

목적

revenues 테이블에 10만 건 더미 데이터를 삽입하고, 인덱스 추가 전후 쿼리 성능을 EXPLAIN ANALYZE로 비교한다.

더미 데이터 생성

loadtest 유저 50명 × 각 2000건 = 총 10만 건 삽입

추가한 인덱스

sql

CREATE INDEX idx_revenue_author_type ON revenues (author_id, type);
CREATE INDEX idx_revenue_author_type_date ON revenues (author_id, type, created_at);

결과 비교

쿼리 1: 수익 현황 집계

항목BeforeAfter

실행 시간	24.7ms	1.15ms
스캔 방식	Full Table Scan (100,015건)	Index Lookup
개선율	-	약 21배

쿼리 2: 월별 수익 통계

항목BeforeAfter

실행 시간	16.2ms	1.29ms
스캔 방식	Full Table Scan	Index Range Scan
개선율	-	약 12배

쿼리 3: 수익 TOP 10 집계 (트레이드오프)

항목BeforeAfter

실행 시간	32.3ms	54ms
결과	-	오히려 느려짐

전체 테이블을 type 기준으로 집계하는 쿼리는 어차피 모든 행을 읽어야 하기 때문에 인덱스가 도움이 안 된다. 오히려 인덱스 스캔 오버헤드가 추가돼 더 느려졌다. 인덱스는 선택도(selectivity)가 높은 컬럼에 효과적이다.

적용전

적용후

7. 캐시 성능 비교

7-1. 이벤트 목록 조회 캐시

API: GET /api/events?status=ONGOING&page=0&size=10
캐시: RedisTemplate, TTL 5분

Cache Miss (DB 조회): 33.5ms
Cache Hit  (Redis):   6.6ms
개선율: 약 5배 (80.3%)
checks: 10/10 성공

7-2. 수익 통계 조회 캐시

API: GET /api/revenues/me/statistics?period=MONTHLY&year=2026
캐시: RedisTemplate, TTL 1시간
데이터: revenues 10만 건 + GROUP BY 집계 쿼리

Cache Miss (DB 집계): 181.5ms
Cache Hit  (Redis):    6.1ms
개선율: 약 7.4배 (86.5%)
checks: 10/10 성공

GROUP BY + 집계 쿼리는 데이터가 많을수록 DB 조회가 느리기 때문에 캐시 효과가 가장 극적으로 나왔다.

7-3. 도서 검색 캐시 (국립도서관 외부 API)

API: GET /api/v1/national-library/books/search?query=스프링&page=1&size=10
캐시: RedisTemplate, TTL 10분
특징: 국립도서관 외부 API 호출

Cache Miss (외부 API): 231.9ms
Cache Hit  (Redis):     43.8ms
개선율: 약 2배 (53.1%)
checks: 10/10 성공

Cache Hit이 43ms로 다른 API에 비해 느린 이유는 응답 크기가 27kB로 크기 때문이다.

캐시 성능 비교 종합

APICache MissCache Hit개선율

이벤트 목록 조회	33.5ms	6.6ms	약 5배
수익 통계 조회	181.5ms	6.1ms	약 7.4배
도서 검색	231.9ms	43.8ms	약 2배

8. Redis Record 클래스 역직렬화 버그 수정

문제 발견

수익 현황 조회 캐시 테스트 중 두 번째 요청부터 500 에러 발생.

SerializationException: Could not read JSON:
Unexpected token (START_OBJECT), expected START_ARRAY:
need Array value to contain `As.WRAPPER_ARRAY` type information

원인 분석

GenericJackson2JsonRedisSerializer가 Redis에 저장할 때 타입 정보 없이 순수 JSON으로 저장한다. 꺼낼 때 Jackson이 타입을 알 수 없어 LinkedHashMap으로 역직렬화한다. 이를 RevenueOverviewResponse로 강제 캐스팅하면 ClassCastException이 발생한다.

activateDefaultTyping(NON_FINAL) 옵션으로 해결하려 했지만 Java Record 클래스는 final로 컴파일되기 때문에 해당 옵션이 적용되지 않는다.

해결 방법

ObjectMapper로 직접 직렬화/역직렬화한다.

java

// 저장 시 (JSON 문자열로 직렬화)
String json = objectMapper.writeValueAsString(response);
redisTemplate.opsForValue().set(cacheKey, json, CACHE_TTL);

// 조회 시 (JSON 문자열로 역직렬화)
Object cached = redisTemplate.opsForValue().get(cacheKey);
if (cached instanceof String jsonStr) {
    return objectMapper.readValue(jsonStr, RevenueOverviewResponse.class);
}

RevenueService와 StatisticsService 두 곳에 적용했다. RedisConfig는 팀원 영향 없이 원래대로 복구했다.

핵심 교훈

Redis에 Java Record 클래스를 캐싱할 때는 GenericJackson2JsonRedisSerializer의 자동 역직렬화가 동작하지 않는다. ObjectMapper로 명시적으로 직렬화/역직렬화해야 한다.

9. k6 VUs(Virtual Users) 설정 개념 정리

shared-iterations: 총 N개의 iteration을 M개의 VU가 나눠서 처리. 동시 참여처럼 정확히 N번의 요청을 보내야 할 때 사용.

constant-vus: M명의 VU가 duration 동안 계속 반복 요청. 지속적인 부하를 주고 싶을 때 사용. Grafana에 의미 있는 트래픽 패턴을 만들기 위해 사용.

이벤트 참여 부하테스트에서 두 시나리오를 동시에 실행한 이유:

spike_participate(VUs 200, iterations 200): 정합성 검증 목적
sustained_read(VUs 50, duration 30s): Grafana 수치 확보 목적

두 시나리오가 동시에 실행되어 Grafana에서 RPS 40 req/s, CPU 74.3%, 스레드 295개, GC 1.72ms를 관찰했다.

10. 트러블슈팅 모음

트러블슈팅 1: MySQL @변수 세션 문제
SQL 파일 실행 시 세션 변수가 초기화되지 않아 데이터 미삽입. Subquery 방식으로 변경해 해결.

트러블슈팅 2: k6 한글 파라미터 인코딩
query=스프링 직접 입력 시 인코딩 문제로 checks 0% 발생. URL 인코딩 값 %EC%8A%A4%ED%94%84%EB%A7%81 사용으로 해결.

트러블슈팅 3: Redis Record 역직렬화
섹션 8 참고.

트러블슈팅 4: NovelStatus enum 값 불일치
더미 SQL에서 'SERIALIZING' 사용 → 실제 enum은 'ONGOING'. SELECT DISTINCT status FROM novels;로 확인 후 수정.

트러블슈팅 5: Grafana 변수 Target data source 미설정
4701 대시보드 임포트 후 Application 드롭다운이 비어 있었음. Variables 편집에서 Target data source를 Prometheus로 수동 선택해야 한다.

11. 최종 포트폴리오 증거 자료 정리

모니터링 구축	Prometheus + Grafana 대시보드 캡처
이벤트 참여 동시성 (분산락)	k6 결과 + DB 100건 정확 + Grafana 수치 (RPS 40, CPU 74.3%)
수익 환전 동시성 (Redis 분산락)	k6 결과 + DB 1건 정확
멘토링 수락 동시성 (낙관적 락)	k6 결과 + DB ACCEPTED 1건 + version=1 증가
피드백 V1/V2 비교 (비관적 락)	k6 결과 + DB sessionNumber 1~5
revenues 인덱스 성능	EXPLAIN ANALYZE Before/After (21배, 12배, 트레이드오프)
이벤트 목록 캐시	k6 결과 (33ms → 6.6ms, 5배)
수익 통계 캐시	k6 결과 (181ms → 6.1ms, 7.4배)
도서 검색 캐시	k6 결과 (231ms → 43ms, 2배)

12. Kafka 도입 스토리 정리

도입 배경

기존에는 이벤트 참여, 멘토링 수락 등 여러 도메인에서 알림 발송을 동기로 처리했다.

문제점:

강결합: 알림 발송 실패 시 핵심 비즈니스 로직도 함께 실패
성능 저하: 알림 처리 시간이 API 응답 시간에 포함됨
OOM 위험: 이벤트 생성 시 전체 READER 유저를 한 번에 조회하면 수만 명일 경우 OOM 발생 위험

Kafka 도입으로 해결한 것

기존: 이벤트 참여 → [알림 발송] → 응답 반환  (동기, 실패 시 롤백)

도입 후: 이벤트 참여 → 응답 반환 (빠름)
                  ↓ ApplicationEventPublisher
              @TransactionalEventListener(AFTER_COMMIT)
                  ↓ 트랜잭션 커밋 후 Kafka 발행
              알림 Consumer (비동기)

대량 알림 발송 시에는 전체 READER 유저를 1000건씩 페이지 단위로 배치 조회하여 순차적으로 이벤트를 발행한다.

왜 @Async가 아닌 Kafka인가?

항목@AsyncKafka

메시지 유실	서버 재시작 시 유실	디스크 영속화로 보존
재처리	별도 구현 필요	Consumer 재시작으로 재처리
확장성	JVM 내부 스레드 풀 한계	Consumer Group으로 수평 확장
모니터링	어려움	토픽/파티션/오프셋으로 추적 가능

알림 유실 없이 안정적으로 처리해야 하고, 향후 여러 Consumer(이메일, 앱 푸시, SMS 등)로 확장 가능한 구조가 필요했기 때문에 Kafka를 선택했다.

안정성과 확장성을 위한 고도화 고민

Kafka 도입으로 비동기 처리와 도메인 간 결합도 해제라는 큰 성과를 얻었지만, 시스템의 신뢰도를 100%로 끌어올리기 위해 다음의 고도화 전략들을 고민하고 있다.

1. 데이터 유실 제로를 위한 'Transactional Outbox Pattern'

현재는 AFTER_COMMIT 시점에 이벤트를 발행하여 정합성을 맞추고 있다. 하지만 아주 희박한 확률로 DB 커밋은 성공했으나 Kafka 발행 직전 네트워크 장애가 발생할 경우 메시지가 유실될 수 있다. 이를 완벽히 방지하기 위해 비즈니스 데이터와 메시지를 하나의 트랜잭션으로 DB(Outbox Table)에 저장하고, 별도 프로세스가 발행을 보장하는 패턴을 검토 중이다.

2. 예외 상황의 격리와 재처리를 위한 'DLT(Dead Letter Topic)'

비동기 처리 중 Consumer에서 예상치 못한 에러가 발생했을 때, 무한 재시도로 인해 전체 시스템이 지연되는 것을 막아야 한다. 실패한 메시지는 별도의 Dead Letter Topic으로 격리하여 장애 원인을 분석하고, 정상화 이후 해당 메시지만 선별적으로 재처리할 수 있는 운영 프로세스를 구상하고 있다.

3. 대규모 트래픽 대비 'Cursor 기반 페이징 & 병렬 처리'

수만 명의 유저에게 알림을 보낼 때, 현재의 페이지 단위 조회를 더욱 최적화하기 위해 ID 기반 Cursor 페이징을 적용하여 조회 성능을 유지하고자 한다. 또한, 알림량이 늘어날 경우 Kafka의 Partition을 확장하고 Consumer Group의 인스턴스를 수평 확장(Scale-out)하여 처리량을 극대화하는 설계를 염두에 두고 있다.

마치며 모든 프로젝트에 이런 고도로 복잡한 패턴이 정답은 아닐 것이다. 하지만 서비스가 성장함에 따라 마주칠 병목 구간을 미리 예측하고, 그에 맞는 아키텍처를 제시할 수 있는 능력이 진정한 기술적 깊이라고 믿는다. 단순히 기술을 '사용'하는 것을 넘어, 시스템의 전체적인 흐름과 운영의 안정성을 책임지는 개발자로 성장해 나가고자 한다.

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 13

minwoo95 — Fri, 1 May 2026 14:10:29 +0900

도메인별 적용 기술 정리하기

튜터님 피드백 및 방향성

[캘린더]

POST /api/calendars/me/records — 독서 기록 등록
적용 기술
CalendarExceptionEnum: PLATFORM 출처인데 서재 미등록 시 BOOK_NOT_IN_LIBRARY 예외 발생 → 400 반환
PK 직접 참조: Library 테이블에서 userId + novelId로 서재 등록 여부 확인, 연관관계 없이 PK로 조회

GET /api/calendars/me/records — 독서 기록 조회
적용 기술
QueryDSL 동적 쿼리: date, novelId가 선택값이므로 BooleanExpression으로 null 조건 자동 제외
PageResponse: 페이징 처리하여 content, totalElements, totalPages 등 반환
PK 직접 참조: novelId, userId를 외래키로 직접 참조해 조회

GET /api/calendars/me — 독서 캘린더 조회
적용 기술
CalendarExceptionEnum: 조회 범위 1년 초과 시 DATE_RANGE_TOO_LARGE → 400 반환
GlobalExceptionHandler + MissingServletRequestParameterException 핸들러: startDate 누락 시 500 대신 400 반환

GET /api/calendars/me/statistics — 월간 통계 조회
적용 기술
CalendarExceptionEnum: 미래 달 조회 시 INVALID_STAT_DATE → 400 반환
JPQL @Query: 월별 집계(총 페이지, 완독 수, 독서일 수 등) 단순 집계 쿼리는 JPA로 처리
MonthlyStatResponse Record: 집계 결과를 Record 클래스 DTO로 반환

이유
통계 조회는 복잡한 동적 조건보다는 month, year가 고정된 단순 집계이므로 QueryDSL 대신 JPQL @Query로 처리했습니다. 복잡도에 맞는 기술을 선택하는 것이 팀 컨벤션이고, 오버엔지니어링을 방지합니다. 미래 달 조회 제한은 존재하지 않는 데이터에 대한 불필요한 쿼리를 사전 차단하기 위한 방어 로직입니다.

N+1, 반복 쿼리 발생을 방지, 불필요한 조인 줄이고 응답 일관성 확보, 복합 유니크 제약과 어플리케이션 중복검사 ==> 중복 서재 등록 방지

--------------------------------------------------------------------------------------------------------

[내서제]
POST /api/libraries — 내서재 담기
적용 기술 1. 메타데이터 스냅샷 저장
문제: 소설 정보(제목, 작가명, 표지)는 작가가 수정할 수 있어서 담기 시점 이후에 변경될 수 있습니다. Novel 테이블을 매번 Join하면 수정된 데이터가 담기 시점과 다르게 노출되고 불필요한 Join 비용이 발생합니다.

해결: 담기 시점의 novelTitle, authorNickname, coverImageUrl을 Library 테이블에 직접 저장합니다. 이후 조회 시 Novel 테이블 Join 없이 Library 단독으로 응답이 가능합니다.

적용 기술 2. DB 유니크 제약 + 애플리케이션 중복 검사 이중 방어
문제: 애플리케이션 레벨의 existsByUserIdAndNovelId() 단독 검사만으로는 동시 요청 시 race condition으로 중복 insert가 발생할 수 있습니다.

해결: Library 테이블에 userId + novelId 복합 유니크 인덱스를 추가하여 DB 레벨에서도 중복을 차단합니다. 애플리케이션 레벨 검사는 409 응답을 위해 유지하고 DB 제약은 동시 요청 방어의 최후 방어선으로 이중 적용하였습니다.

GET /api/libraries/me — 내서재 목록 조회
적용 기술 1. QueryDSL 동적 쿼리
문제: 전체/읽는중/완독/찜/구매 탭 필터와 최신순/제목순 정렬을 JPQL로 구현하면 조건 조합마다 별도 메서드가 필요해 코드 중복이 발생합니다.

해결: QueryDSL을 사용하여 libraryType이 null이면 전체, 값이 있으면 해당 타입만 필터링하는 동적 쿼리를 단일 메서드로 처리합니다. 정렬 조건도 resolveOrder()로 분기하여 확장에 유연한 구조로 설계하였습니다.
적용 기술 2. N+1 문제 해결 — 일괄 집계 쿼리

문제: 각 소설의 총 회차 수를 구하기 위해 항목마다 countByNovelId()를 호출하면 페이지 크기만큼 추가 쿼리가 발생하는 N+1 문제가 생깁니다. 페이지 크기가 12라면 최대 13번의 쿼리가 실행됩니다.

해결: 조회된 Library 목록에서 novelId 집합을 추출한 뒤 countByNovelIds()로 단일 쿼리에서 GROUP BY novelId로 일괄 집계합니다. 결과를 Map으로 변환하여 항목별로 매핑하므로 쿼리가 항상 1회로 고정됩니다. 또한 isDeleted = false 조건으로 soft-delete된 회차를 제외하여 실제 공개된 회차 수만 집계합니다.

적용 기술 3. 엔티티 간 연관관계 제거 + ID 직접 참조
문제: JPA 연관관계를 사용하면 즉시/지연 로딩에 따른 불필요한 쿼리가 발생하고 도메인 간 결합도가 높아져 변경 영향 범위가 넓어집니다.

해결: Library 엔티티가 User, Novel을 객체로 참조하지 않고 userId, novelId를 컬럼으로만 보유하도록 설계하였습니다. 도메인 간 결합을 끊고 필요한 시점에만 QueryDSL Join으로 처리합니다.

GET /api/libraries/me - 내 서재 통합 조회
적용 기술 1 - 단일 API 통합 응답
문제: 소설 서재와 국립도서관 도서 서재를 별도 API로 분리하면 프론트에서 두 번 호출해야 하고 로딩 타이밍이 달라져 UX가 저하됩니다.

해결: 기존 GET /api/libraries/me 하나에서 소설 서재(novels)와 국립도서관 도서 서재(nationalLibraryBooks)를 MyLibraryResponse 하나로 통합하여 반환하도록 설계하였습니다. 프론트 호출 횟수를 줄이고 단일 응답으로 렌더링 구조를 단순화하였습니다.

적용 기술 2 - N+1 방지를 위한 일괄 조회 (findAllById + Map 매핑)
문제: 연관관계 없이 ID로만 관리하는 구조에서 UserBook 목록을 순회하며 Book을 개별 조회하면 N+1 문제가 발생하여 쿼리 횟수가 데이터 수에 비례하여 증가합니다.

해결: UserBook 목록 조회 후 bookId 목록을 추출하여 findAllById로 Book을 단 한 번에 일괄 조회하고, Map으로 변환하여 O(1)로 매핑하는 방식을 적용하였습니다. 조회 쿼리가 항상 2번으로 고정되어 데이터 수와 무관하게 일정한 성능을 유지합니다.

--------------------------------------------------------------------------------------------------------

[국립도서]
구현한 API 및 적용 기술 정리

GET /api/v1/national-library/books/search - 도서 검색
적용 기술 - Redis 캐싱 (RedisTemplate)
문제: 국립중앙도서관은 외부 API라 매 요청마다 호출하면 네트워크 지연으로 응답 속도가 느려지고 API 호출 횟수 제한 리스크가 있습니다. 동일한 검색어에 대한 반복 요청이 많을수록 불필요한 외부 호출이 증가합니다.

해결: 검색어 + 페이지 + 사이즈를 조합한 키로 검색 결과를 Redis에 10분간 캐싱하여 캐시 히트 시 외부 API를 호출하지 않도록 하였습니다. 이를 통해 응답 속도를 개선하고 외부 API 호출 횟수를 최소화하였습니다.

POST /api/v1/national-library/books/shelf - 내 서재 도서 저장
적용 기술 1 - books 테이블 upsert 패턴
문제: 검색 결과에서 선택한 도서를 저장할 때 동일한 ISBN의 도서가 여러 유저에 의해 중복으로 저장될 수 있습니다. 도서 데이터가 중복 적재되면 저장 공간이 낭비되고 데이터 정합성이 깨집니다.

해결: 도서 저장 요청 시 ISBN 기준으로 books 테이블에 이미 존재하는지 먼저 확인하고, 없을 때만 저장하고 있으면 기존 레코드를 재사용하는 방식을 적용하였습니다. 도서 데이터 중복을 방지하고 user_books 테이블에는 유저와 도서의 관계만 저장하도록 설계하였습니다.

적용 기술 2 - 엔티티 간 연관관계 제거 + ID 직접 참조
문제: JPA 연관관계를 사용하면 즉시/지연 로딩에 따른 불필요한 쿼리가 발생하고 도메인 간 결합도가 높아져 변경 영향 범위가 넓어집니다.

해결: UserBook 엔티티가 User, Book을 객체로 참조하지 않고 userId, bookId를 컬럼으로만 보유하도록 설계하였습니다. 도메인 간 결합을 끊고 필요한 시점에만 ID 기반으로 일괄 조회하여 처리합니다.

Redis 캐시 활용 네트워크 지연율 감소, 외부 API 호출 결과 저장 시 upsert 중복적재 방지, 외부 API 장애나 지연 가능성을 고려
--------------------------------------------------------------------------------------------------------

[멘토 도메인]
POST /api/mentors — 멘토 등록 신청
적용 기술 1. careerLevel 기준 자동 승인 처리
문제: 멘토 등록 신청 시 모든 신청을 관리자가 수동으로 검토하면 처리 지연이 발생하고 관리자 부담이 커집니다. 하지만 등급별로 이미 플랫폼 활동 조건이 정해져 있어 일정 조건을 충족한 경우는 자동으로 승인해도 무방합니다.

해결: 신청 시점에 Novel, Episode 테이블을 조회해 PUBLISHED 에피소드 수와 좋아요 합산을 검증합니다. INTRODUCTION은 에피소드 50회 이상, ELEMENTARY는 에피소드 50회 이상 + 좋아요 50개 이상, INTERMEDIATE는 에피소드 100회 이상 + 좋아요 100개 이상이면 즉시 APPROVED로 저장합니다. PROFICIENT는 수상/출간 경력 검증이 필요하므로 관리자 수동 승인으로 PENDING 유지합니다.

적용 기술 2. 리스트 필드 JSON 직렬화 저장
문제: mainGenres, specialFields, mentoringStyles는 복수의 값을 가지는 필드입니다. 별도 테이블로 분리하면 조회 시 항상 Join이 필요하고 수정 시 기존 데이터를 삭제 후 재삽입하는 복잡한 로직이 필요합니다.

해결: ObjectMapper.writeValueAsString()으로 List를 JSON 문자열로 직렬화해 단일 컬럼에 저장합니다. 조회 시에는 objectMapper.readValue()로 역직렬화해 List로 반환합니다. 이 필드들은 단순 목록 조회 외에 복잡한 검색 쿼리가 필요 없고 변경 빈도도 낮아 Join 없이 처리할 수 있는 JSON 직렬화 방식이 적합하다고 판단했습니다.

적용 기술 3. DB 유니크 제약 + DataIntegrityViolationException 처리로 동시성 방어
문제: 멘토 등록 시 PENDING, APPROVED 상태를 사전 조회한 후 저장하는 구조라 동시에 두 요청이 들어오면 둘 다 조회를 통과해 중복 저장이 발생할 수 있습니다. check-then-act 패턴의 전형적인 race condition입니다.

해결: Mentor 엔티티의 userId 컬럼에 @Column(unique = true)를 걸어 DB 레벨에서 중복을 막습니다. 동시 요청으로 두 건이 저장을 시도할 경우 DB에서 DataIntegrityViolationException이 발생하는데, save 호출부를 try-catch로 감싸 해당 예외를 MENTOR_ALREADY_APPROVED로 변환해 409로 응답합니다. 애플리케이션 레벨 검증만으로는 race condition을 막을 수 없어 DB 제약과 예외 처리를 함께 구성했습니다.

적용 기술 4. 정적 팩토리 패턴으로 엔티티 생성
문제: 생성자를 열어두면 팀원이 엔티티를 생성할 때 필드 순서를 실수하거나 필수 초기값 설정을 빠뜨릴 수 있습니다. 특히 Mentor는 생성 시점에 반드시 status가 결정되어야 하는데 이를 강제할 방법이 없습니다.

해결: 생성자를 private으로 막고 Mentor.create()라는 정적 팩토리 메서드만 열어두었습니다. 자동 승인 여부를 결정한 initialStatus를 파라미터로 받아 생성 시점에 반드시 status가 설정되도록 강제합니다. 객체 생성 의도를 메서드 이름으로 명확히 표현할 수 있고 생성 규칙을 한 곳에서 관리할 수 있습니다.

PUT /api/mentors/me — 멘토 정보 수정
적용 기술 1. 부분 업데이트 - null 필드 기존 값 유지
문제: 수정 API에서 전체 필드를 항상 보내도록 강제하면 프론트엔드에서 변경하지 않는 필드까지 모두 채워서 보내야 하는 부담이 생깁니다.

해결: Mentor.update() 메서드에서 null 필드는 기존 값을 유지하도록 구현했습니다. introduction, careerHistory 같은 단순 문자열 필드는 null 여부를 체크하고, mainGenres, specialFields, mentoringStyles 리스트 필드는 등록용 toJson()과 수정용 toJsonForUpdate()를 분리했습니다. toJsonForUpdate()는 null이면 null을 반환해 기존 값을 유지하고, 빈 리스트를 보내면 실제로 직렬화해 명시적으로 비울 수 있도록 했습니다.

GET /api/mentors/me — 내 멘토 프로필 조회
적용 기술 1. JSON 역직렬화로 리스트 필드 복원
문제: DB에 JSON 문자열로 저장된 mainGenres, specialFields, mentoringStyles를 응답 시 List로 변환해야 합니다.

해결: MentorProfileResponse의 parseJson() 메서드에서 objectMapper.readValue()로 JSON 문자열을 List로 역직렬화합니다. 파싱 실패 시 빈 리스트를 반환하도록 예외 처리해 응답이 깨지지 않도록 했습니다.

배치 스케줄러 — 매일 자정 멘토 등급 자동 조정
적용 기술 1. Spring @Scheduled 배치
문제: 멘토 등급은 에피소드 회차와 좋아요 수에 따라 자동으로 올라가야 합니다. 에피소드 발행이나 좋아요 발생 시마다 이벤트로 처리하면 에피소드, 좋아요 도메인에 멘토 도메인 로직이 침투해 결합도가 높아집니다.

해결: Spring의 @Scheduled(cron = "0 0 0 * * *")로 매일 자정에 한 번 APPROVED 상태 멘토 전체를 순회하며 조건을 검사합니다. 각 도메인이 서로를 몰라도 되고 구현이 단순합니다. 현재 트래픽 규모에서 실시간 반영이 필수가 아니라 판단해 별도 인프라 없이 Spring 내장 스케줄러로 충분하다고 결정했습니다.

적용 기술 2. 등급 변경 이력 별도 테이블 저장
문제: 배치로 등급이 변경될 때 Mentor 테이블에 덮어쓰기만 하면 언제 어떤 이유로 등급이 바뀌었는지 추적이 불가능합니다. 관리자 입장에서 멘토 이의 제기 시 근거 자료가 없습니다.

해결: MentorCareerHistory 테이블에 변경 전 등급, 변경 후 등급, 변경 사유, 변경 시각을 함께 저장합니다. 데이터가 누적되는 append-only 구조라 변경 흐름 전체를 추적할 수 있고 삭제나 수정이 없어 관리가 단순합니다.

중복 sessionNumber 발생을 방지하기 위해 비관적 락과 DB 유니크 제약을 함께 적용, 낙관적 락 적용, 상태전이 모델, 성능을 점진적으로 개선 해나 났다 +배치 스케줄러

배치 스케줄러--> 도메인
멘토 등급 자동 조정 청크 단위 고민한거--> 메모리 부하, 영속성 컨텍스트 누적 문제 해결, 배치 페이지네이션 pk 정렬 고정

--------------------------------------------------------------------------------------------------------

[멘토 도메인]
1. GET /api/mentorings/received — 멘토링 접수 목록 조회
적용 기술 1. 페이지네이션 (Spring Data Pageable)
문제: 멘토에게 접수된 멘토링 신청이 많아질수록 전체 목록을 한 번에 반환하면 응답 크기가 커지고 DB 부하가 증가합니다.

해결: Pageable을 적용해 페이지 단위로 조회하고 PageResponse로 감싸 현재 페이지, 전체 페이지 수, 마지막 페이지 여부를 함께 반환합니다.

적용 기술 2. 엔티티 ID 참조 방식 + 개별 조회 (N+1 인지)
문제: 엔티티 간 연관관계를 맺지 않는 설계 원칙상 Mentorship에서 멘티 이름(User)과 소설 제목(Novel)을 바로 JOIN할 수 없습니다.

해결: userRepository.findByIdAndIsDeletedFalse(), novelRepository.findById()로 개별 조회합니다. 현재는 N+1이 발생할 수 있으나 탈퇴한 멘티는 알 수 없는 사용자, 삭제된 소설은 알 수 없는 소설로 graceful하게 처리합니다. 고도화 시 QueryDSL JOIN으로 교체할 위치를 TODO 주석으로 명시해두었습니다.

2. PATCH /api/mentorings/{mentoringId}/mentees/{menteeId}/accept — 멘티 수락
적용 기술 1. 낙관적 락 (@Version)
문제: 멘토가 여러 멘티를 동시에 수락하는 경우 슬롯 차감(decreaseSlot())이 동시에 실행되면 슬롯이 0 이하로 내려가는 race condition이 발생할 수 있습니다

해결: Mentor 엔티티에 @Version을 적용해 낙관적 락을 걸었습니다. 동시에 두 요청이 슬롯을 차감하려 하면 나중에 커밋된 트랜잭션이 OptimisticLockException을 발생시켜 중복 차감을 방지합니다.

적용 기술 2. 상태 검증 (PENDING 체크)
문제: 이미 수락/거절 처리된 멘토링에 중복으로 수락 요청이 들어올 수 있습니다.

해결: mentorship.getStatus() != MentorshipStatus.PENDING 체크로 이미 처리된 요청에는 MENTORING_ALREADY_PROCESSED 예외를 반환합니다.

3. PATCH /api/mentorings/{mentoringId}/mentees/{menteeId}/reject — 멘티 거절
적용 기술 1. 상태 검증 (PENDING 체크)
문제: 이미 수락/거절 처리된 멘토링에 거절 요청이 중복으로 들어올 수 있습니다.

해결: 수락 API와 동일하게 PENDING 상태 체크를 통해 중복 처리를 방지하고 MENTORING_ALREADY_PROCESSED 예외를 반환합니다. 수락과 달리 슬롯 차감이 없으므로 낙관적 락은 적용하지 않았습니다.

4. GET /api/mentorings/{mentoringId}/documents — 원고 다운로드 URL 조회
적용 기술 1. 다운로드 횟수 트래킹
문제: 멘토가 원고를 몇 번 다운로드했는지 추적이 필요합니다.

해결: URL 조회 시 mentorship.increaseManuscriptDownloadCount()를 호출해 다운로드 횟수를 증가시킵니다. 조회와 카운트 증가를 하나의 트랜잭션으로 묶어 일관성을 보장합니다.

적용 기술 2. S3 Presigned URL 연동 준비 (TODO)
문제: 원고 파일 URL을 그대로 노출하면 인증 없이 누구나 접근할 수 있는 보안 문제가 있습니다.

해결: 현재는 manuscriptUrl을 직접 반환하지만 S3 연동 후 s3Service.generatePresignedUrl()로 교체할 위치를 TODO 주석으로 명시해 두었습니다.

5. PATCH /api/mentorings/{mentoringId}/complete — 멘토링 종료
적용 기술 1. 낙관적 락 (@Version) + 슬롯 반환
문제: 멘토링 종료 시 슬롯을 반환(increaseSlot())하는데 동시에 여러 멘토링이 종료되면 슬롯 값이 꼬일 수 있습니다.

해결: Mentor 엔티티의 @Version으로 슬롯 반환 시에도 낙관적 락이 적용되어 동시 수정 충돌을 방지합니다. 수락 시 차감한 슬롯을 종료 시 정확히 반환해 슬롯 정합성을 유지합니다.

적용 기술 2. 상태 검증 (ACCEPTED 체크)
문제: PENDING이나 REJECTED 상태의 멘토링을 종료 처리하려는 잘못된 요청이 들어올 수 있습니다.

해결: mentorship.getStatus() != MentorshipStatus.ACCEPTED 체크로 진행 중인 멘토링만 종료할 수 있도록 제한하고 MENTORING_NOT_ACCEPTED 예외를 반환합니다.

6. GET /api/mentorings/{mentoringId} — 멘토링 상세 조회
적용 기술 1. 엔티티 ID 참조 방식 + Soft Delete 고려 조회
문제: 멘토나 멘티가 탈퇴한 경우에도 멘토링 상세 정보는 조회 가능해야 합니다.

해결: userRepository.findByIdAndIsDeletedFalse()로 조회해 탈퇴한 유저는 알 수 없는 사용자로 graceful하게 처리합니다. 멘토링 데이터 자체는 유지되어 피드백 이력 등을 확인할 수 있습니다.

적용 기술 2. 피드백 목록 시간순 정렬 조회
문제: 피드백이 여러 건일 때 작성 순서대로 보여줘야 멘토링 진행 흐름을 파악할 수 있습니다.

해결: mentorFeedbackRepository.findAllByMentorshipIdOrderByCreatedAtAsc()로 피드백을 시간 오름차순으로 조회합니다.

7. POST /api/mentorings/{mentoringId}/feedbacks — 피드백 작성
적용 기술 1. 세션 횟수 트래킹
문제: 멘토링이 몇 회 진행되었는지 추적이 필요합니다.

해결: 피드백 저장 시 mentorship.increaseSession()을 함께 호출해 총 세션 수를 증가시킵니다. 피드백 저장과 세션 증가를 하나의 트랜잭션으로 묶어 피드백이 저장되면 반드시 세션도 증가하도록 일관성을 보장합니다.

적용 기술 2. 상태 검증 (ACCEPTED 체크)
문제: 진행 중이 아닌 멘토링(PENDING, REJECTED, COMPLETED)에 피드백을 작성하는 잘못된 요청이 들어올 수 있습니다.

해결: mentorship.getStatus() != MentorshipStatus.ACCEPTED 체크로 수락된 멘토링에만 피드백 작성이 가능하도록 제한하고 MENTORING_FEEDBACK_ONLY_ACCEPTED 예외를 반환합니다.

--------------------------------------------------------------------------------------------------------

[고도화 진행한 내용]
POST /api/v1/mentorings/{mentoringId}/feedbacks — 피드백 작성 (V1)
적용 기술 1. 세션 횟수 트래킹
문제: 멘토링이 몇 회 진행되었는지 추적이 필요합니다.

해결: 피드백 저장 시 mentorship.increaseSession()을 함께 호출해 총 세션 수를 증가시킵니다. 피드백 저장과 세션 증가를 하나의 트랜잭션으로 묶어 일관성을 보장합니다.

적용 기술 2. 상태 검증 (ACCEPTED 체크)
문제: 진행 중이 아닌 멘토링에 피드백을 작성하는 잘못된 요청이 들어올 수 있습니다.

해결: mentorship.getStatus() != MentorshipStatus.ACCEPTED 체크로 수락된 멘토링에만 피드백 작성이 가능하도록 제한하고 MENTORING_FEEDBACK_ONLY_ACCEPTED 예외를 반환합니다.

적용 기술 3. 회차별 피드백 이력 관리
문제: 피드백이 몇 회차인지, 어떤 제목의 피드백인지 구분할 방법이 없었습니다.

해결: MentorFeedback에 title과 sessionNumber를 추가해 회차별 피드백 이력을 명확히 관리합니다. sessionNumber는 totalSessions + 1로 계산해 자동 부여합니다.

POST /api/v2/mentorings/{mentoringId}/feedbacks — 피드백 작성 (V2)
적용 기술 1. 비관적 락 (동시성 보호)
문제: 동시에 두 요청이 들어오면 totalSessions + 1을 동시에 읽어 같은 sessionNumber가 중복 저장될 수 있습니다.

해결: findByIdWithLock()으로 멘토링 row에 비관적 락을 걸어 동시 요청을 직렬화합니다. 두 요청이 동시에 들어와도 하나씩 순서대로 처리됩니다.

적용 기술 2. DB 유니크 제약 (이중 방어)
문제: 애플리케이션 레벨의 락만으로는 예외 상황에서 중복 저장을 완전히 막을 수 없습니다.

해결: mentorship_feedbacks 테이블에 (mentorship_id, session_number) 유니크 제약을 추가해 DB 레벨에서도 중복을 차단합니다. 충돌 시 DataIntegrityViolationException을 MENTORING_SESSION_CONFLICT 예외로 변환해 409를 반환합니다.

적용 기술 3. 입력값 길이 검증
문제: title이 200자를 초과하면 DB 예외로 500이 반환될 수 있습니다.

해결: @Size(max = 200)을 추가해 요청 단계에서 400으로 끊어 사용자에게 명확한 오류 메시지를 반환합니다.

GET /api/v1/mentorings/received — 멘토링 접수 목록 조회 (V1)
적용 기술 1. 페이지네이션
문제: 멘토링 신청이 많을 경우 전체 조회 시 성능 저하가 발생할 수 있습니다.

해결: Pageable을 적용해 페이지 단위로 조회합니다. @Min, @Max로 page, size 파라미터를 검증해 잘못된 입력으로 인한 500 에러를 방지합니다.

적용 기술 2. 탈퇴 회원/삭제 소설 Fallback 처리
문제: 멘티가 탈퇴하거나 소설이 삭제된 경우 조회 시 예외가 발생할 수 있습니다.

해결: Optional의 orElse()로 탈퇴한 멘티는 "알 수 없는 사용자", 삭제된 소설은 "알 수 없는 소설"을 반환해 안정적으로 목록을 제공합니다.

GET /api/v2/mentorings/received — 멘토링 접수 목록 조회 (V2)
적용 기술 1. soft-delete 적용
문제: V1의 findById()는 soft-delete 조건을 포함하지 않아 삭제된 소설 제목이 그대로 노출될 수 있습니다.

해결: findByIdAndIsDeletedFalse()로 교체해 삭제된 소설은 "알 수 없는 소설"로 처리합니다.

GET /api/v1/mentorings/{mentoringId} — 멘토링 상세 조회 (V1)
적용 기술 1. 권한 검증
문제: 다른 멘토가 멘토링 상세를 조회하는 잘못된 요청이 들어올 수 있습니다.

해결: mentorship.getMentorId()와 로그인한 멘토의 ID를 비교해 본인의 멘토링만 조회 가능하도록 제한하고 MENTORING_UNAUTHORIZED 예외를 반환합니다.

적용 기술 2. 회차별 피드백 이력 조회
문제: 멘토링 상세에서 피드백 이력을 회차 순서대로 확인해야 합니다.

해결: findAllByMentorshipIdOrderByCreatedAtAsc()로 피드백을 생성 순서대로 조회하고 FeedbackInfo에 title, sessionNumber를 포함해 회차별 내용을 명확히 제공합니다.

GET /api/v2/mentorings/{mentoringId} — 멘토링 상세 조회 (V2)
적용 기술 1. soft-delete 적용
문제: V1의 findById()는 삭제된 소설 제목이 그대로 노출될 수 있습니다.

해결: findByIdAndIsDeletedFalse()로 교체해 삭제된 소설은 "알 수 없는 소설"로 반환합니다.

PATCH /api/v1,v2/mentorings/{mentoringId}/mentees/{menteeId}/accept — 멘티 수락
적용 기술 1. 슬롯 관리
문제: 멘토가 수락할 수 있는 멘티 수는 최대 5명으로 제한됩니다.

해결: 수락 시 mentor.decreaseSlot()으로 잔여 슬롯을 차감합니다. 슬롯 차감과 멘토링 상태 변경을 하나의 트랜잭션으로 묶어 일관성을 보장합니다.

적용 기술 2. 중복 처리 방지
문제: 이미 수락/거절된 멘토링에 다시 수락 요청이 들어올 수 있습니다.

해결: mentorship.getStatus() != MentorshipStatus.PENDING 체크로 PENDING 상태에서만 수락이 가능하도록 제한하고 MENTORING_ALREADY_PROCESSED 예외를 반환합니다.

PATCH /api/v1,v2/mentorings/{mentoringId}/mentees/{menteeId}/reject — 멘티 거절
적용 기술 1. 중복 처리 방지
문제: 이미 처리된 멘토링에 거절 요청이 들어올 수 있습니다.

해결: PENDING 상태에서만 거절 가능하도록 제한하고 MENTORING_ALREADY_PROCESSED 예외를 반환합니다.

적용 기술 2. 거절 시각 기록
문제: 이번 달 거절 건수 통계 집계를 위해 거절 시각이 필요합니다.

해결: mentorship.reject() 호출 시 rejectedAt을 LocalDateTime.now()로 기록합니다. 이를 기반으로 countRejectedThisMonth() 쿼리에서 월별 거절 통계를 정확히 집계합니다.

PATCH /api/v1,v2/mentorings/{mentoringId}/complete — 멘토링 종료
적용 기술 1. 슬롯 반환
문제: 멘토링이 종료되면 해당 슬롯을 다시 다른 멘티에게 열어줘야 합니다.

해결: 종료 시 mentor.increaseSlot()으로 슬롯을 반환합니다. 슬롯 반환과 상태 변경을 하나의 트랜잭션으로 묶어 일관성을 보장합니다.

적용 기술 2. 상태 검증 (ACCEPTED 체크)
문제: PENDING이나 REJECTED 상태의 멘토링을 종료하는 잘못된 요청이 들어올 수 있습니다.

해결: ACCEPTED 상태에서만 종료 가능하도록 제한하고 MENTORING_NOT_ACCEPTED 예외를 반환합니다.

GET /api/v1,v2/mentorings/{mentoringId}/documents — 원고 다운로드 URL 조회
적용 기술 1. 다운로드 횟수 트래킹
문제: 멘토가 원고를 몇 번 다운로드했는지 추적이 필요합니다.

해결: URL 반환 시 mentorship.increaseManuscriptDownloadCount()를 함께 호출해 다운로드 횟수를 기록합니다.

적용 기술 2. 원고 존재 여부 검증
문제: 원고 파일이 없는 멘토링에 다운로드 요청이 들어올 수 있습니다.

해결: manuscriptUrl이 null인 경우 MENTORING_MANUSCRIPT_NOT_FOUND 예외를 반환해 명확한 오류 메시지를 제공합니다.

--------------------------------------------------------------------------------------------------------
[고도화 진행한 내용]
GET /api/mentors/me/mentees — 내 멘티 목록 조회 (v1)
적용 기술 1. 탈퇴/삭제 데이터 방어
문제: 멘티가 탈퇴하거나 소설이 삭제된 경우 응답에 null이 들어갈 수 있습니다.

해결: userRepository.findByIdAndIsDeletedFalse() 조회 후 orElse("알 수 없는 사용자"), novelRepository.findById() 조회 후 orElse("알 수 없는 소설")로 null을 방어합니다.

적용 기술 2. 최근 피드백 날짜 조회
문제: 멘티별로 마지막 피드백 날짜를 보여줘야 합니다.

해결: mentorFeedbackRepository.findTopByMentorshipIdOrderByCreatedAtDesc()로 최신 1건만 조회해서 createdAt을 반환합니다.

GET /api/v2/mentors/me/mentees — 내 멘티 목록 조회 (v2)
적용 기술 1. N+1 문제 해결
문제: v1은 반복문 안에서 멘티, 소설, 피드백을 각각 개별 조회해 멘티가 N명이면 쿼리가 1+3N번 나가는 구조였습니다.

해결: QueryDSL로 mentorship → menteeUser → novel → feedback을 단일 JOIN 쿼리로 처리해 쿼리를 1번으로 줄였습니다.

적용 기술 2. soft-delete 방어
문제: 탈퇴한 유저나 삭제된 소설 조회 시 LEFT JOIN 결과 null이 응답에 그대로 들어갈 수 있습니다.

해결: Expressions.cases()로 쿼리 단에서 직접 null을 방어합니다.
javaExpressions.cases()
        .when(menteeUser.nickname.isNull())
        .then("알 수 없는 사용자")
        .otherwise(menteeUser.nickname)

적용 기술 3. v1 호환성 유지
문제: 기존 v1 API를 바로 교체하면 롤백이 어렵습니다.

해결: v1 엔드포인트는 그대로 유지하고 /api/v2/mentors/me/mentees를 신규 추가해 점진적 전환이 가능하도록 했습니다.

GET /api/v2/mentorings/received — 멘토링 접수 목록 조회 (v2)
적용 기술 1. N+1 문제 해결
문제: v1은 멘토십 목록 조회 후 반복문에서 멘티 정보, 소설 정보를 개별 조회하는 구조였습니다.

해결: QueryDSL로 mentorship → menteeUser → novel을 단일 LEFT JOIN 쿼리로 처리했습니다.

적용 기술 2. soft-delete 적용
문제: 탈퇴한 멘티나 삭제된 소설의 경우 null이 응답에 들어갈 수 있습니다.

해결: JOIN 조건에 isDeleted=false를 추가하고 Expressions.cases()로 null fallback을 처리했습니다.
java.leftJoin(menteeUser).on(menteeUser.id.eq(mentorship.menteeId)
        .and(menteeUser.isDeleted.eq(false)))

적용 기술 3. 페이지네이션
문제: 접수 목록이 많아질수록 전체 조회는 성능에 부담이 됩니다.

해결: Pageable을 적용해 페이지 단위로 조회하고 PageImpl로 응답합니다.

GET /api/mentorships/v2/me/history — 내 멘토링 이력 조회 (v2)
적용 기술 1. N+1 문제 해결
문제: v1은 멘토십 목록 조회 후 반복문에서 멘토 정보를 개별 조회하는 구조였습니다.

해결: QueryDSL로 mentorship → mentor → user를 단일 JOIN 쿼리로 처리했습니다.

적용 기술 2. soft-delete 적용
문제: 탈퇴한 멘토의 닉네임이 inner join 구조에서 그대로 노출될 수 있습니다.

해결: inner join → leftJoin으로 변경하고 isDeleted=false 조건과 null fallback을 추가했습니다.
java.leftJoin(user).on(user.id.eq(mentor.userId)
        .and(user.isDeleted.eq(false)))

적용 기술 3. 상태 필터링
문제: 전체 이력이 아닌 특정 상태(ACCEPTED, COMPLETED 등)의 이력만 조회할 수 있어야 합니다.

해결: BooleanBuilder로 status가 null이면 전체, 값이 있으면 해당 상태만 필터링합니다.
javaif (status != null) {
    where.and(mentorship.status.eq(status));
}

PATCH /api/mentors/me — 멘토 정보 수정
적용 기술 1. 부분 업데이트 (null 허용)
문제: 수정 요청 시 변경하지 않는 필드까지 전부 보내야 하면 불편합니다.

해결: MentorUpdateRequest의 각 필드가 null이면 기존 값을 유지하고, 값이 있을 때만 업데이트합니다.

적용 기술 2. careerHistory 빈 값 검증
문제: careerHistory를 빈 문자열로 보내면 의미없는 데이터가 저장됩니다.

해결: null은 기존 값 유지, 빈 문자열은 MENTOR_CAREER_REQUIRED 예외를 반환합니다.

POST /api/mentors/me — 멘토 등록 신청
적용 기술 1. 등급별 자동 승인 로직
문제: 등급마다 멘토 승인 조건이 다릅니다. INTRODUCTION은 에피소드 50개, ELEMENTARY는 에피소드 50개 + 좋아요 50개, PROFICIENT는 항상 관리자 수동 승인입니다.

해결: resolveInitialStatus()에서 등급별 조건을 switch로 분기해 자동 승인 여부를 결정합니다.

적용 기술 2. 동시 요청 방어
문제: 동시에 여러 요청이 들어오면 중복 등록이 발생할 수 있습니다.

해결: DataIntegrityViolationException 발생 시 MENTOR_ALREADY_APPROVED 예외로 변환해 처리합니다.

적용 기술 3. 중복 신청 방어
문제: 이미 PENDING이거나 APPROVED 상태인 경우 중복 신청이 들어올 수 있습니다.

해결: existsByUserIdAndStatus()로 사전 체크 후 이미 존재하면 예외를 반환합니다.

스케줄러 — 멘토 등급 자동 조정 (매일 자정)
적용 기술 1. 청크 단위 페이지네이션
문제: 승급 대상 멘토를 한 번에 전부 List로 가져오면 데이터가 많을수록 메모리 부하가 커집니다.

해결: 100명씩 페이지 단위로 나눠서 처리합니다.
javaPageRequest.of(pageNumber, CHUNK_SIZE, Sort.by("id").ascending())

적용 기술 2. persistence context 정리
문제: @Transactional 안에서 처리한 엔티티가 배치 종료까지 영속성 컨텍스트에 쌓여 메모리가 누적됩니다.

해결: 청크 처리 후 entityManager.flush() / entityManager.clear()를 호출해 청크마다 메모리를 비웁니다.

적용 기술 3. 정렬 기준 고정
문제: 정렬 기준이 없으면 배치 실행 중 다른 트랜잭션이 데이터를 변경할 때 페이지 경계가 밀려 행 누락/중복이 발생할 수 있습니다.

해결: Sort.by("id").ascending()으로 PK 기준 정렬을 고정합니다.

--------------------------------------------------------------------------------------------------------
[배포]
젠킨스 aws

--------------------------------------------------------------------------------------------------------
[수익환전]
계좌 등록 + 1원 인증
POST /api/revenues/me/account/verify — 계좌 등록 + 1원 인증 코드 발송
POST /api/revenues/me/account/verify/confirm — 인증코드 검증
적용 기술 1. AES/GCM 계좌번호 암호화
문제: 계좌번호를 평문으로 DB에 저장하면 DB 탈취 시 금융 정보가 그대로 노출됩니다.

해결: AES/GCM 양방향 암호화로 계좌번호를 암호화하여 저장하고, 응답 시에는 뒤 4자리만 노출하는 마스킹 처리를 적용했습니다. 복호화는 1원 인증 성공 후 계좌 상세 조회 시에만 수행합니다.

적용 기술 2. BankVerificationClient 인터페이스 분리
문제: 실제 은행 API(useB/CODEF)는 금융규제상 테스트/개발 환경에서 연동이 불가능합니다. 개발 중 매번 실제 API를 호출하면 비용이 발생하고 환경에 따라 동작이 달라집니다.

해결: BankVerificationClient 인터페이스를 분리하고 @Profile({"dev", "local", "test"})가 붙은 LocalBankVerificationClient 시뮬레이션 구현체를 별도로 만들었습니다. 운영 환경에서는 실제 구현체로 교체만 하면 되는 구조입니다.

적용 기술 3. 인증코드 만료/시도 횟수 검증
문제: 인증코드를 무제한으로 시도하거나 만료 이후에도 사용할 수 있으면 보안상 문제가 됩니다.

해결: AccountVerification 엔티티에 expiredAt(5분), attemptCount(최대 5회)를 관리하여 만료 시간 초과 또는 시도 횟수 초과 시 예외를 발생시킵니다.

수익 현황 조회
GET /api/revenues/me — 총 누적 수익 / 총 환전 금액 / 가용 잔액 / 인증된 계좌 정보
적용 기술 1. Redis 캐싱 (TTL 30분)
문제: 수익 현황은 Revenue 테이블 전체를 집계하는 무거운 쿼리입니다. 작가가 대시보드를 반복 조회할 때마다 집계 쿼리가 실행되면 DB 부하가 커집니다.

해결: 첫 조회 시 집계 결과를 Redis에 30분간 캐싱합니다. 이후 동일 요청은 DB를 거치지 않고 Redis에서 바로 반환합니다. 환전 신청 또는 수익 발생 시 해당 캐시를 즉시 무효화하여 데이터 정합성을 유지합니다.

적용 기술 2. Revenue 타입 분리 집계
문제: 수익(EPISODE_SALE, SUBSCRIPTION), 환전(WITHDRAWAL), 환불(REFUND)이 하나의 Revenue 테이블에 혼재되어 있어 가용 잔액 계산 시 타입별 분리 집계가 필요합니다.

해결: sumAmountByAuthorIdAndTypeIn()으로 수익+환불을 합산하고 sumAmountByAuthorIdAndType()으로 환전액을 별도 집계하여 가용 잔액 = 수익합계 - 환전합계로 계산합니다.

환전 신청
POST /api/revenues/me/exchanges — 환전 신청
적용 기술 1. Redis 분산락 (UUID 토큰 기반)
문제: 동시에 여러 환전 요청이 들어오면 잔액 검증을 통과한 요청이 중복으로 처리되어 잔액보다 많은 금액이 환전될 수 있습니다.

해결: Redis SETNX로 lock:withdrawal:{authorId} 키에 UUID 토큰을 5초간 점유합니다. 락 해제 시에는 get 후 delete의 비원자성 문제를 방지하기 위해 Lua Script로 비교와 삭제를 하나의 원자적 연산으로 처리합니다.

적용 기술 2. FeePolicy Enum으로 수수료 정책 분리
문제: 수수료율(3.3%)과 최소 환전 금액(10,000원)을 서비스 코드에 하드코딩하면 정책 변경 시 코드 전체를 수정해야 합니다.

해결: FeePolicy Enum에 수수료율, 최소 환전 금액, 수수료 계산, 실수령액 계산 로직을 캡슐화했습니다. 정책 변경 시 Enum 값만 수정하면 됩니다.

적용 기술 3. Revenue + Withdrawal 한 트랜잭션 처리
문제: Revenue(WITHDRAWAL) 차감 기록과 Withdrawal 생성이 별도 트랜잭션이면 하나만 성공하고 하나가 실패할 경우 잔액 불일치가 발생합니다.

해결: 잔액 확인 → Revenue(WITHDRAWAL) 저장 → Withdrawal 저장을 하나의 @Transactional 안에서 처리하여 원자성을 보장합니다.

환전 내역 조회
GET /api/revenues/me/exchanges — 환전 목록 (상태/기간 필터 + 페이징)
GET /api/revenues/me/exchanges/{id} — 환전 상세 조회
적용 기술 1. QueryDSL 동적 쿼리
문제: 상태 필터, 기간 필터가 선택적으로 적용되어야 하는데 JPQL로 작성하면 조건 조합마다 별도 쿼리가 필요하고 null 체크 분기가 복잡해집니다.

해결: QueryDSL BooleanExpression으로 각 필터 조건을 null 체크 후 동적으로 조합합니다. 또한 requestedAt 단일 정렬 시 동일 시각 레코드에서 페이지 중복/누락이 발생할 수 있어 id DESC를 tie-breaker로 추가했습니다.

수익 분석 통계
GET /api/revenues/me/statistics — 월별/주별 수익 집계
적용 기술 1. Redis 캐싱 + SCAN 기반 패턴 무효화 (TTL 1시간)
문제: 통계는 GROUP BY 집계 쿼리로 부하가 크고, 월별/주별 등 기간 단위로 캐시 키가 달라집니다. 수익 발생 시 해당 작가의 모든 통계 캐시를 무효화해야 하는데 키 패턴이 다양하면 일괄 삭제가 어렵습니다.

해결: statistics:{authorId}:* 패턴으로 캐시 키를 설계하고, 무효화 시 KEYS 대신 SCAN으로 패턴 매칭 키를 순회 삭제합니다. KEYS는 싱글스레드 Redis를 블로킹하지만 SCAN은 커서 기반으로 점진적으로 탐색하여 운영 환경에서도 안전합니다.

관리자 환전 승인/거절
GET /api/admin/exchanges — 전체 환전 목록 조회
GET /api/admin/exchanges/{id} — 환전 상세 조회
PUT /api/admin/exchanges/{id}/approve — 환전 승인
PUT /api/admin/exchanges/{id}/reject — 환전 거절
적용 기술 1. WithdrawalStatus 상태 전이 검증
문제: 이미 완료(COMPLETED)되거나 거절(REJECTED)된 환전 건을 다시 승인/거절하면 데이터 정합성이 깨집니다.

해결: WithdrawalStatus Enum에 VALID_TRANSITIONS Map으로 허용된 전이만 정의하고, Withdrawal 엔티티의 상태 변경 메서드에서 validateTransition()을 호출하여 허용되지 않은 전이 시 IllegalStateException을 발생시킵니다. PENDING → PROCESSING → COMPLETED, PENDING → REJECTED만 허용됩니다.

적용 기술 2. 거절 시 REFUND 타입으로 잔액 복구
문제: 환전 신청 시 Revenue(WITHDRAWAL)로 잔액이 차감됩니다. 거절 시 해당 WITHDRAWAL 레코드를 삭제하거나 수정하면 이력 추적이 불가능합니다.

해결: 거절 시 Revenue를 삭제하지 않고 동일 금액의 Revenue(REFUND)를 새로 생성합니다. 가용 잔액 계산 시 typeIn(EPISODE_SALE, SUBSCRIPTION, REFUND)로 합산하면 자연스럽게 복구된 금액이 반영되고, 환전/거절 이력이 모두 Revenue 테이블에 남습니다.

적용 기술 3. @Secured + 역할 분리
문제: 일반 작가나 독자가 관리자 API에 접근하면 안 됩니다.
해결: @Secured({"ADMIN", "SUPER_ADMIN"})을 컨트롤러 클래스 레벨에 적용하여 ADMIN과 SUPER_ADMIN 역할만 접근 가능하도록 제한했습니다.

RedisTTL 효과, 키 설계, Redis 기반 락, 상태전이, 민감한 금융정보에 대한 핸들링

--------------------------------------------------------------------------------------------------------
[이벤트]
1. POST /api/admin/events — 이벤트 생성 (관리자)
적용 기술 1. 페이지 단위 배치 조회 + Kafka 기반 비동기 알림 발송
문제: 이벤트가 생성되면 전체 독자(READER)에게 알림을 발송해야 한다.
단순하게 userRepository.findAllByRole(READER)로 전체 유저를 한 번에 조회하면
유저 수가 수만 명이 될 경우 메모리에 전부 올라가 OOM이 발생할 수 있고,
이벤트 생성 트랜잭션 자체가 지연되는 문제가 생긴다.

해결: 전체 READER를 1000건씩 페이지 단위로 배치 조회하여 순차적으로 이벤트를 발행했다.
알림 발송은 ApplicationEventPublisher를 통해 이벤트를 등록하고,
@TransactionalEventListener(AFTER_COMMIT)으로 트랜잭션 커밋 이후에 Kafka에 발행되는 구조를 활용했다.
이로 인해 알림 발송 실패가 이벤트 생성 트랜잭션에 영향을 주지 않고, READER에게만 선택적으로 발송된다.

적용 기술 2. Redis 캐시 Evict
문제: 사용자 이벤트 목록 조회에 Redis 캐싱이 적용되어 있기 때문에
새 이벤트가 생성되어도 캐시가 살아있으면 사용자에게 새 이벤트가 노출되지 않는다.

해결: 이벤트 생성 시 사용자용 목록 캐시 전체를 즉시 evict한다.
이후 사용자가 목록을 조회하면 캐시 miss가 발생해 DB에서 최신 데이터를 읽어온 뒤 다시 캐싱된다.

2. GET /api/admin/events — 이벤트 목록 조회 (관리자)
적용 기술. 캐싱 미적용 - 실시간 DB 직접 조회
문제: 관리자는 이벤트의 정확한 현재 상태(참여자 수, 진행 여부 등)를 실시간으로 파악해야 한다.
캐싱을 적용하면 최신 상태가 반영되지 않아 관리 판단에 오류가 생길 수 있다.

해결: 관리자 목록 조회는 캐싱을 전혀 적용하지 않고 항상 DB를 직접 조회한다.
관리자는 소수 인원이라 요청 빈도가 낮으므로 DB 부하 문제가 없다.
사용자 API와 관리자 API를 별도 Service로 분리해 캐싱 전략을 독립적으로 관리했다.

3. GET /api/admin/events/{eventId} — 이벤트 상세 조회 (관리자)
적용 기술. 캐싱 미적용 - 실시간 DB 직접 조회
문제: 관리자 상세 조회는 참여자 현황, 마감 여부 등 실시간 정보가 중요하다.

캐싱된 데이터를 보여주면 관리 목적으로 사용할 수 없다.
해결: 캐싱 없이 항상 DB를 직접 조회한다.
사용자용 상세 조회와 달리 관리자용은 별도 Service 메서드로 분리해 캐싱 로직이 섞이지 않도록 했다.

4. GET /api/admin/events/{eventId}/participants — 이벤트별 참여자 목록 조회 (관리자)
적용 기술. 연관관계 미사용 + FK 컬럼 직접 조회
문제: 프로젝트 컨벤션상 엔티티 간 연관관계(@ManyToOne 등)를 사용하지 않고 FK를 Long 컬럼으로만 관리한다.
EventParticipant에서 Event나 User로의 Join이 필요한 경우 연관관계 없이 처리해야 한다.

해결: EventParticipant 테이블에 event_id, user_id를 Long 컬럼으로 보유하고
Repository에서 findAllByEventId()로 페이징 조회한다.
추가 정보가 필요한 경우 QueryDSL Join으로 처리할 수 있는 구조로 설계했다.

5. GET /api/events — 이벤트 목록 조회 (사용자)
적용 기술. RedisTemplate 캐싱 - TTL 5분
문제: 이벤트 목록 조회는 다수의 사용자가 반복적으로 요청하는 API다.
매 요청마다 DB를 조회하면 이벤트 오픈 직후처럼 트래픽이 몰리는 상황에서 DB 부하가 심해진다.
이벤트 메타 정보(제목, 기간, 포인트 등)는 자주 변경되지 않으므로 캐싱이 적합하다.

해결: RedisTemplate을 사용해 status, 페이지 번호, 페이지 크기, 정렬 조건을 조합한 키로 캐싱한다.
TTL은 5분으로 설정해 짧은 주기로 갱신되게 하고, 이벤트 생성 시 캐시를 evict해 정합성을 유지한다.
캐시 역직렬화 실패 시 자동으로 DB 조회로 전환하는 장애 대응 로직도 포함했다.

6. GET /api/events/{eventId} — 이벤트 상세 조회 (사용자)
적용 기술. 이벤트 상태별 차등 캐싱 전략
문제: 진행 중인 이벤트의 상세 조회는 참여 가능 여부와 현재 상태가 실시간으로 중요하다.
반면 종료된 이벤트는 결과가 확정되어 더 이상 변경되지 않는데도 매 요청마다 DB를 조회하면
이벤트 종료 직후 결과 확인 트래픽이 몰릴 때 DB에 불필요한 부하가 생긴다.

해결: 진행 중인 이벤트는 캐싱 없이 DB를 직접 조회해 실시간 정확성을 보장한다.
종료된 이벤트는 첫 조회 시 Redis에 TTL 7일로 캐싱한다.
이후 동일 이벤트 조회는 전부 Redis에서 응답해 DB 부하 없이 처리된다.

7. POST /api/events/{eventId}/participants — 이벤트 참여 신청 (사용자)
적용 기술 1. Redisson 분산락 - 선착순 동시성 제어
문제: 이벤트 참여 신청은 짧은 시간에 수백 건의 요청이 동시에 몰린다.
동시성 제어 없이 처리하면 maxParticipants를 초과해 참여자가 저장되거나
같은 유저가 중복 참여하는 레이스 컨디션이 발생한다.
DB 비관적 락은 트래픽 집중 시 DB 커넥션을 오래 점유해 병목이 생기므로 부적합하다.
이미 Redis 인프라가 구성되어 있으므로 Redisson 분산락을 선택했다.
TTL(leaseTime) 기반으로 서버 장애 시에도 데드락이 발생하지 않고,
멀티 인스턴스 환경에서도 단일 락으로 동시성을 제어할 수 있다.

해결: 이벤트 ID 단위로 Redisson 분산락을 걸어 한 번에 하나의 요청만 처리한다.
waitTime 5초(최대 대기 시간), leaseTime 3초(자동 해제 시간)로 설정했다.
락 획득 실패 시 TOO_MANY_REQUESTS(429)를 반환해 사용자에게 재시도를 안내한다.

적용 기술 2. DB UniqueConstraint - 이중 동시성 방어
문제: Redisson 락의 leaseTime이 초과되는 극한 상황에서
동시에 두 요청이 락을 획득해 중복 참여가 저장될 가능성이 극히 낮지만 존재한다.
애플리케이션 레벨의 중복 체크만으로는 완전한 방어가 불가능하다.

해결: EventParticipant 테이블에 (event_id, user_id) 복합 UniqueConstraint를 적용했다.
Redisson 락이 1차 방어, DB 제약조건이 2차 방어로 동작하는 이중 구조로 완전한 중복 참여를 차단한다.

적용 기술 3. 포인트 즉시 지급 - 도메인 간 서비스 직접 호출
문제: 선착순 인원 안에 든 사용자에게는 참여 신청 즉시 포인트가 지급되어야 한다.
지급이 지연되면 사용자 경험이 나빠지고 지급 누락 이슈가 발생할 수 있다.

해결: 참여자 저장 직후 같은 트랜잭션 내에서 PointService.chargeEventReward()를 호출한다.
PointHistory에 타입을 EVENT로 기록해 이벤트 보상 이력을 명확히 남긴다.
같은 트랜잭션이므로 참여자 저장과 포인트 지급이 원자적으로 처리되어
참여는 됐는데 포인트가 안 지급되는 불일치 상황이 발생하지 않는다.

Redis 캐싱, 분산락, 유니크제약, kafka를 활용한 이벤트 발행, --> 메모리 고민 대량 사용자 알림 발송시

포폴을위해

1.조회시 성능 지표 가지기

2.동시성이나 데이터 정합성 ->동시성 데이터 정합성 테스트에 관한 수치 자료

3.외부 연동 잘 챙겨가기

4.카프카를 통해 대량 알림 전송 관련 -> 왜 카프카로 넘어오게된 스토리가 필요하고 관련 수치 자료가 필요하다

->카프카 실패시에 대한 재시도 고민, 알림중복발송 을 위한 방지를 위한 고민

5.부하테스트 해보기

6.인프라 쪽으로 더해보던지

7.카프카쪽으로 고도화 해보던지

8.대용량 쿠폰 발행 고민해보기->굳이 여기까지 갈필요는 없을것같다

포인트 -> 증거를 확보하고, 인덱스 설계를 보강하고, 동시성이나 정합성 증거남기기,캐시자체도 내가 어떻게 설계했는데 정리해보기

증거 잘 정리하면 바로 지원서 넣어도 될정도

[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 12

minwoo95 — Thu, 30 Apr 2026 20:11:01 +0900

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

Contribute to Hot6-NovelCraft/Hot6-NovelCraft development by creating an account on GitHub.

github.com

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

Contribute to MinWoo1995/Hot6-NovelCraft-local development by creating an account on GitHub.

github.com

1. 오늘 한 일
오늘은 NovelCraft 프로젝트에서 이벤트 도메인 전체를 설계부터 구현까지 완성했다.
관리자와 사용자 권한을 명확히 분리하고, 선착순 동시성 제어와 Redis 캐싱 전략을 적용했으며,
포인트 즉시 지급 및 Kafka 기반 전체 회원 알림 발송까지 연동했다.
마지막으로 CodeRabbit 리뷰 반영 후 컨트롤러/서비스 테스트 코드를 작성해 커버리지 100%를 달성했다.

구현 API 목록

POST /api/admin/events - 이벤트 생성 (관리자)
GET /api/admin/events - 이벤트 목록 조회 (관리자, 실시간)
GET /api/admin/events/{eventId} - 이벤트 상세 조회 (관리자)
GET /api/admin/events/{eventId}/participants - 이벤트별 참여자 목록 조회 (관리자)
GET /api/events - 이벤트 목록 조회 (사용자, Redis 캐싱)
GET /api/events/{eventId} - 이벤트 상세 조회 (사용자, 종료 이벤트 캐싱)
POST /api/events/{eventId}/participants - 이벤트 참여 신청 (사용자, 선착순 + 포인트 지급)

추가 작업

AdminEventController / UserEventController 권한별 분리
AdminEventService / UserEventService 역할별 분리
EventExceptionEnum 구현 (ErrorCode 인터페이스 구현)
EventParticipant 테이블 (event_id, user_id) UniqueConstraint 적용
SecurityConfig /api/admin/** SUPER_ADMIN, ADMIN 권한 체크 추가
RedisConfig JavaTimeModule 적용 (LocalDateTime 직렬화 지원)
PointService chargeEventReward() 메서드 추가
NotificationType EVENT_CREATED 추가
NotificationEvent eventCreated() 정적 팩토리 메서드 추가
CodeRabbit 리뷰 7건 반영
컨트롤러/서비스 테스트 코드 4개 파일 48개 케이스 작성

2. 기술 선정 이유
2-1. Redisson 분산락 - 선착순 동시성 제어
이벤트 참여 신청은 짧은 시간에 트래픽이 폭발적으로 몰리는 구조라 동시성 제어가 핵심이었다.
세 가지 방식을 비교했다.

DB 비관적 락은 트래픽이 집중될 때 DB 커넥션을 오래 점유하고 병목이 생긴다.
선착순 이벤트처럼 순간적으로 수백 건이 몰리는 상황에서는 적합하지 않다고 판단했다.

Lua 스크립트는 Redis에서 원자적으로 처리가 가능하지만,
카운터 관리 로직이 복잡해지고 디버깅이 어렵다는 단점이 있다.

Redisson 분산락은 이미 프로젝트에 Redis 인프라가 구성되어 있어 추가 비용이 없고,
TTL 기반으로 데드락을 방지하며 멀티 인스턴스 환경에서도 동작한다.
구현도 직관적이어서 가장 적합하다고 판단했다.

RLock lock = redissonClient.getLock("lock:event:participate:" + eventId);
boolean acquired = lock.tryLock(5, 3, TimeUnit.SECONDS);

waitTime 5초는 대기 허용 시간이고, leaseTime 3초는 락 자동 해제 시간이다.
서버 장애로 락 해제가 안 되는 상황을 TTL이 자동으로 막아준다.

추가로 EventParticipant 테이블에 (event_id, user_id) UniqueConstraint를 걸어
Redisson 락이 leaseTime 초과로 뚫리는 극한 케이스에서도 DB 레벨에서 최종 방어하는 이중 동시성 제어 구조로 설계했다.

1차 방어 - Redisson 분산락 : 순차 처리, 선착순 인원 제어
2차 방어 - DB UniqueConstraint : 중복 참여 최종 방어

2-2. Redis 캐싱 전략 - 조회 API 부하 분산
이벤트 조회 API는 참여 신청과 달리 실시간 정확성이 덜 중요한 반면 요청이 매우 많을 수 있다.
캐싱 대상과 TTL을 역할에 따라 명확히 나눴다.

사용자 이벤트 목록 조회 - TTL 5분 제목, 기간 등 메타 정보는 자주 바뀌지 않으므로 단기 캐싱을 적용했다.
관리자가 이벤트를 생성하면 캐시를 즉시 evict해 정합성을 유지했다.

종료된 이벤트 상세 조회 - TTL 7일 이벤트가 종료되면 결과가 확정되어 더 이상 변경이 없다.
종료 시점에 Redis에 캐싱하면 이후 결과 조회 트래픽이 몰려도 DB에 부하가 없다.

진행 중 이벤트 / 참여 API - 캐싱 없음 실시간 참여 현황과 선착순 결과는 정확성이 중요하므로 캐싱을 적용하지 않았다.

처음에는 사용자 결과 조회도 캐싱 없이 가면 부하가 생기지 않냐는 이슈가 있었는데,
이벤트 종료 후에는 결과가 고정되므로 종료 시점에 캐싱하면 된다는 방향으로 정리됐다.

2-3. Kafka 기반 알림 발송 - 이벤트 생성 시 독자 전체 공지
알림 팀원이 이미 ApplicationEventPublisher + Kafka 기반 알림 인프라를 구축해놓았다.
@TransactionalEventListener(phase = AFTER_COMMIT)로 트랜잭션 커밋 이후에
Kafka에 메시지를 발행하는 구조라 알림 발송 실패가 이벤트 생성 트랜잭션에 영향을 주지 않는다.

이 인프라를 그대로 활용해 이벤트 생성 시 READER 역할을 가진 사용자에게만 알림을 발송했다.
전체 유저를 한 번에 메모리에 올리면 OOM 위험이 있어 1000건씩 페이지 단위로 배치 조회하는 방식을 적용했다.

javaint page = 0;
int batchSize = 1000;
while (true) {
    PageRequest pageRequest = PageRequest.of(page, batchSize);
    List<User> readers = userRepository.findAllByRole(UserRole.READER, pageRequest).getContent();
    if (readers.isEmpty()) break;
    readers.forEach(user -> eventPublisher.publishEvent(
            NotificationEvent.eventCreated(user.getId(), saved.getTitle(), saved.getId())
    ));
    page++;
}

3. 트러블슈팅
3-1. LocalDateTime Redis 직렬화 실패
문제 상황
사용자 이벤트 목록 조회 API를 호출하자 500 에러가 발생했다.
에러 메시지는 다음과 같았다.
SerializationException: Could not write JSON: Java 8 date/time type
`java.time.LocalDateTime` not supported by default

원인 분석
RedisConfig를 확인하니 JavaTimeModule이 적용된 ObjectMapper로 serializer를 만들었는데
실제 setValueSerializer()에는 기본 생성자로 새로 만든 serializer를 넣고 있었다.
JavaTimeModule이 적용된 serializer 변수가 완전히 무시되고 있었던 것이다.
java// 문제 코드 - serializer 변수가 있지만 새 객체를 넣음
GenericJackson2JsonRedisSerializer serializer =
new GenericJackson2JsonRedisSerializer(objectMapper); // 이 변수가 무시됨

template.setValueSerializer(new GenericJackson2JsonRedisSerializer()); // 기본 생성자
template.setHashValueSerializer(new GenericJackson2JsonRedisSerializer()); // 기본 생성자

해결
팀원들과 협의 후 RedisConfig에서 두 줄을 수정했다.
기본 생성자 대신 JavaTimeModule이 적용된 serializer 변수를 그대로 사용하도록 변경했다.
기존 도메인에는 LocalDateTime을 Redis에 캐싱하는 곳이 없어 사이드이펙트가 없었다.
java// 수정 후
template.setValueSerializer(serializer);
template.setHashValueSerializer(serializer);

3-2. SecurityConfig 권한 설정 - SUPER_ADMIN vs ADMIN
문제 상황
이벤트 생성 API를 Postman으로 테스트하니 403 Forbidden이 떨어졌다.
DB를 확인하니 테스트 계정의 role이 SUPER_ADMIN이었다.

원인 분석
SecurityConfig에 /api/admin/** 에 대해 hasAuthority("SUPER_ADMIN")으로 설정했는데,
이게 SUPER_ADMIN 단독으로만 열려있는 상태였다.

해결
실무상 SUPER_ADMIN 외에도 담당 ADMIN도 이벤트 관리가 가능해야 한다는 판단으로
hasAnyAuthority("ADMIN", "SUPER_ADMIN")으로 변경했다.
CodeRabbit이 권한 범위가 넓다고 지적했지만 기획 의도에 맞는 설정이라 의견을 답변으로 달고 유지했다.

3-3. CodeRabbit 리뷰 반영 - 7건
3-3-1. evictEventListCache() 중복 호출 (Minor)
AdminEventService의 createEvent()에서 동일한 evictEventListCache()를 두 번 호출하고 있었다.
불필요한 Redis 스캔/삭제가 2배 발생하는 문제였다. 한 번만 호출하도록 수정했다.

3-3-2. 캐시 키에 size/sort 누락 (Major)
UserEventService의 getEventList()에서 캐시 키를 status:pageNumber로만 구성했다.
같은 페이지 번호라도 size나 sort가 다른 요청이 동일 캐시를 재사용하는 문제가 있었다.
캐시 키에 pageSize와 sort를 추가했다.

java// 수정 전
String cacheKey = EVENT_LIST_CACHE_KEY + status + ":" + pageable.getPageNumber();

// 수정 후
String cacheKey = EVENT_LIST_CACHE_KEY + status
        + ":" + pageable.getPageNumber()
        + ":" + pageable.getPageSize()
        + ":" + pageable.getSort();

3-3-3. UPCOMING default 처리 불일치 (Major)
EventStatus의 switch문에서 UPCOMING이 default로 처리되어 findAll()이 호출됐다.
status=UPCOMING 요청이 들어오면 진행 중/종료 이벤트가 섞여서 반환되는 버그였다.
EventRepository에 findAllUpcoming() 쿼리를 추가하고 switch case를 명시적으로 분리했다.

// 수정 후
Page<Event> events = switch (status) {
    case UPCOMING -> eventRepository.findAllUpcoming(now, pageable);
    case ONGOING  -> eventRepository.findAllOngoing(now, pageable);
    case ENDED    -> eventRepository.findAllEnded(now, pageable);
};

3-3-4. 전체 READER 일괄 로드 OOM 위험 (Major)
userRepository.findAllByRole(READER)로 전체 독자를 한 번에 메모리에 올리는 방식이었다.
독자 수가 늘어날수록 생성 API 지연과 메모리 압박이 커지는 구조였다.
1000건씩 페이지 단위로 배치 조회하도록 변경했다.

3-3-5. EventCreateRequest 기간 검증 없음 (Major)
DTO에서 startedAt과 endedAt의 선후 관계 검증이 없어
startedAt > endedAt인 비정상 이벤트가 생성될 수 있었다.
@AssertTrue로 DTO 레벨에서 검증을 추가했다.
서비스 레벨의 중복 검증은 제거하고 EventExceptionEnum.EVENT_INVALID_PERIOD는 향후를 위해 남겨뒀다.

@AssertTrue(message = "이벤트 시작일은 종료일보다 이전이어야 합니다")
public boolean isValidPeriod() {
if (startedAt == null || endedAt == null) return true;
return startedAt.isBefore(endedAt);
}

3-3-6. maxParticipants null 허용 (Major)
@Min만 있고 @NotNull이 없어 null 값이 통과될 수 있었다.
포인트 지급 이벤트 특성상 참여 인원 제한 없이 운영하면 예산 통제가 불가능하다.
@NotNull을 추가해 필수값으로 변경하고, 서비스의 null 체크 분기도 제거했다.
DB의 max_participants 컬럼도 NOT NULL로 변경했다.

3-4. 테스트 코드 - JPA 엔티티 mock() 사용 불가 문제
문제 상황
UserEventServiceTest에서 mock(Event.class)으로 Event 객체를 만들고
given(event.getId()).willReturn(EVENT_ID)로 stubbing을 하니
UnfinishedStubbingException과 UnnecessaryStubbingException이 동시에 터졌다.
UnfinishedStubbingException:
-> at UserEventServiceTest.mockOngoingEvent(UserEventServiceTest.java:59)

원인 분석
JPA 엔티티에 @Getter, @NoArgsConstructor 등 Lombok 어노테이션이 붙어있으면
Mockito가 final 메서드로 인식하는 케이스가 있다.
특히 getId() 같은 메서드는 내부적으로 stubbing이 완료되지 않은 상태에서
다른 메서드 호출이 중간에 끼어들어 UnfinishedStubbingException이 발생했다.
또한 각 테스트에서 사용하지 않는 stubbing이 포함되어 UnnecessaryStubbingException도 함께 발생했다.

해결
mock(Event.class) 대신 실제 Event.create() 정적 팩토리 메서드로 실제 객체를 생성하도록 변경했다.
엔티티는 mock()을 피하고 실제 객체를 만드는 것이 올바른 테스트 패턴이다.
java// 수정 전 - mock() 사용 (문제 발생)
private Event mockOngoingEvent() {
    Event event = mock(Event.class);
    given(event.getId()).willReturn(EVENT_ID);
    given(event.isOngoing()).willReturn(true);
    ...
}

// 수정 후 - 실제 객체 사용
private Event ongoingEvent() {
    return Event.create(1L, "테스트 이벤트", "설명",
            5000L, 100L, NOW.minusDays(1), FUTURE);
}

RLock은 인터페이스라 @Mock 필드 선언이 불가능했다.
setupLock() 헬퍼 메서드 내부에서 직접 mock(RLock.class)로 생성하는 방식으로 해결했다.

javaprivate RLock setupLock(boolean acquired) throws InterruptedException {
    RLock mockLock = mock(RLock.class);
    given(redissonClient.getLock(anyString())).willReturn(mockLock);
    given(mockLock.tryLock(anyLong(), anyLong(), any(TimeUnit.class))).willReturn(acquired);
    lenient().when(mockLock.isHeldByCurrentThread()).thenReturn(acquired);
    return mockLock;
}

4. 느낀 점
오늘은 단순히 CRUD를 넘어 실제 서비스에서 고민해야 할 기술적인 문제들을 직접 설계하고 해결한 하루였다.
선착순 이벤트 참여라는 요구사항 하나에서 Redisson 분산락, DB UniqueConstraint 이중 방어,
Redis 캐싱 전략, 페이지 단위 배치 알림 발송까지 여러 기술이 자연스럽게 연결됐다.

기술은 문제를 해결하기 위해 선택하는 것이고, 각 선택에는 명확한 이유가 있어야 한다는 것을 다시 한번 체감했다.

CodeRabbit 리뷰에서 캐시 키에 size/sort가 빠진 것과 UPCOMING default 처리 불일치 버그를 잡아줬다.
혼자 개발하면 놓치기 쉬운 부분인데 자동화된 리뷰가 실질적인 버그를 찾아준다는 점이 인상적이었다.
특히 전체 READER 일괄 로드 OOM 위험 지적은 지금은 유저 수가 적어 문제가 없지만
서비스가 커지면 치명적인 문제가 될 수 있는 부분이었다.

코드를 작성할 때 현재 상황뿐 아니라 스케일이 커졌을 때를 항상 염두에 두어야 한다는 것을 배웠다.
테스트 코드에서 JPA 엔티티를 mock()으로 쓰면 안 된다는 것도 직접 겪으면서 알게 됐다.

이론으로는 "엔티티는 실제 객체를 써야 한다"는 걸 알고 있었지만,
UnfinishedStubbingException이 왜 발생하는지 원인을 파악하고 해결하는 과정에서 더 깊이 이해하게 됐다.

테스트 코드도 설계가 필요하고, 올바른 패턴을 지켜야 유지보수가 편하다는 것을 다시 느꼈다.

오후에 알림 팀원이 Kafka 인프라를 완성하면 eventCreated() 연동만 하면 전체 흐름이 완성된다.
오늘 설계한 구조가 팀원의 코드와 깔끔하게 붙을 수 있도록 인터페이스를 잘 맞춰둔 것 같아 뿌듯했다.