ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

ErisPulse.Core.Bases.client 模块


模块概述

ErisPulse HTTP 客户端抽象基类

定义 HTTP 客户端、响应和客户端 WebSocket 连接的抽象接口, 使模块和适配器无需直接依赖 aiohttp。 具体实现由 Core.client 模块提供(基于 aiohttp)。

提示

  1. 支持 get / post / put / delete / patch / request 等常用方法
  2. 支持 ws_connect 建立 WebSocket 连接
  3. 自动记录请求日志和统计信息
  4. 推荐所有模块和适配器使用此客户端发送 HTTP 请求和建立 WS 连接

类列表

class BaseHttpResponse

HTTP 响应抽象基类

定义统一的响应访问接口,具体实现由 Core.client.HttpResponse 提供。

提示 通过 .raw 属性可访问底层原生响应对象

示例:

resp = await sdk.client.get("https://httpbin.org/get")
print(resp.status)
data = await resp.json()

方法列表

status -> int(property)

HTTP 状态码

返回值 (int): 状态码 (如 200, 404)


reason -> str | None(property)

状态描述

返回值 (str | None): 状态原因短语


headers -> Any(property)

响应头

返回值 (object): 大小写不敏感的响应头映射


content_type -> str | None(property)

Content-Type 值

返回值 (str | None): 内容类型


url -> Any(property)

响应 URL (可能因重定向而与请求 URL 不同)

返回值: object URL 对象


raw -> Any(property)

底层框架原生 Response 对象

返回值 (object): 原生响应实例


async read() -> bytes

读取响应体原始字节

返回值 (bytes): 响应体内容


async text(encoding: str | None = None) -> str

读取响应体为文本

  • encoding (str | None): 指定编码 (可选, 默认自动检测)

返回值 (str): 文本内容


async json(**kwargs) -> Any

解析响应体为 JSON

  • kwargs: 传递给解析器的额外参数

返回值 (Any): 解析后的数据


class BaseClientWebSocket(WebSocketConnectionBase)

客户端 WebSocket 连接抽象基类

扩展 WebSocketConnectionBase,增加客户端特有的消息类型处理和连接状态。

提示

  1. 通过 sdk.client.ws_connect() 获取实例
  2. 使用 receive() / iter_messages() 处理原始消息类型
  3. 使用 receive_text() / iter_text() 等高级方法自动过滤消息类型

示例:

ws = await sdk.client.ws_connect("wss://example.com/ws")
async for msg in ws.iter_messages():
    if msg.type == WSMessage.TEXT:
        await ws.send_text(f"Echo: {msg.data}")

方法列表

__init__(ws, *, connection_id: str = '', namespace: str = '', owner: str = '', kind: str = 'client')
  • ws (object): 底层框架 WebSocket 对象
  • connection_id (str): 连接池分配的连接 id(未登记时为空串)
  • namespace (str): 服务端路由命名空间(客户端出站连接为空)
  • owner (str): 归属 owner(模块名 / 平台名),拥有关闭权
  • kind (str): 连接种类(默认 "client")

closed -> bool(property)

连接是否已关闭

返回值 (bool): 是否已关闭


async receive() -> WSMessage

接收原始消息

返回值 (WSMessage): 消息对象 (包含 type 和 data 属性)


async iter_messages() -> AsyncIterator[WSMessage]

迭代原始消息直到断开

自动在收到 CLOSE 或 ERROR 消息时停止迭代。

返回值: async generator 逐条返回 WSMessage

示例:

async for msg in ws.iter_messages():
    if msg.type == WSMessage.TEXT:
        print(msg.data)
    elif msg.type == WSMessage.CLOSE:
        break

class BaseClient

HTTP 客户端抽象基类

定义统一的异步 HTTP 请求和 WebSocket 连接接口, 具体实现由 Core.client.Client 提供。

提示

  1. 通过 sdk.client 获取全局单例,也可自行实例化
  2. 使用 get/post/put/delete/patch 快捷方法或通用 request 方法
  3. 使用 ws_connect 建立 WebSocket 连接
  4. 推荐所有模块和适配器使用此客户端发送 HTTP 请求

示例:

resp = await sdk.client.get("https://httpbin.org/get")
data = await resp.json()

ws = await sdk.client.ws_connect("wss://example.com/ws")
await ws.send_text("Hello")

方法列表

async request(method: str, url: str, *, params: dict[str, str] | None = None, headers: dict[str, str] | None = None, data: Any = None, json: Any = None, files: dict[str, Any] | None = None, timeout: float | None = None, max_retries: int | None = None, **kwargs) -> BaseHttpResponse

发送 HTTP 请求

  • method: str HTTP 方法 (GET, POST, PUT, DELETE, PATCH 等)
  • url (str): 请求 URL
  • params (dict[str, str] | None): 查询参数 (可选)
  • headers (dict[str, str] | None): 额外请求头 (可选)
  • data (Any): 请求体 (表单或原始数据) (可选)
  • json: Any JSON 请求体 (可选)
  • files (dict[str, Any] | None): 文件上传字段 (可选, 自动构建 multipart/form-data)
  • timeout (float | None): 本次请求超时 (秒) (可选, 覆盖默认值)
  • max_retries (int | None): 本次最大重试次数 (可选, 覆盖默认值)
  • kwargs: 传递给底层请求的额外参数

返回值 (BaseHttpResponse): 响应对象


async ws_connect(url: str, *, headers: dict[str, str] | None = None, heartbeat: float | None = None, track: bool = True, owner: str | None = None, **kwargs) -> BaseClientWebSocket

建立 WebSocket 连接

  • url: str WebSocket 服务器 URL
  • headers (dict[str, str] | None): 额外请求头 (可选)
  • heartbeat (float | None): 心跳间隔秒数 (可选)
  • track (bool): 是否登记进连接池 (默认: True)
  • owner (str | None): 连接归属者 (默认: 当前 owner 上下文)
  • kwargs: 传递给底层 WS 连接的额外参数

返回值: BaseClientWebSocket WebSocket 连接对象

示例:

ws = await sdk.client.ws_connect("wss://example.com/ws")
async for text in ws.iter_text():
    await ws.send_text(f"Echo: {text}")

async get(url: str, **kwargs) -> BaseHttpResponse

发送 GET 请求

  • url (str): 请求 URL

返回值 (BaseHttpResponse): 响应对象


async post(url: str, **kwargs) -> BaseHttpResponse

发送 POST 请求

  • url (str): 请求 URL

返回值 (BaseHttpResponse): 响应对象


async put(url: str, **kwargs) -> BaseHttpResponse

发送 PUT 请求

  • url (str): 请求 URL

返回值 (BaseHttpResponse): 响应对象


async delete(url: str, **kwargs) -> BaseHttpResponse

发送 DELETE 请求

  • url (str): 请求 URL

返回值 (BaseHttpResponse): 响应对象


async patch(url: str, **kwargs) -> BaseHttpResponse

发送 PATCH 请求

  • url (str): 请求 URL

返回值 (BaseHttpResponse): 响应对象


async close() -> None

关闭客户端会话并释放资源


stats -> dict[str, int | float](property)

请求统计

返回值 (dict): 统计数据(含 latency_p50_ms / latency_p95_ms 延迟分位)


reset_stats() -> None

重置统计数据