Files
clean-architecture-backend-…/docs/improvement/06-performance.md
T
DongHyeonka 3b66358e52 docs(improvement): 리뷰·개선 작업 매뉴얼을 만든다
문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때
기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰
기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가
가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰
문서 여러 곳에 흩어져 있다.

방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은
다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md,
TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다.
정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함
정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션
분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에
「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와
docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다.
버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용
가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접
쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다).

위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지
않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소
밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드
표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로
넣기)는 [제안]으로 표시했다.

검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절
번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖
가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는
DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로
둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
2026-11-05 21:59:44 +09:00

9.7 KiB

06. 성능·최적화 기준

핵심

숫자 없이 최적화하지 않는다. 같은 조건에서 전과 후를 잰다. 바꾼 것 외의 변수가 같아야 두 숫자를 비교할 수 있다.

이 템플릿에는 지연·처리량 목표가 없다. 그래서 "빠르다/느리다" 대신 요청당 비용(SQL 수, 지연, 처리량, CPU)과 그 비용이 데이터 수에 비례해 늘어나는지로 판정한다(1101/09-performance-measurement.md 1절 「규모 목표」).

기준선 측정 ──> 원인 좁히기 ──> 변경 하나 ──> 같은 조건 재측정 ──> 회귀 테스트로 고정 ──> lane 단계 지정
 (2·3절)        (3절)          (7절)        (5절)               (6절)                (07장)

1. 무엇을 재나

지표 재는 법 결함 신호 지난 예
아티팩트 bootJar 크기, BOOT-INF/lib jar 목록 운영 jar에 테스트용·중복 라이브러리 1101/09-09(H2), 1101/09-11(Jackson 2·3)
기동 Started … in 시간, 기동 3초 뒤 RSS·heap, 빈 수, 스레드 수 빈 수에 비해 긴 공백 한 곳 1101/09-performance-measurement.md 3.1절(공백이 한 곳에 몰리지 않아 결함 아님)
요청당 SQL 수 PG log_statement='all'로 요청 하나 전후의 문장 수 페이지 크기에 비례(N+1) 1101/09-01(20건 46개, 100건 206개)
지연·처리량 닫힌 루프 부하, p50·p95·p99·rps 단건 대비 목록 처리량이 SQL 수 비율만큼 떨어짐 1101/09-performance-measurement.md 3.3절
요청당 CPU JFR settings=profile, 상위 프레임 소유자 한 라이브러리가 CPU의 큰 몫 같은 문서 3.5절(목록에서 Hibernate 31%)
데이터 증가에 따른 변화 같은 요청을 행 수를 늘려 반복 행 수에 비례해 느려짐(순차 스캔) 1101/09-02
게이트·테스트 시간 게이트별 rc·초, 테스트 결과 XML 합계 바뀐 것이 없는데 매번 다시 도는 lane 1101/08-02

2. 측정 위치와 조건

측정은 무거운 실행이다. 위치는 07장 「소유자 환경」을 따른다. 조건은 1101/09-performance-measurement.md 「측정 조건」을 기준으로 한다.

조건 기준 이유
머신 다른 빌드가 돌지 않는 머신. 측정 직전 load average(1분)를 회차마다 적는다. 15를 넘은 회차는 "부하 높음"으로 표시하고 비교에 쓰지 않는다 기동 시간이 머신 부하에 따라 ±20% 움직였다(같은 문서 3.1절)
JVM 옵션을 고정하고 적는다. 예: -Xmx1g -XX:+ExitOnOutOfMemoryError, G1 기본 호스트에서 MaxRAMPercentage=75는 22 GiB 힙이 된다. 1 GiB 컨테이너에 가까운 값을 골랐다
DB 자원을 제한한 컨테이너(예: postgres:16-alpine, --cpus 4 --memory 1g), 튜닝 없음 DB 자원이 달라지면 앱 변경 효과를 가린다
데이터 행 수를 정해 적는다(예: work_log 10,000행). 측정 중 늘어나는 테이블은 행 수를 함께 적는다 poster가 측정 중 23,071행까지 늘어 처리량이 회차마다 떨어졌다(같은 문서 3.3절)
부하 생성 닫힌 루프 N 스레드, 앞 20% 워밍업 버림, 생성기가 같은 호스트면 한계로 적는다 wrk·hey가 없어 JDK HttpClient로 만든 생성기를 썼다
반복 3회 반복, 중앙값. 튀는 회차는 이유와 함께 적고 비교에서 뺀다 같은 문서 3.3절(334 rps로 튄 회차를 비교에 쓰지 않음)
캐시 애플리케이션 캐시 상태, DB 버퍼 캐시 상태(워밍업 뒤)를 적는다

3. 측정 방법

다시 재는 명령은 1101/09-performance-measurement.md 「측정 명령 (다시 돌리는 법)」에 있다. 요약:

  • SQL 수: PG에서 alter system set log_statement='all' → 요청 하나 → 로그의 statement·execute 줄 수 → 측정 뒤 'none'으로 되돌림. 앱 설정을 바꾸지 않는다.
  • 부하: 같은 요청을 동시성 N으로 15초, 앞 3초 버림.
  • CPU: 부하 중 jcmd <pid> JFR.start … duration=20s → jfr print --events jdk.ExecutionSample로 상위 프레임 집계.
  • 설정만 바꾼 실험: 코드는 그대로 두고 시스템 프로퍼티 하나만 바꾼다. 예: -Dspring.jpa.properties.hibernate.default_batch_fetch_size=100만으로 목록 처리량이 2.9배가 됐다(같은 문서 3.4절). 코드를 바꾸기 전에 설정으로 원인을 확인한다.

측정 스크립트(run-app.sh, Load.java, sqlcount.sh)는 그때 scratchpad에 두었고 repo에는 없다. 다시 재려면 위 문서의 명령으로 다시 만든다. [제안] 다음 성능 라운드에서 스크립트를 scripts/perf/로 넣을지 소유자가 정한다.

4. 기준선

기준선은 잰 커밋과 함께만 쓴다. 아래 숫자는 현재 HEAD에서 다시 잰 값이 아니다. 성능 작업을 시작하면 현재 커밋에서 다시 재고 이 표와 비교한다.

측정 값 커밋·출처
기본 조합 bootJar / 기동 중앙값 / 빈 수 41.4 MB / 3.44 s / 407 01a8a2a70, 1101/09-performance-measurement.md 3.1절
샘플 bootJar / 기동 중앙값 / 빈 수 99.0 MB / 8.05 s / 603 같음
필터 체인만 지나는 요청 27,130 rps, p50 0.51 ms 같은 문서 3.4절 (d)
샘플 단건 조회 5,521 rps, p50 2.70 ms, SQL 7개 같은 문서 3.2·3.3절
샘플 목록 20건 829 rps, p50 15.54 ms, SQL 46개 같음(수정 전)
샘플 목록 20건(09-01 수정 뒤) SQL 46 → 6, 765 → 2,528 rps 1101 README 14절 r2-09(묶음 보고 — E0, 다시 재지 않음)
관측 기능 비용 처리량 약 3% 같은 문서 3.4절 (b)
가상 스레드 처리량 차이 없음(병목은 커넥션 10개와 DB 왕복) 같은 문서 3.3절
게이트 시간(desktop, 12코어·31GB) ci+verifyDependencyLocks 5분 42초, mainCheck 8분 8초, integrationCheck 17분 10초 2c692554, 1103 README 17.2절

5. 결과를 믿을 조건

  • 커밋 외 변수가 하나다. 전후 측정이 같은 머신·JVM 옵션·DB 자원·데이터·동시성에서 나왔다.
  • 반복과 중앙값이 있다. 1회 측정은 비교 근거가 아니다.
  • 부하가 기록돼 있다. 회차마다 직전 load average.
  • 측정은 E3다. 실험실 결과이고 운영 증거가 아니다(02장 4절). "운영에서 N배 빨라진다"고 쓰지 않는다.
  • 성능 단언을 켠 상태로 돌렸다. 일부 performance lane은 시간 단언을 performance.assertions.enabled 속성으로 켠다. workflow는 이 값을 true로 준다(.github/workflows/integration-main.yml:198). leaf마다 기본값이 다르다: httpclient lane은 false(src/adapter/outbound/httpclient/build.gradle:196-197), persistence-mongo lane은 true (src/adapter/outbound/persistence-mongo/build.gradle:243-244). desktop에서 performanceCheck를 돌릴 때는 workflow와 같게 -Pperformance.assertions.enabled=true를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다.
  • 꼬리 지연의 원인을 확인하지 않았으면 그렇게 적는다. 예: SQL을 46 → 8로 줄여도 p95가 그대로였고, TCP delayed ACK가 의심되지만 확인하지 않았다(같은 문서 3.4절 — 미검증으로 기록).

6. 회귀를 막는 법

숫자는 다음 변경에서 다시 나빠진다. 고친 비용은 테스트로 고정한다.

장치 무엇을 고정하나 단계
요청당 SQL 수 단언 목록 20건과 100건의 문장 수가 같음, 제목만 바꾸는 PATCH가 컬렉션 행을 건드리지 않음, batch 생성이 JDBC batch로 감 — src/sample-portfolio/src/systemTest/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/WorkLogStatementCostSystemTest.java sample systemTest(mainCheck)
자원 한계 lane Tomcat·Jetty 부하·느린 클라이언트·종료(adapter/inbound/web performanceTest, webJettyPerformanceTest), HTTP client 풀·스트리밍·재시도(httpClientPerformanceTest), Hikari 풀(jpaPlatformPoolContractTest) performanceCheck(main·nightly)
마이크로 벤치마크 JMH source set(src/messaging/messaging-kafka/src/jmh, src/messaging/messaging-testkit/src/jmh, src/adapter/outbound/httpclient/src/jmh) 명시 실행
  • 시간 단언은 다른 빌드가 돌지 않는 머신에서만 의미가 있다. 그래서 performance lane은 PR·main 단계가 아니라 performanceCheck에 있다(src/build.gradle performanceCheck 위 주석).
  • SQL 수·호출 수처럼 머신과 무관한 숫자를 먼저 고정한다. 시간보다 덜 흔들린다.

7. 최적화를 고르는 순서

비용이 작은 개선부터 비교한다(가이드 31절 「비용이 작은 개선부터 비교」).

  1. 설정: 이미 열린 설정 키로 해결되는지 본다(default_batch_fetch_size처럼).
  2. DB: 인덱스·유일 제약·쿼리 모양. 순차 스캔은 인덱스로(1101/09-02). 중복 규칙은 DB 유일 제약 하나로 느린 검사 쿼리와 동시 중복을 함께 없앤다.
  3. 매핑·쿼리 코드: N+1, 불필요한 컬렉션 재작성(1101/09-06), 트랜잭션마다 생기는 왕복(1101/09-05).
  4. 구조: 캐시·비동기·새 인프라는 마지막이다. 캐시를 넣으면 무효화·경합을 함께 검증해야 한다(1101/05-04).

지금 이해하면 되는 것

  • 목표가 없는 템플릿이라 "요청당 비용"과 "데이터 수 비례"로 판정한다.
  • 기준선은 잰 커밋과 함께만 쓰고, 측정 조건(부하·JVM·DB·데이터·반복)을 같이 적는다.
  • 고친 비용은 SQL 수 같은 머신 무관 숫자로 먼저 고정한다. performance lane은 단언 속성을 켜고 돌린다.