2. 开发环境搭建：安装 Python 3.11+、Poetry 依赖管理、Docker Desktop、Postman/HTTPie，配置虚拟环境与项目初始化

低延迟评分接口对运行环境的一致性和依赖管理的可复现性要求极高。本章将引导你从零搭建一套标准化的本地开发环境，涵盖 Python 解释器、依赖管理工具、容器化平台以及 API 调试工具，并完成虚拟环境配置与项目骨架初始化。

2.1 环境总览与版本要求

本教程所有代码与配置均基于以下工具链验证。请确保安装的版本不低于表格中的最低版本，以避免因版本差异导致的兼容性问题。

组件 最低版本 用途
Python 3.11 运行时解释器，利用 3.11 的 CPython 性能优化与错误提示增强
Poetry 1.5 依赖解析、虚拟环境管理、构建与发布
Docker Desktop 24 本地容器化运行与生产镜像构建
Postman / HTTPie 最新稳定版 接口调试与压测（二选一）

2.2 安装 Python 3.11+

Python 3.11 引入了 faster CPython 项目的大量优化，包括零成本异常处理、更快的函数调用以及更高效的字节码执行。这些改进对评分接口的毫秒级响应至关重要。

  • Windows：从 python.org 下载 3.11+ 安装包，安装时务必勾选 Add Python to PATH。
  • macOS：推荐使用 Homebrew 安装：brew install python@3.11。
  • Linux (Ubuntu/Debian)：使用 deadsnakes PPA 或源码编译：sudo apt install python3.11 python3.11-venv。
验证安装： 打开终端执行 python3.11 --version，应输出 Python 3.11.x。若系统同时存在多个 Python 版本，建议使用 python3.11 命令而非 python3，避免版本混淆。

2.3 安装 Poetry 依赖管理

Poetry 提供了声明式的 pyproject.toml 配置、自动的虚拟环境隔离以及可锁定的 poetry.lock 文件，确保团队与 CI/CD 环境依赖完全一致。

安装命令（推荐使用官方安装器）：

curl -sSL https://install.python-poetry.org | python3.11 -

安装完成后，将 Poetry 添加到 PATH（通常安装器会自动提示）。验证安装：

poetry --version
避免使用 pip 安装 Poetry： 全局 pip 安装可能导致依赖冲突。始终使用官方安装脚本，确保 Poetry 运行在独立的 Python 环境中。

2.4 安装 Docker Desktop

Docker Desktop 为本地开发提供了与生产环境一致的容器运行时。低延迟评分接口的最终部署将使用 Docker 镜像，因此本地容器化测试是开发流程中不可或缺的一环。

  • Windows / macOS：从 docker.com 下载 Docker Desktop 安装包，安装后启动并确保右下角鲸鱼图标为运行状态。
  • Linux：安装 Docker Engine 与 Docker Compose 插件：sudo apt install docker-ce docker-ce-cli docker-compose-plugin。

验证安装：

docker --version
docker compose version

2.5 安装 API 调试工具：Postman 或 HTTPie

在开发过程中，你需要频繁发送 HTTP 请求测试评分接口的响应时间与正确性。推荐以下两种工具：

工具 类型 适用场景
Postman GUI 图形化 可视化构造请求、管理集合、编写测试脚本
HTTPie CLI 命令行 快速调试、脚本集成、管道操作
  • Postman：从官网下载安装包，安装后注册或跳过登录即可使用。
  • HTTPie：通过 pip 或包管理器安装：pip install httpie 或 brew install httpie。

2.6 项目初始化与虚拟环境配置

以下步骤将创建一个名为 low-latency-scoring 的项目目录，并利用 Poetry 自动创建隔离的虚拟环境。

  1. 创建项目目录并初始化 Poetry 项目：
mkdir low-latency-scoring
cd low-latency-scoring
poetry init --name low-latency-scoring --description "Low latency scoring API" --python "^3.11" --no-interaction

该命令会生成 pyproject.toml 文件，其中声明了项目元数据与 Python 版本约束。

  1. 添加核心依赖：
poetry add fastapi uvicorn[standard] pydantic
  • FastAPI：高性能异步 Web 框架，天然支持异步端点与 Pydantic 模型。
  • Uvicorn：ASGI 服务器，提供极低的请求处理开销。
  • Pydantic：数据验证与序列化，确保评分请求与响应的类型安全。
  1. 激活虚拟环境：
poetry shell

执行后，终端提示符前会出现 (low-latency-scoring-xxxx) 前缀，表示已进入 Poetry 管理的虚拟环境。所有后续的 Python 命令都将在此隔离环境中运行。

  1. 验证环境：
python --version
pip list

确认 Python 版本为 3.11.x，且已安装 FastAPI、Uvicorn、Pydantic 及其依赖。

2.7 环境架构总览

下图展示了本地开发环境中各组件之间的协作关系：

本地开发环境架构 开发机（macOS / Windows / Linux） Python 3.11+ CPython 运行时 Poetry 依赖管理 + 虚拟环境 Docker Desktop 容器化运行环境 low-latency-scoring / 项目目录 pyproject.toml | poetry.lock | src/ | tests/ | Dockerfile Postman / HTTPie Uvicorn (ASGI 服务器)

2.8 验证完整开发链路

完成上述安装后，执行以下快速验证脚本，确保所有工具可正常调用：

# 验证 Python
python3.11 -c "import sys; print(f'Python {sys.version}')"

# 验证 Poetry
poetry --version

# 验证 Docker
docker run --rm hello-world

# 验证 HTTPie（若安装）
http --version
性能基线提示： 在后续章节中，我们将使用 time 命令或 Postman 的响应时间统计来测量接口延迟。确保当前环境无后台高负载进程，以获得稳定的基线数据。

2.9 常见问题与避坑指南

  • Poetry 创建虚拟环境失败： 检查是否已安装 Python 3.11 且 python3.11 命令可用。可尝试 poetry env use python3.11 手动指定解释器。
  • Docker Desktop 启动后容器无法联网： 在 Windows/macOS 上检查 Docker 资源设置中的网络代理配置，确保 DNS 解析正常。
  • Uvicorn 启动报错 ModuleNotFoundError： 确认已在 Poetry 虚拟环境中执行 poetry shell，或使用 poetry run uvicorn 启动。
  • Postman 请求超时： 检查 Uvicorn 是否在预期端口（默认 8000）监听，以及防火墙是否放行。

至此，你的本地开发环境已准备就绪。下一阶段将进入评分接口的核心代码实现。

← 上一章 📖 返回目录 下一章 →