4. 开发环境搭建：Python虚拟环境配置、依赖管理、项目目录结构设计

在风控评分通道API的开发中，环境隔离与依赖管理是保障生产一致性的第一道防线。本章将系统讲解Python虚拟环境的创建策略、依赖锁定机制以及标准化的项目目录结构，确保团队协作与持续交付的顺畅。

4.1 Python虚拟环境配置

风控项目通常依赖多个第三方库（如Flask、SQLAlchemy、Redis、Pandas），不同项目间可能存在版本冲突。虚拟环境为每个项目提供独立的Python解释器与包空间，避免全局污染。

4.1.1 虚拟环境工具选型

4.1.2 创建与激活虚拟环境

# 创建虚拟环境（项目根目录下执行）
python -m venv .venv

# 激活虚拟环境（Linux/macOS）
source .venv/bin/activate

# 激活虚拟环境（Windows PowerShell）
.venv\Scripts\Activate.ps1

# 验证当前解释器路径
which python   # Linux/macOS
where python   # Windows

4.2 依赖管理策略

风控评分通道API的依赖分为三类：核心框架（Flask/FastAPI）、数据处理（Pandas/NumPy）、基础设施（Redis/MySQL驱动）。依赖管理需兼顾可复现性与安全性。

4.2.1 依赖清单文件规范

4.2.2 使用 pip-tools 锁定依赖

# 安装 pip-tools（在虚拟环境中）
pip install pip-tools

# 编译顶层依赖，生成锁定文件
pip-compile requirements.in --output-file requirements.txt

# 安装锁定后的依赖
pip-sync requirements.txt

# 开发环境安装全部依赖（含dev）
pip-sync requirements.txt requirements-dev.txt

4.3 项目目录结构设计

风控评分通道API的目录结构需遵循模块化与关注点分离原则。以下为推荐结构，适用于中等规模的风控服务。

risk-scoring-api/
├── .venv/                    # 虚拟环境（不提交Git）
├── .gitignore                # Git忽略规则
├── requirements.in           # 顶层依赖声明
├── requirements.txt          # 锁定依赖
├── requirements-dev.txt      # 开发依赖
├── README.md                 # 项目说明
├── config/                   # 配置管理
│   ├── __init__.py
│   ├── default.py            # 默认配置
│   ├── production.py         # 生产环境配置
│   └── development.py        # 开发环境配置
├── app/                      # 应用主代码
│   ├── __init__.py
│   ├── api/                  # API路由层
│   │   ├── __init__.py
│   │   ├── v1/               # API版本控制
│   │   │   ├── __init__.py
│   │   │   ├── score.py      # 评分接口
│   │   │   └── health.py     # 健康检查
│   │   └── errors.py         # 统一错误处理
│   ├── core/                 # 核心业务逻辑
│   │   ├── __init__.py
│   │   ├── scoring.py        # 评分引擎
│   │   ├── rules.py          # 规则引擎
│   │   └── models.py         # 数据模型
│   ├── middleware/           # 中间件
│   │   ├── __init__.py
│   │   ├── auth.py           # 认证鉴权
│   │   └── logging.py        # 请求日志
│   ├── storage/              # 数据存储层
│   │   ├── __init__.py
│   │   ├── redis_client.py   # Redis客户端
│   │   └── db_client.py      # 数据库客户端
│   └── utils/                # 工具函数
│       ├── __init__.py
│       ├── validators.py     # 参数校验
│       └── encrypt.py        # 加密工具
├── tests/                    # 测试目录
│   ├── __init__.py
│   ├── conftest.py           # 测试夹具
│   ├── test_api/             # API测试
│   └── test_core/            # 核心逻辑测试
├── scripts/                  # 运维脚本
│   ├── start.sh              # 启动脚本
│   └── migrate.sh            # 数据迁移
└── docs/                     # 文档
    ├── api.md                # API文档
    └── deploy.md             # 部署文档

4.3.1 目录职责说明

4.4 环境搭建流程总览

以下SVG图展示了从创建虚拟环境到启动API服务的完整流程，包含依赖管理与目录初始化两个关键分支。

4.5 常见问题与避坑指南

• 跨平台路径问题： 使用 pathlib.Path 替代字符串拼接，确保Windows/Linux/macOS兼容。
• 敏感信息泄露： 配置文件中禁止硬编码数据库密码、API密钥等，统一通过环境变量注入。
• 依赖版本冲突： 定期执行 pip list --outdated 检查依赖更新，但生产环境升级前需在测试环境充分验证。
• 虚拟环境遗忘激活： 在IDE（如VS Code、PyCharm）中设置默认Python解释器为 .venv/bin/python，避免误用全局环境。