2. 环境搭建与项目初始化
本章将完成《契约测试驱动数据库缓存API响应格式校验工程》的本地开发环境搭建。一个干净、可复现的Python虚拟环境与结构清晰的项目目录，是后续所有契约编写、测试执行与缓存逻辑实现的基础。我们将按照“环境隔离 → 依赖锁定 → 目录设计”的顺序逐步构建。
2.1 Python虚拟环境与依赖管理
使用 venv 创建隔离环境，并通过 pip 安装核心依赖。所有依赖版本将锁定至 requirements.txt，确保团队与CI环境的一致性。
2.1.1 创建与激活虚拟环境
# 创建虚拟环境（项目根目录下执行）
python -m venv .venv
# 激活环境（Windows）
.venv\Scripts\activate
# 激活环境（macOS/Linux）
source .venv/bin/activate2.1.2 安装核心依赖
本工程依赖分为三类：测试框架、数据库与缓存驱动、契约与校验工具。下表列出各组件的用途与推荐版本。
| 分类 | 包名 | 版本 | 用途 |
|---|---|---|---|
| 测试框架 | pytest | ≥7.4 | 测试用例执行、夹具管理、断言 |
| HTTP客户端 | requests | ≥2.31 | 发送API请求，获取响应 |
| 缓存驱动 | redis | ≥5.0 | 连接Redis，实现缓存读写 |
| ORM引擎 | sqlalchemy | ≥2.0 | 数据库模型定义与查询 |
| Schema校验 | jsonschema | ≥4.20 | 根据JSON Schema校验API响应格式 |
# 一次性安装所有依赖
pip install pytest requests redis sqlalchemy jsonschema
# 将当前环境依赖导出为锁定文件
pip freeze > requirements.txt
💡 最佳实践： 建议将
requirements.txt 纳入版本控制。每次新增或升级依赖后，重新执行 pip freeze > requirements.txt 更新锁定文件，避免因依赖版本不一致导致的“在我机器上能跑”问题。
2.2 项目目录结构设计
合理的目录结构应遵循“关注点分离”原则：将契约定义、测试代码、业务逻辑、配置与工具脚本明确分层。下图展示了本工程的推荐目录骨架。
2.3 各目录与核心文件说明
下表详细说明每个目录与关键文件的职责，帮助团队快速定位代码与契约。
| 目录/文件 | 职责 | 关键内容 |
|---|---|---|
contracts/ |
存放所有API的JSON Schema契约文件 | user_api_schema.json, product_api_schema.json |
tests/ |
存放pytest测试用例与共享夹具 | conftest.py 定义全局fixture，测试文件按模块命名 |
src/ |
业务逻辑实现：缓存、数据库、API客户端、校验器 | cache_manager.py, db_models.py, api_client.py, schema_validator.py |
config/ |
应用配置与环境变量模板 | settings.py 读取环境变量，.env.example 提供模板 |
requirements.txt |
锁定所有依赖及其版本 | 由 pip freeze 自动生成，用于CI/CD与新人快速搭建 |
2.4 初始化脚本与验证
为简化重复操作，建议在项目根目录创建 setup.sh（或 setup.bat）脚本，一键完成环境创建、依赖安装与目录生成。
#!/bin/bash
# setup.sh — 项目初始化脚本
# 1. 创建虚拟环境
python -m venv .venv
# 2. 激活环境并安装依赖
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
# 3. 创建目录结构（如果不存在）
mkdir -p contracts tests src config
# 4. 创建占位文件
touch contracts/.gitkeep
touch tests/.gitkeep
touch src/__init__.py
touch config/.env.example
echo "✅ 环境搭建完成！请执行 source .venv/bin/activate 激活环境。"
✅ 验证清单：
- 执行
pytest --version确认pytest安装成功。 - 执行
python -c "import redis; import sqlalchemy; import jsonschema; print('所有依赖导入成功')"验证核心库可用。 - 检查项目目录是否包含
contracts/、tests/、src/、config/四个子目录。
2.5 环境隔离与版本一致性
在团队协作中，环境不一致是导致测试失败的首要原因。本工程通过以下三重机制确保一致性：
- 虚拟环境隔离：每个开发者拥有独立的
.venv，不污染系统级Python。 - 依赖锁定：
requirements.txt记录精确版本号，CI/CD流水线使用同一文件安装。 - 目录结构标准化：所有成员遵循相同的目录布局，避免因文件路径差异导致的导入错误。
⚠️ 常见陷阱：不要将
.venv/ 目录提交到版本控制。请在项目根目录创建 .gitignore 文件，并添加 .venv/、__pycache__/、*.pyc 等条目。
至此，开发环境已准备就绪。下一阶段将基于此结构，在 contracts/ 目录中编写第一个JSON Schema契约文件，并利用 jsonschema 库进行响应格式校验。