[FEAT] 비동기 작업 유실 완화를 위한 Graceful Shutdown 적용

[KoungQ]

📌 제목

[FEAT] 비동기 작업 유실 완화를 위한 Graceful Shutdown 적용

---

📢 요약

운영 환경 재시작 시 처리 중이던 요청과 비동기 작업이 즉시 중단되며 유실될 수 있는 문제를 완화하기 위해 Graceful Shutdown을 적용했습니다.

prod 프로필에서만 애플리케이션 종료 대기 시간을 설정하고, 컨테이너가 해당 시간을 실제로 보장할 수 있도록 실행 및 종료 구성을 함께 정리했습니다. 또한 readiness/liveness
probe를 활성화해 종료 시점에 새 트래픽을 받지 않도록 운영 환경과 연동할 수 있게 했습니다.

🔗 연관 이슈: Resolves #89

---

🚀 PR 유형

해당하는 항목에 체크해주세요.

• ✨ 새로운 기능 추가
• 🏗️ 빌드 및 패키지 매니저 수정

---

✅ PR 체크리스트

PR이 다음 요구 사항을 충족하는지 확인해주세요.

• 🔹 커밋 메시지 컨벤션을 준수했습니다. (Commit message convention 참고)
• 🔹 변경 사항에 대한 테스트를 수행했습니다. (버그 수정/기능 테스트)
• 🔹 관련 문서를 업데이트했습니다. (필요한 경우)

---

📜 기타

리뷰어가 알면 좋을 추가 사항을 적어주세요.

• application-prod.yml에 server.shutdown=graceful, spring.lifecycle.timeout-per-shutdown-phase=30s를 적용했습니다.
• application-prod.yml에 readiness/liveness probe를 활성화해 /actuator/health/readiness, /actuator/health/liveness를 운영 헬스체크 경로로 사용할 수 있게 했습니다.
• Dockerfile은 exec java ... 형태로 수정해 SIGTERM이 JVM에 직접 전달되도록 변경했습니다.
• docker-compose.yml의 backend 서비스에 stop_grace_period: 45s를 추가해 앱의 30초 종료 대기 시간을 컨테이너 레벨에서 보장하도록 했습니다.
• 애플리케이션 시작/종료 및 readiness/liveness 상태 전환 로그를 추가해 배포 시 종료 흐름을 추적할 수 있도록 했습니다.
• 로컬 검증은 임시 DB를 사용한 prod 프로필 기동으로 수행했습니다.
• SIGTERM 전송 시 readiness가 REFUSING_TRAFFIC으로 전환되고, 진행 중이던 15초 요청이 200 OK로 완료된 뒤 프로세스가 종료되는 것을 확인했습니다.
• 테스트를 위해 일시적으로 사용한 전용 엔드포인트/환경은 모두 제거했고, 현재 변경분에는 배포용 설정만 남아 있습니다.
• Graceful Shutdown 효과를 실제 운영에서 온전히 얻으려면 LB/Ingress가 /actuator/health/readiness를 기준으로 트래픽 드레이닝을 수행해야 합니다.

Summary by CodeRabbit

Release Notes

• 새 기능

  • 방 검색 결과에서 사용자 성별과 일치하는 방으로만 필터링
  • 방 신청 시 성별 일치 여부 검증 추가

• 개선 사항

  • 우아한 애플리케이션 종료 및 헬스 체크 기능 강화
  • 데이터베이스 쿼리 성능 최적화

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Warning

Ignoring CodeRabbit configuration file changes. For security, only the configuration from the base branch is applied for open source repositories.

Walkthrough

방 검색에 사용자 성별 기반 필터링을 추가하고, 방 신청 시 성별 일치 여부를 검증하며, 우아한 종료(Graceful Shutdown) 설정을 추가하고, 애플리케이션 생명주기 이벤트에 구조화된 로깅을 도입했습니다.

Changes

Cohort / File(s)	Summary
Graceful Shutdown 설정 Dockerfile, docker-compose.yml, src/main/resources/application-prod.yml	Java 프로세스를 컨테이너의 PID로 실행하고 종료 유예 시간을 45초로 설정하며, 서버 graceful shutdown과 헬스 프로브를 활성화합니다.
애플리케이션 생명주기 로깅 src/main/java/com/project/dorumdorum/global/alert/ApplicationLifecycleAlertListener.java	@Slf4j 추가 및 애플리케이션 준비/종료 이벤트, 헬스 상태 변경 이벤트에 대한 구조화된 로깅 메서드를 도입합니다.
Configuration 업데이트 .coderabbit.yml, .gitignore	코드래빗 auto_review 설정에 기본 브랜치 패턴 추가 및 gitignore에 docs 디렉터리 제외 규칙 추가합니다.
Room 엔티티 및 성별 필터링 src/main/java/com/project/dorumdorum/domain/room/domain/entity/Room.java, src/main/java/com/project/dorumdorum/domain/room/domain/service/RoomService.java, src/main/java/com/project/dorumdorum/domain/room/domain/repository/RoomQueryRepository.java, src/main/java/com/project/dorumdorum/domain/room/infra/repository/RoomRepositoryImpl.java	Room 엔티티에 non-null gender 필드를 추가하고, 쿼리 메서드들에 gender 파라미터를 추가하여 성별 기반 필터링을 지원합니다. 인덱스를 gender 포함하도록 업데이트합니다.
방 검색 UseCase 및 Controller src/main/java/com/project/dorumdorum/domain/room/application/usecase/FindRoomsUseCase.java, src/main/java/com/project/dorumdorum/domain/room/ui/FindRoomsController.java, src/main/java/com/project/dorumdorum/domain/room/ui/spec/FindRoomsApiSpec.java	현재 사용자 정보를 파라미터로 받아 사용자 성별을 조회한 후 repository에 전달하여 동일 성별 방만 검색 결과에 포함되도록 수정합니다.
방 신청 UseCase src/main/java/com/project/dorumdorum/domain/room/application/usecase/ApplyRoomUseCase.java	지원자의 성별을 조회하고 방의 성별과 일치 여부를 검증한 후, 불일치 시 GENDER_MISMATCH 예외를 발생시킵니다.
방 생성 UseCase src/main/java/com/project/dorumdorum/domain/room/application/usecase/CreateRoomUseCase.java	호스트 사용자가 이미 룸메이트인지 검증하고, 사용자 성별을 조회하여 방 생성 시 전달합니다. UserService 의존성을 추가합니다.
User 엔티티 src/main/java/com/project/dorumdorum/domain/user/domain/entity/User.java	gender 필드에 @Column(nullable = false) 제약조건을 추가합니다.
Error Status src/main/java/com/project/dorumdorum/global/exception/code/status/RoomErrorStatus.java	성별 불일치 시 사용할 GENDER_MISMATCH 예외 코드(ROOM016, FORBIDDEN)를 추가합니다.
Database Schema src/main/resources/schema.sql	users 테이블의 gender 컬럼을 NOT NULL로 변경하고, room 테이블의 인덱스를 gender 포함하도록 재구성합니다.
Test 업데이트 src/test/java/com/project/dorumdorum/domain/.../	모든 관련 테스트를 업데이트하여 gender 파라미터 추가, 테스트 데이터에 성별 설정, 새로운 gender 검증 테스트 케이스를 추가합니다.

Sequence Diagram

sequenceDiagram
    participant Client as Client
    participant Controller as FindRoomsController
    participant UseCase as FindRoomsUseCase
    participant UserService as UserService
    participant RoomService as RoomService
    participant Repository as RoomRepositoryImpl

    Client->>Controller: loadAll(userNo, request)
    Controller->>UseCase: execute(userNo, request)
    UseCase->>UserService: findById(userNo)
    UserService-->>UseCase: User{gender}
    UseCase->>RoomService: searchByCursor(gender, request, ...)
    RoomService->>Repository: findByCursor(gender, request, ...)
    Repository->>Repository: queryDSL로 room.gender = gender 필터 적용
    Repository-->>RoomService: List<FindRoomsResponse>
    RoomService-->>UseCase: CursorPage<FindRoomsResponse>
    UseCase-->>Controller: CursorPage<FindRoomsResponse>
    Controller-->>Client: ResponseEntity<CursorPage>

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

주요 이유는 room 검색/생성/신청 로직에 걸쳐 여러 파일에서 일관되게 gender 파라미터를 추가했으며, 데이터베이스 스키마와 쿼리 인덱스 변경이 포함되어 있고, graceful shutdown 설정과 로깅 개선도 함께 진행되었기 때문입니다. 변경이 비교적 명확하고 테스트 커버리지도 적절히 업데이트되었습니다.

Possibly related issues

• [FEAT] 비동기 작업 유실 완화를 위한 Graceful Shutdown 적용 #89: Graceful shutdown 적용 - 본 PR의 docker-compose.yml 변경, Dockerfile exec 추가, application-prod.yml의 graceful shutdown 설정, ApplicationLifecycleAlertListener의 헬스 프로브 구성이 해당 이슈를 직접 구현합니다.

Possibly related PRs

• [RELEASE] v0.1.3 #55: RoomQueryRepository와 RoomRepositoryImpl의 findByCursor/searchByCursor 메서드 시그니처 변경이 동일하게 진행되어 코드 수준에서 연관성이 있습니다.
• [RELEASE] v0.1.8 #74: Room 엔티티, RoomService, RoomRepositoryImpl, FindRoomsUseCase/Controller, ApplyRoomUseCase, 스키마 변경, RoomErrorStatus 등 동일한 방 관련 클래스들이 중복으로 수정되어 상당한 코드 겹침이 발생합니다.
• [FEAT] 비동기 알림 재처리 및 멱등성 보장 로직 구현 #77: ApplyRoomUseCase 클래스가 동시에 수정되므로 병합 충돌 가능성이 있습니다.

Suggested reviewers

• ydking0911

🚥 Pre-merge checks | ✅ 1 | ❌ 4

❌ Failed checks (3 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	PR 제목은 Graceful Shutdown 기능에 관한 것이지만, 실제 변경사항에는 성별 기반 방 필터링 기능이 대부분을 차지하고 있습니다.	PR 제목을 변경사항의 주요 내용을 반영하도록 수정하거나, 아니면 graceful shutdown 관련 변경만 별도 PR로 분리해주세요.
Out of Scope Changes check	⚠️ Warning	Graceful Shutdown 이슈 #89와 무관하게 성별 기반 방 필터링 기능(Room 엔티티에 gender 필드 추가, 쿼리 필터링, 사용자 신청 검증 등)이 다수 포함되어 있습니다. 또한 .gitignore, .coderabbit.yml 변경도 이슈와 무관합니다.	성별 필터링 기능과 .gitignore, .coderabbit.yml 변경을 별도의 PR로 분리하고, 이 PR은 Graceful Shutdown 관련 변경만 포함하도록 정리해주세요.
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.98% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Linked Issues check	❓ Inconclusive	링크된 이슈 #89는 Graceful Shutdown 구현을 목표로 하며, 해당 기능은 일부 구현되었으나(application-prod.yml, Dockerfile, docker-compose.yml, ApplicationLifecycleAlertListener 변경), 변경사항의 대다수가 성별 기반 방 필터링 기능으로 이 이슈와 무관합니다.	변경사항 중 Graceful Shutdown과 무관한 성별 필터링 관련 코드(Room 엔티티, 서비스 레이어, 테스트 등)를 별도 PR로 분리하여 이슈와의 일관성을 확보해주세요.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/#89/비동기-작업-유실-완화를-위한-graceful-shutdown-적용

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[KoungQ]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.