4. 环境搭建：Python虚拟环境创建、依赖安装与项目目录结构设计
在开始编写限流熔断代码之前，必须搭建一个干净、可复现的实验环境。本节将带领你完成从虚拟环境创建到依赖安装，再到项目目录结构设计的全过程，确保后续所有案例都能在一致的沙箱中运行。
4.1 Python虚拟环境创建
虚拟环境是Python项目隔离依赖的标准做法。本课程统一使用Python 3.10+，推荐通过 venv 模块创建。
操作步骤：
- 打开终端，进入课程根目录（例如
~/api-rate-limiting-course）。 - 执行
python3 -m venv venv创建名为venv的虚拟环境。 - 激活虚拟环境：
- Linux/macOS：
source venv/bin/activate - Windows：
venv\Scripts\activate
- Linux/macOS：
- 验证激活成功：终端提示符前出现
(venv)前缀。
最佳实践：将虚拟环境目录命名为
venv 并添加到 .gitignore 中，避免将依赖包提交到版本控制。
4.2 依赖安装与版本锁定
本课程核心依赖包括：Flask（API框架）、Redis（分布式计数器后端）、Pyrate-limiter（限流算法库）。以下表格列出各依赖的用途与推荐版本。
| 依赖包 | 版本 | 用途 |
|---|---|---|
flask |
3.0.x | 构建REST API端点，接收客户端请求 |
redis |
5.0.x | 连接Redis实例，存储滑动窗口计数 |
pyrate-limiter |
3.2.x | 提供令牌桶、滑动窗口等限流算法实现 |
gunicorn |
22.0.x | 生产级WSGI服务器（可选，用于压力测试） |
执行以下命令一次性安装所有依赖：
pip install flask redis pyrate-limiter gunicorn安装完成后，使用 pip freeze > requirements.txt 锁定版本，确保团队成员或CI环境能复现完全相同的依赖组合。
避坑提示：Pyrate-limiter 3.x 版本对Redis适配器有独立的安装要求。如果后续遇到
ModuleNotFoundError: No module named 'pyrate_limiter.redis'，请检查是否遗漏了 pip install pyrate-limiter[redis] 扩展安装。
4.3 项目目录结构设计
良好的目录结构能提升代码可维护性。本课程采用分层模块化设计，将限流逻辑、API路由、配置与测试分离。下图展示了完整的项目骨架。
各模块文件的核心职责如下表所示：
| 文件/目录 | 职责 |
|---|---|
app/__init__.py |
Flask应用工厂函数，初始化扩展与蓝图 |
app/routes.py |
定义API端点，绑定限流装饰器 |
app/limiter.py |
封装Pyrate-limiter，创建限流器实例 |
app/middleware.py |
实现请求前拦截与熔断状态检查 |
app/models.py |
数据模型与Redis键值结构定义 |
config/default.py |
默认配置项：限流阈值、时间窗口、Redis地址 |
config/redis_config.py |
Redis连接池配置与健康检查 |
tests/ |
pytest测试用例，覆盖限流逻辑与API响应 |
run.py |
应用入口，启动开发服务器 |
requirements.txt |
依赖锁定文件，用于环境复现 |
4.4 验证环境可用性
完成上述步骤后，执行以下命令快速验证环境是否就绪：
# 激活虚拟环境
source venv/bin/activate
# 检查关键包版本
python -c "import flask; print(f'Flask: {flask.__version__}')"
python -c "import redis; print(f'Redis: {redis.__version__}')"
python -c "from pyrate_limiter import Limiter; print('Pyrate-limiter: OK')"如果所有命令均无报错并正确输出版本号，说明环境搭建成功。接下来即可进入第5章，开始编写第一个限流装饰器。