ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

ErisPulse.Core.client 模块


模块概述

ErisPulse HTTP/WS 客户端

基于 aiohttp 的统一 HTTP 和 WebSocket 客户端实现,提供完整的请求/响应/WS 抽象。 模块和适配器应优先使用此客户端发送 HTTP 请求和建立 WS 连接,而非自行导入 aiohttp。

底层 aiohttp 异常会在内部捕获并转换为 ErisPulse 异常体系, 确保业务代码不依赖任何特定 HTTP 库。

提示

  1. 使用 sdk.client 获取全局客户端单例
  2. 支持 get / post / put / delete / patch / request / ws_connect 等方法
  3. aiohttp 异常自动转换为 ErisPulse 异常 (ClientError 体系)
  4. 自动记录请求日志和统计信息

类列表

class HttpResponse(BaseHttpResponse)

HTTP 响应封装

提供与 aiohttp.ClientResponse 一致的访问接口。 自动读取并缓存响应体,避免重复读取。

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

示例:

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

方法列表

__init__(response)
  • response (object): 底层框架 Response 对象

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): 内容类型


charset -> str | None(property)

字符编码

返回值 (str | None): 编码名称


url -> Any(property)

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

返回值: object URL 对象


raw -> Any(property)

底层框架原生 Response 对象

返回值 (object): 原生响应实例 (当前为 aiohttp.ClientResponse)


async read() -> bytes

读取响应体原始字节 (自动缓存)

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


class ClientWebSocket(BaseClientWebSocket)

客户端 WebSocket 连接 (基于 aiohttp)

封装 aiohttp.ClientWebSocketResponse,提供统一的 WebSocket 客户端接口。 通过 sdk.client.ws_connect() 获取实例。

提示

  1. 使用 iter_text/iter_bytes/iter_json 自动过滤消息类型
  2. 使用 receive/iter_messages 处理原始消息类型 (如 CLOSE/ERROR)
  3. 通过 .raw 属性可访问底层 aiohttp.ClientWebSocketResponse

示例:

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

方法列表

__init__(ws)
  • ws (aiohttp.ClientWebSocketResponse): 底层 aiohttp WS 对象

closed -> bool(property)

连接是否已关闭

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


async send_text(data: str) -> None

发送文本消息

  • data (str): 文本内容

async send_bytes(data: bytes) -> None

发送二进制消息

  • data (bytes): 二进制内容

async send_json(data: Any, mode: str = 'text') -> None

发送 JSON 消息

  • data (Any): 要序列化的数据
  • mode (str): 发送模式 ("text" 或 "binary") (默认: "text")

_convert_ws_msg(msg) -> WSMessage

转换 aiohttp WSMessage 为 ErisPulse WSMessage

内部方法


_note_closed() -> None

内部方法 远端断开感知:aiohttp 被动关闭不会经 close(),在接收路径同步注销登记


async receive() -> WSMessage

接收原始消息

返回值 (WSMessage): 消息对象


async receive_text() -> str

接收文本消息

返回值 (str): 文本内容

异常: WebSocketDisconnect - 连接断开时

异常: WebSocketError - 收到非文本消息时


async receive_bytes() -> bytes

接收二进制消息

返回值 (bytes): 二进制内容

异常: WebSocketDisconnect - 连接断开时

异常: WebSocketError - 收到非二进制消息时


async receive_json(mode: str = 'text') -> Any

接收 JSON 消息

  • mode (str): 接收模式 ("text" 或 "binary") (默认: "text")

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

异常: WebSocketDisconnect - 连接断开时


async _close(code: int = WS_CLOSE_NORMAL, reason: str | None = None) -> None

实际关闭动作(权限校验见基类 close)

  • code (int): 关闭码 (默认: 1000)
  • reason (str | None): 关闭原因 (可选)

class Client(BaseClient)

HTTP/WS 客户端 (基于 aiohttp)

提供统一的异步 HTTP 请求和 WebSocket 连接接口。 自动管理连接池和会话生命周期,底层 aiohttp 异常自动转换为 ErisPulse 异常。

提示

  1. 通过 sdk.client 获取全局单例,也可自行实例化
  2. 使用 get/post/put/delete/patch 快捷方法或通用 request 方法
  3. 使用 ws_connect 建立 WebSocket 连接
  4. 支持 ErisPulse 异常体系,业务代码不依赖 aiohttp
  5. 所有请求自动通过 lifecycle 发送事件,可用于监控

示例:

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")

方法列表

__init__(*, timeout: float | None = None, connect_timeout: float | None = None, max_retries: int | None = None, retry_delay: float | None = None, headers: dict[str, str] | None = None, user_agent: str | None = None, proxy: str | None = None)
  • timeout (float | None): 请求总超时 (秒) (默认: 30)
  • connect_timeout (float | None): 连接超时 (秒) (默认: 10)
  • max_retries (int): 最大重试次数 (默认: 1)
  • retry_delay (float): 重试间隔 (秒) (默认: 1)
  • headers (dict[str, str]): 全局默认请求头 (可选)
  • user_agent: str User-Agent 字符串 (可选)
  • proxy (str | None): 代理 URL(如 http://127.0.0.1:7890),为 None 时自动检测环境变量

_build_session_kwargs(timeout)

构建 aiohttp.ClientSession 参数,自动注入代理


_build_form_data(data: Any, files: dict[str, Any])

从 data 和 files 构建 multipart/form-data 请求体

  • data (Any): 表单数据 (dict 时合并进 FormData)
  • files (dict[str, Any]): 文件字段

返回值: aiohttp.FormData multipart 表单对象

异常: ValueError - data 为非 dict 类型且不为 None


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) -> HttpResponse

发送 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: 传递给底层请求的额外参数

返回值 (HttpResponse): 响应对象

异常: ClientConnectionError - 连接失败

异常: ClientTimeoutError - 请求超时

异常: ClientError - 其他客户端错误

示例:

resp = await client.request("GET", "https://httpbin.org/get", params={"q": "test"})

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

建立 WebSocket 连接

  • url: str WebSocket 服务器 URL

  • headers (dict[str, str] | None): 额外请求头 (可选)

  • heartbeat (float | None): 心跳间隔秒数 (可选)

  • timeout (float): 连接超时秒数 (默认: DEFAULT_WS_CLIENT_CONNECT_TIMEOUT_SECS)

  • track (bool): 是否将连接自动登记进连接池(默认 True)

  • owner (str | None): 连接归属者(默认取当前 owner 上下文;

            上下文不可用时建议显式传模块名,卸载时框架按其统一关闭)
    
  • kwargs: 传递给底层 ws_connect 的额外参数

返回值: ClientWebSocket WebSocket 连接对象

异常: ClientConnectionError - 连接失败

异常: ClientError - 其他客户端错误

示例:

ws = await sdk.client.ws_connect("wss://example.com/ws", heartbeat=30)
ws.id  # 已登记,可被 connections 查询/广播
async for text in ws.iter_text():
    await ws.send_text(f"Echo: {text}")

async get(url: str, *, params: dict[str, str] | None = None, headers: dict[str, str] | None = None, **kwargs) -> HttpResponse

发送 GET 请求

  • url (str): 请求 URL
  • params (dict[str, str] | None): 查询参数 (可选)
  • headers (dict[str, str] | None): 额外请求头 (可选)

返回值 (HttpResponse): 响应对象

示例:

resp = await client.get("https://httpbin.org/get", params={"q": "test"})
data = await resp.json()

async post(url: str, *, data: Any = None, json: Any = None, files: dict[str, Any] | None = None, headers: dict[str, str] | None = None, **kwargs) -> HttpResponse

发送 POST 请求

  • url (str): 请求 URL
  • data (Any): 请求体 (表单或原始数据) (可选)
  • json: Any JSON 请求体 (可选)
  • files (dict[str, Any] | None): 文件上传字段 (可选, 自动构建 multipart/form-data)
  • headers (dict[str, str] | None): 额外请求头 (可选)

返回值 (HttpResponse): 响应对象

示例:

resp = await client.post("https://httpbin.org/post", json={"key": "value"})

async put(url: str, *, data: Any = None, json: Any = None, files: dict[str, Any] | None = None, headers: dict[str, str] | None = None, **kwargs) -> HttpResponse

发送 PUT 请求

  • url (str): 请求 URL
  • data (Any): 请求体 (可选)
  • json: Any JSON 请求体 (可选)
  • files (dict[str, Any] | None): 文件上传字段 (可选, 自动构建 multipart/form-data)
  • headers (dict[str, str] | None): 额外请求头 (可选)

返回值 (HttpResponse): 响应对象


async delete(url: str, *, headers: dict[str, str] | None = None, **kwargs) -> HttpResponse

发送 DELETE 请求

  • url (str): 请求 URL
  • headers (dict[str, str] | None): 额外请求头 (可选)

返回值 (HttpResponse): 响应对象


async patch(url: str, *, data: Any = None, json: Any = None, files: dict[str, Any] | None = None, headers: dict[str, str] | None = None, **kwargs) -> HttpResponse

发送 PATCH 请求

  • url (str): 请求 URL
  • data (Any): 请求体 (可选)
  • json: Any JSON 请求体 (可选)
  • files (dict[str, Any] | None): 文件上传字段 (可选, 自动构建 multipart/form-data)
  • headers (dict[str, str] | None): 额外请求头 (可选)

返回值 (HttpResponse): 响应对象


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

请求统计

返回值 (dict): 统计数据(total_requests / total_errors 等,含

latency_p50_ms / latency_p95_ms 请求延迟分位;无采样时为 0)

reset_stats() -> None

重置统计数据