client

package
v0.12.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 1, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

client（客户端 SDK）

连接 go-wsc 服务端的客户端——WS 优先、SSE 降级、断线自动重连

这个域干什么

client 是给业务方用的连接 SDK：建连、认证、收发消息、心跳保活、断线重连 服务端能力（hub）之外的「另一半」——没有它，业务方要自己手写 WebSocket 客户端

核心概念

概念 说明
Client 客户端门面：连接管理 + 消息收发 + 重连策略（New(url) 构造）
WebSocket WS 连接封装：NewWebSocket 建连，认证走 subprotocol 握手
DefaultUpgrader 默认升级器（连接参数基准）
ClientMessage 客户端收发消息的统一结构
IsNormalClose 正常关闭判定（重连策略的判据：异常断开才重连）
SSE 降级 WS 不可用时降级 SSE（单向收，上行走 HTTP）

怎么用

package main

import (
    "github.com/kamalyes/go-wsc/client"
)

c := client.New("wss://example.com/ws")

c.OnTextMessageReceived(func(message string) {
    // 处理服务端消息
    _ = message
})

c.OnDisconnected(func(err error) {
    // 异常断开：SDK 按 AutoReconnect 配置自动重连
    _ = err
})

go c.Connect()

_ = c.SendTextMessage("hello")

端口与依赖

  • 只依赖标准库 + gorilla/websocket，不依赖服务端任何域包
  • 认证 Token 经握手 subprotocol 传递，与 transport 域的认证子协议对齐

性能与陷阱

  • 重连退避必须带抖动（jitter），否则服务端重启瞬间被客户端齐射打爆
  • 读循环单 goroutine；业务处理慢就在 msgCh 后面自己挂 worker，别阻塞读循环 （会卡心跳 pong，被服务端误判掉线）

后端绑定

无直连服务端，不经任何中间件

Documentation

Overview

* @Author: kamalyes 501893067@qq.com * @Date: 2025-09-06 09:50:55 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2026-09-22 16:09:00 * @FilePath: \go-wsc\client\client.go * @Description: Client 客户端门面 —— 回调装配、状态查询与消息发送 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-09-06 09:50:55 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2025-12-28 20:01:00 * @FilePath: \go-wsc\client\connection.go * @Description: 连接管理逻辑 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

* @Author: kamalyes 501893067@qq.com * @Date: 2025-09-06 09:50:55 * @LastEditors: kamalyes 501893067@qq.com * @LastEditTime: 2026-10-26 20:31:08 * @FilePath: \go-wsc\client\websocket.go * @Description: WebSocket 结构体及其方法 * * Copyright (c) 2025 by kamalyes, All Rights Reserved.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultUpgrader = websocket.Upgrader{
	CheckOrigin: func(r *http.Request) bool {
		return true
	},
}

DefaultUpgrader 返回默认的WebSocket升级器

Functions

func IsNormalClose 

func IsNormalClose(err error) bool

IsNormalClose 检查WebSocket关闭是否为正常关闭

func ResolveServers 

func ResolveServers(ctx context.Context, host, port, path string) ([]string, error)

ResolveServers 解析 headless Service 域名到全部 Pod 直连地址（集群内 LB 直连入口）

host 为 headless Service 域名（如 apex-notify-service-headless.business.svc.cluster.local）， port/path 为直连端口与 WS 路径；返回的 ws:// 地址列表直接喂给 WithServers。 Pod 扩缩容/滚动更新会改变解析结果——调用方应周期性重解析刷新列表 （建议重连窗口前刷新；列表过期仅导致轮转到已下线地址，失败转下一下一自愈）。 注意：产出为明文 ws://，集群内直连通常无 TLS；跨网段需 TLS 时由调用方自行包装 wss:// 地址

Types

type Client 

type Client struct {
	Config    *wscconfig.WSC // 配置信息，用于配置 WebSocket 客户端的参数
	WebSocket *WebSocket     // 底层 WebSocket 连接，负责实际的网络通信
	// contains filtered or unexported fields
}

Client WebSocket 客户端门面 封装连接状态机、回调装配与消息发送，连接管理细节见 connection.go

func New 

func New(url string) *Client

New 创建一个新的 Client 客户端 参数 url: WebSocket 服务器的地址 返回: 返回一个新的 Client 实例

func NewWithServers 

func NewWithServers(urls []string) *Client

NewWithServers 创建多服务器直连客户端（LB 直连模式） 每次建连/重连随机挑选地址：长连接场景下连接天然均匀分布到各节点， 断线重连风暴自动再平衡（不再集中打回原节点）；单地址失败同轮轮转剩余地址

func (*Client) Close 

func (c *Client) Close()

Close 主动关闭连接

func (*Client) CloseAndReconnect 

func (c *Client) CloseAndReconnect()

CloseAndReconnect 处理断线重连（公开用于测试）

func (*Client) CloseWithMsg 

func (c *Client) CloseWithMsg(msg string)

CloseWithMsg 主动关闭连接并附带消息

func (*Client) Closed 

func (c *Client) Closed() bool

Closed 返回连接状态

func (*Client) Connect 

func (c *Client) Connect()

Connect 发起连接

func (*Client) ConnectedUrl 

func (c *Client) ConnectedUrl() string

ConnectedUrl 返回当前实际连上的地址（观测/诊断；多地址直连模式下每次拨号可能不同，未连接过返回空串）

func (*Client) GetConnectionStatus 

func (c *Client) GetConnectionStatus() models.ConnectionStatus

GetConnectionStatus 获取当前连接状态

func (*Client) HasOnBinaryMessageReceivedCallback 

func (c *Client) HasOnBinaryMessageReceivedCallback() bool

HasOnBinaryMessageReceivedCallback 检查是否设置了二进制消息接收回调

func (*Client) HasOnBinaryMessageSentCallback 

func (c *Client) HasOnBinaryMessageSentCallback() bool

HasOnBinaryMessageSentCallback 检查是否设置了二进制消息发送成功回调

func (*Client) HasOnCloseCallback 

func (c *Client) HasOnCloseCallback() bool

HasOnCloseCallback 检查是否设置了连接关闭回调

func (*Client) HasOnConnectErrorCallback 

func (c *Client) HasOnConnectErrorCallback() bool

HasOnConnectErrorCallback 检查是否设置了连接错误回调

func (*Client) HasOnConnectedCallback 

func (c *Client) HasOnConnectedCallback() bool

HasOnConnectedCallback 检查是否设置了连接成功回调

func (*Client) HasOnDisconnectedCallback 

func (c *Client) HasOnDisconnectedCallback() bool

HasOnDisconnectedCallback 检查是否设置了连接断开回调

func (*Client) HasOnPingReceivedCallback 

func (c *Client) HasOnPingReceivedCallback() bool

HasOnPingReceivedCallback 检查是否设置了Ping接收回调

func (*Client) HasOnPongReceivedCallback 

func (c *Client) HasOnPongReceivedCallback() bool

HasOnPongReceivedCallback 检查是否设置了Pong接收回调

func (*Client) HasOnSentErrorCallback 

func (c *Client) HasOnSentErrorCallback() bool

HasOnSentErrorCallback 检查是否设置了发送错误回调

func (*Client) HasOnTextMessageReceivedCallback 

func (c *Client) HasOnTextMessageReceivedCallback() bool

HasOnTextMessageReceivedCallback 检查是否设置了文本消息接收回调

func (*Client) HasOnTextMessageSentCallback 

func (c *Client) HasOnTextMessageSentCallback() bool

HasOnTextMessageSentCallback 检查是否设置了文本消息发送成功回调

func (*Client) IsConnected 

func (c *Client) IsConnected() bool

IsConnected 检查是否已连接

func (*Client) IsConnecting 

func (c *Client) IsConnecting() bool

IsConnecting 检查是否正在连接

func (*Client) OnBinaryMessageReceived 

func (c *Client) OnBinaryMessageReceived(f func(data []byte))

OnBinaryMessageReceived 设置接收到二进制消息的回调 参数 f: 接收到二进制消息时调用的函数，参数为接收到的数据

func (*Client) OnBinaryMessageSent 

func (c *Client) OnBinaryMessageSent(f func(data []byte))

OnBinaryMessageSent 设置发送二进制消息成功的回调 参数 f: 发送成功时调用的函数，参数为发送的数据

func (*Client) OnClose 

func (c *Client) OnClose(f func(code int, text string))

OnClose 设置连接关闭的回调 参数 f: 连接关闭时调用的函数，参数为关闭代码和关闭文本

func (*Client) OnConnectError 

func (c *Client) OnConnectError(f func(err error))

OnConnectError 设置连接出错的回调 参数 f: 连接出错时调用的函数，参数为错误信息

func (*Client) OnConnected 

func (c *Client) OnConnected(f func())

OnConnected 设置连接成功的回调 参数 f: 连接成功后调用的函数

func (*Client) OnDisconnected 

func (c *Client) OnDisconnected(f func(err error))

OnDisconnected 设置连接断开的回调 参数 f: 连接断开时调用的函数，参数为错误信息

func (*Client) OnPingReceived 

func (c *Client) OnPingReceived(f func(appData string))

OnPingReceived 设置接收到 Ping 消息的回调 参数 f: 接收到 Ping 消息时调用的函数，参数为应用数据

func (*Client) OnPongReceived 

func (c *Client) OnPongReceived(f func(appData string))

OnPongReceived 设置接收到 Pong 消息的回调 参数 f: 接收到 Pong 消息时调用的函数，参数为应用数据

func (*Client) OnSentError 

func (c *Client) OnSentError(f func(err error))

OnSentError 设置发送消息出错的回调 参数 f: 发送出错时调用的函数，参数为错误信息

func (*Client) OnTextMessageReceived 

func (c *Client) OnTextMessageReceived(f func(message string))

OnTextMessageReceived 设置接收到文本消息的回调 参数 f: 接收到文本消息时调用的函数，参数为接收到的消息

func (*Client) OnTextMessageSent 

func (c *Client) OnTextMessageSent(f func(message string))

OnTextMessageSent 设置发送文本消息成功的回调 参数 f: 发送成功时调用的函数，参数为发送的消息

func (*Client) SendBinaryMessage 

func (c *Client) SendBinaryMessage(data []byte) error

SendBinaryMessage 发送二进制消息

func (*Client) SendTextMessage 

func (c *Client) SendTextMessage(message string) error

SendTextMessage 发送文本消息

func (*Client) SetConfig 

func (c *Client) SetConfig(config *wscconfig.WSC)

SetConfig 设置客户端配置 参数 config: 用户自定义的配置

func (*Client) WithServers 

func (c *Client) WithServers(urls []string) *Client

WithServers 设置服务器直连地址列表（链式，LB 直连模式） 列表非空时建连优先走列表（随机挑选 + 失败轮转），Url 仅作列表为空时的单地址回退； 空列表与全空元素被忽略（保持既有单地址行为）；集群内可配合 ResolveServers 解析 headless Service 拿到全量 Pod 地址

type ClientMessage 

type ClientMessage struct {
	T   int    // 消息类型
	Msg []byte // 消息内容
}

ClientMessage 结构体表示 WebSocket 消息(公开用于测试)

type WebSocket 

type WebSocket struct {
	Url           string            // 连接 URL（单地址模式的目标；多地址模式仅作初始回退）
	Conn          *websocket.Conn   // WebSocket 连接
	Dialer        *websocket.Dialer // WebSocket 拨号器
	RequestHeader http.Header       // 请求头
	HttpResponse  *http.Response    // 响应体
	// contains filtered or unexported fields
}

WebSocket 结构体表示底层 WebSocket 连接

func NewWebSocket 

func NewWebSocket(url string) *WebSocket

NewWebSocket 创建一个新的 WebSocket 连接

func (*WebSocket) GetConn 

func (ws *WebSocket) GetConn() *websocket.Conn

GetConn 获取 WebSocket 连接

func (*WebSocket) GetDialer 

func (ws *WebSocket) GetDialer() *websocket.Dialer

GetDialer 获取 WebSocket 拨号器

func (*WebSocket) GetHttpResponse 

func (ws *WebSocket) GetHttpResponse() *http.Response

GetHttpResponse 获取 HTTP 响应

func (*WebSocket) GetRequestHeader 

func (ws *WebSocket) GetRequestHeader() http.Header

GetRequestHeader 获取请求头

func (*WebSocket) GetSendChan 

func (ws *WebSocket) GetSendChan() chan *ClientMessage

GetSendChan 获取发送消息通道

func (*WebSocket) GetSendChanCapacity 

func (ws *WebSocket) GetSendChanCapacity() int

GetSendChanCapacity 获取发送通道的容量

func (*WebSocket) GetSendChanLength 

func (ws *WebSocket) GetSendChanLength() int

GetSendChanLength 获取发送通道的当前长度

func (*WebSocket) GetURL 

func (ws *WebSocket) GetURL() string

GetURL 获取连接 URL

func (*WebSocket) IsConnected 

func (ws *WebSocket) IsConnected() bool

IsConnected 获取连接状态

func (*WebSocket) SendMessageForTest 

func (ws *WebSocket) SendMessageForTest(msgType int, data []byte) error

SendMessageForTest 向发送通道注入消息

func (*WebSocket) SetConnectedForTest 

func (ws *WebSocket) SetConnectedForTest(connected bool)

SetConnectedForTest 设置连接状态

func (*WebSocket) WithCustomURL 

func (ws *WebSocket) WithCustomURL(url string) *WebSocket

WithCustomURL 设置自定义 URL

func (*WebSocket) WithDialer 

func (ws *WebSocket) WithDialer(dialer *websocket.Dialer) *WebSocket

WithDialer 设置自定义的 WebSocket 拨号器

func (*WebSocket) WithRequestHeader 

func (ws *WebSocket) WithRequestHeader(header http.Header) *WebSocket

WithRequestHeader 设置请求头

func (*WebSocket) WithSendBufferSize 

func (ws *WebSocket) WithSendBufferSize(size int) *WebSocket

WithSendBufferSize 设置发送消息缓冲池大小

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.