247｜集成测试与契约测试：Testcontainers、消费者驱动契约和环境治理

// 单元测试中 Mock 了 Repository
when(userRepository.save(any(User.class))).thenReturn(savedUser);
when(emailService.sendWelcomeEmail(anyString())).thenReturn(true);

// 测试通过 ✓
User result = userService.register("alice@example.com", "password123");
assertEquals("alice@example.com", result.getEmail());

                    执行速度
                    ↑
        ┌──────────┐
        │   E2E    │  慢（分钟级）  → 覆盖面广，但定位问题难
        ├──────────┤
        │ 集成测试  │  中（秒～分钟）→ 验证组件交互，ROI 最高
        ├──────────┤
        │ 单元测试  │  快（毫秒级）  → 验证逻辑正确性，但无法发现集成问题
        └──────────┘
                    → 反馈精度

@Testcontainers
class UserRepositoryTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldPersistAndRetrieveUser() {
        User user = new User("alice@example.com", "Alice");
        userRepository.save(user);

        Optional<User> found = userRepository.findByEmail("alice@example.com");
        assertThat(found).isPresent();
        assertThat(found.get().getName()).isEqualTo("Alice");
    }
}

// 这条 SQL 在 H2 上正常运行，在 PostgreSQL 上直接报错
@Query("SELECT * FROM users WHERE metadata->>'role' = :role")
List<User> findByRole(@Param("role") String role);

// MySQL
@Container
static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0");

// PostgreSQL
@Container
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");

// 通过 TC_INITSCRIPT 初始化表结构
@Container
static PostgreSQLContainer<?> postgresWithSchema = new PostgreSQLContainer<>("postgres:15")
        .withInitScript("schema.sql");

@Container
static KafkaContainer kafka = new KafkaContainer(
        DockerImageName.parse("confluentinc/cp-kafka:7.5.0"));

@DynamicPropertySource
static void kafkaProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.kafka.bootstrap-servers", kafka::getBootstrapServers);
}

@Container
static GenericContainer<?> redis = new GenericContainer<>("redis:7-alpine")
        .withExposedPorts(6379);

@Container
static GenericContainer<?> customService = new GenericContainer<>(
        new ImageFromDockerfile()
                .withDockerfile(Paths.get("src/test/resources/Dockerfile")))
        .withExposedPorts(8080)
        .waitingFor(Wait.forHttp("/health").forStatusCode(200));

@Container static    → JVM 内共享，测试类间复用（通过 ryuk 管理）
@Container instance  → 每个测试类独立容器
手动 start/stop      → 完整控制权，适合非 JUnit 场景

@DataJpaTest
@Testcontainers
class OrderRepositoryTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");

    @DynamicPropertySource
    static void datasourceConfig(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Autowired
    private OrderRepository orderRepository;

    @Autowired
    private TestEntityManager em;

    @Test
    void shouldFindOrdersByStatus() {
        // TestEntityManager 提供便捷的 persistAndFlush
        Order order = new Order("ORD-001", OrderStatus.PENDING);
        em.persistAndFlush(order);

        List<Order> pending = orderRepository.findByStatus(OrderStatus.PENDING);
        assertThat(pending).hasSize(1);
    }
}

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Testcontainers
class OrderServiceIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");

    @Container
    static KafkaContainer kafka = new KafkaContainer(
            DockerImageName.parse("confluentinc/cp-kafka:7.5.0"));

    @Container
    static GenericContainer<?> redis = new GenericContainer<>("redis:7-alpine")
            .withExposedPorts(6379);

    @DynamicPropertySource
    static void properties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
        registry.add("spring.kafka.bootstrap-servers", kafka::getBootstrapServers);
        registry.add("spring.redis.host", redis::getHost);
        registry.add("spring.redis.port", () -> redis.getMappedPort(6379));
    }

    @Autowired
    private TestRestTemplate restTemplate;

    @Autowired
    private KafkaTemplate<String, Object> kafkaTemplate;

    @Test
    void shouldCreateOrderAndPublishEvent() {
        // 1. 发送 HTTP 请求创建订单
        OrderRequest request = new OrderRequest("item-1", 2);
        ResponseEntity<OrderResponse> response = restTemplate.postForEntity(
                "/api/orders", request, OrderResponse.class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        String orderId = response.getBody().getOrderId();

        // 2. 验证 Kafka 消息已发送（使用 Awaitility 轮询等待）
        await().atMost(5, TimeUnit.SECONDS)
                .untilAsserted(() -> {
                    ConsumerRecord<String, Object> record = consumeOne("order-created");
                    assertThat(record.key()).isEqualTo(orderId);
                });

        // 3. 验证数据库状态
        Order savedOrder = orderRepository.findById(orderId).orElseThrow();
        assertThat(savedOrder.getStatus()).isEqualTo(OrderStatus.CREATED);
    }
}

Order Service (消费者)  ───HTTP───>  User Service (提供者)
需要: GET /users/{id} 返回 {id, name, email}

1. 消费者编写测试 → 生成契约文件（JSON）
2. 契约文件发布到 Pact Broker（契约交换中心）
3. 提供者 CI 拉取契约文件 → 验证 API 满足契约
4. Broker 提供兼容性矩阵 → 告知是否可以安全部署

{
  "consumer": { "name": "Order Service" },
  "provider": { "name": "User Service" },
  "interactions": [
    {
      "description": "获取用户信息",
      "request": {
        "method": "GET",
        "path": "/users/123",
        "headers": { "Accept": "application/json" }
      },
      "response": {
        "status": 200,
        "headers": { "Content-Type": "application/json" },
        "body": {
          "id": 123,
          "name": "Alice",
          "email": "alice@example.com"
        }
      }
    }
  ]
}

@ExtendWith(PactConsumerTestExt.class)
@PactTestFor(providerName = "UserService", port = "8080")
class OrderServiceConsumerPactTest {

    @Pact(consumer = "OrderService")
    public V4Pact createUserPact(PactDslWithProvider builder) {
        return builder
            .given("用户 123 存在")
            .uponReceiving("获取用户信息请求")
                .path("/users/123")
                .method("GET")
                .headers("Accept", "application/json")
            .willRespondWith()
                .status(200)
                .headers(Map.of("Content-Type", "application/json"))
                .body(newJsonBody(body -> {
                    body.stringType("name", "Alice");
                    body.stringType("email", "alice@example.com");
                    body.integerType("id", 123);
                }).build())
            .toPact(V4Pact.class);
    }

    @Test
    @PactTestFor(pactMethod = "createUserPact")
    void shouldFetchUser(MockServer mockServer) {
        // Pact 启动了一个 Mock Server，行为与契约定义一致
        UserClient client = new UserClient(mockServer.getUrl());

        User user = client.getUser(123L);

        assertThat(user.getName()).isEqualTo("Alice");
        assertThat(user.getEmail()).isEqualTo("alice@example.com");
    }
}

@Provider("UserService")
@PactBroker(url = "https://pact-broker.example.com")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserServiceProviderPactTest {

    @LocalServerPort
    private int port;

    @BeforeEach
    void setUp(PactVerificationContext context) {
        context.setTarget(new HttpTestTarget("localhost", port));
    }

    @TestTemplate
    @ExtendWith(PactVerificationInvocationContextProvider.class)
    void verifyPacts(PactVerificationContext context) {
        context.verifyInteraction();
    }

    // 设置提供者状态：Pact 的 given() 会触发此方法
    @State("用户 123 存在")
    void user123Exists() {
        userRepository.save(new User(123L, "Alice", "alice@example.com"));
    }
}

Pact Broker 页面（概念上）：
┌────────────────────────────────────────────┐
│ Order Service (Consumer)                    │
│  ├── 期望 User Service 的 GET /users/{id}   │
│  ├── 期望 Inventory Service 的 POST /stock  │
│  └── 期望 Payment Service 的 POST /pay      │
│                                              │
│ User Service (Provider)                      │
│  ├── 被 Order Service 消费                   │
│  ├── 被 Notification Service 消费            │
│  └── 最后一次验证：✅ 2026-09-09 10:30       │
└────────────────────────────────────────────┘

sequenceDiagram
    participant C as 消费者 CI
    participant B as Pact Broker
    participant P as 提供者 CI

    C->>C: 运行消费者 Pact 测试
    C->>B: 上传契约文件 (consumer=OrderService v1.2.0)
    B->>P: Webhook 触发提供者验证
    P->>B: 拉取所有未验证的消费者契约
    P->>P: 启动提供者服务
    P->>P: 重放每个契约文件中的请求
    P->>B: 上传验证结果 (✅/❌)
    B->>C: 通知验证结果
    Note over C,P: 提供者验证通过 → 消费者可以安全部署

# 查询 Pact Broker：OrderService v1.2.0 可以部署到生产吗？
pact-broker can-i-deploy \
  --pacticipant OrderService \
  --version 1.2.0 \
  --to-environment production

集成测试环境 = Testcontainers 容器组 + application-test.properties

# docker-compose-test.yml（CI 中的可选后备方案）
version: "3.8"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: testdb
    ports:
      - "5432"
  kafka:
    image: confluentinc/cp-kafka:7.5.0
    environment:
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092

@Sql(scripts = "/sql/init-orders.sql", executionPhase = Sql.ExecutionPhase.BEFORE_TEST_METHOD)
@Sql(scripts = "/sql/cleanup.sql", executionPhase = Sql.ExecutionPhase.AFTER_TEST_METHOD)
@Test
void shouldCalculateOrderTotal() { ... }

@Test
void shouldFindPendingOrders() {
    // Arrange: 使用 Builder 模式构造测试数据
    Order order = OrderBuilder.anOrder()
            .withStatus(OrderStatus.PENDING)
            .withItems(2)
            .build();
    orderRepository.save(order);

    // Act
    List<Order> pending = orderService.findPendingOrders();

    // Assert
    assertThat(pending).hasSize(1);
}

@Component
public class OrderFixtures {
    @Autowired
    private OrderRepository orderRepository;

    public Order createPendingOrder(String orderId) {
        Order order = new Order(orderId, OrderStatus.PENDING);
        return orderRepository.save(order);
    }
}

git push
  │
  ├─ 1. 编译 + 静态检查 (30s)
  ├─ 2. 单元测试 (1-2min)
  ├─ 3. 持久化集成测试 (2-3min)    ← @DataJpaTest + Testcontainers
  ├─ 4. API 集成测试 (3-5min)       ← @SpringBootTest + Testcontainers
  ├─ 5. 契约验证 (1-2min)           ← Pact 提供者验证
  └─ 6. E2E 测试 (10-15min)         ← 仅主分支

# .github/workflows/ci.yml 关键配置
jobs:
  integration-test:
    runs-on: ubuntu-latest
    services:
      # 可选：如果 CI 不支持 Docker-in-Docker
      docker:
        image: docker:24-dind
    steps:
      - uses: actions/checkout@v4
      - name: Run integration tests
        run: ./gradlew integrationTest
        env:
          # 关键：CI 中 Testcontainers 需要连接 Docker daemon
          DOCKER_HOST: unix:///var/run/docker.sock
          TESTCONTAINERS_RYUK_DISABLED: "false"

消费者 CI:
  1. 运行消费者 Pact 测试 → 生成契约文件
  2. 上传契约文件到 Pact Broker
  （不需要启动提供者服务）

提供者 CI（由 Pact Broker Webhook 触发或定时执行）:
  1. 从 Broker 拉取所有消费者的契约文件
  2. 启动提供者服务（通常 + Testcontainers 数据库）
  3. 重放所有契约请求 → 验证响应
  4. 将验证结果回传到 Broker

// 反模式：用 @SpringBootTest 测试纯业务逻辑
@SpringBootTest
class DiscountCalculatorTest {
    @Autowired
    private DiscountCalculator calculator;  // 启动整个容器只为这个

    @Test
    void shouldApplySeasonalDiscount() {
        assertThat(calculator.calculate(100, "SUMMER")).isEqualTo(80);
    }
}

// 反模式：static 字段在测试间共享
static Long sharedOrderId;  // ❌ 测试执行顺序变化会导致结果不确定

@Test
void shouldCreateOrder() {
    sharedOrderId = orderService.create(new OrderRequest(...));
}

@Test
void shouldCancelOrder() {
    orderService.cancel(sharedOrderId);  // 依赖上一个测试先执行
}

// 反模式：@SpringBootTest 中又 Mock 了全部外部服务
@SpringBootTest
class OrderServiceTest {
    @MockBean
    private PaymentGateway paymentGateway;  // 全 Mock 了
    @MockBean
    private InventoryClient inventoryClient;
    @MockBean
    private NotificationService notificationService;

    // 这和单元测试有什么区别？
}

// 反模式：在契约中规定了不关心的字段
.willRespondWith()
    .body(newJsonBody(body -> {
        body.stringType("name", "Alice");
        body.stringType("email", "alice@example.com");
        body.integerType("id", 123);
        body.stringType("createdAt", "2026-01-01T00:00:00Z");  // 消费者根本不关心
        body.stringType("updatedAt", "2026-01-01T00:00:00Z");  // 也不关心
        body.integerType("version", 1);                         // 也不关心
    }).build())