简介一套可完整编译的期货CTP接口数据接收示例工程面向需要对接国内期货柜台系统的量化开发者或C程序员。项目围绕上期技术CTP接口实现行情接收与查询流程封装了行情订阅、交易查询、回调处理等核心逻辑源码已通过VS2010/VS2012编译验证可直接连接期货公司行情服务器获取实时数据需自行申请期货账号。资源共76个文件压缩包约19.74MB其中包含.h/.cpp源码文件、thostmduserapi.dll等动态库、编译生成的exe可执行文件、pdb调试符号以及sln/vcxproj工程文件另有tlog等构建日志可辅助排查编译过程。工程目录结构完整调试信息与中间文件齐全既能直接运行验证也适合对照学习CTP接口的初始化、登录、订阅行情、回调处理等完整调用链条。相比网上常见编译不过的零散片段这套代码已完整验证能为入门与中级开发者提供一条清晰的上手路径。目前已有1530人学习下载适合需要快速搭建CTP行情接入程序并减少排错成本的人群。 做期货程序化交易的朋友第一道门槛基本都在CTP接口上。CTP综合交易平台是国内期货市场覆盖率最高的柜台系统接口只要你有正常接入权限行情数据、交易通道都能通过这一套API拿下来。这次我专门把“行情数据接收”这件事从头到尾拆一遍API怎么初始化、怎么登录、怎么订阅合约、数据回调来了之后怎么处理最后给一个可以直接跑起来的最小代码示例。不管是刚开始接触CTP的新手还是准备把行情接收模块接入量化框架的老手这篇文章都值得你花十分钟过一遍。1. CTP行情接收要解决的三个核心问题1.1 行情接口为什么单独存在CTP接口通常拆成两套独立的动态库交易API负责报单、撤单、持仓查询行情APIMD API负责订阅合约、接收实时行情推送。两者在主程序里各建各的实例互不干扰。这是上期技术做得很合理的一点因为行情数据量远大于交易数据量分开之后行情推送的吞吐量就不会拖累交易链路反过来交易端的偶发阻塞也不会导致行情丢包。行情API在Windows下的库文件一般是thostmduserapi_se.dllLinux下是libthostmduserapi_se.so名字里的_se表示安全增强版现在期货公司基本都在用这个版本。拿到库之后头文件主要是ThostFtdcMdApi.h和ThostFtdcUserApiStruct.h后者是所有接口结构体的总定义后续解析行情数据全靠它建议把这个头文件完整打印一份放桌上。1.2 回调驱动模型别用“先发送再等待”的思路CTP最大的特点是回调驱动Callback Driven。你在主线程里发起登录请求但结果不会立刻返回而是等网络线程收到网关响应之后去调用你注册的回调函数。所以写CTP程序的核心工作其实是写一个继承自CThostFtdcMdSpi的类把回调逻辑填进去然后交给API内部去调用。我刚入门的时候在这上面吃过亏一开始习惯性地去写ReqUserLogin之后马上读取返回值以为返回值非零就等于登录成功。实际上ReqUserLogin返回的只是“请求是否成功发出”真正登录是否通过要看OnRspUserLogin回调里的ErrorID。理解了这个模型CTP后面所有流程都会顺很多。1.3 行情数据处理的基本链路整个行情接收模块在生产环境中的定位通常是这样CTP行情回调被触发后把最新的tick数据推进一个内存队列策略计算单元从队列另一头取数据做指标计算和信号判断。设计上的关键点是回调线程里尽量只做“拷贝和入队”这种轻量动作不能在里面做数据库写入、日志落盘或复杂计算否则回调吞吐能力会被拉低行情高峰期容易出问题。2. 环境搭建与CTP接口初始化准备2.1 从期货公司获取行情SDKCTP接口文件不是你随便下载就能用的必须向你开户的期货公司申请。一般拿到的是一个压缩包里面包含thostmduserapi_se.h行情API头文件thosttraderapi_se.h交易API头文件如果同时开发交易功能会有ThostFtdcUserApiStruct.h核心结构体定义数据接收全靠它对应平台的动态库和静态库连接参数说明文档里面写了行情前置地址、BrokerID、测试账户等这里有两个容易被忽视的坑。第一文件名带_se的库不能和旧版不带_se的混用头文件和库必须配套否则编译能过运行时直接内存崩溃。第二接口库版本要和柜台网关版本匹配我遇到过本地用的新版库连生产环境旧网关OnFrontConnected一直不触发排查了一整天才发现是版本不兼容。2.2 Windows和Linux下的工程配置用CMake组织工程的话头文件目录和动态库目录加上就行一个很基础的最小配置长这样cmake_minimum_required(VERSION 3.20) project(MdReceiver CXX) set(CMAKE_CXX_STANDARD 17) include_directories(${CMAKE_CURRENT_SOURCE_DIR}/ctp_include) add_executable(md_receiver main.cpp) if(WIN32) target_link_libraries(md_receiver ${CMAKE_CURRENT_SOURCE_DIR}/ctp_lib/win/thostmduserapi_se.lib) else() target_link_libraries(md_receiver ${CMAKE_CURRENT_SOURCE_DIR}/ctp_lib/linux/libthostmduserapi_se.so) endif()Windows下还有一个额外动作把thostmduserapi_se.dll复制到exe输出目录下最好再带上thosttraderapi_se.dll备用否则程序启动时会直接提示找不到动态库。Linux下则需要确保LD_LIBRARY_PATH环境变量包含动态库所在目录或者在CMake里把运行路径RPATH设置好。3. 行情接收的完整流程拆解3.1 五步完成从登录到收数行情接收的完整流程可以归纳成五步创建CThostFtdcMdApi实例指定行情落地文件的存储目录。注册回调SPI对象绑定前置地址调用Init()启动后台线程。等OnFrontConnected触发后调用ReqUserLogin做行情登录。在OnRspUserLogin回调里判断登录结果登录成功后调用SubscribeMarketData订阅合约。每笔最新行情通过OnRtnDepthMarketData推上来在这里做数据解析和分发。这个顺序是严格的不能跳步。我见过有人把SubscribeMarketData放在OnFrontConnected里直接调结果因为还没登录订阅请求直接被网关拒绝报错”当前未登录“。3.2 核心回调的触发时机把CTP行情API的几个常用回调整理成一张表方便对照回调函数触发时机关键返回值OnFrontConnected与前置建立连接后无OnRspUserLogin登录请求响应后返回请求编号是否最后一次OnRspSubMarketData订阅合约请求响应后返回合约代码错误信息OnRtnDepthMarketData每笔行情推送时触发深度行情结构体指针OnFrontDisconnected连接断开时触发断开原因代码OnRspUnSubMarketData退订合约请求响应后返回合约代码错误信息OnRspUserLogin里的ErrorID要第一时间判断非0就说明登录失败常见原因有人账号和密码错误、账号在别处登录导致互踢、行情权限未开通。有一个小细节登录成功回调里会返回MaxOrderRef和PrivateFlowSize等字段做行情接收时一般不用管但如果后续接交易APISessionID和FrontID必须妥善保存交易报单时会用到。3.3 订阅合约的细节SubscribeMarketData支持同时订阅多个合约传入一个char*数组和合约数量即可。合约代码格式统一是小写字母加数字比如螺纹钢主力合约rb2610黄金au2612。合约代码的大小写必须严格用大写或者混写都会被网关拒绝而且回调里报的错误并不一定直观排错效率会很低。这里多说一句CTP支持订阅后实时收到全档行情五档买卖盘都在OnRtnDepthMarketData里。如果你只需要最新价也建议订阅五档因为CTP没有单独的轻量tick接口五档数据本身就是唯一行情源。4. 实战代码最小可运行的行情接收器4.1 回调类实现直接给出一个精简但完整的实现我平时做原型测试就是从这个文件改的#include cstdio #include cstring #include ThostFtdcMdApi.h class CMdSpi : public CThostFtdcMdSpi { public: explicit CMdSpi(CThostFtdcMdApi* pApi) : m_pApi(pApi) {} // 前置连接成功 void OnFrontConnected() override { CThostFtdcReqUserLoginField req; memset(req, 0, sizeof(req)); strcpy(req.BrokerID, 9999); strcpy(req.UserID, your_account); strcpy(req.Password, your_password); int rt m_pApi-ReqUserLogin(req, m_nRequestID); printf([OnFrontConnected] ReqUserLogin%d\n, rt); } // 连接断开 void OnFrontDisconnected(int nReason) override { printf([OnFrontDisconnected] reason%d\n, nReason); } // 登录响应 void OnRspUserLogin(CThostFtdcRspUserLoginField* pRspUserLogin, CThostFtdcRspInfoField* pRspInfo, int nRequestID, bool bIsLast) override { if (pRspInfo pRspInfo-ErrorID ! 0) { printf([Login] failed: %s\n, pRspInfo-ErrorMsg); return; } printf([Login] ok, user%s\n, pRspUserLogin-UserID); char* instruments[] {rb2610, au2612}; int cnt 2; m_pApi-SubscribeMarketData(instruments, cnt); } // 订阅响应 void OnRspSubMarketData(CThostFtdcSpecificInstrumentField* pSpecificInstrument, CThostFtdcRspInfoField* pRspInfo, int nRequestID, bool bIsLast) override { if (pRspInfo pRspInfo-ErrorID ! 0) { printf([Subscribe] failed: %s, %s\n, pSpecificInstrument-InstrumentID, pRspInfo-ErrorMsg); return; } printf([Subscribe] ok: %s\n, pSpecificInstrument-InstrumentID); } // 行情推送回调 void OnRtnDepthMarketData(CThostFtdcDepthMarketDataField* pData) override { if (!pData) return; printf(%s time%s.%d last%.2f volume%d turnover%.2f oi%.1f bid1%.2f bidvol1%d ask1%.2f askvol1%d\n, pData-InstrumentID, pData-UpdateTime, pData-UpdateMillisec, pData-LastPrice, pData-Volume, pData-Turnover, pData-OpenInterest, pData-BidPrice1, pData-BidVolume1, pData-AskPrice1, pData-AskVolume1); } private: CThostFtdcMdApi* m_pApi; int m_nRequestID 0; };这个类承担了所有回调逻辑核心关注点有两个登录成功后才订阅订阅之前确认合约代码格式正确。实际使用时printf那一大串建议替换成结构体拷贝和队列入队操作。4.2 主流程与API生命周期有了回调类主函数就非常简单了int main() { CThostFtdcMdApi* pMdApi CThostFtdcMdApi::CreateFtdcMdApi(./md_data/, 1, 1); CMdSpi* pSpi new CMdSpi(pMdApi); pMdApi-RegisterSpi(pSpi); pMdApi-RegisterFront(tcp://your_front_address:41205); pMdApi-Init(); pMdApi-Join(); pMdApi-Release(); delete pSpi; return 0; }CreateFtdcMdApi的第一个参数是数据文件目录CTP会把登录信息、私有流程数据落盘到当前目录已存在的目录名必须有效。Init()之后API内部会自己起一个网络线程和回调线程主线程里的Join()就是让进程挂起直到你手动退出。如果需要优雅退出可以调用Release()但要注意Release之后SPI回调对象就不能再用了先释放API再释放SPI的顺序不能反。需要特别提醒的是CThostFtdcMdApi实例和派生SPI对象的生命周期必须长于整个业务过程。很多新手会在某个函数里局部创建API函数结束直接析构结果OnRtnDepthMarketData永远不触发。一个稳妥做法是让API和SPI都作为全局对象或长期存活的对象持有。4.3 把行情喂给策略引擎的正确姿势回调里如果只是打印日志没什么性能压力。但实际量化系统里行情回调速度非常快0.5秒就能来几百条。我常用的方案是回调线程只做一件事把tick结构体拷贝到RingBuffer或者有锁队列然后立刻返回。#include queue #include mutex std::queueCThostFtdcDepthMarketDataField g_quoteQueue; std::mutex g_quoteMutex; void OnRtnDepthMarketData(CThostFtdcDepthMarketDataField* pData) { std::lock_guardstd::mutex lock(g_quoteMutex); g_quoteQueue.push(*pData); // 结构体浅拷贝 }策略线程再从队列另一端取数据做实时K线合成、指标计算、信号触发。这一步就把“行情接收”和“业务逻辑”两个模块完全解耦也是后期做回测、仿真和实盘共用行情源的基础。5. 行情处理的关键细节与优化技巧5.1 时间和日期别读错字段CThostFtdcDepthMarketDataField里有两个时间相关字段ActionDay和TradingDay一个是交易日一个是行情发生日。夜盘行情跨天时TradingDay属于下一个交易日而ActionDay还是当天的自然日期。比如周一夜盘交易的是周二合约凌晨0点后推送的数据TradingDay已经是周二ActionDay还是周一。做日线合成和交易日划分时必须用TradingDay而不是本地系统时间否则跨日夜盘的数据会被归错交易日。而UpdateTime加UpdateMillisec才是精确到毫秒的行情时间戳。5.2 价格为零的tick要过滤CTP在集合竞价阶段可能会有部分字段为0的tick推上来比如开盘前突然推一笔只有成交量、没有最新价的数据。程序处理时最好加一个过滤条件LastPrice 1e-6的直接跳过避免策略用0价格计算出错误的涨跌停、错误盈亏。这个细节我在模拟盘中没遇到过实盘第一次碰到的时候着实查了很久。5.3 五档行情的解析与使用结构体里的BidPrice[5]、BidVolume[5]、AskPrice[5]、AskVolume[5]分别对应买一档到买五档的报价和数量。需要注意CTP推送行情时五个档位不一定全部有效部分合约在弱势时段可能只有一档或者三档有数据。你写出策略时不要默认五个档位都有效至少要判断BidVolume[0] 0才认为买一档有效最好循环统计前几档有量。5.4 日志打印别用同步IO我在生产代码里踩过最大的坑就是直接把printf或std::cout放到回调函数里。行情密集推送时标准输出IO是极慢的会拖垮整个回调线程导致行情处理延迟直线上升。后期我改成用异步日志库比如spdlog的异步模式或者直接把日志收集后由独立线程批量落盘立刻顺滑了。6. 常见问题排查与避坑经验6.1 连接不到前置或回调不触发这是新手最高频的问题。如果OnFrontConnected一直不触发按顺序排查前置地址前缀必须是tcp://端口有没有写错比如行情端口和交易端口长得像但对不上防火墙是否拦截了外网到网关的TCP连接动态库版本和CTP网关版本是否匹配API对象和SPI对象是否提前析构Init()之后主线程有没有直接退出退出太快进程就没了回调自然看不到。6.2 登录失败常见原因登录失败时OnRspUserLogin里的ErrorMsg会给出具体原因常见有这么几类“账号密码错误”、“账号被锁定”、“重复登录”。重复登录值得展开说一个行情账号在同一时刻只允许一个会话在线如果你在本地调试程序又在CTP快期等客户端里用同一个账号登录就会互踢。我处理这个问题的方法是专门给策略申请一个独立行情账号调试账号和生产账号彻底分离。6.3 断线重连的稳妥做法实盘环境里网络闪断无法避免OnFrontDisconnected触发后等待几秒重新走一遍初始化流程这种方式最稳。很多初学者以为直接在断开回调里调Init()就行实测并不总是稳定。我现在的做法是维护一个重连状态机断开后通过独立定时器延迟2到5秒然后重新CreateFtdcMdApi再走一遍连接登录订阅流程。重连后要注意重新订阅之前所有合约订阅列表要保存在一个全局数组里不能依赖回调参数。6.4 行情推送突然停止的排查思路如果程序运行几小时后行情推送突然停止但进程还活着先看是不是网络连接被网关掐断了再检查是否账号被踢、行情订阅是否被取消。CTP的订阅关系不是永久性的断线重连后订阅关系会丢失。遇到这种问题直接做法是主动查询连接状态如果OnFrontDisconnected没触发但已经超过几秒没有任何行情回调主动重启行情接收模块是最省事的。6.5 一个容易被忽略的收藏级技巧后台进程如果没有终端输出printf打印会被缓冲住排障时你根本看不到实时日志。建议启动后立刻执行setbuf(stdout, NULL)或者在程序里全部用fprintf(stderr, ...)输出。这一点在Linux服务器上尤其重要不然故障现场半天定位不到。行情接收这个环节是整个CTP开发链路里最“前端”的一步它本身不复杂但非常依赖对回调时序和结构体字段的熟练度。我个人在实际操作中的体会是把上面这套最小接收器跑通只是起点真正花时间和精力的地方全在细节——比如回调线程解耦、跨交易日字段解析、重连状态机这些每一个都会在实盘里教做人。建议你先从这份代码开始把模拟行情跑顺再逐步往上叠加K线合成、指标计算和交易模块这会是一条很稳的路径。本文还有配套的精品资源点击获取
