najang 님의 블로그

6월 회고 — 인증부터 옷장 도메인까지

najang — Wed, 10 Jun 2026 21:33:12 +0900

들어가기 전에 — OMO를 왜 만들게 됐나

매일 아침 출근 준비할 때 날씨 앱부터 켰다. 정확히는 오늘 기온이 궁금해서가 아니라, 뭘 입어야 할지 정하기 위해서였다. 근데 회사에서 팀원들이랑 얘기해보니 다들 똑같았다. 아침마다 날씨 앱 켜서 숫자 보고, 그 숫자를 머릿속으로 "그래서 오늘 뭐 입지"로 한 번 더 변환하는 과정을 매일 반복하고 있었다.

그래서 처음 든 생각은 단순했다. 그냥 매일 아침 정해진 시간에 "오늘 이렇게 입으세요"라고 알림으로 알려주는 앱이 있으면 그 변환 과정을 안 거쳐도 되지 않을까 하는 거였다.

근데 조금 더 얘기하다 보니 다른 문제가 보였다. 같은 18도라도 누구는 가디건만 걸치고 나가고, 누구는 그 위에 자켓까지 입어야 한다. 추위나 더위를 타는 정도가 사람마다 다르기 때문이다. 단순히 "오늘 기온은 18도니까 이 옷"이라고 일괄로 추천하면 절반은 맞고 절반은 안 맞는 추천이 될 거였다.

그래서 거기에 "개인화"를 더하기로 했다. 오늘 추천한 옷차림이 그 사람한테 어땠는지(추웠다/적당했다/더웠다) 다음 날 한 번 물어보고, 그 피드백이 쌓일수록 그 사람의 체감 온도에 맞춰 추천이 점점 보정되도록 만드는 것이다. OMO는 이렇게 "매일 아침 옷차림 고민을 줄여주는 알림 + 그 사람한테 맞춰지는 추천"이라는 두 축으로 시작한 프로젝트다.

신규 유저는 당연히 피드백 이력이 없으니 추천이 동작할 기반이 없다. 그래서 온보딩에서 "지금 가지고 있는 옷"과 "평소에 추위/더위를 얼마나 타는지"를 미리 받아두기로 했는데, 이번 달 작업의 상당 부분(옷장 도메인)이 바로 이 시작점을 만드는 과정이었다.

이번 달엔 OMO 앱의 핵심 골격을 거의 다 만들었다. JWT 인증, 닉네임 온보딩, 그리고 옷장(wardrobe) 도메인까지. PR로 치면 두 개를 머지했고(#3, #4), 마이페이지 옷장 수정 API(OMO-63)는 지금 작업 중이다. 작업량 자체보다 중간에 만난 삽질들이 더 기억에 남아서, 그걸 위주로 정리해본다.

1. 인증 인터셉터를 만들면서 — Filter 말고 Interceptor를 쓴 이유

JWT 인증을 붙일 때 가장 먼저 고민한 게 "Filter로 할까, Interceptor로 할까"였다. 둘 다 요청을 가로채서 검증할 수 있는데, 차이를 제대로 몰라서 처음엔 그냥 익숙한 Filter로 시작하려 했다.

근데 우리 프로젝트는 모든 예외를 CoreException + @ControllerAdvice로 처리하고 있다. 그런데 Filter는 DispatcherServlet 앞단이라 @ControllerAdvice가 못 잡는다. Filter에서 던진 예외는 결국 톰캣 기본 에러 페이지로 가버린다. 반면 Interceptor는 DispatcherServlet 안에서 동작해서, preHandle()에서 던진 CoreException도 컨트롤러에서 던진 것과 똑같이 ApiControllerAdvice가 받아서 우리 응답 포맷(ApiResponse)으로 변환해준다.

String token = authHeader.substring(BEARER_PREFIX.length());
try {
    Long userId = jwtProvider.parseUserId(token);
    request.setAttribute(USER_ID_ATTRIBUTE, userId);
    return true;
} catch (ExpiredJwtException e) {
    throw new CoreException(ErrorType.TOKEN_EXPIRED, "만료된 토큰입니다.");
} catch (JwtException e) {
    throw new CoreException(ErrorType.UNAUTHENTICATED, "유효하지 않은 토큰입니다.");
}

여기서 또 하나 걸린 게 catch 순서였다. JJWT의 ExpiredJwtException은 JwtException을 상속한다. 처음에 순서를 반대로 써서, 만료된 토큰도 그냥 UNAUTHENTICATED로 떨어지는 버그가 있었다. 만료(TOKEN_EXPIRED)와 변조(UNAUTHENTICATED)는 클라이언트 입장에서 완전히 다른 처리다 — 만료면 리프레시 토큰으로 재시도하면 되지만, 변조면 그냥 로그인 화면으로 보내야 한다. 자식 예외를 먼저 잡아야 한다는 당연한 원칙인데, 실제로 안 걸려봤으면 계속 모르고 넘어갔을 것 같다.

인증된 userId를 컨트롤러에 넘기는 부분도 재밌었다. request.getAttribute("userId")를 컨트롤러마다 직접 캐스팅해서 쓰면 코드가 지저분해질 게 뻔해서, @AuthUser 커스텀 어노테이션 + HandlerMethodArgumentResolver로 뺐다.

public ApiResponse<?> getProfile(@AuthUser Long userId) { ... }

이렇게 해두니까 컨트롤러는 "인증된 유저 아이디가 필요하다"는 의도만 선언하면 되고, attribute 키 이름이나 캐스팅 같은 디테일은 리졸버 한 곳에만 있다.

2. ErrorType, "같은 상태코드인데 왜 나눠?"

에러 타입을 설계하면서 계속 스스로 물어본 질문이 "이거 굳이 나눠야 하나?"였다. 답은 의외로 단순했다 — 클라이언트가 받았을 때 다른 행동을 해야 하면 나눈다.

TOKEN_EXPIRED vs UNAUTHENTICATED: 둘 다 401이지만, 전자는 토큰 갱신을 시도해야 하고 후자는 바로 로그인 화면으로 보내야 한다.
BAD_REQUEST vs INVALID_INPUT: 둘 다 400이지만, 전자는 "개발자가 API 스펙을 잘못 맞춘 것"에 가깝고 후자는 "사용자가 입력을 잘못한 것"이다.
옷장 API에서는 WARDROBE_NOT_FOUND(404)도 새로 추가했다. 옷장이 아예 없는 것(온보딩 미완료)과 옷장은 있는데 아이템을 0개 선택한 것은 의미가 다르다. 빈 배열로 두 경우를 퉁치면 클라이언트가 "이 유저는 온보딩을 안 끝냈구나"를 알 방법이 없다.

반대로 안 만든 에러 타입도 있다. 추천 결과가 없을 때 404를 내려주는 안을 처음엔 생각했는데, 곰곰이 보니 사용자가 앱을 처음 켰을 때 에러 화면을 보게 되는 최악의 시나리오였다. 그래서 "배치가 실패했으면 그 자리에서 날씨 API를 불러서라도 추천을 만들어 보여준다"는 fallback 전략으로 바꾸고 에러 타입 자체를 없앴다. 에러를 잘 설계하는 것만큼, 어떤 상황을 아예 에러로 만들지 않는 것도 중요하다는 걸 느꼈다.

3. 옷장 도메인 — `@ElementCollection`에서 `@ManyToMany`로 갈아엎은 이야기

이번 달에 가장 시간을 많이 쓴 부분이다. 처음에 옷장 데이터를 설계할 때는 "유저가 어떤 카테고리(상의/아우터/바지...)의 옷을 가지고 있는지"만 저장하면 될 줄 알고 @ElementCollection<ClothingCategory>로 시작했다.

근데 추천 로직을 같이 고민하다 보니 "반팔 티셔츠는 있는데 긴팔은 없다" 같은 아이템 단위 정보가 필요하다는 게 명확해졌다. 카테고리 수준 정보로는 추천이 너무 뭉뚱그려진다. 그래서 ClothingItem이라는 카탈로그 엔티티를 새로 만들고, UserWardrobe와 @ManyToMany로 연결하는 구조로 갈아엎었다.

@ManyToMany(fetch = FetchType.LAZY)
@JoinTable(
    name = "user_wardrobe_item",
    joinColumns = @JoinColumn(name = "wardrobe_id"),
    inverseJoinColumns = @JoinColumn(name = "item_id")
)
private Set<ClothingItem> items = new HashSet<>();

public void updateItems(Set<ClothingItem> items) {
    this.items.clear();
    this.items.addAll(items);
}

여기서 처음엔 this.items = new HashSet<>(items)처럼 통째로 갈아끼우려고 했다. 컴파일도 되고 로직상 문제도 없어 보였는데, 실제로 돌려보니 DB에 반영이 안 됐다. 알고 보니 Hibernate가 추적하고 있던 영속 컬렉션 인스턴스를 새 HashSet으로 바꿔치기하면 dirty checking 대상에서 빠진다고 한다. clear()로 기존 걸 비우고 addAll()로 새로 채워야 같은 인스턴스를 유지하면서 변경을 감지한다 — JPA를 쓰면서 "참조를 바꾸는 것"과 "내용을 바꾸는 것"의 차이를 처음으로 체감한 순간이었다.

그리고 system_key라는 개념도 새로 도입했다. Flutter 화면에서 쓰는 아이템 ID('short-tee', 'padding')와 서버 DB의 PK(숫자)를 분리한 것이다. PK는 배포 환경마다 달라질 수 있는 내부 값이라, API 계약에는 코드로 관리되는 system_key만 노출한다. 대신 이 방식의 단점도 바로 보였다 — Flutter 쪽 하드코딩 목록과 서버 시드 데이터가 코드 레벨에서만 동기화된다. 한쪽만 바뀌면 400 에러가 나는데, CI에서는 안 잡힌다.

그래서 이 빚은 결국 같은 달 안에 갚았다. 방법은 단순했다 — 옷 목록을 Flutter가 들고 있지 말고, 서버가 `GET /api/v1/clothing-items`로 내려주면 된다. 목록이 한 벌만 존재하면 어긋날 일도 없고, DB에서 아이템을 지우면 화면에서도 바로 사라진다. 근데 막상 옮기려니 걸리는 게 하나 있었다. 화면에서 옷을 묶어 보여주는 그룹과 추천 로직이 쓰는 카테고리(`ClothingCategory`)가 1:1이 아니었다. `PANTS`랑 `SKIRT`는 화면에선 그냥 "하의" 한 칸이고, 반대로 `ACCESSORY`는 "모자"랑 "스카프/목도리" 두 칸으로 갈라진다. `category`만 내려주면 볼캡이랑 스카프를 다른 칸에 그릴 수가 없다 — 둘 다 `ACCESSORY`니까. 그래서 화면 그룹을 `display_group` 컬럼으로 따로 뒀다.

여기서 한 번 더 고민한 게 "이 그룹 매핑을 어디에 둘까"였다. 그냥 Flutter에 'systemKey → 그룹' 표를 상수로 남기는 것도 방법이었는데, 그러면 새 액세서리를 추가할 때마다 "이건 모자야 스카프야"를 또 Flutter가 알아야 해서 하드코딩 문제가 절반만 풀린다. 그래서 그룹 소속까지 DB가 쥐게 했다. Flutter엔 그룹의 "생긴 것"(라벨·아이콘·색)만 남기고, 어떤 아이템이 어느 그룹인지는 DB가 정한다. 물론 공짜는 아니라서, 이제 목록이 네트워크에 의존하니 화면마다 로딩/에러 상태를 처리해야 하고 오프라인이면 "다시 시도" 버튼만 남는다. 그래도 "코드 레벨 동기화"가 한 달 만에 "DB가 유일한 출처"로 바뀐 건, 통합 테스트로 땜질하려던 처음 생각보다 훨씬 마음이 편하다.

4. 테스트 격리 버그 — "Duplicate entry" 에러를 만난 날

옷장 기능 테스트를 추가하다가 갑자기 Duplicate entry 에러를 만났다. 분명 각 테스트가 끝나면 DatabaseCleanUp이 모든 테이블을 TRUNCATE하는데, 왜 이전 테스트의 데이터가 남아있는 걸까 한참 헤맸다.

원인은 user_wardrobe_item이라는 조인 테이블이었다. DatabaseCleanUp은 JPA 메타모델에서 @Entity가 붙은 클래스들을 찾아서 그 테이블들을 비운다. 그런데 @ManyToMany + @JoinTable로만 존재하는 조인 테이블은 @Entity가 아니기 때문에 메타모델에 안 잡힌다. 그래서 테스트 A가 만든 (wardrobe_id=1, item_id=1) 행이 테스트 B까지 살아남아서 PK 충돌이 난 것이었다.

해결은 reflection으로 각 엔티티 필드의 @JoinTable 어노테이션을 추가로 훑어서 테이블 이름을 수집하는 것. 한 줄짜리 원인을 찾는 데 꽤 오래 걸렸지만, 덕분에 앞으로 새로운 @ManyToMany가 추가돼도 자동으로 정리 대상에 들어가게 됐다.

for (Field field : type.getDeclaredFields()) {
    JoinTable joinTable = field.getAnnotation(JoinTable.class);
    if (joinTable != null && !joinTable.name().isBlank()) {
        names.add(joinTable.name());
    }
}

5. 같은 "재호출 가능한 API"인데 정책이 다르다

옷장 설정(setupWardrobe)과 체감 온도 초기화(initTempProfile)는 둘 다 "재호출 가능한 멱등 API"라는 공통점이 있는데, 재호출했을 때 동작은 정반대다.

옷장: 다시 호출하면 기존 아이템을 싹 비우고 새 목록으로 교체한다. 옷은 사고 버리고 하면서 계속 바뀌는 게 자연스러우니까.
체감 온도: 다시 호출해도 이미 값이 있으면 무시한다. 온보딩에서 받은 초기값은 어디까지나 "출발점"이고, 그 이후로는 사용자의 착용 피드백으로만 점진적으로 보정되어야 한다. 사용자가 설문을 다시 본다고 그동안 쌓인 학습 데이터를 덮어써버리면 안 된다.

// 옷장: 있으면 교체
userWardrobeRepository.findByUser(user)
    .ifPresentOrElse(
        wardrobe -> wardrobe.updateItems(items),
        () -> userWardrobeRepository.save(UserWardrobe.create(user, items))
    );

// 체감 온도: 있으면 무시
userTempProfileRepository.findByUser(user)
    .ifPresentOrElse(
        profile -> {},
        () -> userTempProfileRepository.save(UserTempProfile.of(user, tempOffset, 0))
    );

코드만 보면 ifPresentOrElse의 두 분기를 어떻게 채우느냐 차이밖에 없다. 근데 이 한 줄 차이가 "이 데이터는 사용자가 언제든 바꿀 수 있는 현재 상태인가, 아니면 시간에 따라 누적되는 학습 데이터인가"라는 도메인 판단을 그대로 코드로 옮긴 거라는 걸 나중에 깨달았다. 비슷해 보이는 upsert 로직도 도메인 의미를 먼저 묻고 분기를 정해야 한다는 걸 배웠다.

6. PATCH를 만들었는데 새 로직이 하나도 없다

지금 작업 중인 마이페이지 옷장 수정 API(OMO-63) 얘기다. "옷장 수정"이라고 하면 뭔가 새 검증 로직이 필요할 것 같은데, 막상 들여다보니 온보딩 때 만든 setupWardrobe()의 "있으면 교체, 없으면 생성" 로직과 요구사항이 100% 동일했다. 그래서 그냥 위임만 했다.

public void updateWardrobe(Long userId, List<String> itemKeys) {
    setupWardrobe(userId, itemKeys);
}

처음엔 "이래도 되나, PATCH인데 너무 성의 없는 거 아닌가" 싶었는데, 다시 생각해보면 "옷장을 설정한다"와 "옷장을 수정한다"가 도메인적으로 똑같은 동작(현재 보유 의류 전체 교체)이라면, 억지로 다른 로직을 만드는 게 오히려 두 엔드포인트가 미묘하게 어긋날 위험만 키운다. 다만 이 선택에는 빚이 하나 남는다 — Flutter는 아직 이 PATCH를 안 쓰고 기존 POST를 그대로 재사용하고 있어서, 지금 PATCH 엔드포인트는 API 문서상으로만 존재하는 죽은 경로다. REST 시맨틱을 깔끔하게 정리할지, 그냥 이대로 둘지는 다음에 한 번 더 얘기해봐야 할 것 같다.

GET 응답에서 옷장이 없을 때 빈 배열이 아니라 404를 내려주기로 한 것도 같은 맥락이다. 옷장 row 자체가 없다는 건 "온보딩을 아직 안 끝냈다"는 뜻인데, 이걸 빈 배열로 내려주면 "옷장은 있는데 아무것도 안 골랐다"와 구분이 안 된다. Flutter 쪽에서는 이 404를 그냥 "빈 선택 상태로 시작"으로 처리하면 되니, 에러 종류를 세분화하기보다 케이스를 단순하게 합쳤다.

이번 달 회고

Spring Boot 4.x로 올라오면서 @RestClientTest, @MockBean이 사라진 영향을 꽤 많이 받았다. RestClient.Builder를 생성자로 주입받게 클라이언트를 설계해야 MockRestServiceServer로 테스트할 수 있다는 걸 이번에 처음 알았는데, "테스트 가능한 구조"가 결국 설계에도 영향을 준다는 걸 체감했다.
같은 맥락에서 RestClient.Builder 빈이 자동 등록되지 않아서 서버가 아예 안 뜨는 사고도 있었다. 로컬에서 빌드는 되는데 기동이 안 되는 류의 문제는 항상 설정 쪽을 의심하게 된다.
다음 달엔 Flutter ↔ 서버 카탈로그 동기화 문제, JWT 토큰 무효화(로그아웃 시 블랙리스트), Apple JWKS 캐싱처럼 "지금은 괜찮지만 트래픽이 늘면 문제될" 항목들을 백로그로 옮겨두고 우선순위를 다시 매겨야겠다.

Docker Volume — 개념 + MySQL로 검증하기

najang — Wed, 13 May 2026 23:36:13 +0900

컨테이너가 가진 근본적인 문제

Docker는 프로그램을 업데이트할 때 기존 컨테이너를 수정하지 않는다. 새로운 컨테이너를 만들어 통째로 교체하는 방식으로 동작한다.

문제는 여기서 발생한다. 컨테이너를 교체하면 기존 컨테이너 내부에 저장되어 있던 데이터도 함께 삭제된다. MySQL 컨테이너였다면 DB에 쌓아둔 데이터까지 전부 날아간다.

데이터가 삭제되면 안 되는 상황이라면 볼륨(Volume) 을 활용해야 한다.

Docker Volume이란?

볼륨(Volume) 은 컨테이너의 데이터를 영속적으로 보존하기 위한 방법이다. 컨테이너 자체의 저장 공간을 쓰는 대신, 호스트 컴퓨터의 저장 공간을 컨테이너와 공유하는 형태로 동작한다.

컨테이너가 삭제되더라도 데이터는 호스트에 그대로 남기 때문에, 새 컨테이너를 띄울 때 같은 경로를 연결하면 데이터가 이어진다.

볼륨을 사용하는 명령어

# docker run -v [호스트 디렉토리 절대경로]:[컨테이너 디렉토리 절대경로] 이미지명[:태그명]
$ docker run -v /host/data:/container/data nginx

동작 방식은 호스트 경로의 존재 여부에 따라 달라진다.

경로가 이미 존재하는 경우 — 호스트 디렉토리가 컨테이너 디렉토리를 덮어씌운다.

경로가 존재하지 않는 경우 — 호스트에 디렉토리를 새로 만들고, 컨테이너 내부의 파일들을 호스트로 복사해온다.

[실습] MySQL 컨테이너 띄워보기

1단계 — 볼륨 없이 띄우기 (데이터가 사라지는 문제 직접 확인)

먼저 볼륨 없이 MySQL을 실행해서 컨테이너 교체 시 데이터가 어떻게 되는지 눈으로 확인해보자.

mysql - Official Image | Docker Hub

$ docker run -e MYSQL_ROOT_PASSWORD=password123 -p 3306:3306 -d mysql

-e 옵션은 컨테이너의 환경 변수를 설정한다. MySQL 공식 이미지는 MYSQL_ROOT_PASSWORD 환경 변수가 반드시 설정되어 있어야 정상 실행된다. 아래 명령어로 컨테이너 내부에서 직접 확인할 수 있다.

$ docker exec -it [MySQL 컨테이너 ID] bash
$ echo $MYSQL_ROOT_PASSWORD  # 특정 환경 변수 값 출력
$ export                      # 설정된 모든 환경 변수 출력

컨테이너가 잘 떴는지 확인한다.

$ docker ps
$ docker logs [컨테이너 ID]

MySQL에 접속해서 데이터베이스 만들기

$ docker exec -it [MySQL 컨테이너 ID] bash
$ mysql -u root -p

mysql> show databases;
mysql> create database mydb;
mysql> show databases;     # mydb가 생성된 걸 확인

컨테이너 삭제 후 재생성 — 데이터 확인

# 컨테이너 종료 및 삭제
$ docker stop [MySQL 컨테이너 ID]
$ docker rm [MySQL 컨테이너 ID]

# 컨테이너 재생성
$ docker run -e MYSQL_ROOT_PASSWORD=password123 -p 3306:3306 -d mysql
$ docker exec -it [MySQL 컨테이너 ID] bash
$ mysql -u root -p

mysql> show databases;  # mydb가 사라진 걸 확인할 수 있다

아까 만들었던 mydb가 사라진다. 볼륨 없이 운영하면 컨테이너를 교체할 때마다 데이터가 초기화된다는 걸 직접 확인한 것이다.

2단계 — 볼륨을 적용해서 데이터 유지하기

이제 볼륨을 연결해서 같은 실습을 반복해보자.

$ cd /Users/jaeseong/Documents/Develop
$ mkdir docker-mysql  # MySQL 데이터를 저장할 폴더 생성

⚠️ mysql_data 디렉토리는 미리 만들어두면 안 된다. 경로가 이미 존재하면 빈 호스트 디렉토리가 컨테이너의 /var/lib/mysql을 덮어씌워버려, MySQL이 정상적으로 초기화되지 않는다. 경로가 없어야 컨테이너 내부 파일이 호스트로 복사된다.

$ docker run \
  -e MYSQL_ROOT_PASSWORD=password123 \
  -p 3306:3306 \
  -v /Users/jaeseong/Documents/Develop/docker-mysql/mysql_data:/var/lib/mysql \
  -d mysql

Windows 환경이라면 경로 형식이 다를 수 있다.

$ docker run -e MYSQL_ROOT_PASSWORD=password123 -p 3306:3306 -v C:/Users/jaeseong/js-mysql:/var/lib/mysql -d mysql

pwd 명령어로 현재 절대 경로를 확인한 뒤 입력하자.

MySQL에 접속해서 데이터베이스 만들기

$ docker exec -it [MySQL 컨테이너 ID] bash
$ mysql -u root -p

mysql> show databases;
mysql> create database mydb;
mysql> show databases;

컨테이너 삭제 후 재생성 — 데이터 유지 확인

# 컨테이너 종료 및 삭제
$ docker stop [MySQL 컨테이너 ID]
$ docker rm [MySQL 컨테이너 ID]

# 동일한 볼륨 경로로 재생성
$ docker run \
  -e MYSQL_ROOT_PASSWORD=password123 \
  -p 3306:3306 \
  -v /Users/jaeseong/Documents/Develop/docker-mysql/mysql_data:/var/lib/mysql \
  -d mysql

$ docker exec -it [MySQL 컨테이너 ID] bash
$ mysql -u root -p

mysql> show databases;  # mydb가 그대로 존재하는 걸 확인할 수 있다

주의 — 볼륨에 비밀번호 정보가 저장된다

볼륨이 연결된 상태에서 MYSQL_ROOT_PASSWORD를 바꿔 컨테이너를 새로 띄워도 비밀번호가 바뀌지 않는다.

$ docker stop [MySQL 컨테이너 ID]
$ docker rm [MySQL 컨테이너 ID]

# 비밀번호를 변경해서 재생성
$ docker run -e MYSQL_ROOT_PASSWORD=pwd1234 -p 3306:3306 \
  -v /Users/jaeseong/Documents/Develop/docker-mysql/mysql_data:/var/lib/mysql \
  -d mysql

$ docker exec -it [MySQL 컨테이너 ID] bash
$ mysql -u root -p  # 새 비밀번호로 접속이 안 된다

볼륨 경로에 이미 기존 비밀번호 정보가 저장되어 있기 때문이다. 비밀번호를 바꾸고 싶다면 볼륨 디렉토리를 삭제하거나 비운 뒤 새로 시작해야 한다.

컨테이너 내부 접속 + Redis 실습

najang — Thu, 30 Apr 2026 22:01:28 +0900

컨테이너 내부에 접속하기 — docker exec -it

앞서 컨테이너를 미니 컴퓨터라고 표현했다. 즉, 각 컨테이너는 자기만의 OS, 저장 공간, 프로그램 환경을 가지고 있다. 그렇다면 그 내부에 직접 들어가서 파일을 확인하거나 명령어를 실행할 수도 있어야 한다. 이때 사용하는 명령어가 exec -it다.

# docker exec -it 컨테이너명[또는 컨테이너 ID] bash
$ docker run -d nginx
$ docker exec -it [컨테이너 ID] bash

$ ls              # 컨테이너 내부 파일 조회
$ cd /etc/nginx
$ cat nginx.conf

컨테이너 내부에서 빠져나오려면 exit 또는 Ctrl + D를 입력하면 된다.
bash는 쉘(Shell)의 일종으로, 명령어를 입력할 수 있는 인터페이스다.
-it 옵션을 붙여야 명령어를 반복해서 입력할 수 있다. 이 옵션 없이 실행하면 명령어 한 번만 실행하고 바로 종료된다.

[실습] Docker로 Redis 실행시켜보기

지금까지 배운 명령어들을 한데 모아 Redis를 직접 실행해보자.

1. Redis 컨테이너 실행

redis - Official Image | Docker Hub

$ docker run -d -p 6379:6379 redis

로컬에 Redis 이미지가 없으면 Docker Hub에서 자동으로 내려받는다.

2. 이미지 확인

$ docker image ls  # ls : list의 약자

3. 컨테이너 실행 상태 확인

$ docker ps

4. 로그로 에러 여부 확인

$ docker logs [컨테이너 ID 또는 컨테이너명]

5. Redis 컨테이너 내부 접속

$ docker exec -it [컨테이너 ID 또는 컨테이너명] bash

6. Redis 직접 사용해보기

$ redis-cli

127.0.0.1:6379> set 1 jscode  # key: 1, value: jscode 저장
127.0.0.1:6379> get 1          # key: 1에 해당하는 value 조회

지금까지 배운 명령어를 한눈에 정리하면 이렇다.

명령어	설명
docker create	이미지로 컨테이너 생성 (실행 X)
docker start	정지된 컨테이너 실행
docker run	컨테이너 생성 + 실행
docker ps	실행 중인 컨테이너 조회
docker ps -a	전체 컨테이너 조회
docker stop / kill	컨테이너 중지
docker rm	컨테이너 삭제
docker logs	컨테이너 로그 조회
docker exec -it	컨테이너 내부 접속

본 블로그는 인프런의 비전공자도 이해할 수 있는 Docker 입문/실전 강의를 참고하여 작성했습니다.

컨테이너 조회 · 중지 · 삭제 · 로그 확인

najang — Thu, 30 Apr 2026 21:56:08 +0900

컨테이너 조회 — docker ps

실행 중인 컨테이너만 조회

$ docker ps

ps는 process status의 약자다.

모든 컨테이너 조회 (실행 중 + 정지된 컨테이너)

$ docker ps -a

-a는 all의 약자다.

컨테이너 중지 — docker stop / docker kill

$ docker stop 컨테이너명[또는 컨테이너 ID]
$ docker kill 컨테이너명[또는 컨테이너 ID]

stop과 kill은 둘 다 컨테이너를 멈추지만 방식이 다르다. stop은 컴퓨터의 정상 종료 버튼처럼 진행 중인 작업을 마무리하고 graceful하게 종료하고, kill은 전원 버튼을 강제로 눌러 즉시 종료하는 것과 같다. 일반적으로는 stop을 사용한다.

컨테이너 삭제 — docker rm

정지된 특정 컨테이너 삭제

$ docker rm 컨테이너명[또는 컨테이너 ID]

실행 중인 컨테이너는 먼저 중지한 뒤에만 삭제할 수 있다.

실행 중인 특정 컨테이너 강제 삭제

$ docker rm -f 컨테이너명[또는 컨테이너 ID]

정지된 모든 컨테이너 삭제

$ docker rm $(docker ps -qa)

실행 중인 모든 컨테이너 강제 삭제

$ docker rm -f $(docker ps -qa)

컨테이너 로그 조회 — docker logs

컨테이너가 정상적으로 동작하는지, 에러가 발생하지는 않았는지 확인하는 가장 기본적인 방법이 로그 조회다. 디버깅할 때 가장 먼저 확인해야 하는 것이 바로 로그다.

특정 컨테이너의 전체 로그 조회

# docker logs [컨테이너 ID 또는 컨테이너명]
$ docker run -d nginx
$ docker logs [컨테이너 ID]

최근 로그 N줄만 조회

# docker logs --tail [줄 수] [컨테이너 ID 또는 컨테이너명]
$ docker logs --tail 10 [컨테이너 ID 또는 컨테이너명]

기존 로그 + 실시간 로그 함께 보기

# docker logs -f [컨테이너 ID 또는 컨테이너명]
$ docker run -d -p 80:80 nginx
$ docker logs -f [컨테이너 ID]

-f는 follow의 약자다. 로그가 쌓이는 걸 실시간으로 스트리밍해서 보여준다.

기존 로그는 제외하고 실시간 로그만 보기

$ docker logs --tail 0 -f [컨테이너 ID 또는 컨테이너명]

본 블로그는 인프런의 비전공자도 이해할 수 있는 Docker 입문/실전 강의를 참고하여 작성했습니다.

컨테이너 생성과 실행 — create / start / run

najang — Thu, 30 Apr 2026 21:52:56 +0900

컨테이너 생성 — docker create

이미지를 바탕으로 컨테이너를 생성만 한다. 실행까지 이어지지는 않는다. 실제로 생성만 하고 멈추는 경우는 거의 없어서, 이 명령어 단독으로 쓰이는 일은 드물다.

# docker create 이미지명[:태그명]
$ docker create nginx

$ docker ps -a  # 모든 컨테이너 조회

로컬에 해당 이미지가 없으면 Docker Hub에서 자동으로 pull한 뒤 컨테이너를 생성한다.

컨테이너 실행 — docker start

정지되어 있는 컨테이너를 다시 실행할 때 사용한다.

# docker start 컨테이너명[또는 컨테이너 ID]
$ docker start 컨테이너명[또는 컨테이너 ID]

$ docker ps  # 실행 중인 컨테이너 조회

실습 후 정리가 필요하다면 아래 순서로 컨테이너를 중단·삭제한다.

$ docker ps                                          # 실행 중인 컨테이너 확인
$ docker stop {Container ID}                         # 컨테이너 중단
$ docker rm {Container ID}                           # 컨테이너 삭제
$ docker image rm nginx                              # 이미지 삭제

컨테이너 생성 + 실행 — docker run

이미지를 바탕으로 컨테이너를 생성하고 바로 실행까지 한다. 처음 컨테이너를 띄울 때 가장 자주 사용하는 명령어다.

# docker run 이미지명[:태그명]
$ docker run nginx  # 포그라운드에서 실행 — Ctrl + C로 종료

로컬에 이미지가 없으면 Docker Hub에서 자동으로 pull한 뒤 실행한다. 새롭게 갱신된 이미지를 명시적으로 받고 싶다면 docker pull 명령어를 따로 실행해야 한다.

백그라운드로 실행하기 — -d

포그라운드(Foreground) 란 실행한 프로그램의 출력이 화면에 그대로 나타나는 상태다. 화면을 점유하기 때문에 다른 명령어를 입력할 수 없다.

백그라운드(Background) 란 프로그램이 내부적으로 실행되는 상태다. 화면에 출력이 나타나지 않아 다른 명령어를 자유롭게 입력할 수 있다.

# docker run -d 이미지명[:태그명]
$ docker run -d nginx

컨테이너에 이름 붙이기 — --name

컨테이너 ID 대신 직접 지정한 이름으로 관리할 수 있다.

# docker run -d --name [컨테이너 이름] 이미지명[:태그명]
$ docker run -d --name my-web-server nginx

호스트 포트와 컨테이너 포트 연결하기 — -p

컨테이너는 독립된 네트워크를 가지기 때문에, 외부에서 접근하려면 호스트의 포트와 컨테이너의 포트를 명시적으로 연결해줘야 한다.

# docker run -d -p [호스트 포트]:[컨테이너 포트] 이미지명[:태그명]
$ docker run -d -p 4000:80 nginx

docker run -p 4000:80 nginx는 호스트의 4000번 포트를 컨테이너의 80번 포트로 연결한다. 브라우저에서 http://localhost:4000으로 접속하면 컨테이너 내부의 Nginx 서버에 닿는다.

본 블로그는 인프런의 비전공자도 이해할 수 있는 Docker 입문/실전 강의를 참고하여 작성했습니다.

Docker 전체 흐름 느껴보기 (Nginx 설치 및 실행)

najang — Wed, 29 Apr 2026 22:02:26 +0900

Docker는 어떻게 조작할까?

Docker는 터미널에서 명령어(CLI) 를 입력하는 방식으로 조작한다.

Nginx가 처음이라면

Nginx는 다양한 기능을 가진 서버 중 하나다. 대표적인 기능은 아래와 같다.

웹 서버 — HTML 웹 페이지를 브라우저에 렌더링하는 역할을 한다.
~~로드 밸런싱~~ (지금은 몰라도 괜찮다.)
~~리버스 프록시~~ (지금은 몰라도 괜찮다.)

무작정 따라하며 Docker 사용해보기

아래 명령어가 지금 당장 이해되지 않아도 괜찮다. 다음 섹션에서 하나씩 차근차근 살펴볼 예정이다.

1. Nginx 이미지 다운로드

Docker Hub에 공식 Nginx 이미지가 등록되어 있다. 아래 명령어로 로컬에 내려받는다.

nginx - Official Image | Docker Hub

$ docker pull nginx

2. 다운로드된 이미지 확인

이미지가 정상적으로 내려받아졌는지 목록으로 확인한다.

$ docker image ls

ls는 list의 약자로, 목록을 출력하는 명령어다.

3. 이미지를 컨테이너에 올려 Nginx 서버 실행

이미지를 실행해 컨테이너를 생성하고, Nginx 서버를 구동한다.

$ docker run --name webserver -d -p 80:80 nginx

4. Nginx 서버가 잘 실행되는지 확인

브라우저에서 http://localhost:80 에 접속했을 때 Nginx 기본 페이지가 보이면 정상이다.

5. 실행 중인 컨테이너 상태 확인

현재 실행 중인 모든 컨테이너의 상태를 한눈에 확인한다.

$ docker ps

6. 특정 컨테이너 정지

실행 중인 컨테이너를 중단하려면 컨테이너 이름을 지정해 정지한다.

$ docker stop webserver

그림으로 이해하기

본 블로그는 인프런의 비전공자도 이해할 수 있는 Docker 입문/실전 강의를 참고하여 작성했습니다.

Docker 입문: 컨테이너와 이미지

najang — Wed, 29 Apr 2026 22:02:03 +0900

Docker란?

Docker는 컨테이너(Container) 기술을 기반으로, 각각의 프로그램을 분리된 환경에서 실행하고 관리할 수 있게 해주는 도구다.

컨테이너(Container)란?

Windows를 사용해본 적 있다면, 하나의 컴퓨터를 여러 사용자 계정으로 나눠 쓸 수 있다는 걸 알 것이다. 각 계정은 서로 독립된 환경을 가지기 때문에, 필요한 프로그램을 계정마다 따로 설치해야 한다.

컨테이너도 이와 비슷한 개념이다. 하나의 컴퓨터 안에서 여러 개의 독립적인 미니 컴퓨터 환경을 만들고, 각 환경에 프로그램을 별도로 설치·실행할 수 있다. Docker에서는 이 미니 컴퓨터 환경 하나하나를 컨테이너(Container) 라고 부른다.

컨테이너를 이해할 때는 '미니 컴퓨터'를 머릿속에 떠올리면 편하다.

컨테이너를 담고 있는 실제 컴퓨터는 호스트(Host) 컴퓨터라고 구분해서 부른다.

컨테이너의 독립성

컨테이너가 '독립적인 환경'이라고 했는데, 구체적으로 무엇이 독립적으로 관리되는지 살펴보자.

디스크 (저장 공간) — 각 컨테이너는 고유한 저장 공간을 갖는다. 기본적으로 컨테이너 A에서 컨테이너 B의 파일에 접근할 수 없다.
네트워크 (IP, Port) — 각 컨테이너는 고유한 네트워크 환경을 갖는다. 즉, 컨테이너마다 독립적인 IP 주소가 부여된다.

이미지(Image)란?

닌텐도 게임기를 생각해보자. 칩만 바꿔 꽂으면 전혀 다른 게임을 즐길 수 있다. Docker에서 이 게임 칩과 같은 역할을 하는 것이 바로 이미지(Image) 다.

예를 들어, Node.js 기반의 Express.js 서버를 이미지로 만들어두면, Docker로 실행하는 순간 해당 서버가 컨테이너 환경에서 바로 구동된다. 복잡한 설치 과정 없이 말이다. MySQL도 마찬가지다. MySQL 이미지를 실행하기만 하면, 별도의 설치 없이 데이터베이스를 즉시 사용할 수 있다.

이미지는 프로그램 실행에 필요한 모든 것 — 설치 과정, 환경 설정, 버전 정보 등 — 을 패키징한 파일이다. 이미지가 있으면 어떤 환경에서든 동일하게 프로그램을 실행할 수 있다는 게 Docker의 핵심 강점이다.

본 블로그는 인프런의 비전공자도 이해할 수 있는 Docker 입문/실전 강의를 참고하여 작성했습니다.

Redis와 Spring Batch로 만든 하이브리드 랭킹 아키텍처

najang — Thu, 16 Apr 2026 22:28:08 +0900

TL;DR

일별 랭킹은 Redis ZSET으로 실시간 처리하고, 주별/월별 랭킹은 Spring Batch로 집계해 Materialized View 테이블에 적재하는 하이브리드 구조를 선택했다.
기간별 특성(실시간 vs 집계 정확성)이 달라 단일 저장소로는 두 요구사항을 동시에 만족할 수 없었기 때문이다.

1. 들어가며 — "기간별로 저장소가 달라야 하나?"

일별, 주별, 월별 랭킹을 구현해야 했습니다. 처음엔 하나의 방식으로 통일하고 싶었습니다.

그런데 각 기간의 특성을 뜯어보니, 요구사항이 근본적으로 달랐습니다.

기간	핵심 요구사항	데이터 갱신 빈도
일별	실시간성 (방금 전 좋아요가 반영돼야 한다)	이벤트마다 즉시
주별	집계 정확성 (7일치 누적 합산)	주 1회 배치
월별	집계 정확성 (한 달치 누적 합산)	월 1회 배치

일별 랭킹은 매 이벤트(좋아요, 주문)마다 점수가 바뀌어야 합니다.

주별/월별은 실시간으로 바뀔 필요가 없고, 전체 기간 데이터를 한 번에 집계해서 저장해두는 편이 조회 성능 면에서 훨씬 유리합니다.

그래서 기간별로 다른 저장소를 쓰기로 했습니다.

2. 설계 결정: 기간별로 다른 저장소

왜 하나로 통일하지 않았나?

Redis ZSET으로 전부 처리하면 주별/월별 TTL 관리가 복잡해지고, 기간별 데이터 분리가 어렵습니다.

MySQL 집계 쿼리로 전부 처리하면 조회마다 GROUP BY + SUM이 발생합니다.

기간별 특성에 맞는 저장소를 쓰는 게 가장 단순한 선택이었습니다.

3. Redis ZSET으로 실시간 랭킹 만들기

일별 랭킹은 Redis의 Sorted Set(ZSET)을 사용합니다.

ranking:all:yyyyMMdd 형태의 키에 productId를 멤버로, 누적 점수를 스코어로 저장합니다.

동시성 문제: Lua 스크립트로 원자성 보장

좋아요를 취소하면 점수가 감소합니다.

문제는 Unlike 이벤트가 Like보다 많이 들어오면 점수가 음수가 될 수 있다는 것입니다.

ZSET에 음수 스코어가 들어가면 정렬이 깨집니다.

단순히 ZINCRBY 후 결과를 확인하고 ZADD 0을 호출하면 두 명령 사이에 다른 명령이 끼어들 수 있습니다.

이를 막기 위해 Lua 스크립트로 두 연산을 원자적으로 묶었습니다.

private static final RedisScript<Void> ZINCRBY_WITH_FLOOR = RedisScript.of(
    "local score = redis.call('ZINCRBY', KEYS[1], ARGV[1], ARGV[2]) " +
    "if tonumber(score) < 0 then " +
    "  redis.call('ZADD', KEYS[1], 0, ARGV[2]) " +
    "end",
    Void.class
);

Redis는 단일 스레드로 명령을 처리하므로, Lua 스크립트 내 연산은 중간에 끼어드는 명령 없이 원자적으로 실행됩니다.

TTL 2일 — 트레이드오프

키 하나에 TTL 2일을 설정했습니다. "오늘"과 "어제" 데이터만 유지하겠다는 의도입니다.

TTL이 짧으면 메모리는 아끼는데 조회 가능한 날짜 범위가 줄어듭니다.

일별 랭킹은 "오늘" 기준 조회가 대부분이지만, 어제 데이터까지는 캐싱 이점이 있겠다 싶어서 2일로 잡았습니다.

4. Spring Batch로 주간/월간 랭킹 집계

주별/월별 랭킹은 Spring Batch Job으로 처리합니다.

WeeklyRankingJob은 매주 월요일 새벽 2시, MonthlyRankingJob은 매월 1일 새벽 2시에 @Scheduled로 실행됩니다.

배치 작업은 두 Step으로 구성됩니다.

weeklyRankingJob
  ├── Step 1: weeklyTruncateStep  (DELETE FROM mv_product_rank_weekly)
  └── Step 2: weeklyAggregateStep (product_metrics 집계 → INSERT)

Chunk 기반 처리

Step 2는 Chunk 기반으로 동작합니다.

JdbcCursorItemReader로 product_metrics를 읽어 점수를 계산한 뒤, JdbcBatchItemWriter로 결과를 삽입합니다.

Chunk 크기는 1000건입니다.

Reader → Processor → Writer
(1000건 단위 반복)

Chunk 처리를 쓰는 이유는 메모리입니다.

전체 결과를 한 번에 메모리에 올리지 않고, 1000건씩 처리-커밋하므로 데이터 규모가 늘어나도 메모리 부담이 일정합니다.

DELETE + INSERT 전략 — 재실행 안전성

집계 테이블 갱신에 UPSERT 대신 DELETE + INSERT를 선택했습니다.

전략	장점	단점
UPSERT	데이터 공백 없음	중복 키 관리, 부분 갱신 복잡
DELETE + INSERT	구현 단순, 재실행 안전	Step 1~2 사이 일시적 데이터 공백

MV 테이블은 배치가 통째로 교체하는 읽기 전용 캐시에 가깝습니다.

"최신 집계 결과"로 완전히 대체하면 충분하므로 기존 데이터를 보존할 이유가 없습니다.

배치를 재실행해도 중복 데이터가 생기지 않는다는 것도 이 방식의 장점입니다.

단점인 "일시적 데이터 공백"은 두 Step을 별도 트랜잭션으로 분리해 처리합니다.

Step을 분리하면 Step 2(INSERT)가 실패해도 Step 1(DELETE)이 롤백되지 않습니다.

따라서 배치를 재실행할 때 DELETE를 다시 실행하지 않고 INSERT만 재시작하면 됩니다.

주별/월별 랭킹에서 수 초의 공백은 감수하기로 했습니다.

5. 점수 가중치 설계: 좋아요 0.2, 주문 0.7

랭킹 점수는 좋아요와 주문 수를 가중합산합니다.

score = 좋아요수 × 0.2 + 주문수 × 0.7

좋아요보다 주문에 더 높은 가중치를 준 이유는, 주문이 더 강한 구매 의도를 나타내기 때문입니다.

버튼 하나로 남기는 좋아요와 실제 결제까지 이어진 주문은 "인기"를 측정하는 데 다른 무게를 가져야 합니다.

배치와 스트리밍의 계산 방식이 다른 이유

배치(주별/월별)와 스트리밍(일별 Redis)에서 주문 점수 계산이 다릅니다.

// 배치: RankingScoreCalculator (선형)
score = likeCount * 0.2 + orderCount * 0.7

// 스트리밍: OrderEventConsumer (로그 스케일)
double rankingScore = ORDER_WEIGHT * Math.log1p(message.finalAmount());

스트리밍에서 log1p(finalAmount)를 쓰는 이유는 고액 주문의 영향력을 조절하기 위해서입니다.

10만 원짜리 주문과 100만 원짜리 주문이 있을 때, 선형으로 계산하면 고가 상품이 일별 랭킹을 독점할 수 있습니다.

로그 스케일을 적용하면 구매액 차이를 완화해 다양한 가격대의 상품이 공정하게 경쟁합니다.

반면 배치는 일별 product_metrics의 카운트를 집계하므로 이미 이벤트 수 기준으로 균일화되어 있습니다.

별도의 스케일 조정 없이 선형 계산으로 충분합니다.

결과적으로 일별 랭킹(금액 기반)과 주별/월별 랭킹(건수 기반)은 같은 기간이라도 순위가 다를 수 있습니다.

의도한 차이입니다.

가중치 일관성 유지

배치에서 사용하는 LIKE_WEIGHT = 0.2, ORDER_WEIGHT = 0.7 상수는 RankingScoreCalculator에 집중 관리합니다.

스트리밍의 가중치도 같은 숫자를 사용합니다.

두 시스템이 같은 상수를 참조하므로, 코드에서 척도가 일치한다는 것을 확인할 수 있습니다.

6. Kafka 이벤트 동시 처리 — 낙관적 락의 선택

Kafka Consumer는 같은 토픽의 메시지를 병렬로 처리할 수 있습니다.

두 이벤트가 동시에 같은 (productId, date) 행을 갱신하려 하면 Lost Update가 발생합니다.

ProductMetrics에 JPA의 @Version을 추가해 낙관적 락으로 이를 방지했습니다.

@Version
private Long version;

충돌이 감지되면 ObjectOptimisticLockingFailureException이 발생하고, Consumer에서 이를 잡아 중복 처리로 간주하고 skip합니다.

} catch (ObjectOptimisticLockingFailureException e) {
    log.warn("LikeEvent 낙관적 락 충돌 — 중복 처리 감지, skip: productId={}, eventId={}",
        message.productId(), message.eventId());
}

비관적 락 대신 낙관적 락을 선택한 이유

비관적 락(SELECT ... FOR UPDATE)을 쓰면 충돌 시 대기가 발생하고 DB 커넥션을 오래 점유합니다.

Kafka 이벤트 처리처럼 처리량이 중요한 환경에서는 병목이 될 수 있습니다.

낙관적 락은 충돌이 드물다는 가정 하에, 충돌 시 재시도 대신 skip합니다.

Kafka 파티션을 productId 기준으로 설정하면 같은 상품에 대한 이벤트가 같은 파티션으로 직렬화되어 처리되므로 동시 충돌 가능성이 낮아집니다.

현재 파티셔닝이 productId 기준으로 설정되어 있지 않다면, 인기 상품에 이벤트가 몰릴 때 충돌이 반복되고 카운트 오차가 쌓일 수 있습니다.

처리량을 포기하지 않는 대신, 카운트 오차는 감수했습니다.

8. 마무리 — 결국은 "왜"의 연속

랭킹이라는 단일 도메인 안에 저장소가 세 개 공존합니다(MySQL product_metrics, Redis ZSET, MySQL MV 테이블).

저장소가 세 개인 건 어쩔 수 없는 결과입니다.

각 기간의 요구사항이 달랐으니까요.

일별에 Redis를 쓴 건 "Redis가 좋아서"가 아니라 실시간 점수 갱신에 ZSET이 맞아서입니다.

주별/월별에 배치를 쓴 건 집계 주기가 길고 조회 성능이 중요해서입니다.

배치와 스트리밍 사이의 약속

두 시스템이 같은 가중치 상수를 쓰면서 계산 방식은 다릅니다(선형 vs 로그 스케일).

이 차이가 의도적이라면 코드와 주석에 남겨야 합니다.

문서화하지 않으면 나중에 누군가 "왜 다르지?"라는 질문을 반드시 하게 됩니다.

남은 과제

해결하지 못한 문제가 하나 있습니다.

DELETE + INSERT 전략에서 Step 1과 Step 2 사이의 짧은 순간, 조회 API는 빈 테이블을 봅니다.

배치 실행 빈도가 낮으니 지금은 허용하지만, 향후에는 두 가지 방향을 고려할 수 있습니다.

Shadow Table 전략: mv_product_rank_weekly_shadow에 먼저 적재한 뒤 MySQL의 RENAME TABLE로 원자적으로 교체
버전 컬럼 전략: batch_version 컬럼을 두어 최신 버전의 데이터만 조회

랭킹 하나를 만드는 데도 결정이 생각보다 많았습니다.

"일별은 Redis냐 DB냐?", "Truncate냐 Upsert냐?", "낙관적 락이냐 비관적 락이냐?"

— 이 글은 그 결정마다 Why를 남긴 기록입니다.

조회수 하나를 세는 데 이렇게 많은 고민이 필요하다니

najang — Thu, 9 Apr 2026 22:13:10 +0900

TL;DR

상품 조회 시 랭킹 집계 실패가 조회 API 실패로 번지지 않도록 Redis에 직접 +1하는 대신, Kafka 이벤트로 분리했다.

1. 들어가며 — "그냥 Redis에 +1 하면 안 되나?"

상품 상세를 조회할 때 그 상품의 랭킹 점수를 올리는 기능을 구현해야 했습니다.
처음엔 이렇게 짜면 되겠다 싶었습니다.

public ProductInfo findById(Long productId, Long userId) {
    Product product = productService.findById(productId);
    redisTemplate.opsForZSet().incrementScore("ranking:all:" + today, productId, 0.1); // 이 한 줄
    return ProductInfo.from(product);
}

단순하고 직관적입니다. 하지만 운영 환경을 상상하니 위험 신호가 감지되었습니다.

"과연 랭킹 점수 1점을 올리는 일이, 상품 정보를 보여주는 핵심 비즈니스보다 중요할까?"

만약 Redis 네트워크에 장애가 발생한다면, 사용자에게는 상품 상세 정보 대신 500 에러 페이지가 노출될 겁니다.

2. 요구사항 파악 — 이 기능이 풀려는 문제

일일 랭킹: 날짜별로 키를 분리해서 오늘 하루치 점수만 집계합니다.

ranking:all:20260409  ← 오늘 키
ranking:all:20260408  ← 어제 키 (TTL 2일 후 자동 삭제)

점수 계산: 조회, 좋아요, 주문에 각기 다른 가중치를 곱해서 합산합니다.
```
조회   +0.1
좋아요 +0.2
주문   +0.7 × log(금액 + 1)
```
순위 조회: 상품 상세 API가 해당 상품의 오늘 순위를 함께 반환합니다.

3. 첫 번째 고민 — 어디서 점수를 올릴까

[사용자] → GET /products/{id} → [ProductFacade] → Redis ZINCRBY → 응답

문제는 이 흐름이 하나의 동기 체인이라는 점입니다.

Redis에 장애가 생기면?

[사용자] → GET /products/{id} → [ProductFacade] → Redis 연결 실패 → 500 에러

상품 조회는 랭킹 점수 업데이트와 아무 관련이 없는데, Redis 하나 때문에 조회 API 전체가 죽어버립니다.
try-catch로 예외를 삼키면 된다고요? 그건 임시방편이고, 근본적인 구조 문제가 그대로 남습니다.

4. 해결 — 이벤트로 분리하기

그래서 조회 API는 이벤트만 던지고 끝내기로 했습니다.

[사용자] → GET /products/{id} → 응답  ← 여기서 끊김
                 ↓ (비동기)
         ApplicationEvent 발행
                 ↓
         Kafka 토픽 "user-action-events"
                 ↓ (별도 서비스)
         commerce-streamer Consumer
                 ↓
         Redis ZINCRBY

1단계: 조회 시 ApplicationEvent 발행 (ProductFacade.java)

if (userId != null) {
    eventPublisher.publishEvent(new UserActionEvent(
        UserActionEvent.EventType.PRODUCT_VIEWED, userId, productId, null
    ));
}

조회 결과를 반환하고 끝입니다. Redis 얘기가 전혀 없습니다.

2단계: 트랜잭션 커밋 후 Kafka 발행 (UserActionEventKafkaPublisher.java)

@Async
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void publish(UserActionEvent event) {
    kafkaTemplate.send(TOPIC, String.valueOf(event.targetId()), event);
}

어노테이션 두 개가 붙어 있는데 둘 다 이유가 있습니다.

AFTER_COMMIT: 트랜잭션이 롤백되면 이벤트를 발행하지 않습니다. 트랜잭션이 실패했는데 조회 이벤트가 랭킹에 잡히는 걸 막습니다.
@Async: Kafka 발행을 별도 스레드에서 처리해서 API 응답 속도에 영향을 주지 않습니다.

3단계: Consumer가 점수 반영 (UserActionEventConsumer.java)

@KafkaListener(topics = TOPIC, containerFactory = KafkaConfig.BATCH_LISTENER)
public void handleUserActionEvents(
    List<ConsumerRecord<String, UserActionEventMessage>> messages,
    Acknowledgment acknowledgment
) {
    for (ConsumerRecord<String, UserActionEventMessage> record : messages) {
        if (!"PRODUCT_VIEWED".equals(message.eventType())) continue;

        LocalDate eventDate = Instant.ofEpochMilli(record.timestamp())
            .atZone(ZoneId.of("Asia/Seoul"))
            .toLocalDate();
        rankingRedisRepository.incrementScore(eventDate, message.targetId(), VIEW_WEIGHT);
    }
    acknowledgment.acknowledge();
}

5. 두 번째 고민 — Kafka 파티션 키를 왜 productId로 잡았을까

kafkaTemplate.send(TOPIC, String.valueOf(event.targetId()), event);
//                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
//                         key = productId

ZINCRBY는 순서가 바뀌어도 결과는 같습니다. A 상품에 +0.1이 두 번 오는 것과 순서가 달라도 합은 똑같습니다.
그러면 굳이 key를 productId로 고정할 필요가 없지 않을까요?

지금 user-action-events 토픽에는 PRODUCT_VIEWED 말고도 LIKED, UNLIKED가 함께 흐릅니다.
좋아요 후 취소(LIKED → UNLIKED)는 순서가 중요합니다. 순서가 뒤집히면 취소가 먼저 처리되고 좋아요가 나중에 처리되어 결과가 달라집니다.

같은 상품의 이벤트가 항상 같은 파티션으로 가도록 key를 productId로 잡으면, 지금 당장은 필요 없어도 나중에 순서 의존적인 이벤트가 생길 때 구조를 바꾸지 않아도 됩니다.

6. 세 번째 고민 — 중복 소비는 괜찮을까

Kafka Consumer가 재시작되면 이미 처리한 메시지를 다시 소비할 수 있습니다.
그러면 같은 조회 이벤트가 두 번 랭킹에 반영됩니다.

코드 주석에 이런 내용이 있습니다.

/**
 * - 멱등성: 조회 이벤트는 중복 처리 시 점수가 소폭 중복 적재될 수 있으나,
 * weight=0.1이므로 허용
 */

VIEW_WEIGHT = 0.1이라서 조회 이벤트 하나가 중복 적재되어도 점수 오차가 0.1에 불과합니다.
완벽한 멱등성을 위해 Redis에 Event ID를 체크하는 로직을 넣을 수도 있었습니다.

하지만 0.1점의 오차를 잡기 위해 추가적인 네트워크 I/O와 저장 공간을 쓰는 것은 배보다 배꼽이 더 큰 설계라고 판단했습니다.

때로는 완벽한 기술보다 비즈니스 허용 범위 내에서의 효율적 타협이 더 좋은 엔지니어링일 수 있으니까요.

7. 결과적으로 얻은 것과 잃은 것

얻은 것 — 장애 격리

비교 항목	AS-IS (동기 직접 적재)	TO-BE (Kafka 비동기)
가용성	Redis 장애 시 API 전체 장애 발생	Redis 장애 시에도 API 정상 응답
응답 속도	Redis 연산 시간만큼 지연 (Latency)	이벤트 발행 후 즉시 응답 (Low Latency)
데이터 정합성	강한 일관성 (Immediate)	최종 일관성 (Eventual Consistency)
시스템 복잡도	매우 낮음	보통 (Kafka 및 Consumer 관리 필요)

잃은 것 — 즉시 반영과 단순함

Eventual Consistency: 조회 후 랭킹에 즉시 반영되지 않습니다. Kafka를 통해 Consumer가 처리할 때까지 지연이 생깁니다.
디버깅 복잡도: 문제가 생겼을 때 API 코드만 보면 안 됩니다. Kafka 토픽, Consumer 로그, Redis 상태를 모두 확인해야 합니다. 호출 스택이 끊기기 때문입니다.
인프라 의존성 증가: Kafka, Redis, commerce-streamer 서비스가 모두 떠 있어야 랭킹이 동작합니다.

8. 마치며 — 단순해 보이는 기능 뒤의 의사결정들

ZINCRBY ranking:all:20260409 0.1 product:42

이 Redis 명령 한 줄을 언제, 어디서, 어떻게 실행할지 결정하는 데 이만큼의 고민이 필요했습니다.

동기로 처리할까, 비동기로 처리할까?
API 서버에서 직접 처리할까, 별도 Consumer로 분리할까?
파티션 키를 어떻게 잡을까?
중복 처리를 허용할까, 막을까?

단순해 보이는 ZINCRBY 한 줄 뒤에 숨겨진 수많은 'Why'를 해결하는 과정이 즐거웠습니다.

구현은 금방이었지만, 이 글을 쓰며 제 고민의 궤적을 정리하는 시간이 저를 더 단단한 개발자로 만들어준 것 같습니다.

[자바의 신] 1.프로그래밍이란 무엇인가?

najang — Wed, 8 Apr 2026 22:41:18 +0900

백엔드 개발을 하면서 Spring Boot를 사용하고 있지만, 막상 Java의 기초 개념을 제대로 설명하라고 하면 막막할 때가 있었다. 이번 포스팅에서는 자바의 신 1장 내용을 토대로 프로그래밍의 핵심 개념들을 정리해본다.

1. 프로그래밍이란?

프로그래밍은 컴퓨터에게 할 일을 가르치는 것이다.

실생활에 비유하면, 옆에 있는 사람에게 어떤 일을 시키려면 말을 하든, 메일을 쓰든, 메신저를 보내든 그 사람이 알아들을 수 있는 방식으로 전달해야 한다. 프로그래밍도 마찬가지다. 컴퓨터에게 "무슨 일을 해야 하는지"를 컴퓨터가 이해할 수 있는 언어로 전달하는 것이다.

웹 서비스 동작 구조

웹 페이지에서 어떤 정보를 요청하면, 서버는 필요한 데이터를 처리해서 화면에 보여준다.

[사용자 단말기]  →요청→  [서버]
  웹 페이지    ←응답←  프로그램

프론트엔드: HTML, JavaScript로 화면 구성
백엔드: Java, C, Python, PHP, Ruby 등으로 데이터 처리
안드로이드: Java 또는 Kotlin 사용

2. 자바 프로그램의 메소드 구조

디지털 도어락의 비밀번호 확인 기능을 Java 코드로 표현하면 다음과 같다.

public boolean checkPassword(String password) {
    // 중간 내용
}

메소드의 구성 요소를 정리하면 다음과 같다.

구성 요소	용어	예시
`public`	접근 제어자(Access Modifier)	`public`
`boolean`	리턴 타입(Return Type)	`boolean`, `void`, `int`
`checkPassword`	메소드 이름	`checkPassword`
`String password`	매개 변수(Parameter)	`String password`

⚠️ 메소드 선언 시 순서를 반드시 지켜야 한다

// ✅ 올바른 순서
public boolean checkPassword(String password) { }

// ❌ 리턴 타입이 뒤에 오면 컴파일 에러
public checkPassword(String password) boolean { }

// ❌ 매개 변수 앞에 public을 쓰면 에러
(String password) public boolean checkPassword { }

void 리턴 타입

리턴 타입이 없는 경우 void를 사용한다. "이 메소드는 아무것도 돌려주지 않아요"라는 의미다.

public void setPassword(String password) {
    // 값은 받지만 아무것도 반환하지 않는다
}

public void resetPassword() {
    // 입력값도, 반환값도 없다
}

3. 자바의 가장 작은 단위 - 클래스

메소드는 반드시 어떤 클래스(Class) 소속이어야 한다. 클래스 없이 메소드만 단독으로 존재할 수 없다.

public class DoorLockManager {
    public boolean checkPassword(String password) {
        // 중간 내용
    }
}

클래스 선언 규칙

반드시 class 키워드가 앞에 와야 한다
접근 제어자는 일단 public으로 지정
선언 순서: public class 클래스이름

하나의 클래스 안에는 0개 이상의 메소드가 존재할 수 있다.

public class DoorLockManager {
    public boolean checkPassword(String password) {
        // 중간 생략
    }
    public void setPassword(String password) {
        // 중간 생략
    }
    public void resetPassword() {
        // 중간 생략
    }
}

4. 클래스의 상태(State)와 행동(Behavior)

Java는 객체지향 프로그래밍 언어(OOP)다. 클래스는 현실 세계의 사물을 프로그램으로 표현한 것으로, 다음 조건을 만족해야 한다.

클래스는 상태(state)와 행동(behavior)이 있어야 한다.

행동(Behavior) → 메소드
상태(State) → 변수(Variable)

public class DoorLockManager {
    String currentPassword;  // 상태: 현재 비밀번호를 저장하는 변수

    public boolean checkPassword(String password) {
        // 중간 생략
    }
    // 이하 메소드 생략
}

상태(변수)는 클래스 안, 메소드 밖에 정의한다.

단, 반드시 상태와 행동이 모두 있어야 하는 건 아니다. 변수나 메소드가 없다고 컴파일 에러가 발생하지는 않는다.

5. 프로그래밍의 가장 기본, = 연산자

수학에서 =는 좌변과 우변이 같다는 의미지만, 프로그래밍에서 =는 우변의 결과를 좌변의 변수에 대입하는 것이다.

// 수학: 1+2 = 3  (양쪽이 같다)
// Java: 좌측에 변수, 우측에 계산식
int a;
a = 1 + 2;  // a라는 변수에 3을 저장한다

변수 선언 방법

타입 변수명;

int a;           // 정수형 변수 선언
String currentPassword;  // 문자열 변수 선언

참고: int는 소수점이 없는 정수형 타입, String은 단어나 문장을 저장하는 문자열 타입이다.

사칙연산

연산 종류	기호	예 (num1=10, num2=5)	결과
더하기	`+`	`num1 + num2`	15
빼기	`-`	`num1 - num2`	5
곱하기	`*`	`num1 * num2`	50
나누기	`/`	`num1 / num2`	2

-와 /는 키보드 왼쪽에, *는 Shift를 눌러 입력한다.

return 키워드

메소드가 값을 돌려줄 때 return 키워드를 사용한다.

public class Calculator {
    public int add(int num1, int num2) {
        int sum;
        sum = num1 + num2;
        return sum;  // sum 값을 반환한다
    }
}

6. 한 줄을 의미하는 세미콜론(;)

Java에서 세미콜론(;)은 한 줄의 끝을 의미한다. "컴파일러는 세미콜론이 나올 때까지를 한 줄로 인식한다."

// 아래 두 코드는 동일하다
sum = num1 + num2;

sum =
num1 +
num2;

연산자 사이에서 엔터를 입력해 줄을 바꿔도 코드가 정상 동작한다. 가독성을 위해 줄을 나눠 쓸 수 있다는 의미다.

7. 인덴트(들여쓰기)

Java는 인덴트(들여쓰기)를 별로 신경 쓰지 않는다. 다음 두 코드는 컴파일 결과가 완전히 동일하다.

// 인덴트 없는 버전 (컴파일은 되지만...)
public int add(int num1, int num2) {
int sum;
sum = num1 + num2;
return sum;
}

// 인덴트 있는 버전 (협업을 위해 이렇게 써야 한다)
public int add(int num1, int num2) {
    int sum;
    sum = num1 + num2;
    return sum;
}

인덴트 없이 코드를 작성하면 같이 일하는 동료에게 엄청난 민폐다. 중괄호({)가 시작되면 Tab 키를 한 번씩 눌러 들여쓰기하는 습관을 들이자.

8. 모든 프로그래밍 언어의 예약어(Reserved Word)

예약어(Reserved Word)란 이미 프로그래밍 언어에서 의미가 정해진, 사용자가 쓸 수 없는 단어다.

public class Calculator {
    public int add(int num1, int num2) {
        int sum;
        sum = num1 + num2;
        return sum;
    }
}

위 코드에서 예약어: public, class, int, return

예약어는 마치 식당에서 예약된 자리처럼, 아무리 손님이 많아도 먼저 온 손님을 앉히지 않는다. Java에서도 마찬가지로 이 예약어들을 클래스 이름, 메소드 이름, 변수 이름으로 사용할 수 없다.

핵심 정리

예약어라는 것이 있고,
예약어는 클래스, 메소드, 변수의 이름으로 사용할 수 없다.

1장 전체 요약

개념	설명
프로그래밍	컴퓨터에게 할 일을 가르치는 것
메소드	`접근제어자 리턴타입 메소드이름(매개변수) { }`
클래스	메소드의 소속, `public class 이름 { }`
상태(State)	클래스 안, 메소드 밖에 선언된 변수
행동(Behavior)	메소드
= 연산자	우변 계산 결과를 좌변 변수에 대입
세미콜론(;)	한 줄의 끝을 의미
인덴트	Java는 강제하지 않지만, 협업을 위해 반드시 지켜야 함
예약어	언어에서 이미 의미가 정해진 단어, 이름으로 사용 불가

백엔드 개발자로서 Spring Boot를 다루면서 이미 이 개념들을 실무에서 사용하고 있었지만, 다시 한번 정리해보니 왜 Java 코드가 이런 구조를 갖는지 더 명확하게 이해할 수 있었다. 기초를 탄탄히 하는 것이 결국 복잡한 시스템을 이해하는 토대가 된다는 걸 다시 한번 느꼈다.

najang 님의 블로그

6월 회고 — 인증부터 옷장 도메인까지

들어가기 전에 — OMO를 왜 만들게 됐나

1. 인증 인터셉터를 만들면서 — Filter 말고 Interceptor를 쓴 이유

2. ErrorType, "같은 상태코드인데 왜 나눠?"

3. 옷장 도메인 — @ElementCollection에서 @ManyToMany로 갈아엎은 이야기

4. 테스트 격리 버그 — "Duplicate entry" 에러를 만난 날

5. 같은 "재호출 가능한 API"인데 정책이 다르다

6. PATCH를 만들었는데 새 로직이 하나도 없다

이번 달 회고

Docker Volume — 개념 + MySQL로 검증하기

컨테이너가 가진 근본적인 문제

Docker Volume이란?

볼륨을 사용하는 명령어

[실습] MySQL 컨테이너 띄워보기

1단계 — 볼륨 없이 띄우기 (데이터가 사라지는 문제 직접 확인)

2단계 — 볼륨을 적용해서 데이터 유지하기

주의 — 볼륨에 비밀번호 정보가 저장된다

컨테이너 내부 접속 + Redis 실습

컨테이너 내부에 접속하기 — docker exec -it

[실습] Docker로 Redis 실행시켜보기

컨테이너 조회 · 중지 · 삭제 · 로그 확인

컨테이너 조회 — docker ps

컨테이너 중지 — docker stop / docker kill

컨테이너 삭제 — docker rm

컨테이너 로그 조회 — docker logs

컨테이너 생성과 실행 — create / start / run

컨테이너 생성 — docker create

컨테이너 실행 — docker start

컨테이너 생성 + 실행 — docker run

백그라운드로 실행하기 — -d

컨테이너에 이름 붙이기 — --name

호스트 포트와 컨테이너 포트 연결하기 — -p

Docker 전체 흐름 느껴보기 (Nginx 설치 및 실행)

Docker는 어떻게 조작할까?

Nginx가 처음이라면

무작정 따라하며 Docker 사용해보기

그림으로 이해하기

Docker 입문: 컨테이너와 이미지

Docker란?

컨테이너(Container)란?

컨테이너의 독립성

이미지(Image)란?

Redis와 Spring Batch로 만든 하이브리드 랭킹 아키텍처

TL;DR

1. 들어가며 — "기간별로 저장소가 달라야 하나?"

2. 설계 결정: 기간별로 다른 저장소

3. Redis ZSET으로 실시간 랭킹 만들기

동시성 문제: Lua 스크립트로 원자성 보장

TTL 2일 — 트레이드오프

4. Spring Batch로 주간/월간 랭킹 집계

Chunk 기반 처리

DELETE + INSERT 전략 — 재실행 안전성

5. 점수 가중치 설계: 좋아요 0.2, 주문 0.7

배치와 스트리밍의 계산 방식이 다른 이유

가중치 일관성 유지

6. Kafka 이벤트 동시 처리 — 낙관적 락의 선택

비관적 락 대신 낙관적 락을 선택한 이유

8. 마무리 — 결국은 "왜"의 연속

배치와 스트리밍 사이의 약속

남은 과제

조회수 하나를 세는 데 이렇게 많은 고민이 필요하다니

TL;DR

1. 들어가며 — "그냥 Redis에 +1 하면 안 되나?"

2. 요구사항 파악 — 이 기능이 풀려는 문제

3. 첫 번째 고민 — 어디서 점수를 올릴까

4. 해결 — 이벤트로 분리하기

5. 두 번째 고민 — Kafka 파티션 키를 왜 productId로 잡았을까

6. 세 번째 고민 — 중복 소비는 괜찮을까

7. 결과적으로 얻은 것과 잃은 것

얻은 것 — 장애 격리

잃은 것 — 즉시 반영과 단순함

8. 마치며 — 단순해 보이는 기능 뒤의 의사결정들

[자바의 신] 1.프로그래밍이란 무엇인가?

1. 프로그래밍이란?

웹 서비스 동작 구조

2. 자바 프로그램의 메소드 구조

⚠️ 메소드 선언 시 순서를 반드시 지켜야 한다

void 리턴 타입

3. 자바의 가장 작은 단위 - 클래스

3. 옷장 도메인 — `@ElementCollection`에서 `@ManyToMany`로 갈아엎은 이야기