# YQuote

**Repository Path**: devilisy/yquote

## Basic Information

- **Project Name**: YQuote
- **Description**: YQuote 实时行情订阅服务
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-06-03
- **Last Updated**: 2025-08-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YQuote 实时行情订阅服务

一个基于C++后端和Python API的高性能实时股票行情订阅系统。

## 🚀 项目概述

YQuote是一个实时行情数据服务，采用现代化架构设计：

- **C++后端服务器**: 高性能WebSocket服务器，支持完整的WebSocket协议，负责行情数据生成和分发
- **Python API服务**: FastAPI构建的RESTful API和WebSocket代理
- **实时数据推送**: 基于WebSocket的低延迟数据传输
- **企业级日志系统**: 多级别、多输出、线程安全的日志框架
- **市场数据模拟**: 内置的股票价格模拟器

## 📋 功能特性

### 🎯 核心功能
- ✅ 实时股票行情数据生成和推送
- ✅ 完整的WebSocket协议支持（TEXT、BINARY、PING、PONG、CLOSE帧）
- ✅ 多客户端订阅管理
- ✅ 自动心跳检测和连接管理
- ✅ 企业级日志系统（6个级别，多种输出）

### 支持的股票(模拟)
**美股 (8只)**: AAPL, GOOGL, MSFT, AMZN, TSLA, META, NVDA, NFLX  
**A股 (4只)**: 000001.SZ, 000002.SZ, 600000.SH, 600036.SH

## 🏗️ 系统架构

```
┌─────────────────┐    WebSocket    ┌─────────────────┐
│   Python API    │ ←─────────────→ │   C++ Backend   │
│   (FastAPI)     │                 │   (WebSocket)   │
└─────────────────┘                 └─────────────────┘
         ↑                                   ↑
         │ HTTP/WebSocket                    │
         ↓                                   ↓
┌─────────────────┐                 ┌─────────────────┐
│   Web Client    │                 │ Market Data     │
│   (Browser)     │                 │ Simulator       │
└─────────────────┘                 └─────────────────┘
```

## 🛠️ 技术栈

### C++后端
- **语言**: C++17
- **构建系统**: CMake
- **网络库**: 原生Socket + OpenSSL
- **WebSocket**: 完整协议实现（RFC 6455）
- **日志系统**: 极简现代化日志框架
- **JSON处理**: 自定义轻量级解析器
- **线程管理**: std::thread + std::atomic

### Python API
- **框架**: FastAPI
- **WebSocket**: websockets库
- **异步处理**: asyncio
- **日志**: Python logging
- **依赖管理**: requirements.txt

## 📦 项目结构

```
yquote/
├── cpp_backend/                 # C++后端服务
│   ├── include/                 # 头文件
│   │   ├── quote_server.h       # 主服务器类
│   │   ├── websocket_server.h   # WebSocket服务器
│   │   ├── logger.h             # 日志系统
│   │   ├── quote_manager.h      # 行情管理器
│   │   ├── market_data_simulator.h # 市场数据模拟器
│   │   ├── json_utils.h         # JSON工具类
│   │   └── quote_data.h         # 数据结构定义
│   ├── src/                     # 源文件
│   │   ├── main.cpp             # 主程序入口
│   │   ├── quote_server.cpp     # 服务器实现
│   │   ├── websocket_server.cpp # WebSocket实现
│   │   ├── quote_manager.cpp    # 行情管理实现
│   │   ├── market_data_simulator.cpp # 数据模拟实现
│   │   └── json_utils.cpp       # JSON工具实现
│   ├── build/                   # 构建目录
│   ├── config/                  # 配置文件目录
│   └── CMakeLists.txt           # CMake配置
├── python_api/                  # Python API服务
│   ├── services/                # 服务层
│   │   └── websocket_client.py  # WebSocket客户端
│   ├── routes/                  # 路由层
│   │   └── quotes.py            # 行情API路由
│   ├── models/                  # 数据模型
│   │   └── quote.py             # 行情数据模型
│   ├── app.py                   # FastAPI主应用
│   └── requirements.txt         # Python依赖
├── tests/                       # 测试文件
└── README.md                    # 项目文档
```

## 🚀 快速开始

### 1. 编译C++后端

#### 方法一：使用构建脚本（推荐）
```bash
cd cpp_backend
./build.sh          # Release模式
./build.sh Debug    # Debug模式
```

#### 方法二：手动构建
```bash
cd cpp_backend
mkdir build && cd build
cmake ..
make
```

### 2. 启动服务

#### 使用配置文件启动（推荐）
```bash
# 使用默认配置文件
./quote_server

# 指定配置文件
./quote_server -c config/server.conf

# 指定端口和日志级别
./quote_server -p 9090 -l DEBUG

# 查看帮助
./quote_server --help
```

#### 启动Python API
```bash
cd python_api
pip install -r requirements.txt
python app.py
```

### 3. 测试连接
```bash
cd tests
python test_websocket_client.py
```

## ⚙️ 配置文件

支持INI格式的配置文件，默认位置为`cpp_backend/config/server.conf`：

```ini
[server]
websocket_port = 8080
bind_address = 0.0.0.0
max_connections = 1000
heartbeat_interval = 30

[market_data]
update_interval = 1000
price_volatility = 2.0
enable_simulator = true
default_symbols = AAPL,GOOGL,MSFT,AMZN,TSLA,META,NVDA,NFLX,000001.SZ,000002.SZ,600000.SH,600036.SH

[logging]
log_level = INFO
log_file = logs/yquote_server.log
console_output = true
enable_colors = true
max_log_size = 100
max_log_files = 10

[performance]
worker_threads = 0
memory_pool_size = 256
enable_monitoring = true
stats_interval = 60
async_logging = false

[security]
enable_access_control = false
allowed_ips = 127.0.0.1,::1
enable_ssl = false
ssl_cert_file = certs/server.crt
ssl_key_file = certs/server.key
```

### 配置说明
- **server**: 服务器基本设置（端口、地址、连接数等）
- **market_data**: 市场数据相关设置（更新频率、波动率、股票列表等）
- **logging**: 日志配置（级别、文件、大小限制等）
- **performance**: 性能相关设置（线程数、内存池等）
- **security**: 安全设置（SSL、访问控制等）

### 命令行参数
```bash
./quote_server [选项]

选项:
  -p, --port <端口号>     指定WebSocket端口 (默认: 8080)
  -c, --config <文件>     指定配置文件路径
  -l, --loglevel <级别>   指定日志级别 (TRACE/DEBUG/INFO/WARN/ERROR/FATAL)
  -h, --help              显示帮助信息

示例:
  ./quote_server                    # 使用默认配置
  ./quote_server -p 9090            # 指定端口
  ./quote_server -c my_config.conf  # 指定配置文件
```

## 📊 日志系统

### 日志级别
- 🔵 **TRACE** - 最详细的调试信息
- 🔷 **DEBUG** - 调试信息  
- 🟢 **INFO** - 一般信息
- 🟡 **WARN** - 警告信息
- 🔴 **ERROR** - 错误信息
- 🟣 **FATAL** - 致命错误

### 使用示例
```cpp
#include "logger.h"

// 初始化日志系统
auto& logger = yquote::Logger::getInstance();
logger.setLevel(yquote::LogLevel::INFO);

// 添加控制台输出（彩色）
auto console_sink = std::make_shared<yquote::ConsoleSink>(true);
logger.addSink(console_sink);

// 添加文件输出
auto file_sink = std::make_shared<yquote::FileSink>("logs/app.log");
logger.addSink(file_sink);

// 使用便捷宏
LOG_INFO("服务器启动成功");
LOG_ERROR_FMT("连接失败，错误码: %d", error_code);
```

### 日志输出
- **控制台输出**: 支持彩色显示
- **文件输出**: 包含详细信息（时间戳、线程ID、文件位置）
- **滚动文件**: 自动滚动，防止文件过大
- **自定义回调**: 可扩展到远程日志服务

## 🔌 WebSocket 协议

### 支持的帧类型
- **TEXT帧**: 文本消息传输
- **BINARY帧**: 二进制数据传输  
- **PING/PONG帧**: 心跳检测
- **CLOSE帧**: 优雅关闭连接

### 连接状态管理
```cpp
enum class ClientConnectionState {
    CONNECTING,  // 正在连接
    CONNECTED,   // 已连接
    CLOSING,     // 正在关闭
    CLOSED       // 已关闭
};
```

### 心跳机制
- 自动发送Ping帧（默认30秒间隔）
- 监控Pong响应超时
- 自动清理断开的连接

## 🎮 控制台命令

服务器启动后，支持以下交互式命令：

```bash
yquote> help                    # 显示帮助信息
yquote> status                  # 显示服务器状态
yquote> clients                 # 显示连接的客户端
yquote> quotes                  # 显示所有行情数据
yquote> loglevel DEBUG         # 设置日志级别
yquote> stop                   # 停止服务器
```

## 🔧 开发指南

### 编译要求
- C++17 或更高版本
- CMake 3.15+
- OpenSSL 开发库

### 依赖安装

#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install build-essential cmake libssl-dev
```

#### CentOS/RHEL
```bash
sudo yum install gcc-c++ cmake openssl-devel
```

#### macOS
```bash
brew install cmake openssl
```

## 📚 API文档

### WebSocket消息格式

#### 订阅股票
```json
{
    "action": "subscribe",
    "symbols": ["AAPL", "GOOGL", "MSFT"]
}
```

#### 行情数据推送
```json
{
    "type": "quote",
    "data": {
        "symbol": "AAPL",
        "price": 150.25,
        "change": 2.15,
        "change_percent": 1.45,
        "volume": 1000000,
        "timestamp": "2025-06-04T09:47:14.371Z"
    }
}
```

## 🧪 测试

### 运行测试
```bash
# C++单元测试
cd cpp_backend/build
make test

# Python测试
cd python_api
python -m pytest tests/
```

### 压力测试
```bash
# WebSocket连接测试
cd tests
python test_websocket_client.py

# 性能基准测试
python benchmark.py
```

## 🐛 故障排除

### 常见问题

**1. 编译错误**:
```bash
# 检查依赖
pkg-config --libs openssl
cmake --version
```

**2. 连接失败**:
```bash
# 检查端口占用
netstat -tulpn | grep 8080
# 检查防火墙
sudo ufw status
```

**3. 数据不更新**:
- 检查订阅状态
- 验证股票代码
- 查看服务器日志

### 日志分析

**C++服务器日志**:
```bash
# 启动时显示详细信息
./quote_server 2>&1 | tee server.log
```

**Python API日志**:
```bash
# 查看日志文件
tail -f python_api/yquote_api.log
```

## 🤝 贡献指南

### 开发流程
1. Fork项目
2. 创建功能分支
3. 提交代码
4. 创建Pull Request

### 代码规范
- C++: Google C++ Style Guide
- Python: PEP 8
- 提交信息: Conventional Commits

## 📄 许可证

本项目采用MIT许可证 - 详见 [LICENSE](LICENSE) 文件

## 📞 联系方式

- **项目主页**: https://gitee.com/devilisy/yquote
- **问题反馈**: https://gitee.com/devilisy/yquote/issues

## 🙏 致谢

感谢所有贡献者和开源社区的支持！

---

**版本**: 0.0.1  
**最后更新**: 2025-06-03  

**注意**: 这是一个演示项目，不应用于实际的金融交易。所有股票数据均为模拟数据。