实时推送
Go SDK 通过 PushClient 提供基于 WebSocket 的实时推送服务,支持行情推送和账户推送,内置自动重连和心跳保活机制。以下为完整可运行示例:
package main
import (
"fmt"
"log"
"time"
"github.com/tigerfintech/openapi-sdks/go/config"
"github.com/tigerfintech/openapi-sdks/go/push"
)
func main() {
cfg, err := config.NewClientConfig(
config.WithPropertiesFile("tiger_openapi_config.properties"),
)
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 *push.QuoteData) {
fmt.Printf("[行情] %s 最新价: %.2f 涨跌幅: %.2f%%\n",
data.Symbol, data.LatestPrice, data.ChangePercentage)
},
OnTick: func(data *push.TickData) {
fmt.Printf("[逐笔] %s 成交价: %.2f 数量: %d\n",
data.Symbol, data.Price, data.Volume)
},
OnDepth: func(data *push.DepthData) {
fmt.Printf("[深度] %s 更新\n", data.Symbol)
},
OnOrder: func(data *push.OrderData) {
fmt.Printf("[订单] %s 状态变更: %s\n", data.Symbol, data.Status)
},
OnAsset: func(data *push.AssetData) {
fmt.Println("[资产] 账户资产变动")
},
OnPosition: func(data *push.PositionData) {
fmt.Printf("[持仓] %s 数量变更\n", data.Symbol)
},
OnTransaction: func(data *push.TransactionData) {
fmt.Printf("[成交] %s 成交价: %.2f\n", data.Symbol, data.FilledPrice)
},
})
// 连接推送服务
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 结构体字段:
| 字段 | 类型 | 描述 |
|---|---|---|
| OnConnect | func() | 连接成功时触发 |
| OnDisconnect | func() | 连接断开时触发(自动重连前也会触发) |
| OnError | func(error) | 发生错误时触发 |
| OnKickout | func(string) | 账户被踢出(如在其他设备登录)时触发 |
| OnQuote | func(*QuoteData) | 收到行情推送时触发 |
| OnTick | func(*TickData) | 收到逐笔成交时触发 |
| OnDepth | func(*DepthData) | 收到深度行情更新时触发 |
| OnOption | func(*OptionData) | 收到期权行情推送时触发 |
| OnFuture | func(*FutureData) | 收到期货行情推送时触发 |
| OnKline | func(*KlineData) | 收到 K 线数据推送时触发 |
| OnAsset | func(*AssetData) | 收到账户资产变动时触发 |
| OnPosition | func(*PositionData) | 收到持仓变动时触发 |
| OnOrder | func(*OrderData) | 收到订单状态变更时触发 |
| OnTransaction | func(*TransactionData) | 收到成交明细时触发 |
示例
pc.SetCallbacks(push.Callbacks{
OnConnect: func() {
fmt.Println("连接成功")
},
OnQuote: func(data *push.QuoteData) {
fmt.Printf("%s: %.2f\n", data.Symbol, data.LatestPrice)
},
})Connect / Disconnect 连接与断开
pc.Connect() error
pc.Disconnect() error
说明
Connect:建立 WebSocket 连接,连接成功后才能订阅数据。Disconnect:主动断开连接,不会触发自动重连。
自动重连机制
当网络中断时,SDK 会自动尝试重连,重连成功后会自动恢复之前的订阅。每次断开和重连成功时分别触发 OnDisconnect 和 OnConnect 回调。
示例
if err := pc.Connect(); err != nil {
log.Fatal("连接失败:", err)
}
defer pc.Disconnect()State 获取连接状态
pc.State() push.ConnectionState
说明
返回当前 WebSocket 连接状态。
返回值
| 值 | 描述 |
|---|---|
ConnectionStateDisconnected | 未连接 |
ConnectionStateConnecting | 连接中 |
ConnectionStateConnected | 已连接 |
ConnectionStateReconnecting | 重连中 |
示例
state := pc.State()
fmt.Println("当前状态:", state)行情推送订阅
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 *push.TickData) {
// fmt.Printf("成交: %.2f x %d\n", data.Price, data.Volume)
// }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"})账户推送订阅
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 *push.OrderData) {
// fmt.Printf("订单 %d 状态: %s\n", data.OrderId, data.Status)
// }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 8 days ago
