跳到主要内容

HubConnection

HubConnection 是客户端的主入口。它管理连接状态机、协商 → 选传输 → 连接 → 握手流程、心跳、服务端超时检测与自动重连。

创建连接​

from aiosignalr.client import HubConnection

connection = HubConnection()

可以在构造时配置选项与协议：

from aiosignalr.client import HubConnection, HubConnectionOptions

connection = HubConnection(
    protocol="json",                        # 或 "messagepack"，或协议实例
    options=HubConnectionOptions(
        handshake_timeout=15.0,
        server_timeout=30.0,
        keep_alive_interval=15.0,
    ),
)

协议​

协议值传输格式说明
JSON"json"文本默认，可读性好，0x1E 分隔
MessagePack"messagepack"二进制大流量场景更小更快

也可以传 IHubProtocol 实例（如自定义协议）。

启动连接​

await connection.start(
    "http://127.0.0.1:8080/hub",
    access_token_factory=lambda: "my-token",
    headers={"X-Custom": "value"},
    transports={"WebSockets", "LongPolling"},
)
  • access_token_factory 在每次 HTTP / WebSocket 请求前调用；返回非 None 时作为 Authorization: Bearer <token> 发送。可以是协程。
  • transports 限制客户端允许使用的传输。
  • skip_negotiation=True 直接连 WebSocket URL，跳过协商（需要 WebSockets 传输）。

连接不在 DISCONNECTED 状态时调用 start() 会抛异常。

停止连接​

await connection.stop()

stop() 发送优雅的 Close 消息、停止传输与定时器、以 ConnectionClosed("Connection stopped.") 使所有挂起调用失败，并触发 on_close。

连接状态​

from aiosignalr.enums import ConnectionState

connection.state  # ConnectionState.DISCONNECTED / CONNECTING / CONNECTED / RECONNECTING

连接事件​

连接级回调是普通可赋值属性：

connection.on_open = lambda: print("connected")
connection.on_close = lambda exc: print("closed:", exc)

async def on_reconnecting(exc):
    print("reconnecting after", exc)

async def on_reconnected():
    print("back online")

connection.on_reconnecting = on_reconnecting
connection.on_reconnected = on_reconnected
事件签名触发时机
on_open() -> None首次连接成功
on_close(exc) -> None连接永久关闭
on_reconnecting(exc) -> None一轮重连开始
on_reconnected() -> None重连成功

回调可以是同步或异步函数。

超时与心跳​

  • 服务端超时：server_timeout 秒内没有收到任何消息，客户端判定连接已死并关闭。 对自身无法感知 EOF 的传输是必须的。
  • 心跳：客户端每隔 keep_alive_interval 秒发送一次 Ping， 让服务器知道客户端还活着（并开始自己的超时计时）。
  • 客户端在 hub 握手完成后才启动心跳，与参考实现一致。

开启状态化重连​

connection = HubConnection().with_stateful_reconnect()

完整细节见状态化重连。当服务器回应 useStatefulReconnect 时，客户端会缓冲未确认的出站消息，并在传输断开后重放。

下一步​