Spring Boot 애플리케이션을 서버에 배포하려면 단순히 JAR 파일을 실행하는 것만으로는 부족하다. 서버 접속부터 파일 관리, 프로세스와 서비스 운영, 네트워크, 로그 확인, 롤백까지 전체 흐름을 이해해야 한다.

이번 글에서는 리눅스 서버에 애플리케이션을 배포할 때 필요한 기본 개념과 명령어를 정리해 본다.

목차

1. 일반적인 배포 흐름
2. 배포의 전체 구조
3. 리눅스 기본 명령어
4. 파일 내용 확인과 검색
5. 프로그램, 프로세스, 서비스의 차이
6. 프로세스 확인과 종료
7. systemd로 서비스 관리하기
8. 리눅스 네트워크 기초
9. SSH로 서버 접속하기
10. 실제 배포 흐름
11. 무중단 배포의 기본 개념

1. 일반적인 배포 흐름

일반적인 서버 배포는 다음과 같은 순서로 진행된다.

1. 서버에 SSH로 접속
2. Java, Node.js 같은 런타임 설치
3. 애플리케이션 파일 또는 Docker 이미지 전달
4. 환경 변수와 설정 파일 구성
5. 데이터베이스 마이그레이션
6. 애플리케이션 실행
7. Nginx 리버스 프록시 설정
8. HTTPS 인증서 설정
9. 로그와 상태 확인
10. 문제가 생기면 이전 버전으로 롤백

예를 들어 Spring Boot 애플리케이션이라면 파일을 다음과 같이 구성할 수 있다.

/opt/myapp/
├── app.jar
├── application-prod.yml
└── logs/

애플리케이션 프로세스는 systemd가 관리하고, Nginx가 외부 요청을 애플리케이션에 전달하는 형태다.

2. 배포의 전체 구조

사용자 브라우저
    │
    │ https://api.example.com
    ▼
DNS
도메인 이름을 서버 IP 주소로 변환
    │
    ▼
서버 방화벽
443 포트 요청 허용 여부 확인
    │
    ▼
Nginx
HTTPS 처리 및 요청 전달
    │
    │ http://127.0.0.1:8080
    ▼
Spring Boot 애플리케이션
    │
    ▼
데이터베이스 · Redis · 외부 API

각 요소의 역할을 간단히 정리하면 다음과 같다.

• Linux: 애플리케이션과 Nginx가 실행되는 운영체제
• SSH: 개발자가 서버에 원격으로 접속하는 방법
• systemd: 애플리케이션 프로세스를 실행하고 관리하는 도구
• Nginx: 외부 요청을 애플리케이션으로 전달하는 웹 서버 또는 리버스 프록시
• DNS: 도메인 이름을 서버 IP 주소로 변환하는 시스템
• TLS 인증서: HTTPS 통신을 암호화하고 서버의 신원을 확인하는 인증서
• 로그: 요청, 오류, 애플리케이션 상태를 기록한 정보
• 방화벽: 특정 포트로 들어오는 요청을 허용하거나 차단하는 장치

3. 리눅스 기본 명령어

배포 과정에서 자주 사용하는 명령어부터 살펴보자.

pwd                     # 현재 위치 확인
ls -al                  # 파일 목록 확인
cd /var/www/myapp       # 디렉터리 이동

mkdir app               # 디렉터리 생성
cp source target        # 파일 복사
mv old new              # 파일 이동 또는 이름 변경
rm file                 # 파일 삭제

cat app.log             # 파일 전체 내용 출력
less app.log            # 긴 파일을 페이지 단위로 확인
tail -f app.log         # 실시간 로그 확인

grep "ERROR" app.log    # 문자열 검색
find . -name "*.log"    # 파일 검색

특히 cd, ls, cp, mv, less, tail, grep, find는 배포와 장애 대응 과정에서 자주 사용한다.

rm -rf는 삭제한 내용을 되돌리기 어려우므로 매우 조심해서 사용해야 한다.

리눅스의 파일과 디렉터리

리눅스 터미널은 항상 어떤 디렉터리를 기준으로 동작한다.

pwd는 print working directory의 약자로, 현재 작업 중인 디렉터리를 출력한다.

절대 경로

루트 디렉터리인 /부터 시작하는 전체 경로다. 현재 어느 디렉터리에 있든 항상 같은 파일을 가리킨다.

상대 경로

현재 위치를 기준으로 나타내는 경로다.

.  : 현재 디렉터리
.. : 상위 디렉터리
~  : 현재 사용자의 홈 디렉터리
/  : 파일 시스템의 최상위 디렉터리

리눅스에서 자주 접하는 디렉터리는 다음과 같다.

/var/www는 정적 웹 파일을 둘 때 많이 사용한다. 독립적인 백엔드 애플리케이션은 /opt나 /srv에 두기도 한다.

ls: 파일 목록 확인

• ls -l: 권한, 소유자, 그룹, 크기, 수정 시간 등 상세 정보 표시
• ls -a: .으로 시작하는 숨김 파일까지 표시
• ls -alh: 숨김 파일과 상세 정보를 함께 보여 주고 파일 크기를 KB, MB처럼 읽기 쉽게 표시
  • a: 숨김 파일 포함
  • l: 상세 정보 표시
  • h: 사람이 읽기 쉬운 단위로 파일 크기 표시

mkdir: 디렉터리 생성

mkdir releases

여러 단계의 디렉터리를 한 번에 만들 때는 -p를 사용한다.

mkdir -p /opt/myapp/releases

-p가 없으면 중간 디렉터리가 존재하지 않을 때 오류가 발생한다.

cp: 복사

cp app.jar app-backup.jar

디렉터리 전체를 복사하려면 -r 옵션이 필요하다.

cp -r config config-backup

기존 파일과 같은 이름으로 복사하면 덮어쓸 수 있으므로 운영 서버에서는 대상 경로를 먼저 확인해야 한다.

mv: 이동 또는 이름 변경

파일 이름을 변경할 수 있다.

mv app-new.jar app.jar

파일을 다른 디렉터리로 이동할 때도 사용한다.

mv 역시 대상 위치에 같은 이름의 파일이 있으면 덮어쓸 수 있다. 운영 환경에서는 파일 이름에 버전을 포함하는 방식을 많이 사용한다.

app-1.0.0.jar
app-1.0.1.jar

이전 버전 파일이 남아 있으므로 문제가 생겼을 때 롤백하기 쉬워진다.

rm: 삭제

디렉터리와 내부 파일을 재귀적으로 강제 삭제하는 다음 명령은 매우 위험하다.

rm -rf 디렉터리

• -r: 내부 디렉터리와 파일까지 재귀적으로 처리
• -f: 별도의 확인 없이 강제로 처리

리눅스 터미널에서 삭제한 파일은 일반적으로 휴지통으로 가지 않는다. 특히 관리자 권한과 함께 잘못 사용하면 시스템 전체를 손상시킬 수 있다.

삭제 전에는 대상 경로를 확인하는 습관을 들이는 것이 좋다.

pwd
ls -al 삭제하려는경로

운영 배포에서는 오래된 파일을 즉시 삭제하기보다 별도의 백업 디렉터리로 옮긴 뒤 보존 기간에 따라 정리하는 편이 안전하다.

4. 파일 내용 확인과 검색

cat: 파일 전체 내용을 한 번에 출력

cat application.yml

짧은 설정 파일을 확인하기에는 좋지만 로그처럼 큰 파일에 사용하면 화면이 빠르게 지나간다.

또한 비밀번호나 API 키가 포함된 파일을 화면에 출력하면 터미널 기록이나 화면 공유를 통해 노출될 수 있으므로 주의해야 한다.

less: 긴 파일을 페이지 단위로 확인

less application.log

less 내부에서 자주 사용하는 키는 다음과 같다.

• 방향키: 이동
• /ERROR: ERROR 검색
• n: 다음 검색 결과
• N: 이전 검색 결과
• q: 종료

head와 tail: 파일의 앞부분과 마지막 부분 확인

# 파일 앞부분 확인
head application.log
head -n 50 application.log

# 파일 마지막 부분 확인
tail application.log
tail -n 100 application.log

# 실시간으로 추가되는 로그 확인
tail -f application.log

tail -f를 종료할 때는 Ctrl + C를 누른다.

grep: 파일 내용에서 특정 문자열 검색

# ERROR 검색
grep "ERROR" application.log

# 대소문자를 구분하지 않고 검색
grep -i "error" application.log

# 줄 번호 포함
grep -n "ERROR" application.log

# 디렉터리 내부를 재귀적으로 검색
grep -R "database.password" /opt/myapp/config

프로세스를 확인할 때 파이프(|)와 함께 자주 사용하기도 한다.

ps aux | grep java

파이프는 왼쪽 명령의 출력을 오른쪽 명령의 입력으로 전달한다. 위 명령에서는 ps aux의 전체 출력 가운데 java가 포함된 줄만 선택한다.

단, grep java 명령 자체도 결과에 나타날 수 있다. 다음처럼 작성하면 그 문제를 피할 수 있다.

ps aux | grep '[j]ava'

find: 이름이나 조건으로 실제 파일 찾기

# 특정 경로에서 로그 파일 검색
find /opt/myapp -name "*.log"

# 현재 디렉터리부터 검색
find . -name "application*.yml"

# 파일만 검색
find . -type f -name "*.jar"

# 디렉터리만 검색
find . -type d -name "logs"

grep과 find의 차이

• find: 파일과 디렉터리 자체를 찾는다.
• grep: 파일 내용에서 문자열을 찾는다.

5. 프로그램, 프로세스, 서비스의 차이

프로그램

디스크에 저장된 실행 가능한 파일이다.

프로세스

프로그램이 실제로 실행 중인 상태다. 프로세스마다 PID라는 고유한 번호가 있다.

ps aux

출력 예시는 다음과 같다.

appuser  2145  2.3  8.1 ... java -jar /opt/myapp/app.jar

여기서 2145가 PID다.

서비스

운영체제가 지속적으로 관리하는 백그라운드 프로그램이다. 애플리케이션을 서비스로 등록하면 시작, 종료, 재시작, 부팅 시 자동 실행 등을 일관된 방식으로 관리할 수 있다.

6. 프로세스 확인과 종료

ps: 현재 실행 중인 프로세스 확인

ps aux

# 특정 프로세스 검색
ps aux | grep '[j]ava'

# PID를 더 간단하게 검색
pgrep -af java

pgrep 옵션의 의미는 다음과 같다.

• -a: 전체 명령어 표시
• -f: 실행 명령 전체를 대상으로 검색

top: CPU와 메모리 사용량 실시간 확인

top

주로 다음 항목을 확인한다.

• CPU를 많이 사용하는 프로세스
• 메모리를 많이 사용하는 프로세스
• 시스템 전체 부하
• 실행 중인 프로세스 수

q를 누르면 종료된다.

kill: 프로세스에 시그널 보내기

kill은 무조건 프로세스를 강제 종료하는 명령이 아니라 프로세스에 시그널을 보내는 명령이다.

kill -15 2145

15, 즉 SIGTERM은 정상 종료를 요청한다. 애플리케이션은 SIGTERM을 받으면 다음 작업을 수행할 기회를 가질 수 있다.

• 새로운 요청 수신 중단
• 처리 중인 요청 마무리
• 데이터 저장
• DB 연결 종료
• 로그 기록
• 프로세스 종료

반면 다음 명령은 SIGKILL을 보낸다.

kill -9 2145

SIGKILL은 애플리케이션이 정리할 기회를 주지 않고 운영체제가 즉시 종료한다. 따라서 보통 다음 순서를 따른다.

1. SIGTERM으로 정상 종료 요청
2. 일정 시간 동안 종료 여부 확인
3. 정상 종료되지 않을 때만 SIGKILL 고려

서비스로 등록된 애플리케이션이라면 PID를 직접 종료하기보다 sudo systemctl stop myapp을 우선 사용한다. systemd에 정의된 종료 절차와 제한 시간을 적용할 수 있기 때문이다.

7. systemd로 서비스 관리하기

systemd는 많은 리눅스 배포판에서 서비스의 시작, 종료, 자동 실행, 재시작, 로그 등을 관리한다.

자주 사용하는 명령어

sudo systemctl start myapp
sudo systemctl stop myapp
sudo systemctl restart myapp
sudo systemctl status myapp

# 서버 부팅 시 자동 시작
sudo systemctl enable myapp

# 자동 시작 해제
sudo systemctl disable myapp

# 서비스 파일 수정 후 systemd가 다시 읽게 하기
sudo systemctl daemon-reload

서비스 설정을 수정한 뒤에는 일반적으로 다음 순서로 확인한다.

서비스 설정 파일 수정
→ systemctl daemon-reload
→ systemctl restart myapp
→ systemctl status myapp
→ 로그 확인

systemd 서비스 파일 예시

[Unit]
Description=My Spring Boot Application
After=network.target

[Service]
User=appuser
Group=appgroup
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/java -jar /opt/myapp/app.jar
EnvironmentFile=/etc/myapp/myapp.env
Restart=on-failure
RestartSec=5
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

[Unit]

서비스 자체의 설명과 실행 순서를 정의한다.

Description=My Spring Boot Application
After=network.target

After=network.target은 네트워크 기본 구성이 준비된 뒤 실행 순서를 잡겠다는 의미다. 이것만으로 데이터베이스에 실제로 연결할 수 있는 상태까지 보장되는 것은 아니다.

[Service]

애플리케이션의 실제 실행 방법을 정의한다.

User=appuser
Group=appgroup

애플리케이션을 root가 아닌 appuser 권한으로 실행한다.

WorkingDirectory=/opt/myapp

애플리케이션의 작업 디렉터리를 지정한다.

ExecStart=/usr/bin/java -jar /opt/myapp/app.jar

실제로 실행할 명령이다. systemd에서는 실행 파일의 절대 경로를 사용하는 것이 명확하다.

EnvironmentFile=/etc/myapp/myapp.env

환경 변수가 담긴 파일을 읽는다.

Restart=on-failure
RestartSec=5

비정상적으로 종료되면 5초 뒤 재시작한다. 설정 오류나 DB 연결 오류로 애플리케이션이 계속 실패하면 무한 재시작처럼 보일 수 있으므로 반드시 로그를 확인해야 한다.

[Install]

부팅 과정의 어느 단계에서 서비스를 실행할지 정의한다.

WantedBy=multi-user.target

일반적인 서버 운영 단계에서 서비스가 실행되도록 설정한다.

journalctl: systemd 서비스 로그 확인

systemd로 실행한 서비스의 표준 출력과 표준 오류는 보통 journal에 기록된다.

# 전체 로그
journalctl -u myapp

# 실시간 로그
journalctl -u myapp -f

# 최근 100줄
journalctl -u myapp -n 100

# 최근 10분
journalctl -u myapp --since "10 minutes ago"

# 오늘 로그
journalctl -u myapp --since today

# 최신 로그부터 보기
journalctl -u myapp -r

애플리케이션이 시작되지 않는다면 다음 두 명령을 먼저 확인한다.

systemctl status myapp
journalctl -u myapp -n 100

systemctl status는 현재 상태를 요약하고, journalctl은 자세한 실행 기록을 보여 준다.

8. 리눅스 네트워크 기초

IP 주소

IP 주소는 네트워크에서 서버를 식별하는 주소다.

• 127.0.0.1: 자기 자신을 가리키는 루프백 주소
• 사설 IP: 내부 네트워크에서 사용하는 주소
• 공인 IP: 인터넷에서 접근할 수 있는 주소

포트

포트는 한 서버에서 여러 프로그램을 구분하기 위한 번호다.

22    SSH
80    HTTP
443   HTTPS
3306  MySQL
5432  PostgreSQL
6379  Redis
8080  애플리케이션에서 자주 사용하는 포트

현재 열려 있는 listening 포트는 다음 명령으로 확인한다.

ss -lntp

• l: 연결을 기다리는 listening 소켓
• n: 포트 번호를 숫자로 표시
• t: TCP 소켓
• p: 해당 포트를 사용하는 프로세스 표시

curl

서버에서 HTTP 요청을 직접 보내는 도구다.

# 애플리케이션 내부 접근 확인
curl http://127.0.0.1:8080

# 헬스 체크 API가 있다면
curl http://127.0.0.1:8080/health

# 응답 헤더만 확인
curl -I https://example.com

# 상세 통신 과정 확인
curl -v https://example.com

curl 결과를 이용하면 문제가 애플리케이션, Nginx, DNS, TLS 중 어느 범위에 있는지 좁힐 수 있다.

DNS

DNS는 도메인 이름을 IP 주소로 바꾸어 준다.

api.example.com
        │ DNS 조회
        ▼
203.0.113.10

DNS를 변경해도 전 세계에 즉시 반영되지 않을 수 있다. 기존 결과가 일정 시간 캐시에 남아 있을 수 있기 때문이다.

DNS가 잘못 설정되어 있으면 애플리케이션과 Nginx가 모두 정상이어도 사용자는 다른 서버에 접속할 수 있다.

HTTP와 HTTPS

HTTP

클라이언트와 서버가 요청과 응답을 주고받는 규칙이다.

HTTPS

HTTP 통신을 TLS로 암호화한 것이다.

• 통신 내용 암호화
• 서버가 해당 도메인의 정당한 서버인지 확인
• 통신 중 데이터 변조 방지

HTTPS를 사용하려면 도메인에 맞는 TLS 인증서가 필요하다.

사용자 ↔ Nginx: HTTPS
Nginx ↔ 같은 서버의 애플리케이션: HTTP

HTTP 상태 코드

상태 코드별로 우선 확인할 부분은 다음과 같다.

• 404: Nginx 경로 또는 애플리케이션 라우팅 확인
• 500: 애플리케이션 로그 확인
• 502: 애플리케이션 실행 여부와 포트 확인
• 504: 느린 쿼리, 외부 API, 타임아웃 확인

9. SSH로 서버 접속하기

SSH는 원격 서버에 암호화된 연결로 접속하는 방법이다.

ssh deploy@server-ip

# 개인 키를 지정한다면
ssh -i company-server-key.pem deploy@server-ip

각 요소의 의미는 다음과 같다.

• deploy: 서버의 사용자 이름
• server-ip: 접속할 서버 주소
• -i: 사용할 개인 키 파일 지정

공개 키와 개인 키

SSH 키 인증은 한 쌍의 키를 사용한다.

• 개인 키: 내 컴퓨터에 보관
• 공개 키: 서버에 등록

개인 키는 Git 저장소에 커밋하거나 이메일·메신저로 공유하면 안 된다. 사람마다 별도의 키를 사용하고, 가능하면 서버에서 root 직접 로그인을 제한하는 편이 안전하다.

10. 실제 배포 흐름

앞에서 배운 내용을 실제 Spring Boot 배포 순서로 연결해 보자. 다만 회사마다 인프라와 배포 도구가 다르므로, 운영 서버에서 처음 보는 명령을 바로 실행하기보다 기존 배포 문서와 스크립트를 먼저 확인해야 한다.

1단계: 배포 대상과 방식 확인

배포 전에는 다음 정보를 확인한다.

서버 주소
SSH 사용자
배포 경로
애플리케이션 실행 사용자
서비스 이름
사용 포트
로그 위치
설정 파일 위치
배포 전 백업 방법
DB 마이그레이션 여부
롤백 방법

2단계: 애플리케이션 빌드

Spring Boot 예시는 다음과 같다.

./gradlew clean build

결과 파일은 보통 다음 경로에 생성된다.

build/libs/myapp.jar

실무에서는 개발자 PC보다 CI 서버에서 빌드하는 편이 재현성과 보안 측면에서 좋다.

3단계: 파일 전달

scp build/libs/myapp.jar deploy@server:/opt/myapp/releases/myapp-1.2.3.jar

파일을 버전별로 보관하면 기존 버전을 덮어쓰지 않으므로 롤백하기 쉽다.

4단계: 설정과 권한 확인

ls -l /opt/myapp/releases/
ls -l /etc/myapp/myapp.env

애플리케이션을 실행하는 사용자가 필요한 파일을 읽을 수 있는지 확인한다.

5단계: DB 마이그레이션

스키마 변경이 있다면 Flyway나 Liquibase 같은 도구를 사용할 수 있다.

DB 마이그레이션은 특히 주의해야 한다. 애플리케이션만 이전 버전으로 되돌려도 DB 구조가 이미 변경되었다면 완전한 롤백이 불가능할 수 있기 때문이다.

가능하면 다음처럼 구버전과 신버전이 함께 호환되는 순서로 변경한다.

1. 기존 코드와 새 코드가 함께 사용할 수 있는 컬럼 추가
2. 새 코드 배포
3. 데이터 이전
4. 충분히 검증한 뒤 오래된 컬럼 제거

6단계: 서비스 재시작

sudo systemctl restart myapp

재시작 직후에는 반드시 상태와 로그를 확인한다.

sudo systemctl status myapp
journalctl -u myapp -n 100

7단계: 서버 내부 헬스 체크

curl http://127.0.0.1:8080/health

8단계: 외부 경로 확인

curl -I https://api.example.com

홈페이지만 열리는지 확인하는 데서 끝내지 말고 핵심 기능도 확인해야 한다.

• 로그인
• DB 조회
• 데이터 생성
• 외부 API 연동
• 파일 업로드
• 비동기 작업

9단계: 로그와 지표 관찰

배포 직후 일정 시간 동안 다음 항목을 확인한다.

• 오류 로그 증가 여부
• HTTP 5xx 증가 여부
• CPU와 메모리 사용량
• DB 연결 상태
• 응답 시간
• 재시작 횟수

10단계: 문제 발생 시 롤백

롤백은 이전 애플리케이션 파일을 다시 실행하는 것만으로 끝나지 않을 수 있다.

확인해야 할 항목은 다음과 같다.

• 이전 버전 파일이 남아 있는가?
• 설정 파일도 이전 상태로 되돌려야 하는가?
• DB 스키마가 이전 버전과 호환되는가?
• 배포 중 생성된 데이터는 어떻게 처리할 것인가?
• 캐시나 메시지 형식이 이전 버전과 호환되는가?

롤백 방법은 장애가 발생한 뒤 만드는 것이 아니라 배포 전에 준비해야 한다.

11. 무중단 배포의 기본 개념

단순 재시작 방식에서는 기존 애플리케이션이 종료되고 새 애플리케이션이 완전히 시작될 때까지 요청을 처리할 수 없다.

기존 애플리케이션 종료
        ↓
새 애플리케이션 시작
        ↓
시작 완료까지 서비스 중단

무중단 배포에서는 보통 두 개 이상의 애플리케이션 인스턴스를 둔다.

             ┌─ 애플리케이션 A
사용자 ─ Nginx
             └─ 애플리케이션 B

배포 순서는 다음과 같다.

1. A가 요청을 처리하는 동안 B에 새 버전 배포
2. B의 헬스 체크 성공 확인
3. 요청을 B로 전환
4. A를 종료하거나 새 버전으로 교체

이를 구현하는 방법에는 다음과 같은 것들이 있다.

• Blue-Green 배포
• Rolling 배포
• Nginx upstream 전환
• Docker Compose
• Kubernetes Deployment
• 클라우드 로드 밸런서

처음부터 무중단 배포를 구현하기보다, 먼저 수동 배포와 롤백 원리를 정확히 이해하는 것이 좋다.

마무리

리눅스 배포에서 중요한 것은 명령어를 외우는 것만이 아니다. 요청이 DNS, 방화벽, Nginx, 애플리케이션을 거쳐 데이터베이스까지 어떻게 이동하는지 이해해야 문제가 생겼을 때 원인을 빠르게 좁힐 수 있다.

처음에는 다음 세 가지 흐름부터 익혀 두면 좋다.

1. systemctl status와 journalctl로 애플리케이션 상태와 로그 확인하기
2. ss와 curl로 포트와 요청 경로 확인하기
3. 버전별 파일 보관과 DB 호환성을 고려해 롤백 준비하기

이 기본 흐름을 이해한 뒤 CI/CD, Docker, 무중단 배포로 범위를 넓혀 가면 배포 과정이 훨씬 선명하게 보일 것이다.

ForPets 프로젝트에서 AI 도전 기능으로 RAG 파이프라인을 구현했다.

기존 AI 시터 추천 챗봇은 시터의 기본 정보, 리뷰 요약, 스케줄 정보를 기반으로 추천을 제공했다. 이번 작업에서는 여기서 한 단계 더 나아가, 실제 보호자 리뷰 원문을 벡터화해서 검색 가능한 지식 베이스로 만들고, 사용자의 자연어 질문과 의미적으로 유사한 리뷰를 찾아 AI 추천 응답의 근거로 활용하도록 확장했다.

즉, LLM이 그냥 “그럴듯하게” 추천하는 것이 아니라 실제 리뷰 데이터를 기반으로 응답하도록 만드는 것이 목표였다.

보호자 리뷰 데이터 조회
→ 리뷰 원문 임베딩 생성
→ Qdrant Vector DB 저장
→ 사용자 자연어 질문 임베딩
→ 유사 리뷰 시맨틱 검색
→ AI 추천 응답에 리뷰 근거 포함

왜 RAG가 필요했나?

시터 추천에서 중요한 건 단순 조건 검색만이 아니었다.

예를 들어 사용자는 이렇게 물어볼 수 있다.

분리불안 있는 말티즈를 차분하게 돌봐줄 시터 추천해줘
노령견을 천천히 산책시켜주는 시터 찾아줘
낯가림 있는 아이를 잘 기다려주는 시터 있어?

이런 요청은 단순히 지역, 가격, 경력만으로 판단하기 어렵다. 실제 보호자 리뷰에 “분리불안”, “천천히 산책”, “억지로 만지지 않고 기다려줌” 같은 경험이 남아 있다면, 그 리뷰를 추천 근거로 활용하는 게 훨씬 설득력 있다.

그래서 리뷰 원문을 벡터화하고, 사용자 질문과 의미적으로 가까운 리뷰를 찾아 AI 추천에 붙이는 구조를 만들었다.

사용 기술

이번 RAG 구현에는 아래 기술을 사용했다.

전체 구조

구현한 흐름은 크게 세 단계다.

1. 리뷰 인덱싱
   리뷰 원문 → Gemini Embedding → Qdrant 저장

2. RAG 검색
   사용자 질문 → Gemini Embedding → Qdrant 유사 리뷰 검색

3. AI 추천 챗봇 결합
   Tool Calling 추천 결과 + RAG 리뷰 근거 → 최종 응답

1. 리뷰 데이터 확인

RAG 인덱싱 대상은 COMPLETED 예약에 연결된 보호자 리뷰다.

리뷰는 실제 케어가 완료된 예약에 대해서만 작성될 수 있기 때문에, 추천 근거로 사용하기에 적합하다고 판단했다.

테스트용으로 시터 리뷰 데이터를 조회했다.

GET /api/reviews/sitters/13?page=0&size=10&sort=createdAt&direction=desc

응답 일부는 다음과 같다.

{
  "id": 130,
  "reservationId": 135,
  "reviewerId": 3,
  "revieweeId": 16,
  "reviewComment": "노령견이라 걱정했는데 이동 속도에 맞춰 천천히 산책해주시고 물 먹는 양도 확인해주셨습니다.",
  "rating": 2
}

이 리뷰 원문을 임베딩해서 Qdrant에 저장한다.

2. RAG 인덱싱 구현

인덱싱 API는 다음과 같다.

POST /api/ai/rag/reviews/index

처리 흐름은 다음과 같다.

1. COMPLETED 예약의 활성 리뷰 조회
2. 리뷰별 RagDocument 생성
3. Gemini Embedding API 호출
4. 리뷰 원문을 벡터로 변환
5. Qdrant collection 초기화
6. Qdrant에 vector + payload upsert
7. 성공/실패 개수 반환

Qdrant payload에는 검색 결과의 출처를 표시하기 위해 다음 정보를 저장했다.

테스트 결과는 다음과 같았다.

{
  "success": true,
  "data": {
    "indexedCount": 100,
    "failedCount": 30
  },
  "error": null
}

총 130개 대상 중 100개가 인덱싱되었고, 30개는 실패 처리되었다. 실패한 문서가 있어도 전체 인덱싱을 중단하지 않고 가능한 문서만 우선 저장하도록 했다.

3. RAG 검색 구현

검색 API는 다음과 같다.

POST /api/ai/rag/search

요청 예시:

{
  "query": "노령견을 천천히 산책시켜주는 시터"
}

처리 흐름은 다음과 같다.

1. 사용자 자연어 질문 수신
2. 질문을 Gemini Embedding API로 벡터화
3. Qdrant에서 cosine similarity 기반 유사 리뷰 검색
4. score_threshold 이상인 결과만 반환
5. sourceId, reviewId, sitterId, snippet, score 포함

응답 예시:

{
  "sourceType": "REVIEW",
  "sourceId": 100,
  "reviewId": 100,
  "sitterId": 10,
  "rating": 5,
  "snippet": "노령견이라 걱정했는데 이동 속도에 맞춰 천천히 산책해주시고 물 먹는 양도 확인해주셨습니다.",
  "score": 0.8516915
}

“노령견을 천천히 산책시켜주는 시터”라는 질문에 대해 실제 리뷰 원문 중 “노령견”, “천천히 산책”, “물 먹는 양 확인”과 의미적으로 가까운 리뷰가 검색되는 것을 확인했다.

4. AI 추천 챗봇과 RAG 결합

기존 AI 추천 챗봇에도 RAG 검색 결과를 연결했다.

POST /api/ai/chat

요청:

{
  "message": "분리불안 있는 말티즈를 차분하게 돌봐줄 시터 추천해줘"
}

응답에는 추천 시터 목록과 함께 RAG 검색 출처가 포함된다.

{
  "sourceType": "REVIEW",
  "sourceId": 61,
  "reviewId": 61,
  "sitterId": 7,
  "rating": 5,
  "snippet": "말티즈가 낯을 많이 가리는데 천천히 적응시켜주시고 사진도 자주 보내주셔서 안심됐습니다.",
  "score": 0.8104445
}

AI 답변에도 실제 리뷰 근거가 포함되도록 했다.

리뷰 근거: 리뷰 #61 / 시터 #7 / "말티즈가 낯을 많이 가리는데 천천히 적응시켜주시고 사진도 자주 보내주셔서 안심됐습니다."

이렇게 하면 사용자는 추천 결과가 어떤 리뷰를 근거로 만들어졌는지 확인할 수 있다.

5. 검색 결과 없음 fallback

ForPets 도메인과 관련 없는 질문도 테스트했다.

요청:

{
  "query": "자동차 엔진오일을 잘 교체하는 시터"
}

응답:

{
  "success": true,
  "data": {
    "results": []
  },
  "error": null
}

관련 없는 질문에 대해 억지로 리뷰를 끼워 맞추지 않고 빈 결과를 반환했다. 환각 방어 관점에서 이 동작이 중요하다고 봤다.

6. Qdrant 장애 fallback

Qdrant 장애 상황도 고려했다.

RAG는 추천 품질을 높이는 보조 기능이지, 핵심 추천 기능 자체가 아니다. 따라서 Qdrant 검색에 실패해도 챗봇 전체가 죽으면 안 된다.

Qdrant 검색 실패
→ RAG sources 빈 리스트 반환
→ Tool Calling 기반 추천은 계속 진행

장애 상황에서도 응답 형태는 유지되도록 처리했다.

{
  "success": true,
  "data": {
    "results": []
  },
  "error": null
}

트러블슈팅 1. Gemini Embedding 모델 오류

처음에는 text-embedding-004 모델을 사용했다.

그런데 Gemini API 호출 시 다음 오류가 발생했다.

models/text-embedding-004 is not found for API version v1beta

현재 호출 방식에서는 해당 모델을 사용할 수 없었다.

그래서 embedding model을 다음과 같이 변경했다.

forpets:
  ai:
    gemini:
      embedding-model: gemini-embedding-001

트러블슈팅 2. Qdrant Collection 중복 생성

인덱싱 API를 여러 번 호출하니 Qdrant에서 collection이 이미 존재한다는 오류가 발생했다.

Collection `forpets_reviews` already exists

인덱싱 API는 여러 번 호출해도 안전해야 한다. 그래서 collection이 이미 존재하면 실패로 보지 않고 재사용하도록 처리했다.

collection 없음 → 새로 생성
collection 있음 → 재사용

트러블슈팅 3. Vector Dimension 불일치

가장 오래 잡아먹은 문제는 벡터 차원 불일치였다.

Gemini gemini-embedding-001은 3072차원 벡터를 반환하는데, Qdrant collection은 처음에 768차원으로 생성되어 있었다.

그 결과 다음 오류가 발생했다.

Vector dimension error: expected dim: 768, got 3072

해결 방법은 두 가지였다.

먼저 설정을 3072로 변경했다.

forpets:
  ai:
    rag:
      vector-size: 3072

그리고 기존 collection이 이미 생성되어 있는 경우를 위해, collection의 vector size를 확인한 뒤 설정값과 다르면 RAG 전용 collection을 삭제 후 재생성하도록 처리했다.

collection 있음 + vector size 일치 → 재사용
collection 있음 + vector size 불일치 → 삭제 후 재생성

이렇게 해서 로컬 테스트 중에도 이전 설정으로 만들어진 collection 때문에 계속 실패하는 문제를 해결했다.

Postman 테스트 결과

최종적으로 Postman에서 6개 시나리오를 테스트했다.

과제 요구사항 매핑

마무리

이번 RAG 작업을 통해 ForPets의 AI 추천 기능은 단순 조건 검색 기반 추천에서 한 단계 확장되었다.

최종 구조는 다음과 같다.

리뷰 원문
→ Gemini Embedding
→ Qdrant 저장
→ 자연어 질문 임베딩
→ 유사 리뷰 검색
→ AI 추천 응답에 리뷰 근거 포함

이제 사용자는 “분리불안 있는 말티즈”, “노령견 산책”, “낯가림 있는 아이”처럼 정확한 키워드가 아니더라도, 실제 리뷰 원문을 기반으로 더 신뢰할 수 있는 시터 추천을 받을 수 있다.

가장 크게 느낀 점은 RAG는 단순히 “벡터 DB 붙이기”가 아니라는 것이다. 모델의 임베딩 차원, Vector DB collection 설정, 검색 threshold, 출처 payload, 장애 fallback까지 함께 맞아야 실제 서비스 기능으로 쓸 수 있었다.

Postman 테스트 링크

이번에는 ForPets 프로젝트의 AI 기능에 대해 Prometheus와 Grafana를 연결해 메트릭을 확인해보았다.

AI 기능은 Gemini API를 사용하고 있기 때문에 단순히 “응답이 잘 온다”에서 끝내면 안 된다고 생각했다.
운영 관점에서는 다음과 같은 정보를 확인할 수 있어야 한다.

• AI 요청이 몇 번 발생했는지
• 요청이 성공했는지, fallback으로 처리되었는지
• 응답 시간이 얼마나 걸렸는지
• 토큰을 얼마나 사용했는지
• 에러가 어떤 유형으로 발생했는지

이를 위해 Spring Boot에서 Micrometer로 AI 메트릭을 기록하고, Prometheus가 이를 수집한 뒤 Grafana에서 시각화하는 방식으로 구성했다.

1. 백엔드 실행 및 Actuator 메트릭 확인

먼저 로컬에서 백엔드를 실행했다.

export GEMINI_API_KEY=나의_제미나이_키
./gradlew bootRun --args='--spring.profiles.active=local,ai'

이후 브라우저에서 Actuator Prometheus endpoint에 접속했다.

http://localhost:8080/actuator/prometheus

AI 리뷰 요약 또는 AI 추천 챗봇을 한 번 실행한 뒤, ai_requests_total을 검색해보았다.

확인된 값은 다음과 같았다.

ai_requests_total ... status="SUCCESS" 1.0

AI 리뷰 요약 요청이 1번 성공했다는 의미다.

ai_request_duration_seconds_sum ... 4.641

AI 요청 처리에 약 4.641초가 걸렸다는 의미다.

ai_tokens_sum ... 745.0

Gemini API 호출에서 총 745 tokens를 사용했다는 의미다.

이 단계에서 확인할 수 있었던 것은 다음과 같다.

• AI 요청 수 수집
• 성공/실패 status 태그 수집
• feature 태그 수집
• model 태그 수집
• 응답 시간 수집
• 토큰 사용량 수집

2. Prometheus 연결 확인

Prometheus와 Grafana를 실행했다.

docker compose up -d prometheus grafana

Prometheus는 아래 주소에서 확인할 수 있다.

http://localhost:9090

상단 검색창에 다음 쿼리를 입력했다.

ai_requests_total

처음에는 값이 나오지 않았다.

원인은 Prometheus target 설정이었다.
현재 백엔드는 Docker 컨테이너가 아니라 로컬에서 직접 실행 중이었기 때문에, Prometheus 컨테이너가 로컬 백엔드에 접근할 수 있도록 target을 수정해야 했다.

monitoring/prometheus.yml에서 target을 아래처럼 임시로 변경했다.

targets: ['host.docker.internal:8080']

이후 Prometheus를 재시작했다.

docker compose restart prometheus

다시 아래 주소에서 target 상태를 확인했다.

http://localhost:9090/targets

상태가 UP으로 표시되면 Prometheus가 Spring Boot 애플리케이션의 메트릭을 정상적으로 수집하고 있다는 뜻이다.

다시 ai_requests_total을 검색해보면 다음과 같이 값이 잘 조회된다.

확인된 정보는 다음과 같다.

job="for-pets"
instance="host.docker.internal:8080"
ai_requests_total ... status="SUCCESS" 1

즉, 아래 흐름이 정상적으로 연결된 것이다.

Spring Boot /actuator/prometheus
→ Prometheus scrape
→ AI 메트릭 저장

3. Grafana 대시보드 구성

Grafana는 아래 주소로 접속했다.

http://localhost:3000

기본 계정은 다음과 같다.

ID: admin
PW: admin

Grafana에서 AI Monitoring 대시보드를 생성하고, 다음 5개의 패널을 구성했다.

3-1. AI 요청 수

Visualization: Time series 또는 Stat

sum(ai_requests_total)

3-2. AI Fallback/실패율

Visualization: Stat

(sum(ai_requests_total{status!="SUCCESS"}) or vector(0)) / sum(ai_requests_total)

3-3. AI 평균 응답 시간

Visualization: Stat

sum(ai_request_duration_seconds_sum) / sum(ai_request_duration_seconds_count)

3-4. AI 토큰 사용량

Visualization: Bar chart 또는 Time series

sum by (feature, model) (ai_tokens_sum)

3-5. AI 에러 타입별 발생 수

Visualization: Bar chart

sum by (errorType) (ai_requests_total{status!="SUCCESS"})

생성된 Grafana snapshot은 아래에서 확인할 수 있다.

http://localhost:3000/dashboard/snapshot/8DNFMuE79sYJXq36bPAhyP3ERB8mwNZe

4. 기술 선택 근거

Micrometer

Spring Boot 애플리케이션 내부에서 메트릭을 코드 레벨로 기록하기 쉽다.
AI 요청 수, 응답 시간, 토큰 사용량 같은 지표를 직접 정의해 기록할 수 있었다.

Prometheus

/actuator/prometheus endpoint를 주기적으로 수집해서 시계열 데이터로 저장할 수 있다.
Spring Boot Actuator와 연동이 쉽고, Grafana와의 조합도 일반적으로 많이 사용된다.

Grafana

Prometheus에 저장된 메트릭을 대시보드로 시각화할 수 있다.
AI 요청 수, fallback 비율, 응답 시간, 토큰 사용량을 한 화면에서 확인할 수 있어 운영 관점에서 유용하다.

Redis Rate Limit

AI 요약 갱신 버튼을 반복 클릭하는 경우 외부 LLM API 호출이 과도하게 발생할 수 있다.
Redis를 사용해 동일 사용자와 동일 시터 기준으로 요청 횟수를 제한하고, 초과 시 429 Too Many Requests를 반환하도록 설계했다.

5. 장애 격리 설계

AI 기능은 사용자 경험을 개선하는 보조 기능이다.
따라서 Gemini API 장애가 발생하더라도 시터 조회, 리뷰 조회, 예약, 결제 같은 핵심 기능에 영향을 주면 안 된다.

이를 위해 다음과 같이 장애 격리를 적용했다.

• Gemini API 실패 시 리뷰 원문 기반 fallback 요약 저장
• Tool Calling 실패 시 서버 기본 추천 응답으로 fallback
• Redis 장애 시 rate limit은 fail-open 처리
• AI 사용량 로그/메트릭 저장 실패가 사용자 흐름에 전파되지 않도록 best-effort 처리

6. 테스트한 장애 시나리오

다음 장애 시나리오를 테스트했다.

• AI 요약 요청 제한 초과 → 429 Too Many Requests
• Redis 장애 → fail-open 처리
• AI 호출 실패 → fallback 요약 저장
• AI 응답에 금지 표현 포함 → fallback 처리
• AI 응답 DTO 스키마 불일치 → fallback 처리
• 로그 저장 실패 → 사용자 흐름 정상 유지

7. 대시보드 결과

이번 테스트에서 확인한 결과는 다음과 같다.

AI 요청 수: 1건
Fallback/실패율: 0%
평균 응답 시간: 4.64초
토큰 사용량: 745 tokens

이를 통해 AI 기능이 단순히 호출되는 것뿐만 아니라, 성공 여부와 응답 시간, 토큰 사용량까지 관측 가능한 상태가 되었음을 확인할 수 있었다.

마무리

이번 작업을 통해 AI 기능도 일반 API처럼 운영 관점에서 관측 가능해야 한다는 것을 체감했다.

특히 LLM API는 외부 서비스이기 때문에 timeout, rate limit, 응답 형식 오류, 비용 증가 같은 문제가 발생할 수 있다.
따라서 fallback 처리뿐만 아니라 요청 수, 실패율, 응답 시간, 토큰 사용량을 함께 모니터링하는 것이 중요하다고 느꼈다.

이번에는 기본적인 AI 메트릭 대시보드를 구성했고, 이후에는 P95/P99 응답 시간이나 기능별 비용 추적을 더 정교하게 개선해볼 수 있을 것 같다.

스파르타 내일배움캠프 Spring Plus 팀 프로젝트 공연·스포츠 티켓팅 플랫폼 Ticket_Javara(TicketFlow) 개발 회고 및 트러블슈팅 정리 역할: 예매(Booking) 도메인 담당 — 좌석 Hold, 동시성 제어, 결제 플로우, Mock PG 웹훅 연동

프로젝트 개요 및 구조를 기반으로 실제 구현하면서 겪었던 문제들과, 왜 그렇게 설계했는지에 대한 고민들을 정리해보려고 한다.

이번 프로젝트는 단순 CRUD보다는, 실제 티켓팅 서비스에서 발생할 수 있는 동시성·트랜잭션·캐시·배포 환경 문제를 직접 경험해본 프로젝트였다.

1. 왜 티켓팅 서비스는 “좌석 선택”이 어려운가?

처음에는 단순하게 생각했다.

좌석 선택 → 결제 → 예매 완료

그런데 실제 티켓팅은 이런 구조로 만들면 큰 문제가 생긴다.

예를 들어 아이유 콘서트 오픈 직후, 1만 명이 동시에 같은 좌석을 클릭했다고 가정하면:

1만 명 모두 결제창 진입
→ PG 결제 완료
→ 서버에서 뒤늦게 “이미 예매된 좌석입니다”
→ 환불 9,999건 발생

이걸 막기 위해 프로젝트에서 도입한 개념이 바로:

✅ Hold(좌석 임시 점유)

이었다.

AVAILABLE
   ↓ 좌석 선택
ON_HOLD (5분 TTL)
   ↓ 결제 완료
CONFIRMED

좌석을 선택하는 순간 Redis에 TTL 기반 Hold를 생성해서, 다른 사용자가 같은 좌석을 결제창까지 가져가지 못하게 막았다.

2. Redis 분산락을 왜 사용했는가

처음에는 단순하게 생각했다.

if (!exists) {
    save();
}

하지만 동시 요청 상황에서는 이게 깨진다.

Thread A → 없음 확인
Thread B → 없음 확인
Thread A → 저장
Thread B → 저장

결국 두 명 모두 성공하는 문제가 발생한다.

이 문제를 해결하기 위해 Redis의 SETNX 기반 분산락(Lettuce)을 사용했다.

3. 가장 크게 배운 것 — @Transactional과 락은 생명주기가 다르다

프로젝트 초반 가장 많이 헤맸던 부분이다.

처음에는 이렇게 구현했었다.

@Transactional
public void processHold() {
    lock.tryLock();

    // DB 작업

    lock.unlock();
}

문제는 여기 있었다.

unlock()이 실행되는 시점은 실제 DB COMMIT보다 빠를 수 있다는 점이었다.

즉:

락은 풀렸는데
DB 반영은 아직 안 끝난 상태

가 발생할 수 있었다.

그 결과 다른 스레드가 아직 반영되지 않은 데이터를 읽어버리는 문제가 생겼다.

해결 방법 — Facade 패턴으로 분리

결국 락 생명주기와 트랜잭션 생명주기를 분리했다.

HoldLockFacade {
    lock.tryLock()

    holdService.processHold() // @Transactional

    lock.unlock()
}

이 구조로 바꾸면서:

• 락은 Facade가 관리
• 실제 DB 작업은 Service가 관리

하도록 역할을 분리했다.

이 경험을 통해 단순히 @Transactional 붙이면 끝이 아니라, 트랜잭션이 언제 커밋되는지까지 이해해야 한다는 걸 체감했다.

4. React StrictMode 때문에 결제가 두 번 요청됐던 문제

이건 프론트와 연동하면서 겪은 문제였다.

결제 완료 페이지 진입 시:

useEffect(() => {
  confirmPayment()
}, [])

이 코드가 개발 환경에서 두 번 실행됐다.

원인은 React StrictMode였다.

결과적으로:

토스 승인 API 2번 호출
→ ObjectOptimisticLockingFailureException 발생

이 발생했다.

해결

const hasConfirmed = useRef(false)

useEffect(() => {
  if (hasConfirmed.current) return

  hasConfirmed.current = true
  confirmPayment()
}, [])

useRef로 최초 1회만 호출되게 막았다.

이 경험 이후, “백엔드 에러라고 항상 백엔드 문제는 아니다”라는 걸 많이 느꼈다.

5. REQUIRES_NEW + Detached Entity 문제

이번 프로젝트에서 가장 어려웠던 트랜잭션 문제였다.

결제 승인 이후:

confirmOrder()

를 REQUIRES_NEW로 실행했는데, 갑자기 아래 예외가 발생했다.

StaleObjectStateException
ObjectOptimisticLockingFailureException

원인은 detached entity였다.

외부 트랜잭션에서 생성된 엔티티를 새로운 트랜잭션에 그대로 넘기면서 충돌이 발생한 것이다.

해결

트랜잭션 내부에서 엔티티를 다시 조회했다.

Order freshOrder =
    orderRepository.findById(order.getOrderId())

즉:

파라미터 엔티티 사용 X
트랜잭션 내부 재조회 O

로 해결했다.

이번 경험으로:

• 영속 상태
• detached 상태
• merge vs persist
• REQUIRES_NEW 동작 방식

을 실제 에러로 체감할 수 있었다.

6. ACTIVE_BOOKING 테이블을 따로 만든 이유

원래는 좌석 상태를 컬럼 하나로 관리하려 했다.

AVAILABLE
ON_HOLD
CONFIRMED

하지만 MySQL은 Partial Index를 지원하지 않는다.

즉:

WHERE status='CONFIRMED'

조건으로 유니크 제약을 걸 수 없었다.

결국 선택한 방식은:

ACTIVE_BOOKING 별도 테이블

seat_id PRIMARY KEY

로 설계하는 것이었다.

이렇게 하면:

동일 좌석 INSERT 자체가 실패

하기 때문에 DB 레벨에서 중복 예매를 물리적으로 막을 수 있었다.

7. 배포 환경에서 타이머가 즉시 만료되던 문제

배포 후 테스트 중:

좌석 선택
→ 카운트다운 바로 종료

되는 문제가 발생했다.

원인은 타임존이었다.

• EC2 서버: UTC
• 프론트: KST
• expiresAt 파싱 불일치

결국 9시간 차이가 발생했다.

해결

const expiresAtUtc =
  expiresAt.endsWith('Z')
    ? expiresAt
    : expiresAt + 'Z'

그리고 Docker에도:

TZ: Asia/Seoul

설정을 추가했다.

이번 경험으로: “로컬에서는 잘 되는데 배포에서만 안 되는 이유” 를 처음 제대로 경험했다.

8. BulkDataInit 때문에 데이터가 안 바뀌던 문제

이건 꽤 오래 헤맸던 문제였다.

더미데이터를 수정했는데 프론트 화면에서는 계속 예전 공연 데이터만 보였다.

원인은:

if (eventCount > 25) {
    return;
}

이 중복 실행 방지 로직 때문이었다.

이미 DB에 데이터가 있으면 새 초기화 코드가 실행되지 않았던 것이다.

해결

TRUNCATE TABLE seat;
TRUNCATE TABLE section;
TRUNCATE TABLE event;

후 재실행했다.

이 과정에서:

• FOREIGN_KEY_CHECKS
• TRUNCATE vs DELETE
• 부모/자식 테이블 삭제 순서

까지 같이 공부하게 됐다.

9. Redis DECR은 그 자체로 원자적이다

쿠폰 발급 구현 당시, 처음에는 분산락을 또 걸려고 했다.

그런데 Redis의:

DECR

연산 자체가 이미 원자적이라는 걸 알게 됐다.

그래서:

DECR
→ 음수면 INCR 복구

방식으로 구현했다.

이 경험 이후: “무조건 락을 거는 게 좋은 건 아니다” 라는 걸 많이 배웠다.

10. 프로젝트를 하며 가장 크게 느낀 점

이번 프로젝트는 단순히 기능 구현보다:

• 왜 이런 구조를 선택했는가
• 왜 락을 이렇게 잡아야 하는가
• 트랜잭션은 언제 끝나는가
• 캐시는 왜 깨지는가
• 배포 환경은 왜 로컬과 다른가

를 정말 많이 고민했던 프로젝트였다.

특히 AI 도움을 받으며 개발하면서도 느낀 건:

“코드를 생성하는 것”과 “왜 그렇게 동작하는지 이해하는 것”은 완전히 다르다

라는 점이었다.

실제로 트랜잭션과 락 문제는 원리를 이해하지 못하면 에러 원인조차 파악할 수 없었다.

마무리

이번 Ticket_Javara 프로젝트를 통해:

• Redis 분산락
• 트랜잭션 전파
• 동시성 테스트
• 캐싱 전략
• Docker/AWS 배포
• 프론트-백엔드 연동 문제

를 단순 개념이 아니라, “실제 장애를 해결하면서” 배울 수 있었다.

특히 예매 시스템 특성상 단순 CRUD 프로젝트보다 훨씬 많은 정합성과 Race Condition을 고려해야 했고, 그 과정에서 정말 많이 성장했다고 느낀다.

프로젝트를 하며 가장 크게 배운 점 — “문서화의 힘”

이번 프로젝트를 진행하면서 가장 크게 느낀 건, 코드를 작성하기 전에 얼마나 설계를 깊게 했는지가 프로젝트 전체 난이도를 크게 좌우한다는 점이었다.

프로젝트 초반에는 단순히 빠르게 개발부터 들어가는 게 아니라, 팀원들과 함께 SA 문서를 오래 작성했다.

실제로 아래와 같이 프로젝트 문서를 총 12개 이상 작성하며 설계 단계에 많은 시간을 투자했다.

• 프로젝트 개요서
• 사용자 시나리오
• 유스케이스 명세서
• 기능 명세서
• ERD 설계
• API 명세서
• 화면 설계서
• 인프라 아키텍처
• 동시성 제어 설계서
• ADR(Architecture Decision Record)
• 백엔드 패키지 구조 설계서
• 공통 에러코드 설계서

특히 단순히 “문서를 만든다” 수준이 아니라:

• 왜 Redis Lettuce를 먼저 선택하는지
• 왜 이후 Redisson으로 전환 가능한 구조를 만드는지
• 왜 Feature Flag 전략을 쓰는지
• 왜 좌석 상태를 컬럼이 아닌 ACTIVE_BOOKING 테이블로 분리하는지

같은 설계 의도를 팀 차원에서 계속 문서화했다.

그 과정에서 느낀 건:

좋은 프로젝트는 코드부터 시작되는 게 아니라 “왜 이렇게 설계했는가”를 팀 전체가 공유하는 것부터 시작된다는 점이었다.

이었다.

개발 범위가 백엔드에서 프론트엔드까지 확장된 경험

이번 프로젝트에서는 원래 백엔드 중심으로 참여했지만, 프로젝트 후반에는 프론트엔드 작업까지 직접 진행하게 되었다.

처음에는 단순히 API만 연결하면 된다고 생각했는데, 실제로는:

• React StrictMode로 인한 중복 요청
• 타임존 차이로 CountdownTimer 즉시 만료
• SPA 라우팅 404 문제
• 백엔드 ENUM과 프론트 값 불일치
• 상태 관리 및 페이지 흐름 연결

등 백엔드만 할 때는 경험하지 못했던 문제들을 많이 겪었다.

특히 프론트엔드까지 직접 붙여보면서 느낀 건:

“API를 만드는 것”과
“사용자 입장에서 실제 서비스를 완성하는 것”은 완전히 다르다

는 점이었다.

이전에는 백엔드 기능 단위로만 사고했다면, 이번 프로젝트 이후에는:

• 사용자 흐름
• API 응답 구조
• 프론트 상태 변화
• 배포 환경
• UX까지 포함한 전체 시스템 흐름

을 함께 고려하게 되었다.

결과적으로 단순히 “백엔드 기능 구현”만 하는 수준에서, 조금 더 서비스 전체를 보는 시야가 생겼다고 느꼈다.

개인적으로 가장 성장했다고 느낀 부분

이번 프로젝트 이전에는:

• 트랜잭션 전파
• 분산락
• 동시성
• 캐싱 전략
• 배포 환경 차이
• 프론트와의 연동 문제

를 개념적으로만 알고 있었다.

하지만 이번에는 실제로:

• REQUIRES_NEW
• Redis SETNX
• Lua Script 원자화
• Docker 타임존 문제
• React StrictMode
• Feature Flag 기반 구조 설계

등을 직접 부딪히며 해결해보면서, 단순 이론이 아니라 “실제 서비스에서는 왜 이런 구조를 쓰는지”를 이해하게 되었다.

특히 프로젝트 초반 문서 설계 경험과, 후반 프론트엔드까지 확장된 경험 덕분에:

“기능 구현 개발자”에서 “시스템 전체 흐름을 고민하는 개발자”로 한 단계 성장했다

고 느낀 프로젝트였다.

"바이브코딩 사전단계 — SA 문서를 AI와 함께 설계한다"

3주짜리 커머스 백엔드 프로젝트를 시작하기 전, AI를 '시니어 아키텍트 동료'처럼 활용해 10종의 SA 문서를 설계하는 법을 배웁니다.

Pre-work

1. 준비물 체크리스트

• Claude / ChatGPT / Gemini 중 최소 1개 이상 로그인 가능한 상태 (Pro이상 유료 계정 권장)
• Figma 무료 계정 (화면 설계서 목업용)
• Mermaid 렌더링이 가능한 마크다운 에디터 (VS Code + Mermaid Preview 확장 추천)
• PlantUML 렌더링 도구 (VS Code 확장 또는 plantuml.com)
• 팀별 공용 저장소 (GitHub Repository 또는 Notion 워크스페이스)

2. 사전 숙지 자료

• 2차 프로젝트 회고 (특히 "설계가 약해서 구현 중에 다시 뒤집은 경험")
• Spring Boot + JPA + MySQL + Redis 기본 개념
• AWS EC2 / RDS / ElastiCache 이름만이라도 들어본 수준

3. 💡 "왜 이 특강이 프로젝트 1일차 오전에 배치되는가"

3주 프로젝트의 첫 3일은 설계 기간입니다. 이 3일을 어떻게 쓰느냐가 남은 18일의 품질을 좌우합니다. 이전 기수들이 가장 자주 했던 후회는 "설계 없이 코딩부터 시작했더니 2주차에 기능을 다 뒤엎었다" 였습니다. 오늘 오전 특강에서 'AI와 설계하는 감각'을 먼저 잡고, 오후부터 팀별로 본격적인 SA 문서 작성에 들어갑니다.

오프닝: "왜 또 설계 얘기? 우리 지금껏 설계 많이 했잖아요"

2차 프로젝트 회고 공감대 형성

"여러분, 손 들어보세요. 2차 프로젝트에서 구현하다가 기능을 뒤엎은 경험 있는 사람?" 대부분의 손이 올라올 겁니다. 왜 그랬을까요? 대부분 이유는 하나입니다 — 설계가 없었거나, 있어도 부실했기 때문입니다.

바이브코딩의 함정

지금까지 여러분은 AI에게 "로그인 기능 만들어줘" 같은 식으로 코드를 부탁했습니다. 이걸 바이브코딩(Vibe Coding) 이라고 부릅니다. 느낌적으로, 상황 봐가며, 수정해가며 완성하는 방식이죠.

바이브코딩은 작은 기능 하나를 만들 때는 기가 막히게 빠릅니다. 그런데 3주짜리, 그것도 동시성 제어·분산락·인프라 자동화까지 들어가는 프로젝트를 바이브코딩만으로 끌고 가면 반드시 다음이 터집니다.

• 1주차: "AI 최고! 다 되네!"
• 2주차: "어? 재고가 음수가 돼요… 왜죠?"
• 3주차: "아키텍처가 꼬였는데 어디부터 손대야 할지 모르겠어요"

오늘 배울 것: "AI를 비서가 아닌 시니어 아키텍트 동료처럼"

"AI에게 '뭘 만들지'를 명확히 말해줄 수 없다면, AI는 여러분이 원하는 걸 만들 수 없습니다."

오늘 특강의 목표는 단 하나입니다. AI와 대화하면서 10종의 SA 문서를 만들고, 그 문서를 근거로 3주를 완주하는 법.

실무 연결 — "쿠팡·배민 시니어 개발자들도 이렇게 일합니다"

쿠팡에서 로켓배송 재고관리 시스템을 만들 때, 시니어 개발자가 가장 먼저 하는 일은 코딩이 아니라 PRD(Product Requirements Document)와 SA 문서 작성입니다. 왜냐면 재고가 음수가 되는 순간 실제로 돈이 사라지거든요. 여러분이 만들 커머스 앱도 마찬가지입니다. 오늘 배울 건 실무에서 매일 쓰는 스킬입니다.

오늘의 흐름

1. SA 문서 10종 지도 그리기 + AI에게 프로젝트 컨텍스트 주입하는 법
2. 사용자 시나리오 → 유스케이스 → ERD → API 명세서 순서로 AI와 함께 설계
3. 화면 설계서를 통해 프론트엔드 바이브코딩 가이드 만들기
4. 인프라 아키텍처 & 동시성 제어 설계서(하이라이트)
5. ADR 기록 + 셀프 리뷰
6. 평생 쓸 5가지 프롬프트 패턴 정리

Step 1: "SA 문서 지도 그리기 & AI 컨텍스트 주입"

1-1. 오늘 만들 SA 문서 10종

먼저 뭘 만들지부터 알아야 합니다. 이번 프로젝트에서 3일간 작성할 문서 목록입니다.

💡 9번 동시성 제어 설계서가 별도 문서인 이유 이번 프로젝트의 하이라이트입니다. 비관락/낙관락/분산락을 언제 뭘 쓸지를 결정하는 이 의사결정이 기능 명세서에 섞이면 묻혀버립니다. 별도 문서로 빼서 집중 관리합니다.

1-2. AI를 설계 파트너로 만드는 3단계

AI를 '잘 쓰는' 사람과 '못 쓰는' 사람의 차이는 딱 하나입니다 — 컨텍스트를 얼마나 잘 주입하느냐. 좋은 프롬프트의 3요소를 기억하세요.

1. 역할 부여 (Role): "너는 10년차 백엔드 아키텍트야"
2. 제약 명시 (Constraints): 기술스택, 인원, 기간, 필수/도전 기능
3. 출력 포맷 지정 (Output Format): 마크다운 표, Mermaid, PlantUML, JSON

비유하자면, 신입 개발자한테 일을 시킬 때 "알아서 잘해봐"라고 하면 절대 원하는 결과가 안 나오잖아요? AI도 똑같습니다. 오히려 AI는 신입보다 더 자세한 가이드를 줘야 원하는 답을 줍니다.

1-3. 🎁 실습 프롬프트 — 프로젝트 컨텍스트 초기화

지금 바로 여러분이 쓰는 AI에 이 프롬프트를 복붙해서 대화를 시작해보세요. 이게 오늘 모든 실습의 출발점입니다.

너는 10년 이상의 경력을 가진 백엔드 시니어 아키텍트야.
지금부터 나와 함께 3주짜리 커머스 백엔드 앱의 SA 문서를 설계할 거야.

## 프로젝트 컨텍스트
- 팀 구성: 백엔드 개발자 N명 (경력 3개월)
- 기간: 3주 (설계 3일 + 개발 2주 + QA/배포 1주)
- 주제: 편의점 유통기한 임박 음식 덤핑 플랫폼
- 기술 스택: Java 17, Spring Boot 3.x, Spring Data JPA, MySQL 8, Redis,
  Docker, AWS(EC2, RDS, ElastiCache, ECR), GitHub Actions
- 프론트엔드: 바이브코딩으로 처리 (화면 설계서 + Figma 목업만 준비)

## 필수 구현 기능
1. 동시성 제어 - 순간적으로 요청이 쏟아지더라도 데이터 정합성이 완벽하게 지켜져야하는 비즈니스
2. 로컬 캐싱 (Caffeine) - 인기 검색어 & 검색 기능

## 도전 기능
1. Redis 분산락 (Redisson)
2. Redis 캐싱 (Cache-Aside 패턴)
3. EXPLAIN 기반 DB 인덱스 최적화
4. 웹소켓(STOMP) 기반 채팅
5. EC2 + RDS + ElastiCache + ECR + GitHub Actions 배포 자동화

## 너의 역할
- 질문을 먼저 하고, 내가 답한 뒤에 설계를 제안할 것
- 모든 의사결정에는 "왜"를 근거로 설명할 것
- 추측하지 말고, 모르는 건 나에게 물어볼 것
- 대안이 있을 땐 Trade-off를 비교표로 보여줄 것

## 함께 작성할 문서
| # | 문서 | 답하는 질문 | 산출 형태 |
| --- | --- | --- | --- |
| 1 | 프로젝트 개요서 | 우리 왜 이걸 만드나? | 마크다운 |
| 2 | 사용자 시나리오 (페르소나 포함) | 누가, 어떤 맥락에서 쓰나? | 마크다운 |
| 3 | 유스케이스 명세서 | 누가 뭘 할 수 있나? | 마크다운 + PlantUML |
| 4 | 기능 명세서 | 각 기능은 어떻게 동작하나? | 마크다운 |
| 5 | ERD | 데이터는 어떻게 연결되나? | Mermaid ERD |
| 6 | API 명세서 | 프론트랑 어떻게 대화하나? | 마크다운 표 + OpenAPI YAML |
| 7 | **화면 설계서** | 사용자는 어떤 화면을 보나? | 와이어프레임 + **Figma 목업** |
| 8 | 인프라 아키텍처 다이어그램 | 어디에 어떻게 배포되나? | Mermaid 다이어그램 |
| 9 | **동시성 제어 설계서 ⭐** | 충돌은 어떻게 막나? | 시나리오 매트릭스 |
| 10 | ADR (Architecture Decision Record) | 왜 이 기술을 골랐나? | 마크다운 (결정마다 1개) |

준비됐으면 "준비됐습니다. 먼저 3가지만 질문드릴게요"라고 답하고
가장 중요한 3가지 질문만 먼저 해줘.

🔑 이 프롬프트의 핵심 장치 마지막 문장 "가장 중요한 3가지 질문만 먼저 해줘" 가 매직입니다. 이 한 줄이 없으면 AI는 멋대로 가정하고 답변을 던집니다. 이 한 줄이 있으면 AI는 모르는 걸 먼저 물어보는 행동 패턴으로 바뀝니다. 시니어 개발자가 신입에게 일을 받을 때처럼요.

1-4. 실습 체크포인트

• AI가 "준비됐습니다. 먼저 3가지만 질문드릴게요"로 답변했는가?
• AI가 던진 3가지 질문이 구체적이고 날카로운가?
• 내가 그 질문에 답변을 던졌을 때, AI가 다음 단계로 부드럽게 넘어가는가?

Step 2: "사용자 시나리오 & 유스케이스 설계"

2-1. 페르소나 → 시나리오 → 유스케이스 흐름

개발자들이 가장 자주 빠지는 함정이 있습니다. "기능 목록 = 유스케이스" 로 착각하는 것. 유스케이스는 "액터의 목표" 입니다. "회원가입 기능"은 기능이고, "새로운 사용자가 회원가입을 통해 쇼핑을 시작하려 한다"가 유스케이스입니다.

비유하자면, 레스토랑 메뉴판에 "파스타"라고만 쓰여있는 거랑, "야근으로 지친 직장인이 혼자 와서 30분 안에 든든히 먹고 갈 수 있는 크림 파스타"라고 쓰여있는 거랑 느낌이 다르잖아요? 후자가 유스케이스입니다.

2-2. 🎁 실습 프롬프트 1 — 페르소나 설계

우리 커머스 앱의 주요 페르소나 3명을 설계해줘.
각 페르소나마다 다음 항목을 포함해줘:
- 이름, 나이, 직업
- Goal (앱에서 이루고 싶은 것)
- Pain Point (기존 커머스 앱에서 겪는 불편함)
- 주요 사용 시나리오 3가지

제약조건: 우리 필수/도전 기능과 연결될 수 있는 페르소나여야 해.
예를 들어 '한정판 스니커즈 드랍을 기다리는 사용자'는 동시성 제어와
자연스럽게 연결되잖아.

💡 왜 "기능과 연결되는 페르소나"를 요구하는가? 페르소나를 위한 페르소나는 문서를 위한 문서가 됩니다. 페르소나가 동시성 제어, 분산락 같은 우리 핵심 기술과 이어져야 "왜 이 기능이 필요한가" 를 설명할 수 있습니다.

2-3. 🎁 실습 프롬프트 2 — 유스케이스 명세서 & 다이어그램

위 페르소나를 기반으로 유스케이스 명세서를 만들어줘.
출력 형식은 다음과 같이 해줘:

## UC-001: [유스케이스 이름]
- **액터**:
- **사전조건**:
- **주요 흐름**:
  1.
  2.
- **대체 흐름**:
- **예외 흐름**:
- **사후조건**:
- **관련 필수/도전 기능**:

그리고 마지막에 PlantUML 형식의 유스케이스 다이어그램 코드도 같이 줘.

Step 3: "ERD 대화형 설계 + 레드팀 검증"

3-1. "한 방 프롬프트"가 위험한 이유

여러분이 가장 자주 하는 실수: AI한테 "커머스 앱 ERD 그려줘" 한 방에 물어보는 것. 이렇게 하면 AI는 평균적인 커머스 앱의 ERD를 던져줍니다. 우리 프로젝트의 필수 기능(동시성 제어)과 도전 기능(분산락, 캐싱)이 반영되지 않은, 교과서 같은 ERD가 나옵니다.

그래서 우리는 대화형 설계(Conversational Design) 를 합니다. 4단계로 쪼개서, 단계마다 내가 OK 해야 다음으로 넘어가게 만듭니다.

3-2. 🎁 실습 프롬프트 1 — 단계별 ERD 도출

우리 커머스 백엔드의 ERD를 설계하자.
다만 바로 답하지 말고, 다음 순서로 진행해줘:

1단계: 먼저 필요한 엔티티 목록만 뽑아줘 (설명 포함)
2단계: 내가 "좋아"라고 하면 엔티티 간 관계를 1:N, N:M으로 정의해줘
3단계: 각 엔티티의 속성을 정의하되, 동시성 제어가 필요한 필드
       (예: 재고 수량)에는 반드시 @Version 또는
       Pessimistic Lock 필요 여부를 주석으로 표시해줘
4단계: Mermaid ERD 코드로 최종 출력해줘

시작하자. 1단계부터.

🔑 "1단계부터. 내가 OK 해야 다음 단계로"의 힘 이 패턴을 단계별 설계 패턴(Step-by-step Design Pattern) 이라고 부릅니다. AI가 중간 단계에서 멋대로 가정하지 않고, 사람이 각 단계를 검토할 수 있게 만드는 장치입니다. 앞으로 AI랑 협업할 때 가장 자주 쓸 패턴이에요.

3-3. 🎁 실습 프롬프트 2 — 레드팀 검증

AI가 만든 ERD를 그냥 쓰면 위험합니다. 왜냐면 AI는 자기가 만든 걸 자기가 칭찬하는 경향이 있거든요. 그래서 페르소나를 바꿔서 다시 물어보는 기법을 씁니다.

방금 만든 ERD를 이제 '비판적인 코드리뷰어' 입장에서 검토해줘.
특히 다음 관점에서 약점을 찾아줘:

1. 정규화 이슈 (중복, 종속성)
2. 동시성 이슈 가능성 (어떤 테이블이 Hot Spot이 될까?)
3. 인덱스 최적화 관점 (자주 조회될 것 같은 컬럼)
4. 확장성 이슈 (MSA로 쪼갤 때 경계는 어디?)
5. 누락된 엔티티 (실제 커머스에서 필요할 법한데 빠진 것)

각 이슈마다 '왜 문제인지'와 '어떻게 개선할지'를 같이 줘.

🔑 레드팀 패턴(Red Team Pattern) AI가 만든 걸 AI에게 다시 비판시키는 이 기법, 실제로 해보면 놀랄 정도로 날카로운 비판이 나옵니다.

3-4. 실무 연결

쿠팡 상품팀에서 ERD를 설계할 때, 실제로 두 명의 시니어가 하나는 '설계자', 하나는 '비판자' 역할을 나눠서 서로 역할극을 합니다. 우리는 AI가 양쪽 역할을 다 해주는 거죠.

Step 4: "API 명세서 & OpenAPI 변환"

4-1. API 명세서가 단순 표가 아닌 이유

초보 개발자들은 API 명세서를 엔드포인트 목록으로만 생각합니다. 실무에선 API 명세서가 프론트-백 사이의 계약서(Contract) 입니다. 이 문서가 바뀌면 양쪽 모두가 고통받습니다. 그래서 처음에 잘 만들어야 합니다.

4-2. 🎁 실습 프롬프트 1 — RESTful API 설계

ERD와 유스케이스를 기반으로 REST API 명세서를 만들어줘.
출력은 다음 형식의 마크다운 표로:

| Method | Endpoint | 설명 | Request | Response | 인증 | 관련 UC |
|---|---|---|---|---|---|---|

제약사항:
- REST 원칙(자원 중심, 동사 X) 준수
- 페이징은 cursor 기반 우선 검토
- 재고 차감 같은 동시성 민감 API는 ⚠️ 표시
- 캐싱 대상 API는 💾 표시
- 인증 필요 API는 🔐 표시

그리고 각 API마다 예시 JSON Request/Response를 추가로 줘.

💡 이모지 표시가 왜 중요한가? ⚠️(동시성), 💾(캐싱), 🔐(인증) 표시는 나중에 구현 단계에서 "이 API는 어떤 특별한 처리가 필요한가" 를 한눈에 보여줍니다. 동시성 민감 API 목록이 곧 Step 7의 동시성 설계서의 입력이 됩니다.

4-3. 🎁 실습 프롬프트 2 — OpenAPI YAML 자동 변환

위 API 명세서를 OpenAPI 3.0 YAML 형식으로 변환해줘.
나중에 Swagger UI에 바로 붙일 수 있도록.

💡 왜 두 번 만드는가? 마크다운 표는 사람이 읽기 위한 거고, OpenAPI YAML은 도구가 읽기 위한 겁니다. 두 형식을 다 만들어두면 팀 회의에선 마크다운 표를 보고, 실제 Swagger UI에선 YAML을 쓸 수 있습니다. AI가 두 형식 간 변환을 대신 해주니까 드는 비용은 없습니다.

Step 5: "화면 설계서 + Figma 목업 연동"

5-1. 백엔드 개발자가 화면 설계서를 만드는 이유

"저 백엔드 개발자인데 화면을 왜 설계해요?" — 좋은 질문입니다. 그런데 사실 이 질문 자체가 흔한 오해에서 나옵니다.

좋은 백엔드 개발자는 화면을 이해하는 사람입니다. 화면을 모르면 좋은 API를 설계할 수 없기 때문이에요.

예를 들어볼게요. 상품 상세 페이지 하나만 생각해봅시다. 이 화면엔 상품 정보, 판매자 정보, 리뷰 요약, 재고 상태, 관련 상품, 장바구니 담기 버튼이 모두 있습니다. 백엔드 개발자가 이 화면을 모른 채로 API를 설계하면 어떻게 될까요?

• /products/{id} 하나만 덩그러니 만들어놓고, 판매자 정보는 /sellers/{id}로 따로 빼고, 리뷰는 /products/{id}/reviews로 또 따로 빼고… 결과적으로 화면 하나 띄우려고 API를 5번 호출하게 됩니다 (N+1 문제의 프론트엔드 버전!)
• 반대로 화면을 이해하는 백엔드 개발자는 이렇게 생각합니다. "이 화면이 한 번에 필요한 데이터는 뭐지?" → 그래서 /products/{id}/detail 응답에 상품+판매자+리뷰요약+재고를 한 번에 묶어서 내려줍니다. 네트워크 왕복이 1번으로 줄어듭니다.

화면 설계서가 백엔드에게 주는 3가지 선물:

1. 응답 DTO 설계의 근거가 생긴다 — "이 화면에 뭐가 보이나"가 곧 "이 API 응답에 뭐가 들어가야 하나"입니다. 오버페칭/언더페칭을 피할 수 있습니다.
2. API 호출 순서와 조합이 보인다 — 로그인→상품조회→장바구니 담기→결제 같은 흐름이 화면 이동과 1:1로 매칭됩니다. 빠진 API, 겹친 API가 드러납니다.
3. 엣지 케이스가 눈에 보인다 — "재고 0개일 때 이 버튼은 어떻게 되나?", "로그인 안 된 상태에서 장바구니 누르면?" 같은 질문이 화면을 보면 저절로 튀어나옵니다. 이게 전부 API 예외 처리 스펙이 됩니다.

이번 프로젝트는 프론트엔드를 바이브코딩으로 처리합니다. 즉, 여러분이 직접 AI에게 "로그인 페이지 만들어줘"라고 해야 합니다.

이렇게 한 방으로 던지면 AI는 "알아서 예쁘게" 만듭니다. 그 결과물이 여러분의 API와 일치할 리가 없죠. 그래서 화면 설계서가 이중으로 중요합니다. 화면 설계서가 있으면:

• AI에게 "이 화면은 이런 API를 호출하고, 이런 데이터를 이런 레이아웃으로 보여줘" 라고 명확히 지시할 수 있습니다
• 나중에 API를 수정해도 화면 설계서를 기준으로 영향도를 파악할 수 있습니다
• Figma 목업과 연동하면 시각적 레퍼런스까지 AI에게 제공할 수 있습니다

💡 실무 한 줄 요약 "API 설계를 잘하는 백엔드 개발자는 예외 없이 화면을 잘 이해합니다. 화면을 모르면 API는 '데이터 덤프'가 되고, 화면을 알면 API는 '사용자 경험의 일부'가 됩니다."

5-2. 🎁 실습 프롬프트 1 — 화면 목록 도출

우리 유스케이스 기준으로, 필요한 화면 목록을 모두 뽑아줘.
출력 형식:

| 화면 ID | 화면 이름 | 관련 UC | 주요 기능 | 호출 API |
|---|---|---|---|---|

그리고 각 화면마다 '이 화면에 반드시 있어야 할 요소'를
불렛 리스트로 정리해줘. (예: 헤더, 검색바, 상품 카드 그리드, 페이징)

5-3. 🎁 실습 프롬프트 2 — ASCII 와이어프레임

위 화면 중 주요 5개에 대해 ASCII 아트 기반 와이어프레임을 그려줘.
각 영역마다 어떤 데이터가 들어가고, 어떤 인터랙션이 가능한지도 주석으로 달아줘.
백엔드 개발자가 API 설계 검증용으로 쓸 거니까 예쁠 필요는 없어. 
첫번째 화면부터 시작하자.

💡 왜 ASCII 와이어프레임? Figma는 나중에 만들 겁니다. 그 전에 텍스트 기반 와이어프레임을 먼저 만드는 이유는 (1) AI가 빠르게 생성할 수 있고, (2) 마크다운 문서에 그대로 박아넣을 수 있고, (3) API와 1:1 매핑을 검증하기 쉽기 때문입니다. "이 화면에 장바구니 아이콘이 있는데 장바구니 API가 없네?" 같은 걸 바로 잡아낼 수 있습니다.

5-4. 🎁 실습 프롬프트 3 — Figma 목업용 프롬프트 생성

ASCII 와이어프레임이 완성되면, 이제 Figma에서 실제 목업을 만들 차례입니다. Figma AI 또는 별도 디자인 AI에게 던질 프롬프트를 AI에게 만들게 합니다. 메타 프롬프팅이죠.

방금 만든 와이어프레임을 Figma에서 목업으로 만들 건데,
Figma AI에게 전달할 프롬프트를 만들어줘.

프롬프트에는:
- 화면 목적
- 필수 컴포넌트 리스트
- 컬러 톤 & 무드
- 레이아웃 가이드 (데스크탑/모바일)
- 참고할 만한 기존 앱 (예: 컬리, 29CM)
가 포함되어야 해.

5-5. 최종 산출물: "화면 설계서 → 프론트 바이브코딩 프롬프트"

이 모든 걸 다 만들면, 나중에 프론트엔드 바이브코딩 단계에서 다음처럼 쓸 수 있습니다.

[AI에게 프론트엔드 코드 요청 시]

아래 화면 설계서를 참고해서 React 컴포넌트를 만들어줘.
- 화면 ID: S-003 (상품 상세)
- 관련 API: GET /api/products/{id}, POST /api/cart
- 와이어프레임: (ASCII 붙여넣기)
- Figma 링크: https://figma.com/...
- 디자인 톤: 29CM 스타일, 미니멀

🔑 포인트: 화면 설계서가 있으면 프론트 AI 프롬프트가 "알아서 해줘" 에서 "이 설계서대로 해줘" 로 바뀝니다. 결과물 퀄리티 차이가 10배입니다.

Step 6: "인프라 아키텍처 다이어그램"

6-1. 도전 기능 "배포 자동화"의 출발점

도전 기능 중에 EC2 + RDS + ElastiCache + ECR + GitHub Actions 배포 자동화가 있습니다. 이걸 구현하려면 먼저 "인프라가 어떻게 생겼는지" 를 그려야 합니다. 없으면 GitHub Actions 워크플로우를 작성할 때 매번 "이거 어디로 보내야 하지?" 에서 헤맵니다.

6-2. 🎁 실습 프롬프트 — AWS 인프라 설계

다음 조건으로 AWS 인프라 아키텍처를 설계해줘:
- EC2 (Spring Boot 앱 서버)
- RDS (MySQL)
- ElastiCache (Redis)
- ECR (Docker 이미지 저장소)
- GitHub Actions (CI/CD)

출력:
1. Mermaid 다이어그램 코드
2. 각 컴포넌트가 왜 필요한지 한 줄 설명
3. 보안 그룹/VPC 구성 제안
4. 예상 월 비용 (프리티어 vs. 실서비스)
5. 배포 파이프라인 흐름 (GitHub push → ECR → EC2까지)

6-3. 💰 비용 예측을 프롬프트에 넣는 이유

부트캠프에서 가장 많이 나오는 사고가 "AWS 요금 폭탄" 입니다. 처음 특강에서 AI한테 "예상 월 비용을 프리티어 vs 실서비스 기준으로 알려줘" 를 요청하는 습관을 들이세요. 이 한 줄이 여러분 지갑을 지켜줍니다.

6-4. 실무 연결

실제 스타트업에서 주니어 백엔드 개발자가 "서버 아키텍처 그려줘" 라는 요청을 받으면 당황합니다. 오늘 이 프롬프트 하나만 기억해둬도 실무에서 바로 씁니다.

Step 7: "동시성 제어 설계서 — 오늘의 하이라이트 ⭐"

7-1. 이번 프로젝트의 진짜 핵심

필수 기능: 비관락, 낙관락, 로컬 캐싱 도전 기능: Redis 분산락, Redis 캐싱

이 기능들을 "구현"하는 건 사실 쉽습니다. 진짜 어려운 건 "언제 뭘 쓸지" 결정하는 겁니다. 이번 프로젝트가 여러분에게 요구하는 가장 높은 수준의 역량이 바로 이 의사결정입니다.

7-2. 🎁 실습 프롬프트 1 — 동시성 시나리오 도출

우리 커머스 앱에서 동시성 제어가 필요한 시나리오를 모두 뽑아줘.
각 시나리오마다 다음 정보를 포함해줘:
- 시나리오 이름
- 충돌이 발생하는 조건
- 충돌 시 비즈니스 임팩트 (예: 재고 음수, 중복 결제)
- 예상 트래픽 패턴 (예: 평소 낮음, 이벤트 시 폭발)

반드시 포함할 시나리오:
- 한정 수량 상품 재고 차감
- 동일 유저의 중복 주문/결제 방지
- 선착순 쿠폰 발급
- 포인트 적립/사용
- 상품 리뷰 좋아요 카운트

7-3. 🎁 실습 프롬프트 2 — 동시성 전략 매트릭스

위 시나리오 각각에 대해 다음 3가지 전략 중 뭐가 적합한지
Trade-off와 함께 추천해줘:

A. 비관적 락 (SELECT ... FOR UPDATE)
B. 낙관적 락 (@Version)
C. Redis 분산락 (Redisson)

출력 형식:
| 시나리오 | 추천 전략 | 이유 | 장점 | 단점 | 대안 | 재시도 정책 |

그리고 각 전략을 썼을 때 예상되는 '실패 케이스'도 하나씩 알려줘.
(예: 낙관락 썼을 때 OptimisticLockException 재시도 지옥 같은 것)

7-4. 락 전략 선택 가이드

7-5. 🎁 실습 프롬프트 3 — 성능 실험 계획

위에서 정한 동시성 전략이 실제로 잘 동작하는지 증명할 실험 계획을 만들어줘.
- 실험 도구: JMeter / K6 / Locust 중 추천
- 테스트 시나리오: 동시 요청 N건 → 기대 결과
- 성공 기준 (SLA): 예) 동시 1000건 재고 차감 시 음수 발생 0건
- 측정 지표: TPS, p95 응답시간, 실패율

7-6. 실무 연결 — "쿠팡 로켓배송, 배민 쿠폰 이벤트"

쿠팡 로켓배송 재고관리에서 재고가 음수가 되는 순간 실제로 돈이 사라집니다. 배민의 선착순 쿠폰 이벤트에서 중복 지급이 발생하면 고객 CS가 폭주합니다. 여러분이 오늘 만드는 이 문서가 바로 그런 사고를 막는 설계도입니다.

7-7. ⚠️ 주의

• 오해 1: "분산락이 제일 좋은 거 아니에요?"
  • 대답: "분산락은 가장 비싸고 느립니다. 단일 인스턴스라면 비관락이 더 빠르고 안전합니다."
• 오해 2: "낙관락 쓰면 재시도만 하면 되잖아요?"
  • 대답: "재시도 지옥이 존재합니다. 충돌 빈도가 높으면 오히려 비관락보다 느려집니다."

Step 8: "ADR 작성법 & 셀프 리뷰 체크리스트"

8-1. ADR이란?

ADR (Architecture Decision Record) 은 "왜 이 기술을 골랐는지" 를 기록하는 문서입니다. 나중에 팀원이 "이거 왜 이렇게 했어요?" 라고 물어봤을 때 답할 수 있는 유일한 증거입니다. 1주일만 지나도 여러분 본인조차 왜 이렇게 결정했는지 기억 못 합니다. ADR이 없으면 똑같은 논의를 또 하게 됩니다.

8-2. 🎁 ADR 템플릿 프롬프트

우리가 방금 결정한 "재고 차감에 Redis 분산락을 사용한다"라는
결정을 ADR 형식으로 문서화해줘.

## ADR-XXX: [결정 제목]
- **상태**: Proposed / Accepted / Deprecated
- **컨텍스트**: 왜 이 결정이 필요했는가?
- **고려한 대안**: A / B / C
- **결정**:
- **근거**:
- **결과(긍정)**:
- **결과(부정/리스크)**:
- **재검토 조건**: 언제 이 결정을 다시 봐야 하는가?

💡 "재검토 조건"이 가장 중요한 이유 6개월 뒤 여러분 프로젝트의 트래픽이 10배 늘어났을 때, 지금 결정한 분산락 전략이 여전히 유효할까요? "트래픽이 N배 되면 재검토한다"를 미리 적어두면 나중에 언제 이 결정을 다시 봐야 할지 명확해집니다.

8-3. 🎁 최종 셀프 리뷰 프롬프트

3일간 작성한 문서를 팀원들과 리뷰할 때 쓸 체크리스트입니다.

내가 작성한 SA 문서 전체를 다음 체크리스트로 검증해줘.
누락된 게 있으면 구체적으로 어떤 문서에 어떤 내용이 빠져있는지 알려줘.

## 체크리스트
- [ ] 유스케이스 ↔ API 엔드포인트 매핑이 1:1 이상 되는가?
- [ ] ERD의 모든 테이블이 최소 하나 이상의 API에서 사용되는가?
- [ ] 필수 기능(비관락/낙관락/로컬캐싱)이 설계에 반영됐는가?
- [ ] 도전 기능이 "왜 필요한지" ADR로 설명됐는가?
- [ ] 동시성 충돌 시나리오가 최소 5개 이상 명시됐는가?
- [ ] 실패/예외 흐름이 API 명세서에 포함됐는가?
- [ ] 인프라 다이어그램의 모든 컴포넌트가 실제로 쓰이는가?
- [ ] 화면 설계서의 모든 화면이 API와 연결되는가?

마무리: 5가지 프롬프트 패턴 복습 & Day 안내

오늘 배운 "평생 쓸 5가지 프롬프트 패턴"

오늘 특강은 SA 문서 만들기지만, 진짜로 배워야 할 건 프롬프트 패턴 입니다. 이 5가지는 SA 문서뿐 아니라 앞으로 모든 AI 협업에서 평생 쓸 수 있습니다.

[패턴 1] 컨텍스트 주입 패턴
  → Role + Constraints + Output Format
  → Step 1의 초기화 프롬프트가 대표 사례

[패턴 2] 단계별 설계 패턴
  → "1단계부터. 내가 OK 해야 다음 단계로"
  → Step 3의 ERD 설계가 대표 사례

[패턴 3] 레드팀 검증 패턴
  → "이제 비판적 리뷰어로 다시 봐줘"
  → Step 3의 ERD 검증이 대표 사례

[패턴 4] Trade-off 매트릭스 패턴
  → "대안 N개와 장단점 비교표"
  → Step 7의 동시성 전략 매트릭스가 대표 사례

[패턴 5] ADR 기록 패턴
  → "이 결정을 ADR 형식으로 남겨줘"
  → Step 8의 ADR 템플릿이 대표 사례

핵심 정리 — "AI는 답을 주지 않는다, 질문을 더 잘 하게 해준다"

AI한테 문서 만들어달라고 했지만, 사실 AI가 던진 질문이 여러분을 더 성장시켰을 겁니다. AI한테 좋은 답변을 받으려면 좋은 질문을 해야 하고, 좋은 질문을 하려면 문제를 깊이 이해해야 합니다. 결국 AI와 협업하는 건 자기 자신의 사고를 정리하는 과정입니다.

3일간의 SA 문서 작성 로드맵

💡 오전 특강 후 오후엔 팀으로! 특강 중에는 개인으로 진행하세요. 각자 프롬프트 감각을 익히는 게 먼저입니다. 오후에 팀으로 모였을 때, 각자가 만든 결과물을 비교하면서 통합하면 "AI는 같은 프롬프트에도 다른 답을 준다" 는 걸 실감할 수 있습니다. 이 경험 자체가 큰 학습입니다.

다음 프로젝트 Day 예고

"이제 SA 문서가 생겼습니다. 이걸 근거로 실제 코드를 씁니다. 바이브코딩이 아니라 명세기반 개발로요. '이 SA 문서 참고해서 Post 엔티티 먼저 만들어줘' 같은 식으로 AI한테 지시할 수 있게 됩니다. 그 감각이 오늘 특강의 진짜 목표입니다."

튜터의 과제

과제 (Homework)

1. [필수] 팀 SA 문서 세트 완성 (3일간)
   • 섹션 10종 모두 포함: 개요서, 페르소나/시나리오, 유스케이스, 기능명세, ERD, API명세서, 화면설계서, 인프라, 동시성설계서, ADR
   • 제출 형태: GitHub Repository 또는 Notion 워크스페이스
   • 필수 포함: Mermaid ERD, OpenAPI YAML, Figma 목업 링크, ADR 최소 3건
2. [필수] 프롬프트 히스토리 기록
   • 이번 SA 문서를 만들며 AI에게 던진 주요 프롬프트 5개 이상 + 그에 대한 AI의 답변을 별도 파일(prompts.md)로 기록
   • 왜 그 프롬프트를 썼는지, 답변이 만족스러웠는지 코멘트 추가
3. [필수] 동시성 설계서 최소 시나리오 수
   • 동시성 충돌 시나리오 최소 5개 이상 포함
   • 각 시나리오마다 추천 전략 + 이유 + 실패 케이스까지 명시
4. [선택] 개인 vs 팀 결과물 비교
   • 특강 중 개인이 만든 초안과 오후에 팀으로 만든 버전의 차이점을 정리
   • "내가 놓친 부분" / "팀원이 놓친 부분" / "AI가 일관되게 틀린 부분" 각각 1개 이상
5. [선택] 다른 AI 모델 교차 검증
   • 같은 프롬프트를 Claude, ChatGPT, Gemini에 각각 던지고 답변을 비교
   • 어떤 모델이 어떤 문서 유형에 강한지 본인만의 기준을 만들어보세요

🤔 생각해볼 거리 (토론 주제)

1. 바이브코딩 vs 명세기반 개발의 경계
   • 오늘 배운 명세기반 개발이 만능일까요? 어떤 상황에서는 오히려 바이브코딩이 더 나을까요? "3일간의 해커톤" vs "3개월짜리 실서비스" 를 비교해서 논의해보세요.
2. AI가 던진 질문의 품질
   • 특강 중 AI가 여러분에게 던진 질문 중 가장 날카로웠던 것과 가장 뻔했던 것을 비교해보세요. 품질 차이가 왜 났을까요? 프롬프트를 어떻게 개선하면 더 날카로운 질문을 받을 수 있을까요?
3. 레드팀 패턴의 한계
   • AI가 자기가 만든 걸 AI가 비판하는 방식, 완벽할까요? AI가 미처 비판하지 못하는 blind spot은 어디일까요? 이걸 사람이 어떻게 보완할 수 있을까요?
4. ADR의 재검토 시점
   • 오늘 여러분이 만든 ADR 중 "재검토 조건"을 가장 엄격하게 잡아야 할 결정은 무엇인가요? 왜 그렇게 생각하세요?
5. "AI 없으면 설계 못 하는 개발자"가 되지 않으려면?
   • AI에 너무 의존하면 본인의 설계 근력이 사라질 위험이 있습니다. AI를 쓰면서도 본인이 성장하려면 어떻게 해야 할까요? 오늘 배운 5가지 프롬프트 패턴 중 어떤 게 가장 본인 성장에 도움이 될 것 같나요?

마지막 한마디 오늘 여러분은 AI와 협업하는 법을 배웠지만, 진짜로 얻어가야 할 건 "스스로에게 좋은 질문을 던지는 습관" 입니다. AI에게 좋은 질문을 할 수 있다는 건, 문제를 깊이 이해하고 있다는 뜻이니까요. 남은 3주 동안, AI와 같이 성장하는 개발자가 되길 바랍니다. 화이팅!

프론트엔드 바이브코딩 프롬프트 가이드

백엔드 개발자를 위한 AI 활용 프론트엔드 개발 가이드 기술 스택: React + Vite + TypeScript

1. 바이브코딩이란?

바이브코딩은 AI에게 자연어로 "이런 느낌(vibe)으로 만들어줘"라고 설명하면 코드를 생성해주는 방식의 개발을 말합니다. 여러분이 백엔드에서 Spring Boot로 API를 설계하는 것처럼, 프론트엔드도 와이어프레임과 API 명세서를 기반으로 AI에게 지시하면 됩니다.

쉽게 비유하면 이런 겁니다. 여러분이 인테리어 업체에 "이런 분위기의 카페를 만들어주세요"라고 레퍼런스 사진과 요구사항을 전달하는 것과 같아요. 레퍼런스 사진이 와이어프레임이고, 요구사항이 프롬프트입니다.

2. 시작하기 전 준비물

2-1. 프로젝트 초기 세팅

AI에게 프로젝트를 처음 세팅해달라고 요청할 때는 아래와 같이 하면 됩니다.

React + Vite + TypeScript 프로젝트를 생성해줘.
추가 라이브러리:
- react-router-dom (페이지 이동)
- axios (API 호출)
- styled-components 또는 tailwindcss (스타일링)

폴더 구조는 아래처럼 잡아줘:
src/
  ├── pages/        # 페이지 단위 컴포넌트
  ├── components/   # 재사용 가능한 공통 컴포넌트
  ├── api/          # API 호출 함수 모음
  ├── hooks/        # 커스텀 훅
  ├── types/        # TypeScript 타입 정의
  └── styles/       # 글로벌 스타일

왜 폴더 구조를 먼저 잡을까? Spring Boot에서 controller, service, repository 패키지를 나누는 것처럼, 프론트엔드도 역할별로 폴더를 나누면 AI가 코드를 생성할 때 일관된 위치에 파일을 만들어줍니다.

2-2. 준비해야 할 자료

3. 프롬프트 작성의 핵심 원칙

원칙 1: 역할을 먼저 부여하라

AI에게 "넌 이런 사람이야"라고 알려주면 훨씬 일관된 코드를 만들어줍니다.

너는 React + TypeScript 프론트엔드 시니어 개발자야.
나는 백엔드 개발자이고 프론트엔드는 잘 몰라.
내가 와이어프레임과 API 명세서를 줄 테니,
이걸 기반으로 React 컴포넌트를 만들어줘.

코드를 작성할 때 다음 규칙을 지켜줘:
- 함수형 컴포넌트만 사용
- TypeScript를 사용하고, 타입은 반드시 정의
- API 호출은 axios를 사용하고, src/api/ 폴더에 분리
- 스타일은 tailwindcss 사용
- 한국어 주석으로 각 코드 블록이 무엇을 하는지 설명

비유: Spring Boot에서 application.yml로 프로젝트 전체 설정을 잡는 것처럼, 이 역할 부여가 프론트엔드 프로젝트의 "설정 파일" 역할을 합니다.

원칙 2: 와이어프레임은 구체적으로 설명하라

이미지를 첨부할 수 있으면 첨부하되, 텍스트로도 설명을 같이 넣어주는 것이 좋습니다.

나쁜 예시:

로그인 페이지 만들어줘

좋은 예시:

아래 와이어프레임을 보고 로그인 페이지를 만들어줘.

[와이어프레임 이미지 첨부 또는 아스키아트]

+----------------------------------+
|           로고 이미지              |
|                                  |
|  [이메일 입력]                    |
|  [비밀번호 입력]                   |
|                                  |
|  [로그인 버튼]                    |
|                                  |
|  아직 회원이 아니신가요? [회원가입]   |
+----------------------------------+

화면 동작 설명:
- 이메일과 비밀번호를 입력하고 로그인 버튼을 클릭하면 로그인 API를 호출한다
- 로그인 성공 시 메인 페이지(/)로 이동한다
- 로그인 실패 시 입력 필드 아래에 빨간색으로 에러 메시지를 표시한다
- 이메일 형식이 올바르지 않으면 "올바른 이메일 형식을 입력해주세요" 메시지를 표시한다
- 회원가입 링크를 클릭하면 /signup 페이지로 이동한다

원칙 3: API 명세서를 정확하게 전달하라

백엔드 개발자인 여러분이 가장 잘 할 수 있는 부분입니다. API 명세를 정확하게 전달하면 AI가 API 연동 코드를 깔끔하게 만들어줍니다.

이 페이지에서 사용하는 API 명세는 다음과 같아:

### 로그인 API
- URL: POST /api/v1/auth/login
- Request Body:
  {
    "email": "string",
    "password": "string"
  }
- Response (200 OK):
  {
    "accessToken": "string",
    "refreshToken": "string",
    "user": {
      "id": "number",
      "email": "string",
      "nickname": "string"
    }
  }
- Response (401 Unauthorized):
  {
    "code": "AUTH_001",
    "message": "이메일 또는 비밀번호가 올바르지 않습니다"
  }

accessToken은 로컬스토리지에 저장하고,
이후 API 호출 시 Authorization 헤더에 Bearer 토큰으로 포함해줘.

Swagger를 활용하는 경우: Swagger UI에서 API 정보를 복사해서 붙여넣거나, OpenAPI JSON 파일을 직접 제공하면 됩니다.

첨부한 swagger.json 파일을 분석해서
이 프로젝트에서 사용할 API 호출 함수들을
src/api/ 폴더에 만들어줘.

원칙 4: 한 번에 하나의 페이지씩 요청하라

나쁜 예시:

전체 화면 다 만들어줘

좋은 예시:

지금은 로그인 페이지만 만들어줘.
나머지 페이지는 이후에 하나씩 요청할게.

비유: Spring에서 Controller를 한 번에 다 만들지 않고 하나씩 만드는 것과 같아요. AI도 한 번에 너무 많은 것을 요청하면 일관성이 떨어질 수 있습니다.

4. 단계별 프롬프트 템플릿

프론트엔드 바이브코딩은 아래 순서로 진행하면 됩니다. 마치 Spring Boot에서 Entity → Repository → Service → Controller 순서로 만드는 것처럼, 프론트엔드도 순서가 있습니다.

Step 1: API 연동 함수 먼저 만들기 (= Repository 계층)

다음 API 명세서를 보고 src/api/ 폴더에 API 호출 함수들을 만들어줘.

[API 명세서 붙여넣기 또는 파일 첨부]

규칙:
- axios 인스턴스를 src/api/client.ts에 만들고, baseURL과 인터셉터를 설정해줘
- 각 도메인별로 파일을 분리해줘 (auth.ts, user.ts, product.ts 등)
- 요청/응답 타입은 src/types/ 폴더에 정의해줘
- 에러 처리는 인터셉터에서 공통으로 처리해줘

왜 API부터? Spring에서 Repository를 먼저 만들고 Service에서 호출하는 것처럼, 프론트엔드도 API 호출 함수를 먼저 만들어두면 페이지를 만들 때 가져다 쓰기만 하면 됩니다.

Step 2: 공통 컴포넌트 만들기 (= 공통 유틸리티)

우리 프로젝트에서 공통으로 사용할 컴포넌트를 만들어줘.
src/components/ 폴더에 넣어줘.

필요한 공통 컴포넌트:
- Button: 크기(small, medium, large), 색상(primary, secondary, danger) 변경 가능
- Input: 라벨, 에러 메시지 표시 기능 포함
- Header: 로고, 네비게이션 메뉴, 로그인/로그아웃 버튼 포함
- Modal: 제목, 내용, 확인/취소 버튼이 있는 모달 팝업

Step 3: 페이지 만들기 (= Controller 계층)

여기서 와이어프레임과 화면설계서를 활용합니다.

아래 와이어프레임과 화면 동작 설명을 보고
회원가입 페이지를 만들어줘.

파일 위치: src/pages/SignupPage.tsx

[와이어프레임 이미지 첨부 또는 아스키아트]

화면 동작:
1. 이메일, 비밀번호, 비밀번호 확인, 닉네임 입력 필드가 있다
2. 비밀번호와 비밀번호 확인이 일치하지 않으면 "비밀번호가 일치하지 않습니다" 표시
3. 모든 필드를 입력하면 회원가입 버튼이 활성화된다
4. 회원가입 성공 시 로그인 페이지로 이동한다
5. 이메일 중복 에러(409) 발생 시 "이미 사용 중인 이메일입니다" 표시

사용할 API: src/api/auth.ts에 있는 signup 함수를 사용해줘
사용할 컴포넌트: src/components/에 있는 Button, Input 컴포넌트를 사용해줘

Step 4: 라우팅 설정 (= 요청 매핑)

react-router-dom을 사용해서 페이지 라우팅을 설정해줘.

라우트 구조:
- / : 메인 페이지 (로그인 필요)
- /login : 로그인 페이지
- /signup : 회원가입 페이지
- /products : 상품 목록 페이지 (로그인 필요)
- /products/:id : 상품 상세 페이지 (로그인 필요)

로그인이 필요한 페이지는 accessToken이 없으면 /login으로 리다이렉트해줘.
이미 로그인한 사용자가 /login이나 /signup에 접근하면 /로 리다이렉트해줘.

비유: Spring Security의 SecurityFilterChain에서 URL별 접근 권한을 설정하는 것과 똑같은 개념이에요!

Step 5: 상태 관리 연결 (= Service 계층)

로그인 상태를 전역으로 관리할 수 있게 해줘.
React Context API를 사용해서 AuthContext를 만들어줘.

관리할 상태:
- isLoggedIn: 로그인 여부
- user: 유저 정보 (id, email, nickname)
- login(): 로그인 함수 (토큰 저장 + 유저 정보 설정)
- logout(): 로그아웃 함수 (토큰 삭제 + 상태 초기화)

이 Context를 App 컴포넌트 최상단에 감싸줘.

5. 자주 쓰는 상황별 프롬프트

상황 1: 목록 + 페이징 화면

아래 와이어프레임을 보고 상품 목록 페이지를 만들어줘.

[와이어프레임]

+----------------------------------+
|  [검색창]              [검색버튼]  |
|                                  |
|  +------+  +------+  +------+   |
|  |상품1  |  |상품2  |  |상품3  |   |
|  |이미지  |  |이미지  |  |이미지  |   |
|  |이름   |  |이름   |  |이름   |   |
|  |가격   |  |가격   |  |가격   |   |
|  +------+  +------+  +------+   |
|                                  |
|       < 1 2 3 4 5 >              |
+----------------------------------+

사용할 API:
- GET /api/v1/products?page={page}&size={size}&keyword={keyword}
- Response: { content: Product[], totalPages: number, currentPage: number }

동작:
- 한 페이지에 9개씩 (3x3 그리드) 표시
- 상품 카드를 클릭하면 /products/{id}로 이동
- 검색어를 입력하고 검색하면 keyword 파라미터로 API 호출
- 페이지 번호를 클릭하면 해당 페이지로 이동

상황 2: 폼 입력 + 유효성 검사

아래 와이어프레임을 보고 상품 등록 페이지를 만들어줘.

[와이어프레임]

화면 동작:
- 상품명(필수, 2~50자), 가격(필수, 0 이상), 설명(선택, 최대 500자),
  이미지 업로드(최대 3장)
- 각 필드에서 포커스를 벗어날 때(onBlur) 유효성 검사를 수행
- 유효성 검사 실패 시 해당 필드 아래에 빨간색 에러 메시지 표시
- 모든 필수 필드가 유효할 때만 등록 버튼 활성화
- 등록 성공 시 상품 목록 페이지로 이동

사용할 API:
- POST /api/v1/products (multipart/form-data)

상황 3: 실시간 데이터 (채팅, 알림 등)

WebSocket을 사용한 실시간 채팅 페이지를 만들어줘.

WebSocket 연결 정보:
- URL: ws://localhost:8080/ws/chat
- STOMP 프로토콜 사용
- 구독: /topic/chat/{roomId}
- 발행: /app/chat/{roomId}

메시지 형태:
{
  "senderId": number,
  "content": string,
  "sentAt": string (ISO 8601)
}

화면 동작:
- 기존 메시지는 GET /api/v1/chat/{roomId}/messages로 불러온다
- 새 메시지는 WebSocket으로 실시간 수신
- 내 메시지는 오른쪽, 상대 메시지는 왼쪽에 표시
- 메시지를 보내면 입력창이 비워지고, 스크롤이 맨 아래로 이동

상황 4: 기존 코드 수정/보완 요청

방금 만든 로그인 페이지에 다음 기능을 추가해줘:

1. "로그인 상태 유지" 체크박스 추가
   - 체크 시: refreshToken을 localStorage에 저장
   - 미체크 시: refreshToken을 sessionStorage에 저장
2. 소셜 로그인 버튼 추가 (카카오, 구글)
   - 카카오: GET /api/v1/auth/oauth2/kakao로 리다이렉트
   - 구글: GET /api/v1/auth/oauth2/google로 리다이렉트
3. 로그인 버튼 클릭 시 로딩 스피너 표시

기존 코드 구조는 유지하면서 추가해줘.

6. 트러블슈팅 프롬프트

개발 중에 문제가 생기면 이렇게 물어보세요.

에러가 발생했을 때

아래 에러가 발생했어. 원인과 해결 방법을 알려줘.

[에러 메시지 또는 스크린샷 붙여넣기]

현재 코드 상태:
- 어떤 파일에서 발생했는지
- 어떤 동작을 하다가 발생했는지

화면이 예상과 다를 때

로그인 페이지에서 아래 문제가 있어:
1. 입력 필드가 화면 왼쪽으로 치우쳐 있어 → 가운데 정렬해줘
2. 모바일에서 버튼이 너무 작아 → 모바일에서는 전체 너비로 변경해줘
3. 에러 메시지가 빨간색이 아니라 검정색이야 → 빨간색(#FF4444)으로 변경해줘

[현재 화면 스크린샷 첨부하면 더 좋음]

API 연동 문제

로그인 API 호출이 안 돼.
Network 탭에서 확인한 내용:
- Request URL: <http://localhost:5173/api/v1/auth/login>
- Status: 404

백엔드 서버는 localhost:8080에서 돌아가고 있어.
CORS 설정은 백엔드에서 해둔 상태야.
Vite 프록시 설정을 추가해줘.

7. 프롬프트 체크리스트

페이지를 요청하기 전에 아래 항목을 확인하세요.

□ 와이어프레임 또는 화면 스케치를 준비했는가?
□ 이 화면에서 사용하는 API 명세를 정리했는가?
  - URL, Method, Request Body, Response Body, 에러 응답
□ 화면의 동작(인터랙션)을 글로 정리했는가?
  - 버튼 클릭 시 무슨 일이 일어나는지
  - 성공/실패 시 각각 어떻게 되는지
  - 페이지 이동은 어디로 하는지
□ 이 페이지에서 사용할 공통 컴포넌트가 이미 만들어져 있는가?
□ 이전에 만든 API 함수나 타입을 재사용할 수 있는가?

8. CLAUDE.md 활용하기

클로드코드를 사용한다면 프로젝트 루트에 CLAUDE.md 파일을 만들어두면, Claude Code가 프로젝트 컨텍스트를 항상 기억합니다. Spring의 application.yml과 비슷한 역할이에요.

# CLAUDE.md

## 프로젝트 개요
이커머스 플랫폼의 프론트엔드 (React + Vite + TypeScript)

## 기술 스택
- React 18 + TypeScript
- Vite
- react-router-dom v6
- axios
- TailwindCSS

## 코딩 규칙
- 함수형 컴포넌트 + hooks만 사용
- 컴포넌트 파일명은 PascalCase (예: LoginPage.tsx)
- API 함수는 src/api/ 에 도메인별로 분리
- 타입 정의는 src/types/ 에 도메인별로 분리
- 주석은 한국어로 작성
- CSS는 TailwindCSS 유틸리티 클래스 사용

## API 서버 정보
- 개발 서버: <http://localhost:8080>
- Vite 프록시: /api → <http://localhost:8080/api>

## 폴더 구조
src/
  ├── api/          # API 호출 함수
  ├── components/   # 공통 컴포넌트
  ├── hooks/        # 커스텀 훅
  ├── pages/        # 페이지 컴포넌트
  ├── types/        # TypeScript 타입 정의
  ├── contexts/     # React Context
  └── styles/       # 글로벌 스타일

9. 실전 워크플로우 요약

전체 작업 흐름을 정리하면 이렇습니다.

1단계: 프로젝트 세팅
  └─ "React + Vite 프로젝트 만들어줘" + CLAUDE.md 설정

2단계: API 레이어 구축 (Swagger/API 명세서 전달)
  └─ "API 명세서 보고 호출 함수 만들어줘"

3단계: 공통 컴포넌트 생성
  └─ "Button, Input, Header 등 공통 컴포넌트 만들어줘"

4단계: 페이지별 개발 (와이어프레임 + 화면설계서 전달)
  └─ "이 와이어프레임 보고 ○○ 페이지 만들어줘"
  └─ 한 페이지씩 순서대로 진행

5단계: 라우팅 + 인증 처리
  └─ "페이지 라우팅 설정하고 로그인 필요한 페이지 보호해줘"

6단계: 테스트 + 수정
  └─ 화면 확인 → 문제 있으면 스크린샷과 함께 수정 요청

10. 주의사항

하지 말 것:

• "알아서 예쁘게 만들어줘" → AI가 임의로 판단하면 원하는 결과가 안 나옵니다
• "전체 페이지 다 한번에 만들어줘" → 한 번에 너무 많으면 품질이 떨어집니다
• API 명세 없이 "로그인 기능 만들어줘" → API 형태를 모르면 연동이 안 됩니다

꼭 할 것:

• 와이어프레임을 최대한 구체적으로 설명하기
• API 명세서의 요청/응답 형태를 정확하게 전달하기
• 에러 상황(4xx, 5xx)에서의 동작도 명시하기
• 수정 요청 시 구체적으로 "어디를 어떻게 바꿔달라"고 말하기
• 작업 후 화면을 직접 확인하고, 문제가 있으면 스크린샷과 함께 피드백하기

CH5 팀 프로젝트때 티켓팅 사이트 구현했는데 그때 튜터님이 알려주셨던 바이브 코딩 가이드 정리! (내가 나중에 보려고)

백엔드 바이브코딩 프롬프트 가이드(TicketFlow)

SA 문서 10종을 기반으로 Claude Code에게 백엔드 코드를 생성시키는 프롬프트 작성 가이드 기술 스택: Java 17 + Spring Boot 3.x + JPA + MySQL 8 + Redis + Docker

1. 바이브코딩으로 백엔드를 만든다는 것

바이브코딩은 AI에게 "이런 걸 만들어줘"라고 자연어로 지시하면 코드를 생성하는 방식입니다. 여러분은 이미 SA 문서 10종(프로젝트 개요서, ERD, API 명세서, 기능 명세서, 동시성 제어 설계서 등)을 작성했습니다. 이 문서들이 바로 AI에게 전달할 설계도입니다.

비유하자면 이렇습니다. 여러분이 건축주이고, SA 문서가 설계도면이고, Claude Code가 시공업체입니다. 설계도면이 정확할수록 시공 품질이 좋아지는 것처럼, SA 문서를 얼마나 정확하게 전달하느냐가 바이브코딩의 품질을 결정합니다.

2. 클로드코드를 사용할 경우 ? 시작하기 전: CLAUDE.md 세팅

프로젝트 루트에 CLAUDE.md를 만들어두면 Claude Code가 프로젝트 컨텍스트를 매 대화마다 기억합니다. Spring Boot의 application.yml이 프로젝트 설정을 담는 것처럼, CLAUDE.md는 AI를 위한 프로젝트 설정 파일입니다.

# CLAUDE.md — TicketFlow Backend

## 프로젝트 개요
TicketFlow — 공연·스포츠 티켓팅 플랫폼 백엔드 (B2C)
공정한 선착순 좌석 예매 + 선착순 쿠폰 발급 + 검색 캐싱

## 기술 스택
- Java 17 + Spring Boot 3.x
- Spring Data JPA + QueryDSL
- Spring Security + JWT (AccessToken 단독, 1시간 TTL)
- MySQL 8 (InnoDB, 타임존 KST)
- Redis 7 (Lettuce — 분산락 SETNX, Hold TTL, 인기검색어 ZSet)
- Caffeine (로컬 캐시, v2 검색)
- Docker + Docker Compose

## 패키지 구조
com.ticketflow
├── global/          # 공통 설정, 예외 처리, 보안
│   ├── config/      # SecurityConfig, RedisConfig, CacheConfig
│   ├── exception/   # GlobalExceptionHandler, ErrorCode, CustomException
│   └── jwt/         # JwtTokenProvider, JwtAuthenticationFilter
├── domain/
│   ├── user/        # User 엔티티, 회원가입/로그인
│   ├── event/       # Event, Section, Seat, Venue 엔티티 + 검색
│   ├── booking/     # Order, Booking, ActiveBooking + Hold + 결제
│   ├── coupon/      # Coupon, UserCoupon + 선착순 발급
│   └── chat/        # ChatRoom, ChatMessage + WebSocket (도전)
└── infra/
    └── redis/       # RedisLockRepository, RedisCacheConfig

## 각 도메인 패키지 내부 구조 (일관되게 유지)
domain/{도메인}/
├── entity/          # JPA 엔티티
├── repository/      # Spring Data JPA Repository
├── service/         # 비즈니스 로직
├── controller/      # REST API
├── dto/
│   ├── request/     # 요청 DTO
│   └── response/    # 응답 DTO
└── exception/       # 도메인 전용 예외 (선택)

## 코딩 규칙
- 엔티티에 @Setter 사용 금지 → 비즈니스 메서드로 상태 변경
- DTO와 엔티티 분리 필수 — 컨트롤러에서 엔티티 직접 반환 금지
- 응답은 공통 응답 형식 사용: { status, code, message, data }
- 예외는 GlobalExceptionHandler에서 일괄 처리
- 서비스 메서드에 @Transactional(readOnly=true) 기본, 쓰기 메서드만 @Transactional
- 테스트: 단위 테스트(Mockito) + 동시성 테스트(ExecutorService + CyclicBarrier)
- 한국어 주석으로 핵심 비즈니스 로직 설명

## ERD 핵심 테이블
- USER (user_id PK, email UK, password, nickname, role ENUM)
- VENUE (venue_id PK, name, address) — 시드데이터 1개만, venue_id=1 고정
- EVENT (event_id PK, venue_id FK, title, category ENUM, event_date, sale_start_at, sale_end_at, round_number, status ENUM)
- SECTION (section_id PK, event_id FK, section_name, price, total_seats)
- SEAT (seat_id PK, section_id FK, row_name, col_num) — status 컬럼 없음!
- ORDER (order_id PK, user_id FK, user_coupon_id FK nullable, total/discount/final_amount, status ENUM)
- BOOKING (booking_id PK, order_id FK, user_id FK, seat_id FK, event_id FK, original_price, ticket_code UK nullable, status ENUM)
- ACTIVE_BOOKING (seat_id PK, booking_id UK) — 확정된 예약만, 중복 확정 물리적 차단
- PAYMENT (payment_id PK, order_id FK, payment_key UK, method, paid_amount, status ENUM)
- COUPON (coupon_id PK, name, discount_amount, total_quantity, remaining_quantity)
- USER_COUPON (user_coupon_id PK, user_id FK, coupon_id FK, status ENUM, version)
- CHAT_ROOM, CHAT_MESSAGE (도전 기능)

## 좌석 상태 판단 로직 (SEAT에 status 컬럼 없음!)
1. ACTIVE_BOOKING에 seat_id 존재 → CONFIRMED
2. Redis hold:{eventId}:{seatId} 키 존재 → ON_HOLD
3. 그 외 → AVAILABLE

## 동시성 제어
- 좌석 Hold: Lettuce SETNX 분산락 (lock:seat:{eventId}:{seatId}), Fail Fast
- 쿠폰 발급: Redis DECR + Lua Script 원자적 차감 (분산락 미사용)
- 쿠폰 사용: lock:user-coupon-use:{userCouponId} 분산락 + @Version 낙관적 락
- 락 획득 순서: ① 좌석 Hold 락 → ② 쿠폰 사용 락 → ③ DB 트랜잭션 (역순 해제)

## 서버 타임존
KST (UTC+9) — spring.jpa.properties.hibernate.jdbc.time_zone=Asia/Seoul

이 CLAUDE.md를 프로젝트 루트에 먼저 만들어두세요. Claude Code가 이 파일을 자동으로 읽고, 이후 모든 코드 생성에 이 컨텍스트를 반영합니다.

3. SA 문서 → 프롬프트 매핑 전략

여러분이 작성한 SA 문서 10종은 각각 바이브코딩의 특정 단계에서 활용됩니다.

4. 구현 순서와 단계별 프롬프트

Spring Boot에서 개발할 때 보통 Entity → Repository → Service → Controller 순서로 만들죠? 바이브코딩도 마찬가지입니다. 단, 인프라 세팅을 가장 먼저 합니다.

구현 순서:

Phase 0: 프로젝트 초기 세팅 + Docker Compose     ← 인프라 아키텍처 문서
Phase 1: 공통 설정 (Security, Exception, Redis)   ← ADR + 프로젝트 개요서
Phase 2: 엔티티 + Repository                      ← ERD 문서
Phase 3: 도메인별 서비스 + 컨트롤러               ← 기능 명세서 + API 명세서
Phase 4: 동시성 제어 (분산락 + 테스트)             ← 동시성 제어 설계서
Phase 5: 캐싱 (Caffeine → Redis)                  ← 프로젝트 개요서 §6
Phase 6: 통합 테스트 + QA                          ← 사용자 시나리오

Phase 0: 프로젝트 초기 세팅

Spring Boot 3.x + Java 17 프로젝트를 생성해줘.

build.gradle 의존성:
- spring-boot-starter-web
- spring-boot-starter-data-jpa
- spring-boot-starter-security
- spring-boot-starter-data-redis (Lettuce)
- spring-boot-starter-cache
- spring-boot-starter-validation
- spring-boot-starter-websocket (도전 기능용)
- com.github.ben-manes.caffeine:caffeine
- querydsl-jpa (jakarta classifier)
- jjwt-api, jjwt-impl, jjwt-jackson (io.jsonwebtoken 0.12.x)
- mysql-connector-j
- lombok
- spring-boot-starter-test
- h2 (test scope)

application.yml 설정:
- DB: jdbc:mysql://localhost:3306/ticketflow?serverTimezone=Asia/Seoul
- JPA: ddl-auto=validate, show-sql=true, time_zone=Asia/Seoul
- Redis: host=localhost, port=6379
- JWT: secret=${JWT_SECRET:local-dev-secret-key-minimum-256-bits-long}, expiration=3600000
- Server port: 8080

패키지 구조는 CLAUDE.md에 정의한 대로 만들어줘.

Docker Compose도 함께 요청합니다:

인프라 아키텍처 문서를 참고해서 docker-compose.yml을 만들어줘.

서비스 구성:
- mysql (MySQL 8.0, port 3306, DB명 ticketflow, root/root)
- redis (Redis 8.0, port 6379)
- 볼륨: mysql_data

app 서비스는 아직 추가하지 마. 로컬에서 IDE로 직접 실행할 거야.

Phase 1: 공통 설정 (Security + Exception + Redis)

이 단계에서는 ADR 문서와 프로젝트 개요서를 활용합니다.

JWT 인증:

ADR-001 결정 사항을 반영해서 JWT 인증을 구현해줘.

설계:
- AccessToken 단독 (RefreshToken 미구현, ADR-001)
- 알고리즘: HS256
- 만료: 1시간 (3600초)
- Payload: { userId, email, role }
- Spring Security 필터 체인에 JwtAuthenticationFilter 추가

구현할 클래스:
1. JwtTokenProvider
   - createToken(userId, email, role): String
   - validateToken(token): boolean
   - getUserIdFromToken(token): Long
   - getRoleFromToken(token): String

2. JwtAuthenticationFilter extends OncePerRequestFilter
   - Authorization 헤더에서 Bearer 토큰 추출
   - 유효하면 SecurityContext에 Authentication 설정
   - /api/auth/** 경로는 필터 스킵

3. SecurityConfig
   - CSRF 비활성화 (Stateless)
   - /api/auth/signup, /api/auth/login → permitAll
   - /api/admin/** → ADMIN 권한만
   - 나머지 → authenticated
   - SessionCreationPolicy.STATELESS

비고: 로그아웃은 클라이언트에서 토큰 삭제로 처리 (서버 블랙리스트 미구현)

공통 예외 처리:

API 명세서의 공통 에러 응답 형식을 참고해서 예외 처리를 구현해줘.

공통 에러 응답:
{
  "status": 409,
  "code": "SEAT_ALREADY_HELD",
  "message": "이미 선점된 좌석입니다.",
  "timestamp": "2026-04-09T12:00:00"
}

구현:
1. ErrorCode enum — 각 도메인별 에러 코드 정의
   - AUTH: EMAIL_DUPLICATED(409), AUTHENTICATION_FAILED(401), INVALID_CURRENT_PASSWORD(401)
   - EVENT: EVENT_NOT_FOUND(404), INVALID_EVENT_DATE(400)
   - SEAT: SEAT_ALREADY_HELD(409), SEAT_LOCK_FAILED(409), HOLD_EXPIRED(410)
   - BOOKING: BOOKING_NOT_FOUND(404), ALREADY_CANCELLED(400)
   - COUPON: COUPON_SOLD_OUT(409), COUPON_ALREADY_ISSUED(409), COUPON_EXPIRED(400)

2. CustomException extends RuntimeException — ErrorCode 포함
3. GlobalExceptionHandler (@RestControllerAdvice)
   - CustomException 처리
   - MethodArgumentNotValidException (Bean Validation 실패) 처리
   - 기타 예외 → 500 Internal Server Error

Phase 2: 엔티티 + Repository

ERD 문서를 통째로 전달합니다. 이것이 가장 효과적입니다.

아래 ERD를 보고 JPA 엔티티와 Repository를 만들어줘.

[ERD 문서(05.erd.md) 전체 내용 붙여넣기]

엔티티 규칙:
- @Getter만, @Setter 금지
- BaseEntity(createdAt, updatedAt)를 만들고 @MappedSuperclass로 상속
- ENUM은 @Enumerated(EnumType.STRING)
- 연관관계는 지연로딩(LAZY) 기본
- 양방향 매핑은 꼭 필요한 경우만 (단방향 우선)
- ACTIVE_BOOKING의 seat_id는 PK이자 UNIQUE

Repository:
- 각 엔티티별 JpaRepository 생성
- 커스텀 쿼리가 필요한 곳은 주석으로 "TODO: QueryDSL" 표시
- BookingRepository: findByUserIdAndStatus, findBySeatIdAndEventId
- ActiveBookingRepository: existsBySeatId, deleteBySeatId
- UserCouponRepository: existsByUserIdAndCouponId (중복 발급 방지)

Phase 3: 도메인별 서비스 + 컨트롤러

여기서 기능 명세서(FN-ID)와 API 명세서를 함께 전달합니다. 한 번에 하나의 도메인씩 요청하는 것이 핵심입니다.

3-1. 회원/인증 도메인

기능 명세서의 FN-AUTH-01(회원가입), FN-AUTH-02(로그인)을 구현해줘.

[FN-AUTH-01, FN-AUTH-02 내용 붙여넣기]

API 명세:
- POST /api/auth/signup
  Request: { email, password, nickname }
  Response 201: { userId, email, nickname, createdAt }
  Error: 409 EMAIL_DUPLICATED, 400 VALIDATION_FAILED

- POST /api/auth/login
  Request: { email, password }
  Response 200: { accessToken, expiresIn, tokenType }
  Error: 401 AUTHENTICATION_FAILED

구현 순서:
1. SignupRequest, LoginRequest DTO (Bean Validation 포함)
2. AuthService — signup(), login()
3. AuthController — @PostMapping

유효성 규칙:
- email: @Email, 최대 100자
- password: 8자 이상, 영문+숫자 포함 (정규식 커스텀 검증)
- nickname: 2~20자, 특수문자 불가

3-2. 이벤트 도메인

기능 명세서의 FN-EVT-01(이벤트 등록), FN-SRCH-01(이벤트 검색 v1)을 구현해줘.

[FN-EVT-01, FN-SRCH-01 내용 붙여넣기]

API 명세:
- POST /api/admin/events (🔐👑 ADMIN만)
  Request: { title, category, venueId, eventDate, saleStartAt, saleEndAt,
             roundNumber, description, thumbnailUrl, sections[] }
  sections: [{ sectionName, price, rowCount, colCount }]
  Response 201: { eventId, title, totalSeats, sectionsCreated }

  이벤트 등록 시 sections 배열 기반으로 SECTION + SEAT를 자동 생성해줘.
  SEAT의 row_name은 A~Z열, col_num은 1부터 colCount까지.
  예: rowCount=3, colCount=5 → A1~A5, B1~B5, C1~C5 총 15석

- GET /api/events?page=0&size=20&sort=eventDate,asc&category=CONCERT (🔓)
  Response: Page<EventSummary> — 캐시 미적용 (v1)

- GET /api/events/{eventId} (🔓)
  Response: EventDetail (섹션별 잔여좌석 포함)

  잔여좌석 계산: 섹션의 전체 좌석 수 - ACTIVE_BOOKING에 존재하는 좌석 수
  (SEAT 테이블에 status 컬럼이 없으므로 ACTIVE_BOOKING JOIN으로 계산)

3-3. 예매 도메인 (핵심! 동시성 주의)

기능 명세서의 FN-SEAT-02(좌석 임시 점유), FN-BK-01(주문 생성),
FN-BK-02(결제 확정 웹훅)을 구현해줘.

⚠️ 이 기능은 동시성 제어가 핵심이야. 동시성 제어 설계서의 시나리오 A를 참고해줘.

[FN-SEAT-02, FN-BK-01, FN-BK-02 내용 붙여넣기]
[동시성 제어 설계서 §3 시나리오 A 내용 붙여넣기]

좌석 Hold 플로우 (프로젝트 개요서 §4-3 기준):
1. 사용자 → 좌석 선택 요청
2. 서버 → Redis 분산락 획득 (Lettuce SETNX, lock:seat:{eventId}:{seatId}, TTL 3초)
3. 서버 → ACTIVE_BOOKING에 해당 seat_id 존재 여부 확인
4. 서버 → Redis에 Hold 키 SET (hold:{eventId}:{seatId}, 값: userId, TTL 5분)
5. 서버 → holdToken 역조회 키 SET (holdToken:{uuid}, 값: "{eventId}:{seatId}:{userId}", TTL 5분)
6. 서버 → user-hold-count:{userId} INCR (4 이상이면 거부)
7. 서버 → 분산락 해제 (UUID 검증 + Lua Script 원자적 삭제)
8. 200 OK { holdToken, expiresAt } 반환

API:
- POST /api/events/{eventId}/seats/{seatId}/hold (🔐⚠️)
  Response 200: { holdToken, expiresAt }
  Error: 409 SEAT_ALREADY_HELD, 409 SEAT_LOCK_FAILED, 429 HOLD_LIMIT_EXCEEDED

Redis 키 설계:
- 분산락: lock:seat:{eventId}:{seatId} (TTL 3초)
- Hold: hold:{eventId}:{seatId} → userId (TTL 300초)
- holdToken 역조회: holdToken:{uuid} → "{eventId}:{seatId}:{userId}" (TTL 300초)
- Hold 카운터: user-hold-count:{userId} (INCR/DECR, TTL 300초)

분산락 해제는 반드시 Lua Script로 원자적으로 처리해줘:
if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("del", KEYS[1])
else
    return 0
end

3-4. 쿠폰 도메인

기능 명세서의 FN-CPN-01(쿠폰 등록), FN-CPN-02(선착순 쿠폰 발급)을 구현해줘.

⚠️ 쿠폰 발급은 Redis DECR + Lua Script로 원자적 수량 차감! (분산락 미사용, ADR/ERD §2-8 참고)

[FN-CPN-01, FN-CPN-02 내용 붙여넣기]

API:
- POST /api/admin/coupons (🔐👑)
  쿠폰 등록 시 Redis에도 초기 재고 SET: coupon:stock:{couponId} = totalQuantity

- POST /api/coupons/{couponId}/issue (🔐⚠️)

쿠폰 발급 Lua Script:
  local stock = redis.call("DECR", KEYS[1])
  if stock < 0 then
      redis.call("INCR", KEYS[1])  -- 복원
      return -1  -- 품절
  end
  return stock

발급 플로우:
1. USER_COUPON에 (userId, couponId) 중복 확인 → 이미 있으면 409
2. Lua Script로 Redis coupon:stock:{couponId} DECR
3. DECR 결과 < 0 → INCR 복원 + 409 COUPON_SOLD_OUT
4. DECR 성공 → MySQL remaining_quantity UPDATE (-1)
5. USER_COUPON INSERT (status=ISSUED)
6. 201 { userCouponId, couponName, discountAmount }

비고: Redis 연결 실패 시 → MySQL SELECT ... FOR UPDATE 폴백 경로

Phase 4: 동시성 제어 테스트

동시성 제어 설계서를 활용하여 테스트를 작성합니다.

동시성 제어 설계서를 참고해서 동시성 테스트를 작성해줘.

테스트 시나리오 1: 좌석 Hold Race Condition
- 100개 Thread가 동시에 같은 좌석(eventId=1, seatId=1)에 Hold 요청
- 기대 결과: 정확히 1명만 Hold 성공, 나머지 99명은 실패
- ExecutorService + CyclicBarrier 사용
- @SpringBootTest + 실제 Redis 연결 (Embedded Redis 또는 Testcontainers)

테스트 시나리오 2: 쿠폰 발급 Race Condition
- 잔여 수량 10개인 쿠폰에 500명이 동시 발급 요청
- 기대 결과: 정확히 10명만 발급 성공, remaining_quantity = 0
- Redis DECR + Lua Script 검증

테스트 시나리오 3: 예매 시 쿠폰 적용 (락 중첩)
- 좌석 Hold + 쿠폰 사용이 동시에 일어나는 상황
- 락 획득 순서(좌석→쿠폰→DB) 준수 확인

각 테스트에서 검증할 것:
- CountDownLatch로 모든 Thread 완료 대기
- 성공 횟수 == 기대값 (AtomicInteger 카운터)
- DB 최종 상태 정합성 (remaining_quantity, ACTIVE_BOOKING 수)

Phase 5: 캐싱 (Caffeine → Redis)

프로젝트 개요서 §6의 3단계 캐싱 진화 흐름을 따릅니다.

프로젝트 개요서의 캐싱 3단계 진화 흐름을 구현해줘.

현재 단계: v1 (캐시 없음) → v2 (Caffeine 로컬 캐시 적용)

v2 Caffeine 적용 대상:
- 이벤트 검색 결과: TTL 5분, maximumSize 1000
- 이벤트 상세 조회: TTL 10분, maximumSize 500
- 인기 검색어: Redis ZSet 사용 (Caffeine 아님)

구현:
1. CacheConfig에 Caffeine CacheManager 설정
2. 검색 서비스에 @Cacheable("eventSearch") 적용
3. 이벤트 등록/수정/삭제 시 @CacheEvict 적용
4. v1/v2 엔드포인트는 동일 — 캐시 적용 여부만 다름

도전 기능 (Redis 캐시 전환) 준비:
- @ConditionalOnProperty(name = "cache.provider", havingValue = "caffeine")
- @ConditionalOnProperty(name = "cache.provider", havingValue = "redis")
- application.yml의 cache.provider 값만 바꾸면 Caffeine ↔ Redis 전환

Phase 6: 인프라 + CI/CD

인프라 아키텍처 문서를 전달합니다.

인프라 아키텍처 문서를 참고해서 다음을 만들어줘:

1. Dockerfile (Multi-stage build)
   - Stage 1: Gradle 빌드 (테스트 포함)
   - Stage 2: Eclipse Temurin JRE 17 기반 실행 이미지
   - 환경변수: DB_URL, REDIS_HOST, JWT_SECRET

2. GitHub Actions Workflow (.github/workflows/deploy.yml)
   - 트리거: main 브랜치 push
   - Job 1: test (./gradlew test)
   - Job 2: build-and-deploy
     - ECR 로그인 + 이미지 빌드/push (태그: $GITHUB_SHA)
     - EC2 SSH 접속 + 컨테이너 교체
   - GitHub Secrets: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY,
     EC2_HOST, EC2_SSH_KEY, DB_URL, REDIS_HOST, JWT_SECRET

3. Health Check 엔드포인트
   - GET /actuator/health → 200 OK (ALB Health Check용)

5. 프롬프트 작성 핵심 원칙

원칙 1: SA 문서를 직접 첨부하거나 복붙하라

나쁜 예시:

좌석 예매 기능 만들어줘

좋은 예시:

아래 기능 명세서(FN-BK-01)와 API 명세서를 보고 주문 생성 기능을 구현해줘.

[기능 명세서 FN-BK-01 전문 붙여넣기]
[API 명세서 POST /api/bookings 전문 붙여넣기]
[동시성 제어 설계서 시나리오 A 붙여넣기]

SA 문서가 곧 프롬프트입니다. 여러분이 공들여 작성한 기능 명세서, API 명세서, ERD가 가장 좋은 프롬프트 재료입니다.

원칙 2: 한 번에 하나의 기능(FN-ID) 단위로 요청하라

나쁜 예시:

예매 도메인 전체 기능 다 만들어줘

좋은 예시:

FN-SEAT-02(좌석 임시 점유)만 먼저 구현해줘.
FN-BK-01(주문 생성)은 다음에 요청할게.

원칙 3: 에러 케이스를 반드시 명시하라

API 명세서에 이미 에러 케이스가 정리되어 있습니다. 반드시 함께 전달하세요.

에러 처리:
- 409 SEAT_ALREADY_HELD: 이미 다른 사용자가 Hold 중
- 409 SEAT_LOCK_FAILED: 분산락 획득 실패 (Fail Fast)
- 429 HOLD_LIMIT_EXCEEDED: 1인 최대 Hold 4석 초과
- 410 HOLD_EXPIRED: Hold TTL 만료 후 결제 시도
- 404 EVENT_NOT_FOUND: 존재하지 않는 이벤트

원칙 4: "왜 이렇게 설계했는지"를 함께 전달하라

ADR 문서의 결정 근거를 함께 전달하면 AI가 설계 의도에 맞는 코드를 생성합니다.

JWT는 AccessToken만 사용해 (RefreshToken 미구현).
이유: 3주 일정에서 블랙리스트 관리 복잡도가 과함.
로그아웃은 클라이언트 토큰 삭제로만 처리해.
(ADR-001 참고)

원칙 5: 기존 코드와의 연결점을 알려줘라

좌석 Hold 서비스를 만들 때:
- 좌석 존재 확인: SeatRepository.findById() (이미 Phase 2에서 만든 것)
- 사용자 인증: SecurityContext에서 userId 추출 (Phase 1에서 만든 JwtAuthenticationFilter)
- Redis 작업: RedisTemplate<String, String> (Phase 1에서 설정한 RedisConfig)
- 에러 처리: CustomException + ErrorCode (Phase 1에서 만든 것)

6. 자주 쓰는 상황별 프롬프트

상황 1: 코드 리뷰 요청

방금 만든 HoldService 코드를 리뷰해줘.
체크포인트:
- 분산락 해제가 finally 블록에서 보장되는지
- Lua Script로 본인 락만 삭제하는지 (UUID 검증)
- Redis 키 TTL이 설계서와 일치하는지
- 예외 발생 시 Hold 카운터(user-hold-count)가 정리되는지

상황 2: 테스트 코드 작성

BookingService.confirmBooking()에 대한 테스트를 작성해줘.

Happy Path:
- Hold 유효 + 결제 성공 → BOOKING CONFIRMED + ACTIVE_BOOKING INSERT

Unhappy Path:
- Hold TTL 만료 후 웹훅 수신 → 예매 실패 처리
- ACTIVE_BOOKING INSERT 시 seat_id 중복 (DuplicateKeyException) → 롤백

동시성 테스트:
- 같은 좌석에 2명이 동시에 confirmBooking 호출 → 1명만 성공

상황 3: 에러 디버깅

아래 에러가 발생했어:

org.springframework.dao.DataIntegrityViolationException:
could not execute statement; SQL [n/a]; constraint [PRIMARY]

상황: Hold 성공한 좌석의 결제 확정(웹훅 수신) 시 발생
코드 위치: BookingService.confirmBooking() → activeBookingRepository.save()

이건 ACTIVE_BOOKING의 seat_id PK 중복 때문인 것 같아.
2차 방어선이 작동한 건데, 왜 1차 방어선(Redis 분산락)을 통과했는지 분석해줘.

상황 4: 시드 데이터 생성

프로젝트 개요서 §6-1의 데이터 볼륨 전략을 참고해서 시드 데이터를 생성해줘.

CommandLineRunner로 구현:
- Venue 1개 (KSPO돔)
- Event 5,000개 (카테고리별 균등 분배: CONCERT, MUSICAL, THEATER, SPORTS)
- 이벤트당 Section 3~6개 (랜덤)
- 섹션당 Seat 100~150석 (랜덤)
- Admin 계정 1개 (admin@ticketflow.io / admin1234)
- 테스트 유저 10명

프로파일: spring.profiles.active=seed 일 때만 실행

7. 팀원별 바이브코딩 가이드

SA 문서의 역할 분담(프로젝트 개요서 §9)에 따라 각 팀원이 요청해야 할 기능 목록입니다.

팀원 A (회원 도메인)

구현 순서:
1. FN-AUTH-01 회원가입 + FN-AUTH-02 로그인 (JWT)
2. FN-AUTH-03 내 정보 조회·수정
3. GET /api/users/me/bookings (내 예매 내역)
4. GET /api/users/me/coupons (내 쿠폰 목록)

함께 전달할 SA 문서: 기능 명세서 §1, API 명세서 §1~2, ERD USER 테이블

팀원 B (이벤트 도메인)

구현 순서:
1. FN-EVT-01 이벤트 등록 (섹션+좌석 자동 생성)
2. FN-SRCH-01 검색 v1 (캐시 없음)
3. FN-SEAT-01 좌석 목록 조회 (상태 판단: ACTIVE_BOOKING + Redis)
4. FN-SRCH-02 검색 v2 (Caffeine 캐시)
5. FN-SRCH-03 인기 검색어 (Redis ZSet)

함께 전달할 SA 문서: 기능 명세서 §2~3, API 명세서 §3~4, ERD EVENT/SECTION/SEAT

팀원 C (예매 도메인)

구현 순서:
1. FN-SEAT-02 좌석 Hold (Lettuce 분산락) ← 동시성 제어 핵심!
2. FN-BK-01 주문 생성 + Mock PG 결제 요청
3. FN-BK-02 웹훅 수신 + 결제 확정 (ACTIVE_BOOKING INSERT)
4. FN-BK-03 예매 취소 (ACTIVE_BOOKING DELETE + 쿠폰 복원)
5. 동시성 테스트 코드 (좌석 Hold 100 Thread 테스트)

함께 전달할 SA 문서: 기능 명세서 §4~5, API 명세서 §5~6, 동시성 제어 설계서 시나리오 A

팀원 D (프로모션 도메인)

구현 순서:
1. FN-CPN-01 쿠폰 등록 (Admin)
2. FN-CPN-02 선착순 쿠폰 발급 (Redis DECR + Lua) ← 동시성 핵심!
3. FN-CPN-03 쿠폰 적용 (예매 플로우 내)
4. 동시성 테스트 (쿠폰 500명 동시 발급)
5. (도전) FN-CHAT-01~03 CS 채팅 WebSocket

함께 전달할 SA 문서: 기능 명세서 §6~7, API 명세서 §7~8, 동시성 제어 설계서 시나리오 B

팀원 E (인프라)

구현 순서:
1. Docker Compose (MySQL + Redis) ← Day 1~2 최우선!
2. Dockerfile (Multi-stage build)
3. GitHub Actions CI/CD 파이프라인
4. AWS 인프라 구성 (EC2, RDS, ElastiCache, ECR, ALB)
5. (도전) DB 인덱스 최적화 (EXPLAIN 분석)

함께 전달할 SA 문서: 인프라 아키텍처 문서 전체, ERD §3 인덱스 설계

8. 프롬프트 체크리스트

기능을 요청하기 전에 아래를 확인하세요.

□ CLAUDE.md가 프로젝트 루트에 있는가?
□ 요청할 기능의 FN-ID를 확인했는가? (기능 명세서)
□ 해당 API의 Request/Response/Error를 정리했는가? (API 명세서)
□ 동시성 민감 기능인가? → 동시성 제어 설계서 해당 시나리오 첨부
□ 이 기능에서 사용하는 Redis 키와 TTL을 명시했는가?
□ 에러 케이스(4xx, 5xx)와 ErrorCode를 명시했는가?
□ 이전에 만든 클래스(엔티티, Repository, 서비스)를 참조하는가? → 연결점 명시
□ 테스트 코드도 함께 요청했는가?

9. 주의사항

하지 말 것:

• "예매 기능 전체 만들어줘" → 한 번에 너무 많으면 품질이 떨어지고 SA 문서와 불일치 발생
• SA 문서 없이 "쿠폰 발급 만들어줘" → AI가 임의 설계하면 ERD, API 명세서와 충돌
• "동시성은 알아서 처리해줘" → Lettuce SETNX인지, Redisson인지, 비관적 락인지 명시 필수
• SEAT 테이블에 status 컬럼 있다고 가정 → ERD v7.0에서 삭제됨! ACTIVE_BOOKING 기반

꼭 할 것:

• SA 문서를 프롬프트의 근거 자료로 첨부하기
• 기능 명세서의 FN-ID 단위로 하나씩 요청하기
• 에러 케이스를 빠짐없이 전달하기
• 동시성 민감 기능은 Redis 키 설계 + 락 전략을 명시하기
• 코드 생성 후 동시성 테스트로 검증하기
• ERD 변경 사항(SEAT.status 삭제, ACTIVE_BOOKING 신규 등)을 AI에게 반드시 알려주기

이번 내일배움캠프 Spring 3기 CH6 과제는 기존 과제들과 달리 요구사항이 명확하게 정의되어 있지 않았다. 채용 과제 형식으로, "왜 이렇게 설계했는가" 를 논리적으로 설명하는 것이 핵심이었다.

구현 요구사항은 아래 4가지였다.

1. 커피 메뉴 목록 조회 API
2. 포인트 충전 API
3. 커피 주문/결제 API
4. 인기 메뉴 조회 API (최근 7일, 상위 3개)

단순 CRUD가 아니라 다수 서버 환경, 동시성, 데이터 일관성을 모두 고려해야 하는 과제였다.

🗂️ 설계 과정

ERD 설계

코딩보다 설계를 먼저 했다. 테이블 구조를 잘못 잡으면 나중에 전체를 뒤집어야 하기 때문이다.

users
- id        BIGINT PK
- point     INT

menus
- id        BIGINT PK
- name      VARCHAR
- price     INT

orders
- id           BIGINT PK
- user_id      BIGINT FK → users.id
- menu_id      BIGINT FK → menus.id
- amount       INT
- created_at   DATETIME

설계 포인트 1: orders.amount에 가격 스냅샷 저장

처음에는 주문 시 menus.price를 그대로 참조하려 했다. 하지만 메뉴 가격이 나중에 변경되면 과거 주문 금액도 바뀌는 문제가 생긴다. 그래서 주문 시점의 가격을 amount 컬럼에 별도 저장하는 방식을 선택했다.

설계 포인트 2: point_histories 테이블 생략

포인트 충전/차감 이력 테이블도 고민했지만, 과제 범위에서는 현재 잔액만 요구하므로 users.point로 단순화했다. 실무라면 반드시 이력 테이블을 추가했을 것이다.

API 명세

동시성 전략 선택

이 과제에서 가장 많이 고민한 부분이 포인트 충전/차감 시 동시 요청 처리였다.

다수의 서버에서 동시에 같은 유저의 포인트를 읽고 수정하면, 각자 읽은 잔액을 기준으로 덮어씌워 실제보다 적게 반영되는 race condition이 발생할 수 있다.

세 가지 전략을 비교했다.

→ 비관적 락 선택

포인트는 금융 데이터에 준하므로 성능보다 정합성이 최우선이라고 판단했다. SELECT ... FOR UPDATE로 트랜잭션이 끝날 때까지 다른 요청을 대기시켜 동시 요청이 와도 순차적으로 처리되도록 보장했다.

세 가지 전략의 트레이드오프를 직접 분석하고 근거를 만드는 과정이 단순 구현보다 훨씬 많은 고민이 필요했다.

🏗️ 프로젝트 구조

도메인 단위로 패키지를 구성했다. 기능이 추가되어도 관련 코드가 한 곳에 모여 있어 유지보수가 쉽다.

src/main/java/
├── domain/
│   ├── user/
│   │   ├── controller/
│   │   ├── service/
│   │   ├── repository/
│   │   ├── entity/
│   │   └── dto/
│   ├── menu/
│   └── order/
└── global/
    ├── exception/
    └── response/

💻 핵심 코드 설명

1. 비관적 락 - UserRepository

// 비관적 락(PESSIMISTIC_WRITE) 적용
// 동시 요청 시 먼저 락을 획득한 트랜잭션이 끝날 때까지 나머지는 대기
@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("SELECT u FROM User u WHERE u.id = :id")
Optional<User> findByIdWithLock(@Param("id") Long id);

일반 findById()를 사용하면 동시 요청 시 동일한 잔액을 읽고 덮어씌우는 문제가 발생한다. @Lock(PESSIMISTIC_WRITE)를 사용하면 DB 레벨에서 SELECT ... FOR UPDATE가 실행되어 트랜잭션이 끝날 때까지 다른 트랜잭션이 해당 행을 수정하지 못하게 막는다.

2. 트랜잭션 처리 - OrderService

@Transactional
public OrderResponseDto order(OrderRequestDto request) {
    // 비관적 락으로 유저 조회 - 동시 주문 시 포인트 차감 순차 처리 보장
    User user = userRepository.findByIdWithLock(request.getUserId())
            .orElseThrow(() -> new CustomException(ErrorCode.USER_NOT_FOUND));

    Menu menu = menuRepository.findById(request.getMenuId())
            .orElseThrow(() -> new CustomException(ErrorCode.MENU_NOT_FOUND));

    // 포인트 차감 - 잔액 부족 시 예외 발생 → 트랜잭션 롤백
    user.use(menu.getPrice());

    // 주문 생성 및 저장
    Order order = Order.of(user, menu);
    orderRepository.save(order);

    // 데이터 플랫폼 전송 (Mock)
    sendToDataPlatform(user.getId(), menu.getId(), order.getAmount());

    return OrderResponseDto.of(order);
}

포인트 차감과 주문 생성을 하나의 트랜잭션으로 묶었다. 중간에 실패하면 전체가 롤백되어 "포인트는 차감됐는데 주문은 생성 안 된" 상황을 방지한다.

3. 인기 메뉴 집계 - OrderRepository

// 최근 7일간 메뉴별 주문 횟수 집계
@Query("SELECT o.menu.id, o.menu.name, COUNT(o) as orderCount " +
       "FROM Order o " +
       "WHERE o.createdAt >= :since " +
       "GROUP BY o.menu.id, o.menu.name " +
       "ORDER BY orderCount DESC")
List<Object[]> findTopMenusSince(@Param("since") LocalDateTime since);

캐싱 없이 매 요청마다 DB에서 직접 집계한다. 과제 요구사항에 "메뉴별 주문 횟수가 정확해야 한다" 고 명시되어 있어 정확성을 최우선으로 판단했다.

✅ API 테스트 (Postman)

메뉴 목록 조회

GET /api/menus 요청 시 DB에 삽입한 메뉴 3개가 정상 응답됐다.

{
  "success": true,
  "data": [
    { "id": 1, "name": "아메리카노", "price": 2000 },
    { "id": 2, "name": "카페라떼", "price": 3000 },
    { "id": 3, "name": "카푸치노", "price": 3500 }
  ],
  "message": null
}

포인트 충전

PATCH /api/users/1/point 요청으로 10,000포인트 충전 성공.

{
  "success": true,
  "data": { "userId": 1, "point": 10000 },
  "message": null
}

주문/결제

POST /api/orders 요청으로 아메리카노 주문 성공. IntelliJ 콘솔에서 데이터 플랫폼 전송 로그도 확인했다.

[DataPlatform] 주문 전송 - userId: 1, menuId: 1, amount: 2000

{
  "success": true,
  "data": {
    "orderId": 1,
    "userId": 1,
    "menuId": 1,
    "menuName": "아메리카노",
    "amount": 2000
  },
  "message": null
}

인기 메뉴 조회

GET /api/menus/popular 요청으로 7일 내 주문 1건인 아메리카노 정상 응답.

{
  "success": true,
  "data": [
    { "menuId": 1, "menuName": "아메리카노", "orderCount": 1 }
  ],
  "message": null
}

🔥 동시성 테스트

비관적 락이 실제로 동작하는지 검증하기 위해 동시성 테스트를 작성했다.

@Test
@DisplayName("동시에 10번 1000원 충전 시 최종 잔액은 10000원이어야 한다")
void concurrentChargeTest() throws InterruptedException {
    int threadCount = 10;
    int chargeAmount = 1000;

    // 여러 스레드가 동시에 작업할 수 있는 스레드 풀 생성
    ExecutorService executorService = Executors.newFixedThreadPool(threadCount);

    // 모든 스레드가 동시에 시작/종료될 때까지 기다리는 동기화 도구
    CountDownLatch latch = new CountDownLatch(threadCount);

    for (int i = 0; i < threadCount; i++) {
        executorService.submit(() -> {
            try {
                userService.charge(userId, new ChargeRequestDto(chargeAmount));
            } finally {
                latch.countDown();
            }
        });
    }

    latch.await();
    executorService.shutdown();

    User user = userRepository.findById(userId).orElseThrow();

    // 비관적 락 없이는 race condition으로 10000원보다 적게 충전될 수 있음
    assertThat(user.getPoint()).isEqualTo(10000);
}

테스트 결과: 1테스트 통과 ✅

10개 스레드가 동시에 충전을 시도했지만 최종 잔액이 정확히 10,000원으로 확인됐다. 비관적 락이 정상적으로 동작해 race condition이 발생하지 않음을 증명했다.

🛠️ 트러블슈팅

1. 서버 재시작마다 데이터가 사라지는 문제

문제: ddl-auto: create 설정으로 인해 앱 실행 시마다 테이블이 새로 생성되어 직접 INSERT한 테스트 데이터가 전부 날아갔다.

ddl-auto 설정 하나가 전체 테스트 흐름을 망가뜨릴 수 있다는 것을 이 과정에서 배웠다. 사소해 보이는 설정도 꼼꼼히 확인하는 습관이 중요하다.

해결: ddl-auto: update로 변경. 테이블 구조만 변경하고 기존 데이터는 유지한다.

# 변경 전
ddl-auto: create

# 변경 후
ddl-auto: update

2. MySQL 접속 불가

문제: ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock'

MySQL이 설치되지 않아 발생한 오류였다.

해결: Homebrew로 MySQL 설치 및 서비스 시작.

brew install mysql
brew services start mysql

3. API 테스트 시 404 응답

문제: 인기 메뉴 조회 API를 추가했는데 Postman에서 계속 404가 떴다.

원인: 코드 수정 후 서버를 재시작하지 않아서 변경 사항이 반영되지 않았다.

해결: IntelliJ에서 서버 재시작 후 정상 응답 확인.

💡 느낀 점

이번 과제를 통해 단순히 기능을 구현하는 것을 넘어서 "왜 이 선택을 했는가" 를 설명할 수 있어야 한다는 것을 배웠다.

특히 가장 어려웠던 부분은 동시성 전략 선택이었다. 비관적 락, 낙관적 락, Redis 분산락 세 가지 중 어떤 것을 선택할지 각각의 장단점과 트레이드오프를 직접 분석하고 근거를 만드는 과정이 단순 구현보다 훨씬 많은 고민을 요구했다.

또한 ddl-auto 설정 실수처럼 사소해 보이는 설정 하나가 전체 테스트 흐름을 망가뜨릴 수 있다는 것도 직접 경험하며 배웠다.

채용 과제 특성상 정답이 없기 때문에 설계의 논리와 트레이드오프를 명확히 설명하는 연습이 중요하다는 것을 느꼈고, 앞으로 코드를 짤 때도 "왜 이렇게 짰는가" 를 항상 생각하는 습관을 들여야겠다.

문제 상황

할 일 저장 API를 호출했을 때 아래와 같은 에러가 발생했다.

Connection is read-only. Queries leading to data modification are not allowed

즉, 저장 API인데 실제로는 데이터베이스가 “현재 읽기 전용 상태라서 insert를 허용할 수 없다”고 판단한 것이다.

여기서 중요한 건, 단순히 저장이 안 된다는 사실보다 왜 저장 메서드가 읽기 전용 트랜잭션 안에서 실행되고 있는지를 찾는 것이었다.

원인 분석

TodoService 클래스에는 다음과 같이 클래스 레벨에 @Transactional(readOnly = true) 가 선언되어 있었다.

@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class TodoService {
    ...
}

이 설정은 클래스 내부의 모든 메서드를 기본적으로 “조회 전용 트랜잭션”으로 동작하게 만든다.

그런데 saveTodo() 메서드는 실제로 todoRepository.save() 를 호출하는 쓰기 작업이다.

즉 구조는 이랬다.

• 클래스 전체는 조회 전용
• 저장 메서드는 그 영향을 그대로 받음
• 저장 시점에 insert 발생
• DB가 쓰기 작업 차단

왜 이런 설정이 문제였을까

readOnly = true 는 조회 전용 작업에 적합하다. 스프링과 JPA는 이 설정을 보고 “이번 트랜잭션은 변경이 아니라 조회가 목적”이라고 해석한다.

이 설정의 장점은 다음과 같다.

• 조회 의도를 명확히 드러낼 수 있다
• 불필요한 변경 감지를 줄일 수 있다
• 실수로 쓰기 작업이 섞이는 것을 방지하는 데 도움이 된다

하지만 저장/수정/삭제가 필요한 메서드에 그대로 적용되면, 오히려 지금처럼 오류의 원인이 된다.

즉 이 문제는 단순한 문법 문제가 아니라, 조회 트랜잭션과 쓰기 트랜잭션의 목적이 다르다는 점을 코드로 구분하지 못했기 때문에 발생한 문제였다.

해결 방법

클래스 전체의 조회 전용 트랜잭션은 유지하되, 저장 메서드인 saveTodo() 에만 일반 @Transactional 을 다시 선언해 쓰기 트랜잭션으로 오버라이드했다.

@Transactional
public TodoSaveResponse saveTodo(AuthUser authUser, TodoSaveRequest todoSaveRequest) {
    User user = User.fromAuthUser(authUser);

    String weather = weatherClient.getTodayWeather();

    Todo newTodo = new Todo(
            todoSaveRequest.getTitle(),
            todoSaveRequest.getContents(),
            weather,
            user
    );
    Todo savedTodo = todoRepository.save(newTodo);

    return new TodoSaveResponse(
            savedTodo.getId(),
            savedTodo.getTitle(),
            savedTodo.getContents(),
            weather,
            new UserResponse(user.getId(), user.getEmail())
    );
}

테스트

POST /todos

요청 예시:

{
  "title": "스프링 과제",
  "contents": "Transactional 오류 해결"
}

확인 포인트는 다음과 같았다.

• 저장 요청 시 더 이상 read-only 관련 예외가 발생하지 않는지
• 정상적으로 Todo가 저장되는지
• 응답에 id, title, contents, weather, user 정보가 포함되는지

3. weather / 수정일 기간 기반 Todo 검색 조건 추가

문제 상황

기존 Todo 목록 조회는 단순히 전체 목록을 수정일 기준 내림차순으로 조회하는 구조였다. 하지만 요구사항은 다음과 같았다.

• weather 조건으로 검색 가능해야 한다
• 수정일 기준 기간 검색이 가능해야 한다
• 각 조건은 있을 수도 있고 없을 수도 있다

즉, 검색 조건이 고정된 것이 아니라 선택적으로 적용되는 동적 검색 구조가 필요했다.

기존 한계

기존 컨트롤러와 서비스는 page, size만 받아 전체 목록을 조회하고 있었다.

@GetMapping("/todos")
public ResponseEntity<Page<TodoResponse>> getTodos(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "10") int size
) {
    return ResponseEntity.ok(todoService.getTodos(page, size));
}

이 구조로는 사용자가 다음과 같은 요청을 보내도 처리할 수 없었다.

• 특정 날씨만 검색
• 특정 날짜 이후만 검색
• 특정 기간만 검색
• weather와 기간을 동시에 검색

해결 방향

이번 문제의 핵심은 “조건이 없으면 무시하고, 값이 있으면 필터로 적용”하는 것이다. 그래서 컨트롤러에서 먼저 optional 파라미터를 받도록 바꾸고, Repository에서는 JPQL의 null 조건 패턴을 사용했다.

컨트롤러 수정

@GetMapping("/todos")
public ResponseEntity<Page<TodoResponse>> getTodos(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(required = false) String weather,
        @RequestParam(required = false)
        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)
        LocalDateTime modifiedAtFrom,
        @RequestParam(required = false)
        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)
        LocalDateTime modifiedAtTo
) {
    return ResponseEntity.ok(todoService.getTodos(page, size, weather, modifiedAtFrom, modifiedAtTo));
}

여기서 required = false 가 핵심이다. 이렇게 해야 사용자가 값을 보내지 않아도 null로 받을 수 있고, “조건이 없는 검색”도 안전하게 처리할 수 있다.

Repository JPQL

@Query(value = "SELECT t FROM Todo t " +
        "LEFT JOIN FETCH t.user " +
        "WHERE (:weather IS NULL OR t.weather = :weather) " +
        "AND (:modifiedAtFrom IS NULL OR t.modifiedAt >= :modifiedAtFrom) " +
        "AND (:modifiedAtTo IS NULL OR t.modifiedAt <= :modifiedAtTo) " +
        "ORDER BY t.modifiedAt DESC",
        countQuery = "SELECT COUNT(t) FROM Todo t " +
                "WHERE (:weather IS NULL OR t.weather = :weather) " +
                "AND (:modifiedAtFrom IS NULL OR t.modifiedAt >= :modifiedAtFrom) " +
                "AND (:modifiedAtTo IS NULL OR t.modifiedAt <= :modifiedAtTo)")
Page<Todo> searchTodos(
        @Param("weather") String weather,
        @Param("modifiedAtFrom") LocalDateTime modifiedAtFrom,
        @Param("modifiedAtTo") LocalDateTime modifiedAtTo,
        Pageable pageable
);

이 JPQL의 핵심 원리

예를 들어 이 조건:

(:weather IS NULL OR t.weather = :weather)

은 이렇게 해석된다.

• weather가 null이면 → 이 조건은 항상 true
• weather 값이 있으면 → 해당 날씨만 조회

즉 값이 없으면 조건을 무시하는 패턴이다.

이 방식은 날짜 조건에도 똑같이 적용된다.

테스트

GET /todos?page=1&size=10

GET /todos?page=1&size=10&weather=Sunny

GET /todos?page=1&size=10&modifiedAtFrom=2026-04-01T00:00:00&modifiedAtTo=2026-04-06T23:59:59

GET /todos?page=1&size=10&weather=Sunny&modifiedAtFrom=2026-04-01T00:00:00&modifiedAtTo=2026-04-06T23:59:59

배운 점

동적 검색은 “조건이 많다”가 핵심이 아니라, 조건이 없을 때도 자연스럽게 동작해야 한다 가 핵심이라는 점을 배웠다.

그리고 JPQL에서도 null 조건 패턴을 적절히 활용하면 QueryDSL 없이도 꽤 유연한 검색을 구현할 수 있다는 걸 확인했다.

6. Todo 생성 시 작성자를 담당자로 자동 등록하기 - JPA Cascade

문제 상황

Todo를 새로 생성할 때, 그 Todo를 만든 사용자가 담당자로 자동 등록되어야 했다.

코드를 확인해보니 Todo 생성자 안에는 이미 다음과 같은 코드가 있었다.

this.managers.add(new Manager(user, this));

즉, 설계 의도 자체는 이미 존재했다. 문제는 리스트에 추가하는 것과 DB에 저장되는 것은 다르다는 점이었다.

원인 분석

JPA에서 연관 객체를 컬렉션에 넣는다고 해서 자동으로 DB에 저장되지는 않는다.

다시 말해,

• 메모리 상에서 관계를 연결하는 것
• 실제로 DB에 insert 되는 것

은 다른 단계다.

이번 구조에서는:

• 부모: Todo
• 자식: Manager

였고, Todo를 저장할 때 Manager도 함께 저장되게 하려면 영속성 전이(cascade) 가 필요했다.

해결 방법

Todo 엔티티의 managers 연관관계에 CascadeType.PERSIST 를 추가했다.

@OneToMany(mappedBy = "todo", cascade = CascadeType.PERSIST)
private List<Manager> managers = new ArrayList<>();

그리고 생성자에서는 작성자를 담당자로 추가하도록 유지했다.

public Todo(String title, String contents, String weather, User user) {
    this.title = title;
    this.contents = contents;
    this.weather = weather;
    this.user = user;
    this.managers.add(new Manager(user, this));
}

왜 PERSIST를 선택했는가

이번 요구사항의 핵심은 “Todo 생성 시 함께 저장”이다. 즉 저장 시점의 전이가 필요했기 때문에 CascadeType.PERSIST 가 가장 의도에 맞았다.

ALL 도 사용할 수는 있지만, 그 경우 저장/수정/삭제까지 모두 전이되어 범위가 넓어진다. 이번 요구사항은 “자동 등록”이라는 생성 시점의 동작이 중심이었기 때문에 PERSIST 가 더 명확한 선택이었다.

테스트

POST /todos

그 다음

GET /todos/{todoId}/managers

확인 포인트:

• Todo 생성 직후 managers 목록에 작성자가 포함되어 있는지
• 별도의 담당자 등록 API를 호출하지 않았는데도 자동 등록이 되었는지

7. 댓글 조회 시 N+1 문제 해결

문제 상황

GET /todos/{todoId}/comments 호출 시 N+1 문제가 발생하고 있었다.

댓글 목록 조회 자체는 한 번에 수행되지만, DTO를 만드는 과정에서 각 댓글 작성자(User)를 꺼낼 때마다 추가 쿼리가 발생하는 구조였다.

N+1이 발생하는 이유

Comment 엔티티는 다음과 같이 user 를 LAZY 로딩으로 가지고 있었다.

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "user_id", nullable = false)
private User user;

그리고 서비스에서는 다음과 같이 반복문에서 comment.getUser() 를 호출하고 있었다.

for (Comment comment : commentList) {
    User user = comment.getUser();
    ...
}

이 경우 댓글 목록을 처음 조회할 때는 Comment 만 가져오고, 이후 각 댓글의 user 가 필요해질 때마다 추가 쿼리가 발생한다.

즉 댓글이 10개면:

• 댓글 조회 1번
• 사용자 조회 10번

총 11번 쿼리가 나갈 수 있다. 이게 전형적인 N+1 문제다.

해결 방법

Repository의 조회 쿼리를 단순 JOIN 에서 JOIN FETCH 로 변경했다.

기존:

@Query("SELECT c FROM Comment c JOIN c.user WHERE c.todo.id = :todoId")

수정 후:

@Query("SELECT c FROM Comment c JOIN FETCH c.user WHERE c.todo.id = :todoId")
List<Comment> findByTodoIdWithUser(@Param("todoId") Long todoId);

왜 JOIN FETCH가 핵심인가

단순 JOIN 은 SQL 레벨에서 조인은 일어나더라도, JPA가 연관 엔티티를 즉시 로딩된 객체로 다 채워준다는 보장이 없다.

반면 FETCH JOIN 은 연관 엔티티까지 한 번에 가져오라는 의도를 명확히 전달한다.

즉 이 변경 이후에는 서비스에서 comment.getUser() 를 호출하더라도 추가 쿼리가 발생하지 않는다.

테스트

GET /todos/{todoId}/comments

이 단계에서는 응답 자체뿐 아니라, 콘솔 SQL 로그도 함께 확인했다.

확인 포인트:

• 댓글과 작성자 정보를 함께 가져오는 쿼리 1번만 실행되는지
• 댓글 수만큼 user 조회 쿼리가 추가로 발생하지 않는지

배운 점

이번 문제는 “성능 최적화는 나중에 하는 것”이 아니라, 엔티티 연관관계를 어떻게 조회하느냐 자체가 성능과 직결된다는 걸 체감하게 해줬다.

LAZY 로딩은 기본 전략으로 매우 유용하지만, “어차피 지금 반드시 함께 사용할 연관 객체”라면 fetch join을 통해 한 번에 가져오는 것이 훨씬 효율적이다.

8. JPQL 기반 Todo 단건 조회를 QueryDSL로 전환

문제 상황

기존 findByIdWithUser 는 문자열 JPQL 기반으로 작성되어 있었다.

@Query("SELECT t FROM Todo t LEFT JOIN FETCH t.user WHERE t.id = :todoId")
Optional<Todo> findByIdWithUser(@Param("todoId") Long todoId);

이 방식도 동작은 하지만, 문자열 기반 쿼리는 다음과 같은 한계가 있다.

• 필드명 변경 시 컴파일 단계에서 잡히지 않는다
• 오타가 있어도 런타임에서야 문제가 드러난다
• 쿼리가 복잡해질수록 유지보수성이 떨어진다

과제에서는 이를 QueryDSL로 바꾸고, 동시에 user 를 함께 조회해 N+1 성격의 문제도 막도록 요구했다.

QueryDSL 적용 과정

먼저 build.gradle 에 QueryDSL 관련 의존성을 추가하고, JPAQueryFactory 를 빈으로 등록했다.

그리고 TodoRepositoryCustom 과 TodoRepositoryImpl 구조를 만들어 기존 JPQL 메서드를 QueryDSL 구현체로 옮겼다.

QueryDSL 구현 코드

@Override
public Optional<Todo> findByIdWithUser(Long todoId) {
    QTodo todo = QTodo.todo;
    QUser user = QUser.user;

    Todo result = jpaQueryFactory
            .selectFrom(todo)
            .leftJoin(todo.user, user).fetchJoin()
            .where(todo.id.eq(todoId))
            .fetchOne();

    return Optional.ofNullable(result);
}

핵심 포인트

여기서 중요한 건 QueryDSL로 바꾼 것 자체보다도, 여전히 fetchJoin() 을 유지했다는 점이다.

즉 이번 단계는 단순히 문법을 JPQL에서 QueryDSL로 옮긴 것이 아니라,

• 타입 안전한 쿼리 작성
• 연관 엔티티 한 번에 조회

이 두 가지를 동시에 만족하도록 구성한 작업이었다.

QueryDSL 적용 중 겪은 트러블슈팅

처음에는 QTodo, QUser 를 찾지 못하는 문제가 발생했다. 원인은 QueryDSL Q클래스가 자동 생성되지 않았기 때문이었다.

이 문제를 해결하기 위해 다음을 확인했다.

• QueryDSL 의존성 추가 여부
• annotation processor 설정
• compileJava 수행 여부
• generated source 경로 인식 여부

이 과정을 통해 QueryDSL은 단순히 코드만 작성한다고 되는 게 아니라, 빌드 설정과 코드 생성까지 함께 맞아야 동작하는 구조라는 점을 체감했다.

테스트

GET /todos/{todoId}

확인 포인트:

• Todo 단건 조회가 정상 동작하는지
• 연관된 user 정보가 함께 응답되는지
• QueryDSL 적용 후 기존 기능이 깨지지 않았는지

배운 점

QueryDSL은 “문자열 대신 자바 코드로 쿼리를 쓴다”는 점에서 유지보수성이 훨씬 높았다. 특히 복잡한 조건이나 동적 쿼리로 갈수록 JPQL보다 훨씬 확장성이 좋다는 걸 느꼈다.

2. User nickname 컬럼 추가 및 JWT claim 확장

문제 상황

기존 JWT에는 email과 userRole만 들어 있었고, 프론트엔드가 사용자 닉네임을 바로 사용할 수 없는 상태였다.

요구사항은 다음과 같았다.

• User 테이블에 nickname 컬럼 추가
• JWT 안에 nickname 포함
• 프론트엔드가 JWT에서 nickname을 꺼내 화면에 표시 가능해야 함

해결 방향

이 문제는 단순히 필드 하나를 추가하는 것이 아니었다. nickname 이 다음 흐름 전체를 타고 전달되어야 했다.

• 회원가입 요청
• User 엔티티 저장
• JWT 생성
• JWT 파싱
• 인증 객체(AuthUser)

즉, DB -> JWT -> 인증 흐름 전체를 연결하는 작업이었다.

주요 수정 포인트

User 엔티티

private String nickname;

SignupRequest

@NotBlank
private String nickname;

JwtUtil

.claim("nickname", nickname)

AuthService

회원가입/로그인 시 토큰 생성 메서드에 nickname 전달

String bearerToken = jwtUtil.createToken(
        user.getId(),
        user.getEmail(),
        user.getNickname(),
        user.getUserRole()
);

AuthUser

private final String nickname;

트러블슈팅 - 서버 실행 실패

nickname 작업 후 서버 실행 시 다음 오류가 발생했다.

Could not resolve placeholder 'jwt.secret.key'

처음에는 nickname 관련 수정 문제라고 생각할 수도 있었지만, 실제 원인은 전혀 달랐다.

JwtUtil 에서 다음 값을 주입받고 있었는데,

@Value("${jwt.secret.key}")
private String secretKey;

실행 환경에 jwt.secret.key 설정이 없어서 빈 생성이 실패한 것이었다.

즉 이번 단계의 핵심 트러블슈팅은 “내가 방금 수정한 코드가 문제일 것”이라는 추측보다, 로그에서 실제 root cause를 정확히 읽는 것이 더 중요하다는 점을 보여줬다.

테스트

POST /auth/signup

요청 예시:

{
  "email": "test@test.com",
  "password": "1234",
  "nickname": "jimin",
  "userRole": "USER"
}

POST /auth/signin

확인 포인트:

• 회원가입 시 nickname이 저장되는지
• 로그인 후 발급된 JWT payload에 nickname이 포함되는지
• 이후 인증이 필요한 API에서 사용자 정보 흐름이 깨지지 않는지

배운 점

JWT는 단순히 로그인 여부만 판단하는 토큰이 아니라, 클라이언트가 자주 사용할 사용자 정보를 함께 담아 전달하는 수단이 될 수 있다.

다만 claim 하나를 추가하는 것만으로 끝나는 것이 아니라, DB 저장, 토큰 생성, 토큰 파싱, 인증 객체 반영까지 모두 이어줘야 전체 흐름이 완성된다.

4. Todo 단건 조회 실패 컨트롤러 테스트 수정

문제 상황

todo_단건_조회_시_todo가_존재하지_않아_예외가_발생한다() 테스트가 실패하고 있었다.

문제를 확인해보니 서비스는 예외를 던지는데, 테스트는 성공 응답을 기대하고 있었다.

즉, 예외 상황을 검증해야 하는 테스트인데도 다음과 같이 200 OK 를 기대하고 있었다.

.andExpect(status().isOk())
.andExpect(jsonPath("$.status").value(HttpStatus.OK.name()))
.andExpect(jsonPath("$.code").value(HttpStatus.OK.value()))

왜 이게 문제였을까

컨트롤러 테스트에서 중요한 것은 “서비스 내부에서 예외가 발생했는가”만이 아니다.

더 중요한 건 그 예외가 Global Exception Handler를 거쳐 어떤 HTTP 응답으로 변환되는가 이다.

즉 이 테스트는 “Todo가 없을 때 서비스가 예외를 던진다”를 검증하는 테스트가 아니라, “그 예외가 웹 계층에서 어떤 응답 형태로 내려가는가”를 검증해야 했다.

해결 방법

기대값을 200 OK 에서 400 Bad Request 로 수정했다.

mockMvc.perform(get("/todos/{todoId}", todoId))
        .andExpect(status().isBadRequest())
        .andExpect(jsonPath("$.status").value(HttpStatus.BAD_REQUEST.name()))
        .andExpect(jsonPath("$.code").value(HttpStatus.BAD_REQUEST.value()))
        .andExpect(jsonPath("$.message").value("Todo not found"));

또한 AuthUser 생성자 구조가 nickname 추가로 변경되었기 때문에, 테스트 코드도 실제 구조에 맞게 함께 수정했다.

배운 점

컨트롤러 테스트는 서비스 로직 자체를 다시 검증하는 것이 아니라, 서비스 결과가 HTTP 응답으로 어떻게 표현되는지 검증하는 레이어라는 점을 다시 확인할 수 있었다.

5. 관리자 권한 변경 API에 AOP 올바르게 적용하기

문제 상황

과제 요구사항은 UserAdminController.changeUserRole() 메서드가 실행되기 전에 관리자 접근 로그가 남아야 한다는 것이었다.

하지만 기존 Aspect는 전혀 다른 메서드에 걸려 있었고, 실행 시점도 잘못되어 있었다.

기존 코드:

@After("execution(* org.example.expert.domain.user.controller.UserController.getUser(..))")
public void logAfterChangeUserRole(JoinPoint joinPoint) {
    ...
}

여기에는 두 가지 문제가 있었다.

• 대상 메서드가 UserController.getUser() 였다
• 실행 시점이 @After 였다

즉 요구사항은 “권한 변경 메서드 실행 전 로그”인데, 실제 코드는 “다른 메서드 실행 후 로그”였던 것이다.

해결 방법

포인트컷과 실행 시점을 모두 수정했다.

@Before("execution(* org.example.expert.domain.user.controller.UserAdminController.changeUserRole(..))")
public void logBeforeChangeUserRole(JoinPoint joinPoint) {
    String userId = String.valueOf(request.getAttribute("userId"));
    String requestUrl = request.getRequestURI();
    LocalDateTime requestTime = LocalDateTime.now();

    log.info("Admin Access Log - User ID: {}, Request Time: {}, Request URL: {}, Method: {}",
            userId, requestTime, requestUrl, joinPoint.getSignature().getName());
}

핵심 개념

AOP는 두 가지가 정확해야 한다.

• 어디에 적용할 것인가 → 포인트컷
• 언제 실행할 것인가 → Before / After / Around

이번 문제는 이 둘이 모두 어긋나 있었기 때문에 의도한 동작이 전혀 일어나지 않았다.

테스트

PATCH /admin/users/{userId}

요청 예시:

{
  "userRole": "ADMIN"
}

추가로 로그 콘솔 확인

확인 포인트:

• changeUserRole() 호출 전에 로그가 찍히는지
• request URL, userId, method가 올바르게 남는지

배운 점

AOP는 “붙이면 된다”가 아니라, 정확한 대상과 정확한 시점을 지정해야 의도한 공통 기능이 동작한다는 걸 확실히 느꼈다.

9. Filter + ArgumentResolver 구조를 Spring Security로 전환

문제 상황

기존 인증 구조는 다음과 같았다.

• JwtFilter 가 JWT를 파싱
• request attribute에 userId, email, userRole 등을 저장
• AuthUserArgumentResolver 가 request에서 값을 꺼내 @Auth AuthUser 로 주입

이 구조도 동작은 했지만, Spring Security 없이 인증/인가를 거의 수동으로 구현한 방식이었다.

특히 /admin 권한 체크도 직접 if문으로 처리하고 있었다.

왜 Spring Security로 바꿔야 했는가

과제 요구사항은 명확했다.

• 기존 Filter / ArgumentResolver 기반 구조를 Spring Security로 전환
• JWT 기반 인증은 유지
• 관리자 권한 기능도 유지

즉 핵심은 “JWT를 버리는 것”이 아니라, JWT 인증 흐름을 Spring Security 표준 방식 안으로 옮기는 것이었다.

변경 전 구조

• JwtFilter
• FilterConfig
• AuthUserArgumentResolver
• WebConfig
• @Auth AuthUser

변경 후 구조

• JwtAuthenticationFilter
• SecurityConfig
• SecurityContext
• @AuthenticationPrincipal AuthUser

핵심 전환 포인트

기존에는 request attribute를 통해 사용자 정보를 넘겼다.

하지만 Spring Security에서는 인증 성공 시 SecurityContextHolder 에 Authentication 을 저장하고, 컨트롤러에서는 @AuthenticationPrincipal 로 principal을 받아 사용한다.

즉 사용자 정보의 전달 통로 자체가 바뀐 것이다.

JwtAuthenticationFilter

AuthUser authUser = new AuthUser(userId, email, nickname, userRole);

UsernamePasswordAuthenticationToken authentication =
        new UsernamePasswordAuthenticationToken(
                authUser,
                null,
                List.of(new SimpleGrantedAuthority(userRole.name()))
        );

SecurityContextHolder.getContext().setAuthentication(authentication);

SecurityConfig

.authorizeHttpRequests(auth -> auth
        .requestMatchers("/auth/**").permitAll()
        .requestMatchers("/admin/**").hasAuthority(UserRole.ADMIN.name())
        .anyRequest().authenticated()
)
.addFilterBefore(new JwtAuthenticationFilter(jwtUtil), UsernamePasswordAuthenticationFilter.class);

이 설정을 통해

• /auth/** 는 누구나 접근 가능
• /admin/** 는 ADMIN 권한 필요
• 나머지 요청은 인증 필요

라는 정책을 Spring Security 설정으로 선언할 수 있었다.

컨트롤러 변경

기존:

@Auth AuthUser authUser

변경 후:

@AuthenticationPrincipal AuthUser authUser

이 과정에서 기존 AuthUserArgumentResolver, FilterConfig, WebConfig 는 더 이상 필요 없어져 제거했다.

트러블슈팅

1) Spring Security로 바꿨는데 Resolver를 유지하려 했던 문제

처음에는 기존 AuthUserArgumentResolver 를 살려두고 SecurityContext 와 섞어 쓰는 방향도 고민했지만, 그렇게 되면 구조가 이중화된다.

즉,

• SecurityContext를 이미 쓰는데
• 다시 Resolver로 래핑하는 불필요한 단계

가 생긴다.

결국 가장 깔끔한 방향은 Resolver 자체를 제거하고 @AuthenticationPrincipal 로 통일하는 것이었다.

2) WebConfig 에서 이미 삭제한 Resolver를 계속 등록하고 있던 문제

WebConfig 가 여전히 AuthUserArgumentResolver 를 등록하려 해서 실행 에러가 발생했다.

이 문제는 예전 구조의 흔적을 완전히 제거하지 못해 생긴 문제였다. 결국 Spring Security 전환은 새 코드 추가만이 아니라, 기존 수동 인증 구조의 흔적을 함께 지우는 작업이라는 점을 배웠다.

테스트

(Postman으로 테스트 한 사진 삽입) POST /auth/signin

토큰 발급 후

(Postman으로 테스트 한 사진 삽입) POST /todos Authorization 헤더에 Bearer 토큰 포함

(Postman으로 테스트 한 사진 삽입) PATCH /admin/users/{userId} 일반 USER 토큰으로 요청한 경우 403 확인

(Postman으로 테스트 한 사진 삽입) PATCH /admin/users/{userId} ADMIN 토큰으로 요청한 경우 정상 처리 확인

배운 점

Spring Security의 핵심은 보안 라이브러리 추가가 아니었다.

정말 중요한 건 다음 두 가지였다.

• 사용자 인증 정보를 request attribute가 아니라 SecurityContext 로 관리하는 것
• 권한 정책을 코드 곳곳의 if문이 아니라, 설정으로 선언하는 것

즉 이번 전환은 단순 리팩토링이 아니라, 인증/인가 구조를 스프링 표준 방식으로 재설계한 작업에 가까웠다.

이번 과제를 통해 느낀 점

이번 과제는 단순히 기능 개수를 채우는 과제가 아니었다. 오히려 이미 존재하는 코드를 읽고, 그 안에 숨어 있는 설계 의도와 문제점을 파악하고, 스프링이 제공하는 기능들을 “왜 이럴 때 쓰는가”까지 연결해보는 과정이었다.

특히 다음 개념들을 실제 문제와 함께 연결해서 이해할 수 있었다.

• @Transactional(readOnly = true) 와 쓰기 트랜잭션 구분
• JPQL의 optional 조건 검색
• JPA Cascade를 통한 영속성 전이
• LAZY 로딩과 fetch join, N+1 문제
• QueryDSL의 장점과 설정 과정
• JWT claim 확장과 인증 흐름 연결
• 컨트롤러 테스트에서 HTTP 응답 검증의 의미
• AOP의 포인트컷과 실행 시점
• Spring Security 기반 인증/인가 구조 전환

무엇보다 가장 크게 느낀 점은, 문제를 해결하는 것과 문제를 설명할 수 있는 것은 다르다는 것이다.

이번 과제에서는 각 기능을 구현할 때마다 “왜 이렇게 해야 하는가”, “이전 구조는 왜 한계가 있었는가”, “스프링이 제공하는 기능은 어떤 원리로 동작하는가” 를 같이 정리하려고 노력했고, 그 과정이 오히려 가장 큰 공부가 되었다.

테스트에 사용한 API 정리

1번

• POST /todos

3번

• GET /todos?page=1&size=10
• GET /todos?page=1&size=10&weather=Sunny
• GET /todos?page=1&size=10&modifiedAtFrom=2026-04-01T00:00:00&modifiedAtTo=2026-04-06T23:59:59
• GET /todos?page=1&size=10&weather=Sunny&modifiedAtFrom=2026-04-01T00:00:00&modifiedAtTo=2026-04-06T23:59:59

6번

• POST /todos
• GET /todos/{todoId}/managers

7번

• GET /todos/{todoId}/comments

8번

• GET /todos/{todoId}

2번

• POST /auth/signup
• POST /auth/signin

5번

• PATCH /admin/users/{userId}

9번

• POST /auth/signin

• POST /todos

• PATCH /admin/users/{userId}

  • USER 토큰으로 실패
  • ADMIN 토큰으로 성공

회고

이번 개인 과제 기간 동안 개인 일정으로 인해 약 2일 정도 학습과 과제 진행에 집중하지 못했던 점이 아쉬움으로 남는다. 그로 인해 전체 과제를 몰아서 진행하게 되었고, 과정이 다소 촉박하게 흘러갔던 부분이 있었다.

하지만 그럼에도 불구하고 이번 과제를 통해 단순히 기능을 구현하는 것을 넘어, 각 기술을 왜 사용하는지, 그리고 어떤 상황에서 필요한지까지 깊이 있게 고민해볼 수 있었던 시간이었다.

특히 트랜잭션, JPA 연관관계, N+1 문제, QueryDSL, 그리고 Spring Security까지 실제 문제 상황과 연결하여 학습할 수 있었던 점이 의미있었다.

이번 경험을 통해 미리 계획하고 꾸준히 진행하는 것이 얼마나 중요한지 다시 한번 느끼게 되었고, 앞으로는 일정 관리까지 포함한 개발 습관을 개선해 나가고자 한다.

이번 단계에서는 Spring Boot 애플리케이션을 Docker 컨테이너로 실행하고, GitHub Actions를 이용해 코드 Push 시 자동으로 서버에 배포되는 CI/CD 파이프라인을 구축하는 것을 목표로 했다.

이 과정을 통해

“로컬에서는 되는데 서버에서는 안 되는 문제”

를 해결하고, 코드 변경 → 자동 배포 환경을 만들 수 있다.

전체 배포 구조

이번 단계에서 구성한 배포 흐름은 다음과 같다.

Developer
   │
   │ git push
   ▼
GitHub Repository
   │
   ▼
GitHub Actions
   │
   │ Gradle Build
   │ Docker Image Build
   ▼
Docker Hub
   │
   │ docker pull
   ▼
AWS EC2
   │
   ▼
Docker Container 실행

즉,

코드 Push → 자동 빌드 → Docker 이미지 생성 → DockerHub 업로드 → EC2 자동 배포

가 이루어지는 CI/CD 자동화 파이프라인이다.

Docker 도입

기존에는 EC2 서버에서 다음과 같이 직접 애플리케이션을 실행했다.

java -jar cloud-architecture-0.0.1-SNAPSHOT.jar

하지만 이 방식에는 다음과 같은 문제가 있다.

• 서버 환경(Java 버전 등)에 의존적
• 실행 환경 재현이 어려움
• 자동 배포 환경 구축이 어려움

이를 해결하기 위해 Docker 컨테이너 환경으로 애플리케이션을 패키징하였다.

Dockerfile 작성

애플리케이션을 Docker 이미지로 만들기 위해 Dockerfile을 작성했다.

FROM eclipse-temurin:17-jre

WORKDIR /app

COPY build/libs/cloud-architecture-0.0.1-SNAPSHOT.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app/app.jar", "--spring.profiles.active=prod"]

설정 설명

GitHub Actions CI/CD 구축

코드를 push 할 때마다 자동으로 배포되도록 GitHub Actions를 이용해 CI/CD 파이프라인을 구성했다.

워크플로우 파일 위치

.github/workflows/deploy.yml

GitHub Actions Workflow

name: Deploy to EC2 with Docker

on:
  push:
    branches:
      - main

jobs:
  build-test-push-deploy:
    runs-on: ubuntu-latest

    steps:

      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 17

      - name: Build with Gradle
        run: ./gradlew clean build -x test

      - name: Login to DockerHub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build Docker image
        run: docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/cloud-architecture .

      - name: Push Docker image
        run: docker push ${{ secrets.DOCKERHUB_USERNAME }}/cloud-architecture

      - name: Deploy to EC2
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ${{ secrets.EC2_USER }}
          key: ${{ secrets.EC2_SSH_KEY }}
          script: |
            sudo docker pull ${{ secrets.DOCKERHUB_USERNAME }}/cloud-architecture
            sudo docker stop cloud-architecture || true
            sudo docker rm cloud-architecture || true
            sudo docker run -d -p 8080:8080 --name cloud-architecture ${{ secrets.DOCKERHUB_USERNAME }}/cloud-architecture

자동 배포 확인

코드를 수정 후 GitHub에 Push하면

git push origin main

GitHub Actions가 자동으로 실행된다.

GitHub Actions 실행 결과

EC2 Docker 컨테이너 확인

EC2 서버 접속 후

sudo docker ps

서버 Health Check

http://EC2_PUBLIC_IP:8080/actuator/health

응답

{
  "status": "UP"
}

트러블슈팅

이번 단계에서는 CI/CD 구축 과정에서 여러 가지 문제를 겪었고 이를 해결하는 과정이 있었다.

GitHub Actions 테스트 실패

문제

GitHub Actions 빌드 과정에서 다음과 같은 오류가 발생했다.

contextLoads() FAILED
SdkClientException

원인

테스트 실행 시 AWS S3 Client 빈 생성 과정에서 자격 증명을 찾지 못해 실패했다.

GitHub Actions 환경에는 AWS 자격 증명이 존재하지 않기 때문이다.

해결

CI 과정에서는 테스트를 제외하도록 설정했다.

run: ./gradlew clean build -x test

Docker 컨테이너 실행 실패

문제

배포 시 다음 오류가 발생했다.

bind: address already in use

원인

이전에 EC2에서 실행 중이던

java -jar cloud-architecture.jar

프로세스가 8080 포트를 점유하고 있었기 때문이었다.

해결

기존 Java 프로세스를 종료 후 Docker 컨테이너를 실행하였다.

kill -9 {PID}

결과

최종적으로 다음 구조의 자동 배포 환경을 구축하였다.

Git Push
 ↓
GitHub Actions
 ↓
Gradle Build
 ↓
Docker Image Build
 ↓
DockerHub Push
 ↓
EC2 Docker Pull
 ↓
컨테이너 실행

이제 코드 수정 후 GitHub에 Push만 하면 자동으로 서버에 반영된다.

느낀 점

이번 단계에서는 단순히 애플리케이션을 배포하는 것을 넘어

• Docker 기반 컨테이너 환경
• GitHub Actions CI/CD 자동화
• AWS EC2 서버 배포

를 직접 구축하면서 실제 서비스 배포 과정과 매우 유사한 경험을 할 수 있었다.

특히 다양한 배포 오류를 해결하는 과정에서 클라우드 환경과 CI/CD 파이프라인에 대한 이해도를 크게 높일 수 있었다.

최종적으로 필수 과제를 끝냈을 때의 구조는 아래와 같다.

로컬 개발 단계에서는

• Spring Boot
• H2

로 빠르게 기능을 구현했고,

운영 배포 단계에서는

• EC2 -> 애플리케이션 서버
• RDS(MySQL) -> 데이터 저장
• S3 -> 이미지 파일 저장
• Parameter Store -> 민감 정보 및 설정값 관리

이 구조로 바뀌었다.

즉, 단순히 서버 한 대 안에 모든 것을 몰아넣는 게 아니라

애플리케이션 / DB / 파일 저장소를 분리하는 방향

으로 설계했다.

기술 스택

• Java 17
• Spring Boot
• Spring Data JPA
• Validation
• H2
• MySQL
• Spring Boot Actuator
• AWS EC2
• AWS VPC
• AWS RDS
• AWS Systems Manager Parameter Store
• AWS IAM Role
• AWS S3
• Spring Cloud AWS

레벨별 진행 목표

Lv0

AWS Budget 설정으로 비용 알림 구성

Lv1

VPC / Public / Private Subnet 구성 후 EC2에 Spring Boot 애플리케이션 배포 그리고 외부에서 /actuator/health 로 서버 상태 확인

Lv2

RDS를 추가해서 DB를 분리하고, DB 정보는 코드에 직접 작성하지 않고 Parameter Store에서 가져오도록 설정

Lv3

프로필 이미지를 서버 디스크가 아니라 S3에 저장하고, Presigned URL을 통해서만 다운로드 가능하도록 구현

Lv0 - 요금 폭탄 방지를 위한 AWS Budget 설정

왜 먼저 Budget부터 설정했는가

클라우드 실습은 기능 구현 못지않게 중요한 게 비용 관리라고 생각했다.

특히 AWS는 처음 사용할 때 “조금만 켜놨다고 생각했는데 과금이 쌓여버리는 상황”이 생길 수 있어서, 이번 과제에서는 기능 구현 이전에 비용 알림 체계를 먼저 만드는 것이 중요했다.

그래서 가장 먼저 한 작업이 AWS Budget 설정이었다.

내가 설정한 것

• 월 예산: $100
• 80% 도달 시 이메일 알림

이렇게 설정해두면, 실수로 EC2나 RDS를 오래 켜두더라도 완전히 모르고 지나가는 상황을 줄일 수 있다.

느낀 점

이 단계는 코드가 없어서 가볍게 보일 수 있는데, 오히려 실제 운영 관점에서는 굉장히 중요한 단계라고 느꼈다.

개발자는 단순히 기능만 만드는 사람이 아니라, 운영 비용과 리스크까지 고려해야 한다는 걸 가장 먼저 체감한 레벨이었다.

Lv1 - 네트워크 구성과 Spring Boot 애플리케이션 배포

Lv1의 목표는 한 줄로 정리하면 이거였다.

“외부에서 접속 가능한 Spring Boot 서버를 AWS 위에 직접 띄운다.”

이 단계에서 나는 단순히 API 구현에만 집중하는 것이 아니라 네트워크 구조와 배포 구조를 같이 이해하는 것에 초점을 맞췄다.

Lv1에서 충족해야 했던 요구사항

• VPC 설정
• Public / Private Subnet 분리
• Public Subnet에 EC2 생성
• 팀원 생성 API 구현
• 팀원 조회 API 구현
• local / prod profile 분리
• API 요청 로그 출력
• 전역 예외 처리
• Actuator health 노출
• EC2에 배포 후 외부 접속 확인

1. Spring Boot 프로젝트 구조 설계

처음 로컬에서 기능을 만들 때는 너무 복잡하게 가지 않고 기본적인 3계층 구조로 설계했다.

패키지 구조는 다음과 같이 잡았다.

kr.spartaclub.cloudarchitecture
 ┣ controller
 ┣ service
 ┣ repository
 ┣ entity
 ┣ dto
 ┣ exception
 ┣ logging
 ┗ config

이 구조를 선택한 이유는 다음과 같다.

• controller -> 요청/응답 처리
• service -> 비즈니스 로직
• repository -> DB 접근
• entity -> JPA 엔티티
• dto -> 요청/응답 분리
• exception -> 전역 예외 처리
• logging -> API 요청 로그 처리

2. 팀원 생성 / 조회 API 구현

Lv1의 핵심 기능은 팀원 정보를 저장하고 조회하는 API였다.

Member 엔티티

저장해야 하는 값은

• 이름
• 나이
• MBTI

였고, 이후 Lv3에서 프로필 이미지 key를 저장해야 했기 때문에 미리 profileImageKey 필드도 같이 두었다.

이렇게 설계한 이유는 나중에 S3 기능이 들어왔을 때 엔티티를 다시 크게 수정하지 않기 위해서였다.

API

• POST /api/members
• GET /api/members/{id}

왜 DTO를 분리했는가

엔티티를 그대로 요청/응답에 노출하면 나중에 필드가 늘어나거나 변경될 때 API 구조가 흔들릴 수 있어서

• MemberCreateRequest
• MemberResponse

로 분리했다.

이건 지금은 단순해 보여도 나중에 이미지 key나 운영용 필드가 추가될 때 훨씬 안정적이었다.

멤버 생성

멤버 조회

3. Validation을 적용한 이유

사용자 입력은 신뢰할 수 없다고 생각해서 요청 DTO에 검증을 넣었다.

예를 들면

• 이름은 비어 있으면 안 됨
• 나이는 너무 큰 값이 들어오면 안 됨
• MBTI는 정해진 형식이어야 함

이렇게 검증해두면 잘못된 데이터가 아예 서비스 로직 안쪽으로 들어오지 않아서 초반부터 데이터 무결성을 지킬 수 있다.

4. 전역 예외 처리 구현

과제 요구사항에 예외 처리 + 에러 로그 출력이 있었기 때문에 @RestControllerAdvice를 사용해서 전역 예외 처리기를 만들었다.

내가 이렇게 구현한 이유는 컨트롤러마다 try-catch를 반복하는 방식보다 예외를 한 곳에서 관리하는 방식이 훨씬 유지보수하기 좋기 때문이다.

처리한 예외는 대표적으로

• 존재하지 않는 멤버 조회
• Validation 실패
• 기타 예상하지 못한 예외

였다.

그리고 이때 ERROR 레벨 로그를 남기도록 해서 문제가 생겼을 때 콘솔에서 원인을 추적할 수 있도록 했다.

5. API 요청 로그를 따로 남긴 이유

과제 요구사항에 API 요청이 들어올 때마다 INFO 로그를 남기라고 되어 있었기 때문에 Filter를 사용해서

[API - LOG] POST /api/members
[API - LOG] GET /api/members/1

형태의 로그를 남기도록 했다.

이렇게 한 이유는 나중에 EC2에 배포했을 때도 “정말 요청이 들어왔는지 / 어떤 경로로 들어왔는지” 를 빠르게 확인하기 위해서였다.

처음에는 로그를 왜 이렇게까지 따로 남겨야 하나 싶었는데, 실제로 배포 후 외부 요청이 들어왔는지 확인할 때 꽤 유용했다.

6. Actuator를 붙인 이유

운영 환경에서는 애플리케이션이 “살아 있는지” 를 확인하는 게 중요하다.

그래서 spring-boot-starter-actuator를 추가하고 /actuator/health 를 열어두었다.

이걸 통해 서버가 단순히 프로세스만 떠 있는지 여부가 아니라, 애플리케이션 관점에서 정상 상태인지 확인할 수 있게 했다.

7. local / prod profile 분리

이 부분은 Lv1에서 미리 해둔 게 정말 컸다.

처음에는 로컬 개발이기 때문에 H2를 사용했고, 나중에 운영 환경에서는 MySQL(RDS)를 써야 했기 때문에 설정 파일을 환경별로 분리했다.

• application.yml
• application-local.yml
• application-prod.yml

이렇게 나눈 이유는 같은 프로젝트라도 환경에 따라 DB, 설정, 실행 방식이 달라지기 때문이다.

지금 당장 Lv1만 보면 local로 충분해 보이지만, Lv2에서 RDS를 붙이는 순간 이 분리가 없었으면 설정이 훨씬 꼬였을 것 같다.

8. 로컬에서 Postman 테스트

이 단계에서 나는 먼저 로컬에서 기능이 완전히 되는지 검증했다.

내가 실제로 테스트한 것

• 멤버 생성
• 멤버 조회
• 존재하지 않는 멤버 조회
• Validation 실패
• actuator health
• actuator info

이 과정을 거친 이유는 AWS에 올렸는데 안 될 경우 그 원인이 코드인지, 배포인지, 네트워크인지 구분이 안 되기 때문이다.

그래서 반드시 로컬에서 먼저 기능 검증을 끝낸 후 배포하는 방식으로 진행했다.

유효성 검증 테스트

존재하지 않는 멤버 조회

멤버 생성

멤버 조회

9. VPC / Subnet / EC2 구성

이제부터는 본격적으로 AWS 인프라 구성이었다.

내가 구성한 구조는 다음과 같다.

• VPC: 10.0.0.0/16
• Public Subnet
• Private Subnet
• Internet Gateway
• Public Route Table
• EC2는 Public Subnet에 생성

왜 Public / Private Subnet을 분리했는가

처음에는 “EC2 하나만 띄우면 되지 왜 서브넷을 나누지?” 싶었는데, 과제 의도는 단순 배포가 아니라 운영 가능한 네트워크 구조를 이해하는 것이었다.

즉

• 외부에서 접근 가능한 서버 -> Public
• 직접 노출되면 안 되는 자원 -> Private

이렇게 분리하는 구조를 처음부터 갖추는 게 핵심이었다.

10. Lv1에서 겪은 트러블슈팅

트러블슈팅 1 - EC2에 퍼블릭 IP가 안 붙은 문제

처음 EC2를 만들었을 때 퍼블릭 IP가 없어서 외부에서 접속이 불가능했다.

원인을 확인해보니 EC2를 Private Subnet에 잘못 생성한 상태였다.

즉 나는 처음에 Public Subnet에 만들어야 하는 인스턴스를 Private Subnet에 올려버린 것이다.

해결 방법

• 기존 인스턴스 종료
• Public Subnet에 다시 생성
• Auto-assign public IP 활성화 확인

배운 점

이 경험으로 “EC2를 만든다” 와 “인터넷에서 접근 가능한 EC2를 만든다” 는 전혀 다른 문제라는 걸 배웠다.

Subnet의 위치가 곧 인스턴스의 역할을 결정한다는 걸 체감한 순간이었다.

트러블슈팅 2 - scp를 EC2 안에서 실행한 문제

jar 파일을 EC2로 업로드할 때 처음에는 scp 명령어를 EC2 내부에서 실행해서 실패했다.

당시 에러를 보니 맥북 경로인 /Users/... 를 EC2가 찾지 못했다.

왜 발생했는가

scp는 로컬 -> 원격 서버로 파일을 보내는 명령어인데, 나는 EC2에 이미 들어간 상태에서 로컬 경로를 참조하려고 했던 것이다.

즉 명령어를 실행하는 위치를 잘못 이해한 실수였다.

해결 방법

• EC2에서 exit
• 맥북 로컬 터미널에서 scp 실행

배운 점

클라우드 작업에서는 “내가 지금 어느 환경에서 명령어를 실행하고 있는가” 를 항상 명확히 구분해야 한다는 걸 배웠다.

이건 작은 실수처럼 보이지만 로컬 / 서버 / AWS 콘솔을 계속 오가다 보면 생각보다 자주 헷갈린다.

트러블슈팅 3 - --spring.profiles.active=local 위치 오류

jar 실행 시

java -jar --spring.profiles.active=local app.jar

식으로 잘못 입력해서 JVM 옵션으로 인식되어 실행이 실패했다.

해결 방법

Spring 옵션은 jar 뒤에 와야 했다.

java -jar app.jar --spring.profiles.active=local

배운 점

Java 실행 명령어에서 JVM 옵션과 애플리케이션 옵션의 위치가 다르다는 걸 확실히 알게 됐다.

트러블슈팅 4 - 외부에서 /actuator/health 접근 시 타임아웃

EC2 내부 로그상으로는 서버가 잘 떠 있었는데, 브라우저/포스트맨에서는 타임아웃이 났다.

원인

애플리케이션 문제라기보다는 EC2 보안 그룹에서 8080 포트가 제대로 열려 있지 않거나, 퍼블릭 접근 설정이 잘못된 경우였다.

해결 방법

• EC2 보안 그룹 인바운드에서 8080 허용
• EC2 내부에서 curl localhost:8080/actuator/health 로 내부 응답 먼저 확인
• 내부는 정상이고 외부만 안 되므로 네트워크 설정으로 범위 축소

배운 점

이 과정에서 타임아웃이 발생했다고 해서 무조건 애플리케이션 코드를 의심하면 안 되고, 내부 응답 / 외부 응답을 분리해서 확인해야 한다는 걸 배웠다.

11. Lv1 마무리

최종적으로 EC2 퍼블릭 IP를 통해

• /actuator/health
• 멤버 생성 API
• 멤버 조회 API

모두 정상 동작하는 것을 확인했다.

이 시점에서 “로컬 프로젝트를 AWS 위에서 직접 실행 가능한 상태로 만든 것” 자체가 굉장히 의미 있게 느껴졌다.

단순히 스프링 코드를 짜는 걸 넘어서 네트워크 / 서버 / 애플리케이션이 함께 맞물려야 서비스가 동작한다는 걸 처음으로 체감했다.

Lv2 - RDS 분리와 Parameter Store 적용

Lv1이 “애플리케이션을 EC2 위에 올리는 단계”였다면, Lv2는 운영 환경답게 DB를 분리하고 민감 정보를 외부화하는 단계였다.

이 단계에서 핵심은

• H2 -> MySQL RDS 전환
• DB 정보를 yml에 직접 쓰지 않기
• Parameter Store 사용
• /actuator/info 에 외부 설정값 표시

였다.

Lv2에서 충족해야 했던 요구사항

• RDS MySQL 생성
• EC2와 RDS 보안 그룹 체이닝
• Parameter Store에 DB 정보 저장
• Spring Boot가 Parameter Store 값으로 RDS 연결
• /actuator/info 에 team-name 출력

1. 왜 DB를 분리해야 했는가

Lv1까지는 H2로 충분히 기능 검증이 가능했다. 하지만 운영 환경에서는 애플리케이션 서버와 DB가 분리되어야 한다.

왜냐하면 서버가 죽거나 재생성되더라도 DB는 독립적으로 살아 있어야 하기 때문이다.

즉, EC2 안에 DB를 같이 두는 방식은 운영 관점에서는 안정성이 떨어진다.

그래서 Lv2에서는 애플리케이션은 EC2, 데이터는 RDS 구조로 바꿨다.

2. RDS 생성 과정

MySQL RDS를 생성하면서 초기에 DB 이름, 계정, 비밀번호를 설정했다.

그리고 같은 VPC 안에 두어 EC2와 RDS가 내부적으로 통신할 수 있도록 구성했다.

3. Lv2에서 겪은 트러블슈팅

트러블슈팅 1 - RDS 생성 시 Availability Zone 조건 미충족

처음 RDS를 만들 때

“DB subnet group doesn't meet Availability Zone coverage requirement”

에러가 발생했다.

원인

처음 만든 subnet들이 모두 같은 AZ에만 있었기 때문이다.

즉 RDS는 최소 2개 AZ를 포함하는 subnet group을 요구했는데, 나는 한 개 AZ만 가진 구조로 만들고 있었던 것이다.

해결 방법

• ap-northeast-2c 에 subnet 추가 생성
• DB subnet group을 서로 다른 AZ의 subnet으로 구성

배운 점

RDS는 단순히 “어디 하나에 DB 하나 띄우는 서비스”가 아니라 가용성을 전제로 설계된 관리형 서비스라는 걸 알게 되었다.

트러블슈팅 2 - RDS 접속 실패 (Can't connect to MySQL server)

EC2에서 RDS endpoint로 접속하려고 했을 때 계속 접속 오류가 났다.

원인

처음에는 RDS 보안 그룹에 EC2의 실제 보안 그룹이 아니라 RDS 자신의 default 보안 그룹만 허용된 상태였다.

즉,

• EC2 보안 그룹
• RDS 보안 그룹

이 서로 다르지만 RDS 인바운드가 EC2 SG를 허용하지 않고 있었던 것이다.

해결 방법

• EC2가 실제로 사용하는 SG 확인
• RDS 인바운드에서 MySQL/Aurora 3306
• Source를 EC2의 Security Group 으로 추가

배운 점

이 경험을 통해 Security Group Chaining 개념을 확실하게 이해하게 됐다.

IP 주소를 직접 허용하는 방식이 아니라 특정 보안 그룹을 가진 리소스만 통신하게 만드는 방식이 AWS에서 훨씬 일반적이고 안전하다는 걸 배웠다.

트러블슈팅 3 - IAM Role이 없어서 Parameter Store 값을 못 읽은 문제

초기에는 /actuator/info가 계속 {} 만 나왔다.

처음에는 yml 문제인가 싶었는데, 확인해보니 EC2에 IAM Role이 없었다.

즉 애플리케이션이 Parameter Store를 읽으려고 해도 권한 자체가 없었던 것이다.

해결 방법

• EC2용 IAM Role 생성
• AmazonSSMReadOnlyAccess 추가
• EC2에 Role 연결
• 애플리케이션 재실행

배운 점

클라우드에서는 코드가 맞아도 권한이 없으면 기능이 동작하지 않는다는 걸 확실히 느꼈다.

특히 AWS에서는 “설정값을 읽는다”는 행위조차 IAM 권한이 필요한 API 호출이라는 점이 인상적이었다.

(이미지 첨부)

(이미지 첨부)

트러블슈팅 4 - Unknown database cloud_architecture

Parameter Store를 읽고, RDS 연결도 되는데 애플리케이션 실행 시

Unknown database 'cloud_architecture'

오류가 발생했다.

원인

RDS 인스턴스는 생성되었지만, 실제 애플리케이션이 접속할 데이터베이스 스키마 cloud_architecture 가 생성되지 않은 상태였다.

해결 방법

EC2에서 mysql client로 RDS에 접속해서

CREATE DATABASE cloud_architecture;

를 실행했다.

배운 점

RDS 인스턴스를 만들었다고 해서 애플리케이션이 사용할 스키마까지 자동으로 완성된 것은 아니라는 걸 배웠다.

즉, RDS 인스턴스 생성 과 애플리케이션용 DB 준비 완료 는 다른 단계였다.

4. Parameter Store를 적용한 이유

이 단계에서 가장 중요하게 생각한 건 DB URL, username, password 같은 민감한 값을 코드나 yml에 직접 쓰지 않는 것이었다.

그래서 Parameter Store에 다음 값을 저장했다.

/cloud/db/url
/cloud/db/username
/cloud/db/password
/cloud/team-name

이렇게 외부화한 이유는

• 운영환경 변경 시 코드 수정 최소화
• 민감 정보 Git 노출 방지
• 설정값 중앙 관리

를 위해서였다.

5. /actuator/info 로 설정값 확인

/cloud/team-name 값을 Parameter Store에 저장하고, Spring Boot에서 이를 읽어 /actuator/info 로 노출되게 구성했다.

최종적으로

{
  "app": {
    "name": "cloud-architecture"
  },
  "team-name": "sparta-cloud-team"
}

형태가 출력되는 걸 확인했다.

이 순간이 사실 Lv2의 완성 포인트라고 느꼈다.

왜냐하면 이 결과는 단순히 info endpoint가 열린 게 아니라,

• EC2가 IAM Role을 통해
• Parameter Store 값을 읽고
• Spring Boot 환경에 주입해서
• actuator info로 노출했다

는 걸 의미하기 때문이다.

actuator 확인

6. Lv2 마무리

Lv2를 끝내면서 단순히 EC2에 앱을 띄우는 수준에서 벗어나 운영용 DB와 설정값 관리 체계까지 갖춘 구조를 만들 수 있었다.

개인적으로는 이 레벨에서 “클라우드 환경에서는 코드보다 설정과 권한, 연결 구조가 더 중요할 수 있다” 는 걸 가장 크게 느꼈다.

Lv3 - S3 이미지 업로드와 Presigned URL

Lv3의 목표는 명확했다.

프로필 이미지를 서버 디스크가 아니라 S3에 저장하고, Presigned URL을 통해서만 조회 가능하게 만든다.

이전까지는 텍스트 데이터 중심이었다면, Lv3는 파일을 어떻게 저장하고 안전하게 제공할 것인가 를 다루는 단계였다.

Lv3에서 충족해야 했던 요구사항

• S3 버킷 생성
• 퍼블릭 액세스 차단 유지
• EC2 IAM Role에 S3 권한 부여
• POST /api/members/{id}/profile-image
• GET /api/members/{id}/profile-image
• Presigned URL 유효기간 7일

1. 왜 서버 디스크가 아니라 S3를 써야 하는가

처음에는 이미지도 서버 내부에 저장하면 되지 않을까 싶었지만, 운영 환경에서는 그 방식이 위험하다.

왜냐하면 EC2는 언제든 교체되거나 재배포될 수 있기 때문이다.

즉, 이미지 파일을 EC2 디스크에 저장하면

• 인스턴스 교체 시 파일 유실 가능
• 여러 서버 운영 시 파일 동기화 문제
• 서버 역할과 파일 저장 역할이 섞임

이런 문제가 생긴다.

그래서 파일은 S3 같은 전용 저장소에 분리하는 것이 맞다고 이해하고 구현했다.

2. S3 버킷 생성

S3 버킷은 퍼블릭 액세스를 차단한 상태로 생성했다.

이렇게 한 이유는 이미지를 단순 public URL로 바로 노출하는 것이 아니라 필요할 때만 Presigned URL을 발급해서 접근하게 만들기 위해서다.

즉 “이미지는 S3에 저장하지만, 누구나 아무 때나 직접 볼 수는 없도록” 구성한 것이다.

3. IAM Role에 S3 권한 추가

EC2에서 S3에 업로드하려면 애플리케이션이 S3 API를 호출할 수 있어야 한다.

그래서 기존 EC2 IAM Role에 S3 접근 권한을 추가했다.

이 과정을 통해 Parameter Store뿐 아니라 S3도 Access Key를 코드에 넣는 방식이 아니라 IAM Role 기반으로 접근하게 구성했다.

이 방식이 더 안전하고, 운영 환경에서도 권장되는 방식이라고 느꼈다.

4. 프로필 이미지 업로드 API 구현

API

POST /api/members/{id}/profile-image

요청은 MultipartFile 형태로 받고, 서비스 로직에서는

• 멤버 존재 확인
• 이미지 파일 검증
• S3 업로드
• S3 object key 생성
• DB의 profileImageKey 업데이트

순서로 처리했다.

왜 전체 URL이 아니라 key를 저장했는가

처음에는 S3 URL을 그대로 DB에 저장할 수도 있다고 생각했지만, 나중에 Presigned URL을 다시 생성하려면 버킷 + key 기반으로 처리하는 게 훨씬 깔끔했다.

그래서 DB에는 최종 URL이 아니라

members/1/uuid.jpeg

같은 S3 key 를 저장하도록 했다.

이렇게 하면

• URL 정책이 바뀌어도 DB 구조는 유지 가능
• Presigned URL 재발급이 쉬움
• 저장소 구조를 더 유연하게 관리 가능

하다고 판단했다.

5. Presigned URL 조회 API 구현

API

GET /api/members/{id}/profile-image

이 API는 실제 파일 데이터를 직접 반환하는 게 아니라, S3 객체에 접근할 수 있는 서명된 URL 을 생성해서 반환한다.

그리고 과제 요구사항에 맞게 유효기간을 7일로 설정했다.

왜 Presigned URL을 사용했는가

버킷은 퍼블릭 차단 상태이기 때문에 그냥 S3 주소만으로는 이미지를 볼 수 없다.

그래서 필요할 때만 유효기간이 있는 임시 URL을 발급해서 안전하게 다운로드하도록 만든 것이다.

이 방식은 다음 장점이 있다.

• 버킷 자체는 private 유지
• 필요한 사용자만 일정 기간 접근 가능
• 파일 서버를 직접 구현하지 않아도 됨

6. Lv3에서 겪은 트러블슈팅

트러블슈팅 1 - S3Presigner 심볼/빈 문제

처음 S3 기능을 붙일 때 S3Presigner 를 인식하지 못하고, 빈 주입도 실패했다.

원인

• S3 starter 의존성이 없었고
• Presigner 빈도 명시적으로 등록되지 않은 상태였다.

해결 방법

• spring-cloud-aws-starter-s3 추가
• S3Config에서 S3Client, S3Presigner 직접 빈 등록

배운 점

자동 설정이 많아도 상황에 따라서는 핵심 빈을 직접 명시적으로 등록하는 편이 더 안정적일 수 있다는 걸 배웠다.

트러블슈팅 2 - 테스트 환경에서 S3 설정값이 없어 빌드 실패

S3 기능 추가 후 contextLoads() 테스트가 실패했다.

원인

테스트 환경에서

• cloud.aws.s3.bucket
• cloud.aws.region.static

같은 설정값이 없어 S3 관련 빈 생성이 실패한 것이었다.

해결 방법

application.yml 또는 local/test 환경에 더미 값을 넣어 테스트가 실패하지 않도록 했다.

배운 점

운영 환경 설정이 늘어날수록 테스트 환경도 같이 고려해야 한다는 걸 배웠다.

기능만 추가한다고 끝이 아니라, 테스트가 그 설정을 어떻게 읽을지도 함께 설계해야 한다는 점이 중요했다.

7. Lv3 최종 검증

최종적으로 아래 세 가지를 모두 확인했다.

1) 프로필 이미지 업로드 성공

• 201 Created
• profileImageKey 반환

2) Presigned URL 조회 성공

• 200 OK
• URL 반환

3) 브라우저에서 이미지 실제 열림

• 반환된 URL을 브라우저에 붙였을 때 이미지 확인

이 과정까지 확인했기 때문에 Lv3는 단순히 API 응답만 만든 게 아니라 실제로 S3 업로드 -> DB 저장 -> Presigned URL 발급 -> 이미지 조회 전체 흐름이 정상 동작하는 걸 검증하였다.

이번 과제를 통해 배운 것

1. 서버가 돌아가는 것과 운영 가능한 것은 다르다

로컬에서 API가 되는 것과, EC2 / RDS / S3 / IAM / Parameter Store까지 연결되어 운영 가능한 구조를 만드는 것은 전혀 다른 문제였다.

2. 클라우드에서는 권한과 네트워크가 정말 중요하다

코드가 맞아도

• 보안 그룹이 틀리면 연결이 안 되고
• IAM Role이 없으면 설정을 못 읽고
• Subnet 위치가 틀리면 외부 접속이 안 된다

이걸 몸으로 배웠다.

3. 데이터와 파일은 서버와 분리되어야 한다

RDS와 S3를 붙이면서 애플리케이션 서버는 “처리 담당”, 데이터와 파일은 별도 저장소 담당 이라는 구조가 왜 중요한지 이해하게 되었다.

마무리

이번 필수 과제를 통해 Spring Boot 애플리케이션을 단순히 “개발”하는 것에서 끝나지 않고, AWS 위에서 실제로 운영 가능한 구조로 확장하는 경험을 할 수 있었다.

특히

• EC2 배포
• RDS 분리
• Parameter Store 설정 관리
• S3 업로드와 Presigned URL

까지 직접 해본 경험은 이후 Docker, CI/CD, ALB, Auto Scaling 같은 도전 과제를 진행할 때도 큰 기반이 될 것 같다고 느꼈다.

다음 단계에서는 이 구조를 바탕으로 Docker와 CI/CD를 붙여 더 자동화된 배포 구조로 확장해볼 예정이다.

회고

처음에는 “AWS는 어렵다”는 느낌이 강했는데, 이번 과제를 하면서 느낀 건 AWS가 어려운 게 아니라 구조를 이해하지 않은 상태에서 한 번에 하려고 하면 어렵다는 것이었다.

레벨별로 하나씩 쌓아가면서 보니 각 서비스가 왜 존재하는지, 왜 그렇게 연결해야 하는지가 조금씩 보이기 시작했다.

github 링크

프로젝트 github 링크

운영 가능이란?

단순히 개발이 완료된 상태와 운영 가능한 상태는 다름!

최종 목표는 코드의 완성이 아니라, 운영이 가능한 상태로 만드는 것

“운영형”이 중요한 이유

1. 새벽 3시 장애 발생
   • ❌ 운영 불가: "서버 들어가서 확인해봐야..." → 2시간 소요
   • ✅ 운영 가능: 헬스체크 DOWN → 로그 확인 → 10분 내 원인 파악
2. 스테이징 → 프로덕션 배포
   • ❌ 운영 불가: DB 설정 하드코딩 → 프로덕션 DB 연결 실패
   • ✅ 운영 가능: 환경변수로 설정 주입 → 무사히 배포

운영 3요소

Health, Log, Config

1. Health(헬스체크)

목적: 서버가 정상 동작 중인지 확인

• Up: 정상
• Down: 문제 발생

  # 헬스체크 요청
  curl http://localhost:8080/actuator/health
  

응답 예시

{"status":"UP"}

### 2. Log(로그)
목적: 장애 발생 시 원인 추적

2024-01-15 10:30:45 INFO - Application started 2024-01-15 10:31:02 ERROR - Database connection failed 2024-01-15 10:31:02 ERROR - java.sql.SQLException: Connection refused

> 로그를 보면 DB 연결 실패가 원인임을 알 수 있음

### Config(설정)
목적: 환경(로컬/개발/운영)별 다른 설정 적용
- local - DB 호스트: localhost / 로그 레벨: DEBUG
- prod - DB 호스트: rds.amazonaws.com / 로그 레벨: INFO

> 코드 수정 없이 환경 변수로 설정

---

## Spring Boot Actuators
**Spring Boot Actuator**는 앱의 상태, 메트릭, 환경 정보를 HTTP 엔드포인트로 제공하는 라이브러리. 의존성을 추가하면 `/actuator/health`, `/actuator/info` 같은 엔드포인트가 자동으로 생성됨

#### 의존성 추가

implementation 'org.springframework.boot:spring-boot-starter-actuator'

### Actuator 주요 엔드포인트
| 엔드포인트 | 용도 | 민감도 | 기본 노출 |
|---|---|---|---|
| /actuator/health | 앱 상태 확인 | 🟢 낮음 | ✅ |
| /actuator/info | 앱 정보 | 🟢 낮음 | ❌ |
| /actuator/metrics | 성능 지표 | 🟡 중간 | ❌ |
| /actuator/env | 환경변수, 설정값 | 🔴 높음 | ❌ |
| /actuator/configprops | 모든 설정값 | 🔴 높음 | ❌ |
| /actuator/heapdump | JVM 메모리 덤프 | 🔴 높음 | ❌ |
| /actuator/threaddump | 스레드 정보 | 🟡 중간 | ❌ |

---

## 로그 레벨
로그 레벨(Log Level)은 로그의 심각도를 나타내는 분류. 개발 시에는 상세한 DEBUG 로그가 필요하지만, 운영 시에는 성능을 위해 INFO 이상만 출력함

| 로그 레벨 | 용도 | 예시 |
|---|---|---|
| ERROR | 에러, 예외 상황 | DB 연결 실패, NPE |
| WARN | 경고, 잠재적 문제 | 느린 쿼리, 재시도 발생 |
| INFO | 일반 정보 | 앱 시작, 요청 처리 완료 |
| DEBUG | 디버깅용 상세 정보 | 변수 값, SQL 쿼리 |
| TRACE | 매우 상세한 정보 | 메서드 진입/종료 |

> Spring Boot에서는 SLF4J를 사용하여 로그를 출력함
-> @Slf4j

---

## Spring Boot Profile별 설정
파일명: 활성화되는 profile

- application-local.properties: local
- application-prod.propertie : prod
- application-dev.properties: dev

---

## AWS Parameter Store
설정값을 안전하게 저장하고 관리하는 서비스

| 파라미터 이름 | Type | 용도 |
|---|---|---|
| /{app이름}/prod/DB_HOST | String | DB 엔드포인트 |
| /{app이름}/prod/DB_PORT | String | 3306 (MySQL port) |
| /{app이름}/prod/DB_NAME | String | 데이터베이스명 |
| /{app이름}/prod/DB_USERNAME | String | 사용자명 |
| /{app이름}/prod/DB_PASSWORD | String | 비밀번호 |

---

## EC2에 Spring 앱 배포 실습

### 배포를 위한 Spring 프로젝트 세팅
![](https://velog.velcdn.com/images/jiiim_ni/post/7a619a0c-1bdc-40d4-8bb4-718b6260939f/image.png)

- 의존성
- 환경변수
- JAR 빌드

---

### EC2 세팅 및 배포

#### 보안그룹
- 인바운드 규칙으로 8080포트 추가 완료

#### Java 설치
![](https://velog.velcdn.com/images/jiiim_ni/post/7b65e80e-870d-48a1-83c2-efe2748c3504/image.png)

---

### JAR 업로드

기본 형식

scp -i <키페어경로> <로컬파일> <사용자>@:~/app.jar

예시

scp -i /.ssh/my-key.pem app.jar ec2-user@{EC2-IP}:/app.jar

![](https://velog.velcdn.com/images/jiiim_ni/post/e1e859f9-681e-437b-8c82-6009d1b55cb6/image.png)

---
### IAM Role 설정

#### 권한 추가

![](https://velog.velcdn.com/images/jiiim_ni/post/0b7dcd61-8e47-44fb-8287-d49af6adc3bd/image.png)

---
### 포그라운드 실행

![](https://velog.velcdn.com/images/jiiim_ni/post/90bb09e7-a177-4520-bf75-cb05b50d0d2c/image.png)
-> 역할을 부여하니 잘 실행되는 모습
![](https://velog.velcdn.com/images/jiiim_ni/post/6871f6c8-71d9-4a8f-a8e3-c7d9681d8b2f/image.png)
- status: UP
---

### 백그라운드 실행
![](https://velog.velcdn.com/images/jiiim_ni/post/aafe02f3-dab3-40fa-b7e9-906dd8ac4c47/image.png)

![](https://velog.velcdn.com/images/jiiim_ni/post/cf8586db-5237-414f-9e46-8dbb659c26e6/image.png)

- status: UP

---

### Parameter Store 검증
![](https://velog.velcdn.com/images/jiiim_ni/post/a9ce0e22-9d11-4200-a914-31715b2245e3/image.png)

---

## 회고 / 알게 된 점

처음에는 **Spring Boot Actuator, 로그 설정, 환경 설정 분리** 같은 것들이 왜 필요한지 잘 이해되지 않았다.  
단순히 서버가 실행되고 API가 정상 동작하면 개발이 완료된 것이라고 생각했기 때문이다.

하지만 EC2에 직접 애플리케이션을 배포하고 실행 과정을 확인하면서  
**“개발 완료”와 “운영 가능한 상태”는 다르다는 것을 이해할 수 있었다.**

---

### Actuator의 역할

처음에는 `/actuator/health` 같은 엔드포인트가 어디에 쓰이는지 감이 오지 않았다.  
하지만 EC2에 배포한 후 직접 요청을 보내보면서 서버 상태를 확인할 수 있었다.

curl http://{EC2-IP}:8080/actuator/health

응답

{"status":"UP"}

이 결과를 통해 **서버가 정상적으로 동작하고 있는지 외부에서 확인할 수 있다는 점**을 이해했다.

즉 단순히 서버가 실행된 것이 아니라  
**서비스 상태를 확인할 수 있는 구조가 운영 환경에서는 중요하다는 것을 알게 되었다.**

---

### 로그의 중요성

개발 단계에서는 로그를 크게 신경 쓰지 않았다.  
하지만 운영 환경에서는 문제가 발생했을 때 **로그가 원인을 파악할 수 있는 중요한 정보**가 된다.

예를 들어 다음과 같은 로그가 있다면

ERROR - Database connection failed java.sql.SQLException: Connection refused

단순히 "서버가 동작하지 않는다"가 아니라  
**DB 연결 문제라는 원인을 빠르게 파악할 수 있다.**

그래서 운영 환경에서는 상황에 맞게 **로그 레벨을 설정하는 것이 중요하다는 것도 이해할 수 있었다.**

---

### 환경 설정 분리

개발 환경과 운영 환경은 사용하는 설정이 다르다.

예를 들어

- local → DB: localhost
- prod → DB: AWS RDS

만약 이러한 설정이 코드에 하드코딩되어 있다면  
환경이 바뀔 때마다 코드를 수정해야 하는 문제가 발생한다.

그래서

- `application-local`
- `application-dev`
- `application-prod`

같이 **Profile 기반 설정 분리**를 사용하고  
DB 계정이나 비밀번호 같은 민감한 값은 **AWS Parameter Store**를 통해 관리하는 방식이 필요하다는 것을 이해했다.

---

### 느낀 점

이번 실습을 통해 단순히 기능을 구현하는 것에서 끝나는 것이 아니라  

- 서버 상태 확인 (Health)
- 문제 원인 추적 (Log)
- 환경별 설정 관리 (Config)

이 세 가지가 있어야 **실제로 운영 가능한 애플리케이션이 된다는 것을 이해할 수 있었다.**

웹사이트 동작 방식

1. 클라이언트(Client) - 요청하는 주체

• 정의: 서비스를 요청하는 사용자 기기나 소프트웨어
• 예시: 브라우저(크롬, 사파리 등)
• 역할: 사용자의 명령을 받아 서버에 "이 작업을 처리해줘"라고 요청(Request)을 보냄

2. 네트워크(Network) - 데이터의 통로

• 정의: 클라이언트와 서버가 서로 데이터를 주고받을 수 있게 연결해 주는 망
• 예시: 인터넷
• 역할: 클라이언트가 보낸 요청을 서버로 전달하고, 반대로 서버가 만든 결과물을 다시 클라이언트에게 안전하게 배달하는 역할. 이때 서로 대화가 통하도록 주로 HTTP라는 일종의 대화 규칙(Protocol, 프로토콜)을 사용

3. 서버(Server) - 제공하는 주체

• 정의: 클라이언트의 요청을 받아 데이터를 처리하고 결과를 되돌려주는 컴퓨터 시스템
• 예시: 네이버 서버, 게임 서버
• 역할: 24시간 깨어 있으면서 클라이언트의 요청(Request)이 오기를 기다림. 요청이 오면 필요한 정보를 찾거나 계산한 뒤, 다시 네트워크를 통해 클라이언트에게 응답(Response)을 보냄

온프레미스 vs 클라우드

온프레미스(On-Premise)

회사가 직접 서버를 구매하고, 자체 서버실에서 운영하는 방식

• 서버 컴퓨터를 직접 구매해야함
• 설치/관리를 직접 해야함
• 전기/냉방 비용이 듬
• 네트워크 구축과 관리를 해야함

클라우드(Cloud)

AWS, GCP, Azure 같은 업체의 서버를 빌려서 사용하는 방식

• 수만~수십만 대의 서버가 이미 준비되어 있음
• 필요할 때 클릭 몇 번으로 서버를 할당받을 수 있음
• 필요가 없어졌다면 클릭 몇 번으로 서버를 반납할 수 있음

온프레미스 = 자가용 클라우드 = 렌트카

IaaS/Paas/Saas

IaaS (Infrastructure as a Service)

인프라만 빌린다 - 서버, 네트워크, 스토리지

PaaS (Platform as a Service)

플랫폼까지 빌린다 - 런타임, 미들웨어 포함 AWS 예시: Elastic Beanstalk AWS 제공: 서버/네트워크, 운영체제, 런타임, 오토스케일링, 로드밸런싱 내가 해야하는 것: 애플리케이션 코드 작성/배포

SaaS (Software as a Service)

소프트웨어를 빌린다 - 완성된 서비스 사용 업체가 제공: 모든 것 내가 하는 것: 툴 사용

AWS

AWS는 전 세계에 분산된 데이터센터를 가지고 있고, 우리는 그 중 원하는 위치를 선택해서 사용하게 됨

데이터 센터란?

데이터 센터는 컴퓨팅 시스템 및 하드웨어 장비를 저장하는 물리적 위치. 여기에는 서버, 데이터 스토리지 드라이브 및 네트워크 장비와 같이 IT 시스템에 필요한 컴퓨팅 인프라가 포함됨 모든 회사의 디지털 데이터를 저장하는 물리적 시설

AWS 서비스 예시

• 아무거나 올릴 수 있는 서버가 필요해: EC2
• 데이터베이스가 필요해: RDS
• 이미지/파일을 저장해야해: S3

IAM

User/Role/Policy

IAM에는 핵심 요소 3가지가 있습니다.

1. User

"사람"이 AWS에 접근할 때 사용하는 계정

• 개발자가 AWS 콘솔(웹사이트)에 로그인할 때
• 관리자가 CLI(명령줄)로 AWS를 관리할 때
• 사람이 직접 AWS를 조작하는 모든 경우

핵심 특징: 영구적인 자격증명(Credential)을 가짐

💡 자격증명(Credential)이란?

본인임을 증명하는 정보 (비밀번호, 키 등)

• User가 가지는 자격증명 2가지
  • 비밀번호: AWS 콘솔(웹사이트) 로그인용
  • Access Key: API/CLI(명령줄) 접근용
    • Access Key ID: 아이디 역할
    • Secret Access Key: 비밀번호 역할

• 특징
  • 한 번 생성하면 삭제하기 전까지 유효 (만료 없음)
  • 1인 1계정 원칙 권장

2. Role

"서버/서비스"에게 권한을 부여할 때 사용

• EC2 서버가 S3에 파일을 업로드할 때
• GitHub Actions가 AWS에 배포할 때
• 서버/자동화 시스템이 AWS를 사용하는 모든 경우

핵심 특징: 임시로 빌려 쓰는 권한 세트

3. Policy

“어떤 작업을 허용/거부”할지 정의

Policy 자체를 단독으로 쓰는 것이 아님!

Policy를 User나 Role에 “연결”하는 형태

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",              ← 허용? 거부?
      "Action": "s3:GetObject",       ← 어떤 동작을?
      "Resource": "arn:aws:s3:::my-bucket/*"  ← 어떤 대상에?
    }
  ]
}

네트워크

VPC와 VPC의 하위 요소

VPC(Virtual Private Cloud)란?

1. 정의

• AWS 클라우드 내에 만드는 사설 네트워크
• 다른 AWS 계정의 네트워크와 논리적으로 완벽히 격리되어 있음

2. IP 주소 범위 (IP Range) 설정 VPC를 만들 때는 이 네트워크에서 총 몇 개의 IP를 쓸 것인가를 정해야 함

1. Subnet

1.1 정의

• 거대한 VPC 네트워크를 관리하기 편하게 작게 쪼갠 구역
• 하나의 VPC 안에는 여러 개의 서브넷을 만들 수 있음

1.2 서브넷의 필수 규칙

• 서브넷 = 1 가용 영역 (AZ):
  • 하나의 서브넷이 여러 데이터센터(가용 영역)에 걸쳐 있을 수 없습니다. "Subnet-A는 서울의 A존 데이터센터에만 존재한다"는 식
  • 앞서 배웠듯, 데이터센터가 여러개 있는 이유는 고가용성을 위해서라고 했듯, 마찬가지로 서브넷을 여러개 두어야하는 이유 또한 가용성 확보 때문
• IP 범위 쪼개기:
  • VPC 전체 IP(10.0.0.0/16)를 서브넷들이 나눠서 가짐

2. Route Table (라우팅 테이블)

2.1 정의

• 네트워크 트래픽(데이터)이 "어디로 가야 하는지" 방향을 알려주는 표지판(규칙)
• 모든 서브넷은 반드시 하나의 라우팅 테이블과 연결되어야 함

2.2 트래픽을 처리하는 두 가지 방식

라우팅 테이블에는 기본적으로 두 가지 규칙이 들어감

• Local (내부 통신):
  • "도착지가 우리 VPC 내부(10.0.x.x)라면?" 👉 VPC 안에서 찾아서 보내라.
  • 이 규칙은 삭제할 수 없으며, VPC 내의 모든 서버끼리는 별도 설정 없이 통신이 가능
• External (외부 통신):
  • "도착지가 모르는 주소(0.0.0.0/0, 즉 인터넷)라면?" 👉 인터넷 게이트웨이(정문)로 보내라.
  • 이 규칙이 있느냐 없느냐가 Public/Private을 결정

3. Internet Gateway (IGW)

3.1 정의

• VPC와 외부 인터넷 세상을 연결해 주는 유일한 관문(하나의 VPC에는 오직 하나의 IGW).
• VPC는 기본적으로 고립된 환경이므로, IGW가 없다면 VPC 내부 인프라에서 인터넷 접속이 불가능

4. Public Subnet vs Private Subnet

AWS에 실제로는 Private Subnet 만들기와 같은 버튼은 없음 오직 라우팅 테이블의 설정 차이로 구분됨

4.1 Public Subnet (🌐 퍼블릭 서브넷)

• 조건: 연결된 라우팅 테이블에 IGW로 향하는 경로가 있는 서브넷.
• 라우팅 규칙:
  1. 172.31.0.0/16 → local (VPC 내부 통신용, 자동 생성됨)
  2. 0.0.0.0/0 → igw-xxxxxxxx (인터넷 연결용, 필수)

4 .2 Private Subnet (🔒 프라이빗 서브넷)

• 조건: 라우팅 테이블에 IGW로 향하는 경로가 없는 서브넷.
• 라우팅 규칙: 172.31.0.0/16 → local (VPC 내부 통신은 가능)

EC2

EC2는 AWS에서 제공하는 클라우드 컴퓨팅 서비스. 쉽게 말하면, 마음대로 세팅해볼 수 있는 AWS 컴퓨터

인스턴스 상태

VPC부터 EC2까지 실습

AWS에서 계정 생성 후 직접 실습한 과정 & 결과

VPC 생성 실습

• public, private 각각 2개씩 잘 되어있음

EC2 생성 실습

• 상태 검사 3/3개 검사 통과 결과 확인

EC2 접속 실습(SSH)

• 처음에 이 과정에서 문제가 생겼었음(이후 트러블슈팅에 작성)
• 문제 해결 후 정상적으로 잘 되는 거 확인

IAM Role도 확인해보기

• 아직은 역할 없음

EC2에서 HTTP 서버 실행

-> 서버 실행이 안됨

보안 그룹 장애 실습

인바운드 규칙 편집

80포트 추가 후 다시 진행

결과 화면

상태 확인 및 HTTP 서버 종료

free -h
df -h
top

직접 실습 후 결과 확인

🚨트러블 슈팅) EC2 SSH 접속 실패 (Operation timed out) — Private Subnet 때문에 발생한 문제

EC2에 SSH로 접속하려고 했는데 아래와 같은 오류가 발생했다.

ssh: connect to host 13.xxx.xxx.xxx port 22: Operation timed out

또한 포트 연결 테스트를 해봐도 동일한 문제가 발생했다.

nc -vz 13.xxx.xxx.xxx 22
→ Operation timed out

처음에는 다음과 같은 문제들을 의심했다.

• EC2 인스턴스가 꺼져 있는 문제
• SSH Key(.pem) 문제
• Security Group 설정 문제
• 현재 네트워크에서 22포트 차단 문제

하지만 모든 설정을 확인해도 문제는 해결되지 않았다.

🔎 문제 원인

EC2 인스턴스의 Subnet 설정을 확인해보니 다음과 같이 되어 있었다.

my-subnet-private1-ap-northeast-2a

즉, Private Subnet에 EC2가 생성되어 있었다.

AWS 네트워크 구조에서 Subnet은 크게 두 가지로 나뉜다.

Private Subnet에 위치한 EC2는 다음 특징을 가진다.

• 외부에서 직접 SSH 접속 불가
• Public IP가 있어도 외부 접근 불가
• 내부 네트워크(VPC 내부)에서만 접근 가능

따라서 아무리 Security Group에서 22번 포트를 열어도 외부에서 접근할 수 없었다.

💥 왜 이런 일이 발생했을까?

EC2 생성 시 Network 설정에서 다음과 같은 선택을 했었다.

Subnet
→ my-subnet-private1-ap-northeast-2a

Public Subnet이 아닌 Private Subnet을 선택한 것이 원인이었다.

🛠 해결 방법

EC2를 Public Subnet에 다시 생성

새 인스턴스를 생성하면서 다음과 같이 설정했다.

Instance Name: sparta-ec2
VPC: my-vpc
Subnet: public subnet
Auto assign public IP: Enable

새로운 인스턴스(sparta-ec2) 생성 후 다시 SSH 접속을 시도했다.

ssh -i ec2-key.pem ec2-user@퍼블릭IP

이번에는 정상적으로 접속이 되었다.

📚 이번 문제로 배운 점

이번 트러블슈팅을 통해 AWS 네트워크 구조에서 중요한 개념을 이해하게 되었다.

1️⃣ Public Subnet

• Internet Gateway 연결
• 외부에서 직접 접근 가능

2️⃣ Private Subnet

• 외부 접근 불가
• 내부 서비스용

3️⃣ Security Group이 열려 있어도 Subnet 구조에 따라 접근이 불가능할 수 있다.

✏️ 정리

EC2를 Private Subnet에 생성하면 외부에서 SSH 접속이 불가능하다.

AWS를 처음 사용할 때 Security Group만 생각하고 Subnet 구조를 놓치는 경우가 많다. 이번 경험을 통해 VPC 네트워크 구조를 먼저 이해하는 것이 중요하다는 것을 알게 되었다.

이번 단계에서는 기존 필수 기능 위에 다음 작업을 진행했다.

1. JWT 인증 구조 리팩토링
2. 인증 책임 분리
3. ArgumentResolver 활용
4. 단위 테스트 작성
5. 테스트 커버리지 측정

단순히 기능을 추가하는 것이 아니라 코드 구조 개선과 테스트 가능한 구조를 만드는 것에 집중했다.

Lv5 JWT 인증 구조 개선

문제 상황

JWT 인증 로직을 구현할 때 처음에는 대부분의 로직이 JwtFilter에 집중되어 있었다.

기존 JwtFilter는 다음 역할을 모두 수행하고 있었다.

JwtFilter

• 토큰 검증
• Claims 추출
• 사용자 정보 request 저장
• 관리자 권한 검사

즉 하나의 클래스가 너무 많은 역할을 가지고 있었다.

이 구조는 다음 문제를 만들 수 있다.

1. 클래스의 책임이 너무 많아짐
2. 테스트가 어려워짐
3. 코드 유지보수가 어려워짐

이 문제는 객체지향 설계 원칙 중 하나인 SRP(Single Responsibility Principle) 를 위반하는 구조였다.

SRP는 하나의 클래스는 하나의 책임만 가져야 한다는 원칙이다.

해결 방법

JWT 인증 관련 로직을 JwtAuthHelper 클래스로 분리하였다.

구조는 다음과 같이 변경하였다.

기존 구조

JwtFilter
 -> validate token
 -> extract claims
 -> set request attribute
 -> check admin role

개선 구조

JwtFilter
 -> JwtAuthHelper

JwtAuthHelper

validateAndExtractClaims()
setUserAttributes()
validateAdminAccess()

이렇게 인증 관련 로직을 Helper 클래스로 이동시켰다.

JwtAuthHelper

토큰 검증과 Claims 추출을 담당하는 메서드이다.

public Claims validateAndExtractClaims(HttpServletRequest request) {
    String bearerJwt = request.getHeader("Authorization");

    if (bearerJwt == null) {
        throw new IllegalArgumentException("인증 헤더가 없습니다.");
    }

    String jwt = jwtUtil.substringToken(bearerJwt);
    Claims claims = jwtUtil.extractClaims(jwt);

    if (claims == null) {
        throw new IllegalArgumentException("유효하지 않은 토큰입니다.");
    }

    return claims;
}

이 메서드는 다음 순서로 동작한다.

Authorization Header 확인

• Bearer 토큰 분리
• JWT Claims 추출

JWT에서 Claims는 토큰에 담긴 사용자 정보를 의미한다.

예를 들어

userId
email
userRole

같은 정보들이 Claims에 포함된다.

사용자 정보 request 저장

JWT에서 추출한 정보를 request attribute로 저장하였다.

public void setUserAttributes(HttpServletRequest request, Claims claims) {
    request.setAttribute("userId", Long.parseLong(claims.getSubject()));
    request.setAttribute("email", claims.get("email"));
    request.setAttribute("userRole", claims.get("userRole"));
}

이렇게 저장한 이유는 이후 단계에서 다음 구조로 사용하기 위해서이다.

JwtFilter
 -> request attribute 저장
 -> ArgumentResolver
 -> Controller

즉 Controller에서는 request를 직접 사용하지 않고 AuthUser 객체로 받을 수 있게 된다.

관리자 권한 검사

관리자 API 접근 시 권한을 검사하는 로직이다.

public void validateAdminAccess(String url, Claims claims) {
    UserRole userRole = UserRole.valueOf(claims.get("userRole", String.class));

    if (url.startsWith("/admin") && !UserRole.ADMIN.equals(userRole)) {
        throw new IllegalArgumentException("접근 권한이 없습니다.");
    }
}

여기서 중요한 포인트는 다음이다.

url.startsWith("/admin")

즉 관리자 API 경로는

/admin/comments
/admin/users

같이 시작하도록 설계되어 있기 때문에 이 경로를 기준으로 권한 검사를 수행하도록 구현했다.

구조 개선 결과

기존 구조

JwtFilter
 -> 인증
 -> 인가
 -> 사용자 정보 처리
 -> 토큰 처리

개선 구조

JwtFilter
 -> JwtAuthHelper

즉

Filter -> 요청 흐름 제어 Helper -> 인증 로직 처리

로 역할을 분리하였다.

Lv6 코드 구조 개선 및 리팩토링

문제 인식

기능 구현이 완료된 후 코드를 다시 확인하면서 다음 문제를 발견했다.

1. 인증 정보를 Controller에서 직접 꺼내는 코드 존재
2. request attribute 접근 코드 반복
3. 테스트 작성이 어려운 구조

예를 들어 기존 방식은 다음과 같았다.

Long userId = (Long) request.getAttribute("userId");

이 방식은 다음 문제를 가진다.

1. Controller가 HttpServletRequest에 의존
2. 인증 정보 처리 코드가 반복됨
3. 테스트 작성이 어려움

해결 방법

Spring에서 제공하는 HandlerMethodArgumentResolver 를 활용하였다.

ArgumentResolver는 Controller의 파라미터를 자동으로 생성해주는 기능이다.

즉 Controller에서는 request를 직접 다루지 않아도 된다.

AuthUserArgumentResolver

Long userId = (Long) request.getAttribute("userId");
String email = (String) request.getAttribute("email");
UserRole userRole = UserRole.of((String) request.getAttribute("userRole"));

return new AuthUser(userId, email, userRole);

이 클래스의 역할은 다음과 같다.

request attribute에서 인증 정보를 가져온다 -> AuthUser 객체 생성 -> Controller 파라미터로 전달

Controller 코드 개선

기존 방식

Long userId = (Long) request.getAttribute("userId");

개선 방식

public ResponseEntity<CommentSaveResponse> saveComment(
        @Auth AuthUser authUser,
        ...
)

Controller에서는 AuthUser 객체만 사용하면 된다.

구조 개선 효과

Controller -> 인증 로직 제거 ArgumentResolver -> 인증 객체 생성 Filter -> request attribute 저장

즉 다음 구조가 만들어졌다.

JwtFilter
 -> JwtAuthHelper
 -> request attribute 저장

ArgumentResolver
 -> AuthUser 객체 생성

Controller
 -> AuthUser 사용

이 구조는 실제 Spring Security의 인증 흐름과도 유사하다.

Lv6 벨로그

Lv 6. 위 제시된 기능 이외 ‘내’가 정의한 문제와 해결 과정 - jiiimni 벨로그

Lv7 테스트 코드 작성 및 커버리지 측정

이번 단계에서는 서비스 로직과 인증 로직에 대한 단위 테스트를 작성하였다.

테스트 작성 목적은 다음과 같다.

1. 비즈니스 로직 검증
2. 리팩토링 안정성 확보
3. 코드 품질 향상

작성한 테스트

Service 테스트

CommentServiceTest
ManagerServiceTest
AuthServiceTest
UserServiceTest

Config 테스트

JwtAuthHelperTest
GlobalExceptionHandlerTest
WebConfigTest
FilterConfigTest

테스트 커버리지

IntelliJ Coverage 기준

전체 클래스 커버리지 77% 메서드 커버리지 73% 라인 커버리지 76% Domain 패키지 82% Config 패키지 81%

테스트 작성 예시

@Test
void 댓글_생성에_성공한다() {

    given(todoRepository.findById(anyLong()))
            .willReturn(Optional.of(todo));

    CommentSaveResponse response =
            commentService.saveComment(authUser, 1L, request);

    assertEquals("댓글", response.getContents());
}

이 테스트는 다음 흐름을 검증한다.

Todo 존재 여부 확인 -> Comment 생성 -> Response 반환

테스트 작성하면서 알게 된 점

테스트 코드를 작성하면서 다음을 많이 느꼈다.

1. 테스트 가능한 구조가 중요하다
2. 책임 분리가 되어 있어야 테스트가 쉽다
3. 테스트 코드가 리팩토링 안정성을 높여준다

특히 JwtFilter 구조를 리팩토링하면서 테스트 코드 작성이 훨씬 쉬워졌다.

트러블슈팅

JWT Claims 테스트 오류

테스트 코드 작성 중 다음 오류가 발생했다.

Cannot resolve symbol Claims

원인은 build.gradle 설정이었다.

기존 설정

compileOnly 'io.jsonwebtoken:jjwt-api'

compileOnly는 테스트 클래스패스에 포함되지 않는다.

그래서 테스트 코드에서 Claims를 사용할 수 없었다.

해결 방법

다음과 같이 수정하였다.

implementation 'io.jsonwebtoken:jjwt-api'

이후 테스트 코드에서 Claims를 정상적으로 사용할 수 있었다.

회고

이번 도전 기능에서는 단순한 기능 구현보다 코드 구조 개선과 테스트 코드 작성 경험을 많이 할 수 있었다.

JWT 인증 구조 리팩토링 -> 책임 분리 -> ArgumentResolver 활용 -> 테스트 코드 작성

이 과정을 통해 Spring 애플리케이션 구조를 더 깊이 이해할 수 있었다.

또한 Filter -> Helper -> Resolver -> Controller 구조는 Spring Security의 인증 흐름과도 유사하다는 점에서 의미 있는 경험이었다.

테스트 코드 작성 과정에서는 AI를 참고하여 테스트 구조와 작성 방법을 학습하였다.

단순히 코드를 그대로 사용하는 것이 아니라 테스트 동작 원리를 이해하고 프로젝트 구조에 맞게 수정하여 적용하였다.

이를 통해 단위 테스트 작성 방식과 테스트 커버리지 측정에 대한 이해도를 높일 수 있었다.

1. 문제 인식 및 정의

Lv5에서 관리자 API 로깅 기능(Interceptor + AOP)을 구현하면서 WebConfig를 수정하였다. 이 과정에서 AuthUserArgumentResolver를 생성자 주입 방식으로 관리하도록 구조를 정리하였다.

기존 코드에서는 HandlerMethodArgumentResolver를 등록할 때 아래처럼 직접 객체를 생성할 수도 있었다.

resolvers.add(new AuthUserArgumentResolver());

하지만 Config 구조를 정리하면서 다음과 같이 의존성 주입(DI) 방식으로 변경하였다.

private final AuthUserArgumentResolver authUserArgumentResolver;

그런데 실행 과정에서 다음과 같은 오류가 발생했다.

Could not autowire. No beans of 'AuthUserArgumentResolver' type found

즉, WebConfig에서 AuthUserArgumentResolver를 주입받으려고 했지만 스프링 컨테이너에 해당 클래스가 Bean으로 등록되어 있지 않아 객체를 찾지 못하는 문제였다.

이 문제의 원인은 다음과 같다.

• AuthUserArgumentResolver가 스프링 Bean으로 등록되어 있지 않음
• WebMvcConfigurer에서 Resolver를 등록하려면 Bean 등록 + Config 등록 두 단계가 필요

결국 Config 클래스와 Bean 등록 구조를 명확하게 정리할 필요가 있었다.

2. 해결 방안

2-1. 의사결정 과정

AuthUserArgumentResolver를 스프링 Bean으로 등록하는 방법은 크게 두 가지가 있었다.

방법 1. @Component를 사용한 Bean 등록

@Component
public class AuthUserArgumentResolver implements HandlerMethodArgumentResolver

방법 2. @Configuration에서 @Bean으로 직접 등록

@Bean
public AuthUserArgumentResolver authUserArgumentResolver() {
    return new AuthUserArgumentResolver();
}

이번 프로젝트에서는 방법 1 (@Component)를 선택하였다.

선택 이유는 다음과 같다.

• ArgumentResolver는 여러 컨트롤러에서 재사용되는 컴포넌트
• 스프링이 직접 관리하는 Bean으로 등록하는 것이 구조적으로 더 자연스러움
• Config 클래스의 책임을 최소화할 수 있음

2-2. 해결 과정

1) AuthUserArgumentResolver를 Bean으로 등록

@Component
public class AuthUserArgumentResolver implements HandlerMethodArgumentResolver {

이렇게 하면 스프링 컨테이너가 자동으로 Bean으로 등록한다.

2) WebConfig에서 ArgumentResolver 등록

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {

    private final AuthUserArgumentResolver authUserArgumentResolver;
    private final AdminApiInterceptor adminApiInterceptor;

    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(authUserArgumentResolver);
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(adminApiInterceptor)
                .addPathPatterns("/admin/comments/*")
                .addPathPatterns("/admin/users/*");
    }
}

이 과정을 통해

• AuthUserArgumentResolver는 스프링 Bean
• WebConfig는 Resolver를 Spring MVC에 등록하는 역할

로 책임이 명확하게 분리되었다.

3. 해결 완료

3-1. 회고

이번 문제를 통해 Spring MVC의 ArgumentResolver 동작 구조를 명확히 이해할 수 있었다.

특히 다음 두 가지 포인트가 중요했다.

1) ArgumentResolver는 자동 등록되지 않는다

단순히 클래스를 만드는 것만으로는 동작하지 않는다.

다음 두 단계가 필요하다.

1. Bean 등록
2. WebMvcConfigurer.addArgumentResolvers 등록

2) Config 구조가 명확해야 오류를 줄일 수 있다

Config 클래스가 여러 개로 나뉘거나 Bean 등록이 누락되면

Could not autowire
No beans found

같은 오류가 쉽게 발생한다.

이번 경험을 통해

• 스프링 Bean 등록 방식
• WebMvcConfigurer의 역할
• ArgumentResolver 동작 방식

을 실제 오류 해결 과정을 통해 이해할 수 있었다.

3-2. 전후 데이터 비교

Lv6. JwtFilter에서 인증과 인가 책임 분리

1. 문제 인식 및 정의

현재 JwtFilter는 인증, 인가, 사용자 정보 세팅, 에러 응답 생성까지 모두 담당하고 있었다.

하나의 클래스에 너무 많은 책임이 몰려 있어 유지보수성과 가독성이 떨어진다고 판단했다.

1. JWT 토큰 존재 여부 확인  
2. JWT 유효성 검증  
3. Claims 추출 및 사용자 정보 저장  
4. 관리자 권한 검증  
5. 에러 응답 생성

즉 하나의 클래스가 인증 과 인가 그리고 예외 처리까지 담당하고 있었다.

• 클래스의 책임이 과도하게 커짐
• 유지보수 어려움
• 테스트 어려움
• 코드 가독성 저하

2. 해결 방안

2-1. 의사결정 과정

처음에는 Filter를 인증용/인가용 두 개로 분리하는 구조도 고민했다. 하지만 현재 프로젝트 규모와 과제 범위를 고려했을 때, 먼저 JwtFilter를 얇게 만들고 JWT 처리 로직을 별도 helper로 위임하는 방식이 가장 적절하다고 판단했다.

각 클래스의 역할은 다음과 같다.

2-2. 해결 과정

JwtAuthHelper 클래스를 생성했다.

claims 추출, request attribute 저장, admin 권한 체크를 JwtAuthHelper로 이동했다.

JwtFilter는 요청 흐름 제어와 예외 응답만 담당하도록 수정했다.

@RequiredArgsConstructor
public class JwtAuthHelper {

    private final JwtUtil jwtUtil;

    public Claims validateAndExtractClaims(HttpServletRequest request) {
        String bearerJwt = request.getHeader("Authorization");

        if (bearerJwt == null) {
            throw new IllegalArgumentException("인증 헤더가 없습니다.");
        }

        String jwt = jwtUtil.substringToken(bearerJwt);
        Claims claims = jwtUtil.extractClaims(jwt);

        if (claims == null) {
            throw new IllegalArgumentException("유효하지 않은 토큰입니다.");
        }

        return claims;
    }

    public void setUserAttributes(HttpServletRequest request, Claims claims) {
        request.setAttribute("userId", Long.parseLong(claims.getSubject()));
        request.setAttribute("email", claims.get("email"));
        request.setAttribute("userRole", claims.get("userRole"));
    }

    public void validateAdminAccess(String url, Claims claims) {
        UserRole userRole = UserRole.valueOf(claims.get("userRole", String.class));

        if (url.startsWith("/admin") && !UserRole.ADMIN.equals(userRole)) {
            throw new IllegalArgumentException("접근 권한이 없습니다.");
        }
    }
}

3. 해결 완료

3-1. 회고

이번 리팩토링을 통해 인증과 인가를 코드 구조 상에서 분리해서 생각하는 연습을 할 수 있었다.

완전히 별도 Filter로 분리하지는 않았지만, 최소한 하나의 클래스가 모든 책임을 가지는 구조는 개선할 수 있었다.

특히 다음 개념을 명확히 이해하게 되었다.

3-2. 전후 데이터 비교

• Lv0: 애플리케이션 실행을 위한 JWT 키/DB 설정
• Lv1: @Auth AuthUser 파라미터 바인딩을 위한 ArgumentResolver 등록
• Lv2: 회원가입/로그인 및 비밀번호 검증 로직 리팩토링(가독성/책임 분리)
• Lv3: N+1 해결 (fetch join -> EntityGraph로 교체)
• Lv4: 테스트 코드 수정 + 서비스 로직 수정으로 테스트 실패 원인 제거

Lv0. 애플리케이션 실행 (JWT 키 / DB 설정)

문제 상황

처음 프로젝트 실행을 위해 application.yml에 JWT secret, datasource 설정이 필요했다.

예시:

jwt:
  secret:
    key: (base64 key)

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/expert
    username: root
    password: 12345678
    driver-class-name: com.mysql.cj.jdbc.Driver

jpa:
  hibernate:
    ddl-auto: create

실행 로그에서 Tomcat 8080, Hibernate, HikariCP 모두 정상 기동되면 Lv0은 통과로 볼 수 있다.

트러블슈팅 1)

처음에는 application-local.yml에 DB 비밀번호/JWT 키를 그대로 넣고 커밋해버렸다. 그 결과 GitHub 커밋 diff에서 그대로 노출되는 걸 확인했다.

내가 선택한 방식 (노출 방지)

• 민감 정보는 로컬 전용 파일(application-local.yml) 로 관리
• 깃에는 환경변수 placeholder만 남김
• 그리고 이미 올라간 히스토리는 git filter-repo로 정리

application.yml은 이렇게 바꾸었다:

jwt:
  secret:
    key: ${JWT_SECRET_KEY}

spring:
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}

그리고 application-local.yml은 .gitignore에 추가해서 추적 제외.

히스토리에서 파일 완전 제거

이미 커밋 히스토리에 비밀번호가 남으면 “파일을 삭제했더라도” 과거 커밋에서 볼 수 있다. 그래서 아래처럼 히스토리에서 제거했다.

git filter-repo --force --path src/main/resources/application-local.yml --invert-paths

이 과정에서 origin remote가 자동 제거되는 이슈가 있었고, remote를 다시 잡아야 push가 가능했다.

(이건 다음에 다시 같은 실수 안 하려고 꼭 기록해둔다.)

Lv1. ArgumentResolver 등록 (AuthUser 주입)

요구사항

컨트롤러에서 이렇게 받을 수 있어야 한다:

@PostMapping("/todos")
public ResponseEntity<TodoSaveResponse> saveTodo(
        @Auth AuthUser authUser,
        @Valid @RequestBody TodoSaveRequest todoSaveRequest
) { ... }

즉, @Auth + AuthUser 조합으로 들어오면 필터에서 넣어둔 request attribute를 꺼내서 AuthUser로 만들어 주입해야 한다.

트러블슈팅 2) Resolver 만들었는데 왜 동작을 안 하지?

원인

HandlerMethodArgumentResolver는 구현만 하면 자동으로 적용되지 않는다. 반드시 WebMvcConfigurer에서 등록해야 한다.

등록을 빼먹으면 컨트롤러에서 @Auth AuthUser를 받을 때 바인딩이 안 되거나, 예상치 못한 에러가 발생한다.

해결: WebConfig에 Resolver 등록

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers){
        resolvers.add(new AuthUserArgumentResolver());
    }
}

AuthUserArgumentResolver 구현 의도

public class AuthUserArgumentResolver implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        boolean hasAuthAnnotation = parameter.getParameterAnnotation(Auth.class) != null;
        boolean isAuthUserType = parameter.getParameterType().equals(AuthUser.class);

        // @Auth 어노테이션과 AuthUser 타입이 함께 사용되지 않은 경우 예외 발생
        if (hasAuthAnnotation != isAuthUserType) {
            throw new AuthException("@Auth와 AuthUser 타입은 함께 사용되어야 합니다.");
        }

        return hasAuthAnnotation;
    }

    @Override
    public Object resolveArgument(...) {
        HttpServletRequest request = (HttpServletRequest) webRequest.getNativeRequest();

        Long userId = (Long) request.getAttribute("userId");
        String email = (String) request.getAttribute("email");
        UserRole userRole = UserRole.of((String) request.getAttribute("userRole"));

        return new AuthUser(userId, email, userRole);
    }
}

내가 이렇게 짠 이유

• supportsParameter에서 @Auth와 AuthUser를 강제 묶음 처리 -> 컨트롤러 개발자가 실수로 @Auth String email 같은 형태로 쓰면 즉시 예외로 알려줌
• resolveArgument는 JwtFilter에서 저장한 attribute를 그대로 꺼내 인증 정보 전달 책임을 한 곳에 모음

Lv2. 코드 개선 (리팩토링)

1) Early Return 적용 (Signup 로직 개선)

문제

기존 코드에서는 조건문이 중첩되는 구조였다.

예를 들어 이메일 중복 체크 같은 로직에서 if 블록 안에 로직이 계속 들어가는 형태였다.

이 방식은 코드가 길어질수록 다음과 같은 문제가 발생한다.

• 조건문이 깊어짐 (Nested if)
• 핵심 로직 파악이 어려움
• 가독성이 떨어짐

해결: Early Return 적용

Early Return은 조건이 만족되지 않으면 바로 return 또는 예외를 던지는 방식이다.

if (userRepository.existsByEmail(signupRequest.getEmail())) {
    throw new InvalidRequestException("이미 존재하는 이메일입니다.");
}

그 다음에 정상 로직을 바로 진행한다.

User savedUser = userRepository.save(
        new User(
                signupRequest.getEmail(),
                encodedPassword,
                signupRequest.getUserName(),
                userRole
        )
);

Early Return을 적용한 이유

Early Return을 사용하면 다음 장점이 있다.

• 코드 깊이가 줄어든다
• 정상 흐름이 더 잘 보인다
• 예외 케이스를 먼저 처리할 수 있다

즉,

"예외 상황 먼저 처리 -> 정상 로직 실행"

이라는 구조가 만들어진다.

이 패턴은 Spring 서비스 로직에서 많이 사용하는 패턴이다.

2) WeatherClient 불필요한 if-else 제거

WeatherClient 코드에서 다음과 같은 구조가 있었다.

if (!HttpStatus.OK.equals(responseEntity.getStatusCode())) {
    throw new ServerException(...);
} else {
    if (weatherArray == null || weatherArray.length == 0) {
        throw new ServerException(...);
    }
}

여기서 문제는

• 불필요한 else 블록
• 조건문 중첩
• 가독성 저하

였다.

개선 방법

불필요한 else를 제거하고 조건을 분리했다.

if (!HttpStatus.OK.equals(responseEntity.getStatusCode())) {
    throw new ServerException("날씨 데이터를 가져오는데 실패했습니다.");
}

if (weatherArray == null || weatherArray.length == 0) {
    throw new ServerException("날씨 데이터가 없습니다.");
}

이렇게 변경한 이유

불필요한 else는 코드 가독성을 떨어뜨린다.

조건이 실패하면 바로 예외를 던지고 정상 흐름을 이어가는 방식이 더 자연스럽다.

이 역시 Early Fail / Guard Clause 패턴이라고 한다.

3) 비밀번호 검증 로직을 DTO Validation으로 이동

기존 코드에서는 비밀번호 검증을 서비스 레이어에서 직접 수행하고 있었다.

if (userChangePasswordRequest.getNewPassword().length() < 8 ||
        !userChangePasswordRequest.getNewPassword().matches(".*\\d.*") ||
        !userChangePasswordRequest.getNewPassword().matches(".*[A-Z].*")) {
    throw new InvalidRequestException("새 비밀번호는 8자 이상이어야 하고, 숫자와 대문자를 포함해야 합니다.");
}

이 방식은 다음 문제가 있다.

• 서비스 로직이 길어짐
• 검증 로직이 여러 서비스에 흩어질 수 있음
• 재사용성이 떨어짐

해결: DTO Validation 사용

DTO에 Validation을 적용했다.

@NotBlank
private String newPassword;

그리고 Controller에서

@Valid

를 사용하여 자동 검증하도록 했다.

Validation을 DTO로 옮긴 이유

Spring에서는 입력값 검증을 DTO에서 처리하는 것이 일반적인 패턴이다.

이렇게 하면

• 서비스 로직이 단순해짐
• 책임 분리 가능
• 코드 재사용 가능
• 유지보수성 증가

Lv2 코드 개선을 통해 얻은 것

이번 리팩토링을 통해 단순히 기능 구현을 넘어서

• 가독성 있는 코드 작성 방법
• 서비스 로직을 단순하게 유지하는 방법
• Spring Validation의 활용 방식

을 이해할 수 있었다.

특히,

"비즈니스 로직과 검증 로직을 분리하는 것"

이 서비스 레이어 설계에서 매우 중요하다는 것을 느꼈다.

Lv3. N+1 해결 (fetch join -> EntityGraph로 변경)

문제 시나리오

getTodos()에서 Todo 목록 조회 후 todo.getUser()를 접근한다.

Todo.user는 LAZY이기 때문에, Todo N개 조회 후 user를 접근하는 순간 N번 추가 쿼리가 발생할 수 있다 -> N+1.

기존 코드는 JPQL fetch join을 사용하고 있었다:

public interface TodoRepository extends JpaRepository<Todo, Long> {

    @Query("SELECT t FROM Todo t LEFT JOIN FETCH t.user u ORDER BY t.modifiedAt DESC")
    Page<Todo> findAllByOrderByModifiedAtDesc(Pageable pageable);

    @Query("SELECT t FROM Todo t " +
            "LEFT JOIN FETCH t.user " +
            "WHERE t.id = :todoId")
    Optional<Todo> findByIdWithUser(@Param("todoId") Long todoId);

    int countById(Long todoId);
}

요구사항: EntityGraph로 동일 동작 구현

EntityGraph 방식 예시 (최종 목표 형태)

@EntityGraph(attributePaths = {"user"})
Page<Todo> findAllByOrderByModifiedAtDesc(Pageable pageable);

그리고 단건 조회도 동일하게:

@EntityGraph(attributePaths = {"user"})
Optional<Todo> findById(Long todoId);

주의: @EntityGraph는 “연관 엔티티를 함께 로딩”하도록 힌트를 주는 방식이고, fetch join처럼 직접 JPQL을 쓰지 않아도 N+1을 방지할 수 있다.

Lv4. 테스트 코드 수정 + 서비스 로직 보완

Lv4는 “코드가 맞는데 테스트가 틀림 / 테스트는 맞는데 로직이 바뀌어서 깨짐” 같은 상황을 직접 다루게 했다.

(1) PasswordEncoderTest 수정

문제

matches() 메서드 파라미터 순서를 잘못 넣으면 테스트가 실패한다.

정상은:

boolean matches = passwordEncoder.matches(rawPassword, encodedPassword);

encoded를 raw처럼 넣으면 당연히 비교가 안 맞는다.

(2) ManagerServiceTest: Todo 없을 때 NPE가 아니라 InvalidRequestException

내가 고친 방향

• 테스트 메서드명부터 컨텍스트에 맞게 수정 (NPE가 아니라 InvalidRequestException을 기대해야 함)
• 예외 타입 + 메시지를 동시에 검증하도록 assertThatThrownBy를 사용

assertThatThrownBy(() -> managerService.getManagers(todoId))
    .isInstanceOf(InvalidRequestException.class)
    .hasMessage("Todo not found");

왜 assertThatThrownBy를 썼나?

• 예외 검증을 체이닝으로 한 번에 표현 가능 -> 가독성 올라감
• assertThrows는 메시지 검증까지 하려면 예외를 변수로 받아서 추가 검증해야 함 -> 의도가 길어짐

(3) CommentServiceTest: Todo 없을 때 던지는 예외가 다르다

테스트는 ServerException을 기대했지만, 실제 컨텍스트(서비스 구현)는 InvalidRequestException을 던질 가능성이 높다.

즉, 테스트의 기대값(예외 타입/메시지)을 서비스 컨벤션과 맞춰야 테스트가 의미를 가진다.

(4) 핵심 트러블슈팅: todo.user가 null이면 NPE -> 서비스 로직 수정

증상

테스트에서 일부러 Todo.user = null로 만들었더니, 서비스 로직에서 아래가 터졌다:

todo.getUser().getId()

해결

권한 체크 전에 null 방어 로직을 넣었다.

if (todo.getUser() == null) {
    throw new InvalidRequestException("일정을 생성한 유저만 담당자를 지정할 수 있습니다.");
}

내가 이렇게 처리한 이유

• user가 null이면 권한 검증 자체가 불가능함 (비교할 대상이 없음)

• “NPE(런타임 오류)” 대신 “의도한 비즈니스 예외”로 바꾸면

  • 테스트도 안정화되고
  • API 사용자 입장에서도 에러 의미가 명확해진다

회고: 이번 과제로 얻은 것

• ArgumentResolver는 만들기보다 등록 누락이 더 흔한 실수라는 점
• 테스트는 “성공시키는 것”보다 왜 실패했는지 원인을 분해하는 과정이 훨씬 학습이 된다는 점
• 예외 처리의 목적은 “에러를 막는 것”이 아니라 의미 있는 실패를 만드는 것이라는 점 (NPE -> InvalidRequestException으로 변경한 케이스)

프로젝트 github 링크

CH3 프로젝트 github 링크

이번 팀 프로젝트에서 내가 맡은 파트는 관리자(Admin) 도메인이었다. 초반에는 인증(세션) 기능을 먼저 구현했고, 그 다음 단계로 “관리자 관리 기능” 체크리스트(READ/WRITE)를 끝까지 완성하는 게 목표였다.

✅ 내가 해야 했던 관리자 체크리스트

관리자 체크리스트에서 “Read/Write”는 아래 6개였다.

📌 READ

• 관리자 목록 조회(검색/정렬/필터/페이징)
• 관리자 상세 조회

📌 WRITE

• 관리자 정보 수정(이름/이메일/전화)
• 관리자 역할 변경
• 관리자 상태 변경
• 관리자 삭제(Soft Delete로 전환)

그리고 이 기능들은 승인/거부(approve/reject), 내 정보 조회/수정, 비밀번호 변경 같은 기존 기능과도 자연스럽게 연결된다.

🧩 내가 만든 구조(패키지/역할)

팀 컨벤션을 최대한 안 깨기 위해, admin 도메인은 아래처럼 정리했다.

admin
 ┣ controller
 ┣ dto
 ┃  ┣ request
 ┃  ┣ response
 ┃  ┗ session
 ┣ entity
 ┣ repository
 ┗ service
    ┣ AdminQueryService   (조회 전용)
    ┗ AdminCommandService (변경 전용)

왜 Query / Command를 나눴을까?

이건 “CQRS 맛보기” 방식이다.

• 조회(Read)는 검색 조건/정렬/페이징 같은 “쿼리 최적화” 중심
• 변경(Write)는 비즈니스 규칙/상태 변경/검증 중심

같은 서비스에 넣으면 코드가 섞여서 커지고, 팀 프로젝트에서는 충돌도 늘어난다. 그래서 아예 조회/수정 흐름을 분리했다.

READ 구현: 관리자 목록 조회 + 상세 조회

READ는 “관리자 목록 화면”을 만들기 위한 핵심 기능이다. 특히 백오피스는 데이터가 많아질수록 검색/필터/정렬/페이징이 중요하다.

1) 관리자 목록 조회에서 지원한 기능

지원 파라미터

• keyword: 이름/이메일 검색
• role: 역할 필터
• status: 상태 필터
• Pageable: 페이징 + 정렬

즉, 이런 요청이 가능하다:

• “운영 관리자만 보고 싶다”
• “승인대기 상태만 보고 싶다”
• “keyword=kim 으로 이름/이메일 검색”
• “페이지 2번, 10개씩”
• “createdAt desc 정렬”

2) Specification을 선택한 이유

관리자 목록 조회는 조건이 계속 변한다.

• keyword가 있을 수도 없을 수도
• role도 있을 수도 없을 수도
• status도 있을 수도 없을 수도

이걸 if문으로 QueryDSL 없이 처리하면:

• 메서드가 과도하게 늘어나거나
• 조건 조합마다 쿼리를 따로 만들게 된다.

그래서 JpaSpecificationExecutor + Specification으로 “조건 조합을 유연하게 붙이는 방식”을 택했다.

3) AdminSpecifications 예시

keyword 검색

• keyword가 없으면 null 반환 → 해당 조건은 적용 안 됨
• keyword가 있으면 name/email like 검색

public static Specification<Admin> keyword(String keyword) {
    if (keyword == null || keyword.isBlank()) return null;

    return (root, query, cb) -> cb.or(
            cb.like(cb.lower(root.get("adminName")), "%" + keyword.toLowerCase() + "%"),
            cb.like(cb.lower(root.get("email")), "%" + keyword.toLowerCase() + "%")
    );
}

4) AdminQueryService: 조회 전용 서비스

@Transactional(readOnly = true)
public Page<AdminListResponse> search(AdminSearchCondition condition, Pageable pageable) {
    Specification<Admin> spec = Specification.where(AdminSpecifications.keyword(condition.keyword()))
            .and(AdminSpecifications.role(condition.role()))
            .and(AdminSpecifications.status(condition.status()));

    return adminRepository.findAll(spec, pageable).map(AdminListResponse::from);
}

여기서 중요한 포인트

✅ @Transactional(readOnly = true)

• 조회는 readOnly로 실행 → 성능/안정성 측면에서 유리
• 팀원 리뷰로 “클래스 레벨 readOnly” 적용도 반영했음

✅ DTO 변환은 map(AdminListResponse::from)

• Entity를 그대로 반환하지 않고 응답 DTO로 변환
• 비밀번호 같은 민감 정보 노출 방지

5) Controller: searchAdmins

@GetMapping
public ApiResponse<Page<AdminListResponse>> searchAdmins(
        @ModelAttribute AdminSearchCondition condition,
        Pageable pageable,
        HttpSession session
) {
    requireSuperAdmin(session);
    return ApiResponse.success(HttpStatus.OK, adminQueryService.search(condition, pageable));
}

리뷰 반영 포인트 1) @ModelAttribute

처음엔 keyword, role, status를 각각 받아서 직접 condition을 new로 만들었다. 근데 팀원 리뷰로:

Spring MVC 바인딩을 활용하면 new로 생성하지 않아도 된다.

그래서 @ModelAttribute로 자동 바인딩을 적용했다.

리뷰 반영 포인트 2) import 누락 문제

내가 한 번 실수로 AdminStatus를 import 안 하고 풀패키지명을 그대로 적어버렸다.

@RequestParam com.example...AdminStatus status

리뷰에서 바로 지적 받았고, import로 정리했다.

WRITE 구현: 수정/역할/상태/삭제

WRITE는 “관리자 관리 화면에서 버튼 누르면 실행되는 기능”이다.

• 관리자 정보 수정 (이름/이메일/전화)
• 역할 변경
• 상태 변경
• 삭제

1) 관리자 정보 수정(updateAdmin)

핵심 검증: 이메일 중복 처리

수정은 가입과 달라서 기존 이메일이 그대로일 때는 중복 체크를 하면 안 됨

그래서 조건을 이렇게 넣었다:

if (!admin.getEmail().equals(request.email()) && adminRepository.existsByEmail(request.email())) {
    throw new CustomException(ErrorCode.ADMIN_EMAIL_DUPLICATED);
}

✅ 이메일이 변경될 때만 중복 체크

2) 역할 변경(changeRole)

@Transactional
public void changeRole(Long adminId, AdminRole role) {
    Admin admin = findAdmin(adminId);
    admin.changeRole(role);
}

• 실제 권한 체크는 Controller에서
• Entity는 상태 변경만 담당

3) 상태 변경(changeStatus)

@Transactional
public void changeStatus(Long adminId, AdminStatus status) {
    Admin admin = findAdmin(adminId);
    admin.changeStatus(status);
}

4) 삭제(deleteAdmin) - Soft Delete 전환

처음엔 물리 삭제를 했다.

adminRepository.delete(admin);

그런데 리뷰에서:

관리자 계정은 기록 추적이 중요한데 Hard Delete는 위험하다 status를 DELETED로 바꾸는 Soft Delete가 낫지 않나요?

그래서 Soft Delete로 변경했다.

public void delete() {
    this.status = AdminStatus.DELETED;
}

서비스는:

@Transactional
public void deleteAdmin(Long adminId) {
    Admin admin = findAdmin(adminId);
    admin.delete();
}

✅ DB row 삭제 X ✅ 상태로만 비활성 처리 ✅ 운영/감사 로그 관점에서 안전

트러블슈팅/리뷰 반영 정리

이번 단계에서 기능 구현보다 리뷰 반영으로 코드 품질을 올린 경험이 컸다.

1) 세션 키 하드코딩 제거

처음에는 문자열로 작성했는데

session.getAttribute("LOGIN_SUPER_ADMIN")

리뷰로 “상수화” 권장 -> SessionConst로 통일했다.

2) Service의 트랜잭션 전략 개선

팀원 리뷰:

클래스 레벨에 readOnly=true를 걸고 수정 메서드에만 @Transactional 붙이면 누락 방지된다.

그래서:

• QueryService -> 클래스 레벨 readOnly
• CommandService -> 기본 readOnly + 쓰기만 @Transactional

3) 비밀번호 변경 검증 로직 위치 개선

서비스가 검증을 다 하면 Service가 도메인 규칙을 너무 많이 알게 된다.

그래서 Admin 엔티티로 책임을 넘겼다.

public void changePasswordWithValidation(...) {
   // current mismatch
   // new confirm mismatch
   // already used password
   // encode + 저장
}

도메인 규칙은 도메인에 서비스는 흐름만 제어

오늘 작업 요약

• 관리자 READ 기능 구현

  • 검색(keyword)
  • 필터(role, status)
  • 정렬/페이징(Pageable)
  • 목록/상세 조회 API

• 관리자 WRITE 기능 구현

  • 관리자 정보 수정
  • 역할 변경
  • 상태 변경
  • 삭제(Soft Delete 전환)

• 리뷰 반영

  • import 정리, 하드코딩 제거
  • @ModelAttribute 활용
  • 트랜잭션 readOnly 전략 개선
  • 비밀번호 변경 로직 도메인 위임

회고 (Keep / Problem / Try)

✅ Keep (만족)

• admin 패키지 구조를 팀 컨벤션에 맞춰 일관되게 유지
• Query/Command 분리로 충돌 가능성 감소
• 응답 포맷(ApiResponse)과 예외 포맷(ErrorCode) 유지

⚠️ Problem (불편)

• Soft Delete 적용 후 조회 제외 정책을 더 명확하게 해야 함
• URI prefix(/admins vs /api/admins) 통일 필요

🚀 Try (다음 개선)

• Soft Delete 된 계정은 기본 조회에서 제외되도록 정책 강화
• 관리 기능 인터셉터/ArgumentResolver로 권한 체크 공통화
• SuperAdmin 도메인 분리 구현 (ERD 기반)

https://documenter.getpostman.com/view/51133118/2sBXcGDzTV#086ea58f-0aa3-48f1-846e-e32e98d671df

팀 프로젝트에서 “백오피스 관리자” 파트를 맡게 되면서, 필수 기능 중 세션 기반 인증(쿠키/세션)을 먼저 구현했다.

구현한 기능 목록 (필수 4개)

• 관리자 회원가입 API (기본 상태: 승인대기 PENDING, 비밀번호 암호화 저장)
• 관리자 로그인 API (세션 생성 및 저장, ACTIVE만 로그인 가능)
• 관리자 로그아웃 API (세션 invalidate)
• 세션 만료 시간/쿠키 옵션(HttpOnly) 설정

1. 팀 컨벤션에 맞춘 패키지 구조

팀 프로젝트라서 내 마음대로 구조를 만들면 나중에 충돌이 나거나 유지보수가 어려워질 수 있다. 프로젝트 내부를 보니 도메인별로 묶는 방식이 사용되고 있었고, 공통 응답/예외 포맷도 이미 존재했다.

그래서 관리자 인증은 아래처럼 admin 도메인 패키지를 만들고 그 안에서 3-layer를 유지했다.

com.example.commercepilot
 ┣ admin
 ┃ ┣ controller
 ┃ ┣ dto
 ┃ ┃ ┣ request
 ┃ ┃ ┣ response
 ┃ ┃ ┗ session
 ┃ ┣ entity
 ┃ ┣ repository
 ┃ ┣ service
 ┣ config
 ┣ exception

팀 공통 포맷 재사용

• ApiResponse (성공/실패 응답 공통)
• ErrorCode, ErrorResponse
• GlobalExceptionHandler (CustomException + Validation 처리)

팀 컨벤션을 최대한 따라가면서, 내가 구현하는 기능만 자연스럽게 추가되도록 했다.

2. 관리자 회원가입 API 구현

2-1. 요구사항 핵심 정리

회원가입에서 놓치면 안 되는 포인트는 아래였다.

• 입력값 유효성 검증 (이메일 형식, 비밀번호 최소 8자, 전화번호 010-XXXX-XXXX, role 필수 등)
• 이메일 중복 체크
• 비밀번호 암호화 저장 (BCrypt 기반 PasswordEncoder)
• 가입 시 기본 상태: 승인대기(PENDING)

2-2. DTO(Validation) 설계 이유

회원가입 요청 DTO는 record로 만들고 Bean Validation을 붙였다. Controller에서 @Valid를 붙이면 Validation 실패 시 MethodArgumentNotValidException이 발생하고, 팀 공통 GlobalExceptionHandler에서 ApiResponse.fail(INVALID_INPUT_VALUE, fieldErrors) 형태로 내려줄 수 있다.

public record AdminSignupRequest(
    @NotBlank String name,
    @Email @NotBlank String email,
    @Size(min = 8) @NotBlank String password,
    @Pattern(regexp = "^010-\\d{4}-\\d{4}$") @NotBlank String callNumber,
    @NotNull AdminRole role
) {}

응답 DTO는 민감정보(비밀번호)는 절대 포함하지 않도록 최소 필드만 정의했다.

public record AdminSignupResponse(
    Long id,
    String name,
    String email,
    String callNumber,
    AdminRole role,
    AdminStatus status,
    LocalDateTime createdAt
) { ... }

🔎 왜 password를 응답에 안 넣는가?

리뷰에서도 실제로 나온 포인트인데, 해시된 비밀번호라도 응답으로 내려주는 건 보안상 적절하지 않다. 그래서 응답 DTO에 password는 아예 포함시키지 않았다.

2-3. Service 로직 설계 이유 (CommandService)

회원가입은 “데이터를 생성하는(쓰기)” 로직이다. 그래서 팀에서 추천하던 CQRS 맛보기 구조처럼, 쓰기 로직은 CommandService에 두고 확장 가능하도록 구성했다.

@Transactional
public AdminSignupResponse signup(AdminSignupRequest request) {
    if (adminRepository.existsByEmail(request.email())) {
        throw new CustomException(ErrorCode.ADMIN_EMAIL_DUPLICATED);
    }

    String encoded = passwordEncoder.encode(request.password());

    Admin admin = Admin.pending(
        request.name(),
        request.email(),
        encoded,
        request.callNumber(),
        request.role()
    );

    Admin saved = adminRepository.save(admin);
    return AdminSignupResponse.from(saved);
}

여기서 내가 신경쓴 부분

• 중복 이메일은 existsByEmail로 빠르게 체크
• 비밀번호는 PasswordEncoder.encode()로 저장 직전에 암호화
• 상태는 무조건 PENDING으로 고정 (승인 전에는 로그인 불가)

3. 로그인 API 구현 (세션 기반 인증)

3-1. 요구사항 핵심

로그인은 단순히 이메일/비밀번호만 맞으면 끝이 아니라, 계정 상태에 따라 로그인 가능 여부가 갈린다.

• ACTIVE만 로그인 가능
• PENDING/REJECTED/SUSPENDED/INACTIVE는 로그인 불가 + 명확한 메시지

또한 로그인 성공 시에는 서버 세션에 아래 정보를 저장해야 한다.

• adminId
• email
• role

3-2. 세션 저장 DTO + 세션 키 상수

세션에 저장하는 데이터는 최소한으로, 그리고 명확하게 하려고 별도 record로 뺐다.

public record LoginAdmin(Long adminId, String email, AdminRole role) {}

세션 key는 오타 방지 위해 상수로 관리했다.

public final class SessionConst {
    public static final String LOGIN_ADMIN = "LOGIN_ADMIN";
}

3-3. 로그인 Service 로직 (상태별 분기)

@Transactional(readOnly = true)
public void login(AdminLoginRequest request, HttpSession session) {
    Admin admin = adminRepository.findByEmail(request.email())
        .orElseThrow(() -> new CustomException(ErrorCode.LOGIN_FAILED));

    if (!passwordEncoder.matches(request.password(), admin.getPassword())) {
        throw new CustomException(ErrorCode.LOGIN_FAILED);
    }

    validateLoginStatus(admin.getStatus());

    LoginAdmin loginAdmin = new LoginAdmin(admin.getId(), admin.getEmail(), admin.getRole());
    session.setAttribute(SessionConst.LOGIN_ADMIN, loginAdmin);
}

🔎 왜 이메일 없음 / 비번 틀림은 같은 에러(LOGIN_FAILED)로 처리했나?

보안상 “이메일이 존재하는지”를 노출하면 안 되기 때문에 보통 로그인 실패는 동일하게 처리한다. 그래서 계정 존재 여부는 숨기고, 상태(승인대기/정지 등)는 요구사항에 맞게 명확히 분기했다.

4. 로그아웃 API 구현

로그아웃은 간단히 세션 무효화만 하면 된다.

public void logout(HttpSession session) {
    session.invalidate();
}

컨트롤러에서는 아래처럼 응답 data 없이 성공만 내려주도록 했다.

@PostMapping("/logout")
public ApiResponse<Void> logout(HttpSession session) {
    adminAuthService.logout(session);
    return ApiResponse.success(HttpStatus.OK);
}

5. 세션 만료시간/쿠키(HttpOnly) 설정

서버에서 세션을 오래 유지할지 결정해야 한다. 필수 요구사항 예시가 24시간이었고, 세션 쿠키는 XSS 위험을 줄이기 위해 HttpOnly 옵션을 사용했다.

application.properties

server.servlet.session.timeout=24h
server.servlet.session.cookie.http-only=true

6. 트러블슈팅

6-1. DTO 패키지 구조 때문에 “import 오류”가 났다

처음에는 DTO를 admin/dto 아래에 바로 두고 import를 작성했는데, 팀 구조를 따라가다 보니 dto/request, dto/response로 폴더를 나눴다.

그 상태에서 서비스 코드가 아래처럼 작성되어 있으면:

import com.example.commercepilot.admin.dto.AdminSignupRequest;

실제 DTO 경로는:

com.example.commercepilot.admin.dto.request.AdminSignupRequest

이라서 IntelliJ에서 Cannot resolve symbol 에러가 계속 났다.

해결:

• DTO 파일의 package 선언을 폴더 구조에 맞추고,
• Service/Controller import도 정확히 맞춰줬다.

6-2. “암호화된 비밀번호를 응답에 담는 게 적절한가요?” 리뷰 대응

서비스 로직에 encoded 변수가 보이다 보니, 리뷰어가 “응답에 password가 포함되는지”를 걱정해주셨다.

실제로는 AdminSignupResponse에 password 필드가 없고, from()에서도 매핑하지 않아 응답으로 나가지 않는다.

✅ 대응:

• AdminSignupResponse에 password가 없음을 코드로 설명
• “해시라도 응답에 포함하지 않는 것이 원칙”이라는 점을 확인

(추가로 안전하게 하려면 엔티티 password에 @JsonIgnore를 붙여 실수로 엔티티를 반환해도 노출되지 않게 막을 수도 있다.)

7. 회고

이번 인증 파트를 하면서 느낀 건, 기능 자체보다 팀 컨벤션에 맞춰 구조를 자연스럽게 끼워 넣는 것이 더 중요했다는 점이다.

• “내가 익숙한 구조”대로 만들면 빨리 만들 수 있지만,
• 팀 프로젝트는 결국 다 같이 유지보수할 수 있는 구조가 더 가치가 크다.

또한 로그인/회원가입은 실무에서도 민감한 영역이라

• 응답에 민감정보 포함 여부
• 실패 응답 메시지 정책
• 세션 보안 옵션(HttpOnly) 같은 세부 포인트가 중요하다는 걸 체감했다.

8. 다음 할 일

인증(세션) 4개를 끝낸 뒤에는 관리자 기능이 본격적으로 남아있다.

• 관리자 승인/거부(슈퍼관리자 세션 기반)
• 내 프로필 조회/수정
• 비밀번호 변경
• 관리자 목록/검색/정렬/필터/페이징
• 관리자 상세/수정/삭제/역할 변경/상태 변경

다음 글에서는 “슈퍼관리자 승인 프로세스(승인대기 -> 활성)”을 구현하면서 생긴 이슈들을 정리할 예정이다.

이전 과제에서 기능은 동작했지만, 한 가지 큰 문제가 있었다.

예외가 발생하면 대부분 400 또는 500으로만 내려갔다.

• 로그인 안 해도 400
• 존재하지 않는 일정도 400
• 이메일 중복도 500
• Validation 실패도 기본 에러 페이지

이 상태는 동작은 하지만 API답지 않은 상태였다.

그래서 Lv5에서는 단순 기능 추가가 아니라 API를 실무스럽게 다듬는 작업을 진행했다.

목표

• Validation 강화
• 전역 예외 처리 도입
• HTTP 상태 코드 명확히 분리
• 에러 응답 구조 통일

Validation 강화 (@Valid + DTO 중심 설계)

왜 DTO에 Validation을 넣었는가?

Validation은 Controller가 아니라 DTO에 두는 게 맞다.

• 데이터의 규칙은 데이터 구조에 정의하는 게 자연스럽다.
• Entity에는 비즈니스 로직만 두는 것이 좋다.
• 유지보수성이 올라간다.

수정한 코드

UserRequest

@NotBlank(message = "username은 필수입니다.")
@Size(max = 4, message = "username은 4글자 이내여야 합니다.")
private String username;

@Email(message = "email 형식이 올바르지 않습니다.")
@NotBlank(message = "email은 필수입니다.")
private String email;

@NotBlank(message = "password는 필수입니다.")
@Size(min = 8, message = "password는 최소 8자 이상이어야 합니다.")
private String password;

ScheduleRequest

@NotBlank(message = "title은 필수입니다.")
@Size(max = 10, message = "title은 10글자 이내여야 합니다.")
private String title;

Controller에 @Valid 적용

@PostMapping
public ResponseEntity<ScheduleResponse> create(
        @Valid @RequestBody ScheduleRequest request,
        HttpSession session
)

여기서 중요한 건:

DTO에만 Validation을 붙이면 아무 일도 안 일어난다. 반드시 @Valid를 Controller에서 붙여야 동작한다.

전역 예외 처리 도입 (@RestControllerAdvice)

이전까지는 예외가 발생하면:

• 500 Internal Server Error
• 기본 에러 응답
• JSON 구조가 통일되지 않음

그래서 전역 예외 처리 클래스를 추가했다.

exception 패키지 추가

exception
 ┣ CustomException
 ┣ ErrorResponse
 ┗ GlobalExceptionHandler

ErrorResponse 구조 통일

@Getter
public class ErrorResponse {

    private final LocalDateTime timestamp = LocalDateTime.now();
    private final int status;
    private final String message;
    private final Map<String, String> fieldErrors;
}

모든 에러는 이 구조로 내려가게 만들었다.

GlobalExceptionHandler

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(...) { ... }

    @ExceptionHandler(CustomException.class)
    public ResponseEntity<ErrorResponse> handleCustomException(...) { ... }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(...) { ... }
}

이제 어디서 예외가 터져도 이 클래스가 전부 받아서 처리한다.

CustomException 도입 (상태 코드 분리)

이전에는:

throw new IllegalArgumentException("로그인이 필요합니다.");

-> 전부 400

이건 명확하지 않다.

그래서 상태 코드를 포함한 예외 클래스를 만들었다.

CustomException

public class CustomException extends RuntimeException {

    private final HttpStatus status;

    public CustomException(HttpStatus status, String message) {
        super(message);
        this.status = status;
    }
}

Service에서 이렇게 변경

로그인 필요

throw new CustomException(HttpStatus.UNAUTHORIZED, "로그인이 필요합니다.");

-> 401

존재하지 않는 일정

.orElseThrow(() -> new CustomException(
        HttpStatus.NOT_FOUND,
        "해당 일정이 존재하지 않습니다."
));

-> 404

이메일 중복

if (userRepository.existsByEmail(request.getEmail())) {
    throw new CustomException(HttpStatus.CONFLICT, "이미 존재하는 이메일입니다.");
}

-> 409

Postman 실습

유저 생성

Validation 실패 (400)

{
  "title": "12345678901",
  "content": "내용"
}

로그인 하지 않고 일정 생성 (400)

로그인 안 함 (401)

POST /api/schedules

-> 401 Unauthorized

로그인- 이메일, 비밀번호 틀림 (401)

존재하지 않는 일정 (404)

GET /api/schedules/99999

-> 404 Not Found

이메일 중복 (409)

POST /api/users

같은 이메일 2번 요청

-> 409 Conflict

Test 계정 생성

"이미 존재하는 이메일입니다" 409 처리

트러블슈팅

이메일 중복 시 500 에러 발생

처음에는 이메일 중복 시 500이 발생했다.

원인은:

DB에 UNIQUE 제약이 걸려 있어서 DataIntegrityViolationException이 터진 것

이걸 해결하기 위해:

• UserRepository에 existsByEmail() 추가
• 저장 전에 사전 차단

결과: 500 -> 409 Conflict로 정상 변경

400과 401의 차이 이해

처음에는 로그인 안 한 상태도 400으로 처리했다.

하지만

• 400 -> 요청 형식이 잘못됨
• 401 -> 인증되지 않음

전역 예외 처리가 왜 필요한지 깨달음

예외를 Controller마다 처리하면 코드가 지저분해진다.

전역으로 처리하니:

• 코드가 깔끔해짐
• 에러 응답 구조 통일
• 유지보수성 증가

Lv6 – 비밀번호 암호화 적용 (BCrypt)

Lv3에서 password 필드를 추가했지만, 사실 그때는 평문 그대로 저장하고 있었다. 기능은 동작했지만 보안 관점에서는 치명적인 구조였다.

이번 Lv6에서는 비밀번호를 암호화하여 저장하고, 로그인 시에는 암호화된 값과 비교하도록 수정했다.

왜 암호화가 필요한가?

지금까지의 구조:

new User(
    request.getUsername(),
    request.getEmail(),
    request.getPassword()
);

그리고 로그인 시에는

if (!user.getPassword().equals(request.getPassword())) {
    ...
}

이 방식의 문제점은

• DB가 털리면 비밀번호가 그대로 노출됨
• 운영 환경에서는 절대 허용되지 않는 구조
• equals 비교는 보안적으로 취약

그래서 단방향 암호화(해시) 방식으로 전환했다.

build.gradle에 BCrypt 추가

implementation 'at.favre.lib:bcrypt:0.10.2'

Gradle을 reload한 뒤, 암호화 클래스를 추가했다.

PasswordEncoder 직접 구현

Spring Security를 쓰지 않고, 과제 요구사항에 맞게 직접 PasswordEncoder를 구현했다.

@Component
public class PasswordEncoder {

    public String encode(String rawPassword) {
        return BCrypt.withDefaults()
                .hashToString(BCrypt.MIN_COST, rawPassword.toCharArray());
    }

    public boolean matches(String rawPassword, String encodedPassword) {
        BCrypt.Result result = BCrypt.verifyer()
                .verify(rawPassword.toCharArray(), encodedPassword);

        return result.verified;
    }
}

• encode() -> 회원가입 시 암호화
• matches() -> 로그인 시 비교

UserService 수정 (회원가입 시 암호화)

기존 코드:

request.getPassword()

수정 코드:

String encodedPassword = passwordEncoder.encode(request.getPassword());

User saved = userRepository.save(
        new User(
                request.getUsername(),
                request.getEmail(),
                encodedPassword
        )
);

이제 DB에 저장되는 값은 다음과 같은 형태가 된다.

$2a$10$g9dS9s8sK...

로그인 로직 수정

이전:

if (!user.getPassword().equals(request.getPassword())) {

수정:

if (!passwordEncoder.matches(request.getPassword(), user.getPassword())) {
    throw new CustomException(HttpStatus.UNAUTHORIZED,
            "이메일 또는 비밀번호가 올바르지 않습니다.");
}

이제는 raw password vs encoded password를 안전하게 비교한다.

Postman 실습

회원가입

{
  "username": "lee",
  "email": "lee@test.com",
  "password": "12345678"
}

DB 확인 -> 암호화된 문자열 저장됨

로그인 성공

{
  "email": "lee@test.com",
  "password": "12345678"
}

-> 200 OK

로그인 실패 (틀린 비밀번호)

{
  "email": "lee@test.com",
  "password": "11111111"
}

-> 401 Unauthorized

트러블슈팅

1) 기존 유저 로그인 실패

암호화 적용 후, 기존에 평문으로 저장된 유저는 로그인에 실패했다.

이유는 간단하다.

• DB에는 평문
• 로그인 로직은 암호화 비교

그래서 테스트를 위해 새로 회원가입을 진행했다.

-> 암호화 적용 이후 생성된 유저만 정상 로그인 가능

2) equals 비교의 위험성 체감

단순 equals 비교는 보안적으로 매우 취약하다.

BCrypt는:

• salt 자동 적용
• 무차별 대입 공격 방지
• 단방향 해시

실무에서 가장 널리 사용되는 방식이라는 점도 직접 체감했다.

이번 단계에서 느낀 점

Lv5에서 예외 처리를 정리했다면, Lv6은 보안을 신경 쓰는 단계였다.

단순히 기능이 되는 API가 아니라, 운영 가능한 API로 발전하는 느낌이었다.

• 상태 코드 분리
• 전역 예외 처리
• 비밀번호 암호화

이제야 비로소 백엔드 API답다는 느낌이 들었다.

개발 환경

• Java 17
• Spring Boot
• Spring Data JPA
• MySQL
• Validation
• Lombok
• Postman

프로젝트 패키지 구조

kr.spartaclub.develop_scheduleapp
 ┣ config
 ┣ controller
 ┣ dto
 ┣ entity
 ┣ repository
 ┗ service

공통 설정: JPA Auditing (createdAt / updatedAt 자동)

Lv1부터 일정 생성/수정 시간을 응답에 포함해야 해서 Auditing을 먼저 잡았다.

1) JPA Auditing 활성화

JpaAuditingConfig.java

• @EnableJpaAuditing 붙이면 JPA가 엔티티 저장/수정 이벤트를 감지해서 시간을 자동으로 채워준다.

@Configuration
@EnableJpaAuditing
public class JpaAuditingConfig {
}

2) BaseTimeEntity

BaseTimeEntity.java

• @MappedSuperclass : 상속한 엔티티 테이블 컬럼으로 포함됨
• @EntityListeners(AuditingEntityListener.class) : auditing 이벤트 감지

@Getter
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseTimeEntity {

    @CreatedDate
    private LocalDateTime createdAt;

    @LastModifiedDate
    private LocalDateTime updatedAt;
}

Lv1. 일정 CRUD (username 기반)

Lv1은 유저 테이블이 없어서, 일정에 username을 문자열로 저장하는 방식으로 시작했다.

Lv1 요구사항(요약)

• 일정 CRUD 구현

  • 생성/전체조회/단건조회/수정/삭제

• createdAt / updatedAt 응답에 포함

Lv1 설계 포인트

• 아직 User 테이블이 없으니까 작성자(username)는 문자열로 받는다
• Controller -> Service -> Repository 흐름으로 분리
• 엔티티는 DB 구조, DTO는 요청/응답 전용으로 분리

Lv1에서 핵심으로 만든 파일들

• controller/ScheduleController
• service/ScheduleService
• repository/ScheduleRepository
• entity/Schedule, entity/BaseTimeEntity
• dto/ScheduleRequest, dto/ScheduleResponse, dto/ScheduleUpdateRequest
• config/JpaAuditingConfig

코드 흐름(요약)

1. Controller에서 요청 받음
2. Service에서 비즈니스 로직 처리(저장/조회/수정/삭제)
3. Repository(JPA) 로 DB 접근
4. 결과를 Response DTO로 감싸서 반환

Lv1 DTO/Entity 역할 분리

• ScheduleRequest: 클라이언트가 보내는 값만 받음(username/title/content)
• ScheduleUpdateRequest: 수정에 필요한 값만 받음(title/content)
• ScheduleResponse: 클라이언트에게 내려줄 값만 담음(id/username/title/content/createdAt/updatedAt)

이 분리를 해두면, 나중에 Lv2에서 username을 없애고 userId로 바꾸는 작업이 훨씬 편해짐(실제로 그랬음).

API 목록

• POST /api/schedules : 일정 생성
• GET /api/schedules : 전체 조회
• GET /api/schedules/{id} : 단건 조회
• PATCH /api/schedules/{id} : 수정
• DELETE /api/schedules/{id} : 삭제

Postman 검증 순서 (Lv1)

1) 일정 생성

POST /api/schedules

{
  "username": "jimin",
  "title": "첫 일정",
  "content": "CRUD 시작!"
}

2) 전체 조회

GET /api/schedules

3) 단건 조회

GET /api/schedules/{id}

4) 수정

PATCH /api/schedules/{id}

{
  "title": "수정된 제목",
  "content": "수정된 내용"
}

5) 삭제

DELETE /api/schedules/{id}

Lv2. User CRUD + Schedule 연관관계 (userId 기반)

Lv2부터는 일정이 username 문자열을 저장하는게 아니라, User를 참조(FK)하는 구조로 바꿔야 한다.

• 기존: Schedule.username (String)
• 변경: Schedule.user (ManyToOne)

핵심 개념: 연관관계(ManyToOne)

Schedule은 작성자(User)를 가진다. 한 명의 유저가 여러 개의 일정을 작성할 수 있으니까 관계는 이렇게 된다.

• User 1 : Schedule N -> Schedule 입장에서는 ManyToOne

Lv2 요구사항

• User CRUD 추가
• 일정 생성 시 유저와 연관관계로 저장
• 일정 응답에서 username은 User에서 가져온 값이어야 함

Lv2에서 바뀐 점

Schedule이 더 이상 username(String)을 저장하지 않고, user(User)를 참조하도록 변경

Lv2 핵심 변경 1) User 엔티티 추가

• entity/User 생성
• 이메일은 unique 처리(중복 가입 방지)

@Entity
@Table(name="users")
public class User extends BaseTimeEntity {
  @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;

  @Column(nullable=false, length=50)
  private String username;

  @Column(nullable=false, length=100, unique=true)
  private String email;
}

Lv2 핵심 변경 2) Schedule 엔티티에 연관관계 추가

• Schedule.user 필드 추가
• @ManyToOne + @JoinColumn(name="user_id") 로 FK 생성

@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "user_id", nullable = false)
private User user;

여기서 실제 DB에 user_id 컬럼이 생기고, schedules 테이블이 users를 참조하게 됨.

Lv2 핵심 변경 3) ScheduleRequest가 userId를 받도록 변경

기존 Lv1:

• username을 받음

Lv2:

• userId를 받음

@NotNull(message="userId는 필수입니다.")
private Long userId;

Lv2 핵심 변경 4) Service에서 userId로 User를 조회해서 Schedule 저장

ScheduleService.create()에서:

1. userRepository.findById(userId) 로 유저 존재 확인
2. 그 User로 Schedule 생성 후 save

User user = userRepository.findById(request.getUserId())
    .orElseThrow(() -> new IllegalArgumentException("해당 유저가 존재하지 않습니다. id=" + request.getUserId()));

Schedule saved = scheduleRepository.save(new Schedule(user, request.getTitle(), request.getContent()));
return new ScheduleResponse(saved);

User 생성 API (Lv2)

POST /api/users

{
  "username": "jimin",
  "email": "jimin@test.com"
}

Postman 검증 순서 (Lv2)

1) 유저 생성 후 id 확인

• 응답에서 id=1 같은 값 확인

2) 일정 생성 (userId로)

POST /api/schedules

{
  "userId": 1,
  "title": "Lv2 일정",
  "content": "유저 연관관계로 생성"
}

3) 일정 전체 조회

GET /api/schedules

4) 유저명 수정 후 일정 다시 조회

PATCH /api/users/1

{
  "username": "jimin2",
  "email": "jimin2@test.com"
}

그 다음 GET /api/schedules 다시 실행

• 일정 응답에서 username이 jimin2로 바뀌어 보이면 Schedule이 username을 저장한게 아니라 User를 참조한다는 증거

Lv3. 유저에 password 포함 / 회원가입 형태 강화

Lv3에서 나는 회원가입 입력에 password를 추가했다. (이후 Lv4 로그인 구현을 위해 필요)

• User에 password 컬럼 추가
• UserRequest DTO에 password 추가

Lv3 요구사항

• 회원가입 형태 강화(로그인 준비 단계)

Lv3에서 추가된 것

• User에 password 컬럼 추가
• DTO(UserRequest 등)에 password 필드 추가 + Validation

@Column(nullable=false)
private String password;

정상 회원가입 테스트

비밀번호 4자리만 입력했을 경우: 오류

-> 오류메시지는 도전 기능에서 구현 예정

비밀번호 입력하지 않았을 경우: 오류

-> 오류메시지는 도전 기능에서 구현 예정

이 단계에서 400이 뜰 수도 있는데, 예외처리는 Lv5에서 하므로 “지금은 400만 확인되면 OK”로 진행했다.

Lv4. 로그인(인증) - Cookie/Session 기반

Lv4 핵심은 세션(HttpSession)을 활용해서 로그인 상태를 유지하는 것.

개념 정리 (Session / Cookie)

• 로그인 성공하면 서버가 세션을 만들고 클라이언트(Postman)에게 JSESSIONID 쿠키를 내려준다
• 이후 요청마다 클라이언트가 쿠키를 같이 보내면 서버는 아, 이 사용자는 로그인 되어 있구나”를 판단할 수 있다

Lv4 요구사항

• 이메일 + 비밀번호로 로그인
• Cookie/Session으로 로그인 상태 유지
• 필요한 API에서 세션을 활용해서 인증 체크

Lv4에서 추가된 파일들

• controller/AuthController
• dto/LoginRequest
• service/AuthService 또는 UserService에 로그인 로직 추가

Lv4 핵심 구현 1) 로그인 API

• POST /api/auth/login

• email/password 검증 성공 시

  • HttpSession에 로그인 유저 id 저장

예시 흐름:

session.setAttribute(LOGIN_USER_ID, user.getId());

Lv4 핵심 구현 2) 로그아웃 API

• POST /api/auth/logout
• 세션 무효화

session.invalidate();

Lv4 핵심 구현 3) 일정 생성에 세션 인증 적용

Lv2까지 일정 생성은 userId를 body로 받았는데 Lv4부터는 로그인 세션에서 userId를 꺼내서 사용하도록 변경.

• 클라이언트는 userId를 보내지 않는다
• 서버가 세션에서 꺼낸 id로만 생성한다

@PostMapping
public ResponseEntity<ScheduleResponse> create(@RequestBody ScheduleRequest request, HttpSession session) {

    Long loginUserId = (Long) session.getAttribute(AuthController.LOGIN_USER_ID);
    if (loginUserId == null) {
        throw new IllegalArgumentException("로그인이 필요합니다.");
    }

    return ResponseEntity.ok(scheduleService.create(loginUserId, request));
}

Postman 검증 순서 (Lv4)

1) 회원가입 (password 포함)

POST /api/users

{
  "username": "jimin3",
  "email": "jimin3@test.com",
  "password": "11223344"
}

2) 로그인 (세션 쿠키 발급)

POST /api/auth/login

{
  "email": "jimin3@test.com",
  "password": "11223344"
}

응답 헤더에서 Set-Cookie: JSESSIONID=... 확인

3) 일정 생성 (이제 userId 보내지 않음)

POST /api/schedules

{
  "title": "세션 일정",
  "content": "로그인 상태로 생성"
}

4) 로그아웃 후 일정 생성 재시도

POST /api/auth/logout

그 다음 다시 POST /api/schedules 요청

-> 오류 발생하는 것을 확인할 수 있음

트러블슈팅 정리

1) Auditing인데 updatedAt이 안 바뀌는 것처럼 보임

현상

PATCH 후 응답을 봤는데 updatedAt이 createdAt이랑 똑같이 보였다.

원인(가능성)

• 요청을 너무 빨리 연속으로 보내서 시간이 같은 초로 찍힘
• 혹은 update가 실제로 flush/dirty checking 되기 전에 응답을 만든 경우

해결/확인 방법

• Postman에서 수정 요청을 몇 초 텀을 두고 다시 실행
• DB에서 직접 확인 (select) 혹은 GET 조회로 updatedAt 변화 확인

2) @NotBlank를 Long(userId)에 걸어서 터짐 (HV000030)

현상

No validator could be found for constraint 'NotBlank' validating type 'Long'

원인

• @NotBlank는 문자열(String) 전용이다.
• 숫자(Long)에 쓰면 검증기가 없어서 예외 발생.

해결

• Long에는 @NotNull을 써야 한다.

@NotNull(message="userId는 필수입니다.")
private Long userId;

3) 500 Internal Server Error로 일정 생성이 실패

현상

Postman에서 일정 생성 시 500이 발생했다.

체크했던 것

• userId가 실제 존재하는지 (GET /api/users)
• DB 테이블 구조 변경이 반영되었는지 (user_id 컬럼 존재 여부)
• Schedule 생성자가 (User, title, content)로 맞게 되어 있는지

결론

대부분 이런 500은

• 엔티티/DTO 필드 타입 불일치
• FK 컬럼 미생성/스키마 미반영
• 존재하지 않는 userId로 생성 시도

이 셋 중 하나였다.

4) 회원가입 시 Duplicate entry (email unique)

현상

Duplicate entry 'jimin2@test.com' for key 'users...'

원인

• User.email에 unique=true가 걸려있어서
• 같은 이메일로 다시 회원가입 시 DB에서 막힘

해결

• 이메일을 다른 값으로 테스트
• 혹은 기존 유저 레코드 삭제 후 재시도

회고

사실 지난 과제 때는 독감 때문에 제대로 구현하지 못해서 아쉬움이 많이 남았었다. 구조를 깊게 고민하기보다는 일단 돌아가게 만드는 것에 집중할 수밖에 없었고, 완성도에 대한 아쉬움이 컸다.

이번 과제도 시간이 넉넉하진 않았지만, 그래도 저번보다는 훨씬 신경 써서 구조를 잡고, 레벨별 요구사항을 정확히 이해하고, 단계적으로 구현해나갈 수 있었던 점이 스스로 만족스럽다.

특히 이번 과제를 통해 깨달은 점은

• 처음 설계를 어떻게 하느냐에 따라 이후 수정 난이도가 완전히 달라진다

• DTO와 Entity를 분리해두는 것이 얼마나 중요한지 체감했다

• 연관관계를 적용하면 단순 문자열 저장과는 차원이 다르다

• 세션 인증은 개념으로 알던 것과 실제 구현은 완전히 다르다

• 에러를 마주쳤을 때 당황하지 않고 하나씩 원인을 좁혀가는 과정이 중요하다

이제 도전 기능을 통해 예외처리와 Validation까지 정리하면서 프로젝트를 더 다듬어보고 싶다.