CTP Rust SDK

一个为CTP (综合交易平台) 提供的安全、现代化的Rust绑定库，支持Linux和macOS系统。

✨ 特性

• 🔒 类型安全: 使用Rust的类型系统确保内存安全和线程安全
• 🌍 跨平台支持: 原生支持Linux和macOS (x86_64/ARM64)
• 📝 编码自动转换: 自动处理GB18030到UTF-8的编码转换
• ⚡ 高性能: 零拷贝设计，最小化性能开销
• 📚 完整文档: 提供完整的中文API文档和使用示例
• 🛡️ 安全FFI: 安全的C++库绑定，避免内存泄露和悬空指针
• 🔄 异步支持: 支持tokio异步运行时

🚀 快速开始

安装依赖

在你的 Cargo.toml 中添加：

[dependencies]
deepissue-ctp-rust = "1.0.0"
tokio = { version = "1.0", features = ["full"] }

基本使用示例

行情订阅

use deepissue_ctp_rust::*;
use deepissue_ctp_rust::api::{MdApi, CtpApi};
use deepissue_ctp_rust::api::md_api::{MdSpiHandler, DepthMarketDataField};
use deepissue_ctp_rust::types::{ReqUserLoginField, RspUserLoginField, RspInfoField};

// 实现行情回调处理器
struct MyMdHandler;

impl MdSpiHandler for MyMdHandler {
    fn on_front_connected(&mut self) {
        println!("行情前置已连接");
    }
    
    fn on_rsp_user_login(
        &mut self,
        user_login: Option<RspUserLoginField>,
        rsp_info: Option<RspInfoField>,
        request_id: i32,
        is_last: bool,
    ) {
        if let Some(rsp) = rsp_info {
            if rsp.is_success() {
                println!("登录成功");
            } else {
                if let Ok(msg) = rsp.get_error_msg() {
                    println!("登录失败: {}", msg);
                }
            }
        }
    }
    
    fn on_rtn_depth_market_data(&mut self, market_data: DepthMarketDataField) {
        println!("收到行情数据，最新价: {}", market_data.last_price);
    }
}

#[tokio::main]
async fn main() -> CtpResult<()> {
    // 创建行情API
    let mut md_api = MdApi::new(Some("./flow"), false, false)?;
    
    // 注册回调处理器
    md_api.register_spi(MyMdHandler)?;
    
    // 注册前置机地址
    md_api.register_front("tcp://180.168.146.187:10131")?;
    
    // 初始化
    md_api.init()?;
    
    // 创建登录请求
    let login_req = ReqUserLoginField::new("9999", "投资者账号", "密码")?
        .with_product_info("MyApp")?;
    
    // 发送登录请求
    md_api.req_user_login(&login_req)?;
    
    // 订阅行情
    md_api.subscribe_market_data(&["rb2501", "i2501"])?;
    
    // 等待API退出
    md_api.join()?;
    
    Ok(())
}

交易接口

use deepissue_ctp_rust::api::{TraderApi, CtpApi};
use deepissue_ctp_rust::api::trader_api::{TraderSpiHandler, ReqAuthenticateField};

struct MyTraderHandler;

impl TraderSpiHandler for MyTraderHandler {
    fn on_front_connected(&mut self) {
        println!("交易前置已连接");
    }
    
    fn on_rsp_authenticate(
        &mut self,
        rsp_authenticate: Option<deepissue_ctp_rust::api::trader_api::RspAuthenticateField>,
        rsp_info: Option<RspInfoField>,
        request_id: i32,
        is_last: bool,
    ) {
        if let Some(rsp) = rsp_info {
            if rsp.is_success() {
                println!("认证成功");
            }
        }
    }
}

#[tokio::main]
async fn main() -> CtpResult<()> {
    // 创建交易API
    let mut trader_api = TraderApi::new(Some("./flow"))?;
    
    // 注册回调处理器
    trader_api.register_spi(MyTraderHandler)?;
    
    // 注册前置机地址
    trader_api.register_front("tcp://180.168.146.187:10130")?;
    
    // 初始化
    trader_api.init()?;
    
    // 客户端认证
    let auth_req = ReqAuthenticateField {
        broker_id: [0; 11], // 填入实际的经纪公司代码
        user_id: [0; 16],   // 填入实际的用户代码
        // ... 其他字段
        ..Default::default()
    };
    
    trader_api.req_authenticate(&auth_req)?;
    
    Ok(())
}

📖 详细文档

系统要求

• 操作系统: Linux (x86_64) 或 macOS (x86_64/ARM64)
• Rust版本: 1.70+
• CTP库: 需要相应平台的CTP动态库

目录结构

ctp-rust/
├── src/
│   ├── lib.rs              # 主库入口
│   ├── error.rs            # 错误定义
│   ├── encoding.rs         # 编码转换
│   ├── types.rs            # 数据类型定义
│   ├── ffi.rs              # FFI绑定声明
│   └── api/
│       ├── mod.rs          # API模块
│       ├── md_api.rs       # 行情API
│       ├── trader_api.rs   # 交易API
│       └── callbacks.rs    # 回调处理
├── libs/
│   └── ctp/
│       ├── include/        # CTP头文件
│       └── lib/
│           ├── linux64/    # Linux动态库
│           └── mac64/      # macOS动态库
├── tests/                  # 测试文件
├── examples/               # 示例代码
└── docs/                   # 文档

编码处理

CTP库使用GB18030编码，而Rust默认使用UTF-8。本SDK自动处理两种编码之间的转换：

use deepissue_ctp_rust::encoding::GbkConverter;

// UTF-8 转 GB18030
let gb_bytes = GbkConverter::utf8_to_gb18030("期货合约")?;

// GB18030 转 UTF-8
let utf8_string = GbkConverter::gb18030_to_utf8(&gb_bytes)?;

// 固定长度字节数组转换
use deepissue_ctp_rust::types::{InstrumentIdType, StringConvert};

let instrument_id = InstrumentIdType::from_utf8_string("rb2501")?;
let back_to_string = instrument_id.to_utf8_string()?;

错误处理

SDK提供了完整的错误处理机制：

use deepissue_ctp_rust::error::{CtpError, CtpResult};

match some_ctp_function() {
    Ok(result) => println!("操作成功: {:?}", result),
    Err(CtpError::ConnectionError(msg)) => println!("连接错误: {}", msg),
    Err(CtpError::AuthenticationError(msg)) => println!("认证错误: {}", msg),
    Err(CtpError::BusinessError(code, msg)) => {
        println!("业务错误 [{}]: {}", code, msg);
    }
    Err(e) => println!("其他错误: {}", e),
}

平台支持

Linux

# 确保系统有必要的库
sudo apt-get install build-essential

# 设置库文件路径
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./libs/ctp/lib/linux64

# 运行程序
cargo run

macOS

# 设置库文件路径
export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:./libs/ctp/lib/mac64

# 在Apple Silicon Mac上可能需要Rosetta
# 如果遇到架构问题，可以用Rosetta运行：
arch -x86_64 cargo run

🔧 构建配置

自定义构建

如果你需要自定义CTP库的位置，可以设置环境变量：

export CTP_LIB_PATH=/path/to/your/ctp/libs
export CTP_INCLUDE_PATH=/path/to/your/ctp/headers

功能特性

[dependencies]
deepissue-ctp-rust = { version = "1.0.0", features = ["channel"] }

可用特性：

• channel: 启用crossbeam-channel支持
• ctp: 默认启用，CTP SDK支持

📋 API参考

主要类型

• MdApi: 行情API接口
• TraderApi: 交易API接口
• ReqUserLoginField: 用户登录请求
• RspUserLoginField: 用户登录响应
• DepthMarketDataField: 深度行情数据
• OrderField: 报单信息
• TradeField: 成交信息

回调接口

• MdSpiHandler: 行情回调处理接口
• TraderSpiHandler: 交易回调处理接口

编码工具

• GbkConverter: GB18030/UTF-8编码转换器
• StringConvert: 字符串转换特质

🧪 测试

运行所有测试：

cargo test

运行编码测试：

cargo test --test encoding_tests

运行集成测试（需要CTP库）：

cargo test --features integration

📚 示例

更多示例请查看 examples/ 目录：

• md_basic.rs: 基础行情订阅
• trader_basic.rs: 基础交易功能
• encoding_demo.rs: 编码转换示例
• error_handling.rs: 错误处理示例

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork本仓库
2. 创建feature分支 (git checkout -b feature/amazing-feature)
3. 提交你的修改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启Pull Request

⚠️ 注意事项

1. 库文件: 需要获取相应平台的CTP库文件并放置在正确位置
2. 网络环境: 连接CTP服务器需要稳定的网络环境
3. 账户权限: 需要有效的CTP账户和相应的交易权限
4. 风险提示: 期货交易有风险，请谨慎使用

📄 许可证

本项目采用MIT或Apache-2.0双重许可证。详见 LICENSE-MIT 和 LICENSE-APACHE 文件。

🔗 相关链接

• CTP官网
• Rust官网
• 文档
• 问题反馈

📞 联系方式

如有问题或建议，请通过以下方式联系：

• GitHub Issues: 提交问题
• Email: 36625090@qq.com

免责声明: 本软件仅供学习和研究使用，作者不对因使用本软件导致的任何损失承担责任。期货投资有风险，入市需谨慎。