Spring Boot 3.5 + Java 25 + Cloud Native 系列（七）：架构质量Quality Gates

@ArchTest
static final ArchRule no_field_injection = fields()
        .should().notBeAnnotatedWith(Autowired.class)
        .because("Use constructor injection instead of @Autowired field injection; "
                + "prefer @RequiredArgsConstructor for conciseness")
        .allowEmptyShould(true);

@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;  // final + 构造器注入
    private final IdempotencyGuard idempotencyGuard;
}

@ArchTest
static final ArchRule no_rest_template = noClasses()
        .should().dependOnClassesThat()
        .haveFullyQualifiedName(RestTemplate.class.getName())
        .because("RestTemplate is in maintenance mode; "
                + "use RestClient or @HttpExchange clients instead")
        .allowEmptyShould(true);

@ArchTest
static final ArchRule no_standard_streams =
        NO_CLASSES_SHOULD_ACCESS_STANDARD_STREAMS.allowEmptyShould(true);

@ArchTest
static final ArchRule kafka_listeners_require_idempotency_guard_or_exemption =
        methods()
                .that().areAnnotatedWith(KafkaListener.class)
                .should(beDeclaredInClassWithIdempotencyGuardOrExemption())
                .because("Kafka listeners must use IdempotencyGuard "
                        + "or document an equivalent mechanism via @IdempotencyExempt")
                .allowEmptyShould(true);

@ArchTest
static final ArchRule idempotency_guard_callers_must_be_transactional =
        methods()
                .that(callIdempotencyGuardExecuteOnce())
                .should().beAnnotatedWith(Transactional.class)
                .because("IdempotencyGuard callers must run inside a @Transactional "
                        + "so the idempotency key and business side-effects "
                        + "are committed atomically")
                .allowEmptyShould(true);

private static DescribedPredicate<JavaMethodCall> callsLegacyExecutorFactory() {
    return new DescribedPredicate<>("...") {
        @Override
        public boolean test(JavaMethodCall call) {
            if (!call.getTarget().getOwner()
                    .isEquivalentTo(java.util.concurrent.Executors.class)) {
                return false;
            }
            String name = call.getTarget().getName();
            return name.equals("newFixedThreadPool")
                    || name.equals("newCachedThreadPool")
                    || name.equals("newSingleThreadExecutor")
                    || name.equals("newScheduledThreadPool");
        }
    };
}

@ArchTest
static final ArchRule services_must_not_depend_on_controllers = noClasses()
        .that().resideInAnyPackage("..service..", "..engine..", "..index..")
        .should().dependOnClassesThat().resideInAPackage("..controller..")
        .because("Service/Engine/Index layers must not depend on the Controller layer; "
                + "keep business logic independent of the HTTP transport layer")
        .allowEmptyShould(true);

@ArchTest
static final ArchRule controllers_must_not_access_repositories = noClasses()
        .that().resideInAPackage("..controller..")
        .should().accessClassesThat()
        .haveSimpleNameEndingWith("Repository")
        .because("Controllers must access data through the Service layer, "
                + "not directly via *Repository")
        .allowEmptyShould(true);

@ArchTest
static final ArchRule no_package_cycles = slices()
        .matching("dev.meirong.shop.(*)..")
        .should().beFreeOfCycles()
        .as("Top-level service packages must be free of cycles; "
                + "share contracts via shop-common and shop-contracts, "
                + "not direct cross-service imports")
        .allowEmptyShould(true);

@ArchTest
static final ArchRule rest_controllers_named_correctly = classes()
        .that().areAnnotatedWith(RestController.class)
        .should().haveSimpleNameEndingWith("Controller")
        .because("All @RestController classes must be named *Controller for consistency");

@ArchTest
static final ArchRule entities_in_domain_package = classes()
        .that().areAnnotatedWith(Entity.class)
        .should().resideInAPackage("..domain..")
        .because("JPA @Entity classes must reside in the ..domain.. package");

@ArchTest
static final ArchRule bff_must_not_have_jpa_entities = noClasses()
        .that().resideInAnyPackage("..buyerbff..", "..sellerbff..")
        .should().beAnnotatedWith(jakarta.persistence.Entity.class)
        .because("BFF modules must not contain @Entity classes; "
                + "fetch data from Domain Services via HTTP")
        .allowEmptyShould(true);

@ArchTest
static final ArchRule contracts_must_be_lightweight = noClasses()
        .that().resideInAPackage("dev.meirong.shop.contracts..")
        .should().dependOnClassesThat().resideInAnyPackage(
                "org.springframework.web.bind.annotation..",
                "org.springframework.web.client..",
                "org.springframework.data..",
                "org.springframework.kafka..",
                "jakarta.persistence..",
                "org.springframework.stereotype..")
        .because("shop-contracts must be a lightweight module "
                + "(DTOs + path constants + validation only); "
                + "adding Spring runtime to contracts forces those dependencies on all consumers")
        .allowEmptyShould(true);

@Test
void apiContracts_useVersionedBasePaths() {
    // 所有 *Api 类的 BASE_PATH 必须包含 /v<版本号> 或 /internal
    for (Class<?> apiType : importTopLevelClasses(API_PACKAGE)) {
        if (!apiType.getSimpleName().endsWith("Api")) continue;
        Field basePath = resolveBasePathField(apiType);
        String value = (String) basePath.get(null);
        if (!value.matches("^/.+/(v\\d+|internal)$")) {
            violations.add(apiType.getName()
                    + " BASE_PATH must end with /v<version> or /internal");
        }
    }
    assertTrue(violations.isEmpty());
}

@Test
void eventContracts_ignoreUnknownFields_andDefaultLegacyMetadata() {
    // 所有事件数据必须标注 @JsonIgnoreProperties(ignoreUnknown = true)
    // 并且 EventEnvelope 的 schemaVersion / contentType 有合理默认值
}

# 创建一个新的领域服务
mvn archetype:generate \
  -DarchetypeGroupId=dev.meirong.shop \
  -DarchetypeArtifactId=domain-service-archetype \
  -DarchetypeVersion=0.1.0-SNAPSHOT \
  -DgroupId=dev.meirong.shop \
  -DartifactId=new-service \
  -DserviceName=new

@Test
void shouldGenerateCompilableProject() throws Exception {
    Path projectDir = generateProject();
    compileProject(projectDir);
    assertThat(projectDir.resolve("target/classes")).exists();
}

// MarketplaceContractTest.java（无 Spring 上下文）
@Test
void deserializeMarketplaceProductResponse() {
    // 启动 WireMock 服务器
    WireMockServer wiremock = new WireMockServer(0);
    wiremock.start();

    // Mock marketplace-service 的返回
    wiremock.stubFor(get(urlPathEqualTo("/api/marketplace/v1/products"))
            .willReturn(aResponse()
                    .withHeader("Content-Type", "application/json")
                    .withBody("""
                    {
                      "traceId": "trace-demo",
                      "status": "SC_OK",
                      "message": "Success",
                      "data": [{
                        "id": "prod-1",
                        "name": "Test Product",
                        "price": 29.99,
                        "inventory": 100
                      }]
                    }
                    """)));

    // Mock ResilienceHelper passthrough
    ResilienceHelper mockHelper = mock(ResilienceHelper.class);
    when(mockHelper.read(anyString(), any(), any()))
            .thenAnswer(inv -> inv.getArgument(1, Supplier.class).get());

    // 验证 buyer-bff 能正确反序列化
    var client = new MarketplaceClient(wiremock.baseUrl());
    var products = client.listProducts();
    assertThat(products).hasSize(1);
    assertThat(products.get(0).name()).isEqualTo("Test Product");
}

# .github/workflows/ci.yml
jobs:
  platform-validate:
    steps:
      - run: bash ./platform/scripts/validate-platform-assets.sh

  maven-verify:
    steps:
      - run: ./mvnw -B -ntp verify

  archetype-test:
    steps:
      - run: ./mvnw -pl shared/shop-common,shared/shop-contracts,tooling/shop-archetypes -am install -B -ntp
      - run: ./mvnw -pl tooling/archetype-tests test -B -ntp

// ❌ 不好
try {
    doSomething();
} catch (Exception e) {
    log.error("Failed", e);  // 吞掉了所有异常类型
}

// ✅ 好
try {
    doSomething();
} catch (SpecificCheckedException e) {
    log.error("Specific failure", e);
    throw new BusinessException(CommonErrorCode.INTERNAL_ERROR, "...", e);
}