4. Pact框架入门：核心概念、Broker、DSL与SDK配置

Pact是目前业界最成熟的消费者驱动契约测试框架。本章将系统讲解Pact的核心概念、Broker协作机制、DSL语法以及JVM/JS SDK的安装配置，为后续在消息队列场景中实施契约测试奠定基础。

4.1 Pact核心概念

Pact框架围绕三个核心角色构建：消费者（Consumer）、提供者（Provider）和契约（Pact）。消费者定义期望，提供者验证期望，契约作为两者之间的可执行文档。

4.2 Pact Broker：契约的中央存储与版本管理

Pact Broker是契约文件的中央存储库，提供版本管理、环境标记、Webhook通知和网络可视化功能。在微服务和消息队列架构中，Broker是团队间协作的关键基础设施。

4.3 Pact DSL：声明式交互定义

Pact DSL（领域特定语言）是定义消费者-提供者交互的声明式语法。DSL的核心目标是让契约定义可读、可维护且与语言无关。以下以消息队列场景为例，展示DSL的核心元素。

4.3.1 消费者端DSL（生成契约）

// Java JUnit 5 + Pact DSL 示例：消息消费者定义契约
@ExtendWith(PactConsumerTestExt.class)
@PactTestFor(providerName = "payment-gateway", providerType = ProviderType.ASYNCH)
public class OrderMessageConsumerPactTest {

    @Pact(consumer = "order-service")
    public MessagePact createOrderMessagePact(MessagePactBuilder builder) {
        return builder
            .expectsToReceive("a payment confirmation message")
            .withContent(
                new PactDslJsonBody()
                    .stringType("orderId", "ord-2024-001")
                    .stringType("status", "CONFIRMED")
                    .decimalType("amount", 299.99)
                    .stringType("currency", "USD")
                    .object("metadata")
                        .stringType("source", "payment-gateway")
                        .timestamp("processedAt", "yyyy-MM-dd'T'HH:mm:ss")
                    .closeObject()
            )
            .withMetadata(Map.of("contentType", "application/json"))
            .toPact();
    }
}

4.3.2 提供者端DSL（验证契约）

// Java JUnit 5 + Pact DSL 示例：消息提供者验证契约
@ExtendWith(PactVerificationInvocationContextProvider.class)
@PactBroker(url = "${pact.broker.url}")
public class PaymentGatewayMessageProviderTest {

    @PactVerification("payment-gateway")
    @PactTestFor(pactMethod = "createOrderMessagePact")
    public void verifyOrderMessagePact(MessagePactVerificationContext context) {
        context.verifyInteraction()
            .withMessageHandler(message -> {
                // 反序列化消息并验证业务逻辑
                OrderConfirmation confirmation = objectMapper.readValue(
                    message.getContents().valueAsString(),
                    OrderConfirmation.class
                );
                assertThat(confirmation.getStatus()).isIn("CONFIRMED", "PENDING");
            });
    }
}

4.4 Pact JVM SDK 安装与配置

JVM生态是Pact支持最完善的平台。以下为Maven和Gradle项目的标准配置。

4.4.1 Maven 配置示例

<!-- pom.xml 关键配置 -->
<properties>
    <pact.version>4.6.15</pact.version>
</properties>

<dependencies>
    <!-- 消费者测试 -->
    <dependency>
        <groupId>au.com.dius.pact.consumer</groupId>
        <artifactId>junit5</artifactId>
        <version>${pact.version}</version>
        <scope>test</scope>
    </dependency>

    <!-- 提供者验证 -->
    <dependency>
        <groupId>au.com.dius.pact.provider</groupId>
        <artifactId>junit5</artifactId>
        <version>${pact.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

4.4.2 Gradle 配置示例

// build.gradle 关键配置
ext {
    pactVersion = '4.6.15'
}

dependencies {
    testImplementation "au.com.dius.pact.consumer:junit5:$pactVersion"
    testImplementation "au.com.dius.pact.provider:junit5:$pactVersion"
}

// 配置 Pact Broker 信息
pact {
    broker {
        pactBrokerUrl = 'https://pact-broker.example.com'
        pactBrokerToken = System.getenv('PACT_BROKER_TOKEN')
    }
}

4.5 Pact JS SDK 安装与配置

Node.js生态使用 @pact-foundation/pact 包。以下为npm安装和基础配置。

4.5.1 安装命令

# 安装 Pact JS SDK（包含消费者和提供者支持）
npm install --save-dev @pact-foundation/pact

# 安装 TypeScript 类型定义（可选）
npm install --save-dev @types/pact

4.5.2 消费者端JS示例

// message-consumer.pact.test.js
const { MessageConsumerPact, Matchers } = require('@pact-foundation/pact');
const { like, term } = Matchers;

const messagePact = new MessageConsumerPact({
    consumer: 'order-service',
    provider: 'payment-gateway',
    pactfileWriteMode: 'merge',
    logLevel: 'info',
});

describe('Order Service - Message Consumer Pact', () => {
    it('should handle payment confirmation message', () => {
        return messagePact
            .expectsToReceive('a payment confirmation message')
            .withContent({
                orderId: like('ord-2024-001'),
                status: term({ generate: 'CONFIRMED', matcher: '^(CONFIRMED|PENDING)$' }),
                amount: like(299.99),
                currency: like('USD'),
                metadata: {
                    source: like('payment-gateway'),
                    processedAt: term({
                        generate: '2024-12-01T10:30:00',
                        matcher: '\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}'
                    })
                }
            })
            .withMetadata({ contentType: 'application/json' })
            .verify(consumerMessageHandler);
    });
});

4.5.3 提供者端JS示例

// payment-provider.verification.test.js
const { MessageProviderPact, providerWithMetadata } = require('@pact-foundation/pact');

const provider = new MessageProviderPact({
    provider: 'payment-gateway',
    pactBrokerUrl: process.env.PACT_BROKER_URL,
    pactBrokerToken: process.env.PACT_BROKER_TOKEN,
    consumerVersionSelectors: [
        { matchingBranch: true, latest: true }
    ],
});

describe('Payment Gateway - Message Provider Verification', () => {
    it('verifies all consumer pacts', async () => {
        await provider.verify({
            messageHandlers: {
                'a payment confirmation message': (message) => {
                    // 模拟消息处理逻辑
                    const payload = JSON.parse(message.contents.value);
                    return validateAndProcessPayment(payload);
                }
            },
            stateHandlers: {
                'order exists': () => setupTestOrder(),
                'payment processed': () => setupProcessedPayment(),
            }
        });
    });
});

4.6 消息契约测试的完整工作流

以下SVG展示了从消费者定义契约到提供者验证的完整流程，以及Broker在其中的枢纽作用。

4.7 常见问题与最佳实践