HQChart 数据服务器 (mifi-server)

作者: @yutiansut @quantaxis 版本: 0.1.0 技术栈: Rust + Actix-web

---

项目简介

mifi-server 是一个高性能的行情数据服务器，专为 HQChart 图表库提供标准化的数据接口。基于 Rust 语言和 Actix-web 框架构建，提供符合 HQChart NetworkFilter 协议的 RESTful API。

核心特性

• ✅ 符合 HQChart 标准: 完全兼容 HQChart 的数据格式要求
• ✅ 高性能: 基于 Rust 异步运行时，低延迟高并发
• ✅ CORS 支持: 允许跨域访问，方便浏览器端集成
• ✅ 类型安全: 使用 Rust 强类型系统，减少运行时错误
• ✅ 易于扩展: 模块化设计，方便对接真实数据源

---

数据格式说明

1. 日K线数据格式

数组格式: [date, open, close, high, low, vol, amount]

索引	字段	类型	说明
0	date	u32	日期 YYYYMMDD
1	open	f64	开盘价
2	close	f64	收盘价
3	high	f64	最高价
4	low	f64	最低价
5	vol	f64	成交量
6	amount	f64	成交额

响应示例:

{
  "code": 0,
  "symbol": "600000.sh",
  "name": "浦发银行",
  "ver": 2.0,
  "data": [
    [20250101, 10.50, 10.80, 11.00, 10.20, 1000000, 10500000],
    [20250102, 10.80, 10.75, 10.95, 10.60, 1100000, 11800000]
  ]
}

2. 分钟K线数据格式

数组格式: [date, open, close, high, low, vol, amount, position, time]

索引	字段	类型	说明
0	date	u32	日期 YYYYMMDD
1	open	f64	开盘价
2	close	f64	收盘价
3	high	f64	最高价
4	low	f64	最低价
5	vol	f64	成交量
6	amount	f64	成交额
7	position	f64	持仓量（期货用，股票为0）
8	time	u32	时间 HHMM （必需）

响应示例:

{
  "code": 0,
  "symbol": "600000.sh",
  "name": "浦发银行",
  "ver": 2.0,
  "data": [
    [20251022, 10.50, 10.52, 10.55, 10.48, 10000, 105200, 0, 930],
    [20251022, 10.52, 10.54, 10.58, 10.50, 12000, 126480, 0, 931]
  ]
}

3. Tick/分时数据格式

对象格式，包含 yclose（昨收价）和 minute 数组

字段	类型	说明
code	i32	状态码，0表示成功
symbol	String	股票代码
name	String	股票名称
date	u32	交易日期 YYYYMMDD
yclose	f64	昨收价（必需）
minute	Array	分钟数据数组

minute 数组格式: [time, price, vol, amount, avprice]

索引	字段	类型	说明
0	time	u32	时间 HHMM
1	price	f64	当前价格
2	vol	u32	成交量
3	amount	f64	成交额
4	avprice	f64	均价

响应示例:

{
  "code": 0,
  "symbol": "600000.sh",
  "name": "浦发银行",
  "date": 20251022,
  "yclose": 10.50,
  "minute": [
    [930, 10.52, 1000, 10520, 10.51],
    [931, 10.53, 800, 8424, 10.52],
    [932, 10.55, 1200, 12660, 10.53]
  ]
}

---

API 接口

基础信息

• 服务器地址: http://localhost:8088
• 协议: HTTP/HTTPS
• 数据格式: JSON

端点列表

1. 健康检查

GET /health

响应:

{
  "status": "ok",
  "service": "mifi-server",
  "version": "0.1.0"
}

2. 服务器信息

GET /api/info

响应: 返回服务器信息和可用端点列表

3. 日K线数据

GET /api/kline/day?symbol={symbol}&count={count}&period={period}&right={right}

查询参数:

• symbol (必需): 股票代码，如 600000.sh
• count (可选): 请求数量，默认 100
• period (可选): 周期类型
  • 0 = 日线（默认）
  • 1 = 周线
  • 2 = 月线
  • 3 = 季线
  • 4 = 年线
• right (可选): 复权类型
  • 0 = 不复权（默认）
  • 1 = 前复权
  • 2 = 后复权

示例请求:

curl "http://localhost:8088/api/kline/day?symbol=600000.sh&count=50"

4. 分钟K线数据

GET /api/kline/minute?symbol={symbol}&count={count}&period={period}

查询参数:

• symbol (必需): 股票代码
• count (可选): 请求数量，默认 240
• period (可选): 分钟周期
  • 1 = 1分钟（默认）
  • 5 = 5分钟
  • 15 = 15分钟
  • 30 = 30分钟
  • 60 = 60分钟

示例请求:

curl "http://localhost:8088/api/kline/minute?symbol=600000.sh&period=5&count=100"

5. Tick/分时数据

GET /api/quote/minute?symbol={symbol}&date={date}

查询参数:

• symbol (必需): 股票代码
• date (可选): 指定日期 YYYYMMDD，默认返回当日数据

示例请求:

curl "http://localhost:8088/api/quote/minute?symbol=600000.sh"

---

快速开始

环境要求

• Rust 1.70+ （推荐使用 rustup 安装）
• Cargo（Rust 包管理器）

安装步骤

1. 克隆或进入项目目录:

cd /home/quantaxis/qapro/mifi-server

2. 构建项目:

cargo build --release

3. 运行服务器:

cargo run --release

或直接运行编译后的二进制文件:

./target/release/mifi-server

验证服务

服务器启动后，访问健康检查端点：

curl http://localhost:8088/health

预期响应：

{
  "status": "ok",
  "service": "mifi-server",
  "version": "0.1.0"
}

---

集成到 HQChart

配置 NetworkFilter

在 HQChart 的初始化代码中配置 NetworkFilter：

// 自定义数据接口
function MyDataAPI() {
    this.ApiUrl = 'http://localhost:8088';
}

MyDataAPI.prototype.RequestHistoryData = function(symbol, callback) {
    // 请求日K线数据
    fetch(`${this.ApiUrl}/api/kline/day?symbol=${symbol}&count=100`)
        .then(response => response.json())
        .then(data => {
            callback(data);
        })
        .catch(error => {
            console.error('请求失败:', error);
        });
};

MyDataAPI.prototype.ReqeustHistoryMinuteData = function(symbol, callback) {
    // 请求分钟K线数据
    fetch(`${this.ApiUrl}/api/kline/minute?symbol=${symbol}&count=240`)
        .then(response => response.json())
        .then(data => {
            callback(data);
        })
        .catch(error => {
            console.error('请求失败:', error);
        });
};

MyDataAPI.prototype.RequestMinuteData = function(symbol, callback) {
    // 请求Tick/分时数据
    fetch(`${this.ApiUrl}/api/quote/minute?symbol=${symbol}`)
        .then(response => response.json())
        .then(data => {
            callback(data);
        })
        .catch(error => {
            console.error('请求失败:', error);
        });
};

// 设置网络过滤器
HQData.NetworkFilter = new MyDataAPI();

// 创建图表
var chart = JSChart.Init('chartDiv');
chart.SetOption({
    Type: '历史K线图',
    Symbol: '600000.sh',
    // ... 其他配置
});

---

项目结构

mifi-server/
├── Cargo.toml              # 项目配置和依赖
├── README.md               # 本文档
└── src/
    ├── main.rs             # 主程序入口，服务器配置
    ├── models.rs           # 数据模型定义
    └── handlers.rs         # API 处理器实现

核心模块说明

• models.rs: 定义所有数据结构和序列化格式

  • DayKLine: 日K线数据类型
  • MinuteKLine: 分钟K线数据类型
  • MinutePoint: Tick数据点类型
  • 各种响应结构和查询参数

• handlers.rs: 实现 API 端点处理逻辑

  • get_day_kline(): 处理日K线请求
  • get_minute_kline(): 处理分钟K线请求
  • get_tick_data(): 处理Tick数据请求
  • health_check(): 健康检查
  • get_server_info(): 服务器信息

• main.rs: 服务器启动和配置

  • CORS 配置
  • 路由注册
  • 日志配置

---

开发指南

对接真实数据源

当前实现使用示例数据。要对接真实数据源：

1. 修改 handlers.rs，替换示例数据生成逻辑
2. 添加数据库连接，在 Cargo.toml 中添加数据库依赖：

[dependencies]
sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres"] }
# 或使用其他数据库驱动

3. 实现数据查询函数：

async fn fetch_day_kline_from_db(symbol: &str, count: u32) -> Result<Vec<DayKLine>, Error> {
    // 从数据库查询数据
    // ...
}

添加新端点

1. 在 models.rs 中定义数据结构
2. 在 handlers.rs 中实现处理函数
3. 在 main.rs 中注册路由：

.route("/api/your/endpoint", web::get().to(handlers::your_handler))

修改服务器端口

编辑 main.rs 中的 bind_address：

let bind_address = "0.0.0.0:8088";  // 修改为你需要的端口

---

依赖说明

依赖库	版本	用途
actix-web	4.9	Web 框架
actix-cors	0.7	CORS 支持
serde	1.0	序列化/反序列化
serde_json	1.0	JSON 处理
chrono	0.4	日期时间处理
tokio	1.x	异步运行时
log	0.4	日志接口
env_logger	0.11	日志实现

---

性能说明

基准测试

• 并发能力: 基于 Actix-web，支持数万级并发连接
• 响应时间: 示例数据模式下，P99 延迟 < 5ms
• 内存占用: 空载约 10MB，随数据量线性增长

优化建议

1. 启用生产模式编译:

cargo build --release

2. 使用连接池: 如果对接数据库，使用连接池提高性能

3. 添加缓存层: 对于热点数据，可以添加 Redis 缓存

4. 启用 gzip 压缩:

.wrap(middleware::Compress::default())

---

故障排除

端口被占用

如果 8088 端口被占用，修改 main.rs 中的端口配置。

CORS 错误

确保 CORS 配置正确，检查 main.rs 中的 CORS 设置：

let cors = Cors::default()
    .allow_any_origin()
    .allow_any_method()
    .allow_any_header();

编译错误

确保 Rust 版本 >= 1.70:

rustc --version

更新 Rust:

rustup update

---

参考文档

• HQChart 官方文档: HQChart GitHub
• HQChart 数据对接指南: /home/quantaxis/qapro/HQChart/doc/07-数据对接完全指南.md
• Actix-web 文档: https://actix.rs
• Rust 官方文档: https://doc.rust-lang.org

---

许可证

本项目采用与 HQChart 相同的开源协议。

---

作者

@yutiansut @quantaxis

如有问题或建议，欢迎提交 Issue 或 Pull Request。

---

最后更新: 2025-10-22