minwoo95 님의 블로그

[파이널 과제] 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() 연동만 하면 전체 흐름이 완성된다.
오늘 설계한 구조가 팀원의 코드와 깔끔하게 붙을 수 있도록 인터페이스를 잘 맞춰둔 것 같아 뿌듯했다.

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

minwoo95 — Wed, 29 Apr 2026 21:59:44 +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 프로젝트에서 수익 환전 도메인의 관리자 기능을 추가 구현하고, 컨트롤러/서비스 테스트 코드를 전면 재작성했다.
관리자 환전 목록 조회 API 구현 - GET /api/admin/exchanges
관리자 환전 상세 조회 API 구현 - GET /api/admin/exchanges/{id}
관리자 환전 승인 API 구현 - PUT /api/admin/exchanges/{id}/approve
관리자 환전 거절 API 구현 - PUT /api/admin/exchanges/{id}/reject
AdminWithdrawalController, AdminWithdrawalService를 domain.admin 패키지에 추가
WithdrawalRepositoryCustom에 관리자용 findAllWithFilters() 추가 (authorId 없이 전체 조회)
컨트롤러 테스트 3개, 서비스 테스트 3개, 엔티티 로직 테스트 1개 전면 재작성
CodeRabbit 리뷰 3건 반영

2. 트러블슈팅
2-1. @WebMvcTest에서 Security 빈 누락으로 전체 컨텍스트 로딩 실패
문제 상황
@WebMvcTest로 컨트롤러 테스트를 실행하자 애플리케이션 컨텍스트 자체가 뜨지 않았다. 에러 메시지는 BeanCreationException으로, JwtFilter → JwtUtil → RedisUtil → UserDetailsService → UserCacheService 순으로 빈을 찾지 못한다는 내용이었다.
원인 분석
@WebMvcTest는 컨트롤러 레이어만 로드하지만 SecurityConfig가 함께 로드되면서 JwtFilter가 등록된다. JwtFilter는 JwtUtil을 주입받고, JwtUtil은 RedisUtil을 주입받는 의존성 체인이 형성된다. @WebMvcTest는 이 빈들을 자동으로 등록하지 않으므로 컨텍스트 로딩 자체가 실패한 것이다.
해결
Security 관련 빈 5개를 @MockBean으로 등록하고, @AutoConfigureMockMvc(addFilters = false)로 실제 필터 체인을 비활성화했다. 인증은 SecurityContextHolder에 직접 인증 객체를 세팅하는 방식으로 처리했다.
java@WebMvcTest(BankAccountController.class)
@AutoConfigureMockMvc(addFilters = false)
class BankAccountControllerTest {

    @MockBean JwtUtil jwtUtil;
    @MockBean RedisUtil redisUtil;
    @MockBean UserDetailsService userDetailsService;
    @MockBean UserCacheService userCacheService;
    @MockBean JpaMetamodelMappingContext jpaMappingContext;

    @BeforeEach
    void setUp() {
        User mockUser = mock(User.class);
        given(mockUser.getId()).willReturn(1L);
        UserDetailsImpl userDetails = mock(UserDetailsImpl.class);
        given(userDetails.getUser()).willReturn(mockUser);
        SecurityContextHolder.getContext().setAuthentication(
                new UsernamePasswordAuthenticationToken(userDetails, null, List.of())
        );
    }
}

2-2. BankAccountServiceTest - save() 반환값 미사용으로 id가 null
문제 상황
BankAccountServiceTest의 계좌 등록 성공 케이스에서 res.expiredAt() 검증 시 Expecting actual not to be null 에러가 발생했다. expiredAt이 null이 되는 이유를 찾아야 했다.
원인 분석
서비스 코드를 보니 bankAccountRepository.save(bankAccount) 후 반환값을 변수에 담지 않고 원본 bankAccount를 계속 사용하고 있었다. Mock 환경에서는 JPA처럼 save() 후 같은 객체에 id가 채워지지 않는다. 결국 bankAccount.getId()가 null인 채로 AccountVerification.create(null, code)가 호출되고, BankAccountVerifyResponse.of()에서 bankAccountId가 null로 세팅된 것이다.
해결
서비스 코드에서 save() 반환값을 savedAccount로 받아 이후 모든 곳에서 savedAccount를 사용하도록 수정했다. Mock에서도 반환값을 사용하는 것이 올바른 패턴이다.
java// 수정 전
bankAccountRepository.save(bankAccount);

// 수정 후
BankAccount savedAccount = bankAccountRepository.save(bankAccount);
AccountVerification verification = AccountVerification.create(savedAccount.getId(), verificationCode);
String maskedNumber = savedAccount.getMaskedAccountNumber(request.accountNumber());
return BankAccountVerifyResponse.of(savedAccount, maskedNumber, verification.getExpiredAt());

2-3. 단일 테스트 실패로 전체 테스트가 실행되지 않아 커버리지가 한 클래스만 표시
문제 상황
IntelliJ에서 exchange 패키지 전체를 실행했는데 커버리지 리포트에 WithdrawalService 하나만 잡혔다. 나머지 클래스들이 전혀 커버리지에 반영되지 않는 상황이었다.
원인 분석
Gradle은 테스트 중 하나라도 실패하면 빌드를 중단하는 기본 동작을 한다. BankAccountServiceTest가 실패하면서 이후 테스트들이 아예 실행되지 않은 것이었다. 커버리지는 실행된 테스트만 반영하므로 WithdrawalServiceTest만 실행된 결과가 나온 것이다.
해결
BankAccountService 서비스 코드의 save() 반환값 문제를 수정하여 BankAccountServiceTest가 통과되도록 했다. 이후 전체 테스트가 정상 실행되면서 커버리지가 모든 클래스에 반영됐다.

3. 코드래빗 리뷰 반영
3-1. 락 해제 원자성 문제 - Lua Script 교체 (Critical)
기존 코드는 get() 후 delete()를 별도로 호출하는 비원자적 방식이었다. 락 만료 직후 다른 요청이 같은 키로 락을 재획득한 사이에 delete()가 호출되면 타인의 락을 지우는 경쟁 조건이 발생한다. Lua Script로 get과 delete를 하나의 원자적 연산으로 묶어 해결했다.
java// 수정 전 - 비원자적
Object currentValue = redisTemplate.opsForValue().get(lockKey);
if (lockValue.equals(currentValue)) {
    redisTemplate.delete(lockKey);
}

// 수정 후 - Lua Script로 원자적 처리
private static final DefaultRedisScript<Long> RELEASE_LOCK_SCRIPT = new DefaultRedisScript<>(
    "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end",
    Long.class
);
redisTemplate.execute(RELEASE_LOCK_SCRIPT, List.of(lockKey), lockValue);

3-2. startDate > endDate 역전 검증 추가 (Minor)
관리자 환전 목록 조회 API에서 startDate가 endDate보다 늦은 경우 그대로 쿼리가 실행되어 항상 빈 결과를 반환하는 문제가 있었다. 컨트롤러에서 400 에러로 빠르게 실패하도록 검증을 추가했다.
javaif (startDate != null && endDate != null && startDate.isAfter(endDate)) {
throw new IllegalArgumentException("시작일이 종료일보다 클 수 없습니다");
}

3-3. 정렬 tie-breaker 추가 (Minor)
findWithFilters, findAllWithFilters 모두 requestedAt 단일 정렬이라 동일 시각에 신청된 레코드가 존재할 경우 페이지 경계에서 중복/누락이 발생할 수 있었다. id DESC를 보조 정렬로 추가하여 안정적인 페이지네이션을 보장했다.
java// 수정 전
.orderBy(withdrawal.requestedAt.desc())

// 수정 후
.orderBy(withdrawal.requestedAt.desc(), withdrawal.id.desc())

4. 느낀 점
오늘은 테스트 코드와 관련된 트러블슈팅이 많았다. @WebMvcTest 환경에서 Security 빈 의존성 체인이 컨텍스트 로딩 자체를 막는다는 걸 직접 겪으면서 Spring Security와 테스트 환경의 관계를 더 깊이 이해하게 됐다.
특히 save() 반환값을 사용하지 않는 서비스 코드 문제가 운영 환경에서는 JPA가 알아서 처리해줘서 드러나지 않다가 Mock 환경에서만 터지는 케이스였다. 테스트 코드가 운영 코드의 숨어있는 문제를 찾아주는 역할도 한다는 점을 다시 한번 체감했다.
CodeRabbit의 Lua Script 제안은 단순히 get 후 delete가 비원자적이라는 이론적 지식을 실제 코드에 적용하는 좋은 계기가 됐다. 분산 환경에서 원자성이 보장되지 않으면 어떤 문제가 생기는지 구체적으로 생각해볼 수 있었다.

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

minwoo95 — Tue, 28 Apr 2026 21:31:13 +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. 오늘 한 일
오늘은 수익/환전 도메인 전체를 설계부터 구현까지 완료했다. 튜터님이 "어줍잖게 구현하면 포트폴리오에서 발목 잡힌다"고 하신 만큼, 금융 도메인에 맞는 디테일을 최대한 챙기며 작업했다.
수익/환전 도메인 ERD 설계 (BankAccount, AccountVerification, Revenue, Withdrawal 4개 엔티티)
계좌 등록 + 1원 인증 API 구현 (2-step: 인증 요청 / 코드 검증 분리)
수익 현황 조회 API 구현 (Revenue 집계 쿼리 + Redis 캐싱)
환전 신청 API 구현 (Redis 분산락 동시성 제어 + 수수료 계산 + 잔액 트랜잭션)
환전 내역/상세 조회 API 구현 (QueryDSL 동적 쿼리 + 기간/상태 필터 + 페이징)
수익 분석 통계 API 구현 (QueryDSL GROUP BY 월별/주별 집계 + Redis 캐싱)
관리자 환전 승인/거절 서비스 로직 선작업 (TODO: Admin Controller 연결 대기)
API 명세서 작성 (전체 8개 엔드포인트)
총 37개 파일, API 6개(작가측) + 2개(관리자 TODO) 구현 완료.

2. 트러블슈팅
2-1. BankVerificationClient 빈 등록 실패
문제 상황
애플리케이션 실행 시 아래 에러가 발생했다.
Parameter 2 of constructor in BankAccountService required a bean of type 'BankVerificationClient' that could not be found.
원인 분석
처음에 외부 은행 API 구현체를 @Profile("dev")와 @Profile("prod")로 분리했는데, spring.profiles.active 설정이 없어서 어떤 프로파일에도 해당하지 않았고 Mock 빈이 등록되지 않은 것이었다.
해결
@Profile 대신 @ConditionalOnProperty로 전환했다. useb.api.enabled: true이면 실제 API 구현체가, 설정이 없거나 false이면 Mock 구현체가 자동으로 등록되도록 변경했다. 이후 금융규제로 인해 실제 은행 API 테스트가 불가능하다는 점을 고려하여, 최종적으로는 UseBVerificationClient를 삭제하고 LocalBankVerificationClient(시뮬레이션)를 @Component로 단순 등록하는 구조로 정리했다. BankVerificationClient 인터페이스는 유지하여 운영 전환 시 실제 구현체로 교체할 수 있는 구조를 열어두었다.

2-2. AES 암호화 설정값 미등록으로 빈 생성 실패
문제 상황
@Profile("dev") 문제를 해결한 뒤에도 아래 에러가 발생했다.
Could not resolve placeholder 'encryption.aes.secret-key' in value "${encryption.aes.secret-key}"
원인 분석
계좌번호를 AES 암호화하기 위해 AesEncryptionUtil을 @Component로 등록했는데, application.yml에 encryption.aes.secret-key와 encryption.aes.iv 값을 정의하지 않은 상태였다. Spring이 빈 생성 시 @Value 플레이스홀더를 해석하지 못해 에러가 발생한 것이다.
해결
application.yml에 아래 설정을 추가했다. AES-128은 키와 IV가 정확히 16바이트여야 한다.
yamlencryption:
  aes:
    secret-key: novelcraft1234ab
    iv: novelcraft1234iv

2-3. 기존 예외 처리 구조와 불일치
문제 상황
컴파일은 통과했지만, ExchangeException이라는 커스텀 예외 클래스를 별도로 만들어 사용하고 있었는데 기존 프로젝트의 예외 처리 구조와 달랐다.
원인 분석
기존 프로젝트는 ErrorCode 인터페이스 + ServiceErrorException 구조로 GlobalExceptionHandler에서 일괄 처리하는 방식이었다. ExchangeException은 이 핸들러에 잡히지 않아 500 에러로 빠질 수 있었다.
해결
ExchangeException 클래스를 삭제하고, ExchangeExceptionEnum이 기존 ErrorCode 인터페이스를 implements하도록 변경했다. 서비스 레이어에서는 new ServiceErrorException(ExchangeExceptionEnum.XXX) 형태로 던지도록 통일하여 GlobalExceptionHandler에서 정상적으로 처리되도록 했다.

3. 의사결정 - 1원 계좌 인증 외부 API 선택
배경
수익 환전 기능에서 계좌 인증이 필수적이었다. 실제 서비스에서는 useB, CODEF 등 외부 은행 API를 통해 1원 입금 → 인증코드 확인 방식으로 계좌를 검증한다. 포트원(PortOne)은 결제와 본인인증에 특화되어 있어 1원 계좌 인증은 지원하지 않았다.
문제
useB, CODEF, 금융결제원 오픈뱅킹 등을 조사한 결과, 모든 서비스가 사업자 등록 또는 기업 계약이 필요했다. CODEF는 샌드박스를 제공하지만 고정 응답값만 반환하는 구조여서 실질적인 테스트 효과는 Mock과 차이가 없었다.
결정
BankVerificationClient 인터페이스로 외부 API 호출을 추상화하고, LocalBankVerificationClient에서 실제 1원 인증 플로우를 자체 시뮬레이션하는 구조로 구현했다. 사전 등록된 가상 계좌 5개(국민/신한/우리/하나/카카오뱅크)를 두고 예금주 확인, 인증코드 생성, 은행 점검시간 체크까지 실제와 동일한 비즈니스 로직이 동작한다. 운영 환경에서는 인터페이스를 구현한 실제 API 연동 구현체로 교체하면 된다.

4. 느낀 점
오늘은 수익/환전이라는 금융 도메인을 처음부터 끝까지 설계하고 구현하면서, 일반적인 CRUD와는 차원이 다른 복잡도를 체감했다.
가장 고민이 깊었던 부분은 동시성 제어였다. 같은 작가가 동시에 환전을 신청하면 잔액 초과 환전이 일어날 수 있는데, Redis 분산락으로 하나의 요청만 통과시키는 구조를 잡았다. 단순히 "락을 걸었다"가 아니라 왜 비관적 락 대신 Redis를 선택했는지, finally에서 반드시 락을 해제하는 이유가 뭔지 등을 설명할 수 있어야 포트폴리오에서 의미가 있다는 걸 느꼈다.
외부 API 연동 부분에서는 금융 규제의 벽을 실감했다. 개인 개발자가 실제 은행 API를 테스트할 방법이 사실상 없었다. 처음에는 useB를 연동하려고 했지만, 사업자 등록 없이는 불가능하다는 걸 알게 됐고, 결국 인터페이스 분리 + 시뮬레이션 구현체로 방향을 잡았다. 이 과정에서 "없는 걸 있는 척 하는 것보다, 구조만 깔끔하게 열어두는 게 낫다"는 판단을 했는데, 면접에서도 솔직하게 "금융규제로 실연동은 불가능했고, 대신 비즈니스 로직은 실제와 동일하게 구현했습니다"라고 설명할 수 있을 것 같다.
상태 전이 검증도 인상 깊었다. WithdrawalStatus enum에 canTransitionTo() 메서드를 넣어서 COMPLETED → REJECTED 같은 잘못된 전이를 엔티티 레벨에서 차단하는 구조인데, 이런 방어 로직 하나가 금융 도메인의 신뢰도를 결정한다는 걸 배웠다.
내일은 Postman으로 전체 API 플로우를 테스트하고, 시간이 되면 서비스 레이어 단위 테스트 코드 작성까지 진행할 예정이다.

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

minwoo95 — Fri, 24 Apr 2026 19:24: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

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. 오늘 한 일
오늘은 중간 발표 준비를 진행했다. 발표 주제는 mentor/mentoring 도메인 고도화 내용으로 선정했고, 의사결정 1개와 문제해결 2개 구조로 구성했다.

발표 주제 선정 및 구성 (의사결정 1개 + 문제해결 2개)
발표 문서 작성 (배경, 요구사항, 의사결정, 장단점)
발표 대본 작성 (5분 분량)
팀 목표 재설정 논의

또한 팀 회의에서 프로젝트 방향을 재설정했다. 기존에는 도메인별 기능 구현 완성도에 집중했는데, 앞으로는 프로젝트 디테일보다 고도화와 부하테스트 쪽에 더 집중하기로 팀 목표를 수정했다. 기능이 돌아가는 것보다 왜 이렇게 설계했는가, 실제 트래픽에서 얼마나 버티는가를 증명하는 방향으로 진행할 예정이다.

2. 발표 내용 정리
의사결정 - 멘토 조회 API v1/v2 분리 (QueryDSL N+1 해결)
getMyMentees API가 반복문 안에서 멘티, 소설, 피드백을 각각 개별 조회하는 N+1 구조였다. 멘티가 N명이면 쿼리가 1+3N번 나가는 문제였다. 이를 해결하기 위해 기존 v1은 유지하고 QueryDSL JOIN 단일 쿼리로 구현한 v2 엔드포인트를 추가했다. 팀 컨벤션상 엔티티 연관관계를 걸지 않아 Fetch Join을 쓸 수 없었고, QueryDSL로 직접 JOIN 쿼리를 짜는 방식을 선택했다.
문제해결 1 - 스케줄러 메모리 부하
매일 자정에 멘토 등급을 자동 조정하는 배치가 승급 대상 멘토를 한 번에 전부 List로 가져오는 구조였다. 코드래빗 리뷰에서 두 가지 문제를 잡아줬다. 첫째, 멘토 수가 늘어나면 메모리가 터질 수 있다. 둘째, @Transactional 안에서 처리한 엔티티가 배치 종료까지 persistence context에 쌓인다. 청크 100명 단위 페이지네이션, ID ASC 정렬 고정, 청크마다 flush()/clear() 호출로 해결했다.
문제해결 2 - QueryDSL LEFT JOIN null 노출
v1은 반복문 안에서 orElse("알 수 없는 사용자")로 null을 방어했는데, v2로 QueryDSL 단일 쿼리로 전환하면서 이 방어 로직을 놓쳤다. 탈퇴한 유저나 삭제된 소설 조회 시 응답에 null이 그대로 들어가는 문제였다. Expressions.cases()로 쿼리 단에서 직접 fallback 처리했다.

3. 느낀 점
발표 준비를 하면서 코드를 짜는 것과 그걸 말로 설명하는 건 완전히 다른 작업이라는 걸 느꼈다. 코드는 짰는데 왜 그렇게 짰는지 말로 정리하려니 생각보다 어려웠다.
팀 목표를 고도화와 부하테스트 중심으로 바꾼 것도 의미있는 결정이었다. 발표 준비를 하면서 "개선 전후 수치가 있으면 훨씬 설득력 있을 텐데"라는 생각이 계속 들었다. 앞으로는 N+1 개선 전후 쿼리 수 비교, 인덱스 적용 전후 실행 계획 비교, 부하테스트 결과를 직접 측정하고 정리하는 작업을 병행할 예정이다.

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

minwoo95 — Thu, 23 Apr 2026 20:27:51 +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 프로젝트의 Jenkins CI/CD 파이프라인 완성 및 AWS 앱 서버 배포까지 전 과정을 마무리했다.
Jenkins Credentials 등록 (Docker Hub, App EC2 SSH Key, MySQL, AWS S3, OAuth2, JWT, PortOne, CoolSMS, 국립도서관 API 총 18개)
GitHub Webhook 연동 (main 브랜치 Push 시 자동 빌드 트리거)
Jenkins Pipeline 생성 및 Jenkinsfile 작성
Docker Hub 레포지토리 생성 및 이미지 Push 성공
앱 EC2 Docker 설치 및 Redis 설치
보안 그룹 인바운드 규칙 추가 (Jenkins EC2 → 앱 EC2 SSH 허용)
Jenkins → Docker Hub → 앱 EC2 자동 배포 파이프라인 완성
application-prod.yml 환경변수 누락 수정 (app.frontend.url)
Postman으로 API 응답 확인 완료

2. 트러블슈팅
2-1. Jenkinsfile 파일명 대소문자 문제
문제 상황
Jenkins 빌드 시 아래 에러가 발생했다.
ERROR: Unable to find Jenkinsfile from git
원인 분석
파일명을 jenkinsfile(소문자)로 생성했는데 Jenkins는 반드시 Jenkinsfile(대문자 J)을 찾는다. 대소문자가 달라 Jenkins가 파일을 인식하지 못한 것이다.
해결
bashgit mv jenkinsfile Jenkinsfile
git commit -m "fix: Jenkinsfile 파일명 대문자로 수정"
git push origin main

2-2. Dockerfile 주석 파싱 에러
문제 상황
Docker 빌드 중 아래 에러가 발생했다.
ERROR: failed to solve: dockerfile parse error on line 1: unknown instruction: 1단계:
원인 분석
Dockerfile에 한글 주석을 # 없이 그냥 텍스트로 작성했다. Docker 파서가 첫 줄의 1단계:를 Dockerfile 명령어로 인식하려다 에러를 낸 것이다.
해결
모든 한글 주석 앞에 #을 붙였다.
dockerfile# 1단계: 빌드
FROM gradle:8.5-jdk17 AS build

2-3. openjdk:17-jdk-slim 이미지 not found
문제 상황
Docker 빌드 중 아래 에러가 발생했다.
ERROR: failed to solve: openjdk:17-jdk-slim: not found
원인 분석
openjdk:17-jdk-slim 이미지가 Docker Hub에서 deprecated 되어 더 이상 존재하지 않았다.
해결
실행 스테이지 베이스 이미지를 eclipse-temurin:17-jre-jammy로 교체했다.
dockerfile# 2단계: 실행
FROM eclipse-temurin:17-jre-jammy
WORKDIR /app
COPY --from=build /app/build/libs/*.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

2-4. Docker Hub Push denied
문제 상황
Docker 이미지 Push 시 아래 에러가 발생했다.
denied: requested access to the resource is denied
원인 분석
두 가지 원인이 있었다. 첫째로 Jenkinsfile의 이미지 태그가 minwoo/novelcraft로 되어있었는데 실제 Docker Hub 유저네임은 jmw1995였다. 둘째로 Docker Hub에 novelcraft 레포지토리 자체가 생성되어 있지 않았다.
해결
Jenkinsfile의 이미지 이름을 jmw1995/novelcraft로 수정하고, Docker Hub에서 novelcraft 레포지토리를 Public으로 생성했다.

2-5. Jenkins Built-In Node 오프라인
문제 상황
Jenkins 빌드가 Waiting for next available executor 상태에서 멈추고 Built-In Node가 오프라인으로 표시됐다.
원인 분석
두 가지 문제가 복합적으로 발생했다. Free Swap Space가 0B로 메모리가 부족했고, Free Temp Space가 951MB로 Jenkins의 임계값인 1GiB 미만이어서 노드가 자동으로 오프라인 처리된 것이었다.
해결
Swap 메모리 2GB를 추가 생성하고, Jenkins Nodes 설정에서 Free Temp Space Threshold를 500MB로 낮춘 후 노드를 온라인으로 복구했다.
bashsudo 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

2-6. App EC2 SSH Connection timed out
문제 상황
Jenkins에서 앱 EC2로 SSH 배포 시 아래 에러가 발생했다.
ssh: connect to host 43.200.129.27 port 22: Connection timed out
원인 분석
앱 EC2의 보안 그룹(novel-app-security-group)에 Jenkins EC2 IP(43.201.153.0)에 대한 SSH 인바운드 규칙이 없었다. Jenkins EC2와 앱 EC2가 서로 다른 보안 그룹을 사용하고 있었는데 처음에 Jenkins 서버의 보안 그룹(novel-craft-security-group)만 수정하고 앱 EC2의 보안 그룹은 수정하지 않은 것이 원인이었다.
해결
novel-app-security-group에 Jenkins EC2 IP를 SSH 허용 규칙으로 추가했다.
유형 : SSH
포트 : 22
소스 : 43.201.153.0/32

2-7. app.frontend.url 환경변수 미설정으로 애플리케이션 실행 실패
문제 상황
배포 후 컨테이너 로그에서 아래 에러가 반복됐다.
Could not resolve placeholder 'app.frontend.url' in value "${app.frontend.url}"
원인 분석
OAuth2SuccessHandler에서 @Value("${app.frontend.url}") 로 프론트엔드 URL을 주입받는데 application-prod.yml에 해당 키가 정의되어 있지 않았다. Jenkinsfile에서는 FRONTEND_URL 환경변수로 넘기고 있었지만 yml에서 app.frontend.url로 매핑하는 설정이 누락된 것이었다.
해결
application-prod.yml 최상단에 아래 설정을 추가했다.
yamlapp:
frontend:
url: ${FRONTEND_URL}

3. 느낀 점
오늘은 CI/CD 파이프라인을 처음부터 끝까지 직접 구축하면서 배포 전 과정에서 마주칠 수 있는 문제들을 거의 다 경험한 것 같다.
가장 인상 깊었던 부분은 보안 그룹이었다. Jenkins EC2와 앱 EC2가 서로 다른 보안 그룹을 사용하고 있다는 걸 뒤늦게 파악했는데, 네트워크 인프라 설정에서는 각 리소스가 어떤 보안 그룹에 속해있는지 먼저 확인하는 습관이 필요하다는 것을 느꼈다.
app.frontend.url 누락 문제는 환경변수 이름과 yml 키 이름이 다를 수 있다는 점을 다시 상기시켜줬다. Jenkinsfile에서 FRONTEND_URL로 넘겨도 애플리케이션 코드가 app.frontend.url을 참조하면 다리를 놓아줘야 한다. 배포 전에 application.yml의 모든 플레이스홀더와 실제 주입되는 환경변수 이름을 맞춰두는 것이 중요하다는 것을 배웠다.
Built-In Node가 Swap 메모리 부족으로 오프라인이 된 것도 흥미로운 경험이었다. t3.small 인스턴스는 메모리가 2GB밖에 안 돼서 Jenkins 자체만으로도 메모리가 빡빡하다. Swap을 추가해서 해결했지만 장기적으로는 인스턴스 타입을 올리거나 빌드를 별도 에이전트로 분리하는 방향을 고려해야 할 것 같다.
무엇보다 오늘 GitHub Push 한 번으로 Docker 빌드, 이미지 Push, 앱 서버 자동 배포까지 한 번에 이루어지는 파이프라인이 완성됐다는 게 뿌듯했다. 앞으로 팀원들이 코드를 Push할 때마다 자동으로 배포되니 수동 배포의 번거로움 없이 개발에 집중할 수 있을 것 같다.