가장 직관적인 구현은 이렇다:

SELECT remaining FROM event WHERE id = ? FOR UPDATE;
-- remaining > 0이면 발급
UPDATE event SET remaining = remaining - 1 WHERE id = ?;
INSERT INTO coupon_issue (event_id, user_id) VALUES (?, ?);

문제는 FOR UPDATE가 행 단위 락을 건다는 것. 1,000명이 동시에 쿠폰을 요청하면 999명이 한 줄로 대기한다. HikariCP 기본 풀이 10개니까, 10번째 요청부터는 커넥션 대기 큐에 쌓인다. 요청이 많아지면 타임아웃, 데드락, 커넥션 풀 고갈이 순서대로 찾아온다.

p99 응답시간이 500ms를 넘기기 시작하면 사실상 서비스 장애다.

Redis 명령 하나하나는 원자적이다. 그런데 조합은 아니다

"그러면 Redis DECR로 재고 차감하면 되지 않나?" 맞다, 절반만.

Redis의 개별 명령(GET, DECR, SADD)은 싱글 스레드라서 각각은 원자적이다. 하지만 이걸 순차적으로 호출하면:

Thread A: GET stock → 1 (재고 있음)
Thread B: GET stock → 1 (재고 있음)
Thread A: DECR stock → 0
Thread B: DECR stock → -1  ← 초과 발급

GET과 DECR 사이에 다른 스레드가 끼어들 수 있다. 이게 "개별 명령은 원자적이지만 조합은 아니다"의 핵심이다.

Lua 스크립트: 3개 명령을 1개 원자 블록으로

Redis는 Lua 스크립트를 실행할 때 다른 명령을 끼워넣지 않는다. 서버 사이드에서 단일 블록으로 실행된다. 이걸 이용하면 GET + DECR + SADD를 하나의 원자적 연산으로 묶을 수 있다.

-- issue_coupon.lua
-- KEYS[1] = coupon:stock:{eventId}
-- KEYS[2] = coupon:issued:{eventId}
-- ARGV[1] = userId
-- ARGV[2] = ttlSeconds

-- 1) 재고 확인 — 매진이 전체 트래픽의 99%+ → 읽기 1회로 즉시 탈출
local stock = tonumber(redis.call('GET', KEYS[1]))
if stock == nil or stock <= 0 then
    return 0   -- 매진
end

-- 2) 중복 확인 — 읽기 1회 추가
if redis.call('SISMEMBER', KEYS[2], ARGV[1]) == 1 then
    return -1  -- 이미 발급됨
end

-- 3) 성공 경로에서만 쓰기 발생
redis.call('DECR', KEYS[1])
redis.call('SADD', KEYS[2], ARGV[1])

-- 4) issued Set에 TTL 없으면 설정(최초 발급 시점 기준)
if redis.call('TTL', KEYS[2]) == -1 then
    redis.call('EXPIRE', KEYS[2], ARGV[2])
end

return 1       -- 발급 성공

27줄. 이 안에 선착순 발급의 핵심 로직이 다 들어있다.

Check-then-Act: 매진 경로를 먼저 최적화하는 이유

선착순 이벤트의 트래픽 분포를 생각해보자. 쿠폰 1,000개에 요청 10,000건이면, 성공하는 건 1,000건(10%)이고 매진으로 튕기는 건 9,000건(90%)이다. 실제 운영에서는 이 비율이 99% 이상이다.

그래서 Lua 스크립트의 첫 번째 동작이 GET stock이다. 매진이면 읽기 1회로 바로 리턴하고, DECR이나 SADD 같은 쓰기 연산을 아예 안 한다. 90%+ 트래픽이 읽기 한 번만 하고 빠지는 구조다.

서비스 레이어: @Transactional을 어디에 걸 것인가

Lua 스크립트가 성공하면 DB에 발급 이력을 저장해야 한다. 여기서 @Transactional 배치가 중요하다.

처음에는 CouponIssueService 전체에 @Transactional을 걸었다. 코드 리뷰에서 이 문제가 잡혔다:

CouponIssueService.issue() {
    @Transactional  ← DB 커넥션 획득
    eventRepository.findById()        // DB 읽기
    redisStockRepository.initStock()  // ← Redis 호출인데 DB 커넥션 점유 중
    redisStockRepository.tryIssue()   // ← Redis 호출인데 DB 커넥션 점유 중
    couponIssueRepository.save()      // DB 쓰기
}                                     // ← 여기서 커넥션 반환

Redis 호출하는 동안에도 DB 커넥션을 붙잡고 있다. HikariCP 기본 풀이 10개인데, 200개 스레드가 동시에 들어오면 190개가 커넥션 대기에 걸린다. DB 락을 피하려고 Redis를 도입했는데 결국 커넥션 풀에서 병목이 생기는 거다.

해결책은 트랜잭션 범위를 쪼개는 것이다:

// CouponIssueService — @Transactional 없음
@Service
class CouponIssueService(
    private val eventRepository: EventRepository,
    private val redisStockRepository: RedisStockRepository,
    private val couponIssueTxService: CouponIssueTxService,
) {
    fun issue(eventId: UUID, userId: UUID): CouponIssueResponse {
        val event = eventRepository.findByIdOrNull(eventId)
            ?: throw BusinessException(ErrorCode.EVENT_NOT_FOUND)

        // 기간 검증
        if (!event.period.contains(Instant.now())) {
            throw BusinessException(ErrorCode.EVENT_NOT_OPEN)
        }

        // Redis 호출 — DB 커넥션 미점유
        val ttlSeconds = Duration.between(Instant.now(), event.period.endedAt)
            .plusHours(1).toSeconds()
        redisStockRepository.initStockIfAbsent(eventId, event.totalQuantity, ttlSeconds)

        val result = redisStockRepository.tryIssueCoupon(eventId, userId, ttlSeconds)
        when (result) {
            IssueResult.ALREADY_ISSUED -> throw BusinessException(ErrorCode.COUPON_ALREADY_ISSUED)
            IssueResult.SOLD_OUT -> throw BusinessException(ErrorCode.EVENT_SOLD_OUT)
            IssueResult.SUCCESS -> Unit
        }

        // DB 저장만 트랜잭션 — 커넥션 점유 최소화
        val couponIssue = couponIssueTxService.saveOrCompensate(eventId, userId)
        return CouponIssueResponse.from(couponIssue)
    }
}

// CouponIssueTxService — DB 저장 구간만 @Transactional
@Service
class CouponIssueTxService(
    private val couponIssueRepository: CouponIssueRepository,
    private val redisStockRepository: RedisStockRepository,
) {
    @Transactional
    fun saveOrCompensate(eventId: UUID, userId: UUID): CouponIssue {
        try {
            return couponIssueRepository.saveAndFlush(
                CouponIssue(eventId = eventId, userId = userId),
            )
        } catch (e: DataIntegrityViolationException) {
            // UK 위반: Redis는 정확, DB에 이미 존재 → stock만 복원
            redisStockRepository.restoreStock(eventId)
            throw BusinessException(ErrorCode.COUPON_ALREADY_ISSUED)
        } catch (e: DataAccessException) {
            // 기타 DB 오류: Redis 상태를 완전 롤백
            redisStockRepository.compensate(eventId, userId)
            throw e
        }
    }
}

Redis 호출 구간에서는 DB 커넥션을 잡지 않고, saveOrCompensate 안에서만 짧게 잡았다가 놓는다.

보상 처리: Redis는 성공했는데 DB가 실패하면?

Lua 스크립트가 성공(DECR + SADD)한 뒤 DB INSERT가 실패하는 경우가 있다. 이때 Redis 상태를 되돌려야 정합성이 유지된다.

여기서 중요한 건 실패 유형에 따라 보상 전략이 다르다는 점이다:

UK 위반 (DataIntegrityViolationException): Lua의 SISMEMBER를 통과했지만 극히 드문 타이밍에 DB에 먼저 기록된 경우. 이때 issued Set에는 userId가 이미 들어가 있으니 그건 그대로 두고, stock만 INCR로 복원한다. SREM까지 하면 같은 유저가 다시 발급받을 수 있다.

기타 DB 오류 (DataAccessException): 네트워크 장애, 타임아웃 등. 이 경우는 발급 자체가 없었던 걸로 만들어야 하니까 SREM(issued Set에서 제거) + INCR(stock 복원)을 둘 다 한다.

UK 위반  → restoreStock(INCR만)   — "발급은 됐으니 기록은 유지, 재고만 복원"
기타 오류 → compensate(SREM+INCR) — "아예 없었던 일로"

이 구분을 안 하면 동일 유저가 재발급받거나, 재고가 맞지 않는 상황이 생긴다.

코드 리뷰에서 잡힌 버그들

초기 구현 후 PR 리뷰에서 꽤 미묘한 버그들이 나왔다:

WRONGTYPE 버그: Redis에서 coupon:issued:{eventId} 키를 String으로 초기화했는데 Lua 스크립트에서는 Set 연산(SISMEMBER, SADD)을 했다. Redis는 키의 타입이 생성 시점에 고정되기 때문에 WRONGTYPE 에러가 발생했다. 초기화 코드에서 해당 키를 SET 명령 대신 EXPIRE만 거는 것으로 수정했다.

HTTP 상태코드 혼동: 매진을 처음에 409 Conflict로 리턴했다. 409는 "재시도하면 될 수 있음"이고, 410 Gone은 "리소스가 소진됨, 재시도 의미 없음"이다. 선착순 매진은 410이 맞다. 클라이언트가 불필요한 재시도를 하지 않도록 의미를 정확히 전달해야 한다.

Lua ARGV 타입: Duration.ofSeconds(3600)을 그대로 넘기면 Lua에 "PT3600S"라는 문자열이 도착한다. ttlSeconds.toString()으로 "3600"을 넘겨야 한다.

이런 건 테스트가 아니라 코드 리뷰에서만 잡히는 종류의 버그다.

동시성 테스트: "정말로 안전한가?"를 증명하기

코드 리뷰를 통과했으니 이제 실제로 동시에 수천 건을 쏴서 검증해야 한다. Kotest + Testcontainers로 4종의 테스트를 작성했다.

핵심은 이중 래치(Double Latch) 패턴이다:

fun concurrentExecute(
    taskCount: Int,
    poolSize: Int = minOf(taskCount, 200),
    action: (index: Int) -> Unit,
) {
    val executor = Executors.newFixedThreadPool(poolSize)
    val startLatch = CountDownLatch(1)    // 동시 출발 신호
    val doneLatch = CountDownLatch(taskCount)  // 전체 완료 대기

    repeat(taskCount) { i ->
        executor.submit {
            startLatch.await()  // 모든 스레드가 여기서 대기
            try {
                action(i)
            } finally {
                doneLatch.countDown()
            }
        }
    }

    startLatch.countDown()  // 한 번에 출발
    try {
        val completed = doneLatch.await(120, TimeUnit.SECONDS)
        check(completed) { "timed out" }
    } finally {
        executor.shutdownNow()  // 실패해도 스레드 정리 보장
        executor.awaitTermination(10, TimeUnit.SECONDS)
    }
}

이 패턴이 없으면 먼저 생성된 스레드부터 실행해서 "순차 요청"에 가까워진다. startLatch로 200개 스레드를 대기시킨 뒤 countDown() 한 번으로 동시에 출발시킨다.

TC-01: 초과 발급 검증

test("1,000개 쿠폰에 3,000건 동시 요청 시 정확히 1,000건만 발급된다") {
    val totalQuantity = 1_000
    val taskCount = 3_000
    val event = createOpenEvent(totalQuantity)
    val successCount = AtomicInteger(0)
    val soldOutCount = AtomicInteger(0)

    concurrentExecute(taskCount) { _ ->
        try {
            couponIssueService.issue(event.id, UUID.randomUUID())
            successCount.incrementAndGet()
        } catch (e: BusinessException) {
            when (e.errorCode) {
                ErrorCode.EVENT_SOLD_OUT -> soldOutCount.incrementAndGet()
                else -> throw e
            }
        }
    }

    // 3중 검증
    successCount.get() shouldBe totalQuantity        // 성공 1,000건
    soldOutCount.get() shouldBe (taskCount - totalQuantity)  // 매진 2,000건
    couponIssueRepository.count() shouldBe totalQuantity.toLong()  // DB도 1,000건
}

3,000건 요청에 정확히 1,000건만 발급. 1,001건도 아니고 999건도 아니다.

TC-02: 중복 발급 검증

동일한 userId로 100건을 동시에 쏜다. Lua의 SISMEMBER와 DB의 Unique Key가 이중으로 방어하므로 딱 1건만 발급된다.

TC-03: 매진 후 무결성

5개 쿠폰을 순차 발급으로 매진시킨 뒤 1,000건을 동시에 쏜다. 추가 발급 0건.

TC-04: Redis-DB 정합성

Redis의 coupon:issued:{eventId} Set 크기와 DB의 coupon_issue 테이블 row count가 일치하는지 검증.

4개 테스트 전부 통과. Lua 스크립트의 원자성이 실제 동시 환경에서 검증됐다.

테스트하면서 겪은 삽질

처음에 TC-01의 taskCount를 10,000으로 잡았다. 그런데 WSL2 + Testcontainers + HikariCP(기본 10개) 조합에서 120초 안에 안 끝났다. 200개 스레드가 10개 커넥션을 놓고 경쟁하니 커넥션 대기 시간이 누적되는 거다.

3,000건(재고의 3배)으로 줄였다. 동시성 안전성 증명에는 3배 과부하면 충분하고, CI 환경에서도 안정적으로 통과한다.

더 큰 문제도 있었다. TC-01이 타임아웃으로 실패한 뒤 TC-02에서 couponIssueRepository.count()가 224를 반환했다. TC-02는 동일 userId 100건이니 최대 1건이어야 하는데.

원인은 TC-01에서 executor.shutdown()에 도달하지 못한 것이다. check(completed)가 예외를 던지면서 200개 스레드가 정리되지 않고 백그라운드에서 계속 DB에 쓰고 있었다. beforeTest에서 deleteAllInBatch()를 해도 그 뒤에 잔여 스레드가 쓰니까 오염되는 거다.

try-finally로 executor.shutdownNow()를 감싸서 해결했다. 테스트가 실패해도 스레드 풀이 확실히 정리된다.

전체 아키텍처 흐름

Client → POST /api/v1/events/{eventId}/issue

CouponIssueService.issue(eventId, userId)
  ├── 1. eventRepository.findById()          ← DB Read (커넥션 잠깐 잡고 놓음)
  ├── 2. event.period.contains(now)          ← 기간 검증
  ├── 3. initStockIfAbsent(SET NX EX)       ← Redis (DB 커넥션 미점유)
  ├── 4. tryIssueCoupon(Lua 스크립트)         ← Redis (DB 커넥션 미점유)
  │     ├── SOLD_OUT(0)  → 410 Gone
  │     ├── ALREADY(-1)  → 409 Conflict
  │     └── SUCCESS(1)   → continue
  └── 5. CouponIssueTxService.saveOrCompensate()  ← @Transactional (여기만)
        ├── DB INSERT 성공 → 201 Created
        ├── UK 위반 → restoreStock(INCR) + 409
        └── DB 오류 → compensate(SREM+INCR) + re-throw

Redis 호출 구간(3~4)에서 DB 커넥션을 안 잡는다. DB 쓰기(5)에서만 짧게 잡았다가 놓는다.

배운 것들

"개별 명령은 원자적이지만 조합은 아니다." Redis를 쓰면서 가장 먼저 부딪히는 함정. Lua 스크립트가 이 문제의 정석적인 해법이다.

트랜잭션 범위는 최소화해야 한다. 특히 Redis 같은 외부 I/O를 포함하는 메서드에 @Transactional을 걸면 DB 커넥션이 Redis 응답을 기다리는 동안 낭비된다. 고동시성에서는 이게 전체 시스템을 죽인다.

보상 전략은 실패 유형별로 달라야 한다. UK 위반과 네트워크 오류를 같은 방식으로 롤백하면 데이터 불일치가 생긴다. 예외 타입을 구분해서 처리해야 한다.

테스트에서 스레드 풀은 반드시 정리해야 한다. executor.shutdown()이 실행 보장 안 되면 다음 테스트를 오염시킨다. 이건 코드 리뷰에서도 잡기 어렵고, 실제로 터져봐야 안다.

동시성 테스트에는 이중 래치가 필수다. 스레드를 만드는 것과 동시에 실행하는 것은 다르다. startLatch로 대기시킨 뒤 한 번에 출발시켜야 "진짜" 동시 요청이다.

이 프로젝트의 전체 코드는 spring-event-lab에서 볼 수 있다.

• Spring Boot 4 + Kotlin + PostgreSQL + Redis + Kafka
• DDD 기반 설계 (Aggregate 분리, Value Object, Rich Domain Model)
• Flyway 마이그레이션, QueryDSL (KSP), Testcontainers
• 혼자 개발하지만 AI와 페어 프로그래밍하는 느낌으로 진행

이 맥락에서 "나한테 효과적이었는가"를 기준으로 평가한다. 프론트엔드 프로젝트나 팀 프로젝트라면 결론이 달라질 수 있다.

핵심 플러그인: 이것만 있어도 된다

bkit (PDCA 워크플로우)

내 개발 흐름을 가장 많이 바꾼 플러그인이다.

/pdca plan event-crud → /pdca design event-crud → 구현 → /pdca analyze 순서로 진행하니까, "그냥 코드부터 치는" 습관이 사라졌다. Plan 문서에서 API 스펙과 에러코드를 먼저 정의하고, Design 문서에서 패키지 구조와 엔티티 설계를 잡고, 그 다음에 코드를 쓴다.

실제로 Event CRUD API를 구현할 때 Plan 단계에서 DateRange Value Object를 별도 설계하기로 결정했고, 이게 나중에 Coupon 유효기간에도 재사용됐다. 코드부터 쳤으면 Entity 안에 startedAt/endedAt을 날것으로 박아뒀을 거다.

단점도 있다. 문서 템플릿이 상당히 무겁다. feature 하나에 Plan + Design 문서가 각각 수백 줄이고, 에이전트가 18개 이상 정의되어 있어서 시스템 프롬프트가 길다. 간단한 버그 수정에도 "PDCA 사이클을 시작하시겠습니까?"라고 물어올 때가 있다. 토큰 소모가 체감된다.

평점: 4/5 — 문서 주도 개발 습관을 만들어주지만, 가벼운 작업에는 과하다.

commit-commands

/commit 한 번이면 변경 사항을 분석하고, 최근 커밋 스타일에 맞춰서 메시지를 만들어준다. 내 프로젝트 커밋 로그를 보면 feat:, refactor:, fix: 접두사가 일관되게 붙어 있는데, 이게 이 플러그인 덕이다.

/commit-push-pr도 있는데 이건 브랜치 생성 → 커밋 → 푸시 → PR 생성까지 원스톱이다. 단독 개발이라 PR을 자주 만들진 않지만, 가끔 코드 리뷰를 받을 때 유용했다.

단점은 특별히 없다. 단순하고, 하는 일이 명확하다.

평점: 5/5 — 모든 Claude Code 사용자에게 추천.

kotlin-lsp

Kotlin 프로젝트면 필수다. go-to-definition, 참조 찾기, 리팩토링 지원이 된다. Claude가 코드를 수정할 때 LSP 정보를 참고하니까 "이 메서드 어디서 호출되지?" 같은 질문에 정확한 답을 준다.

설치에 brew install JetBrains/utils/kotlin-lsp가 필요한데, Linux/WSL 환경이면 별도 설정이 필요할 수 있다.

평점: 4/5 — Kotlin 프로젝트라면 무조건. 아니면 무시.

유용하지만 선택적인 플러그인

code-review + code-simplifier

/code-review는 4개 에이전트가 병렬로 PR을 분석한다. CLAUDE.md 준수 여부, 버그 스캔, git blame 기반 히스토리 분석까지. 신뢰도 80점 이하는 필터링되니까 "이건 아닌데..." 싶은 지적이 적다.

/simplify는 코드 중복, 불필요한 복잡성을 찾아서 직접 수정해준다. Event CRUD 구현 후 돌렸더니 QueryDSL의 where 표현식 중복을 EventQuery object로 추출하라고 제안했다.

다만 두 플러그인 모두 PR이 있어야 제대로 동작한다. 로컬에서 커밋 없이 작업 중이면 분석 대상이 제한적이다.

평점: 각각 3.5/5 — PR 기반 워크플로우라면 효과적. 혼자 개발하면 가끔 쓰는 정도.

pr-review-toolkit

code-review의 상위 호환 같은 플러그인인데, 에이전트가 6개다. 주석 정확도, 테스트 커버리지, 에러 핸들링, 타입 설계, 코드 품질, 코드 간소화를 각각 전문 에이전트가 본다.

솔직히 code-review와 겹치는 부분이 많다. 둘 다 깔아놓으면 비슷한 리뷰를 두 번 받는 느낌이다. 하나만 고르라면 pr-review-toolkit이 더 세분화되어 있어서 이걸 추천한다.

평점: 3.5/5 — code-review랑 중복. 하나만 골라라.

context7 (MCP + Plugin)

라이브러리 문서 조회 도구다. "Spring Boot 4에서 Flyway 설정이 어떻게 바뀌었지?" 같은 질문에 최신 공식 문서를 기반으로 답해준다. 학습 데이터에 없는 최신 변경사항을 잡아준다는 점에서 가치가 있다.

여기서 삽질 에피소드가 하나 있다. MCP 서버와 Plugin이 별개라는 걸 모르고 둘 다 설치했다. MCP 서버(npx -y @upstash/context7-mcp)가 실제 문서 조회 엔진이고, Plugin은 "라이브러리 질문이 들어오면 context7 MCP를 써라"라는 트리거 지침일 뿐이다. Plugin만 깔고 MCP를 안 깔면 아무것도 안 된다. 반대로 MCP만 있어도 잘 동작한다.

평점: MCP 서버 4/5, Plugin 2/5 — MCP 서버가 본체. Plugin은 있으면 좋지만 필수는 아니다.

superpowers

개발 워크플로우 전체를 관리하는 야심찬 플러그인이다. 브레인스토밍 → 스펙 → 구현 계획 → 서브에이전트 병렬 실행까지 자동화한다는 콘셉트인데, bkit와 역할이 겹친다.

bkit가 PDCA라는 명확한 프레임워크를 제공하는 반면, superpowers는 TDD와 YAGNI 원칙을 강조하면서 좀 더 유연하게 접근한다. 둘 다 "코드부터 치지 마라"라는 철학은 같다.

내 경우 bkit를 먼저 도입해서 PDCA에 익숙해진 상태라 superpowers는 거의 안 썼다. 그런데 bkit 없이 시작하는 사람이라면 superpowers가 진입장벽이 낮을 수 있다.

평점: 3/5 — bkit와 양자택일. 둘 다 쓸 필요는 없다.

claude-md-management

/revise-claude-md로 세션 중 배운 내용을 CLAUDE.md에 반영할 수 있다. 프로젝트가 커지면서 컨벤션이 쌓이는데, 이걸 수동으로 관리하는 건 귀찮다.

내 CLAUDE.md에 "Kotlin @field: target 필수", "QueryDSL 정렬 필드는 화이트리스트 Map으로 관리" 같은 항목이 들어간 게 이 플러그인 덕이다.

평점: 3.5/5 — 장기 프로젝트에서 CLAUDE.md를 관리하고 있다면 가치 있다.

안 써도 됐던 것들

불필요했던 LSP 플러그인 3개

jdtls-lsp (Java), typescript-lsp, gopls-lsp (Go)를 전부 깔았다. Kotlin 프로젝트인데.

플러그인 마켓에서 "LSP? 좋은 거 아니야?" 하고 다 깔았는데, 이 프로젝트에 Java/TypeScript/Go 파일이 한 개도 없다. 세션 시작할 때 불필요한 LSP 프로세스가 뜨고, 시스템 프롬프트에 쓸데없는 지침이 들어간다.

교훈: 자기 프로젝트 기술 스택에 맞는 LSP만 설치하라.

figma, atlassian, gitlab

figma는 디자인 파일이 없으면 쓸 일이 없다. atlassian은 Jira/Confluence 연동인데, 인증 설정을 안 해서 매 세션마다 "Needs authentication" 경고가 뜬다. gitlab은 아예 연결 실패 상태.

이런 플러그인들이 문제인 게, 설치만 해도 시스템 프롬프트에 도구 설명이 추가된다. figma 하나만 봐도 도구 20개 이상의 설명이 주입된다. 안 쓰는 플러그인이 토큰을 잡아먹는 구조다.

여기서 느낀 건, 플러그인은 프로젝트 단위로 다르게 가져가야 한다는 거다. figma나 atlassian이 쓸모없는 플러그인이 아니라, 이 프로젝트에서 쓸모없는 거다. 프론트엔드 프로젝트라면 figma가 핵심일 수 있고, 팀 프로젝트에서는 atlassian이 Jira 티켓 → 코드 흐름을 이어주는 허브가 된다. .claude/settings.local.json이 프로젝트별로 존재하는 이유가 이거다. 글로벌에 다 깔아두지 말고, 프로젝트 설정에서 필요한 것만 켜라.

교훈: "나중에 쓸지도 몰라"로 깔지 마라. 필요할 때 깔아도 30초면 된다.

explanatory-output-style

코드 작성 전후에 ★ Insight 블록으로 교육적 설명을 붙여주는 기능이다. 단순히 코드를 고쳐주는 게 아니라, 왜 이렇게 고치는 게 나은지 원리와 베스트 프랙티스를 같이 설명해준다.

새로운 언어나 프레임워크를 학습하면서 개발하는 상황이라면 꽤 쓸 만하다. 나도 Kotlin QueryDSL을 처음 잡았을 때 "왜 where 표현식을 이렇게 분리하는 게 좋은지" 설명을 보면서 감을 잡은 적이 있다. 코드 리뷰를 받는 것과 비슷한 효과라서, 주니어 개발자나 팀에 새로 합류한 사람이 코드베이스를 파악하면서 쓰기에 좋다.

문제는 토큰이다. 매 응답에 Insight가 붙으니까, 같은 작업에 대한 응답이 체감상 2-3배 길어진다. README에도 "토큰 비용 증가 주의"라고 적혀 있다. 이미 익숙한 코드를 수정할 때는 "이거 아는데..."하면서 스크롤하게 된다.

끄고 켜면서 학습 모드와 작업 모드를 오가는 게 이상적이긴 하다. 다만 현실적으로는 몇 번 읽다가 결국 끄게 되는 종류의 기능이다. 학습이 목적이면 켜두고, 속도가 목적이면 끄자.

삽질에서 배운 것들

권한 설정이 하나씩 쌓이는 문제

.claude/settings.local.json을 열어보니 permissions.allow 배열에 46개 항목이 있었다. Bash(./gradlew compileKotlin), Bash(curl -s "https://search.maven.org/...") 같은 구체적인 명령어가 하나하나 들어가 있다.

이건 매번 Claude가 명령어를 실행할 때마다 "허용"을 누른 결과다. 처음에는 보안상 좋다고 생각했는데, 실제로는 ls 한 번 치는 것도 허가를 받아야 했다.

해결은 글로벌 설정에 읽기 전용 명령어를 일괄 허용하는 것이었다:

{
  "permissions": {
    "allow": [
      "Bash(ls:*)",
      "Bash(pwd:*)",
      "Bash(which:*)",
      "Bash(tree:*)"
      // ... 등등
    ]
  }
}

교훈: 프로젝트 시작할 때 안전한 명령어 화이트리스트를 먼저 설정하라. 나중에 하면 이미 수십 개가 쌓여 있다.

MCP 서버와 Plugin의 관계

context7에서 겪은 건데, 같은 이름의 MCP 서버와 Plugin이 있으면 뭐가 뭔지 헷갈린다. 정리하면:

• MCP 서버 = 실제 동작하는 엔진. 프로세스가 떠서 도구(tool)를 제공한다.
• Plugin = 시스템 프롬프트에 지침을 주입하는 래퍼. "이런 상황에서 이 MCP 도구를 써라"라고 알려준다.

MCP 서버 없이 Plugin만 있으면 껍데기다. Plugin 없이 MCP 서버만 있으면 잘 돌아가지만, 자동 트리거가 약해질 수 있다.

bkit vs superpowers 충돌

둘 다 "코딩 전에 생각하라"는 워크플로우 플러그인이다. 동시에 활성화하면 세션 시작할 때 두 플러그인이 각각 지침을 주입한다. 토큰 낭비인 데다가, 가끔 superpowers가 브레인스토밍을 제안하는데 bkit은 PDCA를 제안하는 상황이 생긴다.

교훈: 워크플로우 플러그인은 하나만 쓰자.

내 추천 조합

Kotlin/Spring Boot 서버 개발 기준으로, 이 조합이면 충분하다:

총 5-6개. 나머지는 필요할 때 추가하면 된다.

마무리

18개 깔아보고 느낀 건, 플러그인은 많다고 좋은 게 아니라는 거다. 각 플러그인이 시스템 프롬프트에 지침을 추가하고, MCP 서버는 프로세스를 띄운다. 안 쓰는 플러그인이 토큰과 리소스를 잡아먹는 구조다.

시작은 커밋 플러그인 하나로 충분하다. 거기서 "문서화가 아쉽네" 싶으면 bkit를, "최신 라이브러리 문법을 모르겠네" 싶으면 context7을 추가하면 된다. 한 번에 다 깔지 말고, 불편함이 생길 때 그걸 해결하는 플러그인을 찾아라.

# 최소 시작 세트
/plugin install commit-commands@claude-plugins-official
/plugin install kotlin-lsp@claude-plugins-official  # 본인 언어에 맞는 LSP

나머지는 진짜 필요해질 때 설치해도 늦지 않다.

TIL을 꾸준히 쓰려고 Notion에 데이터베이스를 만들어뒀다. 템플릿도 있다. 잘한 점, 개선점, 배운 점 — 세 섹션으로 나눠서 쓰는 구조.

문제는 매번 Claude한테 이걸 설명해야 한다는 거다.

"오늘 Redis 캐시 적용했는데 무효화 전략을 안 세워서 터졌어. 이거 TIL로 만들어줘. 포맷은 이거고, 잘한 점에는 이걸 넣고, 개선점에는 저걸 넣고..."

한두 번이면 괜찮은데, 매일 하니까 TIL 쓰는 것보다 TIL 포맷 설명하는 데 시간이 더 걸린다. 그래서 스킬로 만들기로 했다.

Claude 스킬이 뭔데

Claude에는 "스킬"이라는 개념이 있다. 쉽게 말하면 Claude한테 미리 주는 매뉴얼이다.

"TIL 써달라고 하면 이 템플릿 쓰고, Notion의 이 DB에 올리고, 이런 톤으로 써라" — 이걸 파일로 만들어서 Claude에 설치하면, 다음부터는 "TIL 써줘"라고만 해도 알아서 한다.

구조는 이렇게 생겼다:

til-manager/
├── SKILL.md              ← 메인 매뉴얼
└── references/
    ├── til-template.md    ← TIL 템플릿 + 예시
    ├── frontmatter-spec.md ← Git 푸시용 포맷
    ├── notion-setup.md    ← Notion DB 연결 가이드
    └── human-writing-guide.md ← "사람처럼 써라" 가이드

SKILL.md가 핵심이고, references/에 상세 가이드를 분리해둔다. Claude는 스킬이 트리거되면 SKILL.md를 읽고, 필요할 때만 reference 파일을 추가로 읽는다. Anthropic에서는 이걸 Progressive Disclosure라고 부른다.

만드는 과정

1단계: 뭘 만들지 정하기

skill-creator라는 내장 스킬이 있어서, "스킬 만들어줘"라고 하면 인터뷰를 해준다. 내가 답한 것들:

• 트리거: "TIL 작성해줘", "커밋 정리해줘", "오늘 회고" 같은 요청
• 입력: 커밋 로그 or 자유 텍스트
• 출력: Notion DB에 페이지 생성
• 추가 기능: 나중에 "TIL 푸시해줘"하면 Git에 Markdown으로 올리기

2단계: 템플릿 설계

기존에 쓰던 TIL 템플릿을 기반으로 했다:

## 잘한 점
  - 상황 → 액션 → 칭찬

## 개선점
  - 문제 → 원인 → 액션플랜

## 배운 점
  - 배움 → 의미

여기서 두 가지를 추가했다.

하나, "핵심 내용" 섹션. AI가 만드는 거니까 기술적 핵심을 자동으로 뽑아주면 좋겠다고 생각했다. "배운 점"이 회고라면, "핵심 내용"은 기술 노트다. 키워드, 개념 요약, 코드 스니펫, 참고 링크까지.

## 핵심 내용
  - 키워드: Cache-Aside, @CacheEvict, TTL
  - 요약: Cache-Aside는 읽기 중심 워크로드에 적합...
  - 코드: @Cacheable(value = "products", key = "#id")
  - 참고: Spring Cache 공식 문서 링크

6개월 뒤에 "Redis 캐시 어떻게 했더라?"하고 검색하면 바로 쓸 수 있는 레퍼런스가 된다.

둘, 하루 여러 개 TIL. 원래는 날짜당 하나였는데, 주제별로 나누는 게 더 나았다. [TIL-260409] Redis 캐시 전략, [TIL-260409] OAuth2 카카오 로그인 — 이런 식으로. 검색할 때 주제로 바로 찾을 수 있다.

3단계: Notion 연동

Claude.ai에서 Notion MCP(Model Context Protocol)를 연결하면 Notion을 직접 읽고 쓸 수 있다.

먼저 내 TIL 데이터베이스 구조를 확인했다:

Notion:notion-fetch(id: "https://www.notion.so/TIL-xxxxx")

결과: DB에 속성이 두 개 — [1/4](제목)과 작성일(날짜). 이걸 스킬에 넣어뒀다. 매번 "DB URL이 뭐예요?"하고 물어볼 필요가 없어진다.

Notion:notion-create-pages(
  parent: { data_source_id: "2f672cc5-d225-..." },
  pages: [{
    properties: {
      "[1/4]": "[TIL-260409] Redis 캐시 전략",
      "date:작성일:start": "2026-04-09"
    },
    content: "## 잘한 점\n..."
  }]
)

근데 여기서 한번 삽질했다. Notion MCP에 읽기 권한만 있으면 페이지 생성이 안 된다. "This connector requires additional permissions" 에러가 나온다. Notion 연결을 끊고 다시 연결해서 쓰기 권한까지 줘야 한다. 이것도 "개선점"이었다 — MCP 연동할 때 권한부터 체크하자.

4단계: "사람처럼 써라" 가이드

여기가 좀 재밌었다. Claude가 TIL을 써주면 기본적으로 이런 톤이 나온다:

"Redis 캐시를 적용하여 API 응답 속도를 유의미하게 개선하였습니다. 이를 통해 성능 최적화의 중요성을 인식하게 되었습니다."

이건 내 TIL이 아니라 보고서다. 내가 쓰면 이렇게 쓴다:

"Redis 캐시 붙이니까 응답이 확 빨라졌다. 근데 무효화 전략을 안 세우고 넣어서 한번 터졌음..."

그래서 human-writing-guide.md를 만들었다. 핵심 규칙:

1. 입력 톤 미러링 — 내가 "삽질했음"이라고 쓰면, TIL도 "삽질했다"로 써라. "시행착오를 겪었다"로 바꾸지 마라.
2. 구체적 숫자 — "유의미하게 개선"(X) → "300ms에서 20ms로 줄었다"(O)
3. 솔직한 한계 — "완벽하게 해결했다"(X) → "일단 TTL로 땜빵했는데 근본적 해결은 아닌 것 같다"(O)
4. 핵심 내용만 예외 — 여기는 기술 문서 톤으로 딱딱하게 써도 OK. 나중에 레퍼런스로 찾아볼 때는 간결하고 정확한 게 낫다.

human-writing이라는 별도의 스킬 가이드가 있어서, 그 원칙들을 TIL 한국어 맥락에 맞게 어댑트했다. Self-Check 질문 7개, Quick Fixes, 감정 표현 사전까지 포함.

5단계: 패키징

cd /mnt/skills/examples/skill-creator
python -m scripts.package_skill /home/claude/til-manager /output/
# → til-manager.skill 생성

.skill 파일 하나가 나온다. 이걸 Claude에 설치하면 끝.

실제로 쓰면 이런 느낌

입력:

오늘 Redis 캐시 적용해서 API 응답 속도 많이 개선함.
근데 캐시 무효화 전략을 제대로 안 세워서 데이터 정합성 이슈가 한번 터졌음.
TTL로 임시 처리했는데 근본적인 해결은 아닌 것 같음.
Cache-Aside 패턴이랑 Write-Through 패턴 차이를 확실히 이해하게 됨.

출력 (Notion에 자동 생성):

제목: [TIL-260409] Redis 캐시 전략

## 잘한 점
### 상황 1
- API 응답이 느려서 Redis 캐시를 적용하기로 했다.
### 액션 1
- Redis 캐시 붙여서 API 응답 속도를 많이 개선했다.
### 칭찬 1
- 성능 문제를 직접 캡치해서 캐시까지 적용한 것. 좋았다.

## 개선점
### 문제 1
- 캐시 무효화 전략을 안 세우고 넣어서 데이터 정합성 이슈가 한번 터졌다.
### 원인 1
- 급하게 넣다 보니 무효화 전략을 미리 안 짰다. TTL로 일단 땜빵.
### 액션플랜 1
- Cache-Aside vs Write-Through 비교해보고 우리 서비스에 맞는 전략 확정하자.

## 배운 점
### 배움 1
- Cache-Aside는 읽기 중심일 때, Write-Through는 쓰기 정합성이 중요할 때.
### 의미 1
- 캐시는 "붙이면 빨라지는 것"이 아니라 "무효화까지 세트"라는 걸 몸으로 배웠다.

## 핵심 내용
### 키워드
- Cache-Aside, Write-Through, TTL, @Cacheable, @CacheEvict
### 요약
- Cache-Aside: 읽기 시 캐시 miss → DB 조회 → 캐시 저장. 쓰기 시 DB 업데이트 → 캐시 삭제.
- Write-Through: 쓰기 시 캐시와 DB 동시 업데이트. 정합성 중요할 때.
### 코드
@Cacheable(value = "products", key = "#id")
public Product getProduct(Long id) { ... }

@CacheEvict(value = "products", key = "#id")
public void updateProduct(Long id, ProductDto dto) { ... }

입력 톤이 캐주얼하면 출력도 캐주얼하게 나온다. "유의미한 개선" 같은 표현 대신 "많이 개선했다", "한번 터졌다" 같은 표현을 쓴다.

삽질한 것들

1. human-writing 스킬 원본을 안 보고 추측으로 가이드를 만들었다

별도의 human-writing 스킬이 있는데, 파일이 미설치 상태였다. "대충 이런 내용이겠지" 하고 내 판단으로 가이드를 작성했는데, 나중에 원본을 받아보니 빠진 원칙들이 꽤 있었다. Self-Check 질문 7개, Quick Fixes 같은 것들.

교훈: 외부 참조를 통합할 때는 원본부터 확보하자.

2. Notion MCP 권한 문제

읽기는 되는데 쓰기가 안 돼서 페이지 생성을 못 했다. Notion MCP를 연결할 때 "Insert content" 권한이 별도로 필요한데, 기본 연결로는 읽기만 된다. 연결을 끊고 다시 연결해야 한다.

교훈: MCP 연동할 때 읽기/쓰기 권한을 미리 체크하자.

3. 데이터베이스 ID vs Data Source ID

Notion MCP에서 DB에 페이지를 추가하려면 database_id가 아니라 data_source_id를 써야 한다. DB URL에서 바로 보이는 ID는 페이지 ID고, 실제 데이터소스 ID는 notion-fetch로 조회해야 나온다. 이거 헷갈려서 좀 삽질했다.

다른 사람도 쓸 수 있게 만들기

여기까지 만들고 보니 문제가 하나 있었다. 내 Notion DB 정보가 스킬에 직접 박혀있다.

# notion-setup.md (초기 버전)
Data Source ID: 2f672cc5-d225-81a6-a131-000b2b6e5f02
Title 속성: [1/4]
Date 속성: 작성일
Git repo: https://github.com/Get-bot/TIL

나 혼자 쓸 때는 문제없다. 근데 이걸 GitHub에 올려서 다른 사람도 쓰게 하려면? 다른 사람의 Notion DB는 ID도 다르고, 속성 이름도 다를 수 있다. "Name"일 수도 있고 "제목"일 수도 있고. 스킬 파일을 직접 열어서 ID를 바꾸라고 하면... 그건 좀 아닌 것 같다.

그래서 자동 설정(Phase 0)을 추가했다.

아이디어: 첫 실행 시 알아서 세팅

원리는 간단하다. 스킬이 처음 트리거될 때 Claude의 memory를 확인한다. TIL 관련 설정이 없으면 setup 모드로 들어간다.

[TIL 요청 진입]
  ↓
memory에 til_notion_data_source_id 있나?
  ├─ YES → 바로 TIL 작성 시작
  └─ NO  → "TIL DB가 아직 없네요. 새로 만들까요, 기존 거 연결할까요?"

사용자가 "새로 만들어줘"라고 하면 Notion:notion-create-database로 DB를 생성하고, "기존 거 연결해줘"라고 하면 URL을 받아서 스키마를 자동 감지한다. 그리고 설정값을 memory에 저장한다.

memory_user_edits(command="add", control="TIL Notion data_source_id: abc123...")
memory_user_edits(command="add", control="TIL Notion title 속성: Name")
memory_user_edits(command="add", control="TIL Notion date 속성: 작성일")

다음부터는 memory에서 읽어오니까 다시 물어볼 필요가 없다.

바꾼 것들

1. SKILL.md — Phase 0 (Setup) 섹션 추가. 모든 TIL 작업 전에 memory 확인하는 로직.
2. notion-setup.md — 하드코딩된 DB 정보 전부 제거. "memory에서 읽어온다"로 변경.
3. frontmatter-spec.md — Git repo URL 하드코딩 제거. {til_git_repo} 플레이스홀더로.

Git 설정은 optional로 뺐다. Notion만 쓰고 Git은 안 쓰는 사람도 있을 수 있으니까. "TIL 깃에 올려줘"라고 처음 말할 때 그때 설정하면 된다.

이게 왜 필요했냐면

스킬은 결국 재사용 가능한 워크플로우다. 나만 쓸 수 있는 스킬은 스크립트랑 다를 게 없다. 설정을 스킬 코드에서 분리해야 다른 사람도 "설치하고 바로 쓸 수 있다"가 된다. 환경 변수를 하드코딩하지 않는 것과 같은 원리다.

배운 것 정리

스킬 구조는 단순하다

SKILL.md 하나 + 필요하면 references/. 끝이다. YAML frontmatter에 description을 쓰면 그게 트리거 역할을 한다. 사용자가 "TIL 써줘"라고 하면 Claude가 description을 보고 "아 이 스킬을 쓸 때구나" 하고 SKILL.md를 읽는다.

트리거 설계가 중요하다

skill-creator 문서에 이런 말이 있다: "Claude는 undertrigger 경향이 있다." 즉, 스킬을 안 쓸 때보다 안 쓰는 쪽으로 실수하기 쉽다. 그래서 description에 트리거 문구를 좀 과하게 넣는 게 낫다.

description: >
  "TIL 작성", "오늘 회고", "TIL 푸시", "오늘 뭐했는지 정리",
  "커밋 정리해줘", "TIL 노션에 올려줘", "Redis 공부한 거 TIL로 만들어줘"
  같은 요청이 들어오면 이 스킬을 사용한다.

이건 API 설계랑 비슷한 마인드셋이다. "내가 만들고 싶은 것"이 아니라 "사용자가 실제로 뭐라고 말할까"부터 생각하는 것.

AI한테 "사람처럼 써라"고 하려면 구체적이어야 한다

"자연스럽게 써줘"는 너무 막연하다. "~하였습니다를 ~했다로 바꿔라", "유의미한 대신 구체적 숫자를 써라", "입력이 캐주얼하면 출력도 캐주얼하게" — 이렇게 규칙을 명시해야 한다. 감정 표현 사전("뿌듯하다", "찝찝하다", "아직 갈 길이 멀다")까지 넣으니까 확실히 톤이 달라졌다.

설정은 코드에서 분리하자

처음에는 내 Notion DB ID를 스킬에 직접 넣었다. 나 혼자 쓸 때는 편하다. 근데 다른 사람이 쓰려면 스킬 파일을 열어서 수정해야 한다. 자동 설정(Phase 0)을 추가하니까 설치만 하면 바로 사용 가능한 형태가 됐다. 환경 변수를 .env로 빼는 것과 같은 원리인데, 스킬에서는 memory가 그 역할을 한다.

최종 구성

til-manager/
├── SKILL.md                          # 메인: Phase 0~2, 워크플로우, 입력 분석 가이드
└── references/
    ├── til-template.md               # TIL 템플릿 + 변환 예시
    ├── frontmatter-spec.md           # Git 푸시용 Markdown 포맷
    ├── notion-setup.md               # Notion DB 연결 가이드 (memory 기반)
    └── human-writing-guide.md        # 사람 톤 가이드, Self-Check, Quick Fixes

지원하는 워크플로우:

1. (첫 실행) 스킬이 알아서 Notion DB 생성/연결 + memory에 설정 저장
2. "오늘 TIL 써줘" + 커밋 로그 or 자유 텍스트 → Notion DB에 TIL 생성
3. Notion에서 리뷰/수정
4. "TIL 깃에 올려줘" → Markdown + frontmatter로 변환 → Git push

하루에 여러 주제로 나눠서 쓸 수 있고, 핵심 내용 섹션에서 기술 레퍼런스를 자동으로 뽑아준다.

마무리

솔직히 스킬 만드는 데 생각보다 시간이 걸렸다. 구조 자체는 단순한데, 템플릿 설계 + 톤 가이드 + Notion 연동 + 권한 삽질 + 범용화까지 하니까 반나절은 쓴 것 같다.

근데 한번 만들어두니까 확실히 편하다. "Redis 공부한 거 TIL로 만들어줘"라고 하면 끝이다. 포맷 설명할 필요 없고, Notion DB 구조 알려줄 필요 없고, "사람처럼 써달라"고 매번 부탁할 필요도 없다.

자주 반복하는 워크플로우가 있다면 스킬로 만들어보는 걸 추천한다. TIL 말고도 코드 리뷰 체크리스트, 장애 보고서, 회의록 정리 같은 것도 가능하다. 스킬 파일은 GitHub에 올려뒀고, npx로 바로 설치할 수 있다.

  npx skills add Get-bot/claude-toolkit/til-manager

Notion MCP만 연결하면 바로 쓸 수 있다.

복잡하게 얽힌 if-else 로직을 Chain of Responsibility 패턴으로 리팩토링하여 유연성과 확장성을 확보한 경험을 공유합니다.

문제 상황: 증식하는 if-else와 유지보수의 한계

담당하고 있는 이상거래 모니터링 시스템은 출금 요청 발생 시 다양한 조건을 검사하여 이상 징후를 포착해야 한다. 서비스 초기에는 조건이 단순했으나, 비즈니스 성장에 따라 초과 출금, 집중 출금, 실패 출금, 시간대 제한, 휴일 제한 등 감지해야 할 조건이 지속적으로 증가했다.

가장 큰 문제는 코드의 구조였다. 새로운 감지 조건이 추가될 때마다 서비스 클래스 내의 비대해진 if-else 블록을 수정해야 했다.

// [기존 코드] 여러 서비스에 분산되고 중복된 감지 로직
public AppValidateWithdrawBlockDto validateWithdrawBlockByCond(
        AppWithdrawDetectReqDto reqDto,
        AppWithdrawBlockDetectCondDto detectCondDto) {

    List<WithdrawLogStatusDto> logStatusDtos = new ArrayList<>();

    // 1. 초과 출금 감지
    if (detectCondDto.overWithdrawBlock() != null && detectCondDto.overWithdrawBlock().isActive()) {
        int count = withdrawRepository.countByOverBlock(reqDto.storeCode(), ...);
        if (count >= threshold) {
            logStatusDtos.add(new WithdrawLogStatusDto(DetectStatus.DETECT, ...));
        }
    }

    // 2. 집중 출금 감지
    if (detectCondDto.focusWithdrawBlock() != null && detectCondDto.focusWithdrawBlock().isActive()) {
        int count = withdrawRepository.countByFocusBlock(reqDto.storeCode(), ...);
        if (count >= threshold) {
            logStatusDtos.add(new WithdrawLogStatusDto(DetectStatus.DETECT, ...));
        }
    }

    // ... 끝없는 if-else의 반복 ...
}

"새로운 감지 조건 하나를 추가하기 위해 수정해야 할 포인트가 너무 많다."

단순한 코드량 증가를 넘어 구조적인 한계가 명확했다.

1. 로직의 파편화: 유사한 검증 로직이 여러 서비스 메서드에 흩어져 있어, 수정 시 누락으로 인한 버그 발생 위험이 높았다.
2. 경직된 유연성: "결제 앱(PayApp)별로 감지 순서를 다르게 설정하고 싶다"는 운영팀의 요구사항을 수용하기에는 if-else 기반의 하드코딩된 순서를 변경하기 어려웠다.

운영 편의성과 시스템 확장성, 두 마리 토끼를 잡기 위해 근본적인 구조 변경이 필요했다.

해결책: Chain of Responsibility 패턴

GoF의 디자인 패턴 중 Chain of Responsibility(책임 연쇄) 패턴을 도입하기로 결정했다. 요청을 처리할 수 있는 핸들러들을 체인(사슬)으로 연결하고, 요청을 체인을 따라 전달하면서 적절한 핸들러가 처리하도록 하는 방식이다.

Why Not Strategy Pattern? Strategy 패턴도 고려했으나, 현재 요구사항은 "단일 전략 선택"이 아닌 "순차적으로 여러 조건을 검사하다가, 하나라도 걸리면 즉시 탐지(중단)"하는 파이프라인 구조였다. 따라서 핸들러의 순서를 제어하고 책임을 다음 객체로 전파하는 Chain of Responsibility가 가장 적합했다.

설계 아키텍처

핵심 설계 원칙:

1. 단일 책임 원칙 (SRP): 각 핸들러는 오직 하나의 감지 조건(초과, 집중, 시간대 등)만 담당한다.
2. 개방-폐쇄 원칙 (OCP): 새 조건 추가 시 기존 코드를 수정하지 않고, 새로운 핸들러 클래스만 추가하여 확장한다.
3. 동적 우선순위 관리: 감지 순서를 코드가 아닌 DB에서 관리하여, 배포 없이 운영팀이 제어할 수 있게 한다.

구현: Step by Step

Step 1. 추상 핸들러와 템플릿 메서드

모든 감지 핸들러가 상속받을 추상 클래스다. handle() 메서드를 final로 선언하여 Template Method 패턴을 적용, 전체적인 처리 흐름을 하위 클래스에서 변경할 수 없도록 강제했다.

// [WithdrawDetectHandler.java]
public abstract class WithdrawDetectHandler<T extends WithdrawBlockDetectCondBase> {

    // 처리 흐름의 골격 정의 (Template Method)
    public final ValidateDetectDto handle(
            T detectCondDto,
            List<WithdrawLogType> allowedLogTypes,
            ValidateParamDto paramDto
    ) {
        // 1. 처리 가능 여부 확인
        if (!canHandle(detectCondDto, allowedLogTypes)) {
            return null; // Pass -> 다음 핸들러로
        }

        // 2. 실제 감지 로직 수행 (추상 메서드 위임)
        DetectStatus detectStatus = doDetect(detectCondDto, paramDto);

        // 3. 감지된 경우 결과 반환 (체인 중단)
        if (DetectStatus.DETECT == detectStatus) {
            return ValidateDetectDto.builder()
                    .detectStatus(detectStatus)
                    .logType(getLogType())
                    .build();
        }

        return null; // Pass
    }

    protected abstract boolean canHandle(T detectCondDto, List<WithdrawLogType> allowedLogTypes);
    protected abstract DetectStatus doDetect(T detectCondDto, ValidateParamDto paramDto);
    // ... 기타 메타데이터 메서드
}

제네릭 타입 T를 활용해 앱 기반 감지(App...Dto)와 매장 기반 감지(Store...Dto)를 유연하게 처리할 수 있도록 설계하여 타입 안정성을 확보했다.

Step 2. 구체 핸들러 구현 (단일 책임)

이제 각 감지 로직은 독립된 클래스로 분리된다. 아래는 '초과 출금'을 감지하는 핸들러의 예시다.

// [AppOverWithdrawBlockHandler.java]
@Component
@RequiredArgsConstructor
public class AppOverWithdrawBlockHandler extends WithdrawDetectHandler<AppWithdrawBlockDetectCondDto> {

    private final WithdrawRepository withdrawRepository;

    @Override
    protected boolean canHandle(AppWithdrawBlockDetectCondDto detectCondDto, List<WithdrawLogType> allowedLogTypes) {
        // 예외 허용 목록에 있거나, 조건이 비활성화된 경우 스킵
        if (allowedLogTypes != null && allowedLogTypes.contains(getLogType())) return false;

        AppOverWithdrawBlockDto overBlock = detectCondDto.overWithdrawBlock();
        return overBlock != null && overBlock.isActive();
    }

    @Override
    protected DetectStatus doDetect(AppWithdrawBlockDetectCondDto detectCondDto, ValidateParamDto paramDto) {
        // 순수한 비즈니스 로직에만 집중
        AppOverWithdrawBlockDto overBlock = detectCondDto.overWithdrawBlock();
        int detectCount = withdrawRepository.countAppWithdrawByOverBlock(paramDto.storeCode(), overBlock);

        return detectCount >= overBlock.thresholdCount()
                ? DetectStatus.DETECT
                : DetectStatus.PASS;
    }

    @Override
    protected WithdrawLogType getLogType() { return WithdrawLogType.OVER_WITHDRAW_BLOCK_LOG; }

    // ...
}

Step 3. Spring DI를 활용한 핸들러 자동 등록

새로운 핸들러를 추가할 때마다 등록 코드를 수동으로 수정해야 한다면 OCP 위반이다. Spring의 List 주입 기능을 활용해 이를 해결했다.

// [WithdrawHandlerRegistry.java]
@Component
@RequiredArgsConstructor
public class WithdrawHandlerRegistry {

    // Spring이 WithdrawDetectHandler 타입을 상속받은 모든 빈(Bean)을 자동으로 주입해준다.
    private final List<WithdrawDetectHandler<?>> handlers;

    // 조회 성능을 위한 캐싱 맵
    private final Map<WithdrawHandlerKey, WithdrawDetectHandler<?>> handlerIndex = new ConcurrentHashMap<>();

    @PostConstruct
    public void init() {
        // 주입받은 핸들러들을 메타데이터 기반으로 인덱싱하여 빠른 조회 지원
        for (WithdrawDetectHandler<?> handler : handlers) {
            // ... 인덱싱 로직 ...
        }
    }

    // ...
}

이 구조 덕분에 개발자는 핸들러 클래스를 만들고 @Component만 붙이면, 별도의 설정 변경 없이 자동으로 시스템에 통합된다.

Step 4. Thread-Safety를 위한 불변 체인(Immutable Chain)

웹 애플리케이션은 멀티스레드 환경이므로, 체인을 구성하는 리스트가 요청 처리 도중 변경되어서는 안 된다. 이를 방지하기 위해 체인을 불변(Immutable) 객체로 설계했다.

// [ImmutableHandlerChain.java]
public class ImmutableHandlerChain<T extends WithdrawBlockDetectCondBase> {

    private final List<WithdrawDetectHandler<T>> handlers;

    public ImmutableHandlerChain(List<WithdrawDetectHandler<T>> handlers) {
        // 생성 시점에 방어적 복사(Defensive Copy) 수행
        this.handlers = List.copyOf(handlers);
    }

    public ValidateDetectDto execute(T detectCondDto, ...) {
        for (WithdrawDetectHandler<T> handler : handlers) {
            try {
                ValidateDetectDto result = handler.handle(...);
                if (result != null) return result; // 감지됨!
            } catch (Exception e) {
                // 하나의 핸들러가 실패해도 전체 프로세스는 멈추지 않도록 예외 격리
                log.error("Handler failed", e);
            }
        }
        return ValidateDetectDto.pass();
    }
}

List.copyOf()를 사용해 불변 리스트를 생성함으로써, 원본 리스트가 외부에서 변경되어도 실행 중인 체인은 영향을 받지 않아 Thread-Safety가 보장된다.

Step 5. DB 기반의 동적 체인 구성

마지막 단계는 '순서의 제어'다. DB에 저장된 우선순위 설정(PriorityConfig)을 읽어 체인을 동적으로 조립한다.

// [WithdrawDetectChainBuilder.java]
public ImmutableHandlerChain<...> buildChain(UUID detectCondId) {
    // 1. DB에서 설정된 순서 조회 (예: 초과 -> 시간대 -> 휴일)
    List<WithdrawBlockType> orderedTypes = priorityConfigRepository.findOrderedTypes(...);

    // 2. 순서에 맞춰 핸들러 매핑
    List<WithdrawDetectHandler<T>> orderedHandlers = orderedTypes.stream()
            .map(handlerRegistry::getHandler)
            .filter(Objects::nonNull)
            .collect(Collectors.toList());

    // 3. 불변 체인 생성 후 반환
    return new ImmutableHandlerChain<>(orderedHandlers);
}

이제 운영팀이 관리자 페이지에서 감지 순서를 변경하면, 다음 요청부터 즉시 반영된다. 서버 재배포는 필요 없다.

운영 유연성: 공용 조건과 개별 조건의 조화

시스템은 두 가지 층위의 규칙을 소화해야 했다.

1. 공용 규칙: 결제앱(PayApp)마다 정해진 기본 감지 순서.
2. 개별 예외: 특정 VIP 회원이나 매장에 대한 예외 처리.

공용 규칙은 위에서 설명한 PriorityConfig로 해결했고, 개별 예외는 allowedLogTypes 파라미터를 통해 구현했다. 각 핸들러의 canHandle 메서드에서 이 목록을 체크하여, 특정 조건 검사를 건너뛰도록(Skip) 처리했다. 이를 통해 일관성 있는 정책 위에 유연한 예외 처리를 얹을 수 있었다.

결과 및 회고

이 리팩토링을 통해 얻은 성과는 다음과 같다.

1. 확장성 확보: 새로운 감지 조건이 필요하면 핸들러 클래스(@Component) 하나만 추가하면 된다. 기존 코드를 수정할 위험(Side Effect)이 사라졌다.
2. 운영 효율성 증대: 개발자의 개입 없이 운영팀이 직접 감지 우선순위를 조정할 수 있게 되어 업무 효율이 높아졌다.
3. 안정성 강화: 각 핸들러가 격리되어 있고, 불변 체인을 통해 동시성 문제로부터 안전하다. 또한 단위 테스트 작성이 훨씬 용이해졌다.

"코드가 고통스러워질 때가 바로 리팩토링의 적기다."

초기에는 단순했던 요구사항이 복잡해지면서 코드는 점차 유지보수하기 힘든 상태가 되었다. 하지만 적절한 시점에 디자인 패턴을 도입함으로써, 기술적 부채를 해결하고 비즈니스의 빠른 변화를 뒷받침할 수 있는 견고한 구조를 구축할 수 있었다.

참고 자료

• GoF Design Patterns - Chain of Responsibility
• Spring Framework Reference - IOC & DI
• Java Concurrency - Immutable Objects

OAuth2 인증 성공 후 자체 JWT를 발급하고, 실패 시 프론트엔드 친화적인 에러 응답을 반환합니다. 사용자 경험을 해치지 않으면서 보안을 유지하는 핸들러 설계를 다룹니다.

들어가며

이전 글에서 쿠키 기반 인증 상태 관리를 구현했습니다. 이번에는 OAuth2 인증의 마지막 단계인 핸들러를 다룹니다.

핸들러의 역할

1. OAuth2AuthenticationSuccessHandler 구현

전체 구조

package com.example.oauth2.handler;

import com.example.global.exception.CustomException;
import com.example.global.exception.ErrorCode;
import com.example.global.properties.Oauth2Properties;
import com.example.global.util.RefreshTokenCookieUtils;
import com.example.member.dto.Oauth2LoginResultDto;
import com.example.member.service.MemberOAuth2LinkService;
import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.userinfo.CustomOAuth2User;
import com.example.oauth2.client.core.userinfo.CustomOidcUser;
import com.example.oauth2.repository.HttpCookieOAuth2AuthorizationRequestRepository;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.core.Authentication;
import org.springframework.security.web.authentication.SimpleUrlAuthenticationSuccessHandler;
import org.springframework.stereotype.Component;
import org.springframework.web.util.UriComponentsBuilder;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

@Component
@RequiredArgsConstructor
@Slf4j
public class OAuth2AuthenticationSuccessHandler
        extends SimpleUrlAuthenticationSuccessHandler {

    private final HttpCookieOAuth2AuthorizationRequestRepository cookieRepository;
    private final MemberOAuth2LinkService memberLinkService;
    private final Oauth2Properties oauth2Properties;
    private final RefreshTokenCookieUtils refreshTokenCookieUtils;

    @Override
    public void onAuthenticationSuccess(
            HttpServletRequest request,
            HttpServletResponse response,
            Authentication authentication
    ) throws IOException {

        try {
            // 1. 프론트엔드 redirect_uri 쿠키에서 조회
            String loginRedirectUri = cookieRepository
                    .getRedirectUriFromCookie(request, response);

            // 2. OAuth2 사용자 정보 추출
            OAuth2UserInfo userInfo = extractUserInfo(authentication);

            log.info("OAuth2 login success: provider={}, providerId={}",
                    userInfo.provider(), userInfo.providerId());

            // 3. 회원 매핑/생성 + JWT 발급
            Oauth2LoginResultDto result = memberLinkService
                    .processOAuth2Login(userInfo);

            // 4. Refresh Token을 HttpOnly 쿠키에 저장
            refreshTokenCookieUtils.addRefreshTokenCookie(
                    response, result.refreshToken()
            );

            // 5. 프론트엔드 콜백 URL로 리다이렉트
            String targetUrl = buildSuccessUrl(loginRedirectUri);
            getRedirectStrategy().sendRedirect(request, response, targetUrl);

        } catch (Exception e) {
            log.error("OAuth2 success handler failed", e);
            handleFailure(request, response, e);
        }
    }

    /**
     * 성공 리다이렉트 URL 빌드
     */
    private String buildSuccessUrl(String callbackUrl) {
        return UriComponentsBuilder
                .fromUriString(oauth2Properties.authorizedRedirectUri())
                .queryParam(
                        oauth2Properties.cookie().redirectUriName(),
                        callbackUrl
                )
                .encode(StandardCharsets.UTF_8)
                .build()
                .toUriString();
    }

    /**
     * 핸들러 내 예외 발생 시 실패 처리
     */
    private void handleFailure(
            HttpServletRequest request,
            HttpServletResponse response,
            Exception e
    ) throws IOException {
        String targetUrl = UriComponentsBuilder
                .fromUriString(oauth2Properties.authorizedRedirectUri())
                .queryParam("error", "login_failed")
                .encode(StandardCharsets.UTF_8)
                .build()
                .toUriString();

        getRedirectStrategy().sendRedirect(request, response, targetUrl);
    }

    /**
     * Authentication에서 OAuth2UserInfo 추출
     */
    private OAuth2UserInfo extractUserInfo(Authentication authentication) {
        Object principal = authentication.getPrincipal();

        // Java 21 Pattern Matching for switch
        return switch (principal) {
            case CustomOidcUser oidc -> oidc.oauth2UserInfo();
            case CustomOAuth2User oauth2 -> oauth2.oauth2UserInfo();
            default -> throw CustomException.withDetails(
                    ErrorCode.BAD_REQUEST,
                    "Unexpected principal type: " + principal.getClass().getSimpleName()
            );
        };
    }
}

핵심 포인트

1. extractUserInfo(): CustomOidcUser/CustomOAuth2User에서 통합 DTO 추출
2. processOAuth2Login(): 회원 매핑/생성 + JWT 발급을 서비스에 위임
3. Refresh Token 쿠키: HttpOnly 쿠키로 안전하게 저장
4. 예외 처리: 핸들러 내 예외도 프론트엔드 친화적으로 응답

2. 회원 매핑 서비스

OAuth2 인증 후 기존 회원과 매핑하거나 새 회원을 생성합니다.

package com.example.member.service;

import com.example.auth.service.JwtTokenService;
import com.example.member.domain.Member;
import com.example.member.domain.MemberOAuth2Link;
import com.example.member.dto.Oauth2LoginResultDto;
import com.example.member.repository.MemberOAuth2LinkRepository;
import com.example.member.repository.MemberRepository;
import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.Optional;

@Service
@RequiredArgsConstructor
public class MemberOAuth2LinkService {

    private final MemberRepository memberRepository;
    private final MemberOAuth2LinkRepository linkRepository;
    private final JwtTokenService jwtTokenService;

    /**
     * OAuth2 로그인 처리
     * 1. 기존 연동 확인 → 있으면 해당 회원으로 로그인
     * 2. 이메일로 기존 회원 확인 → 있으면 연동 추가
     * 3. 없으면 새 회원 생성 + 연동
     */
    @Transactional
    public Oauth2LoginResultDto processOAuth2Login(OAuth2UserInfo userInfo) {
        // 1. 기존 OAuth2 연동 확인
        Optional<MemberOAuth2Link> existingLink = linkRepository
                .findByProviderAndProviderId(
                        userInfo.provider(),
                        userInfo.providerId()
                );

        Member member;

        if (existingLink.isPresent()) {
            // 기존 연동이 있으면 해당 회원 사용
            member = existingLink.get().getMember();
            // 프로필 정보 업데이트 (선택적)
            updateMemberProfile(member, userInfo);
        } else {
            // 이메일로 기존 회원 찾기
            member = findOrCreateMember(userInfo);
            // OAuth2 연동 추가
            createOAuth2Link(member, userInfo);
        }

        // JWT 토큰 발급
        String accessToken = jwtTokenService.createAccessToken(member);
        String refreshToken = jwtTokenService.createRefreshToken(member);

        return new Oauth2LoginResultDto(accessToken, refreshToken, member.getId());
    }

    private Member findOrCreateMember(OAuth2UserInfo userInfo) {
        // 이메일로 기존 회원 찾기
        if (userInfo.email() != null) {
            Optional<Member> existingMember = memberRepository
                    .findByEmail(userInfo.email());

            if (existingMember.isPresent()) {
                return existingMember.get();
            }
        }

        // 새 회원 생성
        Member newMember = Member.builder()
                .email(userInfo.email())
                .nickname(userInfo.getDisplayName())
                .profileImageUrl(userInfo.profileImageUrl())
                .phoneNumber(userInfo.getNormalizedPhoneNumber())
                .build();

        return memberRepository.save(newMember);
    }

    private void createOAuth2Link(Member member, OAuth2UserInfo userInfo) {
        MemberOAuth2Link link = MemberOAuth2Link.builder()
                .member(member)
                .provider(userInfo.provider())
                .providerId(userInfo.providerId())
                .email(userInfo.email())
                .build();

        linkRepository.save(link);
    }

    private void updateMemberProfile(Member member, OAuth2UserInfo userInfo) {
        // 프로필 이미지, 닉네임 등 업데이트 (선택적)
        if (userInfo.profileImageUrl() != null && member.getProfileImageUrl() == null) {
            member.updateProfileImage(userInfo.profileImageUrl());
        }
    }
}

Oauth2LoginResultDto

package com.example.member.dto;

public record Oauth2LoginResultDto(
        String accessToken,
        String refreshToken,
        Long memberId
) {

}

3. Refresh Token 쿠키 유틸리티

package com.example.global.util;

import com.example.global.properties.JwtProperties;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseCookie;
import org.springframework.stereotype.Component;

@Component
@RequiredArgsConstructor
public class RefreshTokenCookieUtils {

    private final JwtProperties jwtProperties;

    /**
     * Refresh Token을 HttpOnly 쿠키에 저장
     */
    public void addRefreshTokenCookie(
            HttpServletResponse response,
            String refreshToken
    ) {
        ResponseCookie cookie = ResponseCookie
                .from("refresh_token", refreshToken)
                .path("/")
                .httpOnly(true)                    // JavaScript 접근 차단
                .secure(jwtProperties.cookie().secure())  // HTTPS 전용
                .maxAge(jwtProperties.refreshTokenExpiration())  // 7일 등
                .sameSite("Lax")                   // CSRF 방어
                .build();

        response.addHeader("Set-Cookie", cookie.toString());
    }

    /**
     * Refresh Token 쿠키 삭제 (로그아웃 시)
     */
    public void deleteRefreshTokenCookie(HttpServletResponse response) {
        ResponseCookie cookie = ResponseCookie
                .from("refresh_token", "")
                .path("/")
                .httpOnly(true)
                .secure(jwtProperties.cookie().secure())
                .maxAge(0)  // 즉시 만료
                .sameSite("Lax")
                .build();

        response.addHeader("Set-Cookie", cookie.toString());
    }
}

4. OAuth2AuthenticationFailureHandler 구현

에러 분류 전략

package com.example.oauth2.handler;

import com.example.global.properties.Oauth2Properties;
import com.example.oauth2.repository.HttpCookieOAuth2AuthorizationRequestRepository;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.security.web.authentication.SimpleUrlAuthenticationFailureHandler;
import org.springframework.stereotype.Component;
import org.springframework.web.util.UriComponentsBuilder;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Map;

@Component
@RequiredArgsConstructor
@Slf4j
public class OAuth2AuthenticationFailureHandler
        extends SimpleUrlAuthenticationFailureHandler {

    /**
     * OAuth2 에러 코드 → 사용자 친화적 에러 정보 매핑
     */
    private static final Map<String, ErrorInfo> ERROR_MAPPINGS = Map.of(
            // 사용자 취소
            "access_denied",
            new ErrorInfo("USER_CANCELLED", "로그인이 취소되었습니다", false),

            // 토큰 오류
            "invalid_token",
            new ErrorInfo("INVALID_TOKEN", "인증 토큰이 유효하지 않습니다", true),

            // Provider 서버 오류
            "server_error",
            new ErrorInfo("PROVIDER_ERROR", "소셜 로그인 서비스에 문제가 발생했습니다", true),

            // 권한 오류
            "insufficient_scope",
            new ErrorInfo("INSUFFICIENT_SCOPE", "필요한 권한이 부족합니다", true),

            // 네트워크 오류
            "temporarily_unavailable",
            new ErrorInfo("TEMPORARILY_UNAVAILABLE", "일시적으로 서비스를 이용할 수 없습니다", true)
    );

    private static final ErrorInfo DEFAULT_ERROR =
            new ErrorInfo("OAUTH2_ERROR", "소셜 로그인 중 오류가 발생했습니다", true);

    private final HttpCookieOAuth2AuthorizationRequestRepository cookieRepository;
    private final Oauth2Properties oauth2Properties;

    @Override
    public void onAuthenticationFailure(
            HttpServletRequest request,
            HttpServletResponse response,
            AuthenticationException exception
    ) throws IOException {

        // 1. 모든 OAuth2 쿠키 정리
        cookieRepository.clearAllCookies(response);

        // 2. 에러 분류
        ErrorInfo errorInfo = resolveError(exception);

        // 3. 로깅 (심각도별)
        if (errorInfo.shouldAlert()) {
            // 시스템 오류: 개발팀 알림 필요
            log.error("OAuth2 authentication failed - code: {}, message: {}",
                    errorInfo.code(), exception.getMessage(), exception);
        } else {
            // 사용자 행동 (취소 등): 정보 로깅만
            log.info("OAuth2 authentication cancelled by user");
        }

        // 4. 프론트엔드로 에러 리다이렉트
        String targetUrl = UriComponentsBuilder
                .fromUriString(oauth2Properties.authorizedRedirectUri())
                .queryParam("error", errorInfo.code())
                .queryParam("message", errorInfo.message())
                .encode(StandardCharsets.UTF_8)
                .build()
                .toUriString();

        getRedirectStrategy().sendRedirect(request, response, targetUrl);
    }

    /**
     * 예외에서 에러 정보 추출
     */
    private ErrorInfo resolveError(AuthenticationException exception) {
        if (exception instanceof OAuth2AuthenticationException oauth2Ex) {
            String errorCode = oauth2Ex.getError().getErrorCode();
            return ERROR_MAPPINGS.getOrDefault(errorCode, DEFAULT_ERROR);
        }
        return DEFAULT_ERROR;
    }

    /**
     * 에러 정보 레코드
     * @param code 프론트엔드용 에러 코드
     * @param message 사용자용 메시지
     * @param shouldAlert 개발팀 알림 필요 여부
     */
    private record ErrorInfo(
            String code,
            String message,
            boolean shouldAlert
    ) {

    }
}

에러 분류 기준

프론트엔드 에러 처리

// /oauth2/callback 페이지
function OAuth2Callback() {
    const [searchParams] = useSearchParams();
    const navigate = useNavigate();

    useEffect(() => {
        const error = searchParams.get('error');
        const message = searchParams.get('message');

        if (error) {
            switch (error) {
                case 'USER_CANCELLED':
                    // 사용자 취소: 조용히 로그인 페이지로
                    navigate('/login');
                    break;

                case 'INVALID_TOKEN':
                case 'PROVIDER_ERROR':
                    // 시스템 오류: 에러 메시지 표시
                    alert(message || '로그인 중 오류가 발생했습니다.');
                    navigate('/login');
                    break;

                default:
                    alert(message || '알 수 없는 오류가 발생했습니다.');
                    navigate('/login');
            }
            return;
        }

        // 성공 처리...
    }, [searchParams, navigate]);

    return <div>로그인 처리 중...</div>;
}

5. Security Configuration에 핸들러 등록

package com.example.global.config;

import com.example.oauth2.handler.OAuth2AuthenticationFailureHandler;
import com.example.oauth2.handler.OAuth2AuthenticationSuccessHandler;
import com.example.oauth2.repository.HttpCookieOAuth2AuthorizationRequestRepository;
import com.example.oauth2.service.CustomOAuth2UserService;
import com.example.oauth2.service.CustomOidcUserService;
import lombok.RequiredArgsConstructor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final CustomOAuth2UserService customOAuth2UserService;
    private final CustomOidcUserService customOidcUserService;
    private final OAuth2AuthenticationSuccessHandler successHandler;
    private final OAuth2AuthenticationFailureHandler failureHandler;
    private final HttpCookieOAuth2AuthorizationRequestRepository cookieRepository;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
                // ... 기타 설정

                .oauth2Login(oauth2 -> oauth2
                        // 쿠키 기반 AuthorizationRequest 저장소
                        .authorizationEndpoint(authorization -> authorization
                                .authorizationRequestRepository(cookieRepository)
                        )

                        // 커스텀 UserService
                        .userInfoEndpoint(userInfo -> userInfo
                                .userService(customOAuth2UserService)
                                .oidcUserService(customOidcUserService)
                        )

                        // 커스텀 핸들러
                        .successHandler(successHandler)
                        .failureHandler(failureHandler)
                );

        return http.build();
    }
}

마치며

OAuth2 인증 핸들러를 구현하여 다음을 달성했습니다:

1. JWT 발급: OAuth2 인증 성공 후 자체 JWT 토큰 발급
2. 회원 매핑: 기존 회원 연동 또는 새 회원 생성
3. 보안 쿠키: Refresh Token을 HttpOnly 쿠키에 안전하게 저장
4. 에러 분류: 사용자 행동 vs 시스템 오류 구분
5. 프론트엔드 친화적: 에러 코드와 메시지를 URL 파라미터로 전달

전체 아키텍처 요약

시리즈 정리

이 시리즈에서 구현한 내용:

참고 자료

• Spring Security OAuth2 공식 문서
• 카카오 로그인 개발 가이드
• JWT.io - JWT 디버깅 도구
• OWASP 세션 관리 치트시트

이 글에서는 Filter, ThreadLocal, 그리고 jOOQ Condition을 조합하여, 기존 쿼리의 수정 없이 우아하게 데이터 격리를 구현한 경험을 공유합니다.

문제 상황

최근 이상거래 모니터링 시스템을 개발하며 '데이터 격리' 문제에 직면했습니다. 시스템 내에 다수의 결제 앱(PayApp)이 공존하는 환경이라, 관리자 권한에 따라 담당 앱 데이터만 엄격하게 격리하여 보여주는 구조가 필요했습니다.

결국 멀티테넌시(Multi-tenancy) 문제구나.

처음에는 단순하게 생각했습니다. API 엔드포인트마다 권한 검증 로직을 넣으면 되지 않을까? 하지만 이 시스템에는 결제 앱 ID를 참조하는 테이블이 수십 개에 달했습니다. 감지 조건, 감지 로그, 알림 설정, 수신자 관리 등 모든 도메인이 결제 앱과 연결되어 있었습니다.

모든 Repository 메서드에 memberId를 파라미터로 넘기고, 매번 권한 체크를 하라고?

이는 지나치게 비효율적이었습니다. 기존 코드를 전부 수정해야 할 뿐만 아니라, 실수로 누락될 경우 데이터 유출이라는 치명적인 보안 사고로 이어질 수 있기 때문입니다. 저는 더 안전하고 우아한 방법이 필요했습니다.

설계 고민

AOP vs Filter

처음 떠오른 방법은 AOP였습니다. @PreAuthorize나 커스텀 어노테이션으로 메서드 레벨에서 권한을 체크하는 방식입니다.

// AOP 방식 (고려했지만 선택하지 않음)
@AuthorizePayApp
public PayAppInfo getPayAppInfo(UUID payAppId) {
    // ...
}

하지만 목록 조회 API에서 문제가 발생했습니다. 결과를 가져온 후 애플리케이션 레벨에서 필터링하면 페이지네이션(Pagination)이 깨집니다. 즉, 쿼리 레벨에서 조건을 걸어야 했습니다.

Filter에서 컨텍스트를 설정하고, Repository에서 조건을 읽어오면 되지 않을까?

Filter는 모든 요청의 진입점입니다. 여기서 사용자 정보를 기반으로 접근 가능한 앱 목록을 조회하고, 어딘가에 저장해두면 Repository 계층에서 꺼내 쓸 수 있을 것입니다.

파라미터 전파 vs ThreadLocal

그렇다면 "어딘가"는 어디일까요? 두 가지 선택지가 있었습니다.

방법 1: 파라미터 전파

// Controller → Service → Repository로 계속 넘겨야 함
public List<DetectCond> getList(UUID memberId, Set<UUID> accessibleAppIds) {
    return repository.findAll(memberId, accessibleAppIds);
}

이 방법을 시도해 보려 했으나, 5분 만에 포기... 구현을 시작하자마자 한계를 직감했습니다. 모든 메서드 시그니처를 변경해야 했고, 파라미터가 누락되어도 컴파일 에러가 발생하지 않아 전체 데이터가 노출될 위험이 컸습니다.

방법 2: ThreadLocal

// 어디서든 현재 요청의 컨텍스트에 접근
Set<UUID> appIds = AppAccessContext.getAccessibleAppIds();

ThreadLocal은 스레드별로 독립된 저장소를 제공합니다. HTTP 요청은 하나의 스레드에서 처리되므로, 요청 시작 시 설정하고 끝날 때 정리하면 완벽한 '요청 스코프' 저장소가 됩니다.

이거다. 기존 코드를 거의 건드리지 않고 접근 제어를 적용할 수 있겠다.

구현

전체 구조

Step 1: ThreadLocal 컨텍스트

먼저 요청 스코프의 접근 정보를 저장할 컨텍스트를 만들었습니다.

public class AppAccessContext {

    private static final ThreadLocal<AppAccessInfo> CONTEXT = new ThreadLocal<>();

    // Filter에서 호출
    public static void set(UUID memberId, Set<UUID> accessibleAppIds, boolean isSuperAdmin) {
        CONTEXT.set(new AppAccessInfo(memberId, accessibleAppIds, isSuperAdmin));
    }

    // Repository에서 호출
    public static Set<UUID> getAccessibleAppIds() {
        AppAccessInfo info = CONTEXT.get();
        return info != null ? info.accessibleAppIds() : null;
    }

    // 슈퍼관리자 여부 확인
    public static boolean isSuperAdmin() {
        AppAccessInfo info = CONTEXT.get();
        return info != null && info.isSuperAdmin();
    }

    // 필터링이 필요한지 확인
    public static boolean requiresFiltering() {
        AppAccessInfo info = CONTEXT.get();
        if (info == null) {
            return false; // 컨텍스트 없음 (public API 등)
        }
        return !info.isSuperAdmin() && info.accessibleAppIds() != null;
    }

    // Filter의 finally에서 반드시 호출
    public static void clear() {
        CONTEXT.remove();
    }

    private record AppAccessInfo(
            UUID memberId,
            Set<UUID> accessibleAppIds,
            boolean isSuperAdmin
    ) {
        AppAccessInfo {
            // 불변성 보장
            accessibleAppIds = accessibleAppIds != null
                    ? Collections.unmodifiableSet(accessibleAppIds)
                    : Collections.emptySet();
        }
    }
}

핵심은 requiresFiltering() 메서드입니다. 슈퍼관리자이거나 컨텍스트가 설정되지 않은 경우(외부 API 등)에는 필터링 로직을 건너뛰게 설계했습니다.

Step 2: Filter 구현

Spring Security의 필터 체인에 위치할 커스텀 필터입니다.

@Component
@RequiredArgsConstructor
public class AppAccessFilter extends OncePerRequestFilter {

    private final MemberPayAppAccessRepository memberPayAppAccessRepository;

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain filterChain
    ) throws ServletException, IOException {
        try {
            setupAppAccessContext();
            filterChain.doFilter(request, response);
        } finally {
            // 반드시 정리해야 함 - 스레드 풀 재사용 시 오염 방지
            AppAccessContext.clear();
        }
    }

    private void setupAppAccessContext() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

        if (authentication == null || !authentication.isAuthenticated()) {
            return; // 인증되지 않은 요청
        }

        if (!(authentication.getPrincipal() instanceof PrincipalDetails principal)) {
            return;
        }

        UUID memberId = UUID.fromString(principal.id());
        List<String> roles = principal.getRole(principal.role());
        boolean isSuperAdmin = roles.contains(MemberRole.SUPER_ADMIN.getValue());

        if (isSuperAdmin) {
            // 슈퍼관리자는 DB 조회 없이 바로 설정
            AppAccessContext.set(memberId, null, true);
        } else {
            // 일반 관리자는 할당된 앱 목록 조회
            Set<UUID> accessibleAppIds = memberPayAppAccessRepository
                    .findPayAppIdsByMemberId(memberId);
            AppAccessContext.set(memberId, accessibleAppIds, false);
        }
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        // 외부 API 경로는 필터 제외
        String path = request.getRequestURI();
        return path.startsWith("/api/v1/external/")
                || path.startsWith("/api/v1/payment/result/");
    }
}

finally 블록에서 clear()를 호출하는 것이 매우 중요합니다.

Tomcat과 같은 WAS는 스레드 풀을 사용합니다. 이전 요청에서 설정된 ThreadLocal 값이 다음 요청에 남아있을 경우, 다른 사용자의 데이터가 노출되는 치명적인 보안 사고가 발생할 수 있습니다.

Step 3: Repository 구현

멤버-앱 접근 권한을 관리하는 Repository입니다.

@Repository
@RequiredArgsConstructor
public class MemberPayAppAccessRepository extends MemberPayAppAccessDao {

    private final DSLContext dslContext;

    // 멤버가 접근 가능한 앱 ID 목록 조회
    public Set<UUID> findPayAppIdsByMemberId(UUID memberId) {
        return new HashSet<>(
                dslContext
                        .select(MEMBER_PAY_APP_ACCESS.PAY_APP_ID)
                        .from(MEMBER_PAY_APP_ACCESS)
                        .where(MEMBER_PAY_APP_ACCESS.MEMBER_ID.eq(memberId))
                        .fetchInto(UUID.class)
        );
    }

    // 권한 부여
    public void grantAccess(UUID memberId, UUID payAppId, LocalDateTime createdAt) {
        dslContext
                .insertInto(MEMBER_PAY_APP_ACCESS)
                .set(MEMBER_PAY_APP_ACCESS.MEMBER_ID, memberId)
                .set(MEMBER_PAY_APP_ACCESS.PAY_APP_ID, payAppId)
                .set(MEMBER_PAY_APP_ACCESS.REG_DATE, createdAt)
                .onDuplicateKeyIgnore() // 중복 무시
                .execute();
    }

    // 권한 회수
    public void revokeAccess(UUID memberId, UUID payAppId) {
        dslContext
                .deleteFrom(MEMBER_PAY_APP_ACCESS)
                .where(MEMBER_PAY_APP_ACCESS.MEMBER_ID.eq(memberId))
                .and(MEMBER_PAY_APP_ACCESS.PAY_APP_ID.eq(payAppId))
                .execute();
    }
}

Step 4: jOOQ 조건 유틸리티

가장 중요한 부분입니다. 동적 쿼리의 복잡성을 캡슐화하여, 기존 쿼리에 접근 제어 조건을 손쉽게 끼워 넣을 유틸리티 클래스입니다.

@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class PayAppAccess {

    /**
     * PAY_APP_ID 필드를 가진 테이블 조회 시 사용
     * 예: .where(PayAppAccess.restrictByAppId(TABLE.PAY_APP_ID))
     */
    public static Condition restrictByAppId(Field<UUID> payAppIdField) {
        if (!AppAccessContext.requiresFiltering()) {
            // 슈퍼관리자 또는 컨텍스트 미설정
            return DSL.trueCondition();
        }

        Set<UUID> accessibleAppIds = AppAccessContext.getAccessibleAppIds();

        if (accessibleAppIds == null || accessibleAppIds.isEmpty()) {
            // 접근 가능한 앱이 없으면 결과도 없음
            return DSL.falseCondition();
        }

        return payAppIdField.in(accessibleAppIds);
    }

    /**
     * 단일 리소스 접근 검증 (상세 조회, 수정, 삭제 시)
     */
    public static void validateAccess(UUID payAppId) {
        if (!AppAccessContext.hasAccessTo(payAppId)) {
            throw new CustomException(ErrorCode.FORBIDDEN, "접근 권한이 없는 결제 앱입니다.");
        }
    }
}

초기에는 boolean을 반환하도록 설계했으나, 사용하는 곳마다 if문을 작성해야 하는 불편함이 있었습니다.

// 처음 시도 (불편함)
if (PayAppAccess.hasAccess(payAppId)) {
    conditions.add(TABLE.PAY_APP_ID.in(accessibleAppIds));
}

jOOQ의 Condition 객체를 직접 반환하면 훨씬 깔끔해지지 않을까?

restrictByAppId 메서드는 상황에 따라 trueCondition(), falseCondition(), 또는 in 조건을 반환합니다. 덕분에 비즈니스 로직에서는 복잡한 분기 처리 없이 이 메서드 하나만 호출하면 됩니다.

적용 예시

기존 쿼리에 단 한 줄만 추가하면 데이터 격리가 적용됩니다.

// 기존 코드
public List<DetectCondDto> getList(DetectCondListReqDto reqDto) {
    return dslContext
            .select(/* ... */)
            .from(APP_WITHDRAW_DETECT_COND)
            .where(APP_WITHDRAW_DETECT_COND.DEL_YN.eq("N"))
            .and(/* 기존 검색 조건 */)
            .fetchInto(DetectCondDto.class);
}

// 접근 제어 적용 후
public List<DetectCondDto> getList(DetectCondListReqDto reqDto) {
    return dslContext
            .select(/* ... */)
            .from(APP_WITHDRAW_DETECT_COND)
            .where(APP_WITHDRAW_DETECT_COND.DEL_YN.eq("N"))
            .and(PayAppAccess.restrictByAppId(APP_WITHDRAW_DETECT_COND.PAY_APP_ID)) // 이 한 줄 추가
            .and(/* 기존 검색 조건 */)
            .fetchInto(DetectCondDto.class);
}

단일 리소스 접근 시에는 검증 메서드를 사용한다.

public DetectCondDto getById(UUID id) {
    DetectCondDto dto = repository.findById(id);

    // 접근 권한 검증
    PayAppAccess.validateAccess(dto.payAppId());

    return dto;
}

장단점 분석

장점

• 기존 코드 수정 최소화: 쿼리에 한 줄만 추가하면 됨
• 일관성: Filter에서 한 번 설정하면 모든 곳에서 동일한 컨텍스트 사용
• 성능: 슈퍼관리자는 DB 조회 없이 바로 통과
• 테스트 용이: 테스트 시 AppAccessContext.set()으로 컨텍스트 주입 가능

단점

• ThreadLocal 관리 필수: clear() 누락 시 메모리 누수 또는 보안 사고
• 비동기 처리 주의: @Async 메서드에서는 컨텍스트가 전파되지 않음
• IDE 지원 부족: 호출 관계가 명시적이지 않아 추적이 어려울 수 있음

개선 방향

1. 비동기 지원: TaskDecorator를 구현하여 비동기 스레드에도 컨텍스트 전파
2. 캐싱: 동일 요청 내 반복 조회 시 캐시 활용
3. 감사 로그: 접근 시도 기록으로 보안 모니터링 강화

마무리

멀티테넌시 접근 제어를 구현하면서 중요한 점을 배웠습니다.

모든 메서드에 파라미터를 추가하는 건 확장 가능한 해결책이 아니다.

ThreadLocal은 '요청 스코프'라는 개념을 깔끔하게 추상화해 줍니다. 또한, jOOQ의 Condition은 조립이 가능(Composable)합니다. rueCondition() 과 falseCondition()을 활용하면 조건부 로직을 아주 우아하게 처리할 수 있습니다.

jOOQ의 Condition은 합성이 자유롭다.

이 패턴은 멀티테넌시뿐만 아니라, 논리적 삭제(Soft Delete)나 활성 상태 필터링 등 "전역적인 데이터 필터링이 필요한 상황"에서 범용적으로 활용할 수 있을 것입니다.

SPA(Single Page Application)와 OAuth2를 연동할 때 발생하는 상태 관리 문제를 쿠키 기반으로 해결합니다. CSRF 공격을 방어하면서 프론트엔드와 안전하게 통신하는 방법을 다룹니다.

들어가며

이전 글에서 Factory Pattern으로 Provider별 응답을 통합했습니다. 이번에는 OAuth2 인증 과정에서 상태를 어떻게 관리하는지 다룹니다.

문제: OAuth2 인증 상태 관리

OAuth2 인증은 여러 단계의 리다이렉트를 거칩니다:

[프론트엔드] → [백엔드] → [카카오] → [백엔드] → [프론트엔드]
    (1)         (2)        (3)        (4)          (5)

문제는 (2)와 (4) 사이에 상태를 어디에 저장할 것인가입니다:

1. AuthorizationRequest: CSRF 방어용 state 파라미터 검증에 필요
2. redirect_uri: 인증 성공 후 프론트엔드의 어느 페이지로 돌려보낼지

세션 vs 쿠키

SPA + 마이크로서비스 환경에서는 쿠키 기반이 더 적합합니다.

1. HttpCookieOAuth2AuthorizationRequestRepository 구현

Spring Security의 AuthorizationRequestRepository 인터페이스를 구현하여 쿠키 기반 저장소를 만듭니다.

전체 구조

package com.example.oauth2.repository;

import com.example.oauth2.client.core.dto.OAuth2AuthorizationRequestDto;
import com.example.oauth2.global.properties.Oauth2Properties;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.http.Cookie;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.ResponseCookie;
import org.springframework.security.oauth2.client.web.AuthorizationRequestRepository;
import org.springframework.security.oauth2.core.endpoint.OAuth2AuthorizationRequest;
import org.springframework.stereotype.Component;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Base64;
import java.util.Optional;

@Component
@RequiredArgsConstructor
@Slf4j
public class HttpCookieOAuth2AuthorizationRequestRepository
        implements AuthorizationRequestRepository<OAuth2AuthorizationRequest> {

    private final Oauth2Properties oauth2Properties;
    private final ObjectMapper objectMapper;

    // ==================== Repository Interface ====================

    /**
     * 쿠키에서 AuthorizationRequest를 로드합니다.
     */
    @Override
    public OAuth2AuthorizationRequest loadAuthorizationRequest(HttpServletRequest request) {
        return getCookieValue(request, oauth2Properties.cookie().authName())
                .map(this::deserialize)
                .orElse(null);
    }

    /**
     * AuthorizationRequest를 쿠키에 저장합니다.
     */
    @Override
    public void saveAuthorizationRequest(
            OAuth2AuthorizationRequest authorizationRequest,
            HttpServletRequest request,
            HttpServletResponse response
    ) {
        if (authorizationRequest == null) {
            deleteCookie(response, oauth2Properties.cookie().authName());
            return;
        }

        String serialized = serialize(authorizationRequest);
        if (serialized != null) {
            // 1. redirect_uri 쿠키 저장 (프론트엔드가 보낸 콜백 URL)
            String loginRedirectUri = request.getParameter(
                    oauth2Properties.cookie().redirectUriName()
            );
            if (loginRedirectUri != null && !loginRedirectUri.isBlank()) {
                addCookie(response, oauth2Properties.cookie().redirectUriName(),
                        loginRedirectUri);
            }

            // 2. AuthorizationRequest 쿠키 저장
            addCookie(response, oauth2Properties.cookie().authName(), serialized);
        }
    }

    /**
     * 쿠키에서 AuthorizationRequest를 제거하고 반환합니다.
     */
    @Override
    public OAuth2AuthorizationRequest removeAuthorizationRequest(
            HttpServletRequest request,
            HttpServletResponse response
    ) {
        OAuth2AuthorizationRequest authorizationRequest = loadAuthorizationRequest(request);
        deleteCookie(response, oauth2Properties.cookie().authName());
        return authorizationRequest;
    }

    // ==================== 추가 메서드 ====================

    /**
     * 프론트엔드 리다이렉트 URI를 쿠키에서 가져오고 삭제합니다.
     */
    public String getRedirectUriFromCookie(
            HttpServletRequest request,
            HttpServletResponse response
    ) {
        String loginRedirectUri = getCookieValue(
                request, oauth2Properties.cookie().redirectUriName()
        ).orElse("/");

        deleteCookie(response, oauth2Properties.cookie().redirectUriName());
        return loginRedirectUri;
    }

    /**
     * 모든 OAuth2 관련 쿠키를 삭제합니다.
     */
    public void clearAllCookies(HttpServletResponse response) {
        deleteCookie(response, oauth2Properties.cookie().authName());
        deleteCookie(response, oauth2Properties.cookie().redirectUriName());
    }

    // ==================== Cookie Operations ====================

    private Optional<String> getCookieValue(HttpServletRequest request, String cookieName) {
        if (request.getCookies() == null) {
            return Optional.empty();
        }
        return Arrays.stream(request.getCookies())
                .filter(cookie -> cookieName.equals(cookie.getName()))
                .map(Cookie::getValue)
                .findFirst();
    }

    private void addCookie(HttpServletResponse response, String name, String value) {
        ResponseCookie cookie = buildCookie(name, value,
                oauth2Properties.cookie().maxAgeSeconds());
        response.addHeader("Set-Cookie", cookie.toString());
    }

    private void deleteCookie(HttpServletResponse response, String name) {
        ResponseCookie cookie = buildCookie(name, "", 0);
        response.addHeader("Set-Cookie", cookie.toString());
    }

    private ResponseCookie buildCookie(String name, String value, int maxAge) {
        ResponseCookie.ResponseCookieBuilder builder = ResponseCookie.from(name, value)
                .path("/")
                .httpOnly(true)
                .secure(oauth2Properties.cookie().secure())
                .maxAge(maxAge)
                .sameSite("Lax");

        String domain = oauth2Properties.getCookieDomain();
        if (domain != null && !domain.isBlank()) {
            builder.domain(domain);
        }

        return builder.build();
    }

    // ==================== Serialization ====================

    private String serialize(OAuth2AuthorizationRequest request) {
        try {
            OAuth2AuthorizationRequestDto dto = OAuth2AuthorizationRequestDto.from(request);
            String json = objectMapper.writeValueAsString(dto);
            return Base64.getUrlEncoder().encodeToString(
                    json.getBytes(StandardCharsets.UTF_8)
            );
        } catch (JsonProcessingException e) {
            log.error("Failed to serialize OAuth2AuthorizationRequest", e);
            return null;
        }
    }

    private OAuth2AuthorizationRequest deserialize(String serialized) {
        try {
            String json = new String(
                    Base64.getUrlDecoder().decode(serialized),
                    StandardCharsets.UTF_8
            );
            OAuth2AuthorizationRequestDto dto = objectMapper.readValue(
                    json, OAuth2AuthorizationRequestDto.class
            );
            return dto.toOAuth2AuthorizationRequest();
        } catch (Exception e) {
            log.error("Failed to deserialize OAuth2AuthorizationRequest", e);
            return null;
        }
    }
}

2. OAuth2AuthorizationRequestDto: 직렬화용 DTO

OAuth2AuthorizationRequest는 직렬화가 어렵습니다. 직렬화 가능한 DTO로 변환합니다.

package com.example.oauth2.client.core.dto;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Getter;
import lombok.NoArgsConstructor;
import org.springframework.security.oauth2.core.endpoint.OAuth2AuthorizationRequest;
import java.util.Map;
import java.util.Set;

@Getter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class OAuth2AuthorizationRequestDto {

    private String authorizationUri;
    private String clientId;
    private String redirectUri;
    private String state;
    private Set<String> scopes;
    private Map<String, Object> additionalParameters;
    private String authorizationRequestUri;
    private Map<String, Object> attributes;
    private String responseType;

    /**
     * OAuth2AuthorizationRequest → DTO 변환
     */
    public static OAuth2AuthorizationRequestDto from(OAuth2AuthorizationRequest request) {
        return OAuth2AuthorizationRequestDto.builder()
                .authorizationUri(request.getAuthorizationUri())
                .clientId(request.getClientId())
                .redirectUri(request.getRedirectUri())
                .state(request.getState())
                .scopes(request.getScopes())
                .additionalParameters(request.getAdditionalParameters())
                .authorizationRequestUri(request.getAuthorizationRequestUri())
                .attributes(request.getAttributes())
                .responseType(request.getResponseType().getValue())
                .build();
    }

    /**
     * DTO → OAuth2AuthorizationRequest 변환
     */
    public OAuth2AuthorizationRequest toOAuth2AuthorizationRequest() {
        return OAuth2AuthorizationRequest.authorizationCode()
                .authorizationUri(this.authorizationUri)
                .clientId(this.clientId)
                .redirectUri(this.redirectUri)
                .state(this.state)
                .scopes(this.scopes)
                .additionalParameters(this.additionalParameters)
                .authorizationRequestUri(this.authorizationRequestUri)
                .attributes(attrs -> attrs.putAll(this.attributes))
                .build();
    }
}

3. 보안 쿠키 설정

쿠키 보안 옵션

ResponseCookie cookie = ResponseCookie.from(name, value)
        .path("/")              // 모든 경로에서 접근 가능
        .httpOnly(true)         // JavaScript 접근 차단 (XSS 방어)
        .secure(true)           // HTTPS에서만 전송
        .maxAge(180)            // 3분 (인증 과정 동안만 유효)
        .sameSite("Lax")        // Cross-Site 요청 제한 (CSRF 방어)
        .build();

각 옵션 설명

SameSite 옵션 비교

OAuth2 인증에서는 Lax가 최적입니다:

• 카카오에서 리다이렉트로 돌아올 때 쿠키가 전송됨 (GET 요청)
• CSRF 공격(POST Form 제출)은 차단됨

4. Properties 설정

Oauth2Properties 클래스

package com.example.global.properties;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "app.security.oauth2")
public record Oauth2Properties(
        String authorizedRedirectUri,  // 인증 성공 후 프론트엔드 콜백 URL
        CookieProperties cookie
) {

    public record CookieProperties(
            String authName,          // AuthorizationRequest 쿠키 이름
            String redirectUriName,   // redirect_uri 쿠키 이름
            int maxAgeSeconds,        // 쿠키 만료 시간 (초)
            boolean secure            // HTTPS 전용 여부
    ) {

    }

    /**
     * 쿠키 도메인 추출 (예: "example.com")
     */
    public String getCookieDomain() {
        try {
            java.net.URI uri = new java.net.URI(authorizedRedirectUri);
            String host = uri.getHost();

            // localhost는 도메인 설정 불필요
            if (host.equals("localhost") || host.equals("127.0.0.1")) {
                return null;
            }

            // 서브도메인 공유를 위해 메인 도메인 반환
            // api.example.com → example.com
            String[] parts = host.split("\\\\.");
            if (parts.length >= 2) {
                return parts[parts.length - 2] + "." + parts[parts.length - 1];
            }
            return host;
        } catch (Exception e) {
            return null;
        }
    }
}

application.yml 설정

app:
  security:
    oauth2:
      # 인증 성공 후 프론트엔드 콜백 URL
      authorized-redirect-uri: https://example.com/oauth2/callback

      cookie:
        auth-name: oauth2_auth_request         # AuthorizationRequest 쿠키 이름
        redirect-uri-name: oauth2_redirect_uri # redirect_uri 쿠키 이름
        max-age-seconds: 180                   # 3분
        secure: true                           # HTTPS 환경 (Prod)

# ==========================================
# 개발 환경 (Local)
# ==========================================
---
spring:
  config:
    activate:
      on-profile: local

app:
  security:
    oauth2:
      authorized-redirect-uri: http://localhost:3000/oauth2/callback
      cookie:
        secure: false  # 로컬 HTTP 환경

5. 프론트엔드 연동

로그인 요청

프론트엔드에서 소셜 로그인 버튼 클릭 시:

// React 예시
const handleKakaoLogin = () => {
    // 현재 페이지 URL을 redirect_uri로 전달
    const currentPath = window.location.pathname;
    const loginUrl = `${API_BASE_URL}/oauth2/authorization/kakao?redirect_uri=${encodeURIComponent(currentPath)}`;

    window.location.href = loginUrl;
};

콜백 처리

인증 성공 후 프론트엔드 콜백 페이지:

// /oauth2/callback 페이지
import {useEffect} from 'react';
import {useSearchParams, useNavigate} from 'react-router-dom';

function OAuth2Callback() {
    const [searchParams] = useSearchParams();
    const navigate = useNavigate();

    useEffect(() => {
        const error = searchParams.get('error');
        const redirectUri = searchParams.get('redirect_uri');

        if (error) {
            // 에러 처리
            const message = searchParams.get('message');
            alert(`로그인 실패: ${message}`);
            navigate('/login');
            return;
        }

        // 성공 시 원래 페이지로 이동
        // (Refresh Token은 HttpOnly 쿠키로 자동 설정됨)
        navigate(redirectUri || '/');
    }, [searchParams, navigate]);

    return <div>로그인 처리 중...</div>;
}

인증 플로우 다이어그램

마치며

쿠키 기반 인증 상태 관리를 구현하여 다음을 달성했습니다:

1. Stateless 아키텍처: 서버 세션 없이 상태 관리
2. CSRF 방어: SameSite=Lax + state 파라미터 검증
3. XSS 방어: HttpOnly 쿠키로 JavaScript 접근 차단
4. SPA 호환: 프론트엔드 redirect_uri 유지

보안 체크리스트

카카오, 네이버, 구글은 각각 다른 JSON 응답 구조를 가집니다. Factory Pattern을 활용하여 Provider별 응답을 통합된 DTO로 변환하는 시스템을 구축합니다.

들어가며

이전 글에서 Strategy Pattern으로 Provider별 로직을 캡슐화했습니다. 이번에는 각 Provider의 서로 다른 응답 구조를 어떻게 통합하는지 다룹니다.

문제: Provider마다 다른 응답 구조

// 카카오 응답 - 중첩 구조
{
  "id": 123456789,
  "kakao_account": {
    "email": "user@kakao.com",
    "profile": {
      "nickname": "홍길동",
      "profile_image_url": "https://..."
    }
  }
}

// 네이버 응답 - response 래퍼
{
  "resultcode": "00",
  "message": "success",
  "response": {
    "id": "abcd1234",
    "email": "user@naver.com",
    "nickname": "홍길동"
  }
}

// 구글 응답 - 플랫 구조
{
  "sub": "1234567890",
  "email": "user@gmail.com",
  "name": "홍길동",
  "picture": "https://..."
}

이 세 가지를 하나의 통합된 형태로 변환해야 합니다:

OAuth2UserInfo {
    providerId: "123456789"
    provider: KAKAO
    email: "user@kakao.com"
    nickname: "홍길동"
    profileImageUrl: "https://..."
}

1. OAuth2UserInfo: 통합 DTO 설계

모든 Provider의 사용자 정보를 담는 통합 DTO를 정의합니다.

package com.example.oauth2.client.core.dto;

import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import lombok.Builder;
import org.springframework.util.StringUtils;
import java.util.Map;
import java.util.regex.Pattern;

@Builder
public record OAuth2UserInfo(
    String providerId,           // Provider 내 고유 ID
    OAuth2ProviderType provider, // Provider 타입
    String email,
    String name,                 // 실명 (비즈앱 전용)
    String nickname,
    String phoneNumber,
    String profileImageUrl,
    Map<String, Object> attributes  // 원본 응답 전체
) {
    // 한국 국가코드 패턴
    private static final Pattern KOREA_CODE = Pattern.compile("^82");
    private static final Pattern NON_DIGIT = Pattern.compile("\\\\D");

    /**
     * 표시 이름을 반환합니다.
     * 우선순위: nickname → name → email 로컬파트 → username
     */
    public String getDisplayName() {
        if (StringUtils.hasText(nickname)) {
            return nickname;
        }
        if (StringUtils.hasText(name)) {
            return name;
        }
        if (StringUtils.hasText(email) && email.contains("@")) {
            return email.substring(0, email.indexOf('@'));
        }
        return getUsername();
    }

    /**
     * 시스템 내 고유 username을 반환합니다.
     * 형식: "PROVIDER_providerId" (예: "KAKAO_123456")
     */
    public String getUsername() {
        return provider.name() + "_" + providerId;
    }

    /**
     * 전화번호를 정규화합니다.
     * - 숫자만 추출
     * - 한국 국가코드(82) → 0으로 변환
     * 예: "+82 10-1234-5678" → "01012345678"
     */
    public String getNormalizedPhoneNumber() {
        if (!StringUtils.hasText(phoneNumber)) {
            return null;
        }

        String digitsOnly = NON_DIGIT.matcher(phoneNumber).replaceAll("");
        if (digitsOnly.isEmpty()) {
            return null;
        }

        return KOREA_CODE.matcher(digitsOnly).replaceFirst("0");
    }
}

설계 포인트

2. OAuth2UserInfoExtractor 인터페이스

Provider별 추출 로직을 추상화하는 인터페이스입니다.

package com.example.oauth2.client.core.userinfo;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.oauth2.core.user.OAuth2User;

public interface OAuth2UserInfoExtractor {

    /**
     * 이 Extractor가 담당하는 Provider 타입
     */
    OAuth2ProviderType getProviderType();

    /**
     * OIDC 모드: ID Token + UserInfo에서 추출
     */
    OAuth2UserInfo extract(OidcUser oidcUser);

    /**
     * OAuth2 모드: UserInfo Endpoint 응답에서만 추출
     */
    OAuth2UserInfo extract(OAuth2User oauth2User);

    /**
     * 지원 여부 확인
     */
    default boolean supports(String registrationId) {
        return getProviderType().getRegistrationId().equals(registrationId);
    }
}

OIDC vs OAuth2 모드

• OIDC 모드: ID Token claims와 UserInfo를 조합 (더 신뢰성 높음)
• OAuth2 모드: UserInfo Endpoint 응답만 사용 (네이버 등 OIDC 미지원 Provider용)

3. OAuth2Attributes: 중첩 Map 탐색 유틸리티

OAuth2 응답은 대부분 중첩된 Map 구조입니다. 이를 쉽게 탐색하는 유틸리티를 만듭니다.

package com.example.oauth2.client.core.userinfo;

import lombok.extern.slf4j.Slf4j;
import org.springframework.util.StringUtils;
import java.util.Collections;
import java.util.Map;
import java.util.function.Function;

@Slf4j
public record OAuth2Attributes(Map<String, Object> attributes) {

    public OAuth2Attributes(Map<String, Object> attributes) {
        this.attributes = attributes != null ? attributes : Collections.emptyMap();
    }

    // ==================== Factory Methods ====================

    public static OAuth2Attributes of(Map<String, Object> attributes) {
        return new OAuth2Attributes(attributes);
    }

    public static OAuth2Attributes empty() {
        return new OAuth2Attributes(Collections.emptyMap());
    }

    // ==================== Navigation ====================

    /**
     * 중첩된 Map을 OAuth2Attributes로 래핑하여 반환
     * 존재하지 않으면 빈 OAuth2Attributes 반환
     *
     * 예: getChild("kakao_account").getChild("profile")
     */
    public OAuth2Attributes getChild(String key) {
        return new OAuth2Attributes(getMapInternal(key));
    }

    /**
     * 점(.) 표기법으로 깊은 탐색
     *
     * 예: getPath("kakao_account.profile.nickname")
     */
    public OAuth2Attributes getPath(String path) {
        if (!StringUtils.hasText(path)) {
            return this;
        }

        OAuth2Attributes current = this;
        for (String key : path.split("\\\\.")) {
            current = current.getChild(key);
            if (current.isEmpty()) {
                return OAuth2Attributes.empty();
            }
        }
        return current;
    }

    // ==================== Primitive Getters ====================

    public String getString(String key) {
        Object value = attributes.get(key);
        return value != null ? String.valueOf(value) : null;
    }

    public Long getLong(String key) {
        Object value = attributes.get(key);
        return switch (value) {
            case null -> null;
            case Long l -> l;
            case Number n -> n.longValue();
            default -> parseLongSafely(String.valueOf(value));
        };
    }

    public Boolean getBoolean(String key) {
        Object value = attributes.get(key);
        return switch (value) {
            case null -> null;
            case Boolean b -> b;
            default -> Boolean.parseBoolean(String.valueOf(value));
        };
    }

    // ==================== Custom Mapping ====================

    /**
     * 값을 커스텀 함수로 변환
     */
    public <T> T map(String key, Function<String, T> mapper) {
        String value = getString(key);
        if (!StringUtils.hasText(value)) {
            return null;
        }

        try {
            return mapper.apply(value);
        } catch (Exception e) {
            log.debug("Failed to map value '{}' for key '{}'", value, key);
            return null;
        }
    }

    // ==================== Utility ====================

    public boolean has(String key) {
        return attributes.containsKey(key) && attributes.get(key) != null;
    }

    public boolean isEmpty() {
        return attributes.isEmpty();
    }

    // ==================== Internal ====================

    @SuppressWarnings("unchecked")
    private Map<String, Object> getMapInternal(String key) {
        Object value = attributes.get(key);
        if (value instanceof Map) {
            return (Map<String, Object>) value;
        }
        return Collections.emptyMap();
    }

    private Long parseLongSafely(String value) {
        try {
            return Long.parseLong(value);
        } catch (NumberFormatException e) {
            log.debug("Failed to parse Long: '{}'", value);
            return null;
        }
    }
}

사용 예시

// Before: 전통적인 방식 (NullPointerException 위험!)
Map<String, Object> account = (Map<String, Object>) attributes.get("kakao_account");
Map<String, Object> profile = (Map<String, Object>) account.get("profile");
String nickname = (String) profile.get("nickname");

// After: OAuth2Attributes 사용 (안전하고 깔끔!)
OAuth2Attributes attrs = OAuth2Attributes.of(attributes);
String nickname = attrs.getChild("kakao_account")
                       .getChild("profile")
                       .getString("nickname");

// 또는 점 표기법으로 한 줄에
String nickname = attrs.getPath("kakao_account.profile.nickname")
                       .getString("nickname");

4. Factory Pattern으로 Extractor 관리

Spring DI를 활용하여 모든 Extractor를 자동으로 수집하고 관리합니다.

package com.example.oauth2.client.core.userinfo;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Component;
import java.util.List;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;

@Component
public class OAuth2UserInfoExtractorFactory {

    private final Map<OAuth2ProviderType, OAuth2UserInfoExtractor> extractorMap;

    /**
     * 생성자에서 모든 Extractor를 수집하여 Map으로 변환
     * Spring이 OAuth2UserInfoExtractor 구현체를 모두 주입
     */
    public OAuth2UserInfoExtractorFactory(List<OAuth2UserInfoExtractor> extractors) {
        this.extractorMap = extractors.stream()
                .collect(Collectors.toMap(
                        OAuth2UserInfoExtractor::getProviderType,
                        Function.identity()
                ));
    }

    /**
     * Provider 타입으로 Extractor 조회
     */
    public OAuth2UserInfoExtractor getExtractor(OAuth2ProviderType providerType) {
        OAuth2UserInfoExtractor extractor = extractorMap.get(providerType);
        if (extractor == null) {
            throw new IllegalArgumentException(
                "No extractor found for: " + providerType
            );
        }
        return extractor;
    }

    /**
     * registrationId로 Extractor 조회
     */
    public OAuth2UserInfoExtractor getExtractor(String registrationId) {
        return getExtractor(OAuth2ProviderType.from(registrationId));
    }

    /**
     * OAuth2User에서 UserInfo 추출 (OIDC/OAuth2 자동 감지)
     */
    public OAuth2UserInfo extract(String registrationId, OAuth2User oauth2User) {
        OAuth2UserInfoExtractor extractor = getExtractor(registrationId);

        // OIDC User인 경우 OIDC 모드로 추출
        if (oauth2User instanceof OidcUser oidcUser) {
            return extractor.extract(oidcUser);
        }

        // 일반 OAuth2 User인 경우
        return extractor.extract(oauth2User);
    }
}

Factory Pattern의 장점

1. 자동 수집: @Component 붙은 Extractor가 자동으로 등록됨
2. 느슨한 결합: Factory는 구체 클래스를 모름
3. 확장 용이: 새 Extractor 추가해도 Factory 수정 불필요

5. Provider별 Extractor 구현

KakaoUserInfoExtractor

package com.example.oauth2.client.kakao;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import com.example.oauth2.client.core.userinfo.OAuth2Attributes;
import com.example.oauth2.client.core.userinfo.OAuth2UserInfoExtractor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.security.oauth2.core.oidc.OidcIdToken;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Component;
import java.util.Map;

import static org.apache.commons.lang3.ObjectUtils.firstNonNull;

@Component
@Slf4j
public class KakaoUserInfoExtractor implements OAuth2UserInfoExtractor {

    @Override
    public OAuth2ProviderType getProviderType() {
        return OAuth2ProviderType.KAKAO;
    }

    /**
     * OIDC 모드: ID Token claims + attributes 조합
     */
    @Override
    public OAuth2UserInfo extract(OidcUser oidcUser) {
        OidcIdToken idToken = oidcUser.getIdToken();
        Map<String, Object> attributes = oidcUser.getAttributes();
        KakaoUserDetail detail = parseKakaoResponse(attributes);

        return OAuth2UserInfo.builder()
                // ID Token의 sub가 더 신뢰성 있음
                .providerId(firstNonNull(idToken.getSubject(), detail.getProviderId()))
                .provider(OAuth2ProviderType.KAKAO)
                // ID Token claims 우선, 없으면 attributes에서
                .email(firstNonNull(idToken.getEmail(), detail.email()))
                .name(detail.name())
                .nickname(firstNonNull(idToken.getNickName(), detail.nickname()))
                .phoneNumber(detail.phoneNumber())
                .profileImageUrl(firstNonNull(idToken.getPicture(), detail.profileImageUrl()))
                .attributes(attributes)
                .build();
    }

    /**
     * OAuth2 모드: UserInfo Endpoint 응답만 사용
     */
    @Override
    public OAuth2UserInfo extract(OAuth2User oauth2User) {
        Map<String, Object> attributes = oauth2User.getAttributes();
        KakaoUserDetail detail = parseKakaoResponse(attributes);

        return OAuth2UserInfo.builder()
                .providerId(detail.getProviderId())
                .provider(OAuth2ProviderType.KAKAO)
                .email(detail.email())
                .name(detail.name())
                .nickname(detail.nickname())
                .phoneNumber(detail.phoneNumber())
                .profileImageUrl(detail.profileImageUrl())
                .attributes(attributes)
                .build();
    }

    /**
     * 카카오 응답 파싱
     */
    private KakaoUserDetail parseKakaoResponse(Map<String, Object> attributes) {
        OAuth2Attributes root = OAuth2Attributes.of(attributes);
        OAuth2Attributes account = root.getChild("kakao_account");
        OAuth2Attributes profile = account.getChild("profile");

        return KakaoUserDetail.builder()
                .id(root.getLong("id"))
                .nickname(profile.getString("nickname"))
                .profileImageUrl(profile.getString("profile_image_url"))
                .name(account.getString("name"))
                .email(account.getString("email"))
                .phoneNumber(account.getString("phone_number"))
                .build();
    }
}

KakaoUserDetail (응답 DTO)

package com.example.oauth2.client.kakao;

import lombok.Builder;

@Builder
public record KakaoUserDetail(
    Long id,
    String nickname,
    String profileImageUrl,
    String name,        // 실명 (비즈앱 전용)
    String email,
    String phoneNumber  // 비즈앱 전용
) {
    public String getProviderId() {
        return id != null ? String.valueOf(id) : null;
    }
}

NaverUserInfoExtractor

package com.example.oauth2.client.naver;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import com.example.oauth2.client.core.userinfo.OAuth2Attributes;
import com.example.oauth2.client.core.userinfo.OAuth2UserInfoExtractor;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Component;
import java.util.Map;

@Component
public class NaverUserInfoExtractor implements OAuth2UserInfoExtractor {

    @Override
    public OAuth2ProviderType getProviderType() {
        return OAuth2ProviderType.NAVER;
    }

    @Override
    public OAuth2UserInfo extract(OidcUser oidcUser) {
        // 네이버는 OIDC 미지원, OAuth2 모드로 폴백
        return extract((OAuth2User) oidcUser);
    }

    @Override
    public OAuth2UserInfo extract(OAuth2User oauth2User) {
        Map<String, Object> attributes = oauth2User.getAttributes();

        // 네이버 응답은 "response" 객체 안에 실제 데이터가 있음
        OAuth2Attributes response = OAuth2Attributes.of(attributes)
                .getChild("response");

        return OAuth2UserInfo.builder()
                .providerId(response.getString("id"))
                .provider(OAuth2ProviderType.NAVER)
                .email(response.getString("email"))
                .name(response.getString("name"))
                .nickname(response.getString("nickname"))
                .phoneNumber(response.getString("mobile"))
                .profileImageUrl(response.getString("profile_image"))
                .attributes(attributes)
                .build();
    }
}

GoogleUserInfoExtractor

package com.example.oauth2.client.google;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import com.example.oauth2.client.core.userinfo.OAuth2Attributes;
import com.example.oauth2.client.core.userinfo.OAuth2UserInfoExtractor;
import org.springframework.security.oauth2.core.oidc.OidcIdToken;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Component;
import java.util.Map;

@Component
public class GoogleUserInfoExtractor implements OAuth2UserInfoExtractor {

    @Override
    public OAuth2ProviderType getProviderType() {
        return OAuth2ProviderType.GOOGLE;
    }

    @Override
    public OAuth2UserInfo extract(OidcUser oidcUser) {
        OidcIdToken idToken = oidcUser.getIdToken();

        return OAuth2UserInfo.builder()
                .providerId(idToken.getSubject())
                .provider(OAuth2ProviderType.GOOGLE)
                .email(idToken.getEmail())
                .name(idToken.getFullName())
                .nickname(idToken.getGivenName())
                .profileImageUrl(idToken.getPicture())
                .attributes(oidcUser.getAttributes())
                .build();
    }

    @Override
    public OAuth2UserInfo extract(OAuth2User oauth2User) {
        OAuth2Attributes attrs = OAuth2Attributes.of(oauth2User.getAttributes());

        return OAuth2UserInfo.builder()
                .providerId(attrs.getString("sub"))
                .provider(OAuth2ProviderType.GOOGLE)
                .email(attrs.getString("email"))
                .name(attrs.getString("name"))
                .nickname(attrs.getString("given_name"))
                .profileImageUrl(attrs.getString("picture"))
                .attributes(oauth2User.getAttributes())
                .build();
    }
}

마치며

Factory Pattern을 적용하여 다음을 달성했습니다:

1. 통합 DTO: 모든 Provider의 응답을 OAuth2UserInfo로 통합
2. 안전한 파싱: OAuth2Attributes로 NullPointerException 방지
3. 자동 확장: Spring DI로 새 Extractor 자동 등록
4. OIDC/OAuth2 자동 감지: Factory가 적절한 추출 모드 선택

아키텍처 요약

카카오, 네이버, 구글 소셜 로그인을 하나의 아키텍처로 통합합니다. Strategy Pattern을 활용하여 새로운 Provider를 추가할 때 기존 코드 수정 없이 확장할 수 있는 구조를 설계합니다.

들어가며

이전 글에서 카카오 OAuth2 로그인의 기초를 다뤘습니다. 하지만 실제 서비스에서는 네이버, 구글, 애플 등 여러 소셜 로그인을 지원해야 합니다.

문제는 각 Provider마다 응답 구조가 다르다는 것입니다:

// 카카오 응답
{
  "id":123456789,
  "kakao_account":{
      "email":"user@kakao.com",
      "profile":{"nickname":"홍길동"}
  }
}

// 네이버 응답
{
    "response":{
        "id":"abcd1234",
        "email":"user@naver.com",
        "nickname":"홍길동"
    }
}

// 구글 응답
{
    "sub":"1234567890",
    "email":"user@gmail.com",
    "name":"홍길동"
}

이런 상황에서 if-else 분기문으로 처리하면 어떻게 될까요?

// 안티패턴: if-else 지옥
if(provider.equals("kakao")){
// 카카오 파싱 로직
}else if(provider.equals("naver")){
// 네이버 파싱 로직
}else if(provider.equals("google")){
// 구글 파싱 로직
}else if(provider.equals("apple")){
// ... 끝없이 증가
}

새 Provider가 추가될 때마다 기존 코드를 수정해야 하고, 한 파일이 비대해집니다. OCP(Open-Closed Principle) 를 위반하는 대표적인 사례입니다.

이 글에서는 Strategy Pattern을 활용하여 이 문제를 해결합니다.

1. 왜 Strategy Pattern인가?

Strategy Pattern이란?

Strategy Pattern은 행위(알고리즘)를 캡슐화하여 런타임에 교체할 수 있게 하는 디자인 패턴입니다.

적용 시 장점

2. OAuth2ProviderType 열거형 설계

먼저 지원하는 Provider를 열거형으로 정의합니다.

package com.example.oauth2.client.core.provider;

import lombok.Getter;
import lombok.RequiredArgsConstructor;
import java.util.Arrays;

@Getter
@RequiredArgsConstructor
public enum OAuth2ProviderType {
    KAKAO("kakao", true, "<https://kauth.kakao.com>"),
    NAVER("naver", false, null),
    GOOGLE("google", true, "<https://accounts.google.com>");

    private final String registrationId;  // application.yml의 registration 이름
    private final boolean oidcSupported;  // OIDC 지원 여부
    private final String issuerUri;       // OIDC issuer URI

    /**
     * registrationId로 Provider 타입을 찾습니다.
     */
    public static OAuth2ProviderType from(String registrationId) {
        return Arrays.stream(values())
                .filter(type -> type.registrationId.equals(registrationId))
                .findFirst()
                .orElseThrow(() -> new IllegalArgumentException(
                        "Unsupported provider: " + registrationId
                ));
    }
}

설계 포인트

1. oidcSupported: OIDC 지원 여부를 명시합니다. 카카오/구글은 OIDC를 지원하지만, 네이버는 OAuth2만 지원한다고 가정합니다.
2. issuerUri: OIDC ID Token의 issuer 검증에 사용합니다.
3. from() 메서드: Spring Security의 registrationId로 열거형을 찾습니다.

3. OAuth2ProviderStrategy 인터페이스

Provider별 로직을 추상화하는 Strategy 인터페이스를 정의합니다.

package com.example.oauth2.client.core.provider;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import org.springframework.security.oauth2.core.oidc.OidcIdToken;
import org.springframework.security.oauth2.core.user.OAuth2User;
import java.util.Set;

public interface OAuth2ProviderStrategy {

    /**
     * 이 Strategy가 담당하는 Provider 타입
     */
    OAuth2ProviderType getProviderType();

    /**
     * OAuth2User에서 사용자 정보를 추출합니다.
     * @param oauth2User OAuth2/OIDC 인증된 사용자
     * @param idToken OIDC ID Token (OIDC 모드일 때만 non-null)
     * @return 정규화된 사용자 정보
     */
    OAuth2UserInfo extractUserInfo(OAuth2User oauth2User, OidcIdToken idToken);

    /**
     * ID Token 검증 (OIDC Provider만 구현)
     * 기본 구현은 아무것도 하지 않음
     */
    default void validateToken(OidcIdToken idToken) {
        // 기본값: 검증 없음 (OAuth2 전용 Provider용)
    }

    /**
     * 이 Provider에 필요한 scope 목록
     */
    Set<String> getRequiredScopes();
}

인터페이스 설계 원칙

1. 최소 인터페이스: 모든 Provider가 구현해야 할 최소한의 메서드만 정의
2. 기본 구현 제공: validateToken()은 OIDC Provider만 필요하므로 기본 구현 제공
3. 타입 안전성: OAuth2ProviderType으로 Provider를 식별

4. Provider별 구체 클래스 구현

KakaoOAuth2Strategy (OIDC 지원)

package com.example.oauth2.client.kakao;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.provider.OAuth2ProviderStrategy;
import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import lombok.RequiredArgsConstructor;
import org.springframework.boot.autoconfigure.security.oauth2.client.OAuth2ClientProperties;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.security.oauth2.core.OAuth2Error;
import org.springframework.security.oauth2.core.oidc.OidcIdToken;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Component;
import java.util.Set;

@Component
@RequiredArgsConstructor
public class KakaoOAuth2Strategy implements OAuth2ProviderStrategy {

    private final KakaoUserInfoExtractor userInfoExtractor;
    private final OAuth2ClientProperties oauth2Properties;

    @Override
    public OAuth2ProviderType getProviderType() {
        return OAuth2ProviderType.KAKAO;
    }

    @Override
    public OAuth2UserInfo extractUserInfo(OAuth2User oauth2User, OidcIdToken idToken) {
        // OIDC 모드 (ID Token이 있는 경우)
        if (idToken != null && oauth2User instanceof OidcUser oidcUser) {
            return userInfoExtractor.extract(oidcUser);
        }
        // OAuth2 모드 (fallback)
        return userInfoExtractor.extract(oauth2User);
    }

    @Override
    public void validateToken(OidcIdToken idToken) {
        if (idToken == null) return;

        // 1. Issuer 검증
        String issuer = idToken.getIssuer().toString();
        String expectedIssuer = oauth2Properties.getProvider()
                .get("kakao").getIssuerUri();

        if (!issuer.equals(expectedIssuer)) {
            throw new OAuth2AuthenticationException(
                    new OAuth2Error("invalid_token",
                            "Invalid Kakao issuer: " + issuer, null)
            );
        }

        // 2. Audience 검증 (client_id와 일치해야 함)
        String clientId = oauth2Properties.getRegistration()
                .get("kakao").getClientId();

        if (!idToken.getAudience().contains(clientId)) {
            throw new OAuth2AuthenticationException(
                    new OAuth2Error("invalid_token",
                            "Invalid Kakao audience", null)
            );
        }
    }

    @Override
    public Set<String> getRequiredScopes() {
        return Set.of(
                "openid",           // OIDC 필수
                "profile_nickname",
                "profile_image",
                "account_email",
                "phone_number"
        );
    }
}

NaverOAuth2Strategy (OAuth2만 지원)

package com.example.oauth2.client.naver;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.provider.OAuth2ProviderStrategy;
import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import lombok.RequiredArgsConstructor;
import org.springframework.security.oauth2.core.oidc.OidcIdToken;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Component;
import java.util.Set;

@Component
@RequiredArgsConstructor
public class NaverOAuth2Strategy implements OAuth2ProviderStrategy {

    private final NaverUserInfoExtractor userInfoExtractor;

    @Override
    public OAuth2ProviderType getProviderType() {
        return OAuth2ProviderType.NAVER;
    }

    @Override
    public OAuth2UserInfo extractUserInfo(OAuth2User oauth2User, OidcIdToken idToken) {
        // 네이버는 OIDC 미지원, OAuth2 모드만 사용
        return userInfoExtractor.extract(oauth2User);
    }

    // validateToken()은 기본 구현 사용 (아무것도 안 함)

    @Override
    public Set<String> getRequiredScopes() {
        return Set.of("name", "email", "profile_image");
    }
}

GoogleOAuth2Strategy (OIDC 지원)

package com.example.oauth2.client.google;

import com.example.oauth2.client.core.dto.OAuth2UserInfo;
import com.example.oauth2.client.core.provider.OAuth2ProviderStrategy;
import com.example.oauth2.client.core.provider.OAuth2ProviderType;
import lombok.RequiredArgsConstructor;
import org.springframework.security.oauth2.core.oidc.OidcIdToken;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Component;
import java.util.Set;

@Component
@RequiredArgsConstructor
public class GoogleOAuth2Strategy implements OAuth2ProviderStrategy {

    private final GoogleUserInfoExtractor userInfoExtractor;

    @Override
    public OAuth2ProviderType getProviderType() {
        return OAuth2ProviderType.GOOGLE;
    }

    @Override
    public OAuth2UserInfo extractUserInfo(OAuth2User oauth2User, OidcIdToken idToken) {
        if (idToken != null && oauth2User instanceof OidcUser oidcUser) {
            return userInfoExtractor.extract(oidcUser);
        }
        return userInfoExtractor.extract(oauth2User);
    }

    @Override
    public Set<String> getRequiredScopes() {
        return Set.of("openid", "profile", "email");
    }
}

5. 새로운 Provider 추가하기 (확장 예제)

Apple 로그인을 추가한다고 가정해봅시다. 기존 코드를 전혀 수정하지 않고 다음 단계만 진행하면 됩니다.

Step 1: OAuth2ProviderType에 열거값 추가

public enum OAuth2ProviderType {
    KAKAO("kakao", true, "<https://kauth.kakao.com>"),
    NAVER("naver", false, null),
    GOOGLE("google", true, "<https://accounts.google.com>"),
    APPLE("apple", true, "<https://appleid.apple.com>");  // 추가!

    // ... 나머지 동일
}

Step 2: AppleUserInfoExtractor 구현

@Component
public class AppleUserInfoExtractor implements OAuth2UserInfoExtractor {

    @Override
    public OAuth2ProviderType getProviderType() {
        return OAuth2ProviderType.APPLE;
    }

    @Override
    public OAuth2UserInfo extract(OidcUser oidcUser) {
        OidcIdToken idToken = oidcUser.getIdToken();

        return OAuth2UserInfo.builder()
                .providerId(idToken.getSubject())
                .provider(OAuth2ProviderType.APPLE)
                .email(idToken.getEmail())
                .name(oidcUser.getAttribute("name"))
                .attributes(oidcUser.getAttributes())
                .build();
    }

    @Override
    public OAuth2UserInfo extract(OAuth2User oauth2User) {
        // Apple은 OIDC 전용
        throw new UnsupportedOperationException("Apple requires OIDC");
    }
}

Step 3: AppleOAuth2Strategy 구현

@Component
@RequiredArgsConstructor
public class AppleOAuth2Strategy implements OAuth2ProviderStrategy {

    private final AppleUserInfoExtractor userInfoExtractor;

    @Override
    public OAuth2ProviderType getProviderType() {
        return OAuth2ProviderType.APPLE;
    }

    @Override
    public OAuth2UserInfo extractUserInfo(OAuth2User oauth2User, OidcIdToken idToken) {
        if (!(oauth2User instanceof OidcUser oidcUser)) {
            throw new OAuth2AuthenticationException(
                    new OAuth2Error("invalid_request", "Apple requires OIDC", null)
            );
        }
        return userInfoExtractor.extract(oidcUser);
    }

    @Override
    public Set<String> getRequiredScopes() {
        return Set.of("openid", "name", "email");
    }
}

Step 4: application.yml 설정

spring:
    security:
        oauth2:
            client:
                registration:
                    apple:
                        client-id: ${APPLE_CLIENT_ID}
                        client-secret: ${APPLE_CLIENT_SECRET}
                        redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
                        authorization-grant-type: authorization_code
                        scope: openid, name, email
                provider:
                    apple:
                        issuer-uri: <https://appleid.apple.com>
                        authorization-uri: <https://appleid.apple.com/auth/authorize>
                        token-uri: <https://appleid.apple.com/auth/token>

끝입니다! 기존의 OAuth2UserService, SuccessHandler 등은 전혀 수정할 필요가 없습니다.

마치며

Strategy Pattern을 적용하여 다음을 달성했습니다:

1. OCP 준수: 새 Provider 추가 시 기존 코드 수정 불필요
2. 단일 책임: 각 Strategy가 하나의 Provider만 담당
3. 테스트 용이: Provider별 독립적인 단위 테스트 가능
4. 확장성: Apple, Facebook 등 새 Provider를 쉽게 추가

핵심 정리

Spring Boot 3와 Spring Security 6를 활용한 카카오 OAuth2 소셜 로그인 구현 방법을 단계별로 알아봅니다. OAuth2와 OIDC의 차이점부터 실제 구현까지 다룹니다.

들어가며

최근 대부분의 서비스에서 소셜 로그인은 필수가 되었습니다. 사용자는 복잡한 회원가입 과정 없이 카카오, 네이버, 구글 계정으로 간편하게 로그인할 수 있고, 서비스 제공자는 인증 보안을 OAuth2 Provider에게 위임할 수 있습니다.

이 글에서는 Spring Boot 3와 Spring Security 6를 사용하여 카카오 소셜 로그인을 구현하는 방법을 다룹니다. 특히 OAuth2와 OIDC의 차이점, 그리고 왜 OIDC를 선택해야 하는지까지 설명합니다.

1. OAuth2와 OIDC의 차이점 이해하기

OAuth2란?

OAuth2(Open Authorization 2.0)는 권한 부여(Authorization) 프로토콜입니다. 사용자가 자신의 리소스(프로필, 이메일 등)에 대한 접근 권한을 제3자 애플리케이션에 부여할 수 있게 해줍니다.

[사용자] → [우리 서비스] → [카카오]
          "카카오 프로필 정보 좀 볼게요"
                    ↓
          [카카오가 Access Token 발급]
                    ↓
          [Access Token으로 UserInfo API 호출]

OIDC란?

OIDC(OpenID Connect)는 OAuth2 위에 구축된 인증(Authentication) 레이어입니다. OAuth2가 "이 사용자가 권한을 부여했다"만 알려준다면, OIDC는 "이 사용자가 누구인지"까지 표준화된 방식으로 알려줍니다.

[사용자] → [우리 서비스] → [카카오]
          "카카오로 로그인할게요"
                    ↓
          [카카오가 ID Token + Access Token 발급]
                    ↓
          [ID Token에서 바로 사용자 정보 추출]

핵심 차이점

왜 OIDC를 선택해야 할까?

1. API 호출 감소: ID Token에서 바로 사용자 정보를 가져올 수 있어 UserInfo API 호출이 줄어듭니다.
2. 보안 강화: ID Token은 JWT이므로 서명 검증으로 위변조를 방지할 수 있습니다.
3. 표준화된 Claims: sub, email, name 등 표준화된 필드로 Provider 간 일관성을 유지합니다.

Tip: 카카오는 OIDC를 지원하므로, 반드시 openid scope를 추가하여 ID Token을 받아야 합니다.

2. Spring Security OAuth2 Client 의존성 설정

build.gradle

dependencies {
    // Spring Boot 3.x
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'

    // OAuth2 Client (필수)
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'

    // OAuth2 Resource Server (JWT 검증용, 선택)
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'
}

의존성 설명

• spring-boot-starter-oauth2-client: OAuth2/OIDC 클라이언트 기능을 제공합니다. 카카오, 네이버, 구글 등의 Provider와 통신합니다.
• spring-boot-starter-oauth2-resource-server: JWT 토큰 검증 기능을 제공합니다. 자체 JWT를 발급하는 경우 필요합니다.

3. application.yml Provider 설정

카카오 OIDC 설정

spring:
    security:
        oauth2:
            client:
                registration:
                    kakao:
                        client-id: ${KAKAO_CLIENT_ID}  # 카카오 REST API 키
                        client-secret: ${KAKAO_CLIENT_SECRET}  # 보안 → Client Secret
                        redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
                        authorization-grant-type: authorization_code
                        client-authentication-method: client_secret_post
                        scope:
                            - openid          # OIDC 필수!
                            - profile_nickname
                            - profile_image
                            - account_email
                            - phone_number
                        client-name: Kakao
                provider:
                    kakao:
                        issuer-uri: https://kauth.kakao.com
                        authorization-uri: https://kauth.kakao.com/oauth/authorize
                        token-uri: https://kauth.kakao.com/oauth/token
                        user-info-uri: https://kapi.kakao.com/v2/user/me
                        user-name-attribute: id

설정 항목 설명

Scope 종류

scope:
    - openid            # OIDC ID Token 발급 (필수)
    - profile_nickname  # 닉네임
    - profile_image     # 프로필 이미지
    - account_email     # 이메일
    - phone_number      # 전화번호 (비즈앱 필요)
    - name              # 실명 (비즈앱 필요)

주의: phone_number와 name scope는 카카오 비즈니스 앱에서만 사용 가능합니다.

4. 카카오 개발자센터 앱 설정

Step 1: 애플리케이션 생성

1. 카카오 개발자센터에 접속합니다.
2. 내 애플리케이션 → 애플리케이션 추가하기를 클릭합니다.
3. 앱 이름과 사업자명을 입력합니다.

Step 2: REST API 키 확인

앱 설정 → 앱 키에서 REST API 키를 복사합니다. 이것이 client-id입니다.

Step 3: 보안 설정

보안 메뉴에서:

1. Client Secret 코드를 생성합니다.
2. 활성화 상태를 ON으로 변경합니다.

Step 4: 카카오 로그인 활성화

카카오 로그인 메뉴에서:

1. 활성화 설정을 ON으로 변경합니다.
2. OpenID Connect 활성화 설정을 ON으로 변경합니다. (OIDC 사용 시 필수!)

Step 5: Redirect URI 등록

카카오 로그인 → Redirect URI에 다음을 등록합니다:

http://localhost:8080/login/oauth2/code/kakao
https://your-domain.com/login/oauth2/code/kakao

Step 6: 동의항목 설정

동의항목 메뉴에서 필요한 정보의 동의 수준을 설정합니다:

5. OAuth2 인증 플로우 이해하기

Authorization Code Grant 플로우

Spring Security 기본 동작

Spring Security OAuth2 Client는 다음 엔드포인트를 자동으로 생성합니다:

실제 요청 URL 예시

# 1. 프론트엔드에서 로그인 버튼 클릭 시
GET /oauth2/authorization/kakao?redirect_uri=/mypage

# 2. 카카오 인증 후 콜백
GET /login/oauth2/code/kakao?code=xxx&state=yyy

# 3. 인증 성공 후 프론트엔드로 리다이렉트
GET /oauth2/callback?redirect_uri=/mypage

마치며

이번 글에서는 Spring Boot 3에서 카카오 OAuth2 소셜 로그인을 구현하기 위한 기초를 다뤘습니다. OAuth2와 OIDC의 차이점을 이해하고, 의존성 설정부터 카카오 개발자센터 설정까지 단계별로 진행했습니다.

핵심 정리

1. 가능하면 OIDC를 선택하세요openid 스코프를 추가하면 ID Token을 통해 사용자 정보를 안전하고 빠르게 얻을 수 있습니다 (JWT 서명 지원).

2. 보안 설정은 꼼꼼하게

   • Client Secret: 보안을 위해 활성화는 필수입니다. 특히 카카오는 client-secret-post (본문 포함), 그 외는 보통 client-secret-basic (헤더 포함) 방식을 사용하므로 설정 시 주의가 필요합니다.
   • Redirect URI: 오타 하나로도 인증이 실패할 수 있으니 정확하게 등록되었는지 확인하세요.

3. 권한(Scope)은 최소한으로 사용자가 거부감을 느끼지 않도록 꼭 필요한 권한만 요청하세요. 단, OIDC를 사용한다면 openid는 필수입니다.

참고 자료

• Spring Security OAuth2 공식 문서
• 카카오 로그인 개발 가이드
• OpenID Connect 스펙

오늘은 Master/Slave 구조에서 발생한 데이터 불일치 문제를 해결하기 위해, 사용자의 최근 쓰기 이력을 추적하여 동적으로 DB를 라우팅한 경험을 공유하려 합니다.

1. 문제 상황: "방금 쓴 글이 안 보여요"

저희 서비스는 읽기 성능을 높이기 위해 AbstractRoutingDataSource를 사용하여 트랜잭션의 @Transactional(readOnly = true) 여부에 따라 쿼리를 분기 처리하고 있습니다.

• 쓰기(Write): Master DB
• 읽기(Read): Slave DB

하지만 Master에 저장된 데이터가 Slave로 복제되기까지는 아주 짧지만 물리적인 시간(Lag)이 소요됩니다. 이로 인해 사용자가 데이터를 수정하고 즉시 목록 페이지로 리다이렉트되었을 때, Slave DB에는 아직 데이터가 도달하지 않아 수정 전의 내용이 노출되는 문제가 발생했습니다. 이는 사용자 경험(UX)에 치명적이었습니다.

2. 해결 전략: "방금 쓴 사람은 Master를 보게 하자"

이 문제를 해결하기 위해 "최근에 쓰기 작업을 수행한 사용자는 일정 시간 동안 강제로 Master DB에서 읽게 한다"는 전략을 세웠습니다. 이를 구현하기 위해 세 가지 범위(Scope)에서의 추적이 필요했습니다.

1. 현재 스레드(Thread): 한 트랜잭션 내에서 쓰기 후 바로 읽는 경우.
2. 현재 요청(Request): 하나의 HTTP 요청 안에서 쓰기 로직 수행 후, 다른 로직에서 읽기를 수행하는 경우.
3. 사용자 세션(Client): 쓰기 요청이 끝나고 다음 요청(새로고침 등)으로 넘어왔을 때.

저는 이 상태를 관리하기 위해 WriteTracker라는 컴포넌트를 설계했고, 다음과 같은 흐름을 만들었습니다.

• 쓰기 발생 시: 타임스탬프를 기록하고, 응답 쿠키(Cookie)에 마지막 쓰기 시간을 구워줍니다.
• 읽기 발생 시: 쿠키나 내부 상태를 확인해 현재 시간 - 마지막 쓰기 시간 < 설정된 Lag 시간이라면 강제로 Master DB를 바라보게 합니다.

3. 구현 상세

3.1. 핵심 로직: WriteTracker와 범위별 추적

가장 먼저 WriteTracker 클래스를 통해 쓰기 상태를 판단하는 로직을 중앙화했습니다.

// WriteTracker.java (요약)
public boolean shouldForceReadFromMaster() {
    // 1. ThreadLocal 체크 (현재 스레드 내 쓰기)
    if (isWithinLagWindow(WRITE_TIMESTAMP.get())) return true;

    // 2. Request Attribute 체크 (현재 요청 내 쓰기)
    if (request.getAttribute(txCommitFlag) != null) return true;

    // 3. Cookie 체크 (이전 요청에서의 쓰기 - 리다이렉트 등)
    Long lastWrite = extractFromCookie(request);
    return lastWrite != null && isWithinLagWindow(lastWrite);
}

여기서 중요한 점은 ThreadLocal, Request Attribute, Cookie를 순차적으로 확인하여, 서버 내부의 로직 흐름뿐만 아니라 클라이언트의 재요청 시나리오까지 커버했다는 점입니다.

3.2. AOP를 통한 투명한 추적 (WriteTrackingAspect)

개발자가 비즈니스 로직마다 tracker.markWrite()를 호출하는 것은 실수할 여지가 많습니다. 그래서 AOP를 사용하여 @Transactional 어노테이션이 붙은 메서드를 가로챘습니다.

// WriteTrackingAspect.java
@Around("@annotation(transactional)")
public Object trackWriteTransaction(ProceedingJoinPoint joinPoint, Transactional transactional) {
    if (transactional.readOnly()) {
        return joinPoint.proceed();
    }

    // 1. 쓰기 시작 마킹
    writeTracker.markWriteStarted();

    Object result = joinPoint.proceed();

    // 2. 트랜잭션 동기화 매니저에 핸들러 등록
    if (TransactionSynchronizationManager.isActualTransactionActive()) {
        TransactionSynchronizationManager.registerSynchronization(new WriteSyncHandler(...));
    }
    return result;
}

트랜잭션이 성공적으로 커밋된 시점(afterCommit)에 쿠키를 생성하여 클라이언트에게 내려줌으로써, 다음 요청부터는 이 쿠키를 들고 오게 만들었습니다.

3.3. 동적 라우팅 (TransactionRoutingDataSource)

마지막으로 AbstractRoutingDataSource를 상속받은 라우팅 소스에서 WriteTracker의 판단 결과를 반영했습니다.

// TransactionRoutingDataSource.java
@Override
protected Object determineCurrentLookupKey() {
    boolean isReadOnly = TransactionSynchronizationManager.isCurrentTransactionReadOnly();

    // 1. 쓰기 트랜잭션이면 무조건 Master
    if (!isReadOnly) return DataSourceType.MASTER;

    // 2. 읽기 트랜잭션이지만, 최근 쓰기 이력이 있다면 Master (Lag 방지)
    if (writeTracker.shouldForceReadFromMaster()) {
        log.debug("Routing to MASTER (avoiding replication lag)");
        return DataSourceType.MASTER;
    }

    return DataSourceType.SLAVE;
}

4. 트러블 슈팅 및 주의할 점

ThreadLocal 메모리 누수 방지

ThreadLocal을 사용할 때는 반드시 사용 후 정리가 필요합니다. 톰캣과 같은 스레드 풀 환경에서는 스레드가 재사용되기 때문입니다. 이를 위해 WriteTrackerCleanupFilter를 구현하여 요청이 끝나는 시점에 writeTracker.clear()를 호출하도록 HighestPrecedence로 설정했습니다.

LazyConnectionDataSourceProxy의 필수성

Spring의 트랜잭션 처리는 트랜잭션 시작 시점에 Connection을 확보하려 합니다. 라우팅 로직이 동작하기도 전에 이미 커넥션을 잡아버리는 문제를 방지하기 위해 LazyConnectionDataSourceProxy를 사용하여 실제 쿼리가 실행되는 시점까지 커넥션 획득을 지연시켰습니다.

P6Spy와 무조건적인 Master 라우팅 이슈

개발 과정에서 쿼리 파라미터를 편하게 확인하기 위해 P6Spy (v1.21.1) 라이브러리를 적용했습니다. 그런데 P6Spy 적용 직후, 분명히 Slave로 가야 할 읽기 전용 트랜잭션들까지 전부 Master DB로 쏠리는 현상이 발견되었습니다.

원인 분석

원인은 P6Spy의 작동 방식에 있었습니다. P6Spy(정확히는 관련 Spring Boot Starter)는 빈 후처리기(BeanPostProcessor)를 통해 애플리케이션의 DataSource 빈을 감싸서(Decorate) 프록시 객체를 만듭니다.

문제는 이 과정에서 P6Spy가 LazyConnectionDataSourceProxy나 RoutingDataSource보다 상위에서 감싸버리거나, 커넥션 객체를 미리 요청해버린다는 점입니다. 이로 인해 트랜잭션의 속성(readOnly)을 확인하고 분기 처리를 하기도 전에 이미 커넥션이 맺어져 버렸고, 결과적으로 기본값인 Master DB 커넥션만 계속 사용하게 된 것입니다.

해결 방법

이 문제를 해결하기 위해 P6Spy의 데코레이터 설정에서 라우팅 로직이 포함된 dataSource 빈은 감싸지 않도록 제외(exclude) 처리했습니다.

# application.yml

decorator:
  datasource:
    # RoutingDataSource는 이미 내부적으로 분기 처리를 하므로 P6Spy가 감싸지 않도록 설정
    ignore-routing-data-sources: true
    # 우리가 직접 만든(Lazy+Routing) 최종 dataSource 빈은 P6Spy 적용 제외
    exclude-beans: dataSource

위와 같이 exclude-beans: dataSource 설정을 추가하여 P6Spy가 최상단 dataSource 빈을 건드리지 않게 하자, LazyConnectionDataSourceProxy가 정상적으로 지연 로딩을 수행하면서 라우팅이 다시 올바르게 작동했습니다.

5. 마치며

이 구조를 도입한 후, 사용자가 "수정했습니다"라는 메시지를 보고 목록으로 돌아갔을 때 데이터가 반영되지 않는 문제는 완벽하게 사라졌습니다.

물론, "최근 글을 쓴 사용자"의 트래픽이 일시적으로 Master DB로 몰릴 수 있다는 트레이드오프가 있습니다. 하지만 데이터의 정합성이 UX에 미치는 영향이 훨씬 크다고 판단했으며, replicationLagMs 시간을 적절히 조절(예: 2초)하여 Master 부하를 최소화했습니다.

이번 개발을 통해 데이터베이스 아키텍처는 단순히 인프라 설정뿐만 아니라, 애플리케이션 레벨에서의 정교한 핸들링이 더해졌을 때 비로소 완성된다는 것을 배웠습니다.

Jooq는 Java 객체 지향 쿼리를 위한 프레임워크로, SQL을 타입 안전하게 작성할 수 있게 해준다. 이는 복잡한 SQL 쿼리를 간편하게 작성하고 관리할 수 있게 해준다.

AOP(Aspect-Oriented Programming) 이해

AOP는 프로그래밍에서 공통적으로 사용되는 기능(예: 로깅, 보안)을 모듈화하는 프로그래밍 패러다임이다. 이는 코드의 재사용성과 가독성을 향상시키는 데 도움을 준다.

발생한 문제

Spring Boot, Jooq, 그리고 전역 오류 로깅을 위한 AOP 설정 후 스프링 실행 속도가 1분 이상 걸리는 문제가 발생하였다. 문제 해결을 위한 디버깅 과정에서 AOP를 제거하고 실행하니 문제 없이 실행되었다. 이로 인해 AOP의 문제인가?? 라고 생각하게 되었다.

문제 진단

AOP 설정의 영향

AOP를 제거한 후 애플리케이션의 실행 속도가 정상으로 돌아온 것으로 보아, AOP 설정이 실행 속도 저하의 직접적인 원인임을 확인할 수 있었다.

실행 속도 저하의 원인 분석

AOP 추적

디버깅 과정에서 org.aspectj.weaver.internal.tools.PointcutExpressionImpl의 canMatchJoinPointsInType 메서드가 항상 true를 반환하고, 이로 인해 DefaultDSLContext의 모든 메서드에 포인트 컷을 적용할 수 있는지 확인하는 과정에서 성능 저하가 발생하는 것을 발견하였다.

Pointcut 표현식의 영향

execution 대신 within을 사용하였을 때 문제가 해결되었다는 사실로 미루어 볼 때, Pointcut 표현식의 선택이 성능에 큰 영향을 미칠 수 있음을 알 수 있었다.

해결 방안

execution 대신 within 사용하기

Pointcut 표현식에서 execution 대신 within을 사용함으로써, 포인트컷의 적용 범위를 좁히고, 이를 통해 DefaultDSLContext의 모든 메서드에 대한 포인트컷 적용을 피함으로써 성능 문제를 해결할 수 있었다.

execution

import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;

@Aspect
public class LoggingAspect {

    @Pointcut("execution(* com.example.service.*.*(..))")
    public void serviceLayerExecution() {
        // Pointcut body, usually empty
    }
}

within

import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;

@Aspect
public class LoggingAspect {

    @Pointcut("within(com.example.service..*)")
    public void serviceLayerWithin() {
        // Pointcut body, usually empty
    }
}

execution과 within의 차이점

execution과 within은 AspectJ에서 사용되는 Pointcut 지시자들로, 조인 포인트(join points)를 지정하는 방식에서 중요한 차이를 가집니다. 이 차이는 어떤 메서드나 객체에 대한 관점(Aspect)의 적용 범위를 결정하는 데 큰 영향을 미칩니다.

execution 지시자는 메소드 실행 시의 조인 포인트를 지정합니다. 이는 특정 메소드가 실행될 때 해당 메소드에 관점을 적용하고자 할 때 사용됩니다. execution 지시자는 메소드의 시그니처를 기반으로 매우 구체적인 타겟을 정할 수 있으며, 이를 통해 특정 메소드나 메소드 그룹에 대해 세밀한 관점 적용이 가능합니다. 예를 들어, execution(public String com.example.MyClass.myMethod(..))는 com.example.MyClass에 있는 myMethod 메소드의 실행 시점에만 관점을 적용하도록 지정합니다.

within 지시자는 특정 타입 내의 모든 조인 포인트를 지정하여 사용 범위가 execution보다 제한적일 수 있습니다. within은 특정 클래스나 패키지 내의 모든 메소드 실행을 포인트컷의 대상으로 지정합니다. 이는 해당 타입 내에서 실행되는 모든 메소드에 관점을 일괄적으로 적용하고자 할 때 유용합니다. 예를 들어, within(com.example.MyClass)는 com.example.MyClass 내의 모든 메소드에 대해 관점을 적용합니다.

이러한 차이는 포인트컷의 적용 범위와 성능 최적화에 중요한 영향을 미칩니다. execution 지시자는 매우 구체적인 적용 범위를 제공하지만, 많은 메소드에 대해 개별적으로 적용될 때 성능 저하의 원인이 될 수 있습니다. 반면, within 지시자는 특정 클래스나 패키지 내의 모든 조인 포인트에 대한 일괄적인 적용을 가능하게 하여, 성능 최적화에 도움을 줄 수 있습니다. 그러나 이는 적용 범위의 정밀도가 다소 떨어질 수 있다는 점을 의미하기도 합니다.

RESTful API는 두 컴퓨터 시스템이 인터넷을 통해 정보를 안전하게 교환하기 위해 사용하는 인터페이스입니다. 대부분의 비즈니스 애플리케이션은 다양한 태스크를 수행하기 위해 다른 내부 애플리케이션 및 서드 파티 애플리케이션과 통신해야 합니다. 예를 들어 월간 급여 명세서를 생성하려면 인보이스 발행을 자동화하고 내부의 근무 시간 기록 애플리케이션과 통신하기 위해 내부 계정 시스템이 데이터를 고객의 뱅킹 시스템과 공유해야 합니다. RESTful API는 안전하고 신뢰할 수 있으며 효율적인 소프트웨어 통신 표준을 따르므로 이러한 정보 교환을 지원합니다.

2. 샘플 설명

Spring Boot, Spring MVC, Spring Test, JUnit, Mockito 등 을 사용하여 User 에 관한 기본적인 REST API 와 단위테스트에 대한 방법을 설명합니다.

3. REST API

Git : https://github.com/Get-bot/springSamepleCode

1. Controller

UserApiController

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1/users")
public class UserApiController {

  private final UserService userService;

  @GetMapping("/{id}")
  public ResponseEntity<ApiResponse<UserDTO>> getUser(@NotNull @PathVariable("id") Long id) {
    return userService.get(id);
  }

  @GetMapping
  public ResponseEntity<ApiResponse<List<UserDTO>>> getUserList() {
    return userService.getList();
  }

  @PostMapping
  public ResponseEntity<ApiResponse<UserDTO>> registerUser(@RequestBody @Valid UserRegisterDTO userRegisterDTO) {
    return userService.register(userRegisterDTO);
  }

  @PutMapping("/{id}")
  public ResponseEntity<ApiResponse<UserDTO>> updateUser(@NotNull @PathVariable("id") Long id, @RequestBody @Valid UserUpdateDTO userUpdateDTO) {
    return userService.update(id, userUpdateDTO);
  }

  @DeleteMapping("/{id}")
  public ResponseEntity<ApiResponse<?>> deleteUser(@NotNull @PathVariable("id") Long id) {
    return userService.delete(id);
  }

}

• @RestController : @Controller에 @ResponseBody가 결합된 어노테이션 으로 컨트롤러 클래스 하위 메서드에 @ResponseBody 어노테이션을 붙이지 않아도 문자열과 JSON 등을 전송할 수 있습니다.

2. Entity and DTO

User

@Entity
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@Table(name = "users")
public class User {

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

  private String username;

  private String email;

  private String password;

  public static User setUser(Long id, String username, String email, String password) {
    User user = new User();
    user.id = id;
    user.username = username;
    user.email = email;
    user.password = password;
    return user;
  }

  public static User setRegisterUser(UserRegisterDTO userRegisterDTO) {
    User user = new User();
    user.username = userRegisterDTO.getUsername();
    user.email = userRegisterDTO.getEmail();
    user.password = userRegisterDTO.getPassword();
    return user;
  }

  public void updateWithUpdateDTO(UserUpdateDTO userUpdateDTO) {
    this.email = userUpdateDTO.getEmail();
    if (userUpdateDTO.getPassword() != null && !userUpdateDTO.getPassword().equals(this.password)) {
      this.password = userUpdateDTO.getPassword();
    }
  }
}

Entity 내부에 정적 메소드를 선언하여 캡슐화 하고 팩토리 메소드 역할을 하게하여 User 인스턴스를 생성하는 방법을 명확하게 하였습니다.

UserDTO

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserDTO {
  private Long id;
  private String username;
  private String email;

  public static UserDTO setUserDTO(User user) {
    return new UserDTO(user.getId(), user.getUsername(), user.getEmail());
  }

}

UserRegisterDTO

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserRegisterDTO {

  @NotEmpty
  private String username;

  @Email
  @NotEmpty
  private String email;

  @NotEmpty
  private String password;

  public static UserRegisterDTO setUserRegisterDTO(String username, String email, String password) {
    UserRegisterDTO user = new UserRegisterDTO();
    user.setUsername(username);
    user.setEmail(email);
    user.setPassword(password);
    return user;
  }
}

UserUpdateDTO

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserUpdateDTO {

  @NotEmpty
  private String email;
  private String password;
}

Responce 할 데이터에 Entity 그대로를 사용하지 않고 DTO 를 사용 하는것은 데이터를 캡슐화하여 필요한 정보만 클라이언트에 전송되도록 하는 API 설계에 필수적인 방법입니다. 이 접근 방식은 개인정보 보호와 보안을 유지하고, 내부 데이터 구조와 외부 표현을 분리하며, 맞춤형 API 응답을 허용합니다. 또한 DTO는 데이터 전송을 필수적인 데이터로 제한하여 대역폭 사용량을 줄이고 데이터 직렬화의 유연성을 제공합니다. 전반적으로 DTO는 보다 효율적이고 유연하며 강력한 API 설계에 필요한 요소입니다.

3. Repository

** JPA UserRepository **

@Repository
public interface UserRepository extends JpaRepository<User, Long> {

  boolean existsByUsername(String username);
  boolean existsByEmail(String email);

}

4. Serivce

* UserService Interface

public interface UserService {

  ResponseEntity<ApiResponse<UserDTO>> get(Long id);

  ResponseEntity<ApiResponse<UserDTO>> register(UserRegisterDTO userRegisterDTO);

  ResponseEntity<ApiResponse<List<UserDTO>>> getList();

  ResponseEntity<ApiResponse<UserDTO>> update(Long id, UserUpdateDTO userUpdateDTO);

  ResponseEntity<ApiResponse<?>> delete(Long id);

}

* UserServiceImpl *

@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService{

  private final UserRepository userRepository;

  @Override
  public ResponseEntity<ApiResponse<UserDTO>> get(Long id) {
    User user = userRepository.findById(id)
        .orElseThrow(this::userNotFoundException);

    return ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "get user", UserDTO.setUserDTO(user)));
  }

  @Override
  @Transactional
  public ResponseEntity<ApiResponse<UserDTO>> register(UserRegisterDTO userRegisterDTO) {
    checkIfUsernameExists(userRegisterDTO.getUsername());

    User user = userRepository.save(User.setRegisterUser(userRegisterDTO));
    URI url = URI.create("/api/v1/users/" + user.getId());
    return ResponseEntity.created(url).body(ApiResponse.setApiResponse(true, "add user", UserDTO.setUserDTO(user)));
  }

  @Override
  public ResponseEntity<ApiResponse<List<UserDTO>>> getList() {
    List<User> userList = userRepository.findAll();
    List<UserDTO> userDTOList = userList.stream()
        .map(UserDTO::setUserDTO)
        .collect(Collectors.toList());

    return ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "userList find", userDTOList));
  }

  @Override
  @Transactional
  public ResponseEntity<ApiResponse<UserDTO>> update(Long id, UserUpdateDTO userUpdateDTO)  {

    User user = userRepository.findById(id)
        .orElseThrow(this::userNotFoundException);

    if (!user.getEmail().equals(userUpdateDTO.getEmail())) {
      checkIfEmailExists(userUpdateDTO.getEmail());
    }

    user.updateWithUpdateDTO(userUpdateDTO);
    return ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "user update", UserDTO.setUserDTO(user)));
  }

  @Override
  @Transactional
  public ResponseEntity<ApiResponse<?>> delete(Long id) {
    User user = userRepository.findById(id)
        .orElseThrow(this::userNotFoundException);

    userRepository.delete(user);

    return ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "delete user", null));
  }

  private void checkIfUsernameExists(String username) {
    if (userRepository.existsByUsername(username)) {
      throw new IllegalArgumentException("이미 존재하는 유저 이름입니다.");
    }
  }

  private void checkIfEmailExists(String email) {
    if (userRepository.existsByEmail(email)) {
      throw new IllegalArgumentException("이미 존재하는 이메일 입니다.");
    }
  }

  private NotFoundException userNotFoundException() {
    return new NotFoundException("존재하지 않는 유저입니다.");
  }

5. Exception Handler

1. API paylod

APIErrorResponse

@Getter
@NoArgsConstructor(access = lombok.AccessLevel.PROTECTED)
public class ApiError {
  private HttpStatus status;
  private String message;
  private String debugMessage;
  private LocalDateTime timestamp;

  public static ApiError setApiError(HttpStatus status, String message, Throwable ex) {
    ApiError apiError = new ApiError();
    apiError.status = status;
    apiError.message = message;
    apiError.debugMessage = ex.getLocalizedMessage();
    apiError.timestamp = LocalDateTime.now();
    return apiError;
  }
}

** NotFoundExceptin **

public class NotFoundException extends RuntimeException{
  public NotFoundException(String message) {
    super(message);
  }
}

GlobalExceptionHandler

@RestControllerAdvice
public class GlobalExceptionHandler {
  @ExceptionHandler(IllegalArgumentException.class)
  protected ResponseEntity<Object> handleIllegalArgumentException(IllegalArgumentException ex) {
    APIErrorResponse apiError = APIErrorResponse.setApiError(HttpStatus.BAD_REQUEST, ex.getMessage(), ex);
    return buildResponseEntity(apiError);
  }

  @ExceptionHandler(MethodArgumentNotValidException.class)
  protected ResponseEntity<Object> handleMethodArgumentNotValidException(MethodArgumentNotValidException ex) {
    APIErrorResponse apiError = APIErrorResponse.setApiError(HttpStatus.BAD_REQUEST, ex.getBindingResult().getAllErrors().get(0).getDefaultMessage(), ex);
    return buildResponseEntity(apiError);
  }

  @ExceptionHandler(NotFoundException.class)
  protected ResponseEntity<Object> handleUsernameNotFoundException(NotFoundException ex) {
    APIErrorResponse apiError = APIErrorResponse.setApiError(HttpStatus.NOT_FOUND, ex.getMessage(), ex);
    return buildResponseEntity(apiError);
  }

  @ExceptionHandler(NoHandlerFoundException.class)
  protected ResponseEntity<Object> handleNoHandlerFoundException(NoHandlerFoundException ex) {
    APIErrorResponse apiError = APIErrorResponse.setApiError(HttpStatus.NOT_FOUND, ex.getMessage(), ex);
    return buildResponseEntity(apiError);
  }

  private ResponseEntity<Object> buildResponseEntity(APIErrorResponse apiError) {
    return new ResponseEntity<>(apiError, apiError.getStatus());
  }
}

GlobalExceptionHandler 를 추가하여 Exception 시 해당하는 오류에 맞게 HttpStatus를 구분하여 Error 응답을 사용자에게 전송합니다.

4. UnitTest

UserApiControllerTest

@WebMvcTest(UserApiController.class)
@WithMockUser(username = "테스트_최고관리자", roles = {"SUPER"})
@DisplayName("유저 API 테스트")
class UserApiControllerTest {
  private static final String API_URL = "/api/v1/users";

  @Autowired
  private MockMvc mockMvc;
  @Autowired
  private ObjectMapper objectMapper;
  @MockBean
  private UserService userService;

  @Test
  @DisplayName("유저 추가 API 실패 테스트")
  public void testAddShouldReturn400BadRequest() throws Exception {

    UserRegisterDTO userRegisterDTO = new UserRegisterDTO();

    userRegisterDTO.setUsername("");
    userRegisterDTO.setPassword("test1234");

    String requestBody = objectMapper.writeValueAsString(userRegisterDTO);

    mockMvc.perform(
            post(API_URL)
                .with(csrf())
                .contentType(MediaType.APPLICATION_JSON)
                .content(requestBody)
        )
        .andExpect(status().isBadRequest())
        .andDo(print());
  }

  @Test
  @DisplayName("유저 추가 API 성공 테스트")
  public void testAddShouldReturn200Request() throws Exception {

    UserRegisterDTO userRegisterDTO = new UserRegisterDTO();

    userRegisterDTO.setUsername("test");
    userRegisterDTO.setEmail("test1234@naver.com");
    userRegisterDTO.setPassword("test1234");

    String requestBody = objectMapper.writeValueAsString(userRegisterDTO);

    Mockito.when(userService.register(any(UserRegisterDTO.class)))
        .thenReturn(ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "add user", UserDTO.setUserDTO(User.setRegisterUser(userRegisterDTO)))));

    mockMvc.perform(
            post(API_URL)
                .with(csrf())
                .contentType(MediaType.APPLICATION_JSON)
                .content(requestBody)
        )
        .andExpect(status().is2xxSuccessful())
        .andExpect(jsonPath("$.data.email").value(userRegisterDTO.getEmail()))
        .andExpect(jsonPath("$.data.username").value(userRegisterDTO.getUsername()))
        .andDo(print());
  }

  @Test
  @DisplayName("유저 조회 API 실패 테스트")
  void getUserTestShouldReturn404NotFound() throws Exception {
    Long userId = 1L;
    String requestUrl = API_URL + "/" + userId;

    when(userService.get(userId)).thenThrow(new NotFoundException("존재하지 않는 유저입니다."));

    mockMvc.perform(
            get(requestUrl)
                .with(csrf())
        )
        .andExpect(status().isNotFound())
        .andDo(print());
  }

  @Test
  @DisplayName("유저 조회 API 성공 테스트")
  void getUserTestShouldReturn200Request() throws Exception {
    Long userId = 1L;
    String requestURI = API_URL + "/" + userId;
    String email = "test@naver.com";

    User user = User.setUser(userId, "test", email, "test1234");
    ResponseEntity<ApiResponse<UserDTO>> responseEntity = ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "get user", UserDTO.setUserDTO(user)));

    when(userService.get(userId)).thenReturn(responseEntity);

    mockMvc.perform(
            get(requestURI)
                .with(csrf())
        )
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.data.email").value(email))
        .andDo(print());
  }

  @Test
  @DisplayName("사용자 리스트 조회 API 성공 테스트")
  void getUserListShouldReturn200Request() throws Exception {
    String user1Email = "test1@naver.com";
    String user2Email = "test2@naver.com";
    User user1 = User.setUser(1L, "test1", user1Email, "test1234");
    User user2 = User.setUser(2L, "test2", user2Email, "test1234");

    List<User> userList = List.of(user1, user2);
    ResponseEntity<ApiResponse<List<UserDTO>>> responseEntity = ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "userList find", userList.stream()
        .map(UserDTO::setUserDTO)
        .collect(Collectors.toList())));

    when(userService.getList()).thenReturn(responseEntity);

    mockMvc.perform(
            get(API_URL)
                .with(csrf())
        )
        .andExpect(status().isOk())
        .andExpect(content().contentType("application/json"))
        .andExpect(jsonPath("$.data[0].email").value(user1Email))
        .andExpect(jsonPath("$.data[1].email").value(user2Email))
        .andDo(print());
  }

  @Test
  @DisplayName("사용자 업데이트 API 실패 NotFound 테스트")
  void updateUserShouldReturn404NotFound() throws Exception {
    Long userId = 1L;
    String requestURI = API_URL + "/" + userId;

    UserUpdateDTO userUpdateDTO = new UserUpdateDTO();
    userUpdateDTO.setEmail("test1@naver.com");
    userUpdateDTO.setPassword("test1234");

    String requestBody = objectMapper.writeValueAsString(userUpdateDTO);

    when(userService.update(eq(userId), any(UserUpdateDTO.class)))
        .thenThrow(new NotFoundException("해당하는 유저가 없습니다."));

    mockMvc.perform(
            put(requestURI)
                .with(csrf())
                .contentType(MediaType.APPLICATION_JSON)
                .content(requestBody))
        .andExpect(status().isNotFound())
        .andDo(print());
  }

  @Test
  @DisplayName("사용자 업데이트 API 실패 BadRequest 테스트")
  void updateUserShouldReturn400BadRequest() throws Exception {
    Long userId = 1L;
    String requestURI = API_URL + "/" + userId;

    UserUpdateDTO userUpdateDTO = new UserUpdateDTO();

    String requestBody = objectMapper.writeValueAsString(userUpdateDTO);

    mockMvc.perform(
            put(requestURI)
                .with(csrf())
                .contentType(MediaType.APPLICATION_JSON)
                .content(requestBody))
        .andExpect(status().isBadRequest())
        .andDo(print());
  }

  @Test
  @DisplayName("사용자 업데이트 API 성공 테스트")
  void updateUserShouldReturn200Ok() throws Exception {
    Long userId = 1L;
    String requestURI = API_URL + "/" + userId;

    User user = User.setUser(userId, "test", "test@naver.com", "test1234");

    UserUpdateDTO userUpdateDTO = new UserUpdateDTO();
    userUpdateDTO.setEmail("test@naver.com");
    userUpdateDTO.setPassword("test1234");

    Mockito.when(userService.update(eq(userId), any(UserUpdateDTO.class)))
        .thenReturn(ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "user update", UserDTO.setUserDTO(user))));

    String requestBody = objectMapper.writeValueAsString(userUpdateDTO);

    mockMvc.perform(
            put(requestURI)
                .with(csrf())
                .contentType(MediaType.APPLICATION_JSON)
                .content(requestBody))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.data.email").value(user.getEmail()))
        .andDo(print());
  }

  @Test
  @DisplayName("사용자 업데이트 API 실패 NotFound 테스트")
  void deleteUserShouldReturn404NotFound() throws Exception {
    Long userId = 1L;
    String requestURI = API_URL + "/" + userId;

    when(userService.delete(userId))
        .thenThrow(new NotFoundException("해당하는 유저가 없습니다."));

    mockMvc.perform(
            delete(requestURI)
                .with(csrf())
        )
        .andExpect(status().isNotFound())
        .andDo(print());
  }

  @Test
  @DisplayName("사용자 삭제 API 성공 테스트")
  void deleteUserShouldReturn200Ok() throws Exception {
    Long userId = 1L;
    String requestURI = API_URL + "/" + userId;

    Mockito.when(userService.delete(userId))
        .thenReturn(ResponseEntity.ok().body(ApiResponse.setApiResponse(true, "delete user", null)));

    mockMvc.perform(
            delete(requestURI)
                .with(csrf())
        )
        .andExpect(status().isOk())
        .andDo(print());
  }
}

5. 유닛테스트 문제 사항 / 의문

1. MockMvc 인자 매칭 오류 해결하기

2. @WebMvcTest 작성 시 Spring Security 유의사항

3. @Transactional 내부에서의 Exception

4. REST API 의 모범적인 오류처리

최근에 Spring Boot 애플리케이션에서 REST API의 단위 테스트를 진행하던 중, MockMvc를 사용한 테스트 케이스에서 예상치 못한 결과를 마주했습니다. 특히, updateUser API를 테스트할 때, NotFoundException을 발생시켜야 하는 상황에서 계속해서 200 OK 응답이 반환되는 문제가 발생했습니다.

@Test
@DisplayName("사용자 업데이트 API 실패 UserNotFound 테스트")
void updateUserShouldReturn404NotFound() throws Exception {
    // ... 코드 생략 ...
    Mockito.when(userService.update(userId, userUpdateDTO))
        .thenThrow(new NotFoundException("해당하는 유저가 없습니다."));
    // ... 코드 생략 ...
}

2. 문제 진단

원인 파악을 위해 다음과 같은 점들을 검토했습니다:

1. Mockito 설정 검증: Mockito.when(...).thenThrow(...) 구문이 정확히 설정되었는지 확인했습니다.
2. MockMvc 로그 분석: andDo(print())를 통해 상세한 실행 결과를 로깅하여 검토했습니다.
3. MockMvc와 실제 서버 동작의 차이: MockMvc는 실제 HTTP 요청을 보내지 않고 서버의 디스패처 서블릿을 모의로 사용한다는 점을 고려했습니다.

3. 해결 과정

문제의 원인은 Mockito의 인자 매칭이 정확히 이루어지지 않은 것으로 밝혀졌습니다. userUpdateDTO 객체가 테스트 중의 userService.update 메서드 호출과 정확히 일치하지 않아 예외가 발생하지 않았던 것입니다.

4. 해결 방법

ArgumentMatchers의 any() 메서드를 사용하여 타입만 일치하면 어떤 객체든 받아들일 수 있도록 설정을 변경했습니다.

@Test
@DisplayName("사용자 업데이트 API 실패 UserNotFound 테스트")
void updateUserShouldReturn404NotFound() throws Exception {
    // ... 코드 생략 ...
    Mockito.when(userService.update(eq(userId), any(UserUpdateDTO.class)))
        .thenThrow(new NotFoundException("해당하는 유저가 없습니다."));
    // ... 코드 생략 ...
}

이 변경 후, 테스트는 정상적으로 NotFoundException을 발생시키고, 404 Not Found 응답을 반환했습니다.

5. 결론

이 경험을 통해 테스트 중에 Mockito인자 매칭의 정확성이 얼마나 중요한지 다시 한 번 깨달았습니다. 또한, ArgumentMatchers를 효과적으로 사용하여 테스트의 유연성과 견고성을 높일 수 있음을 배웠습니다. 테스트 중 예상치 못한 문제에 직면했을 때, 구체적인 로깅과 세심한 디버깅이 문제 해결의 열쇠가 될 수 있음을 잊지 말아야겠습니다.

1. 개요

프로그램의 객체 또는 일부에 대한 제어를 컨테이너나 프레임워크로 이전하는 소프트웨어 엔지니어링의 원칙입니다. 예를들어 기존 프로그래밍에서는 애플리케이션의 비지니스 로직이 실행 흐름을 제어하고 라이브러리 함수나 객체를 호출합니다. 그러나 Ioc에서는 이러한 관게가 역전되어 프레임워크가 실행 흐름을 제어하고 애플리케이션 코드는 프레임워크에 의해 호출됩니다. 객체 지향 프로그래밍에서 가장 자주 사용되며 보다 모듈적이고 유연하며 쉽게 테스트할 수 있는 코드를 가능하게 합니다.

2. 작동방식

소프트웨어 개발에서 할리우드 원칙은 애플리케이션 코드가 프레임워크나 라이브러리 코드를 호출하는 대신 프레임워크가 애플리케이션 코드를 호출하는 것을 의미합니다. 이는 의존성 주입, 이벤트 중심 프로그래밍 또는 템플릿 메서드와 같은 다양한 기술을 통해 이루어집니다. 프레임워크는 객체의 수명 주기를 관리하고, 필요에 따라 인스턴스를 생성하거나 폐기하며, 객체가 생성될 때 필요한 종속성을 제공하는 역할을 담당합니다.

헐리우드 원칙 '당신이 할 일 중에서 내가 필요할 때 불러주면, 요청한 사항에 맞춰서 행동하겠다. ' 라고 정의한다. 즉, 내가 언제 어떻게 해야 할 지를 알고, 스스로 제어 할 수 있는 일이면 하되, 그밖에 영역의 일은 정의해서 알려주면 행동하겠다는 것이다.

3. 사용의 장점

• 커플링 감소: IoC를 사용하면 컴포넌트가 하드코딩된 종속성을 가질 필요가 없으므로 애플리케이션의 여러 부분 간의 결합이 줄어듭니다.

• 모듈성 향상: 구성 요소가 더 느슨하게 결합되므로 애플리케이션이 더 모듈화되어 이해, 유지 관리 및 확장이 더 쉬워집니다.

• 향상된 테스트: IoC를 사용하면 종속성을 모의 또는 스텁으로 쉽게 대체할 수 있으므로 단위 테스트가 더 간단해집니다.

• 유연성 및 재사용성 향상: 컴포넌트가 특정 구현에 엄격하게 종속되지 않으므로 재사용성과 유연성이 향상됩니다.

• 더 쉬운 구성 및 통합: 비즈니스 로직의 변경이나 다른 시스템과의 통합은 주로 구성을 통해 최소한의 코드 변경으로 이루어질 수 있습니다.

전략 설계 패턴, 서비스 로케이터 패턴, 팩토리 패턴, 의존성 주입(DI)과 같은 다양한 메커니즘을 통해 IoC를 구현할 수 있으며 애플리케이션을 설계하고 개발하는 방식에 큰 변화를 가져와 더욱 견고하고 유지 관리가 용이하며 확장 가능한 시스템으로 이어집니다.

2. DI(Dependency Injection) 의존성 주입

DI의 정의 종속성 주입(DI)은 제어의 역전(IoC)을 구현하는 데 중요한 디자인 패턴입니다. 이는 객체가 직접 종속성을 생성하는 것이 아니라 객체에 외부 종속성을 제공하는 프로세스를 포함합니다. 이 패턴은 종속 객체의 구성과 사용법을 분리하여 보다 유연하고 유지 관리가 용이하며 테스트 가능한 코드를 만드는 데 유용합니다. DI에서 객체는 생성 시 종속성을 전달받으며, 일반적으로 객체와 종속성을 함께 어셈블하는 역할을 하는 '인젝터' 또는 '컨테이너'를 통해 종속성을 전달받습니다.

1. 유형

1. Constructor Injection(생성자 주입)

생성자 주입은 클래스 생성자를 통해 종속성이 제공됩니다. 인스턴스화할 때 필요한 종속성을 생성자에 매개변수로 전달하는 일반적인 기법입니다. 이 방법을 사용하면 객체가 항상 종속성과 함께 생성되므로 완전히 생성된 후에는 변경할 수 없습니다.

@Service
public class SomeService {
    private final UserRepository userRepository;
    private final SomeRepository someRepository;

    @Autowired
    public CoffeeServiceImpl(UserRepository userRepository, SomeRepository someRepository) {
        this.userRepository = userRepository;
        this.someRepository = someRepository;
    }
}

• 생성자 호출 시점에 1번만 호출되는 것을 보장합니다.
• 불변과 필수 의존 관계에 사용합니다.
• 생성자가 1개만 존재하는 경우 @AutoWired를 생략해도 자동 주입됩니다.
• NPE(NullPointerException)을 방지할 수 있습니다.
• 주입받을 필드를 final로 선언 가능합니다.

  @Autowired 필요한 의존 객체의 “타입"에 해당하는 빈을 찾아 주입한다. 생성자, setter, 필드 위의 3가지의 경우에 Autowired를 사용할 수 있다. 그리고 Autowired는 기본값이 true이기 때문에 의존성 주입을 할 대상을 찾지 못한다면 애플리케이션 구동에 실패한다.

2. Setter Injection(수정자 주입)

수정자 주입은 클래스의 세터 메서드를 통해 종속성을 주입하는 것입니다. 이 방법을 사용하면 객체의 인스턴스화 후에 종속성을 설정하거나 변경할 수 있으므로 유연성이 향상됩니다. 그러나 세터가 호출되지 않으면 객체가 불완전한 상태가 될 수 있습니다.

@Service
public class SomeService {
    private final UserRepository userRepository;
    private final SomeRepository someRepository;

    @Autowired
    public void setUserRepository(UserRepository userRepository) {
        this.userRepository = userRepository
    }

    @Autowired
    public void setSomeRepository(SomeRepository someRepository) {
        this.someRepository = someRepository
    }
}

• 선택과 변경 가능성이 있는 의존 관계에 사용됩니다.
• set필드명 메서드를 생성하여 의존 관계를 주입합니다.
• @Autowired를 입력하지 않으면 실행이 되지 않습니다.

3. Field Injection(필드 주입)

필드 주입은 클래스의 필드에 종속성을 직접 주입합니다. 가장 간단한 형태이고 코드가 덜 필요하지만 클래스의 공용 API를 우회하기 때문에 객체 상태를 테스트하고 관리하기가 어렵기 때문에 일반적으로 선호되지 않습니다.

@Service
public class SomeService {
    @Autowired
    private final UserRepository userRepository;
    @Autowired
    private final UserRepository userRepository;
}

• 외부에서 변경이 불가능하여 테스트하기 어려운 단점이 있습니다.
• DI 프레임워크가 존재하지 않는다면 아무것도 할 수 없습니다.
• 주로 애플리케이션의 실제 코드와 상관없는 특정 테스트 진행시 사용합니다.
• 정상적으로 사용하려면 결국 Setter 가 필요합니다.
• 만약 의존관계를 필수적으로 넣지 않으려면 @Autowired(required=false) 옵션 통해 처리 가능합니다.

필드 주입을 일반적으로 선호하지 않는 이유는 DI 컨테이너 내부에서만 작동하며, 순수 자바 코드로 테스트 하기 어러움이 있습니다. 그리고 final 키워드를 통해 불변 속성이라고 볼 수도 없고, Setter로 가변 속성이라고 볼 수도 없는 애매한 상황이 발생합니다.

2. 장점

• 느슨한 결합: 종속성 주입(DI)은 소비자 클래스의 종속성을 핵심 동작으로부터 분리하는 역할을 합니다. 이러한 분리는 종속성의 변경이나 구현 방식이 이러한 종속성을 사용하는 클래스에 거의 또는 전혀 영향을 미치지 않음을 의미합니다. 즉, 클래스가 종속성의 세부 사항에 얽매이지 않으므로 보다 모듈화되고 적응력이 뛰어난 코드 구조가 만들어집니다.

소비자 클래스 애플리케이션에서 다른 컴포넌트나 서비스에 종속되어 작업을 수행하는 클래스입니다. 예를 들어 전자상거래 애플리케이션에 OrderProcessor 클래스가 있는 경우 이 클래스는 결제 처리를 처리하기 위해 PaymentService 클래스에 종속되고 배송 물류를 처리하기 위해 ShippingService 클래스에 종속될 수 있습니다.

• 테스트의 간소화: 테스트 중에 클래스에 모의 또는 더미 버전의 종속성을 주입하면 단위 테스트를 더 간단하게 수행할 수 있습니다. 이 접근 방식은 종속성의 실제 구현에 의존하지 않기 때문에 테스트에 집중하고, 관리하기 쉬우며, 안정성을 높일 수 있습니다.

• 코드 유지 관리 개선: 클래스 내에서 종속성을 생성하는 대신 종속성을 주입하면 코드가 더 깔끔하고 가독성이 높아집니다. 이 접근 방식은 클래스가 의존하는 구성 요소와 사용 방법을 명확히 하기 때문에 코드베이스를 더 쉽게 탐색하고 유지 관리할 수 있습니다.

• 유연성 및 확장성: 의존성 주입은 애플리케이션의 유연성과 확장성에 기여합니다. 전체 코드에서 필요한 최소한의 조정만으로 개별 컴포넌트를 쉽게 교체하거나 업그레이드할 수 있습니다. 이러한 적응성은 애플리케이션의 유지보수 및 확장에 매우 중요한 역할을 합니다.

DI를 사용하는 것은 최신 소프트웨어 개발 관행에 따라 확장 가능하고 유지 관리 및 테스트가 가능한 시스템을 구축하는 데 중요한 역할을 합니다.

Spring 프레임워크의 IoC와 DI

Spring에서 IoC 및 DI 구현 Spring 프레임워크는 IoC 및 DI를 강력하게 구현하여 아키텍처의 초석으로 삼습니다. 이 프레임워크는 Bean(Spring의 객체)의 생성 및 wiring을 관리하고 사용하기 전에 모든 종속성이 충족되는지 확인합니다. 이는 빈의 인스턴스화, 구성, 어셈블리를 담당하는 IoC 컨테이너를 통해 이루어집니다.

빈 와이어링(wiring) 스프링을 사용하는 애플리케이션에서 각 객체가 필요한 다른 객체를 직접 찾거나 생성할 필요가 없다. 컨테이너가 협업할 객체에 대한 정보를 주기 때문이다. 애플리케이션 객체 간의 이러한 연관 관계 형성 작업이 바로 의존성 주입(Dependency Injection)의 핵심이며, 이를 보통 와이어링(wiring)이라 한다.

이 프로세스에는 일반적으로 구성 파일이나 어노테이션에 빈과 해당 종속성을 정의하는 작업이 포함되며, Spring 컨테이너는 빈이 생성될 때 이러한 종속성을 생성하고 주입하는 작업을 처리합니다. 이 접근 방식은 애플리케이션의 구성 및 종속성 사양을 실제 애플리케이션 코드와 분리하여 보다 깔끔하고 모듈화된 코드를 생성합니다.

1. Spring의 IoC 컨테이너

Spring의 IoC 컨테이너는 기본적으로 객체 생성, 수명 주기 관리, 구성 및 종속성 관리를 담당하는 정교한 팩토리입니다. 컨테이너는 XML 파일, 어노테이션 또는 Java 기반 구성으로 구성할 수 있습니다. 싱글톤(컨테이너당 하나의 인스턴스), 프로토타입(매번 새로운 인스턴스), 요청, 세션 등 웹 애플리케이션을 위한 여러 가지 범위의 빈을 지원하므로 빈의 수명 주기를 유연하게 관리할 수 있습니다.

2. 구성

• XML 구성: Spring 초창기에는 XML 파일이 구성에 광범위하게 사용되었습니다. 여기에는 XML 파일에 빈과 그 종속성을 정의하는 것이 포함됩니다. Spring 컨테이너는 이 파일을 읽고 그에 따라 빈을 생성합니다. XML 구성은 빈을 관리하기 위한 중앙 집중식 장소를 제공하지만, 대규모 애플리케이션에서는 장황하고 관리하기 어려울 수 있습니다.

• 어노테이션 기반 구성: Spring 프레임워크의 발전과 함께, 어노테이션 기반 구성이 더욱 널리 사용되고 있습니다. autowiring 종속성을 위한 @Autowired, 빈을 선언하기 위한 @Component, Java 기반 구성을 위한 @Configuration, @Bean과 같은 어노테이션이 사용됩니다. 어노테이션 기반 구성은 XML 파일의 필요성을 줄이고 코드를 더 읽기 쉽고 유지 관리하기 쉽게 만듭니다. 또한 빈 구성을 보다 세밀하게 제어할 수 있으며 최신 Java 에서 주로 사용됩니다.

전반적으로 Spring 프레임워크에서 IoC와 DI를 구현하면 Java 애플리케이션 개발이 크게 간소화됩니다. 느슨한 결합과 높은 응집력과 같은 모범 사례를 장려하여 애플리케이션의 확장성, 유지보수성, 테스트 가능성을 높입니다.

참고자료

baeldung-Intro to Inversion of Control and Dependency Injection with Spring [Spring] IoC, DI 란? [Spring] 스프링 의존성 주입

넷플릭스 클론 코딩을 진행하며 JWT로그인을 시도한 기록입니다.

1. Application Architecture

1. 개발환경

java: 17
springBoot: 3.1.5
springSecurity: 6.1.2
jjwt: 0.12.3
gradle: 8.3

2. 아키텍쳐

시나리오

• 사용자가 서비스 측에 계정 생성을 요청합니다.
• 사용자가 서비스에 계정 인증 요청을 제출합니다.
• 인증된 사용자가 리소스 액세스 요청을 보냅니다.

  Sign Up

  

1. 사용자가 서비스에 가입요청을 제출하면 요청 데이터에서 사용자 객체가 생성됩니다.
2. userService가 호출되어 사용자 객체 유효성 검사와 JPA를 활용해 사용자가 데이터베이스에 저장 됩니다.
3. JwtUtils가 호출되어 사용자 객체에 대한 JWT를 반환합니다
4. JWT는 JSON 응답 내부에서 캡슐화되어 사용자에게 반환됩니다.

   Sign In

   
5. 사용자가 서비스에 로그인 요청을 보내면 제공된 사용자 이름과 비밀번호를 사용해UsernamePasswordAuthenticationToken이라는 인증 객체가 생성됩니다.
6. 사용자의 이름이나 비밀번호가 올바르지 않으면 예외가 발생하고 HTTP 4xx 응답이 사용자에게 반환 됩니다.
7. 인증에 성공하면 데이터베이스에서 사용자를 검색하고 사용자가 존재하지 않으면 HTTP 4xx 응답이 사용자에게 전송됩니다.
8. 사용자 정보가 확보되면 JwtUtils를 호출하여 JWT를 생성하고 JSON 응답 내부에서 캡슐화되어 사용자에게 반환 됩니다

resources test

2. Gradle 설정

    implementation 'io.jsonwebtoken:jjwt-api:0.12.3'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.3'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.3'

3. 소스코드

GitHub

https://github.com/Get-bot/netflixCloneServer

1.Entity 구현

userEntity

@Entity
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@EntityListeners(AuditingEntityListener.class)
@Table(name = "users")
public class User {

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

  private String email;

  private String username;

  private String password;

  @CreatedDate
  private LocalDateTime createdAt;

  @OneToMany(mappedBy = "user", orphanRemoval = true, cascade = CascadeType.ALL)
  private Set<UserRoles> roles = new HashSet<>();

  private Integer status;

  public static User registerUser(String email, String username, String password, Set<Role> roles) {
    User user = new User();
    user.email = email;
    user.username = username;
    user.password = password;
    user.status = UserState.ACTIVE.getValue();

    for (Role role : roles) {
      UserRoles userRoles = UserRoles.createUserRoles(user, role);
      user.getRoles().add(userRoles);
    }

    return user;
  }

}

RoleEntity

@Entity
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@Table(name = "roles")
public class Role {

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

  @Enumerated(EnumType.STRING)
  private ERole name;

  private String description;

}

UserRolesJuntionEntity

@Entity
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@Table(name = "user_roles")
public class UserRoles {

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

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "user_id")
  private User user;

  @ManyToOne(fetch = FetchType.LAZY)
  @JoinColumn(name = "role_id")
  private Role role;


  public static UserRoles createUserRoles(User user, Role role) {
    UserRoles userRoles = new UserRoles();
    userRoles.user = user;
    userRoles.role = role;
    return userRoles;
  }

}

ERole

public enum ERole {
  ROLE_USER,
  ROLE_MODERATOR,
  ROLE_ADMIN
}

2. 저장소구현

UserRepository

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
  Optional<User> findByEmail(String email);
  Boolean existsByEmail(String email);
}

RoleRepository

@Repository
public interface RoleRepository extends JpaRepository<Role, Long> {
  Optional<Role> findByName(ERole name);
}

3. 스프링 보안 구성

WebSecurityConfig

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
@AllArgsConstructor
public class WebSecurityConfig {

  private final UserDetailsServiceImpl userDetailsService;

  private final AuthEntryPointJwt unauthorizedHandler;

  @Bean
  public AuthTokenFilter authenticationJwtTokenFilter() {
    return new AuthTokenFilter();
  }

  @Bean
  public DaoAuthenticationProvider authenticationProvider() {
    DaoAuthenticationProvider authProvider = new DaoAuthenticationProvider();
    authProvider.setUserDetailsService(userDetailsService);
    authProvider.setPasswordEncoder(passwordEncoder());
    return authProvider;
  }

  @Bean
  public AuthenticationManager authenticationManager(AuthenticationConfiguration authConfig) throws Exception {
    return authConfig.getAuthenticationManager();
  }

  @Bean
  public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
  }

  @Bean
  public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.csrf(AbstractHttpConfigurer::disable)
        .exceptionHandling(exception -> exception.authenticationEntryPoint(unauthorizedHandler))
        .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .authorizeHttpRequests(auth ->
            auth.requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/api/test/**").permitAll()
                .anyRequest().authenticated()
        );

    http.authenticationProvider(authenticationProvider());

    http.addFilterBefore(authenticationJwtTokenFilter(), UsernamePasswordAuthenticationFilter.class);

    return http.build();
  }
}

• @EnableWebSecurity 주석은 Spring 보안의 웹 보안 지원을 활성화합니다. 이것은 Spring Security가 웹 기반 보안을 제공하도록 설정하는 것을 의미합니다. 이 주석이 적용된 설정 클래스는 웹 보안을 위한 다양한 보안 규칙과 구성을 정의합니다. 예를 들어, URL 패턴에 따른 접근 제어, 로그인 페이지의 구성, 세션 관리 등이 이에 해당합니다. @EnableWebSecurity를 사용하면 Spring Security가 이러한 설정을 찾아서 전체 애플리케이션의 글로벌 웹 보안 설정으로 자동 적용합니다.

• @EnableMethodSecurity 주석은 메소드 수준의 보안을 활성화합니다. 이 주석은 클래스 또는 메소드 수준에서 보안 정책을 세밀하게 정의할 수 있게 해 줍니다. 예를 들어, 특정 역할을 가진 사용자만이 특정 메소드를 호출할 수 있도록 제한하거나, 메소드 실행 전 후에 특정 보안 규칙을 적용할 수 있습니다. @PreAuthorize, @PostAuthorize, @Secured 등의 주석을 메소드에 적용하여 이러한 보안 정책을 구현할 수 있습니다

• WebSecurityConfigurerAdapter 인터페이스에서 configure(HttpSecurity http) 메서드를 재정의합니다. 이 메서드는 모든 사용자에게 인증을 요구할지 여부, 모든 사용자에게 인증을 요구할지 여부, 어떤 필터(AuthTokenFilter)를 사용할지 여부, 언제 작동할지 여부(UsernamePasswordAuthenticationFilter 앞에 필터링), 어떤 예외 처리기(AuthEntryPointJwt)를 선택할지 여부 등을 Spring Security에 알려줍니다.

• Spring Security는 인증 및 권한 부여를 수행하기 위해 사용자 세부 정보를 로드합니다. 따라서 구현해야 하는 UserDetailsService 인터페이스가 있습니다.

• UserDetailsService의 구현은 AuthenticationManagerBuilder.userDetailsService() 메서드에 의해 DaoAuthenticationProvider를 구성하는 데 사용됩니다.

• 또한 DaoAuthenticationProvider에 대한 PasswordEncoder가 필요합니다. 지정하지 않으면 일반 텍스트를 사용합니다.

4. userDetails 구현

애플리케이션에서 인증 및 권한 부여를 위해 Spring Security를 사용하는 경우, 사용자별 데이터를 Spring Security API에 제공하고 인증 프로세스 중에 사용해야 합니다. 이 사용자별 데이터는 UserDetails 객체에 캡슐화됩니다. UserDetails는 다양한 메서드를 포함하는 인터페이스입니다.

자세한 정보 : UserDetails

userDetails

인증 프로세스가 성공하면 인증 객체에서 사용자 이름, 비밀번호, 권한과 같은 사용자 정보를 가져올 수 있습니다.

public class UserDetailsImpl implements UserDetails {
  private static final long serialVersionUID = 1L;

  private final Long id;

  private final String email;

  private final String username;

  @JsonIgnore // 이 어노테이션은 JSON으로 변환될 때, password를 제외시킴
  private final String password;

  private final Collection<? extends GrantedAuthority> authorities;

  public UserDetailsImpl(Long id, String username, String email, String password,
                         Collection<? extends GrantedAuthority> authorities) {
    this.id = id;
    this.email = email;
    this.username = username;
    this.password = password;
    this.authorities = authorities;
  }

  public static UserDetailsImpl build(User user) {
    List<GrantedAuthority> authorities = user.getRoles().stream()
        .map(role -> new SimpleGrantedAuthority(role.getRole().getName().name()))
        .collect(Collectors.toList());

    return new UserDetailsImpl(
        user.getId(),
        user.getUsername(),
        user.getEmail(),
        user.getPassword(),
        authorities);
  }

  @Override
  public Collection<? extends GrantedAuthority> getAuthorities() {
    return authorities;
  }

  public Long getId() {
    return id;
  }

  public String getEmail() {
    return email;
  }

  @Override
  public String getPassword() {
    return password;
  }

  @Override
  public String getUsername() {
    return username;
  }

  @Override
  public boolean isAccountNonExpired() {
    return true;
  }

  @Override
  public boolean isAccountNonLocked() {
    return true;
  }

  @Override
  public boolean isCredentialsNonExpired() {
    return true;
  }

  @Override
  public boolean isEnabled() {
    return true;
  }

  @Override
  public boolean equals(Object o) {
    if (this == o)
      return true;
    if (o == null || getClass() != o.getClass())
      return false;
    UserDetailsImpl user = (UserDetailsImpl) o;
    return Objects.equals(id, user.id);
  }

}

위의 코드를 보면 Set<Role>을 List<GrantedAuthority>로 변환한 것을 알 수 있습니다. 나중에 사용할 Spring 보안 및 인증 객체로 작업하는 것이 중요합니다.

userDetailsImpl

loadUserByUsername() 메서드를 재정의합니다.

@Service
@AllArgsConstructor
public class UserDetailsServiceImpl implements UserDetailsService {

  private final UserRepository userRepository;

  @Override
  @Transactional(readOnly = true)
  public UserDetails loadUserByUsername(String email) throws UsernameNotFoundException {
    User user = userRepository.findByEmail(email)
        .orElseThrow(() -> new UsernameNotFoundException("회원의 이메일을 찾을 수 없습니다: " + email));
    return UserDetailsImpl.build(user);
  }
}

UserRepository를 사용하여 전체 사용자 정의 User 객체를 가져온 다음 정적 build() 메서드를 사용하여 UserDetails 객체를 빌드합니다.

5. 요청 필터링

AuthTokenFilter

@RequiredArgsConstructor
public class AuthTokenFilter extends OncePerRequestFilter {

  private static final Logger logger = Logger.getLogger(AuthTokenFilter.class.getName());
  private final JwtUtils jwtUtils;
  private final UserDetailsServiceImpl userDetailsService;

  @Override
  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
    try {
      String jwt = parseJwt(request);
      if (jwt != null && jwtUtils.vaildateJwtToken(jwt)) {
        String email = jwtUtils.getUserNameFromJwtToken(jwt);

        var userDetails = userDetailsService.loadUserByUsername(email);
        UsernamePasswordAuthenticationToken authentication =
            new UsernamePasswordAuthenticationToken(userDetails, null, userDetails.getAuthorities());

        SecurityContextHolder.getContext().setAuthentication(authentication);
      }
    } catch (Exception e) {
      logger.severe("Cannot set user authentication: " + e);
    }

    filterChain.doFilter(request, response);
  }

  private String parseJwt(HttpServletRequest request) {
    String headerAuth = request.getHeader("Authorization");

    if (StringUtils.hasText(headerAuth) && headerAuth.startsWith("Bearer ")) {
      return headerAuth.substring(7);
    }

    return null;
  }
}

doFilterInternal() 내부에서 수행하는 작업:

• Authorization 헤더에서 JWT를 가져옵니다(Bearer 접두사를 제거).

• 요청에 JWT가 있으면 유효성을 검사하고 email을 구문 분석합니다.

• email에서 UserDetails를 가져와 인증 객체를 만듭니다.

• setAuthentication(authentication) 메서드를 사용하여 SecurityContext에서 현재 UserDetails를 설정합니다.

  6. JWT 유틸리티 클래스 생성

• 사용자 이름, 날짜, 만료일, 비밀번호에서 JWT 생성하기

• JWT에서 사용자 이름 가져오기

• JWT 유효성 검사

  @Component
  public class JwtUtils {
  private static final Logger logger = LoggerFactory.getLogger(JwtUtils.class);
  
  private final SecretKey key;
  @Value("${netflixclone.app.jwtExpirationMs}")
  private int jwtExpirationMs;
  
  public JwtUtils(@Value("${netflixclone.app.jwtSecret}") String jwtSecret) {
    this.key = Keys.hmacShaKeyFor(Decoders.BASE64.decode(jwtSecret));
  }
  
  public String generateJwtToken(Authentication authentication) {
  
    UserDetailsImpl userPrincipal = (UserDetailsImpl) authentication.getPrincipal();
  
    return Jwts.builder()
        .subject(userPrincipal.getEmail())
        .claim("roles", userPrincipal.getAuthorities())
        .issuedAt(new Date())
        .expiration(new Date((new Date()).getTime() + jwtExpirationMs))
        .signWith(key)
        .compact();
  }
  
  public String getUserNameFromJwtToken(String token) {
    return Jwts.parser().verifyWith(key).build().parseSignedClaims(token).getPayload().getSubject();
  }
  
  public boolean vaildateJwtToken(String token) {
    try {
      Jwts.parser().verifyWith(key).build().parseSignedClaims(token);
      return true;
    } catch (MalformedJwtException e) {
      logger.error("Invalid JWT token: {}", e.getMessage());
    } catch (ExpiredJwtException e) {
      logger.error("JWT token is expired: {}", e.getMessage());
    } catch (UnsupportedJwtException e) {
      logger.error("JWT token is unsupported: {}", e.getMessage());
    } catch (IllegalArgumentException e) {
      logger.error("JWT claims string is empty: {}", e.getMessage());
    }
    return false;
  }
  

}

### 7. 인증 예외처리
이제 AuthenticationEntryPoint 인터페이스를 구현하는 AuthEntryPointJwt 클래스를 생성합니다. 그런 다음 commence() 메서드를 재정의합니다. 이 메서드는 인증되지 않은 사용자가 보안 HTTP 리소스를 요청하고 AuthenticationException이 발생할 때마다 트리거됩니다.
#### AuthEntryPointJwt
```java
@Component
public class AuthEntryPointJwt implements AuthenticationEntryPoint {
  private static final Logger logger = LoggerFactory.getLogger(AuthEntryPointJwt.class);

  @Override
  public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException)
      throws IOException, ServletException {
    logger.error("Unauthorized error: {}", authException.getMessage());
    response.setContentType(MediaType.APPLICATION_JSON_VALUE);
    response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);

    final Map<String, Object> body = new HashMap<>();
    body.put("status", HttpServletResponse.SC_UNAUTHORIZED);
    body.put("error", "Unauthorized");
    body.put("message", authException.getMessage());
    body.put("path", request.getServletPath());

    final ObjectMapper mapper = new ObjectMapper();
    mapper.writeValue(response.getOutputStream(), body);
  }
}

8. Spring RestAPI 컨트롤러 생성

AuthController

@CrossOrigin(origins = "*", maxAge = 3600)
@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthController {
  private final AuthenticationManager authenticationManager;

  private final UserRepository userRepository;

  private final UserService userService;

  private final JwtUtils jwtUtils;

  @PostMapping("/signin")
  public ResponseEntity<?> authenticateUser(@RequestBody LoginRequest loginRequest) {
    return ResponseEntity.ok().body(authenticateAndGenerateJWT(loginRequest.getEmail(), loginRequest.getPassword()));
  }

  @PostMapping("/signup")
  public ResponseEntity<?> registerAndAuthenticateUser(@RequestBody SignupRequest signupRequest) throws CustomException {

    // 유저 등록
    userService.registerUser(signupRequest);

    JwtResponse jwtResponse = authenticateAndGenerateJWT(signupRequest.getEmail(), signupRequest.getPassword());
    ApiResponse<JwtResponse> response = ApiResponse.setApiResponse(true, "회원 가입이 완료 되었습니다!", jwtResponse);

    return ResponseEntity.ok().body(response);
  }

  private JwtResponse authenticateAndGenerateJWT(String email, String password) {
    Authentication authentication = authenticationManager.authenticate(
        new UsernamePasswordAuthenticationToken(email, password));
    SecurityContextHolder.getContext().setAuthentication(authentication);

    String jwt = jwtUtils.generateJwtToken(authentication);
    UserDetailsImpl userDetails = (UserDetailsImpl) authentication.getPrincipal();
    List<String> roleNames = userDetails.getAuthorities().stream()
        .map(GrantedAuthority::getAuthority)
        .toList();

    return JwtResponse.setJwtResponse(jwt, userDetails.getId(), userDetails.getUsername(), userDetails.getEmail(), roleNames);
  }

}

ApiController

@CrossOrigin(origins = "*", maxAge = 3600)
@RestController
@RequestMapping("/api/test")
public class ApiController {

  @GetMapping("/all")
  public String allAccess() {
    return "Public Content.";
  }

  @GetMapping("/user")
  @PreAuthorize("hasRole('USER') or hasRole('MODERATOR') or hasRole('ADMIN')")
  public String userAccess() {
    return "User Content.";
  }

  @GetMapping("/mod")
  @PreAuthorize("hasRole('MODERATOR')")
  public String moderatorAccess() {
    return "Moderator Board.";
  }

  @GetMapping("/admin")
  @PreAuthorize("hasRole('ADMIN')")
  public String adminAccess() {
    return "Admin Board.";
  }

}

4. 실행 테스트 해보기

Sign in

success

fail

Test

success

fail

1. JWT란?

JWT(JSON WEB TOKEN)는 당사자 간에 정보를 JSON 객체로 안전하게 전송하기 위한 간결하고 독립적인 방법을 정의하는 개방형 표준입니다.

간단히 말해서 서로 다른 서비스 간에 발신자를 확인할 수 있는 민감한 정보가 포함된 json 형식의 암호화된 문자열입니다.

2. JWT의 구조

JWT는 헤더, 페이로드, 서명의 세 부분으로 구성됩니다. 각 부분은 토큰의 보안과 무결성을 보장하는 데 중요한 역할을 합니다.

따라서 JWT는 일반적으로 다음과 같은 모양을 취합니다.

xxxxx.yyyyy.zzzzz

1. Header

헤더는 일반적으로 두 부분으로 구성됩니다. 토큰 유형(JWT)과 사용 중인 서명 알고리즘(예: HMAC SHA256 또는 RSA)이 그것입니다.

{
  "alg": "HS256",
  "typ": "JWT"
}

그런 다음 이 JSON은 Base64Url로 인코딩되어 JWT의 첫 번째 부분이 됩니다.

2. Payload

토큰의 두 번째 부분은 페이로드이며, 여기에는 클레임이 포함됩니다. 클레임은 엔티티(일반적으로 사용자)와 추가 데이터에 대한 표현입니다. 클레임에는 등록 클레임, 공개 클레임, 비공개 클레임의 세 가지 유형이 있습니다.

• 등록 클레임(Registered claims) 토큰에 대한 정보들을 담고있는 필수는 아니지만 권장되는 사전 정의된 클레임 세트입니다.

  iss (Issuer) : JWT 발급자 발행한 주체를 식별합니다. sub (Subject) : JWT의 주체(사용자) aud (Audience) : JWT가 대상인 수신자 exp (Expiration Time) : JWT가 만료되는 시간 NumericDate 형식으로 되어있어야 하며 언제나 현재 시간보다 이후로 설정되어 있어야 합니다. nbf (Not Before) : 처리를 위해 JWT를 수락해서는 안 되는 시간 NumericDate 형식으로 되어있어야 하며 클레임을 처리하려면 현재 시간과 같거나 이전 이어야 합니다. iat (Issued At) : JWT가 발급된 시간으로, JWT의 연령을 결정하는 데 사용할 수 있습니다. jti (JWT ID) : 고유 식별자, JWT가 반복되는 것을 방지하는 데 사용할 수 있습니다(토큰을 한 번만 사용할 수 있음).

• 공개 클레임(public claims) 이름 및 이메일과 같은 일반 정보를 포함할 수 있는 공개용 사용자 지정 클레임을 만들 수 있습니다. 공개 클레임을 생성하는 경우 등록하거나 네임스페이스를 통해 충돌 방지 이름을 사용해야 하며, 사용하는 네임스페이스를 통제할 수 있도록 적절한 예방 조치를 취해야 합니다.

• 비공개 클레임(Private claims) 비공개 사용자 지정 클레임을 만들어 애플리케이션과 관련된 정보를 공유할 수 있습니다. 예를 들어 공개 클레임에는 이름, 이메일과 같은 일반적인 정보가 포함될 수 있지만 비공개 클레임에는 직원 ID, 부서 이름과 같은 보다 구체적인 정보가 포함될 수 있습니다.

3. signature

서명은 JWT 발신자가 실제 발신자인지 확인하고 메시지가 중간에 변경되지 않았는지 확인하는 데 사용됩니다.

서명을 생성하기 위해 Base64로 인코딩된 헤더와 페이로드를 비밀과 함께 가져와서 헤더에 지정된 알고리즘으로 서명합니다.

예를 들어 HMAC SHA256 알고리즘을 사용하여 토큰에 대한 서명을 만드는 경우 다음과 같이 하면 됩니다:

HMACSHA256(
      base64UrlEncode(header) + "." +
      base64UrlEncode(payload),
      secret)

3. JWT 작동 방식

1. 토큰 생성 과정

• 헤더와 페이로드 설정: JWT는 먼저 헤더(header)와 페이로드(payload)로 구성됩니다. 헤더는 토큰의 유형(JWT)과 사용된 서명 알고리즘을 명시합니다. 페이로드는 클레임(claim)이라고 불리는 정보 조각을 포함하며, 이는 사용자 식별 정보나 토큰에 대한 다른 데이터를 담을 수 있습니다.

• 서명 생성: 헤더와 페이로드는 각각 Base64로 인코딩되고, 이 둘을 합친 다음 서버의 비밀 키 또는 공개/개인 키 쌍을 사용하여 서명(sign)합니다. 이 서명 과정은 토큰이 중간에 변경되지 않았음을 보장하는 데 중요합니다.

  2. 토큰 검증 과정

• 토큰의 서명 검증 : 클라이언트로부터 받은 JWT는 서버에서 서명을 검증합니다. 이는 서버가 가지고 있는 비밀 키 또는 공개 키를 이용하여 이루어집니다. 서명이 유효하면 토큰이 안전하게 생성되었으며, 중간에 변경되지 않았음을 의미합니다.

• 페이로드의 정보 사용: 서명이 유효하다고 확인되면, 페이로드에서 정보를 추출하여 사용합니다. 이 정보는 사용자 인증, 권한 부여 등에 활용될 수 있습니다.

이러한 과정을 통해 JWT는 웹 애플리케이션과 API에서 안전하고 효율적인 방법으로 사용자 인증 및 정보 교환을 가능하게 합니다. JWT의 구조와 이 두 가지 핵심 프로세스의 조합은 웹 보안에서 중요한 역할을 합니다.

4. JWT 사용의 장점

단순 웹 토큰(SWT) 및 SAML 토큰과 비교할 때 JWT를 사용하면 여러 가지 이점이 있습니다.

• 더 컴팩트합니다: JSON은 XML보다 덜 장황하므로 인코딩할 때 JWT는 SAML 토큰보다 작습니다. 따라서 JWT는 HTML 및 HTTP 환경에서 전달하기에 좋은 선택입니다.

• 더 안전하게: JWT는 서명을 위해 X.509 인증서 형식의 공개/개인 키 쌍을 사용할 수 있습니다. 또한 JWT는 HMAC 알고리즘을 사용하여 공유 비밀로 대칭적으로 서명할 수도 있습니다. SAML 토큰은 JWT와 같은 공개/개인 키 쌍을 사용할 수 있지만, 모호한 보안 허점을 도입하지 않고 XML 디지털 서명을 사용하여 XML에 서명하는 것은 JSON에 서명하는 단순성에 비해 매우 어렵습니다.

• 더 일반적인: JSON 파서는 객체에 직접 매핑되기 때문에 대부분의 프로그래밍 언어에서 일반적입니다. 반대로 XML에는 자연스러운 문서와 객체 간 매핑이 없습니다. 따라서 SAML 어설션보다 JWT로 작업하기가 더 쉽습니다.

• 처리하기 쉽습니다: JWT는 인터넷 규모에서 사용됩니다. 즉, 사용자의 디바이스, 특히 모바일에서 처리하기가 더 쉽습니다.

5. JWT 사용예시

JWT는 다양한 방법으로 사용할 수 있습니다:

• 인증: 사용자가 자격 증명을 사용하여 로그인에 성공하면 ID 토큰이 반환됩니다. OIDC(OpenID Connect) 사양에 따르면 ID 토큰은 항상 JWT입니다.

• 권한 부여: 사용자가 로그인에 성공하면 애플리케이션이 해당 사용자를 대신하여 경로, 서비스 또는 리소스(예: API)에 액세스하도록 요청할 수 있습니다. 이렇게 하려면 모든 요청에서 액세스 토큰을 전달해야 하며, 이 토큰은 JWT 형태일 수 있습니다. 싱글 사인온(SSO)은 형식의 오버헤드가 적고 여러 도메인에서 쉽게 사용할 수 있다는 점 때문에 JWT를 널리 사용합니다.

• 정보 교환: JWT는 서명이 가능하므로 발신자가 본인이 맞는지 확인할 수 있으므로 당사자 간에 정보를 안전하게 전송하는 좋은 방법입니다. 또한 JWT의 구조를 통해 콘텐츠가 변조되지 않았는지 확인할 수 있습니다.

6. JWT의 보안 문제

JSON Web Token (JWT)은 웹 애플리케이션과 API에 널리 사용되고 있지만, 몇 가지 잠재적인 보안 취약점이 있습니다. 이러한 취약점을 이해하는 것은 JWT를 안전하게 사용하는 데 매우 중요합니다.

1. 서명 알고리즘의 취약성: JWT는 서명을 통해 데이터의 무결성을 보장합니다. 그러나, 사용하는 알고리즘이 취약하거나 구현에 오류가 있을 경우, 공격자가 토큰을 위조하거나 변조할 수 있습니다. 예를 들어, 'None' 알고리즘을 사용하는 경우 서명 검증이 생략될 수 있으며, 이는 보안 위험을 증가시킵니다.
2. 키 관리의 어려움: JWT는 비밀 키 또는 공개/개인 키 쌍을 사용해 서명합니다. 이 키들의 안전한 관리가 이루어지지 않을 경우, 토큰의 보안이 크게 저하될 수 있습니다. 키가 노출되거나 잘못 관리되면, 공격자가 유효한 토큰을 생성할 수 있게 됩니다.
3. 교차 사이트 스크립팅(XSS) 공격: 웹 애플리케이션에서 JWT를 클라이언트 측에 저장할 경우 (예: 쿠키, 로컬 스토리지), XSS 공격에 취약해질 수 있습니다. 공격자가 악의적인 스크립트를 주입하여 사용자의 JWT를 탈취할 수 있으며, 이를 통해 사용자의 세션을 탈취하거나 악의적인 행동을 할 수 있습니다.
4. 토큰 만료 관리: JWT는 만료 시간을 포함하고 있지만, 이를 적절히 관리하지 못하면 보안 문제가 발생할 수 있습니다. 오래된 토큰이 계속 사용되거나, 만료된 토큰이 재사용되는 경우 보안에 구멍이 생길 수 있습니다.
5. 안전하지 않은 토큰 전송: JWT는 텍스트 형태로 전송되므로, 전송 과정에서 보안이 중요합니다. HTTPS와 같은 안전한 연결을 사용하지 않으면, 중간자 공격을 통해 토큰이 노출될 수 있습니다.

이러한 잠재적 취약점을 고려하여, JWT를 사용할 때는 안전한 알고리즘 선택, 키의 안전한 관리, XSS 공격 방지를 위한 적절한 저장 방법 선택, 토큰의 만료 및 재사용 관리, 그리고 데이터 전송의 보안을 강화하는 것이 중요합니다.

7. JWT 관리 모범 사례

JWT (JSON Web Token) 관리의 모범 사례를 알고 있으면, 웹 애플리케이션과 API의 보안을 크게 향상시킬 수 있습니다. 여기에 안전한 JWT 사용을 위한 중요한 팁과 요령을 소개합니다.

1. 강력한 서명 알고리즘 사용: JWT의 보안은 대부분 서명에 의존합니다. HS256(최소한의 표준) 이상의 강력한 서명 알고리즘을 사용하세요. 가능하다면, RSA나 ECDSA 같은 비대칭 서명 알고리즘을 고려하는 것이 좋습니다.
2. 키 관리 강화: 비밀 키와 공개/개인 키 쌍은 안전하게 보관하고 정기적으로 갱신해야 합니다. 키가 유출되는 것을 방지하기 위해, 안전한 환경에 키를 저장하고 접근 권한을 엄격히 제한해야 합니다.
3. 최소한의 클레임 사용: JWT는 필요한 최소한의 정보만을 포함해야 합니다. 민감한 개인 정보는 토큰에 포함하지 않는 것이 좋습니다. 클레임은 명확하고, 간결해야 하며, 해석이 모호하지 않아야 합니다.
4. 토큰 만료 시간 설정: JWT는 만료 시간을 명시적으로 설정해야 합니다. 짧은 만료 시간은 보안을 강화하지만, 사용자 경험에 영향을 줄 수 있으므로 적절한 균형을 찾아야 합니다.
5. 토큰 취급 주의: 클라이언트 측에서 JWT를 저장할 때는 XSS 공격을 방지하기 위해 쿠키보다는 HTTPOnly와 Secure 플래그가 설정된 쿠키를 사용하거나, 가능한 한 서버 측에서 관리하는 것이 좋습니다.
6. 안전한 토큰 전송: JWT는 항상 HTTPS와 같은 안전한 채널을 통해 전송되어야 합니다. 이렇게 하면 중간자 공격에 대한 위험을 줄일 수 있습니다.

8.** 최신 웹 보안에서 JWT의 역할**

JWT는 웹 기반의 인증과 권한 부여 과정에서 핵심적인 요소로 자리 잡았습니다. 이 토큰은 안전하고 효율적인 방법으로 사용자 신원을 확인하고, 서버와 클라이언트 간의 정보 교환을 쉽게 만듭니다. 특히, 단일 페이지 애플리케이션(SPA), 모바일 애플리케이션, 그리고 마이크로서비스 아키텍처에서 JWT의 중요성은 더욱 부각됩니다.

보안 측면에서, JWT는 사용자 인증 정보를 안전하게 전송할 수 있게 해주며, 이를 통해 사용자와 시스템 간의 신뢰를 구축합니다. 또한, JWT는 확장성이 뛰어나고 다양한 플랫폼과 언어에서 쉽게 구현할 수 있어, 현대의 다양한 웹 애플리케이션 개발 요구사항을 충족시킵니다.

하지만, 모든 기술과 마찬가지로, JWT도 적절히 관리되고 보안이 유지되어야 합니다. 잘못된 관리나 구현은 보안 취약점을 초래할 수 있으므로, JWT를 사용할 때는 모범 사례를 따르는 것이 중요합니다.

요약하자면, JWT는 웹 보안의 현재와 미래에서 중요한 역할을 하고 있습니다. 그것은 간편하고, 유연하며, 강력한 인증 수단으로서 웹 애플리케이션의 보안을 강화하는 데 필수적인 요소입니다

참고 자료

JWT-introduce JWT-doc auth0-Tokens

JWT는 토큰 인증 방식 중 하나로, JSON 객체를 사용하여 토큰을 생성하고 인증하는 방식입니다. 이 방식은 상대적으로 가벼운 구조를 가지고 있어 많은 웹 서비스에서 사용되고 있습니다.

Bearer

Bearer는 '소지자' 또는 '착용자'라는 뜻이며, 인증 토큰을 전달할 때 사용되는 방식입니다. 이 방식은 토큰 소지자가 해당 토큰을 사용하여 인증을 받을 수 있다는 의미로 사용됩니다.

토큰의 이해와 필요성

웹 서비스에서 사용자 인증을 처리하기 위해 토큰을 사용하는 방식이 널리 채택되고 있습니다. 토큰은 사용자의 정보와 권한을 저장하고 있는 일종의 문자열로, 서버와 클라이언트 간의 통신에 사용됩니다.

토큰 인증 방식

토큰 인증 방식은 사용자 인증 정보를 토큰으로 변환하여 전달하는 방식입니다. 인증 토큰은 일종의 문자열로, 서버와 클라이언트 간의 통신에 사용됩니다.

JWT 구성요소

JWT는 세 가지 구성요소로 이루어져 있습니다: 헤더(header), 페이로드(payload), 시그니처(signature). 헤더에는 토큰의 유형과 알고리즘 정보가 포함되어 있으며, 페이로드에는 사용자 정보와 권한 등이 담겨 있습니다. 시그니처는 서버에서 생성되어 토큰의 유효성을 검증하는 데 사용됩니다.

JWT 동작 방식

사용자가 로그인 또는 회원가입을 요청합니다. 서버에서 사용자 정보를 확인한 후 JWT를 생성합니다. 생성된 JWT를 클라이언트에게 전달합니다. 클라이언트는 전달받은 JWT를 저장하고, 인증이 필요한 요청에 함께 보냅니다. 서버는 전달받은 JWT를 검증하여 사용자 인증을 확인합니다.

내보내는 요청에 토큰 첨부하기

요청후 토큰 저장하기

export const action = async ({request, params}) => {
  const mode = new URL(request.url).searchParams.get('mode') || 'login';

  if(mode !== 'login' && mode !== 'signup'){
    throw json({message: 'Invalid mode'}, {status: '422'});
  }

  const data = await request.formData();
  const authData = {
    email: data.get('email'),
    password: data.get('password'),
  }

  const response = await fetch(`http://localhost:8080/${mode}`,{
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(authData),
  });

  if(response.status === 422 || response.status === 401){
    return response;
  }

  if(!response.ok){
    throw json({message: 'Could not authenticate user.'}, {status: 500});
  }

  const resData = await response.json();
  const token = resData.token;

  localStorage.setItem('token', token);

  return redirect('/');

}

요청 후 토큰을 저장하는 과정에서는 사용자의 로그인 또는 회원가입 요청을 받고, 인증에 성공하면 토큰을 생성하여 로컬 스토리지에 저장합니다. 이 과정은 위 코드에서 확인할 수 있습니다.

요청시 토큰 보내기

export const action = async ({ params, request }) => {
  const eventId = params.eventId;
  const token = getAuthTokens();
  const response = await fetch('http://localhost:8080/events/' + eventId, {
    method: request.method,
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });

  if (!response.ok) {
    throw json(
      { message: 'Could not delete event.' },
      {
        status: 500,
      }
    );
  }
  return redirect('/events');
}

인증된 사용자가 특정 요청을 할 때, 예를 들어 이벤트를 삭제하고자 할 경우, 토큰을 함께 보내어 서버에서 사용자 인증을 확인합니다. 위 코드에서는 이벤트 삭제 요청에 토큰을 함께 보내는 과정을 확인할 수 있습니다.

사용자 로그아웃 처리

토큰제거

사용자 로그아웃을 처리하려면 먼저 사용자의 인증 토큰을 제거해야 합니다. 이를 위해 로그아웃 컴포넌트를 생성해봅시다.

로그아웃 컴포넌트 생성

import { redirect } from "react-router-dom";

export const action = () => {
  localStorage.removeItem('token');
  return redirect('/');
}

위 코드는 localStorage에 저장된 토큰을 제거한 뒤, 사용자를 홈페이지로 리다이렉트합니다.

인증상태에 따라 UI 상태 업데이트

auth 컴포넌트에 추가

export const getAuthTokens = () => {
  const token = localStorage.getItem('token');
  return token;
};

export const tokenLoader = () => {
  return getAuthTokens();
}

그리고 라우터 객체에 로더를 추가합니다.

라우터 객체에 추가

import { loader as tokenLoader } from './util/auth';
const router = createBrowserRouter([
  {
    path: '/',
    element: <RootLayout />,
    errorElement: <ErrorPage />,
    id: 'root',
    loader: tokenLoader,
    children: [
      { index: true, element: <HomePage /> },
        //...
    ],
  },
]);

위 코드는 loader()를 통해 데이터를 가져옵니다.

import { NavLink, Form, useRouteLoaderData } from "react-router-dom";

import classes from "./MainNavigation.module.css";
import NewsletterSignup from "./NewsletterSignup";

const MainNavigation = () => {
  const token = useRouteLoaderData("root");

  return (
    <header className={classes.header}>
      <nav>
        <ul className={classes.list}>
          <li>
            <NavLink to="/" className={({ isActive }) => (isActive ? classes.active : undefined)} end>
              Home
            </NavLink>
          </li>
          <li>
            <NavLink to="/events" className={({ isActive }) => (isActive ? classes.active : undefined)}>
              Events
            </NavLink>
          </li>
          <li>
            <NavLink to="/newsletter" className={({ isActive }) => (isActive ? classes.active : undefined)}>
              Newsletter
            </NavLink>
          </li>
          {!token && (
            <li>
              <NavLink to="/auth" className={({ isActive }) => (isActive ? classes.active : undefined)}>
                Authentication
              </NavLink>
            </li>
          )}
          {token && (
            <li>
              <Form action="/logout" method="post">
                <button>Logout</button>
              </Form>
            </li>
          )}
        </ul>
      </nav>
      <NewsletterSignup />
    </header>
  );
};

export default MainNavigation;

이제 인증 상태에 따라 사용자 인터페이스가 업데이트되어 로그아웃 버튼이 보이게 됩니다.

라우트 보호

리액트에서 라우트 보호는 사용자 인증을 확인하여 특정 페이지에 대한 접근 권한을 관리하는 것을 의미합니다. 이 글에서는 라우트 보호를 구현하는 방법에 대해 설명하겠습니다.

import { redirect } from 'react-router-dom';

export const getAuthTokens = () => {
  const token = localStorage.getItem('token');
  return token;
};

export const tokenLoader = () => {
  return getAuthTokens();
}

export const checkAuthLoader = () => {
  const token = getAuthTokens();

  if (!token) {
    return redirect('/login');
  }

  return null;
}

checkAuthLoader 함수는 토큰이 없을 경우 리다이렉트 처리를 해주는 함수입니다. 토큰이 없으면 로그인 페이지로 리다이렉트합니다.

import { tokenLoader, checkAuthLoader } from "./util/auth";

const router = createBrowserRouter([
  {
    path: "/",
    element: <RootLayout />,
    errorElement: <ErrorPage />,
    id: "root",
    loader: tokenLoader,
    children: [
      { index: true, element: <HomePage /> },
      {
        path: "events",
        element: <EventsRootLayout />,
        children: [
            //..
          {
            path: ":eventId",
            id: "event-detail",
            loader: eventDetailLoader,
            children: [
              {
                index: true,
                element: <EventDetailPage />,
                action: deleteEventAction,
              },
              {
                path: "edit",
                element: <EditEventPage />,
                action: manipulateEventAction,
                loader: checkAuthLoader,
              },
            ],
          },
          {
            path: "new",
            element: <NewEventPage />,
            action: manipulateEventAction,
            loader: checkAuthLoader,
          },
        ],
      },
     //..
    ],
  },
]);

checkAuthLoader를 사용하여 라우트 보호를 적용합니다.

자동 로그아웃

인터넷에서 로그인 한 후, 일정 시간 동안 활동하지 않으면 자동으로 로그아웃되는 기능은 매우 중요합니다. 이것은 사용자의 개인 정보와 보안을 보호하며, 불필요한 서버 부하를 줄일 수 있습니다. React에서는 이러한 자동 로그아웃 기능을 구현하는 데 useEffect를 사용할 수 있습니다. 이 기능을 구현하는 방법에 대해 알아보겠습니다.

import { Outlet, useLoaderData, useNavigation, useSubmit } from "react-router-dom";

import MainNavigation from "../components/MainNavigation";
import { useEffect } from "react";

function RootLayout() {
  // const navigation = useNavigation();
  const token = useLoaderData("root");
  const submit = useSubmit();

  useEffect(() => {
    if (!token) {
      return;
    }

    setTimeout(() => {
      submit(null, { action: "/logout", method: "post" });
    }, 1 * 60 * 60 * 1000);
  }, [token, submit]);

  return (
    <>
      <MainNavigation />
      <main>
        {/* {navigation.state === 'loading' && <p>Loading...</p>} */}
        <Outlet />
      </main>
    </>
  );
}

export default RootLayout;

위 코드에서는 RootLayout 컴포넌트에서 useEffect를 사용하여 토큰의 만료 시간을 설정합니다. 코드를 자세히 살펴보면, 토큰이 존재하는 경우 setTimeout 함수를 사용하여 1시간 후에 로그아웃 요청을 전송합니다.

토큰만료 개선

토큰 만료 시간을 추가하여 사용자 인증을 더 안전하게 만드는 방법에 대해 알아보겠습니다. 이를 위해 Authentication 컴포넌트와 관련 기능을 수정하고, 만료 시간을 이용해 자동 로그아웃 기능을 구현합니다.

Authentication 컴포넌트에서 token expiration 추가

먼저, Authentication 컴포넌트에 토큰 만료 시간을 추가해봅시다.

  localStorage.setItem('token', token);
  const expiration = new Date();
  expiration.setHours(expiration.getHours() + 1);
  localStorage.setItem('expiration', expiration.toISOString());

위 코드를 사용하여 토큰과 함께 만료 시간을 저장합니다.

auth 컴포넌트 수정

auth 컴포넌트를 수정하여 expiration을 사용하도록 합니다.

import { redirect } from "react-router-dom";

export const getTokenDuration = () => {
  const storedExpirationDate = localStorage.getItem("expiration");
  const expirationDate = new Date(storedExpirationDate);
  const now = new Date();
  const duration = expirationDate.getTime() - now.getTime();
  return duration;
};

export const getAuthTokens = () => {
  const token = localStorage.getItem("token");

  if(!token) {
    return null;
  }

  const tokenDuration = getTokenDuration();

  if (tokenDuration <= 0) {
    return "EXPIRED";
  }

  return token;
};

export const tokenLoader = () => {
  return getAuthTokens();
};

export const checkAuthLoader = () => {
  const token = getAuthTokens();

  if (!token) {
    return redirect("/login");
  }

  return null;
};

위 코드에서는 만료 시간을 계산하는 getTokenDuration() 함수를 사용하여 토큰이 만료되었는지 확인합니다.

root 컴포넌트에서 useEffect 수정

root 컴포넌트의 useEffect를 수정하여 expiration을 사용하도록 합니다.

  useEffect(() => {
    if (!token) {
      return;
    }

    if(token === "EXPIRED") {
      submit(null, { action: "/logout", method: "post" });
    }

    const tokenDuration = getTokenDuration();

    setTimeout(() => {
      submit(null, { action: "/logout", method: "post" });
    }, tokenDuration);
  }, [token, submit]);

이 코드를 사용하면 토큰이 만료되면 자동으로 로그아웃되도록 설정할 수 있습니다.

logout 컴포넌트에서 expiration 제거 추가

마지막으로, 로그아웃 컴포넌트에서 expiration을 제거하도록 수정합니다.

import { redirect } from "react-router-dom";

export const action = () => {
  localStorage.removeItem('token');
  localStorage.removeItem('expiration');
  return redirect('/');
}

이렇게 토큰 만료 시간을 추가하고 관련 기능을 수정하면 사용자 인증을 더 안전하게 만들 수 있습니다. 만료 시간을 이용해 자동으로 로그아웃되도록 설정하여 편리하게 사용할 수 있습니다.

인증작업 생성을 위한 코드 설명

AuthForm 컴포넌트와 action 함수

인증 작업 생성을 위한 코드는 주로 AuthForm 컴포넌트와 action 함수를 포함합니다. AuthForm 컴포넌트는 사용자 인터페이스(UI)를 담당하며, action 함수는 인증 작업에 대한 로직을 처리합니다.

코드의 주요 부분에 대한 설명

1. AuthForm 컴포넌트에서, 이메일과 비밀번호를 입력 받는 폼을 구성합니다.
2. action 함수에서, 폼 데이터를 추출하고 서버로 전송하여 인증 작업을 진행합니다.
3. 서버로부터 인증 결과를 받아 처리한 후, 필요한 작업을 수행합니다.

   import AuthForm from '../components/AuthForm';
   import { json, redirect } from 'react-router-dom';
   

function AuthenticationPage() { return ; }

export default AuthenticationPage;

export const action = async ({request, params}) => { const mode = new URL(request.url).searchParams.get('mode') || 'login';

if(mode !== 'login' && mode !== 'signup'){ throw json({message: 'Invalid mode'}, {status: '422'}); }

const data = await request.formData(); const authData = { email: data.get('email'), password: data.get('password'), }

const response = await fetch(http://localhost:8080/${mode},{ method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(authData), });

if(response.status === 422 || response.status === 401){ return response; }

if(!response.ok){ throw json({message: 'Could not authenticate user.'}, {status: 500}); }

return redirect('/');

}

## 사용자 유효성 검증을 위한 코드 설명
### AuthForm 함수와 React hooks 사용
사용자 유효성 검증을 위한 코드는 AuthForm 함수 내에서 처리됩니다. 이 함수는 React hooks를 사용하여 검증 결과를 저장하고, 검증 에러와 메시지를 출력합니다.
### 검증 에러와 메시지 출력
검증 에러와 메시지는 `<ul>` 태그와 `<p>` 태그를 사용하여 출력합니다. 각 에러는 `<li>` 태그로 나타내며, 전체 메시지는 `<p>` 태그 안에 표시됩니다.
### 이메일과 비밀번호 입력폼
이메일과 비밀번호를 입력받기 위해 `<input>` 태그를 사용합니다. 각각의 태그에는 id, type, name, 그리고 required 속성이 포함되어 있습니다.
### 로그인 및 회원가입 버튼 구현
로그인 및 회원가입 버튼은 `<Link>` 컴포넌트와 `<button>` 태그를 사용하여 구현합니다. `<Link>` 컴포넌트는 현재 페이지의 mode에 따라 로그인 또는 회원가입 페이지로 이동하며, `<button>` 태그는 폼 제출을 담당합니다
```javascript
import { React } from "react";
import { Form, Link, useSearchParams, useActionData, useNavigation } from "react-router-dom";

import classes from "./AuthForm.module.css";

function AuthForm() {
  const data = useActionData();
  const navigation = useNavigation();

  const [searchParams] = useSearchParams();

  const isLogin = searchParams.get("mode") === "login";
  const isSubmmiting = navigation.state === "submitting";

  return (
    <>
      <Form method="post" className={classes.form}>
        <h1>{isLogin ? "Log in" : "Create a new user"}</h1>
        {data && data.errors && (
          <ul>
            {Object.values(data.errors).map((error, index) => (
              <li key={index}>{error}</li>
            ))}
          </ul>
        )}
        {data && data.message && <p>{data.message}</p>}
        <p>
          <label htmlFor="email">Email</label>
          <input id="email" type="email" name="email" required />
        </p>
        <p>
          <label htmlFor="image">Password</label>
          <input id="password" type="password" name="password" required />
        </p>
        <div className={classes.actions}>
          <Link to={`?mode=${isLogin ? "signup" : "login"}`}>{isLogin ? "Create new user" : "Login"}</Link>
          <button disabled={isSubmmiting}>{isSubmmiting ? "Submitting" : "Save"}</button>
        </div>
      </Form>
    </>
  );
}

export default AuthForm;

서버와 통신

서버와 통신하는 과정은 action 함수에서 처리됩니다. fetch 함수를 사용하여 서버와 통신하며, 서버로부터 받은 응답을 처리한 후 필요한 작업을 수행합니다.

인증 방식

Servet-side session

서버-사이드 세션은 인증을 위한 가장 전통적인 방법 중 하나입니다. 이 방식에서는 사용자가 로그인을 하면, 서버는 해당 사용자에 대한 세션 정보를 생성합니다. 이 세션 정보는 서버에 저장되며, 사용자가 웹 사이트 내에서 다른 페이지로 이동하거나 어떤 작업을 수행할 때마다 이 세션 정보가 사용됩니다.

서버-사이트 세션은 매우 안전한 방식이지만, 최근에는 react와 같은 프레임워크에서 맞지 않는 경우가 있습니다. 이는 react와 같은 프레임워크에서는 세션 정보를 다루기가 어렵기 때문입니다.

Authentication Tokens

Authentication 토큰 방식은 인증을 위한 현재 가장 인기 있는 방법 중 하나입니다. 이 방식에서는 사용자가 로그인을 하면, 서버는 해당 사용자에 대한 토큰 정보를 생성합니다. 이 토큰 정보는 사용자의 브라우저에 저장되며, 사용자가 다른 페이지로 이동하거나 어떤 작업을 수행할 때마다 이 토큰 정보가 사용됩니다.

Authentication 토큰 방식은 매우 유연하며, react와 같은 프레임워크에서도 잘 작동합니다. 또한, 이 방식은 서버-사이트 세션 방식보다 더욱 안전하다고 알려져 있습니다.

인증의 중요성

인증은 현대의 디지털 시대에서 굉장히 중요한 개념입니다. 이번 글에서는 인증의 원리와 인증 방식에 대해 알아보았습니다. 서버-사이트 세션 방식은 전통적이고 안전하지만, react와 같은 프레임워크에서는 맞지 않는 경우가 있습니다. Authentication 토큰 방식은 매우 유연하며, react와 같은 프레임워크에서도 잘 작동합니다. 또한, 이 방식은 서버-사이트 세션 방식보다 더욱 안전하다고 알려져 있습니다.