实时推送

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 结构体字段:

字段类型描述
OnConnectfunc()连接成功时触发
OnDisconnectfunc()连接断开时触发(自动重连前也会触发)
OnErrorfunc(error)发生错误时触发
OnKickoutfunc(string)账户被踢出(如在其他设备登录)时触发
OnQuotefunc(*QuoteData)收到行情推送时触发
OnTickfunc(*TickData)收到逐笔成交时触发
OnDepthfunc(*DepthData)收到深度行情更新时触发
OnOptionfunc(*OptionData)收到期权行情推送时触发
OnFuturefunc(*FutureData)收到期货行情推送时触发
OnKlinefunc(*KlineData)收到 K 线数据推送时触发
OnAssetfunc(*AssetData)收到账户资产变动时触发
OnPositionfunc(*PositionData)收到持仓变动时触发
OnOrderfunc(*OrderData)收到订单状态变更时触发
OnTransactionfunc(*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 会自动尝试重连,重连成功后会自动恢复之前的订阅。每次断开和重连成功时分别触发 OnDisconnectOnConnect 回调。

示例

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 回调。当账户净值、现金余额等发生变化时推送。

参数

参数名类型描述
accountstring账户 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)