实时推送

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 生成)。

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

示例

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 回调接收数据。

参数

参数名类型是否必填描述
marketstring市场代码:US / HK / CN
indicators[]string指标列表,如 LATEST_PRICE / HIGHER / LOWER / VOLUME / AMOUNT / AMPLITUDE / TURNOVER_RATE

回调

OnStockTop func(data *pb.StockTopData)

字段类型描述
Marketstring市场代码
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 回调接收数据。

参数

参数名类型是否必填描述
marketstring市场代码:US / HK / CN
indicators[]string指标列表,如 LATEST_PRICE / HIGHER / LOWER / VOLUME / AMOUNT

回调

OnOptionTop func(data *pb.OptionTopData)

字段类型描述
Marketstring市场代码
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 回调送达。

参数

参数名类型是否必填描述
marketstring市场代码: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 回调。当账户净值、现金余额等发生变化时推送。

参数

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