Skip to content

README-setting.md

Latest commit

 

History

History
238 lines (161 loc) · 7.53 KB

README-setting.md

File metadata and controls

238 lines (161 loc) · 7.53 KB
Raw

SnapTix — 개발 환경 · 도구 설정

이 문서는 코드 품질 도구 · 모니터링 · 부하 테스트 실행 설정을 다룹니다. 프로젝트 소개는 README.md를 참고하세요.

코드 품질 도구

이 프로젝트는 ktlint, detekt, Kover를 사용하여 코드 스타일, 정적 분석, 테스트 커버리지를 관리합니다.

ktlint

Kotlin 공식 코딩 컨벤션 기반의 코드 스타일 검사 도구입니다.

명령어

# 스타일 위반 검사
./gradlew ktlintCheck
# 자동 수정 (수정 가능한 항목에 한해)
./gradlew ktlintFormat

주요 규칙

  • 들여쓰기: 스페이스 4칸
  • 클래스 본문 시작/끝 빈 줄 금지
  • 불필요한 세미콜론 금지
  • import 와일드카드 금지

detekt

Kotlin 정적 분석 도구로 복잡도, 잠재적 버그, 코드 스타일 등을 검사합니다.

명령어

# 전체 소스 분석
./gradlew detekt

설정 파일

규칙 설정은 config/detekt/detekt.yml에서 관리합니다.

주요 설정값:

규칙 기준값
함수 최대 줄 수 60줄
클래스 최대 줄 수 600줄
파일당 최대 함수 수 20개
최대 줄 길이 120자
최대 파라미터 수 (함수) 6개
최대 파라미터 수 (생성자) 7개
최대 중첩 깊이 4단계
최대 return 문 수 2개

리포트

분석 결과는 build/reports/detekt/ 에 생성됩니다.

파일 형식
detekt.html 브라우저에서 확인 가능한 HTML 리포트
detekt.xml CI/CD 연동용 Checkstyle XML
detekt.sarif GitHub Code Scanning 연동용 SARIF

규칙 예외 처리

특정 줄에서 규칙을 무시해야 할 경우:

@Suppress("LongParameterList")
fun someFunction(a: String, b: String, c: String, d: String, e: String, f: String, g: String) { }

Kover (테스트 커버리지)

JetBrains 공식 Kotlin 커버리지 도구입니다. Kotlin의 data class, lambda, inline function 등에서 발생하는 JaCoCo 집계 오차를 방지하기 위해 사용합니다.

명령어

# HTML 리포트 생성
./gradlew koverHtmlReport
# 커버리지 기준 검증 (기준 미달 시 빌드 실패)
./gradlew koverVerify

리포트

리포트는 build/reports/kover/html/ 에 생성됩니다. index.html을 브라우저에서 열면 패키지별 상세 커버리지를 확인할 수 있습니다.

커버리지 기준 및 제외 대상

최소 커버리지 기준은 라인 70%(임시) 이며, 미달 패키지 보완 후 최종 목표인 **80%**로 상향할 예정입니다. 아래 패키지는 측정에서 제외됩니다.

제외 패턴 이유
*.config.* 설정 클래스
*.dto.* 데이터 전달 객체
*Application* 애플리케이션 진입점
*.exception.* 예외 정의 클래스
*.loadtest.* 부하 테스트 전용 인프라 코드
com.develop.snaptix.staff.* deprecated 모듈

패키지별 커버리지 현황은 COVERAGE.md를 참고하세요.

모니터링 (Prometheus + Grafana)

정합성 백그라운드 잡(Reconcile · Drift · Rebuild · Cleanup · OrderStreamTrim)과 Redis 서킷 브레이커를 Micrometer 메트릭으로 수집·시각화합니다. 로컬 우선 구성으로, 앱은 호스트(IDE/gradle, :8080)에서 실행하고 모니터링 스택만 별도 compose로 선택적으로 켜고 끕니다.

실행 방법

1단계 — 앱 기동 (:8080)

로컬에서 docker-compose up -d(MySQL + Redis)를 실행한 뒤 앱을 기동합니다.

2단계 — 모니터링 스택 기동

cd monitoring
docker compose -f docker-compose.monitoring.yml up -d
컨테이너 이미지 포트
Prometheus prom/prometheus:v3.5.4 9090
Grafana grafana/grafana:13.1.0 3000

Linux 호스트에서는 Prometheus가 호스트 앱(:8080)에 닿도록 docker-compose.monitoring.yml의 extra_hosts: "host.docker.internal:host-gateway" 주석을 해제하세요. Docker Desktop(Mac/Win)은 기본 지원합니다.

3단계 — 접속 확인

대상 URL 확인 사항
Prometheus 타깃 http://localhost:9090/targets snaptix-local UP
Grafana http://localhost:3000 (admin/admin) SnapTix > SnapTix Resilience 대시보드 렌더

(옵션) POST /api/v1/admin/reconcile(ADMIN) 호출 후 Reconcile 패널 값 변화를 확인할 수 있습니다.

종료

docker compose -f docker-compose.monitoring.yml down

대시보드 — SnapTix Resilience

7개 패널로 구성됩니다.

패널 내용
Reconcile 처리율 released / compensated / failed (rate/s)
Drift 처리율 fixed / oversell / failed / skipped (rate/s)
잡 실행시간 max reconcile / drift / rebuild / cleanup (s)
Cleanup / OrderStreamTrim 처리율 cleaned / failed / stream.trimmed (rate/s)
Read-Only 모드 OFF(green) / ON(red)
Rebuild outcomes outcome별 누적
Redis 서킷 브레이커 상태 resilience4j_circuitbreaker_state{name="redis"}

메트릭 접두어는 snaptix_*로 통일되어 있으며, 카운터는 부트 시 0-초기화되어 "미배포"와 "처리 0건"을 구분할 수 있습니다. 큐 백로그 깊이는 snaptix_order_stream_xlen / snaptix_order_stream_xpending 게이지로 관측합니다.

디렉터리 구조

Grafana 프로비저닝 경로는 고정이므로 아래 구조를 정확히 맞춰야 자동 로드됩니다.

monitoring/
├── docker-compose.monitoring.yml
├── prometheus/
│   ├── prometheus.yml
│   └── secrets/
│       └── prom_pass                 # 운영 scrape용 비밀번호 (gitignore)
└── grafana/
    ├── provisioning/
    │   ├── datasources/datasource.yml    # uid: prometheus
    │   └── dashboards/dashboard.yml
    └── dashboards/
        └── snaptix-resilience.json

운영(AWS) 환경에서는 /actuator/prometheus를 기존 도메인에서 차단하고, 별도 A레코드 도메인 + NPM Access List(Basic Auth) + HTTPS + 경로 제한으로만 노출합니다.

CI/CD 연동

PR 생성 시 GitHub Actions에서 ktlint, detekt, Kover가 자동으로 실행됩니다. 세 검사 중 하나라도 실패하면 PR 머지가 차단됩니다.

로컬에서 PR 전에 미리 확인하려면:

./gradlew ktlintCheck detekt koverVerify

부하 테스트 (k6)

선착순 티켓팅 시나리오를 k6로 부하 테스트합니다. loadtest 프로파일로 앱을 기동하면 시드 데이터(어드민 · 테스트 유저 · 이벤트 · 재고)가 자동 생성되며, 별도 DB 시딩 스크립트 없이 바로 k6를 실행할 수 있습니다.

사전 조건, 시나리오별 실행 방법, 환경변수·메트릭·임계값 전체 가이드는 loadtest/README.md를 참고하세요.

빠른 시작 (프로젝트 루트에서):

# 1. 부하 테스트 전용 컨테이너 기동 (MySQL:3307, Redis:6380)
docker compose -f docker-compose.loadtest.yml up -d

# 2. loadtest 프로파일로 앱 기동 → 시드 데이터 자동 생성
#    (application-secret.yml에 jwt.secret 설정 필요)
SPRING_PROFILES_ACTIVE=loadtest ./gradlew bootRun

# 3. (다른 터미널에서) 시나리오 실행
./loadtest/run.sh order-load

생성되는 loadtest/seed/.env, loadtest/seed/users.json은 커밋하지 않습니다.