Cloud.log

[설계의사결정] 시리즈 목록

devCloud — Thu, 21 May 2026 22:05:16 +0900

ARCHITECTURE

[설계 의사결정] 시리즈 목록

단순히 기능을 구현하는 것보다 더 중요했던 건 “왜 이 방식을 선택했는가?”에 대한 고민이었다.

1. 이미지 업로드 정책 결정 과정
2. 페이지네이션 방식 선택 과정
3. 독서 리마인더 알림 구현 방식 선택 과정
4. 국내 도서 검색 API 선택 과정
5. JWT + Redis 인증 설계

이 시리즈는 Booktine 개발 과정에서 실제로 고민했던 설계 선택 과정들을 정리한 글이다. 단순 구현 방법보다는 “왜 이 구조를 선택했는가”를 중심으로 기록했다.

이미지 업로드 정책 결정 과정

Booktine에는 책 표지 이미지와 프로필 이미지 두 가지 이미지가 존재한다. 이미지를 저장하는 방식으로 외부 URL 직접 저장, 서버에서 S3 재업로드, Presigned URL을 통한 클라이언트 직접 업로드 세 가지를 비교했다.

이미지 종류별로 특성이 달라 각각 다른 방식을 선택하게 된 과정을 정리했다.

→ 자세히 보기

페이지네이션 방식 선택 과정

게시물, 메모, 추천 도서 목록 등 목록 조회가 많은 서비스 특성상 페이지네이션 도입이 필요했다.

오프셋 기반과 커서 기반을 비교했고, Spring Data의 Page<T>와 Slice<T> 중 어떤 방식이 Booktine에 적합한지 선택한 과정을 정리했다.

→ 자세히 보기

독서 리마인더 알림 구현 방식 선택 과정

사용자가 설정한 시간에 맞춰 서버가 알림을 전달하는 리마인더 기능을 구현하면서 @Scheduled + SSE, 이메일, WebSocket, FCM 등 여러 방식을 비교했다.

단방향 알림 전달이라는 요구사항에 맞는 방식을 선택한 과정을 정리했다.

→ 자세히 보기

국내 도서 검색 API 선택 과정

도서 검색 기능 구현을 위해 알라딘, 카카오, 네이버, 국립중앙도서관, 도서관 정보나루 API를 비교했다.

표지 이미지 제공 여부, 신간/베스트셀러 데이터, JSON 응답 지원 등을 기준으로 검토하고 최종 API를 선택한 과정을 정리했다.

→ 자세히 보기

JWT + Redis 인증 설계

Booktine의 대부분의 기능이 인증을 전제로 하기 때문에 인증 방식 선택이 중요한 설계 결정이었다.

세션 방식과 JWT를 비교하고, Refresh Token 강제 무효화 문제를 해결하기 위해 Redis를 도입한 과정을 정리했다.

→ 자세히 보기

[설계의사결정] JWT + Redis 인증

devCloud — Wed, 13 May 2026 20:58:29 +0900

AUTH

JWT + Redis 인증 설계 - 세션 대신 JWT를 선택한 이유

1. 배경
2. 인증 방식 비교
3. 세션을 선택하지 않은 이유
4. 결정 — JWT + Redis
5. JWT의 한계

Booktine은 로그인 기반 기능이 많은 서비스다. 따라서 인증 구조를 어떻게 설계할지가 서비스 전체 구조에 큰 영향을 줬다.

1. 배경

Booktine은 로그인한 사용자만 이용할 수 있는 기능이 많다. 독서 기록 작성, 메모, 진행률 관리 등 대부분의 핵심 기능이 인증을 전제로 한다. 따라서 어떤 방식으로 인증을 처리할지가 중요한 설계 결정 중 하나였다.

핵심 기준은 다음과 같았다.

서버 확장성
프론트엔드(React)와의 연동 편의성
구현 복잡도

2. 인증 방식 비교

방식	설명	확장성	구현 난이도
세션	서버 메모리에 인증 정보를 저장하고, 클라이언트는 세션 ID만 갖는다.	낮음 (서버 상태 유지 필요)	낮음
JWT	인증 정보를 토큰에 담아 클라이언트가 직접 보관한다.	높음 (Stateless)	중간

세션은 서버 상태를 유지해야 하고, JWT는 Stateless 구조라는 차이가 가장 핵심이었다.

3. 세션을 선택하지 않은 이유

세션은 구현이 단순하고 Spring Security와의 기본 연동이 잘 되어 있다는 장점이 있다. 하지만 구조를 고려했을 때 몇 가지 문제가 있다고 판단했다.

서버 메모리에 세션 정보를 저장하기 때문에 서버 재시작 시 로그인 상태가 초기화된다.
서버를 수평 확장할 경우 세션 동기화 처리가 필요하다.
React 기반 SPA와의 연동에서 CORS 설정이 복잡해질 수 있다.
REST API 구조에서는 Stateless 방식이 더 자연스럽다.

무엇보다 프론트엔드가 React로 분리된 구조이기 때문에, 쿠키 기반 세션보다 토큰 기반 인증이 연동하기 더 편리하다고 판단했다.

4. 결정 - JWT + Redis

Access Token / Refresh Token 발급

JWT는 Access Token과 Refresh Token 두 가지를 발급하는 구조로 설계했다. Access Token은 만료 시간을 짧게 설정해 탈취 위험을 줄이고, 만료 시 Refresh Token으로 재발급받도록 했다.

JwtProvider에서는 Access Token과 Refresh Token 생성, Claim 파싱, 만료 검증 등의 핵심 JWT 로직을 담당한다.

JWT 내부 Claim 정보를 추출하고, 토큰 유효성 검사를 수행하는 로직이다.

Refresh Token을 Redis에 저장한 이유

JWT는 기본적으로 서버가 상태를 저장하지 않기 때문에, 한번 발급된 토큰을 서버에서 강제로 무효화하기 어렵다. 이 문제를 해결하기 위해 Refresh Token을 Redis에 저장했다.

로그아웃 시 Redis에서 Refresh Token을 삭제하면 재발급이 불가능해진다.
Redis TTL 기능으로 만료 처리를 자동화할 수 있다.
메모리 기반 저장소라 조회 속도가 빠르다.
RDB에 저장하는 방식보다 DB 부담이 적다.

별도 Repository 클래스 없이 StringRedisTemplate을 AuthService에서 직접 사용하는 방식으로 구현했다.

Refresh Token은 Redis에 TTL과 함께 저장된다. 이를 통해 만료 시간을 자동으로 관리할 수 있다.

로그인 유지 여부에 따라 Refresh Token의 TTL도 다르게 설정했다. 로그인 유지를 선택하지 않으면 최대 12시간으로 제한한다.

로그인 유지 여부에 따라 Refresh Token의 TTL을 다르게 설정해 보안성과 사용자 편의성 사이의 균형을 맞췄다.

로그인 및 토큰 발급 흐름
사용자가 로그인에 성공하면 서버는 Access Token과 Refresh Token을 생성한다. Refresh Token은 Redis에 TTL과 함께 저장되고, Access Token은 클라이언트에 전달된다.

로그아웃 및 Access Token 블랙리스트

로그아웃 시에는 Redis에서 Refresh Token을 삭제하고, 현재 Access Token을 블랙리스트에 등록한다.

Access Token은 만료 전까지 유효하기 때문에, 블랙리스트에 등록해 재사용을 막는다.

블랙리스트의 TTL은 Access Token의 남은 만료 시간으로 설정했다.

로그아웃 시 Refresh Token을 Redis에서 제거하고, 현재 Access Token을 블랙리스트에 등록한다.

로그아웃 및 토큰 무효화 흐름
로그아웃 요청이 들어오면 Refresh Token은 Redis에서 삭제된다. 동시에 현재 Access Token은 블랙리스트에 등록되어 만료 전까지 재사용되지 못하도록 차단된다.

JwtFilter에서는 매 요청마다 블랙리스트 등록 여부를 확인한다.

JwtFilter는 요청마다 Access Token이 블랙리스트에 등록됐는지 확인해 무효화된 토큰의 접근을 차단한다.

Access Token 재발급

Refresh Token 검증 후 Redis에 저장된 값과 일치하는 경우에만 새 Access Token을 발급한다.

Refresh Token 검증 후 Redis 저장값과 비교해 유효한 경우에만 Access Token을 재발급한다.

Access Token 재발급 흐름
클라이언트는 만료된 Access Token 대신 Refresh Token으로 재발급 요청을 보낸다. 서버는 Redis에 저장된 Refresh Token과 비교 검증 후 새로운 Access Token을 발급한다.

선택 이유

React 기반 SPA와 토큰 기반 인증 연동이 자연스럽다.
Stateless 구조로 서버 확장에 유리하다.
Redis TTL로 Refresh Token 만료를 자동 처리할 수 있다.
로그아웃 시 Refresh Token 삭제 + Access Token 블랙리스트 등록으로 강제 무효화가 가능하다.

5. JWT의 한계

Access Token은 만료 전까지 서버에서 강제로 무효화할 수 없다. 따라서 탈취된 경우에도 만료 시간까지는 유효하게 사용될 수 있다는 단점이 있다.

다만 Access Token의 만료 시간을 짧게 설정하고, 로그아웃 시 블랙리스트에 등록하는 방식으로 이 문제를 최소화했다.

현재 Booktine 서비스 규모에서는 JWT + Redis 방식이 확장성과 구현 복잡도 사이에서 가장 적절한 균형이라고 판단했다.

[프로젝트 개요] 프로젝트 소개 및 기획

devCloud — Tue, 12 May 2026 11:37:52 +0900

프로젝트 소개
기획 배경
서비스 목표
타겟 사용자
기능 범위 결정 과정
개발 일정 설계
주요 기능
기술 스택
Backend
Frontend
Infra
시스템 아키텍처
ERD

프로젝트 소개

GitHub 바로가기

기획 배경

평소 독서를 좋아하고 읽은 책을 기록하는 습관이 있었다. 그런데 막상 꾸준히 기록하려고 하면 마땅한 공간이 없었다. 메모 앱, 노트, 사진 등 여러 곳에 나눠서 적다 보면 어느 순간 흐름이 끊기고 기록 자체를 포기하게 된다. 기록은 있는데 한눈에 보이지 않으니 내가 얼마나 읽었는지, 어떤 책을 좋아하는지도 파악하기 어렵다.

그러다 문득 "내가 원하는 대로 직접 만들면 되겠다"는 생각이 들었다. 마침 백엔드 개발자를 목표로 하고 있었고, 내가 실제로 쓰고 싶은 서비스를 만드는 게 가장 좋은 공부라고 생각했다. 읽은 책의 기록과 메모, 월간·연간 독서 목표, 통계 시각화, 도서 추천, 독서 커뮤니티까지 내가 원하는 기능을 하나씩 직접 설계하고 구현한 것이 Booktine이다.

서비스 목표

독서 기록을 한 곳에서 관리하고, 목표를 설정하고, 얼마나 읽었는지 한눈에 파악할 수 있는 서비스를 만드는 것이 목표였다. 단순한 기록 저장을 넘어 독서 습관을 만들고 유지하는 데 실질적으로 도움이 되는 서비스를 지향했다.

타겟 사용자

독서를 좋아하고 읽은 책을 기록하는 습관이 있는 사람
독서 목표를 세우고 꾸준히 관리하고 싶은 사람

기능 범위 결정 과정

기능을 P1 / P2 / P3 세 단계로 나눠 우선순위를 정했다.

P1 - 핵심 기능 (반드시 구현)

독서 기록 서비스의 본질에 해당하는 기능들이다. 회원가입·로그인, 게시물 CRUD, 메모 CRUD, 목표 설정, 기본 통계가 여기에 해당한다. 이 기능들 없이는 서비스 자체가 성립하지 않는다고 판단했다.

P2 - 보완 기능 (있으면 좋은 기능)

P1만으로는 서비스가 단조롭기 때문에 사용성을 높여주는 기능들을 P2로 분류했다. 키워드 검색, 독서 상태 필터, 장르별 통계, 도서 추천이 여기에 해당한다. 필수는 아니지만 빠지면 아쉬운 기능들이다.

P3 - 확장 기능 (시간이 남으면 구현)

커뮤니티, 리마인더, 관리자 기능은 독서 기록 서비스의 핵심과는 거리가 있다고 판단해 P3로 미뤘다. 서비스의 본질적인 기능을 먼저 완성한 뒤 시간이 남을 때 구현하는 방향으로 결정했다. 독서 챌린지는 기획은 해뒀지만 최종적으로 구현하지 않았다.

개발 일정 설계

백엔드를 먼저 완벽하게 구현한 뒤 프론트엔드를 진행하는 것을 원칙으로 잡았다. 백엔드 개발자를 목표로 하는 만큼 백엔드에 시간을 충분히 투자하고, 프론트는 백엔드가 완성된 상태에서 연결에 집중하는 방식이었다.

D1 ~ D9는 백엔드 전체 구현, D9-1은 리팩토링, D10 ~ D12는 프론트엔드 구현, D13 ~ D14는 배포 및 마무리로 일정을 구성했다.

주요 기능

기능	설명
독서 기록 (Book Note)	독서 상태(읽는 중 / 완독 / 일시정지 / 읽고 싶음) 관리, 별점·한줄평·장르 기반 노트 작성
메모 관리	도서 단위로 메모 작성·수정·삭제, 책을 읽으며 남긴 문장·감상·요약 정리
목표 및 통계 (Progress)	월간·연간 독서 목표 설정, 장르 분포·월별 완독·연간 요약 시각화
도서 추천	알라딘 API 연동, 베스트셀러·장르 기반 추천, 저장 및 목록 관리
독서 커뮤니티	게시글 작성·수정·삭제, 댓글·대댓글·좋아요
리마인더	독서 리마인더 등록, SSE 기반 실시간 알림 수신
관리자	사용자·게시글·장르·문의 목록 조회, 장르 추가·삭제

기술 스택

Backend

구분	기술	선택 이유
Language	Java 21 GraalVM	Record, Switch Expression 등 최신 문법 활용, GraalVM 네이티브 이미지로 시작 시간 단축
Framework	Spring Boot 3.3	Spring Security 6, Virtual Thread 등 최신 기능 활용
Persistence	Spring Data JPA QueryDSL	동적 쿼리를 타입 안전하게 작성하기 위해 QueryDSL 도입
Database	MySQL 8 H2	관계형 데이터 구조에 적합, 로컬에서는 H2로 빠르게 검증
Auth	JWT Redis	Stateless 인증 구조, Redis로 Refresh Token 및 블랙리스트 관리
Storage	AWS S3	프로필 이미지, 게시물 표지 이미지 저장
External	Aladin API SMTP	도서 검색·추천 연동, 이메일 인증·비밀번호 재설정

Frontend

구분	기술	선택 이유
Framework	React 18 TypeScript	컴포넌트 재사용성과 타입 안전성 확보
Styling	Tailwind CSS v3 shadcn/ui	유틸리티 기반으로 빠른 UI 구성, shadcn/ui로 일관된 컴포넌트 관리
HTTP	Axios	인터셉터로 Bearer Token 자동 주입 및 토큰 재발급 처리

Infra

구분	기술	선택 이유
Compute	AWS EC2 Docker	컨테이너 기반으로 운영 환경 일관성 확보
Database	AWS RDS MySQL 8	관리형 DB로 운영 부담 최소화
Cache	AWS ElastiCache Redis	토큰 저장, 블랙리스트, 인증 코드, 실패/잠금 정보 관리
Storage / CDN	AWS S3 CloudFront	정적 파일 서빙 및 이미지 CDN 처리
Network	ALB HTTPS	도메인 기반 라우팅, SSL 인증서 적용

시스템 아키텍처

클라이언트(React)는 CloudFront를 통해 정적 파일을 서빙받고, API 요청은 ALB를 거쳐 EC2의 Spring Boot 컨테이너로 전달된다. 모든 요청은 JwtFilter에서 토큰 검증 및 블랙리스트 확인을 거치고, Spring Security에서 인증·인가를 처리한다. 리마인더 알림은 SSE로 클라이언트와 직접 연결되며, 외부 연동으로 Google OAuth2, 알라딘 API, SMTP, AWS S3를 사용한다.

ERD

총 11개 테이블로 구성된다. users를 중심으로 posts, memos, monthly_goals, annual_goals, reminders, recommendations, inquiries가 연결되고, 커뮤니티 기능은 community_posts, community_comments, community_likes로 분리했다. 장르는 genres 테이블로 독립 관리하며 관리자가 추가·삭제할 수 있다.

1차 개발 돌아보기

2025년 초에 Java 17, Spring Boot 3.3, React 18로 같은 주제를 한 번 구현한 적이 있다. 당시에는 세션 기반 인증, Thymeleaf 서버 사이드 렌더링, Render 무료 배포를 사용했고, 설계보다 구현에 급했던 코드였다. 1차 코드를 다시 봤을 때 수정으로 해결할 수 있는 수준이 아니라고 판단했다. 그래서 코드를 처음부터 다시 짰다. JWT 인증, AWS 인프라, 도메인 중심 설계, 보안 점검까지 이번 2차 개발에서 달라진 부분들이다.

1차 개발 기록은 아래 링크에서 확인할 수 있다.

1차 개발 기록 보러가기

[설계의사결정] 국내 도서 검색 API 선택 과정

devCloud — Fri, 8 May 2026 16:43:14 +0900

PROJECT

국내 도서 검색 API 선택 과정

1. 왜 도서 API를 비교하게 됐나?
2. 국내에서 사용 가능한 도서 API
3. API별 비교
4. 알라딘 Open API
5. 카카오 책 검색 API
6. 네이버 책 검색 API
7. 국립중앙도서관 Open API
8. 도서관 정보나루 API
9. 최종 선택: 알라딘 API
10. 마무리

독서 습관 관리 서비스를 개발하고 있는데 “도서 데이터를 어디서 가져올 것인가?” 에 대한 고민이 생겼다.

1. 왜 도서 API를 비교하게 됐나?

처음에는 단순히 제목만 검색되면 될 줄 알았다. 그런데 막상 구현하려고 보니 생각보다 고려해야 할 요소가 많았다.

표지 이미지 제공 여부
신간 / 베스트셀러 데이터 제공 여부
가격 정보 제공 여부
JSON 지원 여부
API 관리 상태
키 발급 속도

특히 독서 서비스에서는 단순 텍스트보다 책 표지 이미지의 중요도가 굉장히 크다. UI 완성도 자체가 달라지기 때문이다. 이번 글에서는 국내에서 사용할 수 있는 대표적인 도서 검색 API들을 비교하고, 최종적으로 왜 알라딘 API를 선택했는지 정리해보려고 한다.

2. 국내에서 사용 가능한 도서 API

국내에서 사용할 수 있는 대표적인 도서 관련 API는 아래 정도가 있다.

API	특징
알라딘 Open API	도서 서비스 개발에서 가장 많이 사용되는 편
카카오 책 검색 API	카카오 검색 기반
네이버 책 검색 API	네이버 검색 결과 기반
국립중앙도서관 Open API	공공 데이터 중심
도서관 정보나루 API	도서관 대출/인기 데이터 제공
교보문고 / 영풍문고	공식 Open API 미제공

선택지가 많았는데 이 중에 무슨 API를 선택할지 고민이었다. 특히 의외였던 부분은 국내 대형 서점인 교보문고, 영풍문고가 공식 Open API를 제공하지 않는다는 점이었다. 그래서 실제 서비스에서는 결국 알라딘 API를 사용하는 경우가 꽤 많았다.

3. API별 비교

개발하면서 중요하게 봤던 기준들을 중심으로 정리해봤다.

API	표지 이미지	신간/베스트셀러	가격 정보	응답 형식	키 발급	관리 상태
알라딘 Open API	O	O	O	JSON / XML	비교적 빠름	활발
카카오 책 검색 API	O	X	일부	JSON	매우 빠름	활발
네이버 책 검색 API	O	X	일부	JSON / XML	빠름	보통
국립중앙도서관 API	부족	X	X	XML 중심	느린 편	다소 보수적
도서관 정보나루 API	제한적	대출 기반 인기 정보	X	JSON / XML	보통	운영 중

4. 알라딘 Open API

개인적으로는 가장 서비스 개발 친화적이었다. 특히 좋았던 부분은 아래였다.

표지 이미지 품질이 괜찮음
신간 / 베스트셀러 API 제공
가격 정보 제공
JSON 응답 지원
실제 도서 서비스에서 많이 사용됨

독서 앱에서는 단순 검색보다도 홈 화면 구성 요소가 중요하다.

예를 들면

오늘의 추천 도서
신간 목록
베스트셀러
카테고리별 도서

이런 데이터가 필요해지는데, 알라딘 API는 이런 부분이 꽤 잘 되어 있었다. 무엇보다 좋았던 건 JSON 응답이었다. Spring Boot에서 DTO 매핑할 때도 편했고, Android나 React 쪽에서도 다루기 수월했다.

실제로 구현하면서 느낀 건 “도서 검색만 필요한 API가 아니라, 도서 서비스 자체를 만들기 좋은 API” 에 가까웠다.

5. 카카오 책 검색 API

카카오 API는 사용성 자체는 굉장히 좋았다. 키 발급도 빠르고, 문서도 비교적 깔끔한 편이다. 검색 품질도 나쁘지 않았다. 다만 아쉬웠던 점은

신간 API 없음
베스트셀러 API 없음
도서 서비스 특화 기능 부족

즉, “검색 API”에 더 가까운 느낌이었다. 책 검색 기능만 필요한 경우에는 충분히 좋은 선택이라고 생각한다.

6. 네이버 책 검색 API

네이버도 기본적인 검색 기능은 제공한다. 예전부터 존재하던 API라 자료도 꽤 많다. 다만 실제로 비교해보면

응답 데이터 구조가 다소 오래된 느낌
도서 메타데이터 품질 편차 존재
서비스 확장성은 애매

라는 인상이 있었다. 그리고 최근에는 개발자들이 예전만큼 적극적으로 사용하는 분위기는 아니었다.

7. 국립중앙도서관 Open API

처음에는 공공 API라서 가장 신뢰도가 높을 줄 알았다. 그런데 실제 서비스 관점에서는 아쉬운 부분이 꽤 있었다. 대표적으로

표지 이미지가 부족함
신간 / 베스트셀러 제공 안 함
XML 응답 중심
UI 친화적인 데이터가 적음

특히 XML 응답은 생각보다 개발 피로도가 컸다. 물론 Spring에서는 XML 파싱도 가능하지만, 실제 프론트엔드까지 고려하면 JSON 기반 API가 훨씬 편했다. 그리고 독서 서비스에서는 결국 “보여지는 경험”이 중요한데, 표지 이미지가 부실한 점이 꽤 크게 느껴졌다.

8. 도서관 정보나루 API

이 API는 조금 성격이 다르다. 일반적인 도서 검색보다는

대출 순위
인기 도서
연령별 추천
지역별 대출 데이터

같은 공공 도서관 통계 데이터에 가까웠다.

그래서 일반적인 독서 앱보다는

독서 분석 서비스
추천 시스템
통계 기반 기능

쪽에서 더 활용도가 높아 보였다.

9. 최종 선택: 알라딘 API

최종적으로는 알라딘 API를 선택했다. 이유는 단순했다. 독서 서비스에서 필요한 요소들을 가장 균형 있게 제공했기 때문이다.

특히 아래 요소들이 결정적이었다.

표지 이미지 제공
신간 / 베스트셀러 제공
가격 정보 제공
JSON 응답 지원
실제 서비스 UI 구성에 적합

도서 서비스는 결국 “검색”보다 “탐색 경험”이 더 중요하다고 생각한다.

사용자가

책을 발견하고
표지를 보고
관심을 느끼고
저장하고 기록하는 흐름

이 자연스럽게 이어져야 한다. 그 관점에서 알라딘 API가 가장 실용적인 선택이었다.

10. 마무리

처음에는 단순히 “책 검색 API 하나 붙이면 끝”이라고 생각했는데, 실제로는 서비스 방향에 따라 선택 기준이 꽤 달랐다.

만약

단순 검색 기능만 필요하다면 → 카카오
공공 데이터/통계 활용이 목적이라면 → 정보나루
실제 독서 서비스 개발이라면 → 알라딘

쪽이 더 적합하다고 느꼈다. 도서 API는 생각보다 선택지가 제한적인 분야라, 처음 설계 단계에서 충분히 비교해보고 결정하는 걸 추천한다.

[Infrastructure] Spring Boot × Docker × AWS 배포 흐름 한 번에 이해하기

devCloud — Fri, 8 May 2026 13:12:18 +0900

DEPLOYMENT

Spring Boot 앱을 Docker로 AWS에 배포하는 전체 흐름 정리

Docker가 왜 필요한가?
Docker와 AWS의 차이
AWS 서비스 역할 정리
전체 아키텍처 흐름
Dockerfile 작성과 배포
배포 방식 비교
마치며

Docker와 AWS를 처음 접하면 가장 헷갈리는 부분이 있다. “Docker를 쓰는 건가? AWS를 쓰는 건가?” 이 둘의 관계부터 실제 배포 흐름까지 한 번에 정리해보자.

Docker가 무엇인지 알고 싶다면

Docker

목차도커란?핵심 개념VM과 Docker 차이배포한다고 가정할 때기본 명령어참고 링크 도커란?컨테이너 기반 가상화 도구 (2013년 등장)리눅스의 프로세스 격리 기술을 활용해 앱 실행 환경을 컨

dev-cloud.tistory.com

1. Docker가 왜 필요한가?

Spring Boot 앱이 로컬에서는 잘 돌아가는데, 서버에 올리면 갑자기 오류가 나는 경우가 있다. 이런 문제는 대부분 실행 환경 차이 때문에 발생한다. Java 버전이 다르거나, OS 환경이 다르거나, 환경 변수 설정이 달라서 문제가 생기는 것이다.

개발자들 사이에서 자주 나오는 말이 있다.
“내 컴퓨터에선 됐는데?”
Docker는 바로 이 문제를 해결하기 위해 등장했다.

Docker는 앱과 실행 환경을 하나의 이미지로 묶는다. 즉, 어디서 실행하든 동일한 환경을 보장할 수 있다.

Docker를 비유하면?

레시피(코드)만 전달하는 게 아니라, 주방 환경까지 통째로 박스에 담아 보내는 개념이라고 보면 된다.

Docker 이미지에는 앱뿐 아니라 실행에 필요한 JDK, 설정, 라이브러리까지 포함된다.

2. Docker와 AWS의 차이

가장 많이 헷갈리는 부분이 바로 이것이다.

구분	역할
Docker	앱을 패키징하고 실행하는 방식
AWS	서버, DB, 네트워크 등을 제공하는 인프라

즉, 둘 중 하나를 선택하는 개념이 아니다. AWS라는 인프라 위에서 Docker 컨테이너를 실행하는 것이다.

Docker는 “어떻게 실행할 것인가”, AWS는 “어디서 실행할 것인가”에 가깝다.

3. AWS 서비스 역할 정리

Spring Boot 프로젝트를 AWS로 배포할 때 자주 사용하는 서비스들은 다음과 같다.

서비스	역할
EC2	Docker 컨테이너가 실행되는 서버
RDS	MySQL 같은 데이터베이스 관리
ElastiCache	Redis 캐시 서버 제공
S3	파일 저장소
CloudFront	CDN 기반 빠른 정적 파일 배포

실무에서는 보통 EC2 + RDS + Redis + S3 조합을 많이 사용한다.

4. 전체 아키텍처 흐름

전체 흐름은 다음과 같다.

개발자 코드 작성
        ↓
Docker 이미지 빌드
        ↓
DockerHub 또는 ECR 업로드
        ↓
EC2 서버에서 이미지 pull
        ↓
Docker 컨테이너 실행
        ↓
RDS / Redis / S3 연결
        ↓
사용자 요청 처리

사용자의 요청이 들어오면 Spring Boot 앱이 데이터를 처리하고, 필요한 경우 RDS(MySQL), Redis, S3와 통신하게 된다.

실제 서비스는 단순히 “Spring Boot 하나 실행”으로 끝나지 않는다. DB, 캐시, 파일 저장소 등 여러 서비스가 함께 동작한다.

5. Dockerfile 작성과 배포

Spring Boot 앱을 Docker 이미지로 만들기 위해 Dockerfile을 작성한다.

Dockerfile 예시

# Build Stage
FROM eclipse-temurin:17-jdk-alpine AS builder

WORKDIR /app

COPY . .

RUN ./gradlew bootJar

# Run Stage
FROM eclipse-temurin:17-jre-alpine

WORKDIR /app

COPY --from=builder /app/build/libs/*.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "app.jar"]

Multi-stage Build를 사용하면 최종 이미지 크기를 줄일 수 있다.

Docker 이미지 빌드

docker build -t my-spring-app .

DockerHub 업로드

docker push your-dockerhub-id/my-spring-app

EC2에서 실행

docker pull your-dockerhub-id/my-spring-app

docker run -d -p 80:8080 your-dockerhub-id/my-spring-app

DB 비밀번호 같은 민감 정보는 Dockerfile에 직접 작성하지 말고, 환경 변수로 관리하는 것이 안전하다.

application.yml 예시

spring:
  datasource:
    url: ${SPRING_DATASOURCE_URL}
    username: ${SPRING_DATASOURCE_USERNAME}
    password: ${SPRING_DATASOURCE_PASSWORD}

  data:
    redis:
      host: ${SPRING_REDIS_HOST}
      port: 6379

6. 배포 방식 비교

방식	장점	단점
JAR 직접 배포	단순하다	환경 차이 문제 발생 가능
Docker 배포	환경 일관성 보장	Docker 학습 필요
Docker Compose	여러 컨테이너 관리 편리	운영 환경에선 관리 필요
PaaS (Railway 등)	배포가 매우 쉽다	커스터마이징 제한

Docker Compose 예시

version: '3.8'

services:
  app:
    image: my-spring-app
    ports:
      - "80:8080"

  db:
    image: mysql:8

  redis:
    image: redis:7

운영 환경에서는 DB와 Redis를 직접 컨테이너로 운영하기보다, RDS와 ElastiCache 같은 관리형 서비스를 사용하는 경우가 많다.

7. 마치며

Docker는 앱을 어떻게 패키징할지 결정하는 기술이고, AWS는 그 컨테이너가 실제로 실행되는 인프라다. 둘은 경쟁 관계가 아니라 함께 사용하는 조합이다.

정리하면

Docker는 실행 환경을 통째로 패키징한다
AWS는 서버와 인프라를 제공한다
Spring Boot + Docker + AWS 조합은 실무에서도 매우 많이 사용된다
다음 단계로는 GitHub Actions를 이용한 CI/CD 자동 배포까지 공부해보면 좋다.

[Web] REST API, RESTful API 개념

devCloud — Fri, 8 May 2026 11:17:49 +0900

WEB

REST API, RESTful API 개념과 차이

1. API
2. REST
3. REST API vs RESTful API
4. REST API 설계 방법
5. HTTP 상태 코드도 중요하다
6. 마치며

백엔드 공부를 시작하면 가장 먼저 마주치는 단어, REST API. 근데 RESTful API는 또 뭔가? 같은 건가 다른 건가? 오늘 한 번에 정리해보자.

1. API

REST API를 이해하려면 먼저 API가 뭔지 알아야 한다. API(Application Programming Interface)란, 서로 다른 소프트웨어가 서로 통신할 수 있도록 정해놓은 인터페이스다.

쉽게 말하면, 클라이언트(프론트엔드, 앱 등)가 서버에게 “이 데이터 줘” 하고 요청하고, 서버가 “여기 있어” 하고 응답하는 그 창구가 바로 API다.

프론트엔드와 백엔드가 데이터를 주고받는 연결 지점이 바로 API다.

2. REST

REST(Representational State Transfer)는 웹 통신을 위한 아키텍처 스타일(설계 원칙)이다. 2000년에 로이 필딩(Roy Fielding)이 그의 박사 논문에서 처음 정의했다.

REST 자체는 프로토콜이나 표준이 아니다. “이런 방식으로 설계하면 좋다”는 가이드라인에 가깝다. REST가 제시하는 핵심 원칙은 다음과 같다.

원칙	설명
클라이언트-서버 구조	클라이언트와 서버는 역할을 분리한다
무상태(Stateless)	각 요청은 독립적이며 서버는 클라이언트 상태를 저장하지 않는다
캐시 가능(Cacheable)	응답은 캐시될 수 있어야 한다
계층화 시스템	중간 서버를 거치는지 여부를 클라이언트가 알 필요 없다
일관된 인터페이스	URI와 HTTP 메서드 등 일관된 방식으로 통신한다
코드 온 디맨드 (선택)	필요하면 서버가 실행 가능한 코드를 전달할 수 있다

우리가 평소에 자주 접하는 카카오맵 API, 네이버 로그인, 공공데이터포털 등도 모두 REST API 방식으로 제공된다. 즉, 이미 우리 주변에서 널리 쓰이고 있는 방식이다.

이 원칙들을 잘 지키며 설계된 API가 바로 REST API다.

3. REST API vs RESTful API

솔직히 말하면 실무에서는 두 단어를 혼용해서 쓰는 경우가 대부분이다. 하지만 엄밀하게 구분하면 차이가 있다.

	REST API	RESTful API
의미	REST 원칙을 기반으로 만든 API	REST 원칙을 충실히 지킨 API
뉘앙스	REST 스타일을 따른다고 주장하는 API	REST 6가지 원칙을 제대로 준수한 API
현실	원칙 일부만 지켜도 REST API라고 부름	완전한 준수가 기준

즉, 모든 RESTful API는 REST API지만, 모든 REST API가 RESTful한 것은 아니다. 로이 필딩 본인도 “대부분의 REST API는 사실 RESTful하지 않다”고 말할 정도로, 완전한 RESTful 설계는 생각보다 까다롭다.

4. REST API 설계 방법

REST API는 URI + HTTP 메서드 조합으로 행위를 표현한다. 먼저 아키텍처부터 살펴보자.

아키텍처

클라이언트(웹 앱, 모바일 앱, 프론트엔드)가 HTTP 요청(GET, POST, PUT, DELETE)을 인터넷을 통해 서버로 전송하고, 서버는 API 엔드포인트에서 요청을 받아 비즈니스 로직을 처리한 뒤 HTTP 상태 코드와 JSON 데이터를 응답으로 돌려주는 REST API의 전체 흐름이다.

REST API는 데이터의 생성(Create), 조회(Read), 수정(Update), 삭제(Delete), 즉 CRUD를 HTTP 메서드로 표현한다.

HTTP 메서드

메서드	역할
`GET`	데이터 조회
`POST`	데이터 생성
`PUT`	데이터 전체 수정
`PATCH`	데이터 일부 수정
`DELETE`	데이터 삭제

URI 설계 예시

게시판 API를 설계한다고 해보자.

GET    /posts         → 게시글 목록 조회
GET    /posts/{id}    → 특정 게시글 조회
POST   /posts         → 게시글 작성
PUT    /posts/{id}    → 게시글 전체 수정
PATCH  /posts/{id}    → 게시글 일부 수정
DELETE /posts/{id}    → 게시글 삭제

응답 예시 (JSON)

GET /posts/1 요청 시 서버가 돌려주는 응답은 보통 이런 형태다.

{
  "id": 1,
  "title": "REST API란 무엇인가",
  "content": "REST API는 ...",
  "createdAt": "2025-01-01"
}

응답 데이터는 주로 JSON 형식으로 주고받으며, 프론트엔드에서 이 데이터를 파싱해서 화면에 보여준다.

URI 설계 시 주의할 점

❌ /getPosts          → 동사 사용 금지
❌ /posts/delete/1    → URI에 행위를 넣지 않는다
❌ /Posts             → 대문자 사용 지양
❌ /posts/            → 마지막 슬래시(/) 사용 지양

✅ /posts
✅ /posts/{id}
✅ /posts/{postId}/comments

REST에서는 행위를 URI에 넣지 않고, HTTP 메서드로 표현하는 것이 핵심이다.

5. HTTP 상태 코드도 중요하다

REST API는 응답에 적절한 HTTP 상태 코드를 함께 보내야 한다. 단순히 200만 사용하는 것은 RESTful한 설계라고 보기 어렵다.

코드	의미	예시
`200 OK`	요청 성공	GET, PUT, PATCH 성공
`201 Created`	리소스 생성 성공	POST 성공
`204 No Content`	성공했지만 반환 데이터 없음	DELETE 성공
`400 Bad Request`	잘못된 요청	필수 파라미터 누락
`401 Unauthorized`	인증 필요	로그인 안 한 사용자
`403 Forbidden`	권한 없음	다른 사람 글 삭제 시도
`404 Not Found`	리소스 없음	존재하지 않는 게시글 조회
`500 Internal Server Error`	서버 오류	서버 내부 에러

6. 마치며

REST API는 단순히 HTTP로 데이터를 주고받는 것 그 이상이다. URI와 HTTP 메서드를 어떻게 조합하느냐, 상태 코드를 얼마나 의미 있게 사용하느냐에 따라 API의 완성도가 달라진다.

RESTful API는 그 원칙을 잘 지킨 API를 부르는 말이고, 현실에서는 두 단어가 혼용되는 경우가 많다는 것도 알아두면 좋다.

다음 글에서는 Spring Boot로 실제 REST API를 만들어보는 과정을 다뤄볼 예정이다.

[Kotlin] 코틀린 개요

devCloud — Fri, 8 May 2026 10:35:43 +0900

KOTLIN

코틀린(Kotlin) 개요

1. 코틀린이 무엇인가?
2. 왜 Kotlin을 쓰는가?
3. 어디에 쓰이나?
4. 자프링 vs 코프링
5. 어떤 걸 선택해야 할까?
6. 마치며

Java는 들어봤는데, Kotlin은 뭔가요?
요즘 Android 개발이나 백엔드에서 심심찮게 보이는 그 언어, 오늘 제대로 알아보자.

1. 코틀린이 무엇인가?

코틀린(Kotlin)은 JetBrains가 만든 정적 타입 프로그래밍 언어다. 2016년에 공식 출시됐고, 2017년에는 구글이 Android 공식 개발 언어로 채택하면서 폭발적으로 주목받았다.

가장 큰 특징은 Java와 100% 호환된다는 점이다. Kotlin 코드는 JVM 위에서 동작하기 때문에, 기존 Java 라이브러리를 그대로 사용할 수 있고, 하나의 프로젝트 안에서 Java와 Kotlin을 함께 사용하는 것도 가능하다.

Kotlin은 Java 생태계를 그대로 활용하면서도, 더 현대적인 문법과 안전성을 제공하는 언어다.

2. 왜 Kotlin을 쓰는가?

한마디로 요약하면 Java보다 코드가 훨씬 간결하고, 안전하다.

Java로 10줄 써야 할 코드를 Kotlin은 3줄로 끝내는 경우가 많다. 거기다 언어 차원에서 NPE(NullPointerException)를 방어하는 문법을 제공해서 런타임 에러도 줄어든다.

기본 문법에 대한 내용은 다음 포스팅에서 자세히 다룰 예정이다. 이번 글에서는 “코틀린이 어디에 쓰이는가”에 집중해보자.

3. 어디에 쓰이나?

분야	설명
Android 개발	Google 공식 언어. Jetpack Compose도 Kotlin 기반
백엔드 (Spring)	Spring Boot 5부터 Kotlin을 공식 지원
멀티플랫폼	Kotlin Multiplatform으로 iOS, Web도 커버 가능

백엔드 개발자라면 특히 자프링 vs 코프링 이야기를 한 번쯤 들어봤을 것이다.

4. 자프링 vs 코프링

자프링(Javaspring)은 Java + Spring의 조합, 코프링(Kopring)은 Kotlin + Spring의 조합을 부르는 말이다.

같은 Spring 프레임워크를 쓰지만, 어떤 언어로 작성하느냐에 따라 코드 스타일이 꽤 달라진다.

코드로 비교해보기

Entity 클래스를 예로 들어보자.

자프링 (Java + Spring)

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private int age;

    protected User() {}

    public User(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    public int getAge() { return age; }
}

코프링 (Kotlin + Spring)

@Entity
class User(
    val name: String,
    val age: Int,

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0
)

같은 기능인데 코드량 차이가 상당하다. Kotlin의 data class나 기본 생성자 문법 덕분에 보일러플레이트가 확 줄어든다.

5. 어떤 걸 선택해야 할까?

정답은 없다. 다만 각각의 특징을 정리하면 이렇다.

자프링이 유리한 경우

팀 내 Java 숙련도가 높을 때
레거시 Java 코드베이스를 유지보수할 때
Spring 관련 레퍼런스와 예제가 Java 기반일 때

코프링이 유리한 경우

새로운 프로젝트를 시작할 때
Null Safety와 간결한 문법의 장점을 활용하고 싶을 때
Android 개발과 백엔드를 함께 진행할 때

6. 마치며

Kotlin은 단순히 “Java의 대체제”가 아니다. Java 생태계를 그대로 활용하면서도 더 현대적인 언어 기능을 사용할 수 있다는 점에서, Java를 아는 개발자라면 배워두면 확실히 무기가 하나 더 생기는 느낌이다.

다음 글에서는 Kotlin의 기본 문법을 하나씩 파헤쳐볼 예정이다.

[리팩토링] 유지보수성을 높이기 위한 가독성 리팩토링 기록

devCloud — Thu, 7 May 2026 22:02:36 +0900

REFACTORING

중복 코드와 매직 스트링 제거로 가독성 개선하기

1. 왜 가독성 리팩토링을 했는가
2. 공통적으로 발견한 문제 패턴
3. 구체적인 개선 사례
4. 돌아보며

1. 왜 가독성 리팩토링을 했는가

기능 구현이 마무리된 시점에 전체 코드를 다시 훑어봤다. 동작에는 문제가 없었지만 군데군데 읽기 불편한 지점들이 눈에 띄었다.

컨트롤러마다 SecurityUtils.getCurrentUserId()를 반복 호출하고 있었다.
인증 목적을 나타내는 문자열이 상수가 아닌 리터럴로 여기저기 흩어져 있었다.
하나의 메서드가 너무 많은 일을 하고 있어서 흐름을 파악하려면 한참 읽어야 했다.

기능 개발 중에는 “일단 돌아가게” 하는 것이 우선이다 보니 이런 부분들이 자연스럽게 쌓인다. 하지만 이런 코드를 그대로 두면 나중에 수정할 때마다 먼저 코드를 해석하는 데 시간을 쓰게 된다.

그래서 기능 리팩토링과 별개로, 코드의 흐름을 더 빠르게 파악할 수 있도록 가독성 리팩토링을 따로 진행했다.

2. 공통적으로 발견한 문제 패턴

도메인을 하나씩 열어보니 비슷한 문제가 반복되고 있었다.

중복 코드

인증 사용자 ID를 꺼내는 코드가 컨트롤러 메서드마다 그대로 복사되어 있었다. 로직 자체는 한 줄이지만, 같은 코드가 여러 곳에 있으면 나중에 변경할 때 모든 위치를 찾아야 한다.

매직 스트링

의미를 알 수 있는 문자열이더라도 리터럴이 코드 여러 곳에 흩어져 있으면 관리가 어려워진다. 오타가 발생해도 컴파일 타임에 잡히지 않고, 키 형식을 바꾸려면 모든 참조 지점을 찾아 수정해야 한다.

메서드 비대

하나의 메서드가 생성, 검증, 매핑을 한꺼번에 처리하는 경우가 있었다. 메서드 이름만 봐서는 정확히 무엇을 하는지 알기 어렵고, 내부 구현을 끝까지 읽어야 흐름을 파악할 수 있었다.

모호한 네이밍

반환하는 값이 무엇인지 이름만으로 추론하기 어려운 경우가 있었다. 예를 들어 getUsers처럼 단순한 이름은 단건 조회인지, 목록 조회인지, 페이지 조회인지 구분하기 어렵다.

3. 구체적인 개선 사례

3-1. getCurrentUserId() 헬퍼 추출

컨트롤러마다 아래와 같이 현재 로그인한 사용자 ID를 꺼내는 코드가 반복됐다.

Long userId = SecurityUtils.getCurrentUserId();

컨트롤러 메서드마다 SecurityUtils.getCurrentUserId()를 직접 호출하던 코드다.

memo, post, progress, reminder 컨트롤러 모두 같은 구조였다. 동작상 문제는 없었지만 같은 코드가 여러 곳에 있으면 변경에 취약하다.

예를 들어 SecurityUtils의 메서드 시그니처가 바뀌거나, 예외 처리 방식을 통일하고 싶을 때 모든 컨트롤러를 뒤져야 한다. 그래서 각 컨트롤러에 getCurrentUserId() private 헬퍼 메서드를 추출해 호출 지점을 하나로 모았다.

private Long getCurrentUserId() {
    return SecurityUtils.getCurrentUserId();
}

SecurityUtils.getCurrentUserId() 호출을 private 헬퍼 메서드로 감싼 코드다.

단순한 위임처럼 보이지만, 이렇게 하면 이후에 로깅이나 예외 처리를 추가할 때 헬퍼 하나만 수정하면 된다. 그리고 메서드 본문에서 반복되는 노이즈가 사라져 핵심 로직이 더 잘 보인다.

3-2. 매직 스트링을 상수로 분리

AuthService에서 이메일 인증 목적을 구분하는 문자열이 리터럴로 사용되고 있었다.

// 변경 전
redisService.save("signup:" + email, code);
redisService.save("password-reset:" + email, code);

signup, password-reset 문자열을 Redis key 생성에 직접 사용하던 코드다.

signup, password-reset 같은 문자열은 의미를 어느 정도 알 수 있다. 하지만 코드 여러 곳에 흩어져 있으면 오타가 생겨도 컴파일 타임에 잡히지 않는다.

또한 나중에 키 형식을 바꾸려면 모든 참조 지점을 찾아 수정해야 한다. 그래서 인증 목적을 나타내는 문자열을 상수로 분리했다.

private static final String SIGNUP_PURPOSE = "signup";
private static final String PASSWORD_RESET_PURPOSE = "password-reset";

인증 목적 문자열을 SIGNUP_PURPOSE, PASSWORD_RESET_PURPOSE 상수로 분리한 코드다.

이제 목적 값을 바꾸고 싶으면 상수 선언 한 줄만 수정하면 된다. 또한 이름이 의도를 담고 있기 때문에 코드를 읽을 때 문자열의 의미를 다시 추론하지 않아도 된다.

4. 돌아보며

가독성 리팩토링은 기능을 새로 추가하는 작업보다 훨씬 조용한 작업이었다. 화면에 보이는 변화도 없고, 테스트가 통과하는 것 외에는 겉으로 드러나는 차이가 크지 않았다.

하지만 전체 코드를 훑고 나니 코드를 읽는 흐름은 확실히 달라졌다. 메서드 하나를 열었을 때 무엇을 하는지 더 빠르게 파악할 수 있었고, 같은 패턴이 어디 있는지 찾으러 다니는 시간도 줄었다.

동작은 그대로지만 읽히는 속도가 빨라진 느낌이었다. 결국 가독성 리팩토링은 지금 당장의 나보다 나중에 다시 코드를 읽을 나를 위한 작업이라고 느꼈다.

정리하면, 가독성 리팩토링은 기능을 바꾸는 작업은 아니지만 유지보수 비용을 줄이는 작업이다. 코드를 더 쉽게 읽고, 더 안전하게 수정할 수 있게 만드는 것도 중요한 개발 작업이다.

[트러블슈팅] JWT secret 키 길이 부족으로 인한 WeakKeyException

devCloud — Thu, 7 May 2026 21:49:46 +0900

TROUBLESHOOTING

JWT secret 키 길이 부족으로 인한 WeakKeyException 해결

1. 구현 배경
2. 문제 상황
3. 원인
4. 해결
5. 왜 시작 시점에 터지는가
6. 배운 점

1. 구현 배경

JWT 기반 인증 시스템을 구현했다. JwtProvider에 @PostConstruct로 init() 메서드를 작성해 애플리케이션 시작 시 secret 키를 초기화하도록 했고, application.yml에 jwt.secret 값을 설정했다.

JWT 서명에는 secret 키가 사용된다. 이 키는 토큰이 변조되지 않았는지 검증하는 기준이 되기 때문에, 사용하는 알고리즘이 요구하는 최소 길이를 만족해야 한다.

2. 문제 상황

애플리케이션을 실행하자마자 서버가 시작되지 않았고, jwtProvider 빈 생성 과정에서 초기화 메서드 실행에 실패했다.

Error creating bean with name 'jwtProvider': Invocation of init method failed

스택 트레이스를 따라가보니 근본 원인은 WeakKeyException이었다. 지정한 secret 키의 길이가 JWT HMAC-SHA 알고리즘에서 요구하는 보안 기준을 충족하지 못했다.

io.jsonwebtoken.security.WeakKeyException: The specified key byte array is 152 bits which is not secure enough for any JWT HMAC-SHA algorithm.

3. 원인

원인은 application.yml에 설정한 jwt.secret 기본값이 너무 짧았기 때문이다.

app.jwt.secret=${JWT_SECRET:change-me-for-local}

기본값으로 사용한 change-me-for-local은 길이가 짧아 HMAC-SHA256 알고리즘의 최소 요구 키 길이인 256비트(32바이트)를 만족하지 못했다.

HMAC-SHA256을 사용할 경우 secret 키는 최소 32바이트 이상이어야 한다. 그보다 짧은 키를 사용하면 jjwt가 WeakKeyException을 발생시켜 애플리케이션 시작을 막는다.

4. 해결

해결 방법은 jwt.secret 값을 32자 이상으로 변경하는 것이다. 로컬 환경에서는 충분한 길이의 임시 secret 값을 설정해 서버가 정상적으로 기동되도록 했다.

jwt:
  secret: booktine-secret-key-for-jwt-signing-must-be-32bytes-or-longer

secret 키 길이를 충분히 늘린 뒤 서버가 정상적으로 기동되었고, JwtProvider 초기화도 성공했다.

운영 환경에서 사용할 secret 키는 직접 작성하기보다, 아래와 같은 명령어로 충분히 긴 랜덤 값을 생성하는 것이 안전하다.

openssl rand -base64 64

생성한 값은 코드나 설정 파일에 직접 작성하지 않고 환경변수로 분리한 뒤, application.yml에서 참조하도록 구성한다.

jwt:
  secret: ${JWT_SECRET}

로컬 환경은 application-local.yml에 별도로 관리하거나, .env 파일로 분리해두는 방식이 깔끔하다.

5. 왜 런타임이 아니라 시작 시점에 터지는가

처음에는 요청을 처음 처리할 때 오류가 발생하는 것이 아니라, 왜 서버 시작 시점에 바로 실패하는지 의문이 들었다.

이유는 jjwt가 의도적으로 초기화 시점에 키 유효성을 검증하기 때문이다. @PostConstruct로 키를 초기화하는 시점에 스펙 미달 여부를 확인하고, 기준을 만족하지 못하면 즉시 예외를 던진다.

잘못된 키로 서버가 뜬 뒤 인증 요청이 들어올 때 문제가 발생하는 것보다, 아예 서버가 시작되지 못하게 막는 쪽이 더 안전하다. 이런 방식을 fail-fast라고 부른다.

fail-fast는 문제가 있는 설정이나 상태를 가능한 한 빠른 시점에 발견하고 차단하는 방식이다. 보안 설정처럼 잘못된 상태로 서버가 실행되면 위험해질 수 있는 영역에서는 특히 중요한 패턴이다.

스펙 미달 키로 서명된 토큰이 실제 트래픽에서 사용되는 상황 자체를 막는다는 점에서, jjwt의 초기화 시점 검증은 보안 측면에서도 올바른 설계라고 볼 수 있다.

6. 배운 점

HMAC-SHA256 기준 secret 키는 최소 32바이트, 즉 256비트 이상이어야 한다.
jjwt는 스펙 미달 키를 런타임이 아니라 초기화 시점에 차단한다.
운영 환경에서는 secret 값을 설정 파일에 직접 작성하지 말고 환경변수로 분리해야 한다.
운영 secret은 직접 작성한 문자열보다 충분한 길이의 랜덤 값을 사용하는 것이 안전하다.

정리하면, JWT secret은 단순한 문자열 설정값이 아니라 토큰의 신뢰성을 결정하는 보안 요소다. 알고리즘이 요구하는 최소 길이를 만족하고, 운영 환경에서는 반드시 환경변수로 안전하게 관리해야 한다.

[트러블슈팅] 커뮤니티 좋아요 상태 불일치로 인한 409 오류

devCloud — Thu, 7 May 2026 21:27:35 +0900

TROUBLESHOOTING

커뮤니티 좋아요 상태 불일치로 인한 409 오류

1. 문제 상황
2. 원인 분석
3. 해결 방법
4. 적용 결과
5. 배운 점

1. 문제 상황

커뮤니티 게시글에서 좋아요 버튼을 클릭했을 때 간헐적으로 409 Conflict 오류가 발생했다.

처음에는 동시에 같은 요청이 여러 번 발생하는 동시성 문제를 의심했다. 하지만 재현 조건을 확인해보니 특정 상황에서 일관되게 발생하는 문제였다.

커뮤니티 댓글창에서 좋아요 버튼을 클릭하는 화면

좋아요 요청 이후 화면에서 확인된 409 Conflict 오류

브라우저 개발자 도구 Console에서 확인한 좋아요 요청 실패 로그

좋아요 요청 자체는 서버로 정상 전송되었지만, 서버 기준으로는 이미 좋아요가 존재하는 상태였기 때문에 중복 요청으로 판단되어 409 오류가 발생했다.

2. 원인 분석

원인은 좋아요 상태를 백엔드가 아닌 localStorage에 저장해 관리하고 있었기 때문이다.

localStorage를 기준으로 좋아요한 게시글 ID를 조회하고 저장하던 초기 코드

문제는 localStorage와 백엔드의 실제 좋아요 상태가 언제든 불일치할 수 있다는 점이다. 예를 들어 다음과 같은 상황에서 상태 불일치가 발생할 수 있다.

다른 기기나 다른 브라우저에서 이미 좋아요를 누른 경우
브라우저의 localStorage가 초기화된 경우
백엔드 DB의 좋아요 상태와 클라이언트 저장 상태가 달라진 경우

즉, localStorage에는 좋아요를 누르지 않은 상태로 저장되어 있지만, 백엔드에는 이미 좋아요 데이터가 존재할 수 있다. 이 상태에서 프론트엔드가 다시 좋아요 요청을 보내면 서버는 중복 좋아요 요청으로 판단하고 409 Conflict를 반환한다.

결국 근본 원인은 서버 상태와 동기화되어야 하는 좋아요 정보를 클라이언트 저장소인 localStorage를 기준으로 판단한 것이었다.

3. 해결 방법

해결 방법은 localStorage 기반 상태 관리를 제거하고, 백엔드에서 isLiked 필드를 직접 내려주는 방식으로 전환하는 것이었다.

3-1. CommunityPostResponse에 isLiked 필드 추가

먼저 게시글 응답 DTO인 CommunityPostResponse에 isLiked 필드를 추가했다. 이를 통해 프론트엔드는 localStorage가 아니라 서버가 내려준 좋아요 상태를 기준으로 버튼 상태를 렌더링할 수 있다.

CommunityPostResponse에 isLiked 필드를 추가하고, from() 메서드에서 좋아요 상태를 포함해 응답하도록 수정한 코드다.

3-2. 목록 조회 시 N+1 방지

게시글 목록을 조회할 때 게시글마다 existsByPostIdAndUserId()를 호출하면 게시글 수만큼 좋아요 조회 쿼리가 추가로 발생한다. 이는 전형적인 N+1 문제로 이어질 수 있다.

이를 방지하기 위해 사용자가 좋아요한 게시글 ID를 한 번에 조회하는 메서드를 추가했다.

사용자가 좋아요한 게시글 ID 목록을 한 번에 조회하는 findPostIdsByUserId() 쿼리 메서드다.

getPosts()에서 사용자가 좋아요한 게시글 ID를 Set으로 변환한 뒤, 각 게시글의 isLiked 값을 일괄 처리하는 코드다.

게시글마다 좋아요 여부를 개별 조회하지 않고, 좋아요한 게시글 ID 목록을 한 번에 가져온 뒤 Set으로 확인하면 N+1 문제를 줄일 수 있다.

3-3. 프론트 localStorage 제거

프론트엔드에서는 기존의 localStorage 기반 좋아요 상태 관리를 제거했다. 대신 백엔드 응답에 포함된 isLiked 값을 기준으로 좋아요 버튼 상태를 렌더링하도록 수정했다.

수정 후 toggleLike 함수다. 좋아요 상태를 localStorage가 아니라 백엔드에서 내려준 isLiked 기준으로 처리한다.

4. 적용 결과

좋아요 토글 시 발생하던 409 Conflict 오류가 해소되었다.
다른 기기나 브라우저에서도 좋아요 상태가 정확하게 반영되었다.
목록 조회 시 불필요한 개별 좋아요 조회 쿼리를 줄여 N+1 문제를 방지했다.
클라이언트 상태가 아니라 서버 상태를 기준으로 UI를 렌더링하게 되었다.

좋아요 상태의 기준을 localStorage에서 백엔드 응답의 isLiked로 변경하면서, 서버와 클라이언트 간 상태 불일치 문제를 해결할 수 있었다.

5. 배운 점

좋아요처럼 서버 상태와 동기화가 필요한 데이터는 클라이언트 저장소만으로 관리하면 안 된다. localStorage는 언제든 초기화될 수 있고, 여러 기기나 브라우저에서 접근할 경우 상태 불일치가 발생할 수 있다.

서버 상태는 서버가 내려주는 값을 신뢰의 기준으로 삼아야 한다. 클라이언트는 서버 응답을 받아 UI를 렌더링하고, 사용자 액션에 따라 서버에 변경 요청을 보내는 역할에 집중하는 것이 안전하다.

정리하면, 서버와 동기화되어야 하는 상태는 클라이언트 저장소를 기준으로 판단하지 말고, 백엔드 응답 값을 기준으로 관리해야 한다.