Files
sodalive-backend-spring-boot/docs/agent-guides/실행명령어.md
T

9.9 KiB
Raw Blame History

실행 명령어

실행 기준

  • 아래 명령은 저장소 루트(/Users/klaus/Develop/sodalive/Server/sodalive)에서 실행한다.
  • 변경 범위에 맞는 최소 명령으로 검증하고, 결과는 계획 문서 하단 검증 기록에 남긴다.
  • 에이전트는 구현 중인 기능의 focused test와 직접 영향받는 package/feature 회귀만 각각 실행한다. --tests로 대상 클래스·메서드·패키지를 명시한다.
  • 전체 테스트는 10분 실행 제한으로 완료되지 않는 경우가 많으므로 사용자가 직접 실행한다. 에이전트는 무필터 ./gradlew test를 자동 실행하거나 timeout 후 재시도하지 않는다.
  • 공통 코드 변경, 여러 domain/phase 변경, release/final Gate라도 자동으로 전체 테스트로 확대하지 않는다. 영향받는 기능을 식별해 각각 검증하고 확인하지 못한 범위를 보고한다.
  • ./gradlew check, ./gradlew build, ./gradlew clean build도 전체 테스트를 포함하므로 에이전트가 자동 실행하지 않는다. 빌드 산출물 검증이 필요하면 ./gradlew bootJar를 사용하고 기능별 테스트와 구분해 기록한다.
  • 계획 문서와 최종 보고에는 실행한 기능별 테스트 명령·결과, 전체 테스트 미실행 사실, 사용자 실행 명령 ./gradlew test를 남긴다. 기능별 성공을 전체 테스트 성공으로 표현하지 않는다.
  • 전체 테스트의 사용자 실행 대기는 기능 범위 완료를 막지 않는다. 기능별 테스트 실패나 미검증 위험은 별도로 명시하며 실패를 무시하거나 테스트를 완화하지 않는다.

Build/Lint/Test

에이전트는 변경 범위에 필요한 명령만 선택한다. 아래 --tests는 기존 홈 기능의 예시이며 실제 작업 대상에 맞게 바꾼다.

./gradlew tasks --all
./gradlew bootRun
./gradlew test --tests 'kr.co.vividnext.sodalive.v2.creator.channel.home.*' --tests 'kr.co.vividnext.sodalive.v2.api.creator.channel.home.*'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.CodePointTextSplitterTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsLanguageDetectionProviderTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsTranslationServiceTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.AwsLanguageProviderConfigurationTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.TranslationJobRetryIntegrationTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.ContentTagTranslationIntegrationTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.CompletedContentTagRepairTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.content.MetadataLanguageDetectTransactionTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.i18n.translation.*ReadRetryTest' --tests 'kr.co.vividnext.sodalive.i18n.translation.MetadataTranslationHttpIntegrationTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.content.AudioContentDetailTranslationHttpIntegrationTest'
./gradlew --no-daemon test --tests 'kr.co.vividnext.sodalive.content.ContentSeriesDetailTranslationHttpIntegrationTest'
./gradlew bootJar
./gradlew ktlintCheck
./gradlew ktlintFormat

사용자가 직접 실행하는 전체 검증 명령:

./gradlew test
./gradlew check
./gradlew build
./gradlew clean build

위 명령은 목적에 맞게 하나를 선택한다. 전체 테스트 확인만 필요하면 ./gradlew test로 충분하다.

테스트 메모리와 진행 진단

  • IntelliJ의 Build, Execution, Deployment > Build Tools > Gradle > Run tests using을 Gradle로 맞추면 CLI와 같은 테스트 JVM 설정을 사용한다. IDE 자체 JUnit runner는 Gradle의 heap/worker 설정을 적용하지 않는다.
  • 테스트 JVM heap은 Test task 실행 직전에 가용 메모리로 계산한다. 가용 추정의 50%를 유효 동시 worker 수(min(maxParallelForks, maxWorkers))로 나누고, 그 worker 예산의 25%를 힙 외 용도로 남긴다. 나머지 75%를 MiB 단위로 내려 명시적 maxHeapSize로 전달한다. 고정 4GiB 정책 하한이나 고정 1GiB 예약은 사용하지 않는다. 단, JVM 실행 자체가 불가능한 2MiB 미만 결과는 상향 보정하지 않고 명시적으로 거부한다.
  • macOS 가용 추정은 vm_stat의 (Pages free + Pages inactive) × page size이며 speculative/file-backed를 별도로 더하지 않는다. Linux는 /proc/meminfo의 MemAvailable을 사용해 회수 가능한 메모리를 반영한다. MemTotal과 MemAvailable은 kB(1024 bytes)로 읽고 잘못되거나 누락된 값은 추정으로 대체하지 않는다.
  • Linux에서 JDK의 total memory가 host MemTotal보다 작으면 JDK가 인식한 더 작은 제한으로 판단한다. 이 경우에만 host MemAvailable, JDK free memory, JDK total memory 중 가장 작은 값을 사용한다. cgroup v1/v2는 Java 17의 컨테이너 인식에 의존하며, UseContainerSupport 비활성화·발견 실패·미지원 구성이나 JDK가 인식하지 못한 상위 제한까지 탐지한다고 보장하지 않는다.
  • macOS/Linux 외에는 JDK의 free-memory 값을 보수적으로 사용한다. 모든 관측은 시작 시점의 추정이며 이후 사용량 변화나 앱 테스트에 충분한 메모리를 보장하지 않는다.
  • 콘솔의 Test heap:에서 관측값·유효 worker 수·선택한 상한을 확인한다. task 시작 때 한 번 계산하며 교체된 worker도 동일한 상한을 사용한다. 메모리 부족 오류가 나면 다른 프로그램/중복 테스트를 정리한 뒤 다시 실행한다. 기존 maxHeapSize만 지워 Gradle 기본 512MB로 돌아가거나, 비율 옵션만 추가하는 방식은 사용하지 않는다.
  • Linux는 Test memory (Linux):에 JVM total/free와 최종 가용량도 기록한다. Jenkins 메모리 문제를 조사할 때 이 줄과 Test heap:, 최초 OOM 전체 메시지를 함께 확인한다. 전체 빌드 명령의 org.gradle.jvmargs는 Gradle JVM 설정이며 테스트 worker heap과 별개다.
  • 예를 들어 관측값 2,460,004,352 bytes와 worker 1개는 879MiB 힙을 선택한다. 4GiB 미만이라는 이유만으로 중단하지 않지만, 선택된 예산이 앱 테스트의 실제 메모리 요구량보다 작으면 JVM에서 OOM이 발생할 수 있다. 계산 성공을 전체 테스트 통과 보장으로 해석하지 않는다.
  • 동시 worker 1개, Spring context 캐시 최대 4개, forkEvery=300을 사용한다. Gradle이 처리하는 class candidate 수 기준이므로 실제 테스트 개수와 같지 않으며, JUnit Platform 필터 실행에서도 빈 worker가 생길 수 있다. 단일 클래스의 과도한 메모리 사용까지 방지하지는 않는다. Gradle daemon heap과 테스트 worker heap은 별개다. 같은 저장소의 전체 테스트를 IDE와 CLI/에이전트에서 동시에 시작하지 않는다.
  • 실행 콘솔의 Test class:는 클래스 시작 위치이며 완료 또는 성공 표시가 아니다. 최종 종료 코드와 build/test-results/test/의 해당 실행 XML을 함께 확인한다.
  • GC 로그는 build/test-gc/<task 이름>/gc-<PID>.log에 기록한다. PID별 10MB 파일과 회전 로그 최대 3개를 사용한다. 오래된 실행 로그는 조사 후 정리한다.
  • 후반에 진행이 멈추면 해당 worker PID의 jstat -gcutil <PID>와 GC 로그를 확인한다. Old 사용률이 높고 Full GC 시간만 증가하는 상태에서는 실행 제한만 늘리지 않는다. 타인이 시작한 worker는 승인 없이 종료하지 않는다.
  • 힙 예산 build logic를 변경하면 ./gradlew --no-daemon -p buildSrc test --tests 'buildlogic.*'로 산정·OS 파싱·Linux/container 경계를 검증한다. 이 테스트는 애플리케이션의 root test와 별도이며, 일반 root 실행에서 buildSrc 컴파일만 됐다고 테스트까지 통과한 것으로 보지 않는다.
  • 힙 정책과 테스트는 buildSrc/src/main/kotlin/buildlogic/TestHeapPolicy.kt, buildSrc/src/test/kotlin/buildlogic/TestHeapPolicyTest.kt에 둔다. buildSrc는 Gradle 버전에 맞는 kotlin-dsl과 Java 17 toolchain을 사용하며 앱의 Kotlin 버전과 별도로 관리한다. 해당 Kotlin 소스의 포맷 검사는 ./gradlew --no-daemon -p buildSrc ktlintCheck로 실행한다.

Jenkins 전체 빌드 명령

수정된 build logic가 Jenkins workspace에 반영된 뒤 아래 명령을 사용한다. 테스트를 생략하지 않으며, Gradle JVM의 2GB 한도와 테스트 worker의 자동 힙 산정은 별개다.

./gradlew clean build \
  --no-daemon \
  --no-parallel \
  --max-workers=1 \
  --console=plain \
  --stacktrace \
  '-Dorg.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=768m -Dfile.encoding=UTF-8'

별도의 테스트 heap 옵션은 필요하지 않다. Linux에서는 Test memory (Linux):와 Test heap: 두 로그를 함께 확인한다. 이 명령은 Jenkins/사용자의 전체 검증용이며 에이전트가 자동 실행하는 명령이 아니다.

빌드 시간이 길면 같은 명령에 --profile을 추가해 build/reports/profile/에서 컴파일과 테스트 시간을 구분한다. forkEvery=300은 1932MiB 힙에서 관련 33개 테스트의 로컬 비교를 거쳐 적용했으며, 실제 Jenkins 전체 suite의 시간·OOM 여부까지 보장한 값은 아니다. 재시작 간격을 추가로 늘리거나 힙/캐시/병렬 수를 함께 바꾸기 전에 해당 환경의 GC와 실행시간을 비교한다.

AWS 의존성 확인

기존 SDK v1은 유지하고 Comprehend/Translate만 SDK v2 BOM 2.57.11을 사용한다. 기본 동기 HTTP runtime은 전이 의존성이다. Spring Boot 2.7의 HTTP5 하향 관리를 피하도록 SDK POM 기준 httpclient5.version=5.6.4, httpcore5.version=5.4.3을 맞춘다.

./gradlew --no-daemon dependencyInsight --dependency org.apache.httpcomponents --configuration runtimeClasspath
./gradlew bootJar