客户端 API

`aiosignalr.client`

`HubConnection`

客户端连接。用法见客户端指南。

构造

HubConnection(
    *,
    protocol: str | IHubProtocol = "json",
    options: HubConnectionOptions | None = None,
    logger: logging.Logger | None = None,
)

构建器方法

方法	说明
`with_retry_policy(policy) -> HubConnection`	开启自动重连
`with_stateful_reconnect(buffer_size=100_000) -> HubConnection`	开启状态化重连

连接方法

方法	说明
`async start(url, *, access_token_factory=None, headers=None, transports=None, skip_negotiation=False)`	协商、连接、握手
`async stop()`	优雅关闭并清理
`async invoke(target, *args) -> Any`	调用并等待结果
`async stream(target, *args) -> AsyncIterator`	调用流式方法
`async send(target, *args)`	即发即弃调用
`async client_stream(target, *args) -> AsyncIterator[_UploadHandle]`	上传客户端流
`on(target, handler) -> HubConnection`	注册服务器调用处理器
`remove(target, handler)`	移除处理器

属性与事件

成员	类型	说明
`state`	`ConnectionState`	当前生命周期状态
`on_open`	`Callable[[], ...] \| None`	首次连接时触发
`on_close`	`Callable[[BaseException \| None], ...] \| None`	永久关闭时触发
`on_reconnecting`	`Callable[[BaseException \| None], ...] \| None`	重连周期开始时触发
`on_reconnected`	`Callable[[], ...] \| None`	重连成功时触发

`_UploadHandle`

由 client_stream() 返回：

async send_item(item) —— 上传一个数据项。
async complete(error=None) —— 结束上传。
result —— 完成后保存服务器结果。

`HubConnectionOptions`

字段	默认	说明
`handshake_timeout`	15.0	等待握手的秒数
`server_timeout`	30.0	静默多少秒后客户端断开
`keep_alive_interval`	15.0	客户端心跳间隔
`stateful_reconnect_buffer_size`	100_000	出站缓冲字节上限

重试策略

RetryContext(previous_retry_count, elapsed_time, retry_reason) —— 传给 RetryPolicy.next_retry_delay。

RetryPolicy（ABC）—— 实现 next_retry_delay(context) -> float | None。
DefaultRetryPolicy —— 0s, 2s, 10s, 30s，然后 None。

协商辅助

negotiate(session, base_url, *, headers=None, negotiate_version=1, use_stateful_reconnect=False) -> NegotiateResult

NegotiateResult 字段：

字段	说明
`connection_id`	服务器连接 id
`connection_token`	用于 `?id=` 查询串的 token（negotiate v1+）
`negotiate_version`	协商好的版本
`available_transports`	`[AvailableTransport(name, transfer_formats)]`
`use_stateful_reconnect`	是否协商成功 ack 协议
`url` / `access_token`	重定向响应字段（如有）

常量：WEB_SOCKETS、SERVER_SENT_EVENTS、LONG_POLLING、 DEFAULT_TRANSPORTS、NEGOTIATE_VERSION。

`aiosignalr.enums`

枚举	值
`ConnectionState`	`DISCONNECTED, CONNECTING, CONNECTED, RECONNECTING`
`TransferFormat`	`TEXT, BINARY`
`MessageType`	`INVOCATION=1 … SEQUENCE=9`

aiosignalr.client​

HubConnection​

构造​

构建器方法​

连接方法​

属性与事件​

_UploadHandle​

HubConnectionOptions​

重试策略​

协商辅助​

aiosignalr.enums​