契约测试总失败？不是契约写错了，是提供者数据在“说谎”

在微服务架构中，契约测试（Contract Test）是保障服务间接口兼容性的最后防线。Consumer 端严格按契约生成 Mock 并断言，Provider 端则必须基于真实业务逻辑响应契约定义的消息。然而，大量团队在落地时反复掉进一个陷阱：契约没问题，但提供者端测试总因数据准备不当而失败——订单查询返回空列表，用户状态不匹配，数据库约束冲突……这些问题本质上都是“数据提供者”没伺候好。本文将围绕 Spring Cloud Contract 的提供者测试，拆解数据准备中的常见坑，并给出从硬编码到容器化隔离的一整套解决方案，让你的契约测试稳如磐石。

---

一、契约测试的“阿喀琉斯之踵”：提供者端数据

Spring Cloud Contract 的典型流程是：

1. Consumer 定义契约（Groovy DSL 或 YAML），描述请求、响应体、匹配规则。
2. 契约发布到 Maven 仓库。
3. Provider 依赖契约，在测试中自动生成基于契约的测试用例，调用自己的 Controller，验证返回是否符合契约。

重点在第三步：Provider 的 Controller 需要返回契约中约定的数据，但 Controller 往往依赖 Service 层，Service 又依赖数据库、缓存、外部 API。如果测试环境中没有正确的数据，Controller 就会返回 404、空列表或错误信息，导致契约测试失败。这些失败并不是接口实现有误，而是测试数据没给对。

这就是“数据提供者”问题——如何为契约测试稳定、可重复地准备上下文数据。

---

二、常见的数据提供者疑难杂症

2.1 硬编码测试数据：成也萧何败萧何

直接在 given 块或 @Before 中写死数据：

@BeforeEach
public void setup() {
    userRepository.save(new User(1L, "test@example.com", "ACTIVE"));
}

契约测试期望返回 ID=1 的用户，但如果上一次测试未清理，或 ID 自增导致冲突，测试立刻崩溃。多个契约共享同一数据库，数据相互覆盖更是家常便饭。

2.2 状态泄漏：一个测试喂的数据毒死了另一个测试

契约测试 A 要求用户状态为 ACTIVE，测试 B 要求状态为 INACTIVE。如果它们在同一个 Spring 上下文里顺序执行且不清理，B 可能读到 A 残留的 ACTIVE 用户，断言失败。

2.3 外部依赖幽灵：第三方 API 没准备好

Provider 的 Service 可能调用外部支付网关来获取汇率，但契约测试中没有这个网关。如果不 mock 外部依赖，测试会因超时或连接失败而报错，掩盖真正的契约问题。

2.4 契约与提供者数据库的不匹配

契约里定义了 "discount": 0.2，但提供者数据库里的产品打折比例是 0.15，测试失败。这种不是代码逻辑错误，而是测试数据与契约期望不一致。

2.5 多契约并行执行时的资源争抢

当多个契约测试并行执行时，共用同一个数据库和缓存，极易出现主键冲突、数据覆盖，甚至死锁。

---

三、数据提供者的黄金法则：隔离、幂等、自动化

要解决上述问题，提供者端测试的数据准备必须遵循三条原则：

• 隔离性：每个契约测试拥有独立的数据上下文，互不干扰。
• 幂等性：无论执行多少次，只要契约不变，测试结果一致。
• 自动化：数据准备全部由代码或脚本完成，无需人工预置。

Spring Cloud Contract 通过 BaseClass 和 test fixtures 提供了实现这些原则的机制。

---

四、方案一：使用 BaseClass 统一管理数据工厂

Spring Cloud Contract 的提供者测试会自动生成一个测试类，继承你指定的 BaseClass。你可以在 BaseClass 中定义数据准备方法，并利用 @BeforeEach、@AfterEach、@Sql 等控制数据生命周期。

4.1 基础模板

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
@AutoConfigureMockMvc
public abstract class ContractBaseClass {

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private UserRepository userRepository;

    @BeforeEach
    public void setup() {
        // 准备契约需要的标准数据
        userRepository.deleteAll();
        userRepository.save(new User(1L, "contract-test@example.com", "ACTIVE"));
    }

    // 可选：发布 mock 端点
    @TestConfiguration
    static class MockConfig {
        @Bean
        @Primary
        public PaymentGateway paymentGateway() {
            return mock(PaymentGateway.class);
        }
    }
}

然后在提供者模块的 pom.xml 或 build.gradle 中配置：

contracts {
    baseClassForTests = 'com.example.ContractBaseClass'
}

4.2 使用 @Sql 精确控制数据

当数据逻辑复杂时，可以配合 @Sql 脚本在测试前后执行：

@BeforeEach
@Sql(scripts = "/contracts/sql/insert_user.sql", executionPhase = Sql.ExecutionPhase.BEFORE_TEST_METHOD)
@Sql(scripts = "/contracts/sql/cleanup.sql", executionPhase = Sql.ExecutionPhase.AFTER_TEST_METHOD)
public void setup() { }

insert_user.sql 中插入恰好满足契约的数据，cleanup.sql 则清空表。注意脚本必须幂等，多次执行无副作用。

4.3 多个契约的差异化数据

如果有多个契约，可以在 BaseClass 中提供辅助方法，由生成的测试代码调用，或利用 @Nested 结构组织。更推荐的方式是：在契约的 request 中携带触发条件，让 Controller 的路由逻辑能够区分测试场景，然后 BaseClass 根据请求参数动态准备数据。

例如：契约定义请求参数 ?userId=999，BaseClass 预置 id=999 的用户。这样每个契约测试使用唯一的参数，自然隔离。

---

五、方案二：Testcontainers 实现真正的数据库隔离

对于数据库结构复杂、数据量大的项目，手动管理 SQL 脚本极易出错。使用 Testcontainers 为提供者测试启动专用容器，并通过 @ServiceConnection 动态注入数据源，可以做到完全隔离。

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
@AutoConfigureMockMvc
@Testcontainers
public abstract class ContractBaseClass {

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

    @Autowired
    private MockMvc mockMvc;

    @BeforeEach
    public void setup() {
        // 使用 JdbcTemplate 或 Spring Data 初始化数据
    }
}

好处：每个测试类（或所有契约测试）共享同一个容器实例（通过 static），但通过 @BeforeEach 清空表并插入专用数据，速度与隔离性兼备。也可启用容器重用（testcontainers.reuse.enable=true）加速。

对于需要外部 API mock 的场景，可在 BaseClass 中集成 WireMock 或 MockServer，并注入覆盖真实 Bean 的 mock。

---

六、方案三：契约驱动的数据生成——让契约“告诉”提供者要什么

更高级的玩法是，从契约中解析预期状态，然后自动构建对应的实体，免去手动编写 setup() 的麻烦。

6.1 利用 Spring Cloud Contract 的 TestGenerator

在 BaseClass 中注入 ContractVerifierUtil 或自定义注解，获取当前测试对应的契约期望。但这种方式侵入性强，维护成本较高，适合大规模契约的场景。

6.2 约定标签触发

在契约的 description 或 name 中加入特殊标记，例如 #user-active，然后在 BaseClass 的 @BeforeEach 中解析当前测试方法名（通过 JUnit 5 的 TestInfo），根据标记选择不同的数据预制策略。

@BeforeEach
public void setup(TestInfo testInfo) {
    String methodName = testInfo.getTestMethod().get().getName();
    if (methodName.contains("active")) {
        userRepository.save(new User(1L, "active@test.com", "ACTIVE"));
    } else if (methodName.contains("inactive")) {
        userRepository.save(new User(2L, "inactive@test.com", "INACTIVE"));
    }
}

但这种靠命名约定的方式不够稳健，建议还是通过请求参数显式区分。

---

七、排查与诊断：当提供者测试失败时，你怎么知道是数据的锅？

7.1 观察报错上下文

• 如果错误是 404 NOT_FOUND，大概率是数据没插入或查询条件不匹配。
• 如果是 200 但响应体与契约不匹配（如某个字段为 null 而非期望值），检查数据库对应字段值是否正确。
• 如果是 500 或异常栈，通常是数据完整性问题（如非空约束）或外部调用超时。

7.2 启用 SQL 日志

logging:
  level:
    org.springframework.jdbc.core: TRACE
    org.hibernate.SQL: DEBUG

观察测试过程中实际执行的 SQL，对比契约期望，即可定位数据缺失。

7.3 单独调试提供者端点

暂停契约测试，用 MockMvc 单独写一个测试，手动调用相同的端点并输入同样的请求，快速验证数据是否就绪。

---

八、常见坑点与避坑指南

坑	症状	解法
@BeforeEach 中用了 @Transactional，但 Service 内部使用 Propagation.REQUIRES_NEW	数据提交无法回滚，污染下个契约	契约测试通常不开启事务，直接使用 @Sql 清理，或取消 @Transactional
契约测试依赖了真实的外部服务	测试随机失败	在 BaseClass 中 Mock 掉所有外部 API，或使用 WireMock 容器
多个契约测试共享静态状态（如 static 缓存）	并行执行出现脏数据	将缓存改为实例变量，或在 @BeforeEach 中清空
提供者测试未加载完整的 Spring 上下文	@WebMvcTest 丢失了 Service 自动配置	使用 @SpringBootTest 保证全量加载，或精确指定 @Import
契约中的 JSON Path 与提供者返回字段名大小写不一致	断言失败	检查 Jackson 配置，确保契约和实际序列化规则一致

---

九、最佳实践总结：契约测试提供者数据的五层保障

1. 基础设施层：使用 Testcontainers 或内存数据库，确保数据库随时可用且隔离。
2. 数据预制层：通过 @BeforeEach + 专用 SQL 脚本或 Repository 插入数据，脚本与契约一一对应。
3. Mock 层：所有外部依赖（支付、短信、RPC）一律在 BaseClass 中 Mock 并 @Primary 覆盖。
4. 清理层：@AfterEach 清空表，或依赖事务回滚（仅限简单场景），保证无残留。
5. 验证层：在 CI 中并行运行契约测试，利用数据库隔离杜绝资源竞争，让每一次失败都是真正的接口问题。

契约测试的终极目标不是“让测试通过”，而是“让服务提供方和消费方对接口达成铁一般的共识”。数据提供者就是这份共识的白纸黑字——只有数据对，契约才会对。现在，检查你的 BaseClass，看看有没有遗漏的 @MockBean 或残留的硬编码数据，治好“数据说谎症”，让你的契约测试真正成为微服务信任的基石。