2. 开发环境搭建与依赖管理

实时交易风控系统对环境的隔离性、组件的稳定性和目录的可维护性要求极高。本章将指导你从零搭建一套生产级别的 Python 开发环境，涵盖虚拟环境管理、Web 框架选型、关键中间件安装以及项目目录结构设计。

2.1 Python 虚拟环境创建

虚拟环境是 Python 项目依赖隔离的基石。在交易风控场景中，不同策略或回测框架可能依赖同一库的不同版本，虚拟环境能有效避免“依赖地狱”。

2.1.1 使用 venv 创建

Python 3.3+ 内置 venv 模块，无需额外安装。推荐在项目根目录下创建虚拟环境。

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

# 激活虚拟环境（Windows）
venv\Scripts\activate

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

2.1.2 使用 pipenv 管理依赖

pipenv 自动管理 Pipfile 和 Pipfile.lock，确保依赖版本锁定，适合团队协作。

# 安装 pipenv
pip install pipenv

# 安装项目依赖（自动创建虚拟环境）
pipenv install fastapi uvicorn redis psycopg2-binary

# 激活虚拟环境
pipenv shell

2.2 Web 框架选择：FastAPI vs Flask

实时风控 API 对并发性能、异步支持和数据校验有较高要求。下表从关键维度对比 FastAPI 和 Flask：

2.3 关键中间件安装与配置

2.3.1 Redis 安装（数据缓存与消息队列）

Redis 在风控系统中承担双重角色：作为高频数据缓存（如行情快照、账户余额）和轻量级消息队列（如风控事件通知）。

# macOS (Homebrew)
brew install redis
brew services start redis

# Ubuntu/Debian
sudo apt update
sudo apt install redis-server
sudo systemctl enable redis
sudo systemctl start redis

# Windows (WSL 或 Docker)
# 推荐使用 Docker 运行
docker run --name redis -p 6379:6379 -d redis:7-alpine

验证安装：

redis-cli ping
# 输出：PONG

2.3.2 PostgreSQL 安装（持久化存储）

PostgreSQL 用于存储交易订单、风控规则、审计日志等结构化数据，支持事务和复杂查询。

# macOS (Homebrew)
brew install postgresql@16
brew services start postgresql@16

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Windows (Docker)
docker run --name postgres -e POSTGRES_PASSWORD=risk123 -p 5432:5432 -d postgres:16-alpine

创建风控专用数据库：

# 进入 PostgreSQL 命令行
psql -U postgres

# 创建数据库和用户
CREATE DATABASE trading_risk;
CREATE USER risk_user WITH PASSWORD 'risk_pass';
GRANT ALL PRIVILEGES ON DATABASE trading_risk TO risk_user;
\q

2.4 项目目录结构设计

良好的目录结构能提升代码可维护性和团队协作效率。以下是本课程推荐的实时交易风控 API 项目结构：

trading-risk-api/
├── app/                        # 主应用代码
│   ├── __init__.py
│   ├── main.py                 # FastAPI 应用入口
│   ├── config.py               # 配置管理（环境变量读取）
│   ├── api/                    # 路由层
│   │   ├── __init__.py
│   │   ├── v1/                 # API 版本控制
│   │   │   ├── __init__.py
│   │   │   ├── orders.py       # 订单相关接口
│   │   │   ├── risk.py         # 风控规则接口
│   │   │   └── account.py      # 账户查询接口
│   ├── core/                   # 核心业务逻辑
│   │   ├── __init__.py
│   │   ├── risk_engine.py      # 风控引擎
│   │   ├── order_validator.py  # 订单校验器
│   │   └── position_manager.py # 持仓管理
│   ├── models/                 # 数据模型（Pydantic + SQLAlchemy）
│   │   ├── __init__.py
│   │   ├── schemas.py          # Pydantic 请求/响应模型
│   │   └── database.py         # 数据库 ORM 模型
│   ├── services/               # 服务层（外部依赖封装）
│   │   ├── __init__.py
│   │   ├── redis_client.py     # Redis 客户端封装
│   │   └── postgres_client.py  # PostgreSQL 客户端封装
│   └── utils/                  # 工具函数
│       ├── __init__.py
│       ├── logger.py           # 日志配置
│       └── exceptions.py       # 自定义异常
├── tests/                      # 测试目录
│   ├── __init__.py
│   ├── test_risk_engine.py
│   └── test_orders.py
├── scripts/                    # 运维脚本
│   ├── init_db.sql             # 数据库初始化 SQL
│   └── seed_data.py            # 测试数据填充
├── .env                        # 环境变量（不提交到 Git）
├── .env.example                # 环境变量模板
├── .gitignore
├── Pipfile                     # pipenv 依赖文件
├── requirements.txt            # pip 依赖文件
└── README.md

目录设计遵循以下原则：

• 分层解耦： API 路由、业务逻辑、数据模型、外部服务严格分离，便于单元测试和模块替换。
• 版本控制： API 路由按 v1、v2 组织，支持接口平滑升级。
• 配置外部化： 所有环境敏感配置（数据库连接、Redis 密码、API Key）通过 .env 文件注入，不硬编码。

2.5 依赖清单速查

以下是本课程项目核心依赖及其用途：