2. 开发环境全景：整体技术栈概览
在契约测试落地API事务边界治理之前，必须首先厘清开发环境的全貌。本章从语言/框架、契约工具链、基础设施三个维度，构建一个可复现的本地开发环境全景图。所有后续章节的配置、脚本、调试均基于此技术栈展开。
2.1 多语言微服务技术栈
本课程选取三种主流后端技术栈作为演示载体，覆盖Java生态、Node.js生态与Python生态。每个服务均承担明确的API事务边界角色。
| 服务角色 | 语言/框架 | API事务边界职责 | 端口 |
|---|---|---|---|
| 订单服务 (Order Service) | Java 17 / Spring Boot 3.x | 创建订单、校验库存、发起支付 | 8081 |
| 库存服务 (Inventory Service) | Node.js 20 / Express | 扣减库存、回滚预留 | 8082 |
| 支付服务 (Payment Service) | Python 3.11 / Flask | 处理支付、返回交易凭证 | 8083 |
选型原则：三种技术栈覆盖了企业级微服务最常见的运行时。Java/Spring Boot 提供强类型契约支持；Node.js 代表高IO场景；Python/Flask 适合快速原型与AI集成。契约测试工具链对三者均有成熟适配。
2.2 契约测试工具链
工具链分为契约生成与验证、API调试、容器化编排三类。下表列出核心工具及其在本环境中的用途。
| 工具 | 版本 | 核心用途 | 与本课程的关系 |
|---|---|---|---|
| Pact (JVM / JS / Python) | 4.x / 10.x / 2.x | 消费者驱动契约测试，生成pact文件 | 跨语言契约验证的核心工具 |
| Spring Cloud Contract | 4.x | 提供者端契约验证，生成桩代码 | 与Spring Boot深度集成，用于订单服务 |
| Postman / Newman | 11.x / 6.x | API调试与集成测试 | 手动验证契约边界，辅助调试 |
| Docker / Docker Compose | 24+ / 2.x | 容器化服务与依赖（数据库、消息队列） | 环境一致性保障，CI/CD基础 |
关键决策：本课程同时使用Pact和Spring Cloud Contract，而非二选一。Pact负责跨语言消费者驱动契约；Spring Cloud Contract负责Java生态内的提供者契约验证。两者互补，覆盖契约测试的完整生命周期。
2.3 开发环境架构总览
下图展示本地开发环境的服务拓扑、契约流动方向以及工具链的交互关系。每个服务运行在独立的Docker容器中，通过定义良好的API边界通信。
2.4 事务边界与契约流动方向
在API事务边界治理中，契约测试的流动方向遵循消费者驱动原则。下图展示一次完整的跨服务事务中，契约从生成到验证的路径。
事务边界陷阱：在分布式事务中，契约测试只能保证API的请求/响应格式正确，无法保证最终一致性。本课程后续章节将演示如何通过契约测试捕获“库存扣减成功但支付超时”这类边界场景，并利用Pact的状态机（provider state）模拟事务中间状态。
2.5 环境版本锁定与兼容性矩阵
为避免“在我机器上能跑”的经典问题，所有依赖版本必须锁定。下表列出经过验证的兼容版本组合。
| 组件 | 最低版本 | 推荐版本 | 备注 |
|---|---|---|---|
| JDK | 17 | 17 LTS 或 21 | Spring Boot 3.x 强制要求 |
| Node.js | 18 | 20 LTS | 支持ESM模块 |
| Python | 3.9 | 3.11 | Flask 3.x 兼容 |
| Docker Engine | 24.0 | 24.0+ | 支持Compose V2 |
| Pact Broker (Docker) | 2.108.0 | latest | 使用pactfoundation/pact-broker镜像 |
| Postman | 10.0 | 11.x | Newman 6.x 用于CI |
2.6 快速启动命令参考
以下命令用于验证开发环境是否就绪。后续章节的配置均假设这些命令能正常执行。
# 验证Java
java --version
# 输出示例: openjdk 17.0.9 2023-10-17 LTS
# 验证Node.js
node --version
# 输出示例: v20.11.0
# 验证Python
python3 --version
# 输出示例: Python 3.11.5
# 验证Docker
docker --version
# 输出示例: Docker version 24.0.7
# 验证Docker Compose
docker compose version
# 输出示例: Docker Compose version v2.24.1
环境一致性建议：推荐使用
.nvmrc（Node.js）、.python-version（pyenv）和 sdk use（SDKMAN! for Java）来锁定本地开发版本。Docker镜像则通过 Dockerfile 中的 FROM 指令锁定基础镜像标签，避免使用 latest。
2.7 本章小结
本章建立了契约测试开发环境的完整全景图：
- 三种技术栈：Java/Spring Boot、Node.js/Express、Python/Flask，分别承载订单、库存、支付服务。
- 四类工具：Pact（跨语言契约）、Spring Cloud Contract（Java生态）、Postman（调试）、Docker（环境标准化）。
- 契约流动方向：消费者生成契约 → Pact Broker存储 → 提供者验证 → 结果反馈。
- 事务边界治理点：契约测试聚焦于API格式与状态机，补偿事务逻辑需额外设计。