From 6764246ac948aad0d856d50ba7ffbd5dcdf6803b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 01:28:33 +0900 Subject: [PATCH] =?UTF-8?q?fix(architecture):=20Flyway=20=EA=B7=9C?= =?UTF-8?q?=EC=B9=99=EC=9D=B4=20=EC=84=A4=EC=A0=95=20=EA=B0=9D=EC=B2=B4?= =?UTF-8?q?=EB=A5=BC=20=EC=A7=81=EC=A0=91=20=EB=A7=8C=EB=93=9C=EB=8A=94=20?= =?UTF-8?q?=EA=B8=B8=EB=8F=84=20=EB=A7=89=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 (재리뷰 round7 RR7-03-06) - 규칙 문장은 "코드로 만드는 Flyway는 모두 FlywaySchemaPolicy.configure() 에서 시작한다"(persistence-jpa CLAUDE.md, FlywaySchemaPolicy Javadoc, migration-guide)인데 JpaProductionArchitectureTest는 Flyway.configure() 호출만 막는다. new FluentConfiguration(), new ClassicConfiguration(), FluentConfiguration::new로 만든 Flyway는 검사를 지나 Flyway의 PostgreSQL 잠금 기본값(트랜잭션 안의 잠금)을 되찾는다. 그 잠금 아래 동시 인덱스 마이그레이션은 끝나지 않는다(RR6-03-01). 고른 방법 - 규칙을 상수 EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY로 빼고, Flyway Configuration에 대입 가능한 타입의 생성자 접근(호출과 생성자 참조)을 더 막는다. 하위 클래스와 직접 구현도 같은 접근이라 함께 걸린다. new Flyway(...)는 허용한다 — 정책의 설정 위에서는 정책의 Flyway다. - 위반 fixture 4개(configure 호출, FluentConfiguration·ClassicConfiguration 생성, 생성자 참조)와 허용 fixture 1개(정책 빌더, 정책 설정 위의 new Flyway)를 ArchitectureViolationFixtureTest로 평가한다. - 버린 안: callConstructor를 생성자 시그니처마다 나열 — Flyway 버전마다 생성자 목록이 바뀌고 생성자 참조를 못 본다. new Flyway(...)까지 금지 — 정책 설정 위의 정당한 사용까지 막는다. 위험·한계 - 하위 클래스 fixture는 두지 않았다. SpotBugs가 Flyway 설정을 상속한 클래스를 분석하다 lombok.Generated를 못 찾아 testQualityCheck가 실패한다 (빌드는 불완전 분석을 실패로 본다). 이 경우는 GREEN 1차 실행에서 규칙이 잡는 것을 확인했고(g0306-archtest.log), 규칙 Javadoc에 이유를 적었다. - 리플렉션이나 Configuration 맵으로 잠금 값을 덮어쓰는 것은 막지 않는다. - 이 규칙을 이미 지키는 파생 서비스(업그레이드 안내 2절 15번)는 바꿀 것이 없다. 설정 객체를 직접 만들던 서비스는 architectureTest가 새로 실패한다 (안내 15번과 5절 「Flyway 잠금」 행에 적었다). 검증 (desktop, 공유 잠금, 로그 ~/r8-f3-logs/) RED — 6ec0c4f7 + 규칙 상수 추출(규칙 그대로)과 fixture·테스트: - :app-bootstrap:architectureTest 1차 233건 중 3건 실패 (FluentConfiguration·ClassicConfiguration·하위 클래스 fixture 통과), 2차(생성자 참조 fixture 추가) 234건 중 4건 실패. Flyway.configure() fixture는 잡히고 허용 fixture는 통과 (red0306-arch*.log) GREEN — 이 커밋의 트리 e7e19298: - :app-bootstrap:architectureTest rc=0 (233건 실패 0; 위반 fixture 4개 모두 걸리고 허용 fixture와 운영 코드는 통과) - architectureCheck rc=0 - :adapter:outbound:persistence-jpa:check rc=0, :app-bootstrap:check rc=0 - :app-bootstrap:documentContractTest rc=0 (66건 실패 0) - :app-bootstrap:testQualityCheck rc=0. 하위 클래스 fixture를 둔 1차 트리(f8fecd1e)에서는 spotbugsArchitectureTest가 "missing analysis class lombok.Generated"로 실패했고, 그 fixture만 빼자 통과했다 (g0306-testquality.log, g0306b-testquality.log) - 같은 우회가 다른 곳에 있는지: 운영 코드 전체(src 아래 main·testFixtures) 에서 Flyway를 만드는 곳은 FlywaySchemaPolicy와 규칙이 예외로 둔 MessagingInboxSchemaStream의 Flyway.configure()뿐이다. optional 빌드와 src/messaging에는 운영 Flyway 생성이 없다 Refs: docs/reviews/2026-11-03-rereview/README.md 18.5절 round7 1차 Declined 판정 (cb340001) --- docs/jpa/migration-guide.md | 5 +- docs/manual/04-persistence.md | 6 +- docs/upgrade/2026-11-maturity-review.md | 4 +- .../outbound/persistence-jpa/CLAUDE.md | 5 +- .../outbound/persistence-jpa/README.md | 5 +- .../migration/FlywaySchemaPolicy.java | 7 +- .../ArchitectureViolationFixtureTest.java | 48 +++++++++++ .../JpaProductionArchitectureTest.java | 80 ++++++++++++++----- .../flyway/SchemaPolicyFlywayFixture.java | 17 ++++ .../persistence/flyway/package-info.java | 6 ++ .../ClassicConfigurationFlywayFixture.java | 15 ++++ .../flyway/ConfigureCallingFlywayFixture.java | 12 +++ .../FluentConfigurationFlywayFixture.java | 13 +++ .../ReferencedConfigurationFlywayFixture.java | 16 ++++ .../persistence/flyway/package-info.java | 8 ++ 15 files changed, 215 insertions(+), 32 deletions(-) create mode 100644 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/SchemaPolicyFlywayFixture.java create mode 100644 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/package-info.java create mode 100644 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ClassicConfigurationFlywayFixture.java create mode 100644 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ConfigureCallingFlywayFixture.java create mode 100644 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/FluentConfigurationFlywayFixture.java create mode 100644 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ReferencedConfigurationFlywayFixture.java create mode 100644 src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/package-info.java diff --git a/docs/jpa/migration-guide.md b/docs/jpa/migration-guide.md index 9223d687..5f2e2158 100644 --- a/docs/jpa/migration-guide.md +++ b/docs/jpa/migration-guide.md @@ -20,7 +20,10 @@ older than itself, Flyway's own included — the deploy stops with no error and defaults (`config/module-defaults/persistence-jpa.yml`, `spring.flyway.postgresql.transactional-lock: false`) for the one Spring Boot builds at startup, and `FlywaySchemaPolicy.configure()` for every stream it builds itself — a service's own stream starts from it too, and `JpaProductionArchitectureTest` -refuses production code that calls `Flyway.configure()` directly. The deployment-owned migration of +refuses production code that builds a Flyway any other way: calling `Flyway.configure()`, or +constructing a configuration itself (`new FluentConfiguration()`, `new ClassicConfiguration()`, a +subclass of either, or `FluentConfiguration::new`). `new Flyway(...)` over the policy's configuration +is allowed. The deployment-owned migration of staging and prod is outside this repository: give its tool the same value (`FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`, or the key above in its configuration file). diff --git a/docs/manual/04-persistence.md b/docs/manual/04-persistence.md index f009b847..e26a24e6 100644 --- a/docs/manual/04-persistence.md +++ b/docs/manual/04-persistence.md @@ -120,8 +120,10 @@ capability 스트림 db/migration/jpa/ 각자 histor (`src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SamplePostgreSqlPersistenceConfig.java`)와 `NotificationSchemaStream`(persistence-notification). 그러면 번호가 템플릿 스트림과 독립이라 V1부터 쓴다. 자기 스트림의 Flyway는 `Flyway.configure()`가 아니라 `FlywaySchemaPolicy.configure()`(persistence-jpa)로 - 만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝나고, - 직접 부르면 `:app-bootstrap:architectureTest`가 실패한다(`docs/jpa/migration-guide.md` "Who may change the schema"). + 만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝난다. + `Flyway.configure()`를 직접 부르거나 설정 객체를 직접 만들면(`new FluentConfiguration()`, + `new ClassicConfiguration()`, 그 하위 클래스) `:app-bootstrap:architectureTest`가 실패한다 + (`docs/jpa/migration-guide.md` "Who may change the schema"). - **예외**: 템플릿 운영 스트림(`db/migration/postgresql`)에 직접 넣으면 upstream이 다음에 쓸 번호와 겹친다. 어쩔 수 없으면 upstream이 쓰지 않을 큰 번호대를 정해 문서에 적는다. - 이미 적용된 파일은 고치지 않는다. 고치면 체크섬 불일치로 기동이 멈추고, `repair`는 쓰지 않는다 diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index 73a3f76d..8b01b9b4 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -35,7 +35,7 @@ | 12 | 자기 Flyway 마이그레이션 번호가 템플릿의 새 번호와 겹치지 않는지 본다(4절) | 같은 버전 두 개로 Flyway 실패 | 같은 stream에 자기 마이그레이션을 둔 서비스 | | 13 | `.env`에 옛 `.env.example` 값을 복사해 두었다면 5.6절 키를 다시 맞춘다 | 새 기본값이 안 먹거나(JDBC batch), 기동 실패(알림 콜백 상한) | `.env`를 복사해 쓰는 서비스 | | 14 | 자기 테스트 코드에 `./gradlew testQualityCheck`를 돌려 보고, 발견을 고치거나 이유를 단 Match로 뺀다(B-40) | `mainCheck`가 실패 | 테스트 코드가 있는 모든 서비스 | -| 15 | staging·prod 배포 마이그레이션 도구에 `flyway.postgresql.transactional.lock=false`(환경 변수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`)를 넣는다. 자기 Flyway stream은 `Flyway.configure()` 대신 `FlywaySchemaPolicy.configure()`로 만든다(5절 「Flyway 잠금」) | `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY` 마이그레이션에서 배포가 오류 없이 멈춘다. 자기 stream이 `Flyway.configure()`를 부르면 `:app-bootstrap:architectureTest` 실패 | persistence-jpa 선택 + 배포 도구로 마이그레이션하거나 자기 stream을 둔 서비스 | +| 15 | staging·prod 배포 마이그레이션 도구에 `flyway.postgresql.transactional.lock=false`(환경 변수 `FLYWAY_POSTGRESQL_TRANSACTIONAL_LOCK=false`)를 넣는다. 자기 Flyway stream은 `Flyway.configure()` 대신 `FlywaySchemaPolicy.configure()`로 만든다(5절 「Flyway 잠금」) | `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY` 마이그레이션에서 배포가 오류 없이 멈춘다. 자기 stream이 `Flyway.configure()`를 부르거나 설정 객체를 직접 만들면(`new FluentConfiguration()`·`new ClassicConfiguration()`, 재리뷰 round7 RR7-03-06부터) `:app-bootstrap:architectureTest` 실패 | persistence-jpa 선택 + 배포 도구로 마이그레이션하거나 자기 stream을 둔 서비스 | | 16 | 자기 성능 lane(`performance()`)에서 `performance.assertions.enabled`를 `false`로 두는 `systemProperty` 줄을 지우고, 그 속성을 읽어 상한 단언을 건너뛰던 테스트는 항상 단언하게 고친다. 성능 lane의 `@Disabled`·assumption skip을 없앤다(B-43) | `performanceCheck`가 테스트 전에 실패(`its test JVM would get performance.assertions.enabled=false`)하거나 skip 때문에 실패(`forbids skipped tests`) | 자기 성능 lane이 있는 서비스 | | 17 | 자기 `docs/registries/error-codes.yaml` 행에서 `log_level:` 줄을 지운다(B-44) | `mainCheck`의 `:app-bootstrap:documentContractTest`가 실패(`docs/registries/error-codes.yaml rows with a log_level; the code decides the level, not the registry`) | `error-codes.yaml`에 자기 행을 더한 서비스 | @@ -247,7 +247,7 @@ V21 실패의 분류는 `docs/runbooks/migration-failed.md` "Classify the failur | 빌드 단계(HTTP client) | `httpClientFailureInjectionTest`(Toxiproxy 장애 주입)가 `mainCheck`에서 빠졌다. `integrationCheck`에만 있고, main push·nightly의 `integration-main.yml` `integration-check` job이 돌린다 | main push마다 같은 lane이 `main-check`·`integration-check` 두 job에서 두 번 돌던 것이 한 번이 된다. 로컬에서 `mainCheck`만 돌리면 이 lane은 돌지 않는다(`integrationCheck`로 돌린다) | r9 · `src/adapter/outbound/httpclient/build.gradle` | | 서버 로그(GraphQL·gRPC·STOMP) | carrier로 답한 실패를 web과 같은 줄(shared-contract `ServerFailureLog`)로 ERROR에 남긴다: persistence 실패는 분류만, 5xx carrier는 예외와 함께, 4xx carrier는 남기지 않는다. gRPC는 ` (method=…)`, GraphQL은 ` (executionId=…)`를 붙인다. gRPC는 인식 못 한 실패(`INTERNAL_ERROR`)도 `unhandled failure on …`로 남긴다. 클라이언트가 취소한 호출은 남기지 않고, 서비스가 `CANCELLED` status로 끝낸 살아 있는 호출은 남긴다. raw status는 넘겼든 던졌든 설명을 남기지 않는다(원인 예외가 있으면 그것만 붙인다). `IllegalArgumentException`(`BAD_PARAMETER`)은 web과 같은 WARN 한 줄 `request refused as BAD_PARAMETER by <예외 타입>`(메시지 없음)으로 남긴다. STOMP `@MessageMapping` 실패는 Spring의 `Unhandled exception from message handler method`(예외 전체) 대신 같은 줄로 남는다 | ERROR 로그가 늘어난다(전에는 gRPC가 아무것도 남기지 않았다). GraphQL·gRPC·STOMP는 잘못된 입력마다 WARN 한 줄이 생긴다. STOMP에서 Spring 문구로 경보를 걸었다면 고친다. `IDEMPOTENCY_RECOVERY_REQUIRED`의 scope digest를 모든 전송에서 찾을 수 있다(`docs/runbooks/idempotency-unavailable.md`) | r9 · `src/shared-contract/.../error/ServerFailureLog.java`, `GrpcExceptionHandlingInterceptor.java`, `GraphQlWireErrorMapper.java`, `StompHandlerFailureLog.java` | | sample-portfolio | 익명 쓰기 401, 포스터 제목 대소문자 무시 유일(409 `POSTER_ALREADY_EXISTS`), 관리자도 남의 work log 수정 불가, 샘플 이벤트 tenant `global` | sample을 남긴 서비스만 | `34565130`, `1400dc15` | -| Flyway 잠금 | Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션 대신 세션에 둔다. Spring Boot의 Flyway는 module-defaults `spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway(멱등성·알림·sample stream, schema-per-tenant, testkit `MigrationContractRunner`)는 `FlywaySchemaPolicy.configure()`, messaging inbox stream은 같은 값을 직접 넣는다. 운영 코드의 `Flyway.configure()` 직접 호출은 `JpaProductionArchitectureTest`가 거부한다 | Flyway 기본값에서는 동시 인덱스 마이그레이션이 Flyway 자신의 열린 트랜잭션을 기다려 끝나지 않았다. 이제 끝난다. 마이그레이션은 잠금을 잡은 연결 하나로 돈다. transaction 모드 PgBouncer 뒤에서는 잠금 해제가 다른 서버 연결로 가 다음 배포가 기다릴 수 있으니 마이그레이션은 직접 연결이나 session 모드 pool로 돌린다. 배포 도구는 이 repo 밖이라 2절 15번으로 맞춘다 | 재리뷰 round6 RR6-03-01 · `persistence-jpa.yml`, `.../migration/FlywaySchemaPolicy.java`, `docs/jpa/migration-guide.md` "Who may change the schema"·"Concurrent index builds" | +| Flyway 잠금 | Flyway의 PostgreSQL 마이그레이션 잠금을 트랜잭션 대신 세션에 둔다. Spring Boot의 Flyway는 module-defaults `spring.flyway.postgresql.transactional-lock: false`, 템플릿이 직접 만드는 Flyway(멱등성·알림·sample stream, schema-per-tenant, testkit `MigrationContractRunner`)는 `FlywaySchemaPolicy.configure()`, messaging inbox stream은 같은 값을 직접 넣는다. 운영 코드의 `Flyway.configure()` 직접 호출과 설정 객체 직접 생성(`new FluentConfiguration()`·`new ClassicConfiguration()`·그 하위 클래스, round7 RR7-03-06)은 `JpaProductionArchitectureTest`가 거부한다 | Flyway 기본값에서는 동시 인덱스 마이그레이션이 Flyway 자신의 열린 트랜잭션을 기다려 끝나지 않았다. 이제 끝난다. 마이그레이션은 잠금을 잡은 연결 하나로 돈다. transaction 모드 PgBouncer 뒤에서는 잠금 해제가 다른 서버 연결로 가 다음 배포가 기다릴 수 있으니 마이그레이션은 직접 연결이나 session 모드 pool로 돌린다. 배포 도구는 이 repo 밖이라 2절 15번으로 맞춘다 | 재리뷰 round6 RR6-03-01 · `persistence-jpa.yml`, `.../migration/FlywaySchemaPolicy.java`, `docs/jpa/migration-guide.md` "Who may change the schema"·"Concurrent index builds" | | 실패한 동시 인덱스 마이그레이션 복구 | `docs/runbooks/migration-failed.md`에 「Recover a failed concurrent index migration」을 더했다: 진행 중인 빌드가 없는지 보고, 무효 인덱스를 `DROP INDEX CONCURRENTLY`로 지우고, 원인을 정리하고, 그 버전의 실패 이력 행(`success = false`)만 지운 뒤 다시 배포한다. 「Do not」의 이력 수정 금지에 이 한 가지 예외를 적었다. `flyway repair`는 계속 쓰지 않는다 | 전에는 안내가 "`DROP INDEX` 하나"였고, 그대로 하면 남은 실패 이력 때문에 다음 배포가 validate에서 다시 멈췄다. 동시 인덱스 마이그레이션을 쓰는 서비스의 운영자는 이 절차로 복구한다 | 재리뷰 round7 RR7-03-03, 소유자 결정 2026-11-06 · `docs/jpa/migration-guide.md` "Concurrent index builds", `PostgreSqlConcurrentIndexMigrationIntegrationTest` | | 성능 lane(HTTP client·Mongo) | httpclient `LargeBodyResourceTest`의 힙 상한(32 MiB 스트리밍 중 힙 증가 16 MiB 미만)을 매번 단언한다. 전에는 `-Pperformance.assertions.enabled=true`일 때만 단언하고 아니면 건너뛴다는 줄만 찍었다. Mongo `MongoResourceBudgetLaneTest`는 표준 gate 전체(p99 500ms, pool 대기 250ms, 힙 512 MiB, examined/returned 10, spill 금지)를 Gradle 밖 실행에서도 단언한다(B-43) | 손으로 돌린 `performanceCheck`가 상한을 실제로 재므로, 전에는 통과하던 느린 기계에서 실패할 수 있다 | B4(2026-11-06) · `LargeBodyResourceTest`, `MongoResourceBudgetLaneTest` | | 보안 필터 로그 레벨 | 보안 필터(`AuthErrorResponseWriter`)의 `security failure` 줄을 5xx(`AUTH_JWKS_UNAVAILABLE` 503, `INTERNAL_AUTH_MISCONFIGURATION` 500)면 ERROR, 4xx면 WARN으로 남긴다. 전에는 모두 WARN이었다. 다른 경로가 5xx를 ERROR로 남기는 규칙(`ServerFailureLog`)과 같아졌다 | ERROR로 거르는 로그 경보·대시보드에 JWKS 장애와 인증 설정 오류가 새로 잡힌다. 401·403은 그대로 WARN | 설계 메모 2026-11-06 7절 결정 2 · `src/adapter/inbound/web/.../auth/AuthErrorResponseWriter.java`, `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md` | diff --git a/src/adapter/outbound/persistence-jpa/CLAUDE.md b/src/adapter/outbound/persistence-jpa/CLAUDE.md index e8caf319..56a4170a 100644 --- a/src/adapter/outbound/persistence-jpa/CLAUDE.md +++ b/src/adapter/outbound/persistence-jpa/CLAUDE.md @@ -100,8 +100,9 @@ not grow by wiring accident. - Flyway holds its PostgreSQL migration lock for the session, never in an open transaction, or a `CREATE INDEX CONCURRENTLY` migration waits for Flyway forever: `spring.flyway.postgresql.transactional-lock: false` in the module defaults, and every Flyway built in code starts from - `FlywaySchemaPolicy.configure()` (`JpaProductionArchitectureTest` refuses `Flyway.configure()`; - `docs/jpa/migration-guide.md` "Who may change the schema"). + `FlywaySchemaPolicy.configure()` (`JpaProductionArchitectureTest` refuses `Flyway.configure()` and + constructing a Flyway configuration directly — `new FluentConfiguration()`, `new + ClassicConfiguration()`, a subclass; `docs/jpa/migration-guide.md` "Who may change the schema"). - Metric tags, exception messages, and logs carry no SQL parameters, entity ids, tenant ids, or PII. - Contracts run against real PostgreSQL. H2 never satisfies one. diff --git a/src/adapter/outbound/persistence-jpa/README.md b/src/adapter/outbound/persistence-jpa/README.md index a13880a2..a586810a 100644 --- a/src/adapter/outbound/persistence-jpa/README.md +++ b/src/adapter/outbound/persistence-jpa/README.md @@ -405,8 +405,9 @@ Flyway의 PostgreSQL 마이그레이션 잠금은 트랜잭션이 아니라 세 열어 두고, `CREATE INDEX CONCURRENTLY`·`REINDEX … CONCURRENTLY`는 그 트랜잭션이 끝나기를 기다려 배포가 끝나지 않는다(재리뷰 round6 RR6-03-01). Spring Boot의 Flyway는 `config/module-defaults/persistence-jpa.yml`의 `spring.flyway.postgresql.transactional-lock: false`로, 템플릿이 직접 만드는 Flyway는 -`FlywaySchemaPolicy.configure()`로 받는다. 운영 코드가 `Flyway.configure()`를 직접 부르면 -`JpaProductionArchitectureTest`가 거부한다. 배포 마이그레이션 도구에도 같은 값을 넣는다 +`FlywaySchemaPolicy.configure()`로 받는다. 운영 코드가 `Flyway.configure()`를 직접 부르거나 Flyway 설정 객체를 +직접 만들면(`new FluentConfiguration()`, `new ClassicConfiguration()`, 그 하위 클래스) `JpaProductionArchitectureTest`가 +거부한다. 배포 마이그레이션 도구에도 같은 값을 넣는다 (`docs/jpa/migration-guide.md` "Who may change the schema", lane `postgresqlConcurrentIndexMigrationIntegrationTest`). 적용된 versioned migration은 수정하지 않는다. Flyway가 기동할 때마다 checksum을 검사하므로 diff --git a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/FlywaySchemaPolicy.java b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/FlywaySchemaPolicy.java index 1ac9fbaf..272cb06e 100644 --- a/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/FlywaySchemaPolicy.java +++ b/src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/migration/FlywaySchemaPolicy.java @@ -109,8 +109,11 @@ public final class FlywaySchemaPolicy { * spring.flyway.postgresql.transactional-lock}); a deployment's migration tool has to be given it * ({@code docs/jpa/migration-guide.md}, "Who may change the schema"). * - *

Callers chain their own settings onto the result. Calling {@link Flyway#configure()} - * directly in production code is refused by {@code JpaProductionArchitectureTest}. + *

Callers chain their own settings onto the result. Production code that builds a Flyway any + * other way — calling {@link Flyway#configure()}, or constructing a Flyway configuration itself + * ({@code new FluentConfiguration()}, {@code new ClassicConfiguration()}, a subclass of either) — + * is refused by {@code JpaProductionArchitectureTest}; {@code new Flyway(...)} over this method's + * result is allowed (re-review 2026-11-03 round 7, RR7-03-06). */ public static FluentConfiguration configure() { return sessionLevelLock(Flyway.configure()); diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java index 0b82c1e1..7d688eb1 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/ArchitectureViolationFixtureTest.java @@ -16,6 +16,7 @@ import dev.caskeleton.bootstrap.architecture.allowed.application.CleanProjection import dev.caskeleton.bootstrap.architecture.allowed.configuration.SystemCallerBesideControllerRegistrationFixture; import dev.caskeleton.bootstrap.architecture.allowed.configuration.SystemCallerBesideFieldReadingWebMvcConfigurerFixture; import dev.caskeleton.bootstrap.architecture.allowed.configuration.SystemCallerBesideWebMvcRegistrationFixture; +import dev.caskeleton.bootstrap.architecture.allowed.persistence.flyway.SchemaPolicyFlywayFixture; import dev.caskeleton.bootstrap.architecture.fixtures.application.RootWriteTransactionBoundaryUseCase; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.SystemCallerRestControllerFixture; import dev.caskeleton.bootstrap.architecture.violations.adapter.inbound.messaging.UnmarkedSystemInvokedHandlerFixture; @@ -50,9 +51,16 @@ import dev.caskeleton.bootstrap.architecture.violations.domain.AnnotatedPublicNo import dev.caskeleton.bootstrap.architecture.violations.domain.JakartaValidationDomainFixture; import dev.caskeleton.bootstrap.architecture.violations.domain.entity.FakeDomainEntity; import dev.caskeleton.bootstrap.architecture.violations.domain.vo.PackagePublicNoArgValueObjectFixture; +import dev.caskeleton.bootstrap.architecture.violations.persistence.flyway.ClassicConfigurationFlywayFixture; +import dev.caskeleton.bootstrap.architecture.violations.persistence.flyway.ConfigureCallingFlywayFixture; +import dev.caskeleton.bootstrap.architecture.violations.persistence.flyway.FluentConfigurationFlywayFixture; +import dev.caskeleton.bootstrap.architecture.violations.persistence.flyway.ReferencedConfigurationFlywayFixture; import dev.caskeleton.bootstrap.architecture.violations.streaming.JakartaWebSocketEndpointFixture; import dev.caskeleton.bootstrap.architecture.violations.streaming.SpringWebSocketHandlerFixture; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; /** * Negative ("violations-as-data") tests proving each architecture rule actually catches the @@ -1383,4 +1391,44 @@ class ArchitectureViolationFixtureTest { + "it references no broker/HTTP type") .isFalse(); } + + @ParameterizedTest + @ValueSource( + classes = { + ConfigureCallingFlywayFixture.class, + FluentConfigurationFlywayFixture.class, + ClassicConfigurationFlywayFixture.class, + ReferencedConfigurationFlywayFixture.class + }) + @DisplayName("FlywaySchemaPolicy를 거치지 않고 Flyway를 만드는 길은 어느 것이든 Flyway 규칙에 걸린다") + void everyWayToBuildAFlywayPastTheSchemaPolicyIsCaught(Class fixture) { + // given + JavaClasses fixtureOnly = new ClassFileImporter().importClasses(fixture); + + // when + EvaluationResult result = + JpaProductionArchitectureTest.EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY.evaluate( + fixtureOnly); + + // then + assertThat(result.hasViolation()) + .as("%s builds a Flyway past FlywaySchemaPolicy.configure()", fixture.getSimpleName()) + .isTrue(); + } + + @Test + @DisplayName("FlywaySchemaPolicy.configure()에서 시작한 Flyway는 빌더로도 생성자로도 Flyway 규칙에 걸리지 않는다") + void aFlywayBuiltFromTheSchemaPolicyIsNotFlagged() { + // given + JavaClasses fixtureOnly = + new ClassFileImporter().importClasses(SchemaPolicyFlywayFixture.class); + + // when + EvaluationResult result = + JpaProductionArchitectureTest.EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY.evaluate( + fixtureOnly); + + // then + assertThat(result.getFailureReport().getDetails()).isEmpty(); + } } diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java index a17fdf6b..07ea43dc 100644 --- a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/JpaProductionArchitectureTest.java @@ -3,8 +3,12 @@ package dev.caskeleton.bootstrap.architecture; import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses; import static org.assertj.core.api.Assertions.assertThat; +import com.tngtech.archunit.base.DescribedPredicate; +import com.tngtech.archunit.core.domain.JavaAccess; import com.tngtech.archunit.core.domain.JavaClasses; +import com.tngtech.archunit.core.domain.JavaConstructor; import com.tngtech.archunit.core.importer.ClassFileImporter; +import com.tngtech.archunit.lang.ArchRule; import dev.caskeleton.adapter.outbound.persistence.migration.FlywaySchemaPolicy; import dev.caskeleton.adapter.outbound.persistence.testkit.arch.JpaArchitectureRules; import jakarta.persistence.Entity; @@ -164,29 +168,63 @@ class JpaProductionArchitectureTest { .check(productionClasses); } + /** + * A call to, or a reference to ({@code FluentConfiguration::new}), a constructor of a type that + * is a Flyway {@code Configuration}. + */ + private static final DescribedPredicate> CONSTRUCTS_A_FLYWAY_CONFIGURATION = + DescribedPredicate.describe( + "a constructor of a Flyway Configuration", + access -> + JavaConstructor.CONSTRUCTOR_NAME.equals(access.getTarget().getName()) + && access + .getTargetOwner() + .isAssignableTo("org.flywaydb.core.api.configuration.Configuration")); + + /** + * Every Flyway the template builds starts from {@code FlywaySchemaPolicy.configure()}. + * + *

Flyway's PostgreSQL default holds its lock in a transaction left open for the whole run, and + * a concurrent index build waits for it without end (re-review 2026-11-03 round 6, RR6-03-01). + * FlywaySchemaPolicy.configure() holds it for the session; a stream that builds its own Flyway + * gets the default back. The inbox stream of adapter:inbound:messaging may not depend on + * persistence-jpa and keeps its own copy, held to the same value by its own test. + * + *

A Flyway has two starts besides the policy: {@code Flyway.configure()}, and a configuration + * built directly — {@code new FluentConfiguration()}, {@code new ClassicConfiguration()}, or a + * class of its own that extends or implements one — which {@code load()} or {@code new + * Flyway(...)} turns into a Flyway. The rule refuses both: the method, and constructing anything + * that is a Flyway {@code Configuration}, by a call or a constructor reference. {@code new + * Flyway(...)} itself stays allowed; over the policy's configuration it is the policy's Flyway + * (round 7, RR7-03-06: the rule saw only the method). The fixtures in {@code + * ..violations.persistence.flyway} and {@code ..allowed.persistence.flyway} show it catches the + * method, both constructors and a constructor reference, and passes the policy. A subclass has no + * fixture: SpotBugs cannot analyse a class that extends Flyway's configuration (it misses {@code + * lombok.Generated}, which the build treats as a failed analysis). Its constructor calls the + * configuration's, the access this rule refuses. + */ + static final ArchRule EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY = + noClasses() + .that() + .doNotHaveFullyQualifiedName(FlywaySchemaPolicy.class.getName()) + .and() + .doNotHaveFullyQualifiedName( + "dev.caskeleton.adapter.inbound.messaging.MessagingInboxSchemaStream") + .should() + .callMethod("org.flywaydb.core.Flyway", "configure") + .orShould() + .callMethod("org.flywaydb.core.Flyway", "configure", "java.lang.ClassLoader") + .orShould() + .accessTargetWhere(CONSTRUCTS_A_FLYWAY_CONFIGURATION) + .because( + "every Flyway the template builds starts from FlywaySchemaPolicy.configure(), which" + + " holds Flyway's PostgreSQL lock for the session (docs/jpa/migration-guide.md," + + " \"Concurrent index builds\")"); + @Test - @DisplayName("Flyway.configure()를 부르는 운영 코드는 FlywaySchemaPolicy뿐이다") + @DisplayName("Flyway.configure()를 부르거나 Flyway 설정 객체를 직접 만드는 운영 코드는 FlywaySchemaPolicy뿐이다") void everyProductionFlywayIsConfiguredThroughTheSchemaPolicy() { - // Flyway's PostgreSQL default holds its lock in a transaction left open for the whole run, and - // a concurrent index build waits for it without end (re-review 2026-11-03 round 6, RR6-03-01). - // FlywaySchemaPolicy.configure() holds it for the session; a stream that builds its own Flyway - // gets the default back. The inbox stream of adapter:inbound:messaging may not depend on - // persistence-jpa and keeps its own copy, held to the same value by its own test. - noClasses() - .that() - .doNotHaveFullyQualifiedName(FlywaySchemaPolicy.class.getName()) - .and() - .doNotHaveFullyQualifiedName( - "dev.caskeleton.adapter.inbound.messaging.MessagingInboxSchemaStream") - .should() - .callMethod("org.flywaydb.core.Flyway", "configure") - .orShould() - .callMethod("org.flywaydb.core.Flyway", "configure", "java.lang.ClassLoader") - .because( - "every Flyway the template builds starts from FlywaySchemaPolicy.configure(), which" - + " holds Flyway's PostgreSQL lock for the session (docs/jpa/migration-guide.md," - + " \"Concurrent index builds\")") - .check(productionClasses); + EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY.check(productionClasses); } @Test diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/SchemaPolicyFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/SchemaPolicyFlywayFixture.java new file mode 100644 index 00000000..39f0c4a7 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/SchemaPolicyFlywayFixture.java @@ -0,0 +1,17 @@ +package dev.caskeleton.bootstrap.architecture.allowed.persistence.flyway; + +import dev.caskeleton.adapter.outbound.persistence.migration.FlywaySchemaPolicy; +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; + +/** Builds a Flyway from the schema policy, the two ways a stream does. */ +public class SchemaPolicyFlywayFixture { + + public Flyway flyway(DataSource dataSource) { + return FlywaySchemaPolicy.configure().dataSource(dataSource).load(); + } + + public Flyway flywayFromTheConstructor(DataSource dataSource) { + return new Flyway(FlywaySchemaPolicy.configure().dataSource(dataSource)); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/package-info.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/package-info.java new file mode 100644 index 00000000..c2487b8a --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/allowed/persistence/flyway/package-info.java @@ -0,0 +1,6 @@ +/** + * "Allowed-as-data" for {@code EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY}: a Flyway built from + * {@code FlywaySchemaPolicy.configure()}, by its builder or by the {@code Flyway} constructor over + * the policy's configuration, is what the rule asks for and is not flagged. + */ +package dev.caskeleton.bootstrap.architecture.allowed.persistence.flyway; diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ClassicConfigurationFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ClassicConfigurationFlywayFixture.java new file mode 100644 index 00000000..2725ccd4 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ClassicConfigurationFlywayFixture.java @@ -0,0 +1,15 @@ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway; + +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; +import org.flywaydb.core.api.configuration.ClassicConfiguration; + +/** Builds a Flyway around {@code new ClassicConfiguration()}, the mutable configuration. */ +public class ClassicConfigurationFlywayFixture { + + public Flyway flyway(DataSource dataSource) { + ClassicConfiguration configuration = new ClassicConfiguration(); + configuration.setDataSource(dataSource); + return new Flyway(configuration); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ConfigureCallingFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ConfigureCallingFlywayFixture.java new file mode 100644 index 00000000..3754f095 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ConfigureCallingFlywayFixture.java @@ -0,0 +1,12 @@ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway; + +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; + +/** Builds a Flyway from {@code Flyway.configure()} instead of the schema policy. */ +public class ConfigureCallingFlywayFixture { + + public Flyway flyway(DataSource dataSource) { + return Flyway.configure().dataSource(dataSource).load(); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/FluentConfigurationFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/FluentConfigurationFlywayFixture.java new file mode 100644 index 00000000..2f7fdea3 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/FluentConfigurationFlywayFixture.java @@ -0,0 +1,13 @@ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway; + +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; +import org.flywaydb.core.api.configuration.FluentConfiguration; + +/** Builds a Flyway from {@code new FluentConfiguration()}, the builder without the method call. */ +public class FluentConfigurationFlywayFixture { + + public Flyway flyway(DataSource dataSource) { + return new FluentConfiguration().dataSource(dataSource).load(); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ReferencedConfigurationFlywayFixture.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ReferencedConfigurationFlywayFixture.java new file mode 100644 index 00000000..b8ecc0fd --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/ReferencedConfigurationFlywayFixture.java @@ -0,0 +1,16 @@ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway; + +import java.util.function.Supplier; +import javax.sql.DataSource; +import org.flywaydb.core.Flyway; +import org.flywaydb.core.api.configuration.FluentConfiguration; + +/** Builds a Flyway through a constructor reference, {@code FluentConfiguration::new}. */ +public class ReferencedConfigurationFlywayFixture { + + private final Supplier configurations = FluentConfiguration::new; + + public Flyway flyway(DataSource dataSource) { + return configurations.get().dataSource(dataSource).load(); + } +} diff --git a/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/package-info.java b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/package-info.java new file mode 100644 index 00000000..62dfada3 --- /dev/null +++ b/src/app-bootstrap/src/architectureTest/java/dev/caskeleton/bootstrap/architecture/violations/persistence/flyway/package-info.java @@ -0,0 +1,8 @@ +/** + * "Violations-as-data" for {@code EVERY_FLYWAY_STARTS_FROM_THE_SCHEMA_POLICY}: each class builds a + * Flyway past {@code FlywaySchemaPolicy.configure()}, one way per class, and so gets Flyway's + * PostgreSQL lock default back — a lock held in a transaction that a concurrent index build waits + * for without end (re-review 2026-11-03 round 6, RR6-03-01; round 7, RR7-03-06: the rule saw only + * {@code Flyway.configure()}). + */ +package dev.caskeleton.bootstrap.architecture.violations.persistence.flyway;