# CTP Rust SDK
[](https://crates.io/crates/deepissue-ctp-rust)
[](https://docs.rs/deepissue-ctp-rust)
[](https://github.com/deepissue/ctp-rust)
一个为CTP (综合交易平台) 提供的安全、现代化的Rust绑定库，支持Linux和macOS系统。
## ✨ 特性
- 🔒 **类型安全**: 使用Rust的类型系统确保内存安全和线程安全
- 🌍 **跨平台支持**: 原生支持Linux和macOS (x86_64/ARM64)
- 📝 **编码自动转换**: 自动处理GB18030到UTF-8的编码转换
- ⚡ **高性能**: 零拷贝设计，最小化性能开销
- 📚 **完整文档**: 提供完整的中文API文档和使用示例
- 🛡️ **安全FFI**: 安全的C++库绑定，避免内存泄露和悬空指针
- 🔄 **异步支持**: 支持tokio异步运行时
## 🚀 快速开始
### 安装依赖
在你的 `Cargo.toml` 中添加：
```toml
[dependencies]
deepissue-ctp-rust = "1.0.0"
tokio = { version = "1.0", features = ["full"] }
```
### 基本使用示例
#### 行情订阅
```rust
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(())
}
```
#### 交易接口
```rust
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自动处理两种编码之间的转换：
```rust
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提供了完整的错误处理机制：
```rust
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
```bash
# 确保系统有必要的库
sudo apt-get install build-essential
# 设置库文件路径
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./libs/ctp/lib/linux64
# 运行程序
cargo run
```
#### macOS
```bash
# 设置库文件路径
export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:./libs/ctp/lib/mac64
# 在Apple Silicon Mac上可能需要Rosetta
# 如果遇到架构问题，可以用Rosetta运行：
arch -x86_64 cargo run
```
## 🔧 构建配置
### 自定义构建
如果你需要自定义CTP库的位置，可以设置环境变量：
```bash
export CTP_LIB_PATH=/path/to/your/ctp/libs
export CTP_INCLUDE_PATH=/path/to/your/ctp/headers
```
### 功能特性
```toml
[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`: 字符串转换特质
## 🧪 测试
运行所有测试：
```bash
cargo test
```
运行编码测试：
```bash
cargo test --test encoding_tests
```
运行集成测试（需要CTP库）：
```bash
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-MIT) 和 [LICENSE-APACHE](LICENSE-APACHE) 文件。
## 🔗 相关链接
- [CTP官网](http://www.sfit.com.cn/)
- [Rust官网](https://www.rust-lang.org/)
- [文档](https://docs.rs/deepissue-ctp-rust)
- [问题反馈](https://github.com/deepissue/ctp-rust/issues)
## 📞 联系方式
如有问题或建议，请通过以下方式联系：
- GitHub Issues: [提交问题](https://github.com/deepissue/ctp-rust/issues)
- Email: 36625090@qq.com
---
**免责声明**: 本软件仅供学习和研究使用，作者不对因使用本软件导致的任何损失承担责任。期货投资有风险，入市需谨慎。