fix(architecture): Flyway 규칙이 설정 객체를 직접 만드는 길도 막는다

문제 (재리뷰 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)
This commit is contained in:
DongHyeonka
2026-11-07 01:28:33 +09:00
parent 6ec0c4f7fa
commit 6764246ac9
15 changed files with 215 additions and 32 deletions
@@ -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();
}
}
@@ -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<JavaAccess<?>> 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()}.
*
* <p>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.
*
* <p>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
@@ -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));
}
}
@@ -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;
@@ -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);
}
}
@@ -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();
}
}
@@ -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();
}
}
@@ -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<FluentConfiguration> configurations = FluentConfiguration::new;
public Flyway flyway(DataSource dataSource) {
return configurations.get().dataSource(dataSource).load();
}
}
@@ -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;