문법 이후의 백엔드 엔지니어링
요청 한 건을 소켓에서 JVM, Spring proxy, transaction, connection, 외부 결제까지 추적한다. 추측 대신 코드로 깨뜨리고, metric으로 측정하고, release gate로 복구한다.
읽기 전에
읽는 문서가 아니라, 같은 commerce service를 네 번 통과하는 작업 지시서다.
빈 종이에 책임, thread, proxy, transaction, connection 경계를 그린다.
고정된 명령과 테스트로 정상 경로와 실패를 직접 관찰한다.
SLO, 보안, 관측, 복구, 배포 gate를 증거와 함께 제출한다.
COMPANION REPOSITORY
Java 21 LTS + Spring Boot 4.1.0 + Gradle 9.6.1을 고정했다. Gradle을 택한 이유는 wrapper, toolchain, dependency locking, test suite 분리가 이 교육 저장소의 재현성 요구에 직접 맞기 때문이다.
고정 스택
clean install
macOS/Linux: cd lab && ./gradlew clean check · Windows: cd lab; .\gradlew.bat clean check검증 층
P00—P10
각 모듈은 이전 코드를 버리지 않는다. 최소 경로를 만들고, 깨뜨리고, 단단하게 만든다.
JVM은 Java 소스가 아니라 class file의 명령을 실행한다. class는 loading 뒤 verification·preparation·resolution을 포함한 linking을 거쳐 initialization되며, JIT와 GC 정책은 JVM 구현의 영역이다.
Oracle · JLS 12장 · 실행 ↗Oracle · JVMS Java SE 21 ↗0–4
4–8
8–12
frame·heap·metaspace·allocation·GC root를 한 호출 위에 표시한다.
Oracle · JVMS Java SE 21 ↗12–15
happens-before와 platform/virtual thread를 CPU·memory limit과 연결한다.
Oracle · JLS 17장 · 스레드와 메모리 모델 ↗Oracle · Java 21 Thread API · 가상 스레드 ↗Application class loader가 OrderApplication의 binary representation을 찾고 VM이 검증한 뒤 static initializer를 실행한다.
Oracle · JLS 12장 · 실행 ↗각 method invocation은 frame을 만들며 operand stack과 local variables를 사용한다. heap과 method area의 실제 배치는 구현 세부다.
Oracle · JVMS Java SE 21 ↗가시성·순서 보장은 program order, monitor unlock/lock, volatile write/read, thread start/join 같은 happens-before edge에서 나온다.
Oracle · JLS 17장 · 스레드와 메모리 모델 ↗Java 21 virtual thread는 I/O 대기가 많은 task에 적합하며 장시간 CPU 집약 task용이 아니다.
Oracle · Java 21 Thread API · 가상 스레드 ↗final class P00BytecodeUnitTest {
record OrderId(long value) {}
static long unwrap(OrderId id) { return id.value(); }
@org.junit.jupiter.api.Test
void recordCompilesToJvmMethods() {
org.assertj.core.api.Assertions.assertThat(unwrap(new OrderId(42))).isEqualTo(42);
}
}test 뒤 javap -c -v로 constructor, accessor, invocation bytecode와 class-file version을 확인한다.
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75.0",
"-XX:+ExitOnOutOfMemoryError", "-jar", "/app/app.jar"]현재 Dockerfile은 heap 밖의 metaspace, code cache, thread stack, direct buffer, native memory를 위해 container memory의 25%를 남기고 OOM에서 즉시 종료한다.
75%는 현재 container fixture의 시작값이며 실제 RSS·OOM·GC 자료로 조정한다.
Oracle · JDK Flight Recorder 런타임 가이드 ↗record도 class의 한 종류이며 value accessor 호출은 JVM method invocation으로 실행된다.
Oracle · JVMS Java SE 21 ↗escape analysis 결과를 소스만 보고 단정하지 말고 JFR allocation sample과 필요한 경우 JIT 진단으로 확인한다.
Oracle · JDK Flight Recorder 런타임 가이드 ↗compileJava evidence에는 선택된 JDK 21 compiler와 build/classes 산출물 경로가 있어야 한다.
Gradle · Gradle 빌드 생명주기 ↗POST /api/v1/orders의 allocation은 orderId와 traceId로 표시한 JFR window에서 찾는다.
Oracle · JDK Flight Recorder 런타임 가이드 ↗container memory kill과 Java heap OOM을 같은 사건으로 분류하지 않고 exit reason, RSS, heap를 함께 기록한다.
./gradlew failureTestP00MemoryCeilingFailureTest는 현재 Java 실행 파일을 교차 플랫폼 방식으로 찾아 작은 heap child process의 non-zero exit를 assertion한다.
Oracle · JDK Flight Recorder 런타임 가이드 ↗unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p00 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 allocation rate·GC pause·RSS다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗heap/JFR/dump 파일에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 jvm.memory, jvm.gc.pause, process.memory, allocation profile다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew --version./gradlew classes && javap -c build/classes/java/main/dev/productionlab/commerce/CommerceApplication.class./gradlew failureTestJava는 primitive 값과 reference 값을 모두 값으로 전달한다. reference를 전달해도 변수 자체는 복사되며, equals와 hashCode는 hash collection의 정확성에 직접 연결된다.
Oracle · JLS 17장 · 스레드와 메모리 모델 ↗Oracle · Object equals/hashCode 계약 ↗0–4
primitive/reference, pass-by-value, String immutability를 묶는다.
Oracle · Object equals/hashCode 계약 ↗4–8
equals/hashCode, mutable key, collection 복잡도, generics erasure 경계를 표시한다.
Oracle · Java 21 Collections Framework ↗Oracle · Object equals/hashCode 계약 ↗8–12
checked/unchecked, Optional, enum/record/sealed type을 API 실패 모델과 연결한다.
Oracle · Object equals/hashCode 계약 ↗12–15
Instant, ZoneId, BigDecimal+Currency, rounding policy를 경계에 둔다.
Oracle · java.time 패키지 ↗generic type argument는 대체로 erasure 후 runtime class에 남지 않으므로 unchecked cast가 type safety를 우회할 수 있다.
Oracle · JVMS Java SE 21 ↗List<Integer>는 List<Number>의 subtype이 아니다. 값을 읽는 producer는 ? extends T, 값을 받는 consumer는 ? super T로 경계를 표현하며 wildcard capture가 필요하면 helper method로 type parameter를 이름 붙인다.
Oracle · dev.java · Generic wildcard와 PECS ↗HashMap 같은 hash 기반 collection은 key가 들어간 뒤 equality/hash 결과가 변하면 lookup 계약을 유지할 수 없다.
Oracle · Java 21 Collections Framework ↗Oracle · Object equals/hashCode 계약 ↗Stream pipeline은 terminal operation이 시작될 때 traversal하며 side effect와 encounter order는 operation 계약을 읽어야 한다.
Oracle · Java 21 Collections Framework ↗record Sku(String value) {
Sku { if (value == null || value.isBlank()) throw new IllegalArgumentException("sku"); }
}
record Quantity(int value) {
Quantity { if (value < 1) throw new IllegalArgumentException("quantity"); }
}
record Money(java.math.BigDecimal amount, java.util.Currency currency) {
Money {
if (amount == null || currency == null || amount.signum() < 0) {
throw new IllegalArgumentException("money");
}
}
}record constructor에서 null·범위를 막고 통화 없는 소수를 금액으로 전달하지 않는다.
sealed interface OrderDecision permits Accepted, Rejected {}
record Accepted(java.time.Instant acceptedAt) implements OrderDecision {}
record Rejected(String code) implements OrderDecision {}
java.time.Clock clock = java.time.Clock.fixed(
java.time.Instant.parse("2026-01-01T00:00:00Z"),
java.time.ZoneOffset.UTC);
OrderDecision decision = new Accepted(clock.instant());sealed result는 성공/거절 처리를 exhaustively 만들고 Clock 주입은 시간 test를 결정적으로 만든다.
record component 기반 equality는 값 객체에 적합하지만 entity identity와 같은 개념은 아니다.
Oracle · Object equals/hashCode 계약 ↗금액 scale·rounding·통화 허용 목록은 결제 계약에 고정하고 암묵적 반올림을 금지한다.
contract test는 JSON sku/quantity/amount의 역직렬화 뒤 domain value constructor 재검증을 요구한다.
reference argument는 복사되지만 mutable object의 동일한 state를 가리킬 수 있으므로 defensive copy 경계가 필요하다.
Oracle · Object equals/hashCode 계약 ↗acceptedAt은 server Clock의 Instant로 생성하고 client timezone은 저장 상태에 섞지 않는다.
API error에는 안정된 code와 안전한 message만 노출하고 exception class/stack은 외부에 내보내지 않는다.
Spring · Spring Security · Servlet Architecture ↗./gradlew failureTestP01LanguageContractsTest는 insert 뒤 key를 변경하면 같은 instance의 Map.get이 null이 되는 실패를 재현한다.
Oracle · Object equals/hashCode 계약 ↗Oracle · Java 21 Collections Framework ↗unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p01 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 Stream/loop allocation, serialization payload, CPU다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗금액·시간·오류 message에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 order.validation.rejected와 error.code cardinality다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew unitTest./gradlew failureTest./gradlew contractTestGradle은 initialization, configuration, execution 단계에서 task graph를 만들고 실행한다. BOM은 version 정렬을 돕지만 plugin, repository, lock, toolchain, generated source까지 자동 고정하지 않는다.
Gradle · Gradle 빌드 생명주기 ↗Gradle · Platform/BOM 정렬 ↗0–4
4–8
configuration, transitive dependency, conflict resolution, BOM constraint를 그린다.
Gradle · Platform/BOM 정렬 ↗8–12
annotation processor, test fixture, multi-module boundary가 compile classpath에 미치는 영향을 확인한다.
Gradle · Gradle 빌드 생명주기 ↗12–15
Wrapper, toolchain, repository, verification metadata, dependency locks, clean CI를 한 gate로 묶는다.
Gradle · Dependency Locking ↗settings.gradle.kts가 project graph를 정의하고 build script가 task/model을 구성한 뒤 요청 task와 dependency만 실행된다.
Gradle · Gradle 빌드 생명주기 ↗implementation은 main compile/runtime graph에, testImplementation은 test compile/runtime graph에 참여한다. runtime classpath는 compile classpath와 같다고 가정할 수 없다.
Gradle · Gradle 빌드 생명주기 ↗현재 capstone은 package-by-feature 단일 deployable로 시작한다. 독립 build/release 또는 강제 compile boundary가 필요할 때만 subproject를 추가한다.
Gradle · Gradle 빌드 생명주기 ↗plugins {
java
id("org.springframework.boot") version "4.1.0"
}
java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }
dependencies {
implementation(platform("org.springframework.boot:spring-boot-dependencies:4.1.0"))
implementation("org.springframework.boot:spring-boot-starter-webmvc")
testImplementation("org.springframework.boot:spring-boot-starter-test")
}plugin, Java toolchain, BOM을 명시한다. 실제 resolved version은 dependency report와 lock으로 검증한다.
commerce-lab은 Java 21, Spring Boot BOM 4.1.0, Gradle Wrapper 9.6.1을 고정한다.
Gradle · Platform/BOM 정렬 ↗dependencyLocking { lockAllConfigurations() }
fun taggedTest(name: String, tag: String) = tasks.register<Test>(name) {
testClassesDirs = sourceSets.test.get().output.classesDirs
classpath = sourceSets.test.get().runtimeClasspath
useJUnitPlatform { includeTags(tag) }
shouldRunAfter(tasks.test)
}
val integrationTest = taggedTest("integrationTest", "integration")
val contractTest = taggedTest("contractTest", "contract")
val concurrencyTest = taggedTest("concurrencyTest", "concurrency")
val failureTest = taggedTest("failureTest", "failure")
tasks.check {
dependsOn(integrationTest, contractTest, concurrencyTest, failureTest)
}빠른 unit과 외부 resource integration을 분리하되 check가 둘 다 요구하게 만든다.
test 이름이 아니라 task graph로 CI gate를 표현하고 lock 변경을 review한다.
Gradle · Dependency Locking ↗annotation processor는 implementation과 분리해 compile classpath 누출과 cache miss 원인을 줄인다.
Gradle · Gradle 빌드 생명주기 ↗./gradlew clean check는 Wrapper distribution을 확인하고 unit→integration→contract→concurrency→failure gate를 모두 실행하도록 구성한다.
Gradle · Gradle 빌드 생명주기 ↗dependency graph resolution은 repository metadata, constraint, conflict rule, lock state로 최종 artifact를 선택한다.
Gradle · Dependency Locking ↗Gradle · Platform/BOM 정렬 ↗CI는 cache를 써도 clean checkout에서 check를 실행하며 lock 또는 verification metadata 변경을 별도 review한다.
macOS의 ./gradlew와 Windows의 gradlew.bat를 모두 문서화하고 개인 JDK 경로를 build script에 넣지 않는다.
Gradle · Gradle 빌드 생명주기 ↗./gradlew --dependency-verification strict verifyReproducibilityFiles dependencies --configuration runtimeClasspathclean check는 metadata 존재와 strict resolution을 gate로 둔다. destructive drift injection은 저장소 원본이 아닌 disposable copy에서 수행한다.
Gradle · Dependency Locking ↗unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p02 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 configuration time, task cache hit, clean build duration다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗dependency repository·plugin·artifact provenance에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 build scan 없이도 남는 task duration·cache state·dependency report다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew clean check --no-daemon./gradlew dependencies --write-locks./gradlew javaToolchainsIoC container는 configuration metadata를 읽어 BeanDefinition을 만들고 bean을 생성·연결한다. AOP 기능은 일반적으로 원본 객체 주위의 proxy가 MethodInterceptor chain을 실행해 제공한다.
Spring · Spring Framework · 컨테이너와 Bean ↗Spring · Spring AOP · 프록시 메커니즘 ↗0–4
scan/import/configuration → BeanDefinition registry를 그린다.
Spring · Spring Framework · 컨테이너와 Bean ↗4–8
constructor injection → populate → aware/callback → post-process 순서를 표시한다.
Spring · Spring Framework · 생명주기 콜백 ↗8–12
12–15
caller → proxy → interceptor chain → target → return/throw 경로를 말한다.
Spring · Spring AOP · 프록시 메커니즘 ↗ApplicationContext refresh 중 BeanFactory post-processors가 definition을 수정하고 BeanPostProcessor가 bean instance initialization 전후에 개입한다.
Spring · Spring Framework · 컨테이너와 Bean ↗Spring · Spring Framework · 생명주기 콜백 ↗@Configuration class는 bean method 간 호출 semantics를 보존하기 위해 runtime enhancement 대상이 될 수 있다. proxyBeanMethods=false는 그 inter-bean 호출을 요구하지 않는 구성에 적합하다.
Spring · Spring Framework · 컨테이너와 Bean ↗Spring AOP는 interface가 있으면 JDK dynamic proxy를 사용할 수 있고 class proxy는 subclassing 제약(final class/method 등)을 받는다.
Spring · Spring AOP · 프록시 메커니즘 ↗constructor cycle은 책임이 얽혔다는 architecture signal로 취급하고 port/event/orchestrator 경계를 재검토한다.
Spring · Spring Framework · 컨테이너와 Bean ↗@org.springframework.stereotype.Service
public class OrderApplicationService {
public OrderApplicationService(
IdempotencyStore idempotencyStore,
InventoryService inventoryService,
OrderRepository orderRepository,
PaymentRepository paymentRepository,
OutboxRepository outboxRepository,
Clock clock,
MeterRegistry registry) {
// Assign every mandatory dependency explicitly.
}
}parameter가 dependency graph를 드러내며 test에서 같은 class를 Spring 없이 생성할 수 있다.
필수 dependency는 constructor로 표현하고 null/field injection을 허용하지 않는다.
Spring · Spring Framework · 컨테이너와 Bean ↗@org.junit.jupiter.api.Tag("integration")
class P03ProxyIntegrationTest extends PostgresIntegrationTest {
@org.springframework.beans.factory.annotation.Autowired OrderApplicationService service;
@org.junit.jupiter.api.Test
void reportsRuntimeType() {
assertThat(org.springframework.aop.support.AopUtils.isAopProxy(service)).isTrue();
assertThat(org.springframework.aop.support.AopUtils.getTargetClass(service))
.isEqualTo(OrderApplicationService.class);
assertThat(service).isInstanceOf(org.springframework.aop.framework.Advised.class);
var advised = (org.springframework.aop.framework.Advised) service;
assertThat(advised.getAdvisors()).isNotEmpty();
}
}runtime proxy, target class, transaction advisor를 분리해 현재 wiring을 test artifact로 남긴다.
proxyBeanMethods=false는 @Bean method를 직접 여러 번 호출해도 container singleton lookup으로 바꾸지 않는다.
Spring · Spring Framework · 컨테이너와 Bean ↗proxy 여부를 class 이름 문자열로 판단하지 말고 Spring AopUtils와 advisor inspection을 사용한다.
Spring · Spring AOP · 프록시 메커니즘 ↗component scan 또는 @Import가 OrderConfiguration을 candidate로 등록하고 parser가 @Bean method를 BeanDefinition으로 만든다.
Spring · Spring Framework · 컨테이너와 Bean ↗BeanFactory가 repository와 inventory dependency를 먼저 resolve하고 constructor/factory method로 service target을 만든다.
Spring · Spring Framework · 컨테이너와 Bean ↗auto-proxy creator 역할의 BeanPostProcessor가 matching advisor를 찾아 proxy를 container에 반환한다.
Spring · Spring AOP · 프록시 메커니즘 ↗controller가 주입받는 reference의 target/proxy/advisor를 integration test artifact로 기록한다.
Spring · Spring AOP · 프록시 메커니즘 ↗./gradlew failureTestunit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p03 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 bean count, startup steps, proxy invocation overhead다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗application context와 injected port에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 startup failure root cause, bean count, runtime target/proxy class다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew integrationTest./gradlew failureTestrg -n '@Autowired[[:space:]]+(private|protected|public)' src/main/javaSpring Boot auto-configuration은 classpath, bean, property 같은 조건이 맞을 때 configuration을 import한다. starter는 dependency 묶음이고 실행 주체가 아니다.
Spring · Spring Boot · Auto-configuration ↗0–4
main → SpringApplication → Environment → context type을 연결한다.
Spring · Spring Boot · Auto-configuration ↗4–8
imports → condition evaluation → user bean back-off를 표시한다.
Spring · Spring Boot · Auto-configuration ↗8–12
12–15
started/ready, liveness/readiness, SIGTERM/grace period를 분리한다.
Spring · Spring Boot Actuator · Kubernetes Probes ↗Spring · Spring Boot · Graceful Shutdown ↗SpringApplication은 Environment를 준비하고 ApplicationContext를 만들고 refresh한 뒤 runner와 ready event를 진행한다.
Spring · Spring Boot · Auto-configuration ↗@ConditionalOnMissingBean 같은 조건은 user configuration을 존중해 auto-config bean을 back off할 수 있다. condition report가 선택 근거다.
Spring · Spring Boot · Auto-configuration ↗외부 설정 source에는 정해진 우선순위가 있으며 뒤 source가 앞 값을 override할 수 있다. secret이 안전해지는 규칙은 아니다.
Spring · Spring Boot · 외부 설정 ↗graceful shutdown은 context close의 SmartLifecycle stop phase에서 기존 요청에 grace를 주고 새 요청을 거부한다.
Spring · Spring Boot · Graceful Shutdown ↗startup probe는 느린 시작 동안 liveness failure가 restart loop를 만들지 않도록 초기 생존 판정을 지연한다. Boot가 자동 노출하는 liveness/readiness group과 platform의 startupProbe 설정은 별도 경계다.
Spring · Spring Boot Actuator · Kubernetes Probes ↗@org.springframework.boot.context.properties.ConfigurationProperties("commerce")
@org.springframework.validation.annotation.Validated
record CommerceProperties(
@jakarta.validation.Valid Security security,
@jakarta.validation.Valid Payment payment,
@jakarta.validation.Valid Outbox outbox) {
record Payment(
@jakarta.validation.constraints.NotBlank String baseUrl,
@jakarta.validation.constraints.NotNull java.time.Duration connectTimeout,
@jakarta.validation.constraints.NotNull java.time.Duration readTimeout,
@jakarta.validation.constraints.Min(1) int maxConcurrent,
@jakarta.validation.constraints.Min(1) int circuitFailureThreshold,
@jakarta.validation.constraints.NotNull java.time.Duration circuitOpenDuration) {}
}문자열 lookup을 흩뿌리지 않고 type, prefix, startup validation을 한 경계에 둔다.
필수 operational setting은 binding 실패 시 startup을 중단한다.
Spring · Spring Boot · 외부 설정 ↗spring:
lifecycle:
timeout-per-shutdown-phase: 20s
server:
shutdown: graceful
commerce:
payment:
connect-timeout: 500ms
read-timeout: 800ms
management:
endpoint:
health:
probes:
enabled: trueprobe는 traffic routing 신호, shutdown timeout은 종료 budget이다. 값은 SLO와 platform termination grace보다 작게 검증한다.
connect 500ms/read 800ms/shutdown 20s는 capstone fixture용 값이며 production 측정으로 재설정한다.
Spring · Spring Boot Actuator · Kubernetes Probes ↗Spring · Spring Boot · Graceful Shutdown ↗@ConfigurationProperties는 relaxed binding을 지원하지만 알 수 없는/누락된 값 처리 정책은 validation과 type 설계에 달려 있다.
Spring · Spring Boot · 외부 설정 ↗liveness에 DB·payment를 넣어 dependency 장애가 전체 pod restart storm으로 번지게 하지 않는다.
Spring · Spring Boot Actuator · Kubernetes Probes ↗main이 SpringApplication.run을 호출하고 command-line, system property, environment, file 등의 property source를 Environment에 결합한다.
Spring · Spring Boot · 외부 설정 ↗auto-configuration import selector가 candidate를 찾고 condition outcome으로 적용/제외한다.
Spring · Spring Boot · Auto-configuration ↗learner startup artifact는 embedded Tomcat connector 시작과 ApplicationReadyEvent 뒤 readiness 전환을 별도 timeline으로 기록한다. 현재 자동 test는 health 접근 제어만 검증한다.
Spring · Spring Boot 4.1.0 시스템 요구사항 ↗Spring · Spring Boot Actuator · Kubernetes Probes ↗SIGTERM은 context close와 graceful shutdown을 시작하며 grace 뒤 남은 lifecycle phase가 종료된다.
Spring · Spring Boot · Graceful Shutdown ↗./gradlew failureTestConfigurationBindingFailureTest는 commerce.payment.read-timeout=fast를 넣고 ApplicationContextRunner startup failure의 property 이름을 assertion한다.
Spring · Spring Boot · 외부 설정 ↗unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p04 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 startup duration, bean count, readiness transition, shutdown drain다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗Environment·Actuator endpoint·config origin에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 condition report, startup step, availability state, shutdown timeout다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew failureTest --tests '*ConfigurationBindingFailureTest'./gradlew contractTest./gradlew failureTestServlet container가 request/response를 만들고 filter chain을 호출한 뒤 DispatcherServlet이 handler mapping, adapter, argument resolution, controller, exception resolution, message conversion을 조정한다.
Jakarta · Jakarta Servlet · Filter ↗Spring · Spring MVC · DispatcherServlet ↗0–4
socket → Tomcat connector → request thread → servlet filter를 그린다.
Jakarta · Jakarta Servlet · Filter ↗Spring · Spring Boot 4.1.0 시스템 요구사항 ↗4–8
DelegatingFilterProxy → SecurityFilterChain → authentication/authorization을 구분한다.
Spring · Spring Security · Servlet Architecture ↗8–12
DispatcherServlet → mapping → interceptor → resolver/validation → controller를 배치한다.
Spring · Spring MVC · DispatcherServlet ↗12–15
service/repository → serialization 또는 exception handler → error contract를 연결한다.
Spring · Spring MVC · DispatcherServlet ↗Servlet Filter는 DispatcherServlet 앞/뒤를 감싸고 Spring Security는 FilterChainProxy 내부에서 선택된 SecurityFilterChain을 실행한다.
Jakarta · Jakarta Servlet · Filter ↗Spring · Spring Security · Servlet Architecture ↗HandlerMethodArgumentResolver가 header/body/path 값을 parameter로 만들고 validation 실패는 controller body 진입 전에 exception resolution으로 갈 수 있다.
Spring · Spring MVC · DispatcherServlet ↗HandlerExceptionResolver와 message converter가 status/header/body를 만들며 response가 commit된 뒤에는 error body를 안전하게 바꿀 수 없다.
Spring · Spring MVC · DispatcherServlet ↗client timeout·socket disconnect는 server transaction이나 payment call의 cancellation을 보장하지 않는다. request thread가 write 실패를 늦게 관찰할 수 있으므로 server-side deadline, idempotency, 명시적 cancellation propagation을 각각 검증한다.
Jakarta · Jakarta Servlet · Filter ↗Spring · Spring MVC · DispatcherServlet ↗API version은 URL/header/media type 중 하나를 명시적으로 고르고 pagination cursor는 stable ordering key를 포함한다.
Spring · Spring MVC · DispatcherServlet ↗@org.springframework.web.bind.annotation.RestController
@org.springframework.web.bind.annotation.RequestMapping("/api/v1/orders")
public final class OrderController {
private final OrderApplicationService service;
public OrderController(OrderApplicationService service) { this.service = service; }
@org.springframework.web.bind.annotation.PostMapping
org.springframework.http.ResponseEntity<OrderResponse> create(
@org.springframework.web.bind.annotation.RequestHeader("Idempotency-Key") String key,
@jakarta.validation.Valid @org.springframework.web.bind.annotation.RequestBody CreateOrderRequest body) {
var response = service.create(key, body);
return org.springframework.http.ResponseEntity.accepted()
.location(java.net.URI.create("/api/v1/orders/" + response.id()))
.body(response);
}
}version, idempotency key, validation, status를 HTTP boundary에 드러내고 business orchestration은 service에 둔다.
POST /api/v1/orders는 API key 인증과 100자 이하 Idempotency-Key를 요구한다.
Spring · Spring Security · Servlet Architecture ↗@org.springframework.web.bind.annotation.RestControllerAdvice
public final class ApiExceptionHandler {
@org.springframework.web.bind.annotation.ExceptionHandler(ConflictException.class)
org.springframework.http.ResponseEntity<org.springframework.http.ProblemDetail> conflict(
ConflictException exception, jakarta.servlet.http.HttpServletRequest request) {
return problem(org.springframework.http.HttpStatus.CONFLICT,
"conflict", exception.getMessage(), request);
}
}외부 계약은 안정된 status/code/title이며 내부 stack·SQL·secret을 response에 넣지 않는다.
exception taxonomy와 외부 error code를 분리한다.
Spring · Spring MVC · DispatcherServlet ↗@Valid는 Bean Validation provider와 MVC argument resolution을 통해 body constraint를 평가한다.
Spring · Spring MVC · DispatcherServlet ↗같은 key+같은 request hash는 기존 결과, 같은 key+다른 hash는 409를 반환한다.
Tomcat connector가 socket bytes를 HTTP request로 parse하고 worker thread가 servlet filter chain에 진입한다.
Jakarta · Jakarta Servlet · Filter ↗Spring · Spring Boot 4.1.0 시스템 요구사항 ↗CorrelationIdFilter는 유효한 correlation ID를 보존/생성하고 ApiKeyAuthenticationFilter는 principal을 만들어야 한다.
Spring · Spring Security · Servlet Architecture ↗DispatcherServlet이 OrderController method를 찾고 Idempotency-Key/body를 resolve·validate한 뒤 service proxy를 호출한다.
Spring · Spring MVC · DispatcherServlet ↗비동기 payment를 시작한 성공은 202 JSON, 동일 replay는 같은 order, hash conflict는 409 ProblemDetail이어야 한다.
Spring · Spring MVC · DispatcherServlet ↗./gradlew concurrencyTestconcurrency fixture는 check-then-act 구현을 깨고 constraint 기반 구현만 통과시켜야 한다.
unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p05 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 HTTP p95/p99, Tomcat threads, request/response bytes, disconnects다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗public HTTP boundary·API key·order ownership에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 http.server.requests, status/error.code, traceId/orderId correlation다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew contractTest./gradlew concurrencyTest./gradlew failureTest선언적 transaction은 proxy를 통과하는 method invocation에 transaction interceptor를 적용한다. persistence context는 managed entity의 identity와 변경을 추적하고 flush에서 SQL과 constraint 결과가 드러날 수 있다.
Spring · Spring · 선언적 트랜잭션 ↗Hibernate · Hibernate ORM · Persistence Context ↗0–4
4–8
transient/managed/detached/removed, identity map, dirty checking, flush를 잇는다.
Hibernate · Hibernate ORM · Persistence Context ↗8–12
lazy/eager, N+1, fetch join/entity graph, batch, optimistic/pessimistic lock을 배치한다.
Hibernate · Hibernate ORM · Fetching ↗Hibernate · Hibernate ORM · Locking ↗12–15
local commit+outbox → relay → payment → compensation/recovery를 그린다.
Spring · Spring · 선언적 트랜잭션 ↗TransactionInterceptor가 propagation에 따라 기존 transaction에 참여하거나 새 status를 만들고 정상/예외 반환 규칙에 따라 commit 또는 rollback을 요청한다.
Spring · Spring · 선언적 트랜잭션 ↗Spring · Spring · 롤백 규칙 ↗기본 declarative rollback 규칙은 RuntimeException/Error이며 checked exception은 명시 rule 없이 자동 rollback되지 않는다.
Spring · Spring · 롤백 규칙 ↗같은 persistence context에서 같은 entity identity는 같은 managed instance로 대응되고 dirty checking은 flush 전에 변경을 계산한다.
Hibernate · Hibernate ORM · Persistence Context ↗optimistic lock은 version 충돌을 감지하고 pessimistic lock은 database lock을 요청한다. 어느 쪽도 잘못된 business invariant를 대신 정의하지 않는다.
Hibernate · Hibernate ORM · Locking ↗InventoryService.Reservation reservation =
inventoryService.reserve(request.sku(), request.quantity());
CommerceOrder order =
new CommerceOrder(
idempotencyKey,
reservation.sku(),
reservation.quantity(),
reservation.unitPrice(),
reservation.currency().getCurrencyCode(),
now);
orderRepository.save(order);
Payment payment =
new Payment(
order.id(),
reservation.total(),
reservation.currency().getCurrencyCode(),
now);
paymentRepository.save(payment);
String payload =
"{\"orderId\":\"%s\",\"paymentId\":\"%s\","
+ "\"amount\":\"%s\",\"currency\":\"%s\"}"
.formatted(
order.id(), payment.id(), payment.amount(), payment.currency());
outboxRepository.save(
new OutboxEvent(
"ORDER", order.id(), "PAYMENT_REQUESTED", payload,
MDC.get("correlationId"), now));
orderRepository.flush();
idempotencyStore.complete(idempotencyKey, order.id(), now);idempotency, inventory reservation, order, payment intent, outbox row를 같은 local DB transaction에 둔다. payment network는 이 method 밖이다.
DB constraint를 최종 invariant로 두고 application check는 친절한 오류와 빠른 경로에 사용한다.
Spring · Spring · 선언적 트랜잭션 ↗@jakarta.persistence.Entity
class InventoryItem {
@jakarta.persistence.Id private java.util.UUID id;
@jakarta.persistence.Column(nullable = false, unique = true, length = 64)
private String sku;
private int available;
@jakarta.persistence.Version private long version;
private java.time.Instant updatedAt;
public void reserve(int quantity, java.time.Instant now) {
if (quantity <= 0) throw new IllegalArgumentException("quantity must be positive");
if (available < quantity) {
throw new BusinessRuleException("insufficient inventory for sku " + sku);
}
available -= quantity;
updatedAt = now;
}
}@Version update count가 0이면 concurrent write 충돌이다. retry는 새 transaction에서 invariant를 다시 읽고 제한적으로 수행한다.
self-invocation으로 create를 부르면 caller가 proxy 밖에 있어 transaction interceptor가 실행되지 않을 수 있다.
Spring · Spring AOP · 프록시 메커니즘 ↗Spring · Spring · 선언적 트랜잭션 ↗LAZY association은 transaction 밖 serialization에 기대지 말고 query별 DTO projection/fetch plan을 명시한다.
Hibernate · Hibernate ORM · Fetching ↗payment UNKNOWN은 실패와 구분하고 recovery가 idempotency key로 provider 상태를 조회한다.
controller가 service proxy를 호출하면 transaction interceptor가 connection-bound transaction을 시작한다.
Spring · Spring · 선언적 트랜잭션 ↗repository query가 persistence context/DB에서 entity를 managed state로 가져오고 inventory mutation은 dirty checking 대상이 된다.
Hibernate · Hibernate ORM · Persistence Context ↗flush에서 inventory version update, order insert, outbox insert와 unique/FK/check constraint가 확인되고 그 뒤 local commit한다.
별도 relay transaction이 outbox를 claim하고 payment adapter를 호출하며 timeout이면 UNKNOWN으로 남겨 조회 기반 recovery를 예약한다.
Spring · Spring · 선언적 트랜잭션 ↗./gradlew failureTest실패 test 전체가 release gate에 포함되어야 VERIFIED BEHAVIOR로 승격한다.
Spring · Spring · 선언적 트랜잭션 ↗Hibernate · Hibernate ORM · Fetching ↗Hibernate · Hibernate ORM · Locking ↗unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p06 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 SQL count/duration, flush batches, DB pool pending, lock wait/deadlock다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗entity/tenant ownership·DB credential·payment token에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 transaction duration, query count, pool acquire, outbox age, payment outcome다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew integrationTest./gradlew concurrencyTest./gradlew failureTestSpring MVC는 Servlet blocking contract 위에서 보통 request thread가 완료까지 흐른다. WebFlux는 non-blocking runtime과 reactive chain을 지원하지만 blocking call을 넣으면 event-loop 자원을 막을 수 있다.
Spring · Spring MVC · DispatcherServlet ↗Spring · Spring WebFlux · Reactive Core ↗0–4
request → servlet thread → blocking client/JDBC → response를 그린다.
Spring · Spring MVC · DispatcherServlet ↗4–8
event loop → Publisher assembly → subscribe → signals를 그린다.
Spring · Spring WebFlux · Reactive Core ↗Project Reactor · Reactor Core Reference ↗8–12
demand, queue, backpressure, blocking boundary와 context propagation을 표시한다.
Project Reactor · Reactor Core Reference ↗12–15
throughput, p99, memory, team debugging cost를 같은 표에서 비교한다.
Spring · Spring WebFlux · Reactive Core ↗MVC DispatcherServlet은 Servlet request lifecycle에서 handler를 호출하며 blocking repository/client와 직접 맞는다.
Spring · Spring MVC · DispatcherServlet ↗Reactor Publisher는 subscription 전에는 pipeline description이며 demand와 onNext/onError/onComplete signal로 실행된다.
Project Reactor · Reactor Core Reference ↗WebFlux는 작은 고정 event-loop를 전제하므로 blocking call은 감지·격리하거나 non-blocking driver로 끝까지 연결해야 한다.
Spring · Spring WebFlux · Reactive Core ↗JPA/JDBC 중심 modular monolith는 MVC가 더 단순하고 안전한 기본값이다. 높은 fan-out I/O와 non-blocking dependency가 입증될 때 WebFlux를 비교한다.
Spring · Spring WebFlux · Reactive Core ↗@org.springframework.web.bind.annotation.RestController
@org.springframework.web.bind.annotation.RequestMapping("/api/v1/orders")
final class OrderController {
private final OrderApplicationService service;
@org.springframework.web.bind.annotation.GetMapping("/{orderId}")
OrderResponse get(
@org.springframework.web.bind.annotation.PathVariable java.util.UUID orderId) {
return service.get(orderId);
}
}JPA-backed 동기 application service를 호출하는 MVC baseline이다.
capstone production 경로는 측정 전 MVC를 baseline으로 유지한다.
Spring · Spring MVC · DispatcherServlet ↗public Mono<OrderResponse> findById(UUID orderId) {
return databaseClient.sql(FIND_ORDER)
.bind("orderId", orderId)
.map((row, metadata) -> mapRow(row))
.all()
.collectList()
.filter(rows -> !rows.isEmpty())
.map(this::toResponse);
}독립 build가 기존 commerce schema를 한 번의 joined R2DBC query로 읽는다. 쓰기 경로를 이식하지 않으며 MVC보다 빠르다는 결론도 내리지 않는다.
동일 contract·row·connection cap·자원 제한으로 read path를 격리하고, 측정 결과를 write-heavy transaction 경로로 일반화하지 않는다.
Spring · Spring WebFlux · Reactive Core ↗Project Reactor · Reactor Core Reference ↗fromCallable은 subscription 때 callable을 실행하고 subscribeOn이 subscription/work 실행 scheduler를 지정한다.
Project Reactor · Reactor Core Reference ↗MDC/ThreadLocal correlation은 scheduler hop에서 자동 보존을 가정하지 말고 Reactor Context/관측 library integration을 test한다.
Spring · Spring Boot · Observability ↗MVC: Tomcat worker → controller → transaction proxy → JDBC wait → serializer → worker 반환.
Spring · Spring MVC · DispatcherServlet ↗WebFlux: event loop → handler Publisher → subscribe → non-blocking signals → encoder; blocking bridge가 있으면 별도 scheduler hop이 추가된다.
Spring · Spring WebFlux · Reactive Core ↗Project Reactor · Reactor Core Reference ↗비교 fixture는 동일 endpoint semantics, payload, DB rows, connection cap, CPU/memory limit, warm-up을 사용한다.
throughput만 보고 선택하지 않고 p99, RSS, queue saturation, cancellation, trace continuity, 코드 복잡도를 함께 판정한다.
Spring · Spring WebFlux · Reactive Core ↗./gradlew -p reactive-comparison test --tests '*BlockingBoundaryFailureTest'동일 workload 비교 결과를 저장한 뒤에만 선택을 VERIFIED BEHAVIOR로 기술한다.
Spring · Spring WebFlux · Reactive Core ↗unit
./gradlew -p reactive-comparison test --tests '*BlockingBoundaryFailureTest'증명 범위: single scheduler에서 blocking task 뒤 signal 지연
증명하지 않는 것: production event-loop 지연 분포 또는 BlockHound coverage
integration
./gradlew -p reactive-comparison --dependency-verification strict clean check증명 범위: 고정된 WebFlux·R2DBC·PostgreSQL 조합의 실제 기동과 read-only transaction
증명하지 않는 것: MVC 대비 latency·memory 우위
contract
./gradlew -p reactive-comparison test --tests '*OrderHttpContractIntegrationTest'증명 범위: 동일 order GET schema, 인증, 404/405, DB read-only 경계
증명하지 않는 것: write path 또는 payment workflow 호환성
load
k6 run -e TARGET=mvc -e ORDER_ID=<uuid> -e API_KEY=<key> scripts/p07-comparison.js증명 범위: 동일 seeded GET workload의 환경·error·p95/p99 JSON
증명하지 않는 것: 다른 workload나 write-heavy 서비스의 기술 선택
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 MVC threads vs event-loop delay, scheduler queue, p99, RSS다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗reactive Context·principal·cancellation boundary에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 event-loop delay, scheduler pending, context/trace continuity다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew contractTest./gradlew -p reactive-comparison test --tests '*BlockingBoundaryFailureTest'k6 run -e TARGET=reactive -e ORDER_ID=<uuid> -e API_KEY=<key> scripts/p07-comparison.jsExecutor는 task 제출과 실행을 분리하고 ExecutorService는 lifecycle을 갖는다. virtual thread는 값싼 대기 단위를 제공하지만 DB connection, remote rate limit, CPU capacity를 늘리지 않는다.
Oracle · ExecutorService API ↗OpenJDK · JEP 444 · Virtual Threads (Final) ↗0–4
4–8
Future completion/exception/cancel과 executor shutdown/awaitTermination을 잇는다.
Oracle · ExecutorService API ↗8–12
transaction/security/trace ThreadLocal이 async boundary에서 끊기는 위치를 표시한다.
Spring · Spring Boot · Task Execution and Scheduling ↗12–15
timeout → bounded retry+jitter → circuit/bulkhead → durable recovery를 그린다.
Oracle · ExecutorService API ↗ThreadPoolExecutor는 core/max worker, work queue, keep-alive, rejection policy 조합으로 admission을 결정한다.
Oracle · ExecutorService API ↗CompletableFuture의 async stage는 executor를 명시하지 않으면 default asynchronous facility를 쓸 수 있으므로 blocking workload가 shared pool을 점유하지 않게 한다.
Oracle · ExecutorService API ↗Structured concurrency는 Java 21에서 preview였고 JDK 26에서도 sixth preview다. 이 Java 21 baseline은 --enable-preview 없이 production dependency로 사용하지 않는다.
OpenJDK · JEP 453 · Structured Concurrency (Preview) ↗OpenJDK · JEP 525 · Structured Concurrency (Sixth Preview) ↗Java 21 virtual thread는 일부 blocking operation에서 carrier pinning을 겪을 수 있다. JDK 24의 JEP 491이 synchronized 관련 pinning 대부분을 제거했으므로 JDK별 결과를 섞지 않는다.
OpenJDK · JEP 491 · synchronized에서 Virtual Thread Pinning 제거 ↗OpenJDK · JEP 444 · Virtual Threads (Final) ↗@org.springframework.context.annotation.Bean("outboxTaskExecutor")
org.springframework.core.task.TaskExecutor outboxTaskExecutor() {
var executor = new org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor();
executor.setCorePoolSize(2);
executor.setMaxPoolSize(4);
executor.setQueueCapacity(32);
executor.setWaitForTasksToCompleteOnShutdown(true);
executor.setAwaitTerminationSeconds(15);
executor.setRejectedExecutionHandler(
new java.util.concurrent.ThreadPoolExecutor.AbortPolicy());
executor.initialize();
return executor;
}core 2, max 4, queue 32, rejection과 15초 drain을 숨기지 않는다. 이 수치는 throughput/latency/DB·payment cap으로 다시 계산한다.
outbox core=2, max=4, queue=32는 saturation fixture를 위한 현재 시작값이다.
Oracle · ExecutorService API ↗PaymentGateway.Result result;
if (payment.status() == PaymentStatus.UNKNOWN) {
result = gateway.findByPaymentId(payment.id());
} else if (payment.status() == PaymentStatus.PENDING) {
result = gateway.charge(
payment.id(), payment.orderId(), payment.amount(), payment.currency());
} else {
throw new IllegalStateException("terminal payment cannot be retried");
}
recovery.recover(event.id(), result);timeout 뒤 재청구부터 하지 않고 provider 상태를 조회한다. attempt와 nextAt은 durable state여야 process restart를 견딘다.
복구는 idempotent query/command와 durable state를 결합하고 retry budget을 전체 요청 chain에 둔다.
Oracle · ExecutorService API ↗AbortPolicy는 saturation을 RejectedExecutionException으로 caller에 드러낸다. CallerRunsPolicy는 backpressure처럼 보이지만 caller thread latency와 deadlock risk를 바꾼다.
Oracle · ExecutorService API ↗ThreadLocal transaction/security state를 암묵적으로 복사하지 말고 필요한 principal/trace/business key만 명시적으로 전달한다.
Spring · Spring Boot · Task Execution and Scheduling ↗현재 fixture는 최대 8 attempts, 2초 base의 capped exponential delay+deterministic jitter를 사용하고 소진 시 DEAD metric/error log를 낸다. 총 wall-clock budget은 아직 learner가 SLO로 결정해야 한다.
OutboxRelay가 transaction 안에서 due row를 제한 수 claim한 뒤 commit하고 executor에 제출한다.
worker가 payment task를 실행하고 Future는 success/exception/cancel 중 하나로 완료된다.
Oracle · ExecutorService API ↗timeout/circuit-open은 order를 UNKNOWN으로 보존하고 attempt/nextAt/error class를 저장해 scheduler가 재개한다.
Oracle · ExecutorService API ↗shutdown은 새 제출을 막고 진행 task 완료를 기다린 뒤 deadline에서 강제 취소한다. interrupt는 협력적 신호라 code가 처리해야 한다.
Oracle · ExecutorService API ↗./gradlew failureTest && ./gradlew concurrencyTestThreadPoolSaturationFailureTest, RetryStormFailureTest, OutboxEventTest가 rejection·retry 분산·DEAD budget을 각각 assertion한다.
unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p08 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 executor active/queue/rejected, retry rate, outbox age, carrier pinning다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗async principal/context·payment idempotency key에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 executor saturation, retry/circuit state, recovery age, cancellation다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew concurrencyTest./gradlew failureTest./gradlew failureTest --tests '*GracefulShutdownFailureTest'JUnit은 test discovery/execution model을 제공하고 Spring TestContext는 ApplicationContext와 transaction test support를 제공한다. 어떤 현실을 증명하는지는 fixture·boundary·assertion이 결정한다.
JUnit · JUnit 6 User Guide ↗Spring · Spring Framework Testing ↗0–4
rule, wiring, infrastructure, peer contract, race, capacity 중 무엇을 묻는지 먼저 쓴다.
JUnit · JUnit 6 User Guide ↗4–8
plain JUnit → slice → full context+container → HTTP process 순으로 실제 경계를 늘린다.
Spring · Spring Framework Testing ↗Testcontainers · Testcontainers for Java ↗8–12
fake Clock, seed, barrier/latch, isolated schema, stub server로 우연을 제거한다.
Spring · Spring Framework Testing ↗Testcontainers · Testcontainers for Java ↗12–15
JUnit Platform이 TestEngine을 통해 test descriptor를 발견하고 lifecycle/callback을 실행한다.
JUnit · JUnit 6 User Guide ↗Spring TestContext framework는 context cache와 listener를 사용한다. context-altering annotation은 cache key를 늘려 suite 시간과 격리를 바꾼다.
Spring · Spring Framework Testing ↗Spring-managed test transaction은 기본 rollback될 수 있어 실제 commit callback, DB constraint timing, outbox visibility를 숨길 수 있다.
Spring · Spring Framework Testing ↗MVC slice는 controller·argument resolver·validation·security boundary를 빠르게 격리하지만 JPA/Flyway/실제 network는 증명하지 않는다. 이 저장소는 중요한 HTTP 계약을 full context+PostgreSQL에서 다시 검증한다.
Spring · Spring Framework Testing ↗Testcontainers는 실제 engine behavior를 높이지만 Docker availability, image pin, startup, migration, cleanup도 test surface에 포함한다.
Testcontainers · Testcontainers for Java ↗@org.junit.jupiter.api.Test
void unknownPaymentIsReconciledByStatusWithoutAnotherCharge() {
java.time.Instant now = java.time.Instant.EPOCH;
var event = new OutboxEvent(
"ORDER", orderId, "PAYMENT_REQUESTED", "{}",
"request-correlation-0001", now);
event.startAttempt(now);
payment.unknown("transport_timeout_or_io", now.plusSeconds(1));
when(outbox.findById(event.id())).thenReturn(java.util.Optional.of(event));
when(payments.findByOrderId(orderId)).thenReturn(java.util.Optional.of(payment));
when(gateway.findByPaymentId(payment.id())).thenReturn(providerResult);
processor.process(event.id());
verify(gateway).findByPaymentId(payment.id());
verifyNoMoreInteractions(gateway);
}sleep/wall clock을 제거하고 핵심 안전성인 '불확실할 때 재청구하지 않음'을 직접 assertion한다.
test fixture 시각을 고정하고 production의 현재 시각 의존성은 Clock 경계로 격리한 뒤 business outcome을 assertion한다.
Oracle · java.time 패키지 ↗JUnit · JUnit 6 User Guide ↗@org.junit.jupiter.api.Test
void replayReturnsTheOriginalOrderAndReservesOnce() {
var request = new CreateOrderRequest("LAB-SKU", 2);
var first = orders.create("integration-key-0001", request);
var replay = orders.create("integration-key-0001", request);
assertThat(replay.id()).isEqualTo(first.id());
assertThat(jdbc.sql("select count(*) from commerce_orders")
.query(Integer.class).single()).isEqualTo(1);
assertThat(jdbc.sql("select count(*) from outbox_events")
.query(Integer.class).single()).isEqualTo(1);
}test method 전체 rollback에 기대지 않는다. transactional service 호출이 commit된 뒤 독립 JDBC reader와 repository 조회로 persisted row를 관측한다.
commit 뒤에만 보이는 behavior는 명시적인 transaction boundary와 새 reader로 검증한다.
Spring · Spring Framework Testing ↗mock은 관측 가능한 port interaction이 contract일 때만 사용하고 entity/repository/framework internals를 복제하지 않는다.
Spring · Spring Framework Testing ↗unit/integration/contract/concurrency/failure는 Gradle JUnit tag task로 분리하며 check가 모두 의존한다. k6 load는 환경 명세와 함께 별도 gate다.
Gradle test task가 JUnit Platform engine을 시작하고 tag로 suite를 선택한다.
JUnit · JUnit 6 User Guide ↗Gradle · Gradle 빌드 생명주기 ↗integration suite는 Testcontainers lifecycle에서 DB를 시작하고 migration 후 Spring context가 datasource와 repository를 연결한다.
Testcontainers · Testcontainers for Java ↗Spring · Spring Framework Testing ↗contract suite는 실제 HTTP serialization과 stub payment adapter request를 snapshot이 아닌 semantic assertion으로 확인한다.
failure/concurrency suite는 barrier, bounded timeout, final DB state를 남겨 hang과 false pass를 막는다.
JUnit · JUnit 6 User Guide ↗Spring · Spring Framework Testing ↗./gradlew integrationTest --tests '*OrderIdempotencyIntegrationTest'OrderIdempotencyIntegrationTest는 실제 service transaction이 끝난 뒤 JdbcClient로 order/outbox count와 inventory를 확인한다.
Spring · Spring Framework Testing ↗unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p09 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 suite duration/flakiness, context cache, container startup, coverage gap다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗test fixture·recording·container credential에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 test duration, retry/flaky count, seed, container/log artifact다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew clean check --no-daemon./gradlew unitTest integrationTest contractTest concurrencyTest failureTestk6 run -e SCENARIO=checkout scripts/load-test.jsSpring Boot observability는 Micrometer Observation을 바탕으로 metrics와 traces를 기록할 수 있다. correlation은 instrumentation과 context propagation이 실제 경로에 있어야 생기며 log만 많다고 관측 가능한 것은 아니다.
Spring · Spring Boot · Observability ↗Micrometer · Micrometer Concepts ↗0–4
log, metric, trace, profile의 질문과 비용을 분리한다.
Spring · Spring Boot · Observability ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗4–8
RED(rate/errors/duration)와 order/payment outcome을 연결한다.
Micrometer · Micrometer Concepts ↗8–12
USE(utilization/saturation/errors)를 CPU, memory, DB/thread pool, queue에 적용한다.
Micrometer · Micrometer Concepts ↗12–15
alert → timeline → diagnose → mitigate → verify → learn을 canary/rollback과 잇는다.
Spring · Spring Boot · Observability ↗Observation은 start/stop/error lifecycle과 low/high-cardinality key-values를 갖고 registry handler가 meter/trace 같은 signal을 만든다.
Spring · Spring Boot · Observability ↗Micrometer · Micrometer Concepts ↗low-cardinality key는 metrics와 traces에, high-cardinality key는 traces에 사용할 수 있으므로 orderId를 metric label로 두지 않는다.
Spring · Spring Boot · Observability ↗JFR는 JVM event를 recording하고 thread/heap dump는 시점 상태를 보여 준다. artifact에는 민감한 heap/object/string이 포함될 수 있다.
Oracle · JDK Flight Recorder 런타임 가이드 ↗Java 21 unified logging은 -Xlog selector로 gc·safepoint 같은 tag, level, output, rotation을 정한다. GC log는 pause·heap transition의 시간축 증거이며 allocation 원인 자체는 JFR/allocation profile과 연결해야 한다.
Oracle · Java 21 java launcher · Unified JVM Logging ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗canary는 작은 traffic cohort에서 동일 SLO/error/queue 기준을 비교하고 rollback은 app version뿐 아니라 schema compatibility를 고려한다.
Spring · Spring Boot · Observability ↗@org.springframework.stereotype.Component
final class CorrelationIdFilter extends org.springframework.web.filter.OncePerRequestFilter {
protected void doFilterInternal(
jakarta.servlet.http.HttpServletRequest req,
jakarta.servlet.http.HttpServletResponse res,
jakarta.servlet.FilterChain chain) throws java.io.IOException, jakarta.servlet.ServletException {
var supplied = req.getHeader("X-Correlation-Id");
var id = supplied != null && SAFE_ID.matcher(supplied).matches()
? supplied : java.util.UUID.randomUUID().toString();
org.slf4j.MDC.put("correlationId", id);
res.setHeader("X-Correlation-Id", id);
try {
chain.doFilter(req, res);
} finally {
org.slf4j.MDC.remove("correlationId");
}
}
}허용 문자/길이를 검증해 log injection과 unbounded cardinality를 막고 finally 성격의 close로 thread reuse 누출을 막는다.
외부 correlation ID는 untrusted input으로 다루고 traceId와 역할을 구분한다.
Spring · Spring Boot · Observability ↗String previousCorrelationId = MDC.get("correlationId");
if (event.correlationId() != null) {
MDC.put("correlationId", event.correlationId());
} else {
MDC.remove("correlationId");
}
try {
Observation.createNotStarted("commerce.outbox.payment", observations)
.lowCardinalityKeyValue("event.type", event.eventType())
.observe(() -> processPayment(event));
} finally {
if (previousCorrelationId == null) {
MDC.remove("correlationId");
} else {
MDC.put("correlationId", previousCorrelationId);
}
}event.type은 bounded low-cardinality key로 두고 orderId/provider message는 metric tag로 만들지 않는다. worker는 저장한 correlation을 복원한 뒤 finally에서 이전 MDC를 되돌린다.
metric dimension은 bounded business state로 제한하고 cardinality budget을 review한다.
Micrometer · Micrometer Concepts ↗Spring · Spring Boot · Observability ↗MDC는 thread-local 성격이므로 async/reactive hop에서 별도 propagation integration을 검증해야 한다.
Spring · Spring Boot · Observability ↗trace sample은 baseline 10%에서 시작하고 error/UNKNOWN recovery는 tail/rule 기반 보존 경로를 검토한다. 비용·누락률로 조정한다.
Spring · Spring Boot · Observability ↗POST /orders ingress가 trace/correlation context를 만들고 controller→transaction→SQL→outbox span에 전파한다.
outbox에는 trace link에 필요한 안전한 context만 저장하고 relay는 producer/consumer 인과를 span link 또는 명시 attribute로 연결한다.
OpenTelemetry · OpenTelemetry Java ↗dashboard는 HTTP RED, order/payment outcome, DB pool, executor queue/rejection, outbox oldest age, JVM CPU/heap/GC를 같은 deploy marker 위에 겹친다.
incident timeline은 최초 alert, deploy/config/migration, symptom, hypothesis, evidence, mitigation, recovery 확인, follow-up owner를 UTC로 기록한다.
Spring · Spring Boot · Observability ↗./gradlew failureTest && ./gradlew unitTest --tests '*SensitiveDataRedactorTest' --tests '*SafeAccessLogFilterTest'SchemaCompatibilityFailureTest는 unsafe migration failure를, SensitiveDataRedactorTest와 SafeAccessLogFilterTest는 known credential/body 비노출을 assertion한다. 범위를 넘어선 scanner·binary matrix는 주장하지 않는다.
unit
./gradlew unitTest증명 범위: 격리된 도메인 규칙과 경계값
증명하지 않는 것: Spring wiring, 실제 DB, 네트워크 동작
integration
./gradlew integrationTest증명 범위: 고정된 DB·Spring 조합의 실제 연결
증명하지 않는 것: 운영 데이터 분포와 장시간 부하
contract
./gradlew contractTest증명 범위: HTTP·결제 adapter 경계의 요청/응답 계약
증명하지 않는 것: 상대 시스템의 가용성
load
k6 run -e SCENARIO=p10 scripts/load-test.js증명 범위: 명시한 부하 모델에서 latency·saturation 변화
증명하지 않는 것: 다른 하드웨어·데이터·트래픽에서 같은 수치
모든 부하 결과에 p50/p95/p99, 오류율, 처리량과 함께 CPU, heap/RSS, GC pause, DB pool active/pending, executor active/queue를 같은 시간축으로 기록한다. 이 모듈의 초점은 RED/USE, cardinality, trace sampling cost, JFR allocation/CPU다.
Micrometer · Micrometer Concepts ↗평균만으로 gate를 통과시키지 않는다. warm-up, duration, concurrency, payload, DB row 수, CPU/memory limit을 결과와 함께 저장한다.
Micrometer · Micrometer Concepts ↗logs·metrics backend·traces·JFR/thread/heap dumps에 대한 신뢰 경계를 표시하고 API key·payment token·DB credential은 코드, fixture, log, trace attribute에 넣지 않는다.
Spring · Spring Security · Servlet Architecture ↗입력 검증과 권한 검사는 서로 대체하지 않는다. 인증된 주체, 허용된 행위, 대상 리소스 소유권을 각각 확인한다.
Spring · Spring Security · Servlet Architecture ↗구조화 log에는 timestamp, level, service, traceId, orderId, outcome, error.type을 남기되 원문 body와 secret은 제외한다. 핵심 신호는 order/payment SLI, DB/executor saturation, incident timeline completeness다.
Spring · Spring Boot · Observability ↗metric은 집계 가능한 상태, trace는 한 요청의 인과 경로, profile은 CPU·allocation 원인에 사용한다. 하나의 신호로 다른 신호를 흉내 내지 않는다.
Spring · Spring Boot · Observability ↗OpenTelemetry · OpenTelemetry Java ↗Oracle · JDK Flight Recorder 런타임 가이드 ↗./gradlew contractTest unitTest --tests '*SensitiveDataRedactorTest' --tests '*PaymentOutboxProcessorTest'./gradlew failureTestnpm run verifyBOUNDARY TABLE
같은 단어를 서로 다른 층의 개념으로 쓰는 순간 디버깅이 흔들린다.
| 용어 | 이 가이드의 경계 | 이것과 혼동 금지 | 공식 출처 |
|---|---|---|---|
JDK / JVM | JDK는 compiler·tools·runtime을 배포하고 JVM은 class-file 실행 모델을 구현한다. | Java 언어, JDK distribution, HotSpot 구현을 모두 JVM이라는 한 단어로 섞지 않는다. | Oracle · JVMS Java SE 21 ↗ |
Class loading / initialization | loading은 binary로 Class를 만들고 linking은 verify/prepare/resolve하며 initialization은 static initializer를 실행한다. | class가 load됐다는 사실만으로 static initialization이 끝났다고 보지 않는다. | Oracle · JLS 12장 · 실행 ↗ |
Visibility / atomicity / ordering | visibility는 write 관측, atomicity는 중간 상태 불가, ordering은 허용 재배치와 관측 순서의 문제다. | volatile 하나가 복합 read-modify-write 전체를 atomic하게 만들지 않는다. | Oracle · JLS 17장 · 스레드와 메모리 모델 ↗ |
Platform thread / virtual thread | platform thread는 OS thread와 밀접히 대응하고 virtual thread는 JVM이 carrier 위에 schedule하는 Java Thread다. | virtual thread를 CPU·DB connection·rate limit 증설로 번역하지 않는다. | OpenJDK · JEP 444 · Virtual Threads (Final) ↗ |
BeanDefinition / bean / target / proxy | definition은 recipe, bean은 container가 관리하는 instance, target은 실제 logic, proxy는 interceptor를 거치는 외부 reference다. | @Service annotation, 원본 class, runtime class를 같은 것으로 보지 않는다. | Spring · Spring Framework · 컨테이너와 Bean ↗ |
Starter / auto-configuration | starter는 dependency 묶음, auto-configuration은 조건 평가 후 import되는 configuration code다. | starter가 bean을 직접 실행하거나 모든 조건을 강제한다고 말하지 않는다. | Spring · Spring Boot · Auto-configuration ↗ |
Authentication / authorization | authentication은 주체 증명, authorization은 그 주체가 이 리소스에 이 행위를 할 수 있는지 판정한다. | 유효한 API key가 모든 order 접근 권한을 뜻하지 않는다. | Spring · Spring Security · Servlet Architecture ↗ |
Transaction / connection | transaction은 commit/rollback되는 작업 경계이고 connection은 DB와 통신하는 제한 자원이다. | thread, HTTP request, @Transactional method, connection lifetime이 항상 일치한다고 가정하지 않는다. | Spring · Spring · 선언적 트랜잭션 ↗ |
Flush / commit | flush는 persistence 변경을 SQL로 동기화하고 commit은 transaction 성공을 확정한다. | repository save가 즉시 flush 또는 commit을 뜻하지 않는다. | Hibernate · Hibernate ORM · Persistence Context ↗ |
Persistence context / database | persistence context는 managed entity의 identity·snapshot을 추적하는 application-side unit이고 DB가 최종 constraint와 durability를 제공한다. | first-level cache hit를 DB commit 또는 최신 외부 상태로 해석하지 않는다. | Hibernate · Hibernate ORM · Persistence Context ↗ |
Lazy / N+1 | lazy는 접근 시점까지 load를 미루는 전략이고 N+1은 한 query 뒤 반복 association query가 생기는 실행 형태다. | 모든 lazy가 N+1이거나 모든 eager가 해결책이라고 보지 않는다. | Hibernate · Hibernate ORM · Fetching ↗ |
Timeout / cancellation / deadline | timeout은 기다림 한도, cancellation은 중단 요청, deadline은 전체 작업이 끝나야 할 절대/전파 시간 경계다. | client timeout이 server side effect 취소를 증명하지 않는다. | Oracle · ExecutorService API ↗ |
Retry / recovery | retry는 같은 operation을 제한적으로 다시 시도하고 recovery는 durable state를 읽어 process restart 뒤에도 reconcile한다. | memory queue retry를 durable recovery로 부르지 않는다. | Oracle · ExecutorService API ↗ |
Idempotency / exactly-once | idempotency는 같은 logical request 반복이 허용된 동일 효과를 내도록 하는 contract다. | network와 process 실패가 있는 end-to-end 경로를 단일 lock으로 exactly-once라 부르지 않는다. | Spring · Spring · 선언적 트랜잭션 ↗ |
MVC / WebFlux | MVC는 Servlet blocking model, WebFlux는 reactive/non-blocking model이며 실제 driver와 call chain이 모델을 완성한다. | return type이 Mono라는 사실만으로 end-to-end non-blocking이라 하지 않는다. | Spring · Spring WebFlux · Reactive Core ↗ |
Liveness / readiness / startup | liveness는 restart 필요, readiness는 traffic 수신 가능, startup은 느린 시작 동안 liveness 개입을 늦추는 신호다. | 모든 dependency health를 세 probe에 똑같이 넣지 않는다. | Spring · Spring Boot Actuator · Kubernetes Probes ↗ |
Log / metric / trace / profile | log는 사건 record, metric은 집계 time series, trace는 요청 인과 경로, profile은 자원 소비 attribution이다. | 하나를 과적재해 다른 signal의 질문에 모두 답하게 하지 않는다. | Spring · Spring Boot · Observability ↗ |
Unit / integration / contract / load test | unit은 격리 규칙, integration은 실제 연결, contract는 경계 semantics, load는 명시 workload의 capacity를 묻는다. | 한 종류의 통과를 다른 종류의 증거로 확장하지 않는다. | Spring · Spring Framework Testing ↗ |
CLAIM TRANSLATOR
절대 표현을 측정 가능한 조건과 실패 비용으로 바꾼다.
주장
“Spring이 transaction을 알아서 처리한다.”
운영 번역
외부 proxy 호출에서 TransactionInterceptor가 manager를 통해 begin/commit/rollback한다.
self-invocation, rollback rule, async boundary, 외부 HTTP는 별도 설계다.
주장
“JPA가 entity를 자동 저장한다.”
운영 번역
managed entity snapshot의 변경을 dirty checking하고 flush에서 SQL로 동기화한다.
detached entity, flush timing, constraint, commit 실패는 '자동 저장' 밖에 숨는다.
주장
“starter 하나면 production-ready다.”
운영 번역
starter가 관련 artifact를 classpath에 추가하고 auto-configuration 조건이 일부 bean 기본값을 만든다.
timeout, authz, capacity, data migration, alert, recovery, release gate는 team 책임이다.
주장
“Reactive라서 빠르다.”
운영 번역
non-blocking dependency와 event-loop model이면 많은 I/O 대기 작업의 thread 비용을 줄일 수 있다.
JDBC bridge, scheduler queue, p99, memory, debugging 비용을 동일 workload에서 비교해야 한다.
reactive는 측정 전 성능 결론이 아니라 execution model이다.
Spring · Spring WebFlux · Reactive Core ↗주장
“Virtual thread면 thread pool tuning이 사라진다.”
운영 번역
요청별 대기 thread 비용은 낮아지지만 downstream concurrency admission은 더 명시해야 한다.
DB pool, remote quota, CPU, memory, queue와 JDK별 pinning은 그대로 측정한다.
virtual thread는 I/O 대기용이며 자원 capacity를 생성하지 않는다.
OpenJDK · JEP 444 · Virtual Threads (Final) ↗OpenJDK · JEP 491 · synchronized에서 Virtual Thread Pinning 제거 ↗주장
“결제는 exactly once다.”
운영 번역
client/server idempotency key, unique state transition, provider 조회, reconciliation을 결합해 duplicate effect를 제한한다.
timeout-after-success와 process crash가 있으므로 UNKNOWN 상태와 운영 recovery가 필요하다.
주장
“graceful shutdown이면 요청 손실이 없다.”
운영 번역
새 요청을 거부하고 기존 요청에 제한된 완료 시간을 주는 lifecycle 절차다.
deadline 초과, client retry, load balancer drain, durable async state를 함께 설계해야 한다.
주장
“Actuator를 켜면 observability가 끝난다.”
운영 번역
instrumentation hook와 endpoint를 얻고 domain outcome, context propagation, dashboard, alert, runbook을 연결한다.
tag cardinality, sampling, secret 노출, backend retention과 incident 사용성은 별도 검증한다.
signal 생성과 운영 의사결정 가능성은 다른 완료 수준이다.
Spring · Spring Boot · Observability ↗Micrometer · Micrometer Concepts ↗VERIFICATION LEDGER
명령·환경·기대값·관찰값·보존 artifact를 함께 기록한다. Java 25, Windows 실실행, 실제 학습 효과는 검증되지 않았다.
아래 원장은 2026-07-16 고정 환경에서 실제 실행한 명령만 기록한다. 통과한 테스트는 기능 증거이고, 짧은 로컬 부하는 POST 202 수락 경로의 품질 표본일 뿐 production 용량이나 학습 효과의 증거가 아니다.
| ID | 수준 | 상태 | 환경 | 명령 | 기대 | 관찰 | artifact | 기록 시각 |
|---|---|---|---|---|---|---|---|---|
FUNC-MAIN-20260716 | FUNCTION | VERIFIED | macOS 26.2 arm64 · OpenJDK 21.0.11 Homebrew · Docker Engine 28.5.2 · PostgreSQL 17.6 Testcontainers | cd lab && ./gradlew --no-daemon --dependency-verification strict clean check --rerun-tasks | format·정적 분석·unit·integration·contract·concurrency·failure suite가 모두 성공한다. | BUILD SUCCESSFUL (33초), 16/16 task 실행. 6개 test task의 66회 실행은 실패·오류·skip 0이며 task 간 중복을 포함한다. | docs/evidence/2026-07-16-local-verification.json | 2026-07-17T00:27:34Z |
FUNC-P07-20260716 | FUNCTION | VERIFIED | macOS 26.2 arm64 · OpenJDK 21.0.11 Homebrew · Docker Engine 28.5.2 · PostgreSQL 17.6 Testcontainers | cd lab && ./gradlew -p reactive-comparison --no-daemon --dependency-verification strict clean check --rerun-tasks | WebFlux/R2DBC contract와 blocking-boundary failure test가 성공한다. | BUILD SUCCESSFUL (22초). `--rerun-tasks`로 독립 P07 build의 10개 task를 실행해 성공했다. | docs/evidence/2026-07-16-local-verification.json | 2026-07-17T00:21:00Z |
FUNC-IMAGE-20260716 | FUNCTION | VERIFIED | Docker Engine 28.5.2 · Eclipse Temurin 21.0.11 Alpine · pinned PostgreSQL/WireMock images | cd lab && docker compose --profile full up --build -d && ./scripts/smoke.sh | health가 UP이고 inventory seed·order accept·payment reconciliation이 연결된다. | health UP, inventory HTTP 200, order HTTP 202, 7회 polling 후 최종 CONFIRMED. 앱은 uid 100이며 당시 존재한 최근 로그 159줄에서 ERROR/Exception·로컬 secret literal 0건이었다. | docs/evidence/2026-07-16-local-verification.json | 2026-07-17T00:24:00Z |
QUALITY-ADMISSION-20260716 | QUALITY | VERIFIED | Apple M2 Max · host 32 GB/no Compose memory cap · k6 2.0.0 · 10 req/s for 10s · one post-run resource snapshot | cd lab && k6 run -e RATE=10 -e DURATION=10s -e SUMMARY_EXPORT=load-summary.json scripts/load-test.js | POST 202 수락 경로에서 check 100%, HTTP failure <1%, p95 <500ms, p99 <1000ms. | 102 요청, check 100%, failure 0%, 평균 15.11ms, p95 22.57ms, p99 28.09ms. post-run 표본은 앱 CPU 1.92%·452.4MiB, Hikari active/pending 0, outbox active/queue 0이다. 동기화된 시계열은 아니다. | docs/evidence/2026-07-16-local-verification.json | 2026-07-17T00:24:54Z |
PRODUCT-LEARNER | PRODUCT | UNVERIFIED | No representative learner study has been run | UNRUN — moderated learner task study | 학습자가 도움 없이 요청 경로를 설명하고 장애를 재현·복구하며 시간·오류율이 기준선보다 개선된다. | UNVERIFIED — 저장소 테스트와 콘텐츠 검사는 실제 이해도나 업무 속도를 증명하지 않는다. | NONE — learner test required | 2026-07-16 |
CAPSTONE ORDER
순서를 건너뛰지 않는다. 각 gate는 다음 단계의 입력이다.
gate: javap/JFR/container limit evidence를 서로 구분한다.
artifact: LEARNER OUTPUT (not committed) — docs/evidence/p00-jvm-map.md
gate: null·금액·시간대·mutable-key 경계 test가 있다.
artifact: src/main/java/dev/productionlab/commerce/order
gate: macOS ./gradlew와 Windows gradlew.bat 경로가 개인 설정 없이 재현 가능하다.
artifact: build.gradle.kts
gate: bean graph에 cycle이 없고 target/proxy/advisor가 식별된다.
artifact: LEARNER OUTPUT (not committed) — docs/evidence/p03-beans.md
gate: invalid config는 startup 실패, readiness는 traffic 상태와 일치한다.
artifact: src/main/resources/application.yml
gate: 202/400/401/403/409 contract와 동시 duplicate test가 있다.
artifact: src/main/java/dev/productionlab/commerce/order/OrderController.java
gate: self-invocation·rollback·N+1·lazy·pool·lock·timeout 실패가 fixture로 재현된다.
artifact: src/main/java/dev/productionlab/commerce/outbox
gate: 두 harness의 contract test는 존재하지만 같은 자원 제한의 비교 JSON 전에는 성능 우위를 VERIFIED BEHAVIOR로 주장하지 않는다.
artifact: reactive-comparison/ + LEARNER OUTPUT — docs/evidence/p07-mvc-reactive.json
gate: 현재 race·deadlock·rejection·retry-spread·recovery·실제 HTTP shutdown-drain fixture를 실행한다.
artifact: src/main/java/dev/productionlab/commerce/payment/PaymentRecoveryService.java
gate: 각 suite가 실제 test를 실행하며 clean check가 모두 요구한다.
artifact: GENERATED BY TEST RUN — build/reports/tests
gate: 현재 schema compatibility와 redaction test를 실행한다. secret scanner·signal contract·runbook은 학습자 산출물이다.
artifact: docs/RUNBOOK.md + learner dashboard/alert evidence