用途:当 Axum 处理器需要以纯 HTTP 单向推送服务端到客户端数据流时使用,典型场景包括实时通知、日志跟踪、进度更新、LLM token 流。SSE 使用 text/event-stream 长连接响应,浏览器用 new EventSource(url) 消费并自动重连。
主要能力:Axum 通过 axum::response::sse 模块提供 SSE,仅三个公开类型:Sse<S>(包装 Stream 并实现 IntoResponse)、Event(用 Event::default() 链式构建单条记录)、KeepAlive(空闲填充,保持安静连接)。该模块在 Axum 0.7 与 0.8 间 API 稳定,示例代码两版通用。
使用方式:处理器返回 Sse<impl Stream<Item = Result<Event, E>>>,用 Sse::new(stream) 构建;无失败流用 .map(Ok) 转为 Result<Event, Infallible>;长连接加 .keep_alive(KeepAlive::new())。单条消息用 Event::default().data("text"),命名事件加 .event("name"),JSON 负载用 .json_data(value)?(需 json feature),可恢复事件加 .id("42")。可用 tokio_stream::StreamExt 的 .throttle(Duration) 控制节奏。
限制与注意:Sse::new 要求 S: TryStream<Ok = Event>,裸 Stream<Item = Event> 不满足,这是最常见编译错误。同一 Event 上 .data、.event、.id、.retry 各只能调用一次,重复调用会 panic;.event、.id、.comment 中不能含换行,仅 .data 接受换行。流必须 Send + 'static,避免 Rc 或借用数据。不要在流的 poll_next 中执行阻塞或 CPU 密集工作,应使用 tokio::spawn 或 spawn_blocking 并通过 channel 送入。长连接务必附加 KeepAlive,默认 15 秒注释间隔。若客户端也需发送消息,应改用 WebSocket。
适用场景:仅服务端推送的通知、订阅源、日志、进度、token 流。
暂未提供:具体收费、价格、平台支持范围等资料未给出。