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

89 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 실행 명령어
## 실행 기준
- 아래 명령은 저장소 루트(`/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`는 기존 홈 기능의 예시이며 실제 작업 대상에 맞게 바꾼다.
```bash
./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
```
사용자가 직접 실행하는 전체 검증 명령:
```bash
./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의 자동 힙 산정은 별개다.
```bash
./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`을 맞춘다.
```bash
./gradlew --no-daemon dependencyInsight --dependency org.apache.httpcomponents --configuration runtimeClasspath
./gradlew bootJar
```