xfyun-sdk
Version:
科大讯飞语音识别 SDK，支持浏览器中实时语音听写功能
187 lines (186 loc) • 5.37 kB
TypeScript
/**
* WebSocket 客户端基类
* @description 提取所有基于 WebSocket 的讯飞 API 客户端的通用逻辑
*
* 包含功能：
* - WebSocket 连接管理（创建、发送、关闭）
* - 定时器管理（连接超时、关闭延迟）
* - 状态管理（状态转换验证）
* - 错误处理模式
*
* @example
* ```typescript
* abstract class MyClient extends BaseWebSocketClient<MyState> {
* protected readonly STATE_TRANSITIONS: Record<MyState, MyState[]> = { ... };
*
* protected parseMessage(data: string | ArrayBuffer): void {
* // 子类实现消息解析
* }
*
* protected getModulePrefix(): string {
* return '[MyClient]';
* }
* }
* ```
*/
import { Logger } from './logger';
import type { XfyunError } from './types';
/**
* 基础状态类型
*/
export type BaseState = 'idle' | 'connecting' | 'connected' | 'stopped' | 'error';
/**
* WebSocket 客户端配置接口
*/
export interface BaseWebSocketClientOptions {
appId: string;
apiKey: string;
apiSecret: string;
logLevel?: 'debug' | 'info' | 'warn' | 'error';
}
/**
* 事件处理器基接口
*/
export interface BaseEventHandlers<State extends string = string> {
onError?: (error: XfyunError) => void;
onStateChange?: (state: State) => void;
onStop?: () => void;
}
/**
* WebSocket 客户端基类
*
* 提供通用的 WebSocket 连接管理、状态管理和错误处理功能。
* 子类需要实现特定的消息解析和业务逻辑。
*/
export declare abstract class BaseWebSocketClient<State extends string = BaseState, Options extends BaseWebSocketClientOptions = BaseWebSocketClientOptions, Handlers extends BaseEventHandlers<State> = BaseEventHandlers<State>> {
protected websocket: WebSocket | null;
protected websocketCloseTimer: number | null;
protected connectingTimer: number | null;
protected static readonly CONNECTING_TIMEOUT_MS = 10000;
protected state: State;
protected abstract readonly STATE_TRANSITIONS: Record<State, State[]>;
readonly logger: Logger;
protected readonly options: Options;
protected handlers: Handlers;
protected destroyed: boolean;
/**
* 创建 WebSocket 客户端实例
* @param options 配置选项
* @param handlers 事件处理程序
*/
constructor(options: Options, handlers?: Handlers);
/**
* 获取模块前缀（用于日志）
*/
protected abstract getModulePrefix(): string;
/**
* 解析 WebSocket 消息
* @param data 接收到的数据
*/
protected abstract parseMessage(data: string | ArrayBuffer): void;
/**
* 获取错误码前缀（用于错误码命名空间）
*/
protected abstract getErrorCodePrefix(): number;
/**
* 生成认证 URL
*/
protected abstract generateAuthUrl(): string;
/**
* 确保 WebSocket 已初始化
* @throws 如果 WebSocket 未初始化则抛出错误
*/
protected ensureWebSocket(): WebSocket;
/**
* 安全地发送 WebSocket 消息
* @param data 要发送的数据
* @returns 发送是否成功
*/
protected safeSend(data: string | ArrayBuffer): boolean;
/**
* 安全地关闭 WebSocket 连接
*/
protected safeCloseWebSocket(): void;
/**
* 初始化 WebSocket 连接
*/
protected initWebSocket(): void;
/**
* 设置 WebSocket 所有事件处理器
*/
protected setupWebSocketHandlers(): void;
/**
* 处理 WebSocket 连接打开事件
*/
protected handleWebSocketOpen(): void;
/**
* 连接成功后的回调 - 子类可重写
*/
protected onConnected(): void;
/**
* 处理 WebSocket 消息事件
*/
protected handleWebSocketMessage(event: MessageEvent): void;
/**
* 处理 WebSocket 错误事件
*/
protected handleWebSocketError(error: Event): void;
/**
* 处理 WebSocket 关闭事件
*/
protected handleWebSocketClose(event: CloseEvent): void;
/**
* WebSocket 关闭后的回调 - 子类可重写
*/
protected onWebSocketClosed(_event: CloseEvent): void;
/**
* 设置 Connecting 超时检测
*/
protected setupConnectingTimeout(): void;
/**
* 清除 WebSocket 关闭定时器
*/
protected clearWebSocketCloseTimer(): void;
/**
* 清除连接超时定时器
*/
protected clearConnectingTimer(): void;
/**
* 安排 WebSocket 延迟关闭
* @param delay 延迟时间（毫秒）
*/
protected scheduleWebSocketClose(delay?: number): void;
/**
* 获取当前状态
*/
getState(): State;
/**
* 设置状态（带转换验证）
* @param newState 新状态
*/
protected setState(newState: State): void;
/**
* 处理错误
* @param error 错误信息
*/
protected handleError(error: XfyunError): void;
/**
* 销毁实例，释放所有资源
*/
destroy(): void;
/**
* 检查实例是否已销毁
*/
isDestroyed(): boolean;
/**
* 设置事件处理程序
* @param newHandlers 新的事件处理程序
*/
setHandlers(newHandlers: Partial<Handlers>): void;
}
/**
* 构造函数类型（用于 Mixin）
*/
export interface Constructor<T = object> {
new (...args: any[]): T;
}