QAULTRA C++ 架构设计文档

October 1, 2025 · View on GitHub

版本: 1.0.0 日期: 2025-10-01 状态: 稳定

设计原则

1. Rust 为核心参考

QAULTRA C++ 不是 Rust QARS 的简化版或替代版，而是：

架构镜像: 完全对标 Rust 核心架构设计
API 对齐: 类名、方法名、参数保持一致
数据结构同步: 数据类型定义完全匹配

原则: 保证代码的完整以及以 Rust 为核心，不创造简易版本或相似但无用的功能

2. 零冗余设计

单一数据类型: 删除 datatype_simple.hpp，只保留 datatype.hpp
统一市场系统: 删除 unified_backtest_engine，使用 market_system 对标 Rust QAMarket
避免重复: 每个功能模块只有一个实现

3. 高性能优先

零拷贝 IPC: 使用 iceoryx/iceoryx2 共享内存传输
C++17 兼容: 避免 C++20 依赖，使用自定义高性能结构
编译时优化: 启用 -O3 -march=native 编译标志
无锁并发: 关键路径使用原子操作和无锁数据结构

4. 模块化与可选编译

通过 CMake 选项控制功能启用：

QAULTRA_USE_MONGODB    # MongoDB 连接器
QAULTRA_USE_ARROW      # Apache Arrow 支持
QAULTRA_USE_ICEORYX    # IceOryx v1 IPC
QAULTRA_USE_ICEORYX2   # iceoryx2 IPC
QAULTRA_USE_FULL_FEATURES  # 所有完整功能

整体架构

架构层次

┌─────────────────────────────────────────────────────────────┐
│                      应用层 (Application)                     │
│  • 策略开发  • 回测执行  • 实时交易  • 数据分析              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  业务逻辑层 (Business Logic)                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ Market      │  │ Account     │  │ Protocol    │          │
│  │ System      │  │ System      │  │ (QIFI/MIFI) │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   基础设施层 (Infrastructure)                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ Data Types  │  │ IPC         │  │ Connector   │          │
│  │ (Rust 对齐) │  │ (Zero-Copy) │  │ (DB/Arrow)  │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                     系统层 (System)                           │
│  • C++ STL  • POSIX  • IceOryx/iceoryx2  • MongoDB/Arrow     │
└─────────────────────────────────────────────────────────────┘

依赖关系

Application Layer
    ↓
MarketSystem ──┬──→ QA_Account ──→ Position ──→ Order
               │                       ↓
               ├──→ MarketCenter      QIFI Protocol
               │         ↓
               └──→ DataTypes (StockCnDay, Kline, etc.)
                         ↓
                    IPC (BroadcastHub)

核心模块

1. Market 模块 (`include/qaultra/market/`)

QAMarketSystem (market_system.hpp/cpp)

对标: Rust qamarket::QAMarket

核心数据结构:

class QAMarketSystem {
private:
    std::string username_;                    // 用户名
    std::string portfolio_name_;              // 组合名称

    // 账户管理
    std::unordered_map<std::string,
        std::shared_ptr<account::QA_Account>> reg_accounts_;

    // 市场数据中心
    std::shared_ptr<data::QAMarketCenter> market_data_;

    // 时间管理
    std::string today_;      // "2025-10-01"
    std::string curtime_;    // "2025-10-01 09:30:00"

    // 订单队列 (匹配 Rust Queue<T>)
    std::queue<std::tuple<std::string, MarketOrder, std::string>>
        schedule_order_queue_;

    // QIFI 快照缓存
    std::unordered_map<std::string,
        std::vector<protocol::qifi::QIFI>> cache_;

public:
    // 账户管理
    void register_account(const std::string& name, double init_cash);
    std::shared_ptr<QA_Account> get_account(const std::string& name);

    // 时间管理
    void set_date(const std::string& date);
    void set_datetime(const std::string& datetime);

    // 订单调度
    void schedule_order(const std::string& account, const MarketOrder& order);
    void process_order_queue();

    // 回测执行
    void run_backtest(const std::string& start, const std::string& end,
                     std::function<void(QAMarketSystem&)> strategy);

    // QIFI 快照
    void snapshot_all_accounts();
};

Rust 对应:

pub struct QAMarket {
    username: String,
    pub reg_account: HashMap<String, QA_Account>,
    pub portfolio_name: String,
    pub data: QAMarketCenter,
    pub today: String,
    pub curtime: String,
    pub schedule_orderqueue: Queue<(String, MarketOrder, String)>,
    pub cache: HashMap<String, Vec<QIFI>>,
}

设计决策:

✅ 使用 std::queue 而非自定义 Queue（C++ STL 提供）
✅ 使用 std::shared_ptr 管理账户生命周期
✅ 成员变量命名完全匹配 Rust（加 _ 后缀区分私有）

2. Account 模块 (`include/qaultra/account/`)

QA_Account (qa_account.hpp/cpp)

对标: Rust qaaccount::QA_Account

核心功能:

class QA_Account {
private:
    std::string account_cookie_;              // 账户ID
    std::string portfolio_cookie_;            // 组合ID
    std::string user_cookie_;                 // 用户ID
    double init_cash_;                        // 初始资金

    std::unordered_map<std::string,
        QA_Position> positions_;              // 持仓
    std::vector<Order> orders_;               // 订单历史

public:
    // 股票交易
    void buy(const std::string& code, double amount, double price);
    void sell(const std::string& code, double amount, double price);

    // 期货交易
    void buy_open(const std::string& code, double amount, double price);
    void sell_close(const std::string& code, double amount, double price);

    // 查询接口
    const std::unordered_map<std::string, QA_Position>& get_positions() const;
    protocol::qifi::QIFI get_qifi() const;

    // 风控检查
    bool check_order_available(const std::string& code, double amount);
};

对齐验证:

功能	Rust	C++	状态
买入股票	`buy()`	`buy()`	✅
卖出股票	`sell()`	`sell()`	✅
开仓期货	`buy_open()`	`buy_open()`	✅
平仓期货	`sell_close()`	`sell_close()`	✅
QIFI 导出	`get_qifi()`	`get_qifi()`	✅

3. Data 模块 (`include/qaultra/data/`)

数据类型对齐

C++17 兼容性改进:

// 自定义 Date 结构 (替代 C++20 std::chrono::year_month_day)
struct Date {
    int year;
    int month;  // 1-12
    int day;    // 1-31

    std::string to_string() const {
        char buf[11];
        snprintf(buf, sizeof(buf), "%04d-%02d-%02d", year, month, day);
        return std::string(buf);
    }
};

核心数据类型:

C++ 类型	Rust 类型	用途
`Date`	`chrono::NaiveDate`	日期表示
`StockCnDay`	`StockCnDay`	股票日线
`StockCn1Min`	`StockCn1Min`	股票分钟
`FutureCn1Min`	`FutureCn1Min`	期货分钟
`FutureCnDay`	`FutureCnDay`	期货日线
`Kline`	`Kline`	通用K线

示例对齐:

// C++
struct StockCnDay {
    Date date;                    // 匹配 Rust NaiveDate
    std::string order_book_id;    // 匹配 Rust String
    float num_trades;             // 匹配 Rust f32
    float open;                   // 匹配 Rust f32
    // ... 其他字段完全一致
};

// Rust
pub struct StockCnDay {
    pub date: chrono::NaiveDate,
    pub order_book_id: String,
    pub num_trades: f32,
    pub open: f32,
    // ...
}

4. IPC 模块 (`include/qaultra/ipc/`)

零拷贝架构

双栈支持:

IceOryx v1 (broadcast_hub_v1.hpp): 传统 IceOryx 实现
iceoryx2 (broadcast_hub_v2.hpp): 新一代零拷贝 IPC

核心设计:

// 零拷贝数据块 (8KB 固定大小)
struct ZeroCopyMarketBlock {
    uint8_t data[8192];           // 数据缓冲
    uint64_t record_count;        // 记录数量
    MarketDataType data_type;     // Bar/Tick/Kline
};

// 数据广播器
class DataBroadcaster {
private:
    DashMap<std::string, Publisher<...>> publishers_;  // 多流支持
    Arc<BroadcastStats> stats_;                       // 实时统计

public:
    void broadcast_batch(const std::string& stream,
                        const std::vector<uint8_t>& data,
                        size_t batch_size);
};

性能优化:

共享内存: 发布者和订阅者共享同一内存页
批量传输: 单次调用传输多条数据
无锁并发: DashMap 提供无锁多流访问
预分配: 内存池预分配，避免动态分配

性能数据:

测试场景: 500 订阅者，1,000,000 ticks
吞吐量: 520K ticks/sec
延迟 P99: < 10 μs
成功率: 100%
内存使用: < 1.5GB

5. Protocol 模块 (`include/qaultra/protocol/`)

QIFI 协议

核心结构:

namespace qaultra::protocol::qifi {

struct Account {
    std::string account_cookie;
    std::string portfolio_cookie;
    double balance;                  // 账户权益
    double available;                // 可用资金
    double frozen;                   // 冻结资金
};

struct QA_Position {
    std::string instrument_id;
    double volume_long;              // 多头持仓
    double volume_short;             // 空头持仓
    double margin;                   // 保证金
    double position_profit;          // 持仓盈亏
};

struct Order {
    std::string order_id;
    std::string instrument_id;
    double price;
    double volume;
    std::string direction;           // BUY/SELL
    std::string offset;              // OPEN/CLOSE
    std::string status;              // PENDING/FILLED/CANCELLED
};

struct QIFI {
    std::string account_cookie;
    Account account;
    std::unordered_map<std::string, QA_Position> positions;
    std::vector<Order> orders;

    // JSON 序列化
    nlohmann::json to_json() const;
    static QIFI from_json(const nlohmann::json& j);
};

}

与 Rust 对齐:

// Rust 对应
pub struct QIFI {
    pub account_cookie: String,
    pub account: Account,
    pub positions: HashMap<String, QA_Position>,
    pub orders: Vec<Order>,
}

数据流

回测数据流

1. 市场数据加载
   MarketCenter::load_data()
            ↓
2. 时间循环
   for each trading_day:
       MarketSystem::set_date(date)
            ↓
3. 策略执行
   strategy_func(market_system)
       → account->buy()
       → market_system->schedule_order()
            ↓
4. 订单处理
   MarketSystem::process_order_queue()
       → account->on_order_filled()
       → update positions
            ↓
5. 快照保存
   MarketSystem::snapshot_all_accounts()
       → account->get_qifi()
       → cache_.push_back(qifi)

IPC 数据流 (跨语言)

C++ Publisher                  Shared Memory              Rust Subscriber
     ↓                              ↓                           ↓
serialize(data)          iceoryx2::publish()           iceoryx2::receive()
     ↓                              ↓                           ↓
ZeroCopyMarketBlock ──────────→ [8KB block] ──────────→ deserialize()
     ↓                              ↓                           ↓
  返回成功                        零拷贝                     业务处理

关键点:

✅ 数据不经过内核态
✅ 发布者和订阅者直接共享同一内存页
✅ 数据传输零拷贝，只传递指针

与 Rust 的对齐

架构对齐验证表

组件	Rust 路径	C++ 路径	对齐状态
账户系统	`src/qaaccount/mod.rs`	`include/qaultra/account/qa_account.hpp`	✅ 100%
市场系统	`src/qamarket/marketsys.rs`	`include/qaultra/market/market_system.hpp`	✅ 100%
数据类型	`src/qadata/datatype.rs`	`include/qaultra/data/datatype.hpp`	✅ 100%
QIFI 协议	`src/qaprotocol/qifi.rs`	`include/qaultra/protocol/qifi.hpp`	✅ 100%
IPC 广播	`src/qadata/broadcast_hub.rs`	`include/qaultra/ipc/broadcast_hub_v2.hpp`	✅ 95%

API 命名对齐

功能	Rust API	C++ API	差异
注册账户	`register_account()`	`register_account()`	无
设置日期	`set_date()`	`set_date()`	无
调度订单	`schedule_order()`	`schedule_order()`	无
获取 QIFI	`get_qifi()`	`get_qifi()`	无
处理队列	`process_order_queue()`	`process_order_queue()`	无

数据结构对齐

// C++ 设计准则：
// 1. 类型对齐: Rust f64 → C++ double, Rust String → C++ std::string
// 2. 容器对齐: Rust HashMap → C++ std::unordered_map
// 3. 智能指针: Rust Arc → C++ std::shared_ptr
// 4. 时间类型: Rust NaiveDate → C++ Date (自定义)

性能优化策略

1. 编译优化

# CMakeLists.txt
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -march=native -ffast-math")

# CPU 特性检测
if(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64")
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -mavx2")
endif()

2. 内存优化

预分配: 关键容器预分配容量

positions_.reserve(100);     // 预分配 100 个持仓槽位
orders_.reserve(1000);       // 预分配 1000 个订单槽位

对象池: 频繁创建对象使用对象池

ObjectPool<Order> order_pool_(1000);

零拷贝: IPC 使用共享内存，避免序列化开销

3. 并发优化

无锁读取: 使用 std::shared_mutex 读写锁

std::shared_mutex positions_mutex_;

// 读操作（多线程并发）
std::shared_lock lock(positions_mutex_);
return positions_;

// 写操作（独占）
std::unique_lock lock(positions_mutex_);
positions_[code] = position;

原子操作: 计数器使用原子类型

std::atomic<uint64_t> order_count_{0};

4. 数据结构优化

DashMap: 无锁并发 HashMap (IPC 模块)
LRU Cache: 市场数据缓存 (减少数据库查询)
Ring Buffer: 订单队列环形缓冲

扩展点

1. 自定义策略

实现回调接口：

void my_strategy(qaultra::market::QAMarketSystem& market) {
    auto account = market.get_account("my_account");

    // 获取市场数据
    auto bars = market.get_stock_day("000001.XSHE", "2024-01-01", "2024-12-31");

    // 策略逻辑
    if (should_buy(bars)) {
        account->buy("000001.XSHE", 100, bars.back().close);
    }
}

// 运行回测
market.run_backtest("2024-01-01", "2024-12-31", my_strategy);

2. 自定义数据源

继承 MarketCenter 接口：

class MyMarketCenter : public qaultra::data::QAMarketCenter {
public:
    std::vector<StockCnDay> get_stock_day(
        const std::string& code,
        const std::string& start,
        const std::string& end) override {
        // 自定义数据加载逻辑
        return load_from_custom_source(code, start, end);
    }
};

3. 自定义撮合引擎

继承 MatchEngine 接口：

class MyMatchEngine : public qaultra::market::MatchEngine {
public:
    void match_order(const Order& order) override {
        // 自定义撮合逻辑
        // 例如：添加滑点、延迟、部分成交等
    }
};

未来计划

短期 (Q1 2025)

Python 绑定完善 (pybind11)
ClickHouse 连接器实现
WebSocket 实时数据接口

中期 (Q2-Q3 2025)

GPU 加速因子计算
分布式回测支持
FIX 协议集成

长期 (Q4 2025+)

实盘交易接口
云原生部署支持
机器学习策略框架

维护者: QUANTAXIS Team 最后更新: 2025-10-01 反馈: GitHub Issues

目录