- shared-contract `Sha256`(약 65벌 흡수, notification `MessageDigestPort` 삭제), `HmacSha256`(서명 헬퍼), `Backoff`("full jitter" 뜻 하나),
`MdcKeys`(gRPC·STOMP에도 상관관계), registry edge application-notification → shared-contract
- application-core `TenantId` 하나로 web·GraphQL tenant 문법 통일, web operation 경로에 tenant 해석(JWT `tenant_id`)
- persistence-jpa `CallerTransaction` 하나(복사본 4벌 + `JpaStreamScope` 흡수), 범위 없는 멱등성·outbox 리포지토리 메서드 제거(E-6b)
- 주입된 `Clock` 우회 제거(objectstorage·websocket·mongo·web stream), GraphQL 오류가 HTTP request id 사용, notification UUIDv7은 uuid-creator
- 호출처 없는 `WebRequestContext`·argument resolver 삭제
- 결함 수정: `WebStreamRegistry` 상한 경합(ORCH-new-3 — bin 하나만 잠그는 lock 안에서 크기 확인, 원자 카운터로 슬롯 예약)
- 현황표: 소유자 결정 33(persistence-notification·fileserver → persistence-jpa edge), 34(id 포트 domain 전환 보류), 35(X2-P2-6b 나머지 보류)
검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck
:app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest graphql·websocket systemTest
persistence-jpa jpaPlatformContractTest·postgresql{Idempotency,Outbox*}IntegrationTest --continue 통과(695 task)
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
adapter-persistence-rdbms — 설계 결정 참조
RDBMS/JPA 퍼시스턴스 베이스 모듈. 패키지 루트: dev.caskeleton.adapter.persistence.
허용/금지 의존, 테스트 명령, 그리고 계약 테이블(TransactionPort 모드표, SQLState → Error Code 매트릭스, auditing 계약, 분산 락 provider 선택표)의 SSOT 는 CLAUDE.md 다. 이 문서는 코드 주석에서 덜어낸 설계 결정의 근거를 모아둔 참조용 기록이다 — 코드를 읽다 "왜 이렇게 했나"가 궁금할 때 본다. 표가 CLAUDE.md 에 있으면 여기서는 중복하지 않고 그 근거만 적는다.
capability 모듈로 쓰기 — 제공하는 것, 추가할 한 줄, 필요한 env
템플릿 기본 조립에는 이 모듈이 없다. 관계형 저장소가 필요한 서비스는 app-bootstrap/build.gradle에
한 줄을 넣는다.
runtimeOnly project(':adapter:outbound:persistence-jpa')
그 줄을 지우면 아래 전부가 함께 사라진다. 다른 파일은 고치지 않는다.
제공하는 것 (모듈이 있으면 켜진다. APP_PERSISTENCE_JPA_ENABLED=false면 완전히 꺼진다: 이 모듈의
bean과 함께 Boot의 JDBC·Hibernate·Spring Data JPA·Flyway 자동 설정도 spring.autoconfigure.exclude에
추가되므로 DataSource·풀·EntityManagerFactory·Flyway가 만들어지지 않고 DB 없이 기동한다. 그래서 DB가
필요한 다른 capability(notification·fileserver 저장소, messaging JDBC outbox/inbox 등)와 함께 끌 수는 없다)
- 포트 구현:
TransactionPort(SpringTransactionPort),DistributedLockPort(단일 인스턴스는 in-process,APP_MULTI_INSTANCE_ENABLED=true면 JDBCINT_LOCK+MeteredDistributedLockPort데코레이터 =distributedLockProvider), outbox store(OutboxStorePort,APP_OUTBOX_ENABLED=true), PostgreSQL 멱등성 store(APP_IDEMPOTENCY_PROVIDER=postgresql), audit·operation·live-event store. - 엔티티/리포지토리 스캔, vendor 조립(PostgreSQL 기본, H2는 개발용), Flyway 위치.
- 기동 정책(
startup패키지,JpaStartupAutoConfiguration): Flyway 마이그레이션 전략 (migrationStartupRunner, 실패 시 exit 70), datasource env 확인(exit 78), 실제 DB 제품·버전 확인, OSIV·DDL·Hikari·TLS·H2 금지 가드(prod exit 71),/actuator/jpaplatform(actuator가 있을 때만). - 스위치의 환경 처리(
JpaActivationEnvironmentPostProcessor, 모듈의spring.factories): 켜져 있으면 readiness 그룹에db추가, 꺼져 있으면 Boot의jdbc·hibernate·data.jpa·flyway자동 설정 패키지를spring.autoconfigure.exclude에 추가(기존 값은 유지). - 기본 설정
config/module-defaults/persistence-jpa.yml(spring.datasource/flyway/jpa,ca-skeleton.persistence*,ca-skeleton.lock.*,ca-skeleton.outbox.*,ca-skeleton.realtime.replay.*,ca-skeleton.runtime.migration-on-startup). support 모듈의ModuleDefaultsEnvironmentPostProcessor가 가장 낮은 우선순위로 읽으므로 애플리케이션 설정과 환경변수가 언제나 이긴다.
outbox relay(스케줄러)는 이 모듈이 아니라 합성 루트의 OutboxConfig가 조립한다. use case를
만들고 구동하는 일은 driven adapter의 몫이 아니기 때문이다. 그 설정은 이 모듈이 주는
OutboxStorePort와 messaging이 주는 OutboxMessagePublishPort가 모두 있을 때만 켜진다.
durable operation HTTP 엔드포인트(POST /operations·GET·DELETE /operations/{id})도 같은
이유로 합성 루트의 DurableOperationConfig가 조립한다. 이 모듈이 주는 operation store와 outbox
append 포트(APP_OUTBOX_ENABLED=true)가 모두 있을 때만 켜진다. submit·cancel에는
operation-submit 역할(operation:submit, operation:cancel)이 필요하다.
애플리케이션이 제공해야 하는 bean: Clock, DomainContextPropagator(app-bootstrap과
sample-portfolio가 제공).
필요한 env 키 (src/.env.example, 레지스트리 docs/registries/env-keys.yaml)
| 용도 | 키 |
|---|---|
| 연결(필수) | APP_DATASOURCE_URL, APP_DATASOURCE_USERNAME, APP_DATASOURCE_PASSWORD(prod 필수 secret), APP_DATASOURCE_DRIVER |
| 스위치·vendor | APP_PERSISTENCE_JPA_ENABLED(기본 true), APP_PERSISTENCE_VENDOR(postgresql|h2), APP_FLYWAY_ENABLED, APP_MIGRATION_ON_STARTUP |
| 풀 | APP_DATASOURCE_POOL_MAX_SIZE, APP_DATASOURCE_POOL_MIN_IDLE, APP_DATASOURCE_CONNECTION_TIMEOUT, APP_DATASOURCE_POOL_IDLE_TIMEOUT, APP_DATASOURCE_POOL_MAX_LIFETIME |
| JPA | APP_DATASOURCE_DDL_AUTO, APP_DATASOURCE_SHOW_SQL, APP_DATASOURCE_FORMAT_SQL, APP_DATASOURCE_OPEN_IN_VIEW, APP_JPA_HIBERNATE_* |
| 선택 기능 | APP_OUTBOX_ENABLED, APP_OUTBOX_RELAY_ENABLED, APP_MULTI_INSTANCE_ENABLED(합성 루트 소유, 락 provider 선택), APP_IDEMPOTENCY_PROVIDER=postgresql, APP_REALTIME_REPLAY_ENABLED, APP_REALTIME_REPLAY_RETENTION |
라이브러리 API — 서비스의 어댑터 leaf에서 implementation으로 받아 직접 호출
아래 타입은 어떤 설정도 bean으로 만들지 않는다. 쓰려면 서비스의 어댑터 leaf가
implementation project(':adapter:outbound:persistence-jpa')를 선언하고(registry
allowed_dependencies에 그 edge가 있어야 한다) 자기 코드에서 생성·호출한다. runtimeOnly로는
컴파일되지 않는다(AGENTS.md capability 규칙의 라이브러리형 예외). Querydsl·Envers는 이 leaf에서
compileOnly이므로 쓰는 서비스가 com.querydsl:querydsl-jpa:5.1.0:jakarta·org.hibernate.orm:hibernate-envers를
직접 추가한다. "PG"는 postgresqlIntegrationTest(실제 PostgreSQL) 테스트다.
| 패키지 | 진입점 | 동작을 증명하는 테스트 |
|---|---|---|
springdata |
JpaRepositoryFragmentSupport(커스텀 fragment 베이스) + RegisteredQuery |
JpaRepositoryFragmentSupportTest |
springdata |
SafeSortRegistry·SafeSortMapper(클라이언트 정렬 → 등록 컬럼) |
SafeSortMapperTest, KeysetOrderingContractTest |
springdata, api.query |
JpaKeysetQuerySupport·KeysetPredicateBuilder + KeysetPageRequest·KeysetSlice |
JpaKeysetQuerySupportTest, KeysetSliceAssemblerTest, KeysetOrderingContractTest |
springdata |
FetchPlanApplier + EntityGraphCatalog |
FetchPlanApplierTest |
springdata |
JpaStreamExecutor + ScrollPolicy |
JpaStreamExecutorTest, ScrollPolicyTest |
api.query |
SignedJsonCursorCodec(서비스가 CursorPayloadCodec 구현), QueryName |
SignedJsonCursorCodecTest, QueryNameTest |
hibernate.batch |
HibernateJpaBatchExecutor + JpaBatchProfile·HibernateStatisticsCollector·JdbcBatchCounter |
HibernateJpaBatchExecutorTest, HibernateBatchConfigurationGuardTest, HibernateStatisticsCollectorTest, PG HibernateJpaBatchExecutorIntegrationTest |
hibernate.bulk |
HibernateBulkDmlExecutor |
PG HibernateBulkDmlExecutorIntegrationTest |
hibernate.stateless |
HibernateStatelessSessionRunner |
PG HibernateStatelessSessionRunnerIntegrationTest |
hibernate |
NamedStatementInspector(spring.jpa.properties.hibernate.session_factory.statement_inspector로 켬) |
NamedStatementInspectorTest |
postgresql.error |
PostgreSqlExceptionTranslator.with(PostgreSqlConstraintCatalog) → api.error 예외 계층 |
PostgreSqlFailureClassifierTest, PostgreSqlConstraintCatalogTest, PG PostgreSqlSqlStateContractTest·ConstraintRaceContractTest |
postgresql.lock |
PostgreSqlLockExceptionTranslator.standard(), PostgreSqlLockOptions |
PostgreSqlLockOptionsTest, PG PostgreSqlPessimisticLockContractTest |
postgresql.json |
PostgreSqlJsonQuerySupport + JsonDocumentCodec·JsonDocument |
PG PostgreSqlJsonbContractTest |
postgresql.array, .range |
PostgreSqlArraySupport, PgRange·PgRangeCodec |
PgRangeTest, PG PostgreSqlArrayRangeContractTest |
postgresql.copy |
RegisteredPostgreSqlCopyLoader(admin DataSource + CopyAdminCapability) |
PG PostgreSqlCopyLoaderIntegrationTest |
envers |
HibernateEnversHistoryReader, EnversConfigurationGuard |
PG EnversHistoryContractTest |
querydsl |
PredicatePolicy, QueryPage(서비스가 만든 JPAQuery 앞에서 검사) |
PredicatePolicyTest |
cache |
HibernateCacheGuard, HibernateCachePolicy, CacheRegionCatalog |
HibernateCacheGuardTest |
observation |
MicrometerQueryObservation(위 executor에 QueryObservation으로 전달), SqlDiagnosticRedactor |
JpaObservabilityContractTest, JpaMetricTagsTest |
experimental |
tenant·RLS·schema·database·replica 진입점 — 목록은 docs/jpa/experimental-support-matrix.md |
ExperimentalFailClosedTest, PG platform/experimental/* |
metric은 기본으로 하나도 나오지 않는다. jpa.query.*는 서비스가 MicrometerQueryObservation을
넘길 때만 기록된다(docs/jpa/observability.md). 2026-09-25에 지운 항목(단일 구현 인터페이스,
아무도 읽지 않는 app.jpa-platform.addons-enabled·backend.jpa.experimental.*, main의
promotion gate, 생성하는 곳 없는 JpaTransactionObservation 등)은 docs/capability-status.md
"제거된 코드"에 있다.
transaction — SpringTransactionPort
왜 모드별 템플릿을 미리 만들어 두나
TransactionTemplate 은 문서상 thread-safe 지만 mutable 하다. 매 호출마다 propagation /
readOnly 를 바꿔 쓰면 같은 빈을 공유하는 동시 요청 사이에 race window 가 생긴다. 모드별로
(WRITE / READ_ONLY / REQUIRES_NEW) 템플릿을 생성 시점에 하나씩 만들어 두면 그 race 가
사라지고, 각 모드를 따로 감사(audit)할 수 있다. 세 템플릿 모두 isolation 을 READ_COMMITTED
로 고정한다(모드표는 CLAUDE.md §TransactionPort implementation contract).
왜 inRootWrite가 별도 템플릿이나 NEVER propagation을 만들지 않나
inRootWrite의 실행 속성은 inWrite와 같은 WRITE + REQUIRED + READ_COMMITTED라 기존
write template을 재사용한다. 차이는 실행 전 precondition이다.
TransactionSynchronizationManager.isActualTransactionActive()가 true이면 action과
PlatformTransactionManager를 호출하기 전에
NestedRootTransactionRejectedException으로 fail-fast한다. REQUIRES_NEW로 suspend해서
"root처럼 보이게" 하지 않으므로 호출자 transaction과 독립 commit되는 silent 의미 변경이 없다.
TransactionTemplate.execute는 commit까지 성공한 다음 값을 반환한다. 따라서
inRootWrite의 결과는 post-commit에만 호출자에게 보이고, commit 실패는 값 대신 원래 transaction
예외로 전파된다. 이 보장은 action이 외부 객체를 직접 변경하는 것을 되돌리는 보상이 아니라,
경계의 반환값을 성공으로 노출하지 않는 계약이다.
audit — AuditableEntity / AuditContextPort / DomainContextAuditContextPort
캡처 메커니즘 — Manual explicit-set (D1 현재 스켈레톤 기본값)
AuditableEntity 의 네 필드(created_at / updated_at / created_by / updated_by)는 평범한
@Column 이다 — Spring Data 의 @CreatedDate/@LastModifiedDate/@CreatedBy/@LastModifiedBy
도, @EntityListeners(AuditingEntityListener.class) 도 붙이지 않는다. 퍼시스턴스 어댑터가
initializeAudit(INSERT) 와 carryCreation + applyModification(UPDATE)로 명시적으로 값을
세팅한다. 공유 Clock 빈(D4)과 AuditContextPort actor(D5)를 재사용한다.
- INSERT 는
created_*와updated_*를 같은now/actor로 찍는다. NOT NULL 인updated_*를 신규 row 에서 채우기 위함이며, JPA-auditing 의modifyOnCreate기본동작에 의존하지 않는다. - UPDATE 는 두 단계다:
carryCreation으로 (Vernon Option A 재구성된) 엔티티가 잃어버린created_*를 다시 채워 넣고,applyModification으로updated_*만 옮긴다. created_*는updatable = false라 INSERT 이후 모든 UPDATE 문에서 제외된다 — 생성 actor/시각이 덮어써질 수 없다.version/optimistic-lock 은 여기 두지 않는다. 이 베이스는 audit 전용으로 남기고, 낙관적 잠금 정책은 개별 영속성 모델이 소유한다.
Growth path (D1, deferred — 구현 복제본 없음)
audited 애그리거트 수가 늘어 수동 세팅이 누락 위험을 키우면 Spring Data JPA Auditing 으로 이전할
수 있다. 다만 현재 leaf에는 두 번째 audit 모델을 미리 보관하지 않는다. 전환할 때
AuditableEntity의 같은 created_*/updated_* 스키마와 256자 actor 계약을 유지한 채
@EntityListeners(AuditingEntityListener.class)와 composition-owned AuditorAware /
DateTimeProvider를 원자적으로 도입한다. bulk/native @Query UPDATE는 어느 방식에서도 listener를
우회하므로 audit column을 statement에서 명시적으로 갱신해야 한다.
actor seam 을 왜 별도 포트로 격리하나
AuditContextPort 는 퍼시스턴스가 "누가 행위하는가"에 대해 의존하는 단 하나의 seam 이다.
actor 의 값 의미론(user id vs email vs subject claim)은 application/web 쪽의 사용자 모델
책임이고 여기서는 의도적으로 다루지 않는다. 그래서 타입을 String 으로 못박고, 이
포트가 보장하는 건 오직 "non-null actor"(프레임워크의 blank-on-absent 가 아니라) 하나 —
principal 이 없으면 "system".
DomainContextAuditContextPort 는 actor id 를 runtime-context-propagation seam
(DomainContextPropagator)에서 읽는다. 그 브랜치가 canonical actor key 를 소유하지만 API 가
확정되기 전까지 이 어댑터가 ACTOR_KEY 뒤로 격리해, 키가 바뀌어도 정확히 한 클래스만 손대게
한다(D5 Open Risk). 빈/blank context 값은 null/blank actor 가 아니라 "system" 으로 떨어뜨려
scheduler / Flyway / anonymous 경로에서도 NOT NULL created_by/updated_by 를 항상 만족시킨다.
config — PersistenceJpaConfig
왜 명시적 @EntityScan / @EnableJpaRepositories 가 필요한가
Spring Boot 메인 클래스는 dev.caskeleton.bootstrap 에 있어서, @AutoConfigurationPackage 가
앵커로 삼는 기본 엔티티/리포지토리 스캔이 dev.caskeleton.adapter.persistence.* 를 놓친다.
@SpringBootApplication 의 scanBasePackages 는 컴포넌트 스캔만 넓힐 뿐 JPA 엔티티/리포지토리
스캔은 넓히지 않는다. 이 설정이 없으면 production 리포지토리(예: IdempotencyRecordJpaRepository)
가 생성되지 않아 소비자(예: IdempotencyReaper)가 부팅에서 와이어링 실패한다. 스캔을 엔티티를
소유한 모듈에 둬서 와이어링을 그 자리에 유지한다.
왜 이름이 JpaConfig 가 아닌가
sample 모듈에 이미 ...sample.portfolio.adapter.persistence.config.JpaConfig 가 있다. IDE 의
"Run main class" 가 테스트 스코프 sample 모듈을 클래스패스에 올리면, simple name JpaConfig 를
공유하는 두 @Configuration 이 기본 빈 이름 jpaConfig 에서 충돌한다
(ConflictingBeanDefinitionException). 다른 simple name 으로 이를 피한다.
failure — 퍼시스턴스 실패 변환 SPI
매트릭스(SQLState → DB_* 코드, category, http, retryable)의 SSOT 는 CLAUDE.md §Persistence
failure translation contract 다. 여기서는 SPI 구조와 fallback 근거만 적는다.
SPI-pluggable 설계 (vendor 추출)
PersistenceExceptionTranslator 는 exact-state → code 맵을 등록된 모든 SqlStateErrorMapping
빈을 생성 시점에 merge 해서 만든다. core 모듈(StandardSqlStateErrorMapping)은 모든 RDBMS 가
공통으로 반환하는 portable/vendor-neutral 5개 row(40001, 23502, 23503, 23505, 23514)만
기여한다. vendor 별 row(40P01, 25P03, 57014 등 PostgreSQL)는 adapter-persistence-postgresql
가 추가 SqlStateErrorMapping 빈으로 기여한다.
- 서로 다른 contributor가 같은 exact SQLState를 등록하면 code가 같더라도 startup construction을 실패시킨다. last-writer-wins merge는 mapping ownership drift를 숨기므로 허용하지 않는다.
08*connection-class prefix →DB_UNAVAILABLE규칙은 맵 엔트리가 아니라 translator 가 직접 처리한다. 따라서 core 매핑 맵에는08*가 없다.- Fallback: 기여된 어떤 row 에도 없는 SQLState — 또는 cause chain 에
SQLException자체가 없는 경우 — 는Optional.empty()를 반환한다. 호출부는 원본 예외를 web catch-all 까지 전파시켜 detail 누설 없는 genericINTERNAL엔벨로프로 답하게 한다. translator 는 unknown state 에 대해DB_*코드를 절대 지어내지 않는다. - 변환된 carrier 의 진단 메시지에 SQLState 를 넣는 건 server-log 전용이다(web 어댑터가 절대 surface 하지 않음) — triage 를 돕되 클라이언트로 새지 않는다.
idempotency — PostgreSQL provider
ca-skeleton.capabilities.idempotency.provider=postgresql 일 때만 켜진다
(autoconfigure/PostgreSqlIdempotencyStoreConfig). 이 leaf 는 IdempotencyStorePort 구현
(PostgreSqlOwnerSafeIdempotencyStore) 하나만 내놓고, executor 는 app-bootstrap
IdempotencyProviderSelectionConfig 가 만든다. V1 JDBC store 와 jdbc provider 값은 없다.
- 스키마: 기본 테이블은 primary Flyway(
db/migration/postgresql/V1__idempotency_record.sql)가, owner-safe 컬럼은db/migration/jpa/idempotencystream 이 소유한다. 기동 시IdempotencySchemaStream이db/migration/jpa/core→db/migration/jpa/idempotency순서로 적용하고 capability registry 행을ACTIVE로 올린다. 알림 capability 의NotificationSchemaStream과 같은 방식이다.ca-skeleton.runtime.migration-on-startup=false면 건너뛰고, 운영자가 적용·활성화할 때까지 store 가 fail closed 한다. - PostgreSQL 전용: data source 가 PostgreSQL 이 아니면 기동을 거부한다.
bootRunH2는 provider 를disabled나redis로 둔다. - 응답 크기: 완료 응답은 8 KiB 이하만 행에 inline 저장하고, 넘으면 거부한다.
- 만료: store 가 완료·실패 때
expires_at을 앞으로 옮기고,IdempotencyReaper(IdempotencyRecordJpaRepository사용, 기본 10분 간격reaper-interval)가 지난 행을 지운다. reaper 는 provider 가postgresql일 때만 돈다.
outbox — OutboxStoreAdapter 외
스키마는 Flyway(V3__outbox_event.sql)가 소유하고, V13__outbox_canonical_transport_compatibility.sql이
canonical metadata와 exact BYTEA envelope_bytes를 더했다. append 모델은 canonical 하나다(2026-09-28,
소유자 결정 7): OutboxStoreAdapter가 OutboxAppendPort(ValidatedIntegrationEvent)와
OutboxStorePort를 함께 구현하고, ca-skeleton.outbox.enabled=true일 때만 존재한다. row는 validated
event의 exact envelope bytes와 hash를 저장하고, claim은 그 bytes로 같은 event를 복원한다
(ClaimedOutboxEvent). event_type·aggregate_id·correlation_id는 claim gate와 metrics query를
위해 contract id·aggregate id·correlation id를 한 번 더 적는다.
V19__outbox_event_canonical_only.sql은 pre-canonical row가 더 없다는 것을 DB에 적는다: envelope 없는
미발행 row가 남아 있으면 migration이 실패하고(이전 릴리스로 relay를 비우거나 손으로 정리한 뒤
다시 적용한다), 이후로는 PUBLISHED가 아닌 row에 canonical metadata가 반드시 있다
(ck_outbox_event_canonical_unless_published). pre-canonical payload·idempotency_key 컬럼은
nullable로 남고 아무것도 쓰거나 읽지 않는다 — 이전 릴리스로 되돌릴 때를 위해 지우지 않았다.
트랜잭션 경계 계약
- append: 호출자의
TransactionPort.inWrite()경계 안에서 호출되어야 하며, 내부에서 새 트랜잭션을 열지 않는다.@Repository가 빈만 등록하고 TX 는 use case 가 소유한다. - Application write 경계에는 adapter-local
@Transactional을 추가하지 않는다: 여러 port를 하나의 원자 작업으로 묶는 경계는 use case의TransactionPort가 소유한다. 예외는 adapter 자체가 하나의 저장소 프로토콜을 구현하는 내부 원자 단위다. 예를 들어 durable operation의 claim은UPDATE ... RETURNING후 같은 claim을 읽어야 하고, live-event append는 position allocator와 event insert가 함께 commit돼야 한다. 이런 메서드의 로컬 transaction은 application transaction을 대체하는 것이 아니라 port 자체의 atomic semantics다.
claim 계약 — vendor SPI (OutboxClaimRepository)
row claim 은 vendor 별 락 전략이 필요해 OutboxClaimRepository SPI 로 추출했다. canonical
PostgreSQL 구현은 native query 의 FOR UPDATE SKIP LOCKED 를 쓰고, 다른 벤더는 등가물을
공급한다(예: SQL Server WITH (UPDLOCK, READPAST)). eligibility predicate(I3 — concurrent-relay
안전을 위한 SKIP LOCKED)와 per-aggregate FIFO gate(I4 — NOT EXISTS correlated subquery)를
전부 SQL 에서 강제한다. 한 배치에 aggregate 당 최대 한 row(head)만 나타난다. 어댑터는 추가
in-memory 필터링을 하지 않는다 — 리포지토리가 반환한 모든 row 를 IN_FLIGHT 로 전이시켜 호출자에
돌려준다. 전체 SQL gate 동작은 PG contract 테스트(Testcontainers)가 검증한다.
FIFO gate 의 "같은 aggregate"와 "앞선 row":
- canonical row 끼리는
(tenant_scope, aggregate_type, aggregate_id)가 같아야 같은 aggregate 이고, 순서는(aggregate_sequence, event_index)다. 그래서occurred_at이 같은 이벤트도 한 번에 하나씩 나가고, 다른 tenant·type 의 DEAD row 가 같은aggregate_id를 막지 않는다. 인덱스는V18의ix_outbox_event_unpublished_aggregate_order. - gate 가 비교하는 row 는 전부 canonical 이다: V19 가 envelope 없는 미발행 row 를 거부한다.
읽을 수 없는 row(envelope 없음, 부분 metadata, 저장된 hash 와 bytes 불일치 등)는 claim 에서 DEAD 로 옮기고 배치에서 뺀다. 예전에는 예외로 claim transaction 전체가 롤백되고 다음 claim 이 같은 row 를 다시 먼저 골라 relay 가 영구히 멈췄다. 추측해서 발행하지 않으므로 fail-closed 는 유지된다.
eligible row(I3/I4/I6):
PENDING—next_attempt_at <= now(insert 시 즉시 eligible)FAILED—next_attempt_at <= now(backoff 경과)IN_FLIGHT—next_attempt_at <= now(orphaned row)
claim lease와 fencing token (V17)
in-flight timeout이 지나면 다른 relay가 IN_FLIGHT row를 다시 claim한다. 예전 완료 처리는
event_id만으로 row를 읽어 status를 덮어썼고 claim·publish·완료가 서로 다른 transaction이라,
timeout을 넘겨 멈췄던 relay A가 relay B의 결과를 덮을 수 있었다 — B가 PUBLISHED로 만든 row를
A가 FAILED로 바꾸면 다시 발행되고(중복 전달), A의 늦은 PUBLISHED는 B의 실패를 가린다.
- claim:
claimBatch(owner, ...)가 row lock(FOR UPDATE SKIP LOCKED)을 쥔 상태에서lease_owner = owner,lease_token = lease_token + 1을 기록하고OutboxLease(event, owner, token)을 돌려준다. owner는 relay 인스턴스(PublishPendingOutboxEventsUseCase)마다 한 번 만든 UUID다. - 완료:
markPublished/markFailed/markDead(lease)는 한 문장의 조건부 UPDATE다 —WHERE event_id = ? AND status = 'IN_FLIGHT' AND lease_owner = ? AND lease_token = ?. owner는 비우고 token은 그대로 둔다(token은 증가만 한다). 1 row면APPLIED, 0 row면STALE.findById+ setter 경로와@Version은 쓰지 않는다. - STALE은 예외가 아니다: row의 결과는 지금 lease를 가진 relay가 쓴다. use case는 결과를
OutboxRelayResult.Outcome.STALE로 남기고OutboxRelayFailureReportPort.reportStaleCompletion으로 알린 뒤 다음 이벤트로 넘어간다. FAILED/DEAD report는 보내지 않는다(아무것도 저장되지 않았다).outbox.publisher.published.total{outcome=STALE}이 0보다 크면 in-flight timeout이 relay 정지 시간보다 짧다는 뜻이고, broker는 그 이벤트를 두 번 받았을 수 있다. - row가 없을 때도 0 row라
STALE이다. 예전처럼 throw하지 않는 이유: fencing 뒤에는 0 row가 "다른 relay가 가져감"이라는 정상 결과이고, 그 row는 가져간 relay가 끝내거나 timeout 뒤 다시 claim되므로 FIFO 큐가 막히지 않는다.
OutboxEventEntity 의 결정
AuditableEntity미상속(D6 — infra 엔티티).IdempotencyRecordEntity처럼 outbox row 는 도메인 애그리거트가 아니라 인프라 record 다. 자체 temporal 필드(occurred_at,next_attempt_at)가 도메인 의미를 갖고, genericcreated_at/updated_ataudit 컬럼과 섞이면 안 된다.- mutating setter 노출은 의도. claim은 lock된 managed 엔티티 위에서 상태(status /
attempt_count / next_attempt_at / lease)를 전이시킨다. 완료는 setter가 아니라 lease 조건부
bulk UPDATE다. outbox 어댑터만
이 필드를 건드리고, 모든 mutation 이 use case 소유
TransactionPort.inWrite()경계 안에서 돌기에 안전하다. next_attempt_atdual-purpose(I6 — 추가 컬럼 없음):PENDING: insert 때occurred_at으로 세팅 → 최초 claim 체크(next_attempt_at <= now)가 즉시 만족.IN_FLIGHT:claim_time + in_flight_timeout→ orphaned row 가 visibility window 만료 후 재claim 가능.FAILED:now + backoff→ backoff window 경과 후에만 재시도.
status는PENDING | IN_FLIGHT | PUBLISHED | FAILED | DEAD문자열이다.Persistable<String>(새 엔티티는isNew() == true). 식별자를 직접 넣고@Version이 없는 엔티티를 Spring Data 는 기존 row 로 보고 merge 한다. 그래서 같은event_id로 두 번 append 하면 이미 PUBLISHED 된 row 가 PENDING·attempt 0 으로 덮여 다시 발행됐다. 이제 append 는 항상 insert 이고, 중복은 primary key 위반(23505)으로 드러난다.
metric 쿼리 반환 형태
OutboxEventJpaRepository.countGroupedByStatus() 는 [status(String), count(Long)],
findOldestUnpublishedOccurredAtByEventType() 는 [eventType(String), oldestOccurredAt(Instant)]
2-요소 배열 리스트를 돌려준다(각각 outbox.pending.size, outbox.publisher.lag gauge 용).
두 쿼리 모두 PUBLISHED row 는 세지 않는다 — retention 기간 동안 테이블 대부분이 PUBLISHED 라,
매 poll 마다 테이블 전체를 세게 된다.
OutboxStoreAdapter.oldestUnpublishedAgeSecondsByEventType 가 HashMap 을 쓰는 건 키가
enum 이 아니라 String(event-type 이름)이기 때문이다 — countByStatus() 는 키가
OutboxEventStatus enum 이라 EnumMap 을 쓴다(두 반환 타입이 의도적으로 다름).
OutboxReaper
PUBLISHED row 는 이미 전달된 terminal-success record 라 무한 보관할 필요가 없다. reaper 가
retention 보다 오래된 PUBLISHED row 를 주기적으로 비워 테이블 성장과 metric gauge 를 묶는다.
스케줄링은 컴포지션 루트의 @EnableScheduling 으로 켜진다. 삭제는 deletePublishedBatch 로
1,000 row 씩, 배치마다 별도 transaction 으로 돌리고 배치가 덜 차면 멈춘다 — relay 장애 뒤 쌓인
PUBLISHED backlog 를 한 transaction 으로 지우면 그 사이 모든 row lock 을 쥔 긴 transaction 이 된다.
고정 interval / clock-skew 미처리는 프로젝트 선택(부하 하
cadence 측정 필요). retention 한 값은 reaper-local 이라 @Value 로 받지만, canonical 6-property
문서는 app-bootstrap OutboxSettings / application.yml 에 있다.
JPA production capability candidate
src/config/jpa/readiness-cards.yaml이 capability와 독립 schema stream의
machine-readable SSOT다(개수는 registry가 소유한다). selected base card와 implemented-candidate reliability card를
구분하며, 실제 PostgreSQL 테스트 통과만으로 immutable 운영 evidence가 필요한 R2를 주장하지
않는다.
적용된 versioned migration은 수정하지 않는다. Flyway가 기동할 때마다 checksum을 검사하므로
바꾼 파일은 이미 그것을 적용한 모든 DB의 기동을 막는다. 변경은 새 버전으로 추가하고,
src/test/resources/db/applied-migrations.sha256에 한 줄을 더한다
(AppliedMigrationImmutabilityTest가 검사). 2026-09-23~25 사이에 수정본 postgresql/V9·V13을
적용해 만든 개발 DB는 원복된 파일과 checksum이 다르므로 한 번 flyway repair가 필요하다. 그
사이 수정본이 바꾸려던 char(64)→varchar(64)는 V16이 한다.
독립 Flyway stream은 broad classpath:db/migration으로 함께 실행하지 않는다. 각 stream은
자기 location/history table을 사용하고 non-empty schema adoption 때 version 0 baseline을 명시한
뒤 V1부터 실행한다.
| Capability | Location | History table | 상태 |
|---|---|---|---|
| core/adoption | db/migration/jpa/core |
flyway_jpa_core_history |
selected candidate |
| idempotency | db/migration/jpa/idempotency |
flyway_jpa_idempotency_history |
implemented-candidate |
owner-safe idempotency
PostgreSqlOwnerSafeIdempotencyStore는 row lock을 얻은 뒤 clock_timestamp()를 평가한다.
claim takeover와 start/renew/complete/fail/release는 scope/state/owner/attempt/claim operation/
state revision을 SQL predicate로 다시 검증한다. expired CLAIMED만 takeover하며 expired
EXECUTING은 ABANDONED로 닫고 reconciliation을 요구한다. raw client key는 저장하지 않고
versioned HMAC scope digest만 쓴다.
outbox V2 (삭제됨)
immutable outbox storage·polling delivery V2(jpa/outbox-storage, jpa/outbox-polling stream과
그 adapter)는 어떤 composition도 location을 설정한 적 없는 미조립 세대라 2026-09-25에 삭제했다
(docs/capability-status.md "제거된 코드"). 실제로 도는 v1 outbox_event relay가 V2의
owner/token CAS를 이어받았다(위 "claim lease와 fencing token").
실제 PostgreSQL task
base task 외에 다음 candidate task가 Docker 부재 시 skip이 아니라 실패하도록 등록돼 있다.
postgresqlIdempotencyIntegrationTest
readiness card 검사 (evidence manifest 폐기)
readiness-cards.yaml의 evidence.scenarios와 evidence.task-claims가 required evidence를 실제
테스트와 task에 연결한다. build-tools의 JPA evidence manifest(ca.jpa-evidence,
ca.jpa-qualification, verifyJpaCandidateEvidence, verifyJpaPrimaryFoundationEvidence,
jpa-r2-evidence.yml)는 소유자 결정 4(2026-09-25)로 폐기했다. 그 manifest가 증명하던 사실은
이제 두 곳에서 확인한다.
JpaReadinessRegistryTest(이 leaf의test): 카드 상태·선행 관계(순환 없음), 구현된 카드가 가리키는 이 leaf의 task가build.gradle에 선언된 lane인지, 인용한 scenario 메서드가src/postgresqlIntegrationTest에 있는지, required evidence가 모두 덮이는지, 소유 schema stream의 location·history table이 고유하고 존재하는지.- readiness lane 자체: 카드가 인용한 scenario마다 lane의 required test가 되고(
requires), lane은 skip을 거절한다(rejectSkipped). 실제 PostgreSQL이 없으면 skip이 아니라 실패한다.
./gradlew :adapter:outbound:persistence-jpa:test --tests '*JpaReadinessRegistryTest' --console=plain
./gradlew :adapter:outbound:persistence-jpa:integrationTestLaneCheck --console=plain # 모든 readiness·platform lane
R2(운영 evidence) 승격은 더 이상 build가 판정하지 않는다. clean revision에서 위 lane을 돌린
CI 결과(jpa-release job의 JUnit XML artifact)를 검토해 결정한다.
stream migration이 중단되면 history/registry/object 상태를 먼저 확인하고 기존 migration을
임의 수정하거나 history를 바로 repair하지 않는다. 장애를 수정한 forward migration으로
복구하는 운영 절차는 docs/runbooks/migration-failed.md를 따른다.
lock — 분산 락
provider 선택표(flag → bean → registry)의 SSOT 는 CLAUDE.md(또는 app-bootstrap 와이어링)다. 여기서는 어댑터/설정 결정 근거만 적는다.
LockRegistryDistributedLockAdapter 계약
- D4 — transaction-commit ordering invariant. 이 어댑터는 트랜잭션 경계를 관리하지 않는다.
호출자는 보호된 트랜잭션이 커밋된 뒤에만 핸들(
DistributedLock.close())을 release 해야 한다. 커밋 전(트랜잭션 안)에 release 하면 lost-update race 가 생긴다. - D5 — finite waitTime + lease TTL.
tryAcquire는 Spring IntegrationDistributedLock이면tryLock(waitTime, leaseTtl)로, 일반Lock이면Lock.tryLock(long, TimeUnit)으로 최대waitTime만 블록하고, 잡으면 핸들을, 못 잡으면LockAcquisitionTimeoutException을 던진다. 무한 블로킹은 쓰지 않는다. leaseTtl > configuredTtl은IllegalArgumentException으로 거부한다. provider 기본 TTL 보다 긴 lease 를 약속하는 건 false contract 다. shipped 와이어링에선leaseTtl == configuredTtl(둘 다LockSettings.leaseTtl()바인딩)이라 이 가드는 mis-wired 호출자/테스트에서만 fail-fast 로 발동한다.- 반환 핸들은
lock::unlock람다(SAM 인터페이스 충족).InterruptedException은 interrupt flag 를 복원하고LockAcquisitionTimeoutException으로 변환한다.
TTL 주의 (SI 7.0)
JdbcLockRegistry: 기본 TTL 은JdbcLockRegistry(LockRepository, Duration)생성자로 설정하고, acquisition 별 TTL 은DistributedLock.tryLock(Duration waitTime, Duration ttl)로 전달한다. 크래시한 JVM 의 row 는 lock TTL 만료 후 다음 acquire 시도에서 회수된다.DefaultLockRegistry: TTL 은 advisory 이고 무의미하다 — JVM 크래시가 in-JVM 락을 프로세스와 함께 자동으로 떨군다.
SI-LOCK-C5 — lease 만료 후 release
반환 핸들은 lock::unlock 이다. lease TTL 이 close() 전에 만료된 JdbcLockRegistry
의 경우, 내부 JdbcLock.unlock() 이 ConcurrentModificationException 을 던진다(row 가 이미
회수됨). 이 어댑터는 여기서 일부러 잡지 않는다 — metered distributedLockProvider 데코레이터
(컴포지션 루트)가 SI-LOCK-C5 계약을 소유한다: 로그 + lock.lease.expired metric 후 close() 에서
정상 return 해, 만료가 호출자의 보호작업 예외를 가리지 않게 한다. in-process DefaultLockRegistry
경로는 만료가 없어 그 close() 가 이 예외를 던질 수 없다.
DistributedLockPersistenceConfig 와이어링 결정
jdbcDistributedLock빈은 일부러@Primary가 아니다. 같은 설정이 이를 metrics 데코레이터(MeteredDistributedLockPort, package-private)로 감싸@PrimarydistributedLockProvider빈으로 노출한다. 예전에는 app-bootstrap의DistributedLockConfig가 감쌌지만, JDBC 락이 있을 때만 의미가 있는 코드라 이 모듈로 옮겼다. SI 타입은 여전히 이 모듈 밖으로 보이지 않는다(SI 는implementation의존).DefaultLockRepository는InitializingBean/SmartLifecycle을 구현해 Spring 이 lifecycle 을 자동 관리하고,ApplicationContextAware로PlatformTransactionManager를 auto-discover 한다. app-bootstrap Testcontainers 테스트가 와이어링 갭을 드러내면 부트스트랩이setTransactionManager로 명시 전달할 수 있다.setCheckDatabaseOnStart(false):INT_LOCK테이블은 첫 lock acquire 전에 Flyway V4/V5 가 provision 하므로 DDL 체크를 건너뛴다.JdbcLockRegistry(lockRepository, settings.leaseTtl()): Spring Integration 7.0 이후 기본 TTL 은 repository setter 가 아니라 registry 생성자에서 설정한다. 어댑터는 호출별leaseTtl도DistributedLock.tryLock(waitTime, leaseTtl)로 전달한다.
LockSettings
ca-skeleton.lock.* 에서 바인딩되는 yaml-only 기본값이다(config/module-defaults/persistence-jpa.yml).
새 APP_* env 키가 아니므로 env-keys.yaml 엔트리가 필요 없다. DistributedLockPersistenceConfig의
@EnableConfigurationProperties가 바인딩한다. cross-field invariant: leaseTtl >= waitTime
이어야 한다 — TTL 이 waitTime 보다 먼저 만료되면 첫 holder 의 보호작업이 끝나기 전에 두 번째
holder 가 락을 잡을 수 있다.
MeteredDistributedLockPort (app-bootstrap에서 이동)
DistributedLockPort를 감싸는 얇은 Micrometer 데코레이터다.tryAcquire호출마다lock.acquisition카운터를outcome태그와 함께 1 증가시킨다. 태그 값은 세 가지:acquired(락 획득 성공, 위임 핸들 반환),timeout(LockAcquisitionTimeoutException발생),error(그 외 모든RuntimeException발생). 메트릭 이름과 태그 값은docs/registries/metrics.yaml의lock.acquisition행과 일치해야 한다.- 리스 만료(lease-expiry) CME 흡수. 보유자가
close()를 호출하기 전에 리스(저장소 TTL)가 만료되면 그 락 행은 이미 다른 인스턴스가 회수해 갔을 수 있고, 그 시점에 내부JdbcLock.unlock()은ConcurrentModificationException(CME)을 던진다. 이 예외를 호출자의finally { lock.close(); }블록 밖으로 그대로 전파하면 보호 구간(critical section)에서 발생한 본래 예외를 가려버린다 (masking). 그래서 CME 만 잡아 WARN 로그를 남기고 태그 없는lock.lease.expired카운터를 1 증가시킨 뒤close()는 정상 복귀시킨다. 이렇게 해야 신호(로그+메트릭)는 남기면서도 호출자의 정상 흐름과 예외 전파를 방해하지 않는다. 오직ConcurrentModificationException만 흡수하며, DB 장애 같은 다른 예외(예:DataAccessResourceFailureException)는 리스 만료 신호가 아니므로 손대지 않고 그대로 전파한다. - MeterRegistry 부재 시 no-op. 레지스트리를
ObjectProvider.getIfAvailable()로 해석하므로 클래스패스에MeterRegistry빈이 없으면(Actuator 미탑재) 모든 메트릭 연산이 조용히 no-op 이 된다.BackgroundJobMetrics선례와 동일한 패턴이다. - 메트릭 실패가 락 경로를 절대 깨뜨리지 않음. 카운터 등록·증가는 모두 try/catch 로 감싸 예외를 로깅 후 삼킨다(log-and-swallow). Micrometer 쪽 실패가 락 획득·보유·실패 보고를 막는 일은 없어야 하기 때문이다.
startup — 관계형 기동 정책 (app-bootstrap에서 이동)
JpaStartupAutoConfiguration(package-private, 모듈 스위치 ca-skeleton.persistence-jpa.enabled
아래)이 아래 가드를 등록한다. 전부 adapter:outbound:support의 StartupFailures로 실패하므로 exit
코드(78/70/71)와 구조화 로그 필드(startup.phase/error.code/error.category)는 옮기기 전과 같다.
migrationStartupRunner는 @ConditionalOnMissingBean(FlywayMigrationStrategy)라, 자기 전략을 둔
애플리케이션(sample-portfolio의 두 번째 마이그레이션 스트림)에는 끼어들지 않는다.
FlywayProdSafetyValidator
prod프로파일에서 Flyway 안전장치가 꺼지지 못하도록 런타임에서 강제한다. Flyway 옵션은application.yml에 안전값으로 고정돼 있지만(baseline-on-migrate=false,out-of-order=false,clean-disabled=true), 환경별 override 가 프로덕션에서 이 값을 조용히 되돌릴 수 있다. 이 검증기는 그런 override 를 시작 시점에 잡아PROFILE_MISMATCH(exit 71)로 부팅을 막는다.- 금지하는 옵션은 각각 "복구 불가능한 위험" 때문이다.
baseline-on-migrate=true는 누락된 마이그레이션을 감지하는 안전망을 없애고,out-of-order=true는 개발자 간 마이그레이션 적용 순서 일관성을 깨며,clean-disabled=false는 스키마 전체를 드롭하는 파괴적clean명령을 다시 활성화한다. - 프로파일 비교는 대소문자를 무시한다.
SPRING_PROFILES_ACTIVE=PROD처럼 대문자 오타가 나도 가드가 우회되지 않게 하기 위함이다. - Flyway repair 는 가드 대상이 아니다. repair 는 property 가 아니라 Flyway 명령이고 스켈레톤은
repair 호출 경로 자체를 배선하지 않으므로, "prod 에서 repair 금지"는 런타임 트리거가 없는
문서화된 정책으로 남는다. 부분 스키마 복구는 in-prod Flyway repair 가 아니라
runbook(
runbook://migration/manual-recovery)을 통한 수동 복구로 가도록 실패 메시지에 명시한다. (프로젝트가 repair 경로를 추가한다면 동일하게 prod 게이트 + non-prod 감사 로그를 걸어야 한다.)
RequiredEnvironmentValidator
- datasource 연결 환경변수를 마이그레이션 실행 전에 검증해 부팅을 빨리 실패시킨다. Flyway
forward-only 마이그레이션은 context refresh 동안 애플리케이션 datasource 에 대해 실행된다. 연결
환경변수가 빠져 있으면 마이그레이션은 시작 단계 구분자 없이 불투명한 driver/connection 에러로
한참 뒤에야 실패한다. 이 검증기는 그것을 명시적인 env 검증 실패(
STARTUP_VALIDATION_FAILED, exit 78)로 바꿔, 누락된 운영자용 env 키를 전부 이름으로 짚어준다. - 검증 범위를 datasource 3종(url/username/driver)으로 의도적으로 좁혔다. 이것들이 이 브랜치가
소유하는 마이그레이션 전제조건이기 때문이다. app-name(
BootstrapSettings), issuer-uri(security settings) 등 다른 필수값은 각 모듈의 가드가 책임지므로 여기서 중복 검증하지 않는다. - 값이 없거나(blank) 공백이면 모두 "누락"으로 본다. spring-dotenv 에서 미설정 placeholder
${...}가 빈 문자열로 해석되기 때문에, null 뿐 아니라 blank 도 누락으로 처리해야 빈틈이 없다. - 메시지는 env 키 이름순으로 정렬해 출력한다. Map 순회 순서와 무관하게 결정적이고 안정적인 실패 메시지를 보장하기 위함이다.
JpaStartupAutoConfiguration (옛 MigrationStartupConfig·PersistenceJpaRootAutoConfiguration·JpaPlatformRuntimeAutoConfiguration)
- 마이그레이션 전략과 관계형 기동 가드를 한곳에 모은다. app-bootstrap에서는 네 개 설정 클래스와
RuntimeSafetyConfig의 validator 목록에 흩어져 있었고, JPA 스위치를 합성 루트가 알아야 했다.JpaPlatformAutoConfiguration(플랫폼 조립 factory)은 지웠고, 보고서 조립은JpaPlatformReport로 옮겼다. migrationStartupRunner빈 이름은 유지한다. Spring Boot Flyway 오토컨피규레이션이migrate()를 위임하는FlywayMigrationStrategy다.
MigrationStartupRunner
FlywayMigrationStrategy로 등록해 context refresh 중에 마이그레이션을 직접 실행한다(오토컨피그 기본값을 그대로 두지 않는다). refresh 안에서 실행한다는 것은 마이그레이션이 완료되거나 부팅을 실패시키는 일이 애플리케이션이 readiness 를 보고하기 전에 일어난다는 뜻이다. 따라서 절반만 마이그레이션된 스키마가 트래픽을 받는 일이 구조적으로 없다(actuator readiness probe 의 형태 자체는 health-lifecycle 브랜치가 소유하고, 여기서는 "마이그레이션 → ready" 순서만 책임진다).FlywayException을StartupFailures.migrationFailed(MIGRATION_FAILED, exit 70)로 번역한다. 일반적이고 구분 안 되는 스택트레이스 대신 구조화된MIGRATION_FAILED로그와 표준 exit 코드를 남기기 위함이다.- 멀티 인스턴스에서는 in-app 마이그레이션 + Flyway 자체 schema-history 락에 의존하는 것이 기본
전략이다. 여러 레플리카의 동시
migrate()를 Flyway 의 락이 직렬화한다. 대안인 "in-app 마이그레이션을 끄고 플랫폼 one-shot Job 으로 돌리기"는 "migration=Job"을 강제하는 공개 표준이 없는 배포 선택이라 스켈레톤 기본값이 아니다. Job 으로 돌리는 프로젝트는 이 빈의migrate()를 no-op 으로 만들면 된다.
HikariPoolConstraintValidator
- HikariCP 노브 사이의 상호 제약을 부팅 실패로 바꾼다. Hikari/Tomcat 은 잘못된 값을 결국
거부하지만 pool/connector 초기화 시점에 난해한 메시지로만 거부한다. 이 검증기는 계약을 일찍·명확
하게 만든다: resolved Spring property 를 읽고, 위반을 모두 모아 운영자가 실제로 설정한
APP_*환경 키를 메시지에 담아IllegalStateException을 던진다. 속성이 없으면 건너뛰고(placeholder/ 프레임워크 기본값이 소유), 있을 때만 검사한다. - 강제하는 제약과 그 숫자의 근거.
connection-timeout >= 250ms(너무 짧으면 정상 연결도 타임 아웃).validation-timeout < connection-timeout(둘 다 있을 때; validation-timeout 기본 5000ms 가 흔한 connection-timeout 5s/5000ms 와 같아지는 충돌을 해소).keepalive-time < max-lifetime(둘 다 있을 때; keepalive 가 lifetime 보다 길면 의미 없음).leak-detection-threshold는 0(비활성)이 아니라면>= 2000ms(너무 작으면 정상 사용을 누수로 오탐). - Spring Boot와 같은 Duration 문법을 검증한다.
env-keys.yaml의connection-timeout기본값은5s인데src/.env는30000(ms)을 준다. resolved 값을String으로 읽은 뒤DurationStyle로 plain milliseconds, simple duration(5s)과 ISO-8601(PT5S)을 같은 milliseconds 계약으로 변환한다. present-but-invalid 값은 부재로 조용히 취급하지 않고 property 이름을 포함한 startup validation failure로 거절한다. - env 키가 아직 없는 노브는 "env key pending" 문구를 쓴다.
connection-timeout/max-lifetime만env-keys.yaml에 등록돼 있고, greenfield 노브(validation-timeout, keepalive-time, leak-detection-threshold)는 env 키가 없다. 없는 키 이름을 지어내는 대신 pending 문구를 메시지에 넣는다.
OpenInViewSafetyValidator
- OSIV(Open Session In View) OFF 를 hard stop 으로 강제한다. OSIV 가 켜져 있으면 Hibernate
세션이 view 렌더링까지 열려 있어, presentation 레이어에서 lazy 연관을 건드리면 거기서 조용히 DB
쿼리가 나간다 — 이것이 정확히 금지된 레이어 경계 위반이다. Spring Boot 는
spring.jpa.open-in-view가 암묵 기본값일 때 WARN 만 찍을 뿐 명시적으로true로 설정한 배포는 막지 못한다. WARN 은 놓치기 쉬우므로, resolved 값이true면 운영자가 실제 설정한APP_DATASOURCE_OPEN_IN_VIEW키를 메시지에 담아 부팅을 실패시킨다. - 읽기만 하고 re-bind 하지 않으며, 부재 값은 Spring 기본에 맡긴다.
StartupRule로 위반만 돌려주고 support의StartupRuleRunner가 모든 싱글톤 생성 후 한 번 실행하며, 값이 없으면 Spring Boot 기본(이 스켈레톤은application.yml에서 OSIV off 가 기본)에 맡기며 *있는true*만 거부한다.
JpaDangerousConfigurationGuard (ddl-auto)
- Flyway를 physical schema의 유일한 writer로 유지한다. local convenience profile만으로 이뤄진
profile 집합이 아니면(
prod,staging, profile 없음,local+prod혼합 모두)spring.jpa.hibernate.ddl-auto가none또는validate일 때만 허용한다.update,create,create-drop, 빈 값, 그 밖의 값이면APP_DATASOURCE_DDL_AUTO를 이름으로 포함한PROFILE_MISMATCH로 부팅을 중단한다. mode 비교는 대소문자를 무시한다. - 검사는 이 guard 하나다. prod만 보던
JpaSchemaSafetyValidator는 이 guard보다 늦게 돌아 한 번도 발동하지 않았고, 실제 prod 거부는PROFILE_MISMATCH가 아닌IllegalStateException이었다. 두 검사를 합치면서 guard가PROFILE_MISMATCH를 던진다.