review-followup Wave 3 라운드 3(P21): messaging 플랫폼 — Kafka 소비(MessageHandler 하나), API 정리

- 결정 10: consume 계약을 `MessageHandler<T>` 하나로, starter-kafka가 consumer 조립(handler bean이 있으면 켜짐,
  `app.messaging.enabled=false`로 끔). 오프셋은 handler Success(inbox면 트랜잭션 커밋) 뒤 또는 DLQ 쓰기 확인 뒤에만 커밋,
  auto-commit 금지, `read_committed`, 재시도 소진 → DLQ(없으면 멈춤) — Kafka+PG로 왕복·중복 제거·DLQ 검증
- 미사용 API 타입·Blocking/Reactive/Batch facade·reactor api 노출 삭제, `PublishResult` 정적 factory,
  `MessagingCapabilities` → EnumSet, API leaf 병합(core-api+schema-api, admin-api+admin-runtime), starter god config 분해,
  Kafka broker 설정은 starter-kafka로, 등급 용어 정리
- 결함 수정: Retry 응답이 시도 횟수를 세지 않아 partition 정지(P21-new-1), deliveryAttempt 항상 1(P21-new-2)
- 통합: app-bootstrap `MessagingPublicSurfaceContractTest` 기대값을 P21 변경에 맞춤, starter-kafka에 `api kafka-clients`

검증: ./gradlew check architectureCheck verifyDependencyLocks :app-bootstrap:verifyEnvKeys :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :messaging:messaging-spring-boot-starter:integrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest mainCheck --continue 통과(812 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 13:29:46 +09:00
co-authored by Claude Opus 5.5
parent 6397f52dc8
commit 763392c8b2
188 changed files with 3405 additions and 4015 deletions
@@ -5,22 +5,22 @@ import java.util.Map;
import java.util.Objects;
/**
* The certified broker versions and support tier for every adapter.
* The certified broker versions and support grade for every adapter.
*
* <p>Held as code with a test over it rather than as a document, because a support matrix that
* lives only in prose drifts the first time an adapter is added. The test asserts the rules the
* design fixes: a Stable adapter must run the shared contract and be certified against a live
* broker, and an Experimental adapter must be disabled by default.
*
* <p>The certification claim is derived from lane evidence rather than declared beside the tier, so
* an adapter cannot be promoted by editing a boolean.
* <p>The certification claim is derived from lane evidence rather than declared beside the grade,
* so an adapter cannot be promoted by editing a boolean.
*/
public final class CompatibilityMatrix {
private CompatibilityMatrix() {}
/** The support tier an adapter has earned. */
public enum Tier {
/** The support grade an adapter has earned. */
public enum SupportGrade {
/** Passes the shared adapter contract unchanged. */
STABLE,
@@ -36,14 +36,14 @@ public final class CompatibilityMatrix {
*
* @param adapter the module name
* @param brokerVersions the broker versions the adapter is certified against
* @param tier the support tier
* @param grade the support grade
* @param runsSharedContract whether the module runs {@link MessagingAdapterContract}
* @param enabledByDefault whether the adapter is active without an explicit opt-in
*/
public record Entry(
String adapter,
List<String> brokerVersions,
Tier tier,
SupportGrade grade,
boolean runsSharedContract,
boolean enabledByDefault) {
@@ -51,7 +51,7 @@ public final class CompatibilityMatrix {
* Reports whether a lane has run this adapter against a real broker.
*
* <p>Read from the evidence rather than declared. As a field it was a boolean an author set
* next to the tier, and an Experimental adapter carried {@code true} while no fault scenario
* next to the grade, and an Experimental adapter carried {@code true} while no fault scenario
* had ever been executed against it — the same shape as the coverage matrix that used to assert
* its own constants.
*
@@ -63,7 +63,7 @@ public final class CompatibilityMatrix {
}
public Entry {
Objects.requireNonNull(tier, "tier must not be null");
Objects.requireNonNull(grade, "grade must not be null");
Objects.requireNonNull(brokerVersions, "brokerVersions must not be null");
if (adapter == null || adapter.isBlank()) {
throw new IllegalArgumentException("adapter must not be blank");
@@ -82,7 +82,7 @@ public final class CompatibilityMatrix {
// the locked client is 4.1.1, so the matrix and the support document agreed with each
// other and with nothing that had executed. A version returns here when a lane runs
// against its image.
new Entry("messaging-kafka", List.of("4.1"), Tier.STABLE, true, true));
new Entry("messaging-kafka", List.of("4.1"), SupportGrade.STABLE, true, true));
/**
* Returns every certified adapter.
@@ -23,7 +23,7 @@ class CompatibilityMatrixTest {
@Test
void everyStableAdapterRunsTheSharedContract() {
assertThat(CompatibilityMatrix.entries().values())
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
.filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE)
.isNotEmpty()
.allSatisfy(entry -> assertThat(entry.runsSharedContract()).isTrue());
}
@@ -31,14 +31,14 @@ class CompatibilityMatrixTest {
@Test
void noExperimentalAdapterIsEnabledByDefault() {
assertThat(CompatibilityMatrix.entries().values())
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL)
.filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL)
.allSatisfy(entry -> assertThat(entry.enabledByDefault()).isFalse());
}
@Test
void theStableSetIsExactlyWhatALaneHasCertified() {
assertThat(CompatibilityMatrix.entries().values())
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
.filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE)
.extracting(CompatibilityMatrix.Entry::adapter)
.containsExactly("messaging-kafka");
}
@@ -59,7 +59,7 @@ class CompatibilityMatrixTest {
@Test
void everyStableAdapterHasOnlyExplicitlyApprovedEvidenceGaps() {
assertThat(CompatibilityMatrix.entries().values())
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
.filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE)
.allSatisfy(
entry ->
assertThat(CertifiedEvidence.approvedGaps(entry.adapter()))
@@ -98,14 +98,14 @@ class CompatibilityMatrixTest {
assertThatThrownBy(
() ->
new CompatibilityMatrix.Entry(
"messaging-x", List.of(), CompatibilityMatrix.Tier.STABLE, true, true))
"messaging-x", List.of(), CompatibilityMatrix.SupportGrade.STABLE, true, true))
.isInstanceOf(IllegalArgumentException.class);
}
@Test
void everyStableAdapterIsCertifiedAgainstALiveBroker() {
assertThat(CompatibilityMatrix.entries().values())
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
.filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE)
.isNotEmpty()
.allSatisfy(
entry ->
@@ -119,7 +119,7 @@ class CompatibilityMatrixTest {
@Test
void noExperimentalAdapterClaimsLiveBrokerCertification() {
assertThat(CompatibilityMatrix.entries().values())
.filteredOn(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL)
.filteredOn(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL)
.allSatisfy(entry -> assertThat(entry.hasLiveBrokerCertification()).isFalse());
}
@@ -127,7 +127,11 @@ class CompatibilityMatrixTest {
void anAdapterWithoutEvidenceCannotBeCalledStable() {
CompatibilityMatrix.Entry undeclared =
new CompatibilityMatrix.Entry(
"messaging-artemis", List.of("2.42"), CompatibilityMatrix.Tier.STABLE, true, false);
"messaging-artemis",
List.of("2.42"),
CompatibilityMatrix.SupportGrade.STABLE,
true,
false);
assertThat(undeclared.hasLiveBrokerCertification())
.as("promoting an adapter used to be a boolean an author could set beside the tier")
@@ -35,7 +35,7 @@ class CrossBrokerContractSuite {
private static List<String> stableAdapters() {
return CompatibilityMatrix.entries().values().stream()
.filter(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
.filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE)
.map(CompatibilityMatrix.Entry::adapter)
.toList();
}
@@ -88,7 +88,7 @@ class CrossBrokerContractSuite {
void noExperimentalAdapterClaimsLiveBrokerFaultCoverage() {
List<String> experimental =
CompatibilityMatrix.entries().values().stream()
.filter(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL)
.filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL)
.map(CompatibilityMatrix.Entry::adapter)
.toList();
@@ -62,7 +62,7 @@ class MessagingDocumentationContractTest {
String matrix = read("support-matrix.md");
CompatibilityMatrix.entries().values().stream()
.filter(entry -> entry.tier() == CompatibilityMatrix.Tier.STABLE)
.filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.STABLE)
.forEach(entry -> assertThat(matrix).contains(brokerLabel(entry.adapter())));
}
@@ -71,7 +71,7 @@ class MessagingDocumentationContractTest {
String matrix = read("support-matrix.md");
CompatibilityMatrix.entries().values().stream()
.filter(entry -> entry.tier() == CompatibilityMatrix.Tier.EXPERIMENTAL)
.filter(entry -> entry.grade() == CompatibilityMatrix.SupportGrade.EXPERIMENTAL)
.forEach(
entry ->
assertThat(matrix)
@@ -96,7 +96,7 @@ class MessagingPublicSurfaceContractTest {
assertThat(leaves)
.as("a scan that found no leaf would report every violation as absent")
.hasSizeGreaterThan(20);
.hasSizeGreaterThan(15);
assertThat(
exposedLibraries(
leaves.stream().filter(isNamed("messaging-kafka")).findFirst().orElseThrow()))
@@ -123,8 +123,8 @@ class MessagingPublicSurfaceContractTest {
assertThat(reachable)
.as(
"an empty closure would satisfy the assertion below without proving anything; the "
+ "metrics registry and the reactive facade are exported on purpose")
.contains("io.micrometer:micrometer-core", "io.projectreactor:reactor-core");
+ "metrics registry is exported on purpose (the reactive facade was deleted, S7-#9c)")
.contains("io.micrometer:micrometer-core");
assertThat(reachable)
.as(
"both adapters were exported, so every adopter compiled against two broker SDKs at "