3. 操作系统与基础工具：Windows/macOS/Linux 环境准备

在契约测试与 API 事务边界治理的实践中，开发环境的统一性是降低“在我机器上能跑”类问题的第一道防线。本章将指导你在三大主流操作系统上完成 Git、JDK 17、Node.js 18 和 Python 3.11 的安装与验证。无论你使用哪种系统，最终的环境基线必须一致，才能保证后续 Pact 或 Spring Cloud Contract 的契约验证流水线稳定运行。

3.1 环境基线总览

下表列出了本次课程所需的基础工具及其最低版本要求。请务必安装指定主版本，避免因版本差异导致契约测试框架行为不一致。

工具 最低版本 用途 验证命令
Git 2.30+ 版本控制、契约文件存储与 CI/CD 触发 git --version
JDK 17 LTS Java 微服务、Spring Cloud Contract 运行环境 java -version
Node.js 18 LTS Pact JS、API 网关模拟、契约验证脚本 node --version
Python 3.11 契约测试辅助脚本、数据生成与事务边界校验 python --version
版本对齐提示： 不要安装 JDK 8/11 或 Node.js 16 等旧版本。契约测试框架（如 Pact JVM 4.x、Spring Cloud Contract 4.x）已全面转向 Jakarta EE 和 Java 17+，低版本会导致依赖冲突或运行时异常。

3.2 操作系统专项安装指南

3.2.1 Windows 环境

Windows 用户推荐使用 winget 或 Chocolatey 进行包管理，避免手动下载安装包时遗漏 PATH 配置。

  1. Git：winget install --id Git.Git -e --source winget，安装后重启终端。
  2. JDK 17：推荐 Eclipse Temurin 发行版。winget install EclipseAdoptium.Temurin.17.JDK。
  3. Node.js 18：winget install OpenJS.NodeJS.LTS，安装后自带 npm。
  4. Python 3.11：winget install Python.Python.3.11，安装时勾选“Add Python to PATH”。
Windows 避坑： 安装 JDK 后务必检查 JAVA_HOME 环境变量是否指向 C:\Program Files\Eclipse Adoptium\jdk-17.0.x，且 %JAVA_HOME%\bin 已加入 PATH。Node.js 安装后若 npm 不可用，请以管理员身份运行 PowerShell 并执行 Set-ExecutionPolicy RemoteSigned。

3.2.2 macOS 环境

macOS 用户强烈建议安装 Homebrew，它能够统一管理依赖路径，避免与系统自带工具冲突。

  1. Git：macOS 自带 Git，但版本可能较旧。执行 brew install git 升级到最新版。
  2. JDK 17：brew install openjdk@17，安装后执行 sudo ln -sfn /usr/local/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk 建立符号链接。
  3. Node.js 18：brew install node@18，安装后执行 brew link --overwrite node@18。
  4. Python 3.11：brew install python@3.11，安装后 python3.11 --version 验证。
macOS 提示： 如果系统中同时存在多个 Python 版本，建议使用 python3.11 命令而非 python3，避免指向错误的解释器。JDK 安装后可通过 /usr/libexec/java_home -v 17 确认默认 Java 版本。

3.2.3 Linux 环境（Ubuntu/Debian 系）

Linux 环境是 CI/CD 流水线的典型运行平台，建议在开发机与流水线镜像中保持相同的安装源。

  1. Git：sudo apt update && sudo apt install git -y。
  2. JDK 17：sudo apt install openjdk-17-jdk -y，安装后检查 java -version 输出是否为 17.x。
  3. Node.js 18：使用 NodeSource 官方源：curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -，然后 sudo apt install nodejs -y。
  4. Python 3.11：sudo apt install python3.11 python3.11-venv python3.11-dev -y。
Linux 避坑： 不要使用系统默认的 python3 软链接（通常指向 Python 3.10），请显式使用 python3.11 命令。Node.js 安装后若 npm 版本低于 9，请执行 npm install -g npm@9 升级。

3.3 环境验证清单

安装完成后，请逐项执行以下命令并核对输出。建议将验证结果截图保存，作为后续排错的基线参考。

# Git 验证
git --version
# 期望输出：git version 2.30.0 或更高

# JDK 验证
java -version
# 期望输出：openjdk version "17.0.x" 或 "java version "17.0.x"

# Node.js 验证
node --version
# 期望输出：v18.x.x

# npm 验证（Node.js 附带）
npm --version
# 期望输出：9.x.x 或更高

# Python 验证
python3.11 --version
# 期望输出：Python 3.11.x
基线对齐： 如果团队使用 Docker 开发环境，建议将上述工具版本写入 Dockerfile 作为基础镜像层。后续章节的契约测试示例将默认使用此环境基线，任何版本偏差都可能导致契约验证失败。

3.4 工具链关系与事务边界上下文

下图展示了基础工具在契约测试与 API 事务边界治理中的角色定位。Git 负责契约文件的版本化存储，JDK 和 Node.js 分别支撑 Java 与 JavaScript 微服务的契约生成与验证，Python 则用于编写事务边界校验的辅助脚本。

基础工具在契约测试与事务边界治理中的角色 契约测试核心（Pact / Spring Cloud Contract） Git JDK 17 Node.js 18 Python 3.11 API 事务边界治理（事务传播、补偿、一致性校验） 工具职责说明 • Git：契约文件版本化、分支策略、CI/CD 触发 • JDK 17：Java 微服务契约生成与验证（Spring Cloud Contract） • Node.js 18：JavaScript 微服务契约测试（Pact JS） • Python 3.11：事务边界校验脚本、数据生成与断言辅助

3.5 常见问题与快速修复

问题现象 可能原因 快速修复
java -version 显示旧版本 系统 PATH 中多个 JDK 冲突 调整 JAVA_HOME 环境变量，将其置于 PATH 最前面
npm install 报权限错误 Node.js 安装在系统目录 使用 nvm 管理 Node.js 版本，或配置 npm 全局路径
python3.11 命令未找到 Python 未加入 PATH Windows 重新安装并勾选 PATH；macOS/Linux 使用 brew link 或 apt install 修复
Git 换行符导致契约文件校验失败 Windows 下 core.autocrlf 为 true 执行 git config --global core.autocrlf input，保持 LF 换行符
环境一致性检查点： 在进入下一章之前，请确保你能够在终端中同时执行上述五个验证命令并得到预期输出。任何工具的缺失或版本偏差都会在后续的契约测试示例中引发难以追踪的错误。建议将验证命令写入 check-env.sh 脚本，作为团队 onboarding 的标准步骤。
← 上一章 📖 返回目录 下一章 →