📚 课程目录第4章开发环境搭建

4. 开发环境搭建：Python虚拟环境配置、Flask/FastAPI框架选型、依赖管理

在开始编写实时欺诈评分接口之前，必须建立一个干净、可复现的开发环境。本章将指导你完成Python虚拟环境的配置、Web框架的选型分析以及依赖管理的标准化流程。一个良好的环境基础能避免90%以上的“在我机器上能跑”问题，是生产级项目的起点。

4.1 Python虚拟环境配置

虚拟环境为每个项目提供独立的Python解释器和包依赖空间，防止不同项目间的版本冲突。推荐使用Python 3.9+内置的venv模块，无需额外安装。

4.1.1 创建与激活虚拟环境

以下命令在项目根目录下创建名为.venv的虚拟环境文件夹，并激活它。

# 创建虚拟环境（Windows / macOS / Linux 通用）
python -m venv .venv

# 激活虚拟环境
# Windows (CMD/PowerShell)
.venv\Scripts\activate

# macOS / Linux (bash/zsh)
source .venv/bin/activate

# 验证环境
which python   # macOS/Linux: 应显示 .venv/bin/python
where python   # Windows: 应显示 .venv\Scripts\python.exe
python --version  # 确认版本为 3.9+

最佳实践：将虚拟环境文件夹命名为.venv（带点前缀），大多数IDE和代码编辑器会自动识别并忽略该文件夹。同时，务必在.gitignore中添加.venv/，避免将环境文件提交到版本控制。

4.1.2 虚拟环境目录结构

激活后的虚拟环境包含以下核心目录，理解其结构有助于排查依赖问题：

目录/文件	作用
`bin/` (Linux/macOS) 或 `Scripts/` (Windows)	存放Python解释器、pip、激活脚本等可执行文件
`lib/python3.x/site-packages/`	存放所有已安装的第三方包，是依赖管理的核心目录
`pyvenv.cfg`	配置文件，记录虚拟环境关联的系统Python路径和版本

4.2 Web框架选型：Flask vs FastAPI

实时欺诈评分接口对延迟和并发有较高要求。下表从多个维度对比当前最主流的两个Python Web框架，帮助你做出技术选型决策。

对比维度	Flask	FastAPI
异步支持	原生同步，需额外安装 `asyncio` 扩展	原生异步，基于 `asyncio` 和 `Starlette`
性能（请求/秒）	约 3,000 - 5,000（同步阻塞）	约 10,000 - 20,000（异步非阻塞）
数据验证	需手动或借助 `marshmallow`	内置 Pydantic 模型，自动校验与序列化
API文档生成	需集成 `flasgger` 或 `Flask-RESTful`	自动生成 OpenAPI / Swagger 文档
学习曲线	平缓，适合初学者	中等，需理解异步编程概念
社区生态	极其成熟，扩展丰富	快速增长，现代工具链完善
适用场景	中小型项目、原型验证、同步服务	高并发API、实时系统、微服务

  选型结论：本课程选择 FastAPI 作为开发框架。原因如下：实时欺诈评分接口需要处理高并发请求（如每秒数千笔交易），FastAPI的异步非阻塞模型能显著降低延迟；其内置的Pydantic数据验证可直接用于请求参数校验，减少代码量；自动生成的Swagger文档便于测试和联调。

4.3 依赖管理与版本锁定

依赖管理的核心目标是确保开发、测试、生产环境使用完全一致的包版本。推荐使用pip配合requirements.txt文件，或更现代的pipenv/poetry工具。本课程采用最通用的requirements.txt方案，便于团队协作和CI/CD集成。

4.3.1 核心依赖清单

以下是为实时欺诈评分接口项目准备的核心依赖文件，包含框架、数据库驱动、序列化工具等：

# requirements.txt
# Web框架
fastapi==0.110.0
uvicorn[standard]==0.27.1

# 数据验证与序列化
pydantic==2.6.1
pydantic-settings==2.1.0

# 数据库与缓存
asyncpg==0.29.0          # PostgreSQL异步驱动
redis[hiredis]==5.0.3    # Redis缓存，hiredis加速

# 机器学习与特征工程
scikit-learn==1.4.1.post1
pandas==2.2.0
numpy==1.26.4

# 工具与监控
python-json-logger==2.0.7
prometheus-client==0.19.0  # 指标监控
httpx==0.27.0              # 异步HTTP客户端（调用外部风控服务）

# 测试
pytest==8.0.1
pytest-asyncio==0.23.5

4.3.2 依赖安装与冻结

使用以下命令安装依赖并锁定精确版本：

# 安装所有依赖
pip install -r requirements.txt

# 冻结当前环境的精确版本（生成锁文件）
pip freeze > requirements-lock.txt

# 查看已安装包列表
pip list

注意：pip freeze会输出当前环境中所有包（包括依赖的依赖），导致文件冗余。建议使用pip-compile（来自pip-tools）生成更干净的锁定文件。本课程直接使用requirements.txt作为唯一依赖清单，保持简单。

4.4 开发环境架构总览

下图展示了完整的开发环境组件及其交互关系，帮助你建立全局视角：

4.5 环境验证与快速启动

完成上述配置后，执行以下命令验证环境是否就绪：

# 1. 确认虚拟环境已激活（终端提示符应显示 (.venv)）
# 2. 启动一个最小化 FastAPI 应用测试
cat <<EOF > main.py
from fastapi import FastAPI

app = FastAPI(title="Fraud Scoring API")

@app.get("/health")
async def health_check():
    return {"status": "ok", "version": "1.0.0"}
EOF

# 3. 启动服务（开发模式，热重载）
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 4. 在浏览器访问 http://localhost:8000/docs 查看自动生成的 Swagger 文档
# 5. 访问 http://localhost:8000/health 验证接口返回

快速检查清单：

虚拟环境激活后，pip list 输出的包应干净（仅包含 requirements.txt 中的包）。
FastAPI 的 /docs 页面能正常加载 Swagger UI，说明框架和依赖安装正确。
使用 pytest 运行一个空测试文件，确认测试框架可用。

至此，开发环境搭建完成。你拥有了一个基于 FastAPI、配备异步数据库驱动和机器学习库的独立Python环境，可以开始编写实时欺诈评分接口的核心逻辑。