3. 项目环境搭建：Python虚拟环境创建、Java Maven/Gradle项目初始化、Docker Compose编排测试依赖服务

本章是契约测试项目的实操起点。我们将依次完成三部分环境准备：Python 虚拟环境（用于 Pact 验证脚本与聚合查询服务）、Java 项目初始化（用于消费者/提供者端契约测试与错误码聚合服务）、以及Docker Compose 编排（用于数据库、消息队列等测试依赖服务的快速启动）。

3.1 Python 虚拟环境创建

契约测试项目中，Python 主要用于编写消费者端的 Pact 验证脚本、聚合查询的 API 测试以及数据同步的校验工具。推荐使用 venv 或 conda 创建隔离环境。

3.1.1 使用 venv 创建虚拟环境

# 创建项目目录并进入
mkdir contract-testing-project && cd contract-testing-project

# 创建 Python 虚拟环境（Python 3.9+）
python3 -m venv venv

# 激活虚拟环境（Linux/macOS）
source venv/bin/activate

# 激活虚拟环境（Windows）
# venv\Scripts\activate

# 验证 Python 与 pip 路径
which python   # 应指向 venv/bin/python
pip --version

3.1.2 安装核心依赖

在虚拟环境中安装契约测试与数据同步所需的核心库：

pip install pact-python==2.0.0
pip install requests==2.31.0
pip install pydantic==2.5.0
pip install pytest==7.4.0
pip install pyyaml==6.0.1
pip install psycopg2-binary==2.9.9   # PostgreSQL 驱动
pip install kafka-python==2.0.2      # Kafka 客户端

# 生成 requirements.txt
pip freeze > requirements.txt

3.2 Java Maven/Gradle 项目初始化

Java 项目承载消费者与提供者两端的契约测试用例、错误码聚合服务以及数据同步的消费者逻辑。我们同时提供 Maven 和 Gradle 两种构建工具的初始化方式。

3.2.1 Maven 项目初始化

使用 Maven Archetype 快速生成项目骨架：

mvn archetype:generate \
  -DgroupId=com.contract.testing \
  -DartifactId=contract-testing-java \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.4 \
  -DinteractiveMode=false

cd contract-testing-java

在 pom.xml 中添加契约测试与数据同步所需依赖：

<dependencies>
    <!-- Pact JVM 消费者端 -->
    <dependency>
        <groupId>au.com.dius.pact.consumer</groupId>
        <artifactId>junit5</artifactId>
        <version>4.6.0</version>
        <scope>test</scope>
    </dependency>
    <!-- Pact JVM 提供者端 -->
    <dependency>
        <groupId>au.com.dius.pact.provider</groupId>
        <artifactId>junit5</artifactId>
        <version>4.6.0</version>
        <scope>test</scope>
    </dependency>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>3.2.0</version>
    </dependency>
    <!-- PostgreSQL 驱动 -->
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>42.7.1</version>
    </dependency>
    <!-- Kafka 客户端 -->
    <dependency>
        <groupId>org.apache.kafka</groupId>
        <artifactId>kafka-clients</artifactId>
        <version>3.6.0</version>
    </dependency>
</dependencies>

3.2.2 Gradle 项目初始化

使用 Gradle Init 创建项目：

gradle init --type java-application \
  --dsl groovy \
  --test-framework junit-jupiter \
  --project-name contract-testing-java \
  --package com.contract.testing

在 build.gradle 中添加依赖：

dependencies {
    // Pact 消费者端
    testImplementation 'au.com.dius.pact.consumer:junit5:4.6.0'
    // Pact 提供者端
    testImplementation 'au.com.dius.pact.provider:junit5:4.6.0'
    // Spring Boot Web
    implementation 'org.springframework.boot:spring-boot-starter-web:3.2.0'
    // PostgreSQL
    implementation 'org.postgresql:postgresql:42.7.1'
    // Kafka
    implementation 'org.apache.kafka:kafka-clients:3.6.0'
    // JUnit 5
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.1'
}

3.3 Docker Compose 编排测试依赖服务

契约测试与数据同步需要外部基础设施：PostgreSQL（存储错误码与同步状态）、Kafka（事件总线）、Pact Broker（契约存储与验证）。使用 Docker Compose 一键启动所有依赖。

3.3.1 docker-compose.yml 完整配置

version: '3.8'

services:
  # PostgreSQL 数据库
  postgres:
    image: postgres:16-alpine
    container_name: contract-postgres
    environment:
      POSTGRES_DB: contract_testing
      POSTGRES_USER: pactuser
      POSTGRES_PASSWORD: pactpass
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pactuser -d contract_testing"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Kafka 消息队列
  zookeeper:
    image: confluentinc/cp-zookeeper:7.5.0
    container_name: contract-zookeeper
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:7.5.0
    container_name: contract-kafka
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1

  # Pact Broker 契约存储
  pact-broker:
    image: pactfoundation/pact-broker:2.112.0
    container_name: contract-pact-broker
    ports:
      - "9292:9292"
    environment:
      PACT_BROKER_DATABASE_URL: "postgres://pactuser:pactpass@postgres:5432/contract_testing"
      PACT_BROKER_PORT: "9292"
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:

3.3.2 启动与验证

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 验证 PostgreSQL 连接
docker exec -it contract-postgres psql -U pactuser -d contract_testing -c "SELECT 1;"

# 验证 Kafka 可用性
docker exec -it contract-kafka kafka-topics --bootstrap-server localhost:9092 --list

# 访问 Pact Broker（浏览器打开 http://localhost:9292）

3.4 环境架构总览

下图展示了本课程项目环境的整体架构，包含 Python 虚拟环境、Java 项目与 Docker 编排服务之间的调用关系：

3.5 环境验证清单

完成上述步骤后，执行以下验证确保环境就绪：