实时推送
Go SDK 通过 PushClient 提供基于 Protobuf/TCP+TLS 的实时推送服务,支持行情推送和账户推送,内置自动重连和心跳保活机制。数据采用 Protobuf 编码 + varint32 长度前缀帧格式传输。以下为完整可运行示例:
package main
import (
"fmt"
"log"
"time"
"github.com/tigerfintech/openapi-go-sdk/config"
"github.com/tigerfintech/openapi-go-sdk/push"
"github.com/tigerfintech/openapi-go-sdk/push/pb"
)
func main() {
cfg, err := config.NewClientConfig()
if err != nil {
log.Fatal(err)
}
pc := push.NewPushClient(cfg)
// 设置所有回调
pc.SetCallbacks(push.Callbacks{
OnConnect: func() {
fmt.Println("[推送] 连接成功")
},
OnDisconnect: func() {
fmt.Println("[推送] 连接断开,等待自动重连...")
},
OnError: func(err error) {
fmt.Printf("[推送] 发生错误: %v\n", err)
},
OnKickout: func(reason string) {
fmt.Printf("[推送] 账户被踢出: %s\n", reason)
},
OnQuote: func(data *pb.QuoteData) {
fmt.Printf("[行情] %s latest=%.2f\n", data.GetSymbol(), data.GetLatestPrice())
},
OnTick: func(data *pb.TradeTickData) {
fmt.Printf("[逐笔] %s\n", data.GetSymbol())
},
OnDepth: func(data *pb.QuoteDepthData) {
fmt.Printf("[深度] %s\n", data.GetSymbol())
},
OnOrder: func(data *pb.OrderStatusData) {
fmt.Printf("[订单] id=%d status=%s\n", data.GetId(), data.GetStatus())
},
OnAsset: func(data *pb.AssetData) {
fmt.Println("[资产] 账户资产变动")
},
OnPosition: func(data *pb.PositionData) {
fmt.Printf("[持仓] %s\n", data.GetSymbol())
},
OnTransaction: func(data *pb.OrderTransactionData) {
fmt.Printf("[成交] orderId=%d\n", data.GetOrderId())
},
})
if err := pc.Connect(); err != nil {
log.Fatal(err)
}
defer pc.Disconnect()
// 订阅行情推送
if err := pc.SubscribeQuote([]string{"AAPL", "TSLA"}); err != nil {
log.Printf("订阅行情失败: %v", err)
}
// 订阅账户推送(传空字符串使用配置中的账户)
pc.SubscribeAsset("")
pc.SubscribeOrder("")
pc.SubscribePosition("")
pc.SubscribeTransaction("")
fmt.Println("推送已启动,按 Ctrl+C 退出...")
time.Sleep(60 * time.Second)
}初始化
NewPushClient 创建推送客户端
push.NewPushClient(cfg *config.ClientConfig, opts ...PushClientOption)
说明
创建 PushClient 实例。可传入可选的 PushClientOption 来自定义重连间隔、心跳超时等行为。
参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| cfg | *config.ClientConfig | 是 | 客户端配置,通过 config.NewClientConfig() 创建 |
| opts | ...PushClientOption | 否 | 可选配置项 |
示例
cfg, _ := config.NewClientConfig(
config.WithPropertiesFile("tiger_openapi_config.properties"),
)
pc := push.NewPushClient(cfg)SetCallbacks 设置回调函数
pc.SetCallbacks(cb push.Callbacks)
说明
在连接前设置所有事件回调。Callbacks 结构体中所有字段均为可选的函数类型,只需赋值所需的回调。
Callbacks 结构体字段:
所有数据类型定义在 github.com/tigerfintech/openapi-go-sdk/push/pb 包(由 Protobuf 生成)。
| 字段 | 类型 | 描述 |
|---|---|---|
| OnConnect | func() | 连接成功时触发 |
| OnDisconnect | func() | 连接断开时触发(自动重连前也会触发) |
| OnError | func(error) | 发生错误时触发 |
| OnKickout | func(message string) | 账户被踢出(如在其他设备登录)时触发 |
| OnQuote | func(*pb.QuoteData) | 收到股票行情推送时触发 |
| OnQuoteBBO | func(*pb.QuoteData) | 收到 BBO 报价时触发 |
| OnTick | func(*pb.TradeTickData) | 收到逐笔成交时触发 |
| OnDepth | func(*pb.QuoteDepthData) | 收到深度行情更新时触发 |
| OnOption | func(*pb.QuoteData) | 收到期权行情推送时触发 |
| OnFuture | func(*pb.QuoteData) | 收到期货行情推送时触发 |
| OnKline | func(*pb.KlineData) | 收到 K 线数据推送时触发 |
| OnStockTop | func(*pb.StockTopData) | 收到股票榜单数据时触发 |
| OnOptionTop | func(*pb.OptionTopData) | 收到期权榜单数据时触发 |
| OnFullTick | func(*pb.TickData) | 收到全量 Tick 数据时触发 |
| OnAsset | func(*pb.AssetData) | 收到账户资产变动时触发 |
| OnPosition | func(*pb.PositionData) | 收到持仓变动时触发 |
| OnOrder | func(*pb.OrderStatusData) | 收到订单状态变更时触发 |
| OnTransaction | func(*pb.OrderTransactionData) | 收到成交明细时触发 |
示例
import "github.com/tigerfintech/openapi-go-sdk/push/pb"
pc.SetCallbacks(push.Callbacks{
OnConnect: func() {
fmt.Println("连接成功")
},
OnQuote: func(data *pb.QuoteData) {
fmt.Printf("%s: %.2f\n", data.GetSymbol(), data.GetLatestPrice())
},
})Connect / Disconnect 连接与断开
pc.Connect() error
pc.Disconnect() error
说明
Connect:建立 TCP+TLS 连接,连接成功后才能订阅数据。Disconnect:主动断开连接,不会触发自动重连。
自动重连机制
当网络中断时,SDK 会自动尝试重连,重连成功后会自动恢复之前的订阅。每次断开和重连成功时分别触发 OnDisconnect 和 OnConnect 回调。
示例
if err := pc.Connect(); err != nil {
log.Fatal("连接失败:", err)
}
defer pc.Disconnect()State 获取连接状态
pc.State() push.ConnectionState
说明
返回当前连接状态。
返回值
| 值 | 描述 |
|---|---|
ConnectionStateDisconnected | 未连接 |
ConnectionStateConnecting | 连接中 |
ConnectionStateConnected | 已连接 |
ConnectionStateReconnecting | 重连中 |
示例
state := pc.State()
fmt.Println("当前状态:", state)行情推送订阅
v0.3.0 说明:修复了加密货币(Cc)推送的 dispatcher 漏洞 —— 之前订阅 Cc 后收到推送会抛
未知的 DataType: Cc错误,现已修复,Cc 推送统一走OnQuote回调。同时新增股票/期权排行榜、加密货币行情、市场状态 4 对订阅方法(详见下文「v0.3.0 新增」小节)。
SubscribeQuote / UnsubscribeQuote 订阅行情
pc.SubscribeQuote(symbols []string) error
pc.UnsubscribeQuote(symbols []string) error
说明
订阅/退订股票的实时行情推送,触发 OnQuote 回调。
参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| symbols | []string | 股票代码列表 |
示例
// 订阅行情
if err := pc.SubscribeQuote([]string{"AAPL", "TSLA"}); err != nil {
log.Println("订阅失败:", err)
}
// 退订某只股票
pc.UnsubscribeQuote([]string{"TSLA"})SubscribeTick / UnsubscribeTick 订阅逐笔成交
pc.SubscribeTick(symbols []string) error
pc.UnsubscribeTick(symbols []string) error
说明
订阅/退订逐笔成交数据,触发 OnTick 回调。每笔成交会实时推送价格、数量和买卖方向。
示例
pc.SubscribeTick([]string{"AAPL"})
// 回调中处理:
// OnTick: func(data *pb.TradeTickData) {
// fmt.Printf("%s ticks=%d\n", data.GetSymbol(), len(data.GetTicks()))
// }SubscribeDepth / UnsubscribeDepth 订阅深度行情
pc.SubscribeDepth(symbols []string) error
pc.UnsubscribeDepth(symbols []string) error
说明
订阅/退订买卖五档盘口深度数据,触发 OnDepth 回调。
示例
pc.SubscribeDepth([]string{"AAPL"})SubscribeOption / UnsubscribeOption 订阅期权行情
pc.SubscribeOption(symbols []string) error
pc.UnsubscribeOption(symbols []string) error
说明
订阅/退订期权合约实时行情,触发 OnOption 回调。
参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| symbols | []string | 期权合约代码列表,格式:"AAPL 250117C00150000" |
示例
pc.SubscribeOption([]string{"AAPL 250117C00150000"})SubscribeFuture / UnsubscribeFuture 订阅期货行情
pc.SubscribeFuture(symbols []string) error
pc.UnsubscribeFuture(symbols []string) error
说明
订阅/退订期货合约实时行情,触发 OnFuture 回调。
示例
pc.SubscribeFuture([]string{"ES2506", "NQ2506"})SubscribeKline / UnsubscribeKline 订阅K线
pc.SubscribeKline(symbols []string) error
pc.UnsubscribeKline(symbols []string) error
说明
订阅/退订 K 线数据实时推送,触发 OnKline 回调。每根 K 线完成时推送。
示例
pc.SubscribeKline([]string{"AAPL"})SubscribeStockTop / UnsubscribeStockTop 订阅股票排行榜 (v0.3.0 新增)
pc.SubscribeStockTop(market string, indicators []string) error
pc.UnsubscribeStockTop(market string, indicators []string) error
说明
订阅指定市场的股票排行榜实时推送,可选择多个指标(最新价 / 涨幅 / 跌幅 / 成交量 / 成交额 / 振幅 / 换手率 等)。订阅后通过 OnStockTop 回调接收数据。
参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| market | string | 是 | 市场代码:US / HK / CN |
| indicators | []string | 是 | 指标列表,如 LATEST_PRICE / HIGHER / LOWER / VOLUME / AMOUNT / AMPLITUDE / TURNOVER_RATE |
回调
OnStockTop func(data *pb.StockTopData)
| 字段 | 类型 | 描述 |
|---|---|---|
| Market | string | 市场代码 |
| TopData | []*StockTopData_TopData | 排行数据列表(按 indicator 分组) |
示例
pc.SetCallbacks(push.Callbacks{
OnStockTop: func(data *pb.StockTopData) {
fmt.Printf("[StockTop] market=%s items=%d\n", data.GetMarket(), len(data.GetTopData()))
},
})
// 订阅
pc.SubscribeStockTop("US", []string{"LATEST_PRICE", "HIGHER", "LOWER"})
// 退订
pc.UnsubscribeStockTop("US", []string{"LATEST_PRICE", "HIGHER", "LOWER"})SubscribeOptionTop / UnsubscribeOptionTop 订阅期权排行榜 (v0.3.0 新增)
pc.SubscribeOptionTop(market string, indicators []string) error
pc.UnsubscribeOptionTop(market string, indicators []string) error
说明
订阅指定市场的期权排行榜实时推送,可选择多个指标。订阅后通过 OnOptionTop 回调接收数据。
参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| market | string | 是 | 市场代码:US / HK / CN |
| indicators | []string | 是 | 指标列表,如 LATEST_PRICE / HIGHER / LOWER / VOLUME / AMOUNT 等 |
回调
OnOptionTop func(data *pb.OptionTopData)
| 字段 | 类型 | 描述 |
|---|---|---|
| Market | string | 市场代码 |
| TopData | []*OptionTopData_TopData | 排行数据列表(按 indicator 分组) |
示例
pc.SetCallbacks(push.Callbacks{
OnOptionTop: func(data *pb.OptionTopData) {
fmt.Printf("[OptionTop] market=%s items=%d\n", data.GetMarket(), len(data.GetTopData()))
},
})
// 订阅
pc.SubscribeOptionTop("US", []string{"VOLUME", "AMOUNT"})
// 退订
pc.UnsubscribeOptionTop("US", []string{"VOLUME", "AMOUNT"})SubscribeCc / UnsubscribeCc 订阅加密货币行情 (v0.3.0 新增)
pc.SubscribeCc(symbols []string) error
pc.UnsubscribeCc(symbols []string) error
说明
订阅/退订加密货币实时行情推送。
注意:Cc 推送的数据类型与普通股票行情一致,统一走 OnQuote 回调,不是新的回调函数。dispatcher 会将 Cc dataType 路由到 OnQuote(与 Python SDK 保持一致)。
参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| symbols | []string | 是 | 加密货币代码列表,如 BTCUSD / ETHUSD |
回调
OnQuote func(data *pb.QuoteData) (复用行情回调)
示例
pc.SetCallbacks(push.Callbacks{
OnQuote: func(data *pb.QuoteData) {
// Cc 推送也会进入这里
fmt.Printf("[Quote/Cc] %s latest=%.2f\n", data.GetSymbol(), data.GetLatestPrice())
},
})
// 订阅
pc.SubscribeCc([]string{"BTCUSD", "ETHUSD"})
// 退订
pc.UnsubscribeCc([]string{"BTCUSD", "ETHUSD"})SubscribeMarket / UnsubscribeMarket 订阅市场状态 (v0.3.0 新增)
pc.SubscribeMarket(market string) error
pc.UnsubscribeMarket(market string) error
说明
订阅/退订整个市场的状态变化推送(如开盘、收盘、盘前、盘后等状态切换)。
注意:协议上 dataType 为 Quote + market 字段,因此数据也通过 OnQuote 回调送达。
参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| market | string | 是 | 市场代码:US / HK / CN / SG |
回调
OnQuote func(data *pb.QuoteData) (复用行情回调)
示例
pc.SetCallbacks(push.Callbacks{
OnQuote: func(data *pb.QuoteData) {
// 市场状态变化也会进入这里
fmt.Printf("[Market/Quote] symbol=%s\n", data.GetSymbol())
},
})
// 订阅美股市场状态
pc.SubscribeMarket("US")
// 退订
pc.UnsubscribeMarket("US")账户推送订阅
SubscribeAsset / UnsubscribeAsset 订阅资产变动
pc.SubscribeAsset(account string) error
pc.UnsubscribeAsset() error
说明
订阅账户资产变动推送,触发 OnAsset 回调。当账户净值、现金余额等发生变化时推送。
参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| account | string | 账户 ID,传空字符串 "" 使用配置文件中的默认账户 |
示例
pc.SubscribeAsset("") // 使用默认账户
pc.SubscribeAsset("DU123456") // 指定账户SubscribePosition / UnsubscribePosition 订阅持仓变动
pc.SubscribePosition(account string) error
pc.UnsubscribePosition() error
说明
订阅持仓变动推送,触发 OnPosition 回调。当持仓数量或成本变化时推送。
示例
pc.SubscribePosition("")SubscribeOrder / UnsubscribeOrder 订阅订单状态
pc.SubscribeOrder(account string) error
pc.UnsubscribeOrder() error
说明
订阅订单状态变更推送,触发 OnOrder 回调。订单从提交到成交的每个状态变化都会推送。
示例
pc.SubscribeOrder("")
// 回调示例:
// OnOrder: func(data *pb.OrderStatusData) {
// fmt.Printf("订单 %d 状态: %s\n", data.GetId(), data.GetStatus())
// }SubscribeTransaction / UnsubscribeTransaction 订阅成交明细
pc.SubscribeTransaction(account string) error
pc.UnsubscribeTransaction() error
说明
订阅实时成交明细推送,触发 OnTransaction 回调。每次成交时立即推送成交价和数量。
示例
pc.SubscribeTransaction("")查询订阅状态
GetSubscriptions 查询行情订阅列表
pc.GetSubscriptions() map[push.SubjectType][]string
说明
返回当前已订阅的行情标的,按订阅类型分组。
示例
subs := pc.GetSubscriptions()
for subType, symbols := range subs {
fmt.Printf("订阅类型: %v, 标的: %v\n", subType, symbols)
}GetAccountSubscriptions 查询账户订阅列表
pc.GetAccountSubscriptions() []push.SubjectType
说明
返回当前已订阅的账户推送类型列表。
示例
accountSubs := pc.GetAccountSubscriptions()
fmt.Println("已订阅账户推送:", accountSubs)Updated 17 days ago
