罗罗编程学习记录
本页内容 展开查看

04.4.3.3 错误处理与实时通信实战

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.4 Rust / 04.4.3 Axum

04.4.3.3-001 axum 的 handler 返回值为什么必须实现 IntoResponse?

一句话结论

axum 把 handler 的返回值统一转成 Response<Body>,因此任何返回类型都必须实现 IntoResponse;trait 提供 into_response(self) -> Response,框架在分发时调用它完成类型到 HTTP 报文的转换。

概念解释

IntoResponse 是 axum 的响应抽象边界:字符串、Json<T>、StatusCode、元组 (StatusCode, T)、Result<Ok, Err> 都有现成实现。handler 本身不直接操作 hyper 的 Response,只返回业务类型,由框架适配层完成序列化、状态码与 header 填充。这与提取器 FromRequest 形成对称:请求侧把 Request 拆成参数,响应侧把返回值拼回 Response。

原理流程

  1. 路由命中后,axum 适配器调用 handler 得到返回值。
  2. 适配器对返回值调用 IntoResponse::into_response。
  3. 若返回 Result,框架分别对 Ok 与 Err 调用各自的 IntoResponse。
  4. 生成的 Response<Body> 交给 tower 层链与 hyper 写出。
  5. 未实现 IntoResponse 的自定义类型会在编译期报错。

代码或图示

use axum::{response::IntoResponse, http::StatusCode};

async fn handler() -> Result<&'static str, AppError> {
    Ok("ok")
}

// 只要 AppError 实现 IntoResponse,Result<&str, AppError> 就自动满足约束

常见误区

  • 以为 handler 必须返回 Response<Body>:业务代码通常返回更具体的类型即可。
  • 以为 Result 的 Err 会被框架自动转成 500:Err 类型同样要实现 IntoResponse,否则编译不通过。

追问

  • Json<T> 如何实现 IntoResponse?答:把 T 用 serde_json 序列化,写入 Content-Type: application/json 与 body,序列化失败时返回 500。
  • 元组 (StatusCode, impl IntoResponse) 的作用是什么?答:在保留内层响应体的同时覆盖状态码,是最常用的错误返回形式。

04.4.3.3-002 如何为自定义错误枚举实现 IntoResponse?

一句话结论

用 thiserror 定义错误枚举,再为它手写 IntoResponse 实现:在 into_response 里按变体选择状态码与错误体,返回 (StatusCode, Json(Body)) 形式的响应。

概念解释

自定义错误枚举是应用层最常见的返回类型。枚举变体对应不同业务失败场景,IntoResponse 实现负责把变体映射到 HTTP 语义:未找到对应 404、参数非法对应 422、未授权对应 401。错误体结构在实现内统一构造,避免每个 handler 重复拼装 JSON。thiserror 只负责派生 Error、Display 与 source,不提供 HTTP 映射,这部分必须手写。

原理流程

  1. 定义 enum AppError,用 #[error("...")] 标注每个变体的展示信息。
  2. 定义统一错误体结构体 ErrorBody,派生 Serialize。
  3. 为 AppError 实现 IntoResponse,先匹配变体得到状态码与错误码。
  4. 构造 ErrorBody,序列化为 Json,与状态码组成元组返回。
  5. handler 直接返回 Result<T, AppError>,无需在业务代码里写状态码。

代码或图示

use axum::{http::StatusCode, response::{IntoResponse, Json}};
use serde::Serialize;
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("用户不存在")]
    NotFound,
    #[error("参数校验失败: {0}")]
    Validation(String),
    #[error("内部错误")]
    Internal,
}

#[derive(Serialize)]
struct ErrorBody { code: String, message: String }

impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        let (status, code) = match &self {
            AppError::NotFound => (StatusCode::NOT_FOUND, "NOT_FOUND"),
            AppError::Validation(_) => (StatusCode::UNPROCESSABLE_ENTITY, "VALIDATION"),
            AppError::Internal => (StatusCode::INTERNAL_SERVER_ERROR, "INTERNAL"),
        };
        let body = Json(ErrorBody { code: code.into(), message: self.to_string() });
        (status, body).into_response()
    }
}

常见误区

  • 在 IntoResponse 里直接 unwrap 序列化结果:序列化失败会再次 panic,应兜底为纯文本 500。
  • 把内部异常的原始消息(含 SQL、堆栈)原样写进响应体,造成信息泄露。

追问

  • 变体携带 source 时如何处理?答:日志层通过 source() 展开错误链,响应体只暴露面向用户的摘要消息。
  • 为什么不直接给每个变体单独实现响应?答:枚举集中映射便于统一错误码与错误体格式,新增变体时只改一处。

04.4.3.3-003 axum 提供了哪些现成的 IntoResponse 组合形式?

一句话结论

标准库与 axum 为 StatusCode、&str、String、Json<T>、Bytes、(StatusCode, T)、(HeaderMap, T)、Result<Ok, Err> 等类型提供了实现,组合元组可以叠加状态码与响应头。

概念解释

IntoResponse 的组合规则是 axum 响应层的基础能力。单元素类型直接决定 body 与默认状态码;带状态码的二元组覆盖状态;带头的二元组在写出前插入 header。Result 的实现要求 Ok 与 Err 各自实现 IntoResponse,从而让 handler 用 ? 传播错误后由框架分别转响应。理解这些现成实现,可以避免为简单返回值手写 trait。

原理流程

  1. handler 返回类型进入适配器,框架按类型查找 IntoResponse 实现。
  2. 元组实现按位置拆解:先取状态码或 header,再把内层类型转成 body。
  3. Result 实现内部分支匹配 Ok/Err,分别调用内层 into_response。
  4. 序列化类类型(如 Json)在实现内写入对应 Content-Type。
  5. 最终统一为 Response<Body> 进入层链。

代码或图示

use axum::{http::{StatusCode, HeaderMap, header}, response::Json};
use serde::Serialize;

#[derive(Serialize)]
struct Item { id: u64 }

// 状态码 + JSON
let a = (StatusCode::CREATED, Json(Item { id: 1 }));

// 响应头 + 正文
let mut headers = HeaderMap::new();
headers.insert(header::CACHE_CONTROL, "no-cache".parse().unwrap());
let b = (headers, "text");

// Result 两侧各自满足 IntoResponse 即可
async fn f() -> Result<Json<Item>, AppError> { Ok(Json(Item { id: 1 })) }

常见误区

  • 以为三元组 (StatusCode, HeaderMap, T) 也有实现:具体支持的元组长度与顺序以 docs.rs 当前版本为准,不确定时先查 IntoResponse 文档。
  • 在元组里放 String 又重复设置 Content-Type:类型实现默认已带文本或 JSON 的头,重复设置可能被覆盖。

追问

  • (StatusCode, Json<T>) 与直接返回 Json<T> 的区别?答:前者显式指定状态码(如创建成功用 201),后者默认 200。
  • 如何返回纯字节流响应?答:使用 Bytes 或 axum::body::Body 类型,具体实现以当前版本文档为准。

04.4.3.3-004 提取器的拒绝类型 Rejection 如何映射成 HTTP 响应?

一句话结论

提取器返回 Result<Self, Self::Rejection>,Rejection 类型需要实现 IntoResponse;axum 内置提取器的拒绝通常映射为 400/415/422 等状态码,自定义提取器可在拒绝类型上覆写映射。

概念解释

提取器在构造参数失败时不直接 panic,而是返回拒绝。拒绝类型是提取器错误与响应层之间的桥:内置提取器(Path、Query、Json 等)各有自己的 Rejection,并通过组合实现描述失败原因。业务侧若想定制拒绝响应(例如把 JSON 解析失败改成 422 字段级错误),需要把内置 rejection 转换为自己的错误类型,再走 IntoResponse 映射。

原理流程

  1. handler 适配器依次调用提取器的 from_request 或 from_request_parts。
  2. 提取器返回 Err(Rejection) 时,适配器立即短路,不再构造后续参数。
  3. 框架调用 Rejection::into_response 生成响应。
  4. 内置 rejection 组合链按原因匹配默认状态码。
  5. 自定义提取器可在实现中直接返回 (StatusCode, Json(body)) 作为拒绝。

代码或图示

use axum::{extract::Json, response::{IntoResponse, Response}, http::StatusCode};
use serde::Deserialize;

#[derive(Deserialize)]
struct CreateUser { name: String }

// 内置 Json rejection 默认按解析失败处理;需要定制时可在 handler 内
// 用 Result 接收 Json<JsonRejection> 再转换为 AppError
async fn create(Json(payload): Json<CreateUser>) -> Response {
    (StatusCode::OK, format!("{}", payload.name)).into_response()
}

常见误区

  • 以为提取器失败会抛出可被 catch_unwind 捕获的 panic:拒绝是普通 Result 分支,不是 panic。
  • 混淆提取器拒绝与业务错误:前者是请求格式/绑定失败,后者是业务规则失败,二者在响应体里最好区分错误码。

追问

  • Json 提取器对缺失 Content-Type 与 JSON 语法错误分别返回什么状态码?答:以 docs.rs 当前版本内置 rejection 实现为准,通常分别对应不支持的类型与请求体解析失败,需要时用日志核对实际状态码。
  • 自定义提取器的 Rejection 怎么定义?答:定义一个错误枚举或结构体,为其实现 IntoResponse,并在 FromRequest/FromRequestParts 的 Rejection 关联类型上指定。

04.4.3.3-005 如何把 thiserror 错误枚举按变体映射到不同 HTTP 状态码?

一句话结论

在 IntoResponse 实现内用 match 匹配枚举变体,分别给出状态码与业务错误码;携带底层源错误的变体只在日志中展开,响应体不暴露内部细节。

概念解释

thiserror 派生的枚举天然适合做 HTTP 错误映射:变体即错误场景。映射时区分三类信息:HTTP 状态码表达协议语义,业务错误码供前端与日志检索,展示消息面向调用者。底层依赖错误(数据库、IO)通过 #[source] 关联,不直接进响应。映射逻辑集中在一处,避免 handler 里散落 match 与状态码字面量。

原理流程

  1. 用 #[derive(Error, Debug)] 定义变体,携带消息与 source。
  2. 写一个 status(&self) 或在 into_response 内直接 match,得到 StatusCode。
  3. 为每个变体分配稳定的业务错误码字符串。
  4. 构造统一 ErrorBody,序列化为 JSON 响应。
  5. 内部错误变体额外写日志后再返回 500。

代码或图示

use axum::{http::StatusCode, response::{IntoResponse, Json}};
use serde::Serialize;
use thiserror::Error;

#[derive(Error, Debug)]
pub enum ServiceError {
    #[error("资源未找到: {0}")]
    NotFound(String),
    #[error("当前用户无权操作")]
    Forbidden,
    #[error("数据库故障")]
    Db(#[from] sqlx::Error),
}

#[derive(Serialize)]
struct Body { code: String, message: String }

impl IntoResponse for ServiceError {
    fn into_response(self) -> axum::response::Response {
        let (status, code) = match &self {
            ServiceError::NotFound(_) => (StatusCode::NOT_FOUND, "NOT_FOUND"),
            ServiceError::Forbidden => (StatusCode::FORBIDDEN, "FORBIDDEN"),
            ServiceError::Db(_) => (StatusCode::INTERNAL_SERVER_ERROR, "INTERNAL"),
        };
        (status, Json(Body { code: code.into(), message: self.to_string() })).into_response()
    }
}

常见误区

  • 把 Db(sqlx::Error) 的 to_string() 直接返回给客户端:可能泄露 SQL 语句与连接信息。
  • 为内部错误也分配 4xx 状态码:5xx 表示服务端失败,4xx 表示调用方问题,语义不能混用。

追问

  • #[from] 变体如何区分 SQL 唯一冲突与连接失败?答:先在应用边界用 sqlx::Error 的变体(如 Database 错误码)再映射成业务错误,唯一冲突可对应 409,具体错误码取值以 sqlx 当前版本为准。
  • 映射表想配置化怎么办?答:把状态码与错误码放进结构体或配置表,match 只做变体到条目的查找。

04.4.3.3-006 anyhow::Error 为什么不能直接作为 axum 响应,应用边界怎么处理?

一句话结论

anyhow::Error 是擦除具体类型的动态错误,标准库没有为它实现 IntoResponse;应用边界应把 anyhow::Result 转换成具体的 AppError 或统一兜底为 500,再进入响应层。

概念解释

anyhow 适合在应用内部快速传播与附加上下文,但它丢失了错误的具体分类:无法在响应层判断这是未找到、参数非法还是内部故障。因此正确做法是:库与核心逻辑返回具体错误类型,应用层用 anyhow::Result 做边界汇总,在进入 HTTP 层前映射为 AppError。直接在 handler 返回 anyhow::Error 会编译失败,因为缺少 IntoResponse 实现。

原理流程

  1. 业务函数返回 anyhow::Result<T>,内部用 ? 与 .context(...) 附加信息。
  2. handler 调用业务函数后,用 map_err 把 anyhow::Error 归类为 AppError。
  3. 已知的具体场景在调用点提前转成枚举变体。
  4. 无法归类的剩余错误兜底为 Internal,写日志后返回 500。
  5. 响应层只面对具体的 AppError。

代码或图示

use anyhow::{Context, Result};
use axum::{http::StatusCode, response::{IntoResponse, Json}};

async fn load_item(id: u64) -> Result<String> {
    // 内部使用 anyhow 传播错误
    tokio::time::sleep(std::time::Duration::from_millis(10)).await;
    Ok(format!("item-{id}"))
}

async fn handler(axum::extract::Path(id): axum::extract::Path<u64>) -> axum::response::Response {
    match load_item(id).await {
        Ok(v) => (StatusCode::OK, v).into_response(),
        Err(e) => {
            tracing::error!(error = ?e, "load item failed");
            (StatusCode::INTERNAL_SERVER_ERROR, Json(serde_json::json!({"code": "INTERNAL"})))
                .into_response()
        }
    }
}

常见误区

  • 为图省事给 anyhow::Error 手写 IntoResponse 统一返回 500:会把 404/422 也变成 500,监控与前端判断全部失真。
  • 在核心库到处返回 anyhow::Error:库侧应保留具体错误类型,便于调用方分类。

追问

  • anyhow::Error 与 Box<dyn Error> 有何异同?答:都做类型擦除,anyhow 额外提供链式 context、错误链回溯与格式化输出,运行期开销更小、API 更完整。
  • 何时可以接受边界直接兜底 500?答:内部运维接口、无外部调用方的后台任务,或确实无法归类且已记录完整上下文的场景。

04.4.3.3-007 库错误与应用错误如何分层:thiserror 与 anyhow 各放哪一层?

一句话结论

库与核心模块用 thiserror 定义可枚举、可被调用方匹配的具体错误;应用边界用 anyhow 汇总与附加上下文,再映射成 HTTP 响应错误。

概念解释

错误分层与 crate 分层对应:底层模块需要让上层区分失败原因,因此错误类型必须是具体枚举,并用 thiserror 派生标准 Error 实现;上层应用把多个来源的具体错误揉在一起传播时,anyhow 的类型擦除更顺手。HTTP 层是应用错误的出口,只认识应用自己的 AppError。混用时常见反模式:底层返回 anyhow::Error 导致调用方无法 match,或应用层维护巨型具体枚举却从不匹配。

原理流程

  1. 定义领域错误枚举 DomainError,变体覆盖该模块可预期的失败。
  2. 模块函数签名返回 Result<T, DomainError>,用 #[source] 携带依赖错误。
  3. 应用 service 层可用 anyhow::Result 汇总多个 DomainError,附加场景上下文。
  4. HTTP handler 边界把 anyhow::Error 或具体错误映射为 AppError。
  5. AppError 实现 IntoResponse 完成协议转换。

代码或图示

# Cargo.toml
[dependencies]
thiserror = "2"
anyhow = "1"
// 库/模块层:具体枚举
#[derive(Debug, thiserror::Error)]
pub enum DomainError {
    #[error("记录不存在")]
    NotFound,
    #[error("违反唯一约束")]
    Conflict,
}

// 应用层:边界汇总
async fn service() -> anyhow::Result<String> {
    let v = repo::find(1).await.context("读取记录失败")?;
    Ok(v)
}

// HTTP 层:映射到响应错误
enum AppError { NotFound, Internal }

常见误区

  • 在库 crate 里引入 anyhow 作为公开错误类型:破坏调用方的错误分类能力。
  • 应用层继续用巨型 thiserror 枚举罗列所有失败:维护成本高,且多数变体在 HTTP 映射时只落到同一状态码。

追问

  • 依赖错误如何在两层之间传递?答:用 #[source] 或 #[from] 关联原始错误,保证日志能回溯到根因。
  • 两层之间需要转换吗?答:需要;From<DomainError> for AppError 实现集中做枚举到枚举的映射。

04.4.3.3-008 如何实现 RFC 7807 风格的统一错误响应体(Problem Details)?

一句话结论

定义包含 type、title、status、detail、instance 字段的错误体结构体,序列化后用 application/problem+json 作为 Content-Type,由 AppError 的 IntoResponse 统一产出。

概念解释

RFC 7807(Problem Details for HTTP APIs)是一种标准错误报文格式:type 是错误类型标识 URI,title 是简短概括,status 是 HTTP 状态码副本,detail 是具体说明,instance 标识当前请求。项目不一定严格遵循规范字段,但统一结构比每个接口各造 JSON 更利于前端与日志解析。axum 不内置 ProblemDetails 类型,需要自行定义结构体与序列化逻辑。

原理流程

  1. 定义 ProblemDetails 结构体,字段可 #[serde(skip_serializing_if)] 省略空值。
  2. 在 AppError::into_response 内按变体填充状态码、标题与细节。
  3. 从请求路径或请求 ID 填入 instance。
  4. 用 Json 序列化并覆盖 Content-Type: application/problem+json。
  5. 响应体与状态码保持一致:status 字段值等于响应状态码。

代码或图示

use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
use serde::Serialize;

#[derive(Serialize)]
struct ProblemDetails {
    r#type: String,
    title: String,
    status: u16,
    detail: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    instance: Option<String>,
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, problem) = match self {
            AppError::NotFound => (StatusCode::NOT_FOUND,
                ProblemDetails { r#type: "https://example.com/problems/not-found".into(),
                    title: "资源不存在".into(), status: 404, detail: self.to_string(), instance: None }),
            AppError::Internal => (StatusCode::INTERNAL_SERVER_ERROR,
                ProblemDetails { r#type: "https://example.com/problems/internal".into(),
                    title: "内部错误".into(), status: 500, detail: "稍后重试".into(), instance: None }),
        };
        let mut resp = Json(problem).into_response();
        *resp.status_mut() = status;
        resp.headers_mut().insert(axum::http::header::CONTENT_TYPE,
            "application/problem+json".parse().unwrap());
        resp
    }
}

常见误区

  • 响应 status 字段与真实状态码不一致:前端同时读两者,矛盾会导致判断错误。
  • type 字段填成本地错误码而非可解析标识:保留错误码可放在扩展字段,不要挤占规范字段语义。

追问

  • 是否必须使用 application/problem+json?答:规范推荐该媒体类型;项目内部也可继续用 application/json,但字段结构保持一致即可,以团队约定为准。
  • 字段不够用怎么办?答:按 RFC 7807 允许扩展成员,在结构体上增加自定义字段(如 error_code、fields)。

04.4.3.3-009 401 与 403 在错误处理中如何区分?

一句话结论

401 Unauthorized 表示未认证(缺少或无效凭证,需要登录),403 Forbidden 表示已认证但无权访问该资源;两者在错误码、提示文案与响应头(如 WWW-Authenticate)上分别处理。

概念解释

两者常被混用,但 HTTP 语义不同:401 的调用方身份不明或凭证失效,应引导重新认证;403 的身份已确认,只是权限不足。错误映射时,认证守卫失败返回 401,授权校验失败返回 403。响应体文案也要区分:401 提示未登录或凭证过期,403 提示无权限,避免前端据此错误跳转登录页。

原理流程

  1. 认证层校验凭证:缺失/过期/签名失败归类为未认证。
  2. 授权层在已知用户身份后校验资源权限,失败归类为禁止访问。
  3. 错误枚举分别定义 Unauthenticated 与 Forbidden 变体。
  4. IntoResponse 分别映射 401 与 403,附带不同错误码与文案。
  5. 401 响应可按认证方案补充 WWW-Authenticate 头。

代码或图示

#[derive(Error, Debug)]
pub enum AppError {
    #[error("未认证或凭证已过期")]
    Unauthenticated,
    #[error("无权访问该资源")]
    Forbidden,
}

fn status_of(e: &AppError) -> StatusCode {
    match e {
        AppError::Unauthenticated => StatusCode::UNAUTHORIZED,
        AppError::Forbidden => StatusCode::FORBIDDEN,
    }
}

常见误区

  • 登录态过期返回 403:浏览器与前端拦截器通常只在 401 时跳转登录,403 会被当成普通禁止。
  • 用 401 表达“已登录但角色不足”:丢失了认证信息,排查权限问题时容易误判。

追问

  • 匿名访问受保护资源应该返回哪个?答:返回 401,先完成认证;认证通过后仍无权限再返回 403。
  • 403 是否需要 WWW-Authenticate 头?答:不需要,该头主要用于 401 的认证方案协商。

04.4.3.3-010 404、422、500 分别对应哪类错误,响应体怎么写?

一句话结论

404 对应资源不存在或路径未命中,422 对应请求格式合法但语义/校验不通过,500 对应服务端内部故障;三者错误码、消息粒度与日志级别都不同。

概念解释

状态码选择决定调用方的处理方式:404 是资源定位问题,422 是业务校验问题(JSON 语法正确但字段不满足规则),500 是服务端异常。注意 400 与 422 的分工:报文无法解析常用 400,可解析但业务校验失败常用 422。响应体中 4xx 可以面向用户描述问题,5xx 只给通用提示,详细原因进服务端日志。

原理流程

  1. 资源查找返回未找到 → 404,错误码 NOT_FOUND。
  2. DTO 字段校验失败(长度、取值、关联存在性)→ 422,错误码 VALIDATION,可带字段级明细。
  3. 数据库、IO、未预期异常 → 500,错误码 INTERNAL,记录完整错误链。
  4. 统一错误体携带 code、message,422 可追加 fields 列表。
  5. 监控按状态码与错误码聚合告警。

代码或图示

#[derive(Serialize)]
struct FieldError { field: String, message: String }

#[derive(Serialize)]
struct ErrorBody { code: String, message: String,
    #[serde(skip_serializing_if = "Vec::is_empty")] fields: Vec<FieldError> }

// 422 示例体
let body = ErrorBody {
    code: "VALIDATION".into(), message: "参数校验失败".into(),
    fields: vec![FieldError { field: "email".into(), message: "邮箱格式不正确".into() }],
};

常见误区

  • 把所有参数问题都返回 400:丢失了“报文合法、语义非法”的区分,前端无法区分解析失败与校验失败。
  • 500 响应体返回堆栈与 SQL:信息泄露且对调用方无价值。

追问

  • 路由整体未命中(404 页面)由谁处理?答:未被任何路由匹配时,axum 默认返回 404;可通过兜底路由或层自定义响应,具体方式以当前版本文档为准。
  • 422 与 409 如何区分?答:422 是当前请求自身校验不通过,409 是与当前资源状态冲突(如重复提交、版本冲突)。

04.4.3.3-011 错误响应里如何携带请求 ID 并与日志关联?

一句话结论

在请求进入时生成或提取请求 ID,通过 Extension 或状态传递给错误层;IntoResponse 把该 ID 写进响应体或响应头,日志记录同一 ID,从而串起单次请求的完整链路。

概念解释

请求 ID 是错误排查的关联键:线上报错时用户只看到响应里的 ID,服务端日志按该 ID 检索即可还原上下文。实现上通常用一个中间件在 Request 进入时生成 UUID(或透传上游传入的 x-request-id),放入扩展类型;错误构造时读取该 ID,响应体或 x-request-id 头回填。日志层用 tracing::Span 携带同一字段,保证日志与响应一致。

原理流程

  1. 中间件读取 x-request-id,缺失则生成新 ID。
  2. 将 ID 封装为 Extension<RequestId> 或写入请求扩展。
  3. handler 与错误构造路径能取到该 ID。
  4. IntoResponse 在错误体中加入 request_id,并设置响应头。
  5. 日志 span 记录同一 request_id,检索时按 ID 对齐。

代码或图示

use axum::{Extension, http::HeaderMap, response::IntoResponse};

#[derive(Clone, Debug)]
struct RequestId(String);

async fn add_request_id(headers: HeaderMap, req: axum::extract::Request,
    next: axum::middleware::Next) -> axum::response::Response {
    let id = headers.get("x-request-id")
        .and_then(|v| v.to_str().ok().map(|s| s.to_string()))
        .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
    let resp = next.run(req).await;
    // 错误构造路径同样可从 Extension 读取 RequestId
    let _ = &id;
    resp
}

常见误区

  • 响应体与响应头里的 ID 不一致:两处应取同一个 RequestId 实例。
  • 每道层都重新生成 ID:应在最外层中间件生成一次,后续层只读不写。

追问

  • 如何让 tracing 日志自动带上请求 ID?答:在中间件内用 tracing::info_span! 创建 span,把 request_id 作为字段,在 span 内执行 next.run(req).await。
  • 上游网关已传 ID 时要不要覆盖?答:透传优先,缺失时才生成,避免链路 ID 断档。

04.4.3.3-012 在 IntoResponse 实现里记录错误日志要注意什么?

一句话结论

日志应在错误类型被映射时按级别记录:4xx 记 warn,5xx 记 error,并带上错误链与请求 ID;避免在 IntoResponse 里做重 IO,也不要把敏感信息写进日志。

概念解释

IntoResponse 是所有响应错误的必经出口,集中记日志看似方便,但它处于响应适配层,不应承担复杂业务逻辑。推荐做法:在错误枚举映射前(handler 边界或 service 层)完成结构化日志记录,IntoResponse 只负责转报文。若在 trait 实现内记日志,要区分错误级别,避免 404 这类正常业务分支刷 error 告警。错误链通过 std::error::Error::source 逐层展开。

原理流程

  1. 错误在边界被捕获,先附加请求 ID 与上下文。
  2. 按变体级别选择 warn(4xx)或 error(5xx)。
  3. 结构化字段记录 error、source 链、错误码。
  4. 再调用映射逻辑生成响应。
  5. IntoResponse 内不做同步阻塞 IO 与外部调用。

代码或图示

impl AppError {
    fn log(&self) {
        match self {
            AppError::NotFound | AppError::Validation(_) =>
                tracing::warn!(error = %self, code = "client_error"),
            AppError::Internal =>
                tracing::error!(error = ?self, code = "internal_error"),
        }
    }
}

impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        self.log();
        // 状态码与错误体映射……
        (axum::http::StatusCode::INTERNAL_SERVER_ERROR, self.to_string()).into_response()
    }
}

常见误区

  • 404 也打 error 级别:告警被正常探测流量淹没,真正的 5xx 反而被忽略。
  • 在 IntoResponse 里查数据库补错误信息:响应层被拖慢,且可能引入二次错误。

追问

  • 如何记录完整错误链?答:tracing 的 ?self 配合实现了 std::error::Error 的类型会输出 source 链;anyhow::Error 可直接用 {:#} 格式打印链。
  • 日志里能记请求体吗?答:谨慎处理,含密码、手机号等敏感字段应脱敏后再记录。

04.4.3.3-013 handler 内 panic 会发生什么,如何捕获并转成 500?

一句话结论

未捕获的 panic 会导致当前任务中止;在 Web 服务中应通过 tower-http 的 catch panic 层在请求边界拦截 panic,转成统一 500 响应,避免连接异常断开并记录 panic 位置。

概念解释

Rust 的 panic 默认展开(unwind),但异步任务中的 panic 只会终止该任务,连接行为依赖底层服务框架。线上服务不允许 panic 直接暴露给调用方:需要在 tower 层链最外层捕获 panic,记录位置与消息,返回 500。业务代码仍应尽量用 Result 表达失败,catch panic 只是最后一道防线,不能替代正常错误处理。

原理流程

  1. 在路由上挂载 catch panic 层,位于其他层之外。
  2. 请求进入后,panic 展开被该层拦截。
  3. 层捕获 panic 消息与位置,写错误日志。
  4. 构造统一 500 响应返回。
  5. 服务进程继续运行,不被单个 panic 拖垮。

代码或图示

use axum::Router;
use tower_http::catch_panic::CatchPanicLayer;

let app = Router::new()
    // 具体 feature 与类型名以 tower-http 当前版本文档为准
    .route("/health", axum::routing::get(|| async { "ok" }))
    .layer(CatchPanicLayer::new());

常见误区

  • 以为 Result 能接住 panic:panic 是不可恢复控制流,不是 Err,必须靠 unwind 拦截或上层层处理。
  • 捕获 panic 后继续执行业务:拦截只用于兜底转 500,不保证程序状态一致。

追问

  • 什么 feature 提供 catch panic 层?答:在 tower-http 中对应 catch-panic 功能,具体 feature 名与类型以 docs.rs 当前版本为准。
  • 能否把 panic 转成 4xx?答:协议上 panic 属于服务端缺陷,通常应映射 500;转成 4xx 会掩盖服务端问题。

04.4.3.3-014 catch panic 层的配置要点有哪些?

一句话结论

要点包括层挂载位置(最外层)、panic 处理器自定义响应体、panic 消息是否外露,以及确认运行时 panic 策略是 unwind 而非 abort;配置以 tower-http 当前版本 API 为准。

概念解释

catch panic 层位于 tower 服务链,负责把 panic 转换为响应。挂载位置决定它能否覆盖下游所有层与 handler:应放在最外层,确保中间件与 handler 的 panic 都被拦截。panic 处理器可以自定义返回内容,但不要把 PanicInfo 里的文件、行号、消息直接返回客户端。若构建 profile 设置了 panic = "abort",unwind 拦截将失效,进程会直接退出。

原理流程

  1. 确认 Cargo.toml 的 profile 未使用 panic = "abort"。
  2. 在路由最外层挂载 catch panic 层。
  3. 配置 panic 处理器:记录消息,返回统一 500 体。
  4. 用测试触发 handler 内 panic,验证返回 500 且进程存活。
  5. 核对日志包含 panic 位置与请求 ID。

代码或图示

use axum::Router;
use tower_http::catch_panic::CatchPanicLayer;

let app = Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    // 处理器签名与可用构造方式以 tower-http 当前版本为准
    .layer(CatchPanicLayer::new());

常见误区

  • 把 catch panic 层挂在鉴权层内侧:内侧 panic 仍可能逃逸到外层。
  • 生产构建用 panic = "abort" 又依赖 panic 拦截:abort 直接终止进程,层内拦截不生效。

追问

  • panic 消息里的 &str/String 如何记录?答:在 panic 处理器中读取 PanicInfo 的 payload 与位置,结构化写入日志;具体 API 以当前版本为准。
  • 除了层拦截还有其他兜底吗?答:可在服务启动层配合任务监控,捕获未处理任务的 panic 并告警;进程级崩溃需靠容器重启策略兜底。

04.4.3.3-015 错误链 source() 如何在日志中展开,而响应体只暴露摘要?

一句话结论

错误类型实现 std::error::Error 的 source 链后,日志层沿链逐层打印根因;响应映射只取顶层 Display 摘要,不展开底层依赖细节。

概念解释

一个业务失败往往经过多层包装:HTTP 错误 → service 错误 → 数据库错误。source() 指针链保留完整因果,Display 只表达当前层语义。日志需要根因定位,因此沿链展开;响应面向调用方,只暴露当前层可理解的消息。thiserror 的 #[source] 与 #[from] 会自动维护这条链,anyhow 则用链式上下文保留回溯。

原理流程

  1. 底层错误变体用 #[source] 持有原始错误。
  2. 上层错误通过 #[from] 或显式包装加入链。
  3. 日志格式化沿 Error::source() 逐层调用 Display。
  4. IntoResponse 只使用顶层 self.to_string() 生成消息。
  5. 底层错误码、SQL、堆栈不出现在响应体中。

代码或图示

use std::error::Error;

#[derive(Debug, thiserror::Error)]
pub enum AppError {
    #[error("查询订单失败")]
    Order(#[source] sqlx::Error),
}

fn walk_source(e: &dyn Error) {
    let mut cur = Some(e);
    while let Some(err) = cur {
        tracing::error!(cause = %err);
        cur = err.source();
    }
}

常见误区

  • 响应体里调用 {:#} 展开整个链:把依赖内部信息泄露给客户端。
  • 只记录顶层错误:根因被包装消息掩盖,线上无法定位数据库或 IO 问题。

追问

  • thiserror 的 #[from] 是否自动设置 source?答:是,#[from] 变体自动把来源错误作为 source,无需手写 source() 方法。
  • anyhow::Error 的链如何查看?答:anyhow::Error 实现 Error,同样可沿 source() 遍历,或用 {:#} 一次打印全部上下文。

04.4.3.3-016 业务错误码枚举如何设计(Code + Message + Status)?

一句话结论

错误码应与 HTTP 状态码解耦:枚举变体同时携带稳定字符串错误码、面向用户的消息模板与映射状态码,错误码按模块分段,便于前端分支处理与日志检索。

概念解释

HTTP 状态码表达协议语义,业务错误码表达具体失败场景,两者不能互相替代。设计上常见三元组:code(机器可读,如 ORDER_NOT_FOUND)、message(可读摘要)、status(HTTP 状态)。错误码一旦对外发布就要保持稳定,不要随重构改名;新增场景追加新码,不复用旧码表达新含义。枚举集中定义比散落字符串字面量更易审查。

原理流程

  1. 按模块划分错误码前缀(如 AUTH_、ORDER_)。
  2. 定义错误枚举变体,每个变体绑定状态码与错误码。
  3. 消息模板支持占位参数,运行期填充。
  4. IntoResponse 从枚举取出三元组组装响应体。
  5. 错误码登记到接口文档,前后端按码分支。

代码或图示

#[derive(Debug, Clone, Copy)]
pub enum ErrorCode {
    AuthUnauthenticated,
    OrderNotFound,
    OrderConflict,
    Internal,
}

impl ErrorCode {
    pub fn as_str(self) -> &'static str {
        match self {
            ErrorCode::AuthUnauthenticated => "AUTH_UNAUTHENTICATED",
            ErrorCode::OrderNotFound => "ORDER_NOT_FOUND",
            ErrorCode::OrderConflict => "ORDER_CONFLICT",
            ErrorCode::Internal => "INTERNAL",
        }
    }
}

常见误区

  • 错误码直接用 HTTP 状态码数字:粒度太粗,前端无法区分同状态码下的不同场景。
  • 错误码随版本频繁改名:已发布接口的调用方会按旧码分支,改名等于破坏契约。

追问

  • 消息要不要后端写死中文?答:错误码稳定,消息可按多语言模板渲染;接口层可只返回码与参数,文案由前端按语言处理。
  • 错误码需要分段编号吗?答:字符串前缀已能分段;数字分段适合老系统迁移,新项目用语义化字符串更易读。

04.4.3.3-017 校验错误如何转成 422 字段级错误?

一句话结论

把 DTO 反序列化与字段校验失败收集成 Vec<FieldError>(字段名 + 消息),在 IntoResponse 中以 422 返回;校验库(如 validator)的错误按字段聚合后再输出。

概念解释

422 响应的价值在于告诉调用方“哪个字段、为什么错”,便于表单逐字段提示。流程上分两层:JSON 报文解析失败属于格式错误,字段规则校验失败属于语义错误。字段级错误通常包含 field、message,可选 rejected_value。axum 的 Json 提取器失败默认只给笼统拒绝,需要在 handler 边界捕获校验结果,组装成自己的字段错误列表。

原理流程

  1. DTO 派生 Deserialize 与校验库的校验属性。
  2. 解析成功后调用校验方法,收集字段错误。
  3. 校验库返回的错误按字段名分组,翻译成可读消息。
  4. 组装 ErrorBody { fields },映射 422。
  5. 响应体字段列表供前端定位表单控件。

代码或图示

use serde::Deserialize;

#[derive(Deserialize)]
struct CreateUser {
    email: String,
    age: i32,
}

#[derive(serde::Serialize)]
struct FieldError { field: String, message: String }

fn validate(u: &CreateUser) -> Vec<FieldError> {
    let mut errs = Vec::new();
    if !u.email.contains('@') {
        errs.push(FieldError { field: "email".into(), message: "邮箱格式不正确".into() });
    }
    if u.age < 18 {
        errs.push(FieldError { field: "age".into(), message: "年龄须满 18 岁".into() });
    }
    errs
}

常见误区

  • 把所有校验失败合并成一条消息:前端无法定位具体字段。
  • 在校验通过前访问可能非法的字段:应先完成解析与校验,再进入业务逻辑。

追问

  • 嵌套对象的字段路径怎么表达?答:用点号路径(如 address.city)作为 field 字符串,保持与 JSON 结构一致。
  • 校验库错误消息如何本地化?答:在聚合层把校验规则码映射为对应语言模板,不直接暴露库内部消息。

04.4.3.3-018 数据库错误(sqlx::Error)如何分类映射?

一句话结论

在应用边界把 sqlx::Error 区分为未找到、唯一约束冲突、外键冲突、连接/查询故障等类别,分别映射 404、409、422 与 500;原始错误进入日志,不进响应体。

概念解释

数据库错误是服务端依赖错误,但其中部分是调用方数据导致的可预期冲突。sqlx 的错误类型区分 RowNotFound、Database(携带数据库错误码)等变体;应用层需要先匹配这些变体,再把数据库原始错误码翻译成业务错误。映射规则集中在一个转换函数里,避免每个 repository 重复判断。具体变体名与错误码字段以 sqlx 当前版本为准。

原理流程

  1. repository 层返回 sqlx::Error 或包装后的领域错误。
  2. 边界转换函数匹配 sqlx::Error 变体:未找到、数据库错误、其他。
  3. 数据库错误按驱动返回的错误码判断唯一冲突、外键冲突。
  4. 分别映射为 NotFound、Conflict、Validation、Internal。
  5. 原始错误作为 source 保留进日志。

代码或图示

fn map_db_error(e: sqlx::Error) -> AppError {
    match &e {
        sqlx::Error::RowNotFound => AppError::NotFound,
        sqlx::Error::Database(db) => match db.code().map(|c| c.as_ref()) {
            Some("23505") => AppError::Conflict("唯一约束冲突".into()),
            Some("23503") => AppError::Validation("关联记录不存在".into()),
            _ => AppError::Internal,
        },
        _ => AppError::Internal,
    }
}

常见误区

  • 把所有数据库错误都映射 500:唯一冲突本应是 409,前端无法据此提示“已存在”。
  • 在响应体里回传数据库错误码与 SQL:泄露表结构与查询细节。

追问

  • RowNotFound 与查询返回空集合怎么区分?答:RowNotFound 由 fetch_one 等要求单行的方法产生;fetch_optional 返回 Option,空集合走业务判断,不抛错误。
  • 错误码 23505 属于哪种数据库?答:示例为 PostgreSQL 的唯一约束违反码;MySQL 等驱动的错误码取值不同,需按所用数据库核对。

04.4.3.3-019 错误响应的 Content-Type 与序列化格式怎么选?

一句话结论

JSON 接口统一返回 application/json(或 Problem Details 的 application/problem+json),错误体结构与成功响应保持同一序列化约定;纯文本兜底只用于序列化自身失败的极端情况。

概念解释

响应格式由接口契约决定:成功响应是 JSON,错误响应也应是 JSON,避免前端解析分支混乱。Content-Type 必须与 body 实际格式一致,否则浏览器或客户端解析器可能拒绝。错误结构体同样派生 Serialize,字段命名风格(snake_case 或 camelCase)与成功 DTO 保持一致。只有当错误体序列化本身失败时,才兜底返回纯文本 500。

原理流程

  1. 定义与成功 DTO 同风格的错误体结构体。
  2. IntoResponse 用 Json(body) 序列化,默认带 JSON Content-Type。
  3. 使用 Problem Details 时显式覆盖为 application/problem+json。
  4. 序列化失败兜底为文本响应,避免二次错误。
  5. 接口文档写明错误响应结构。

代码或图示

use axum::response::Json;
use serde::Serialize;

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct ErrorBody { error_code: String, message: String }

impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        (axum::http::StatusCode::BAD_REQUEST, Json(ErrorBody {
            error_code: self.code().into(), message: self.to_string(),
        })).into_response()
    }
}

常见误区

  • 成功返回 JSON、错误返回纯文本字符串:前端统一解析 JSON 时会在错误分支崩溃。
  • 错误体字段命名风格与成功接口不一致:增加前端适配成本。

追问

  • 能否返回 XML 错误体?答:可以,但需与接口整体契约一致;JSON 是 axum 项目最常见的选择。
  • Json 序列化失败怎么办?答:在实现内 match 序列化结果,失败时返回固定纯文本 500,不要再走 Json。

04.4.3.3-020 如何在中间件层把下游错误统一包装?

一句话结论

在 tower 层链外层包裹 handler 响应,统一补充请求 ID、日志与错误体规范化;但错误分类(4xx/5xx)应在进入中间件前由具体错误类型完成,中间件只做横切增强。

概念解释

中间件适合做与业务无关的横切工作:记录请求耗时、补充响应头、按状态码汇总日志。错误的语义分类依赖具体错误类型,放在 handler 边界更合适。若在中间件里重新解析响应体来判断错误,会重复消费 body,实现复杂且容易出错。常见做法是内层产出标准错误响应,外层中间件只读取状态码与扩展信息做增强。

原理流程

  1. 路由内层 handler 返回已分类的 AppError 响应。
  2. 外层中间件调用 next.run(req).await 拿到响应。
  3. 读取状态码,按 4xx/5xx 记录日志级别。
  4. 补充 x-request-id 等响应头。
  5. 不重写 body,避免重复消费。

代码或图示

async fn log_middleware(req: axum::extract::Request,
    next: axum::middleware::Next) -> axum::response::Response {
    let start = std::time::Instant::now();
    let resp = next.run(req).await;
    let status = resp.status();
    if status.is_server_error() {
        tracing::error!(%status, elapsed = ?start.elapsed(), "server error");
    } else if status.is_client_error() {
        tracing::warn!(%status, elapsed = ?start.elapsed(), "client error");
    }
    resp
}

常见误区

  • 在中间件里读取并重建 body 来包装错误:body 只能消费一次,重建需要缓冲整个响应,增加内存占用。
  • 把错误分类逻辑下沉到通用中间件:中间件看不到业务错误类型,只能猜状态码。

追问

  • 中间件顺序对错误处理有什么影响?答:外层中间件先看到进入请求、后看到返回响应;catch panic、日志等横切层应位于外层,业务鉴权与提取在内部。
  • 如何在中间件访问错误枚举类型?答:通过请求扩展或响应扩展传递,不要反序列化 body;具体做法以项目状态设计为准。

04.4.3.3-021 为什么不建议把内部错误详情直接返回给客户端?

一句话结论

内部详情(SQL、堆栈、文件路径、依赖版本)会帮助攻击者推断系统结构,且对调用方无业务价值;响应只暴露必要的错误码与摘要,详细信息进服务端日志。

概念解释

错误响应是对外接口的一部分。原始错误常包含表名、列名、查询条件、框架版本、本地路径等敏感信息,泄露后可被用于构造注入或定向攻击。安全原则是“对外最小披露”:客户端拿到可理解的失败原因与排查 ID 即可,根因分析在服务端完成。同时内部错误详情也不稳定,随版本变动,不应成为接口契约的一部分。

原理流程

  1. 区分面向调用方的消息与内部诊断信息。
  2. 响应体只放错误码、摘要、请求 ID。
  3. 内部错误链、堆栈、SQL 写入服务端日志。
  4. 错误枚举的 Display 面向用户,Debug 与 source 面向日志。
  5. 上线前审计错误响应样例,确认无敏感字段。

代码或图示

impl AppError {
    fn public_message(&self) -> String {
        match self {
            AppError::Internal => "服务暂时不可用,请稍后重试".into(),
            other => other.to_string(),
        }
    }
}

常见误区

  • 调试阶段习惯直接 self.to_string() 返回底层错误,上线前未清理:遗留信息泄露路径。
  • 把堆栈字符串塞进响应体:既泄露内部结构,又增大响应体积。

追问

  • 内部错误需要给调用方排查入口吗?答:给请求 ID 或追踪 ID,调用方凭此联系运维,而不是直接暴露堆栈。
  • 日志脱敏怎么做?答:记录前对手机号、邮箱、证件号、密钥等字段做掩码;不要把完整请求体写入 error 日志。

04.4.3.3-022 IntoResponse 与提取器拒绝的错误路径有何不同?

一句话结论

提取器拒绝发生在参数构造阶段(请求进入 handler 之前),返回 Rejection;IntoResponse 发生在 handler 返回之后;两者都要映射成响应,但触发时机、可用上下文与错误类型不同。

概念解释

一条请求的错误路径分两段:先经过提取器绑定路径参数、查询参数、body 等,任一提取器失败即短路;再执行 handler 业务逻辑,返回 Result 由响应层转换。提取器拒绝偏“报文与绑定”问题,业务错误偏“规则与依赖”问题。设计上两类错误可统一到同一错误体,但区分错误码前缀,便于定位是输入绑定还是业务规则失败。

原理流程

  1. 请求到达,适配器按参数顺序调用提取器。
  2. 提取器失败 → 返回 Rejection,短路并转响应。
  3. 全部提取成功 → 执行 handler。
  4. handler 返回 Result<T, AppError> → IntoResponse 转响应。
  5. 两类响应经统一错误体格式输出。

代码或图示

async fn create(
    Path(id): axum::extract::Path<u64>,        // 提取器拒绝在此短路
    Json(body): axum::extract::Json<CreateUser>, // body 只能放最后
) -> Result<Json<Item>, AppError> {
    // 业务错误由 AppError 经 IntoResponse 映射
    Ok(Json(Item { id }))
}

常见误区

  • 在 handler 内部再手动解析路径参数:提取器已经完成绑定,重复解析属于冗余。
  • 把业务校验错误伪装成提取器拒绝:提取器只负责请求绑定,业务规则应在 handler 内返回业务错误。

追问

  • 提取器拒绝能否复用 AppError?答:可以,在自定义提取器的拒绝类型上实现 IntoResponse,或在内置 rejection 到 AppError 之间做转换。
  • 两类错误的状态码如何分工?答:绑定失败常用 400/415/422,业务失败按场景选 404/409/403 等。

04.4.3.3-023 如何为 Result<Success, AppError> 提供便捷别名?

一句话结论

用类型别名 type AppResult<T> = Result<T, AppError> 统一 handler 与 service 的返回签名,减少重复泛型书写,并让未来替换错误类型只改一处。

概念解释

项目内所有 HTTP handler 与 service 函数共享同一错误类型时,类型别名能保持签名一致、减少拼写漂移。别名不是新类型,不增加 trait 实现负担;AppError 实现 IntoResponse 后,AppResult<T> 可直接作为 handler 返回类型。若后续需要在 service 层使用 anyhow::Result,可再定义内部别名,与 HTTP 边界别名分开。

原理流程

  1. 定义 AppError 并实现 IntoResponse。
  2. 定义 pub type AppResult<T> = Result<T, AppError>。
  3. handler 与 service 签名统一使用 AppResult<T>。
  4. 业务函数内用 ? 传播错误。
  5. 错误类型演进时只调整 AppError 与别名定义。

代码或图示

pub type AppResult<T> = Result<T, AppError>;

async fn get_item(id: u64) -> AppResult<Item> {
    let item = repo::find(id).await?.ok_or(AppError::NotFound)?;
    Ok(item)
}

async fn handler(Path(id): axum::extract::Path<u64>) -> AppResult<axum::Json<Item>> {
    Ok(axum::Json(get_item(id).await?))
}

常见误区

  • 为每个模块定义不同错误别名:错误类型分散后响应映射难以统一。
  • 把别名定义成新结构体类型:包装类型需要额外解包与 trait 实现,徒增成本。

追问

  • service 层能否也用 AppResult?答:可以;若 service 需要跨模块汇总多种错误,可内部用 anyhow::Result,到 HTTP 边界再转 AppError。
  • 别名会影响 ? 的错误转换吗?答:不会,? 仍按 From 转换;需要为依赖错误实现 From 才能直接 ?。

04.4.3.3-024 错误测试如何断言状态码与响应体?

一句话结论

用 axum 测试客户端发起请求,断言响应状态码,再解析 body 为错误结构体,校验错误码与字段明细;分类映射函数可单独做单元测试。

概念解释

错误处理最容易在重构时被改坏:状态码漂移、错误码改名、字段遗漏都需要测试兜底。测试分两层:映射函数单测直接喂入错误变体断言状态码与错误码;接口测试通过本地客户端发起请求,断言完整响应。解析 JSON body 时要处理读取与反序列化错误,避免测试本身被忽略的失败掩盖。

原理流程

  1. 构造应用路由,挂测试客户端。
  2. 调用对应接口触发目标错误场景。
  3. 断言 StatusCode 符合预期。
  4. 读取 body 并反序列化为错误体,断言 code 与字段列表。
  5. 对映射函数补充纯单元测试,覆盖所有变体。

代码或图示

use axum::body::Body;
use axum::http::StatusCode;
use tower::ServiceExt; // 提供 oneshot

# async fn test() {
# let app = axum::Router::new().route("/items/{id}", axum::routing::get(get_item));
let resp = app.oneshot(
    axum::http::Request::get("/items/999")).await.unwrap();
assert_eq!(resp.status(), StatusCode::NOT_FOUND);
let body = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
let err: ErrorBody = serde_json::from_slice(&body).unwrap();
assert_eq!(err.code, "ORDER_NOT_FOUND");
# }

常见误区

  • 只断言状态码不断言错误码:同状态码下错误语义漂移无法被发现。
  • 测试里用真实数据库触发错误:应依赖 repository 替身或固定数据,保证错误场景稳定可复现。

追问

  • 测试客户端如何构造?答:axum 测试常用 tower::ServiceExt::oneshot 直接对路由发请求;异步客户端工具的具体类型以当前版本与依赖为准。
  • 如何断言 422 的字段列表?答:反序列化后比对 fields 数组的字段名集合与消息,避免顺序敏感断言。

04.4.3.3-025 错误跨边界时如何保留上下文(context 方法)?

一句话结论

在跨层调用点用 .context(...) 给底层错误补充场景信息,形成可回溯的错误链;进入 HTTP 边界时再映射为对外错误码,上下文只留在日志中。

概念解释

底层错误只知道“查询失败”,上层才知道“是加载哪个订单失败”。anyhow::Error::context 在不丢失原错误的前提下追加一层描述;thiserror 变体也可通过消息模板携带参数。上下文沿错误链向上累积,日志展开时能看到完整因果;对外响应只取当前层摘要,避免把内部路径与参数暴露出去。

原理流程

  1. 底层函数返回具体错误或 anyhow::Error。
  2. 上层调用点用 .context("加载订单 {id} 失败") 追加场景。
  3. 错误链在边界被捕获,记录完整链。
  4. 映射为 AppError 变体,生成对外摘要。
  5. 响应体只含摘要与请求 ID。

代码或图示

use anyhow::{Context, Result};

async fn load_order(id: u64) -> Result<Order> {
    repo::find_order(id)
        .await
        .with_context(|| format!("查询订单 {id} 失败"))?;
    Ok(Order { id })
}

常见误区

  • 在底层库到处加业务上下文:上下文应在了解业务语义的上层添加,底层保持通用描述。
  • 追加上下文时丢弃原始错误:必须用带 source 的包装,不能只返回新的字符串错误。

追问

  • context 与 map_err 怎么选?答:context 适合 anyhow 链追加描述;map_err 适合把具体错误转成另一个具体错误类型。
  • 上下文里能放请求参数吗?答:可以放必要的定位参数,但敏感值(密码、完整证件号)应脱敏后再进入错误消息。

04.4.3.3-026 SSE 在 axum 中由哪些类型支撑?

一句话结论

axum 的 SSE 能力位于 axum::response::sse 模块,核心类型是 Sse(响应包装)、Event(单个事件)与 KeepAlive(保活配置),事件流由实现 Stream 的异步序列提供。

概念解释

Server-Sent Events 是服务端单向推送的 HTTP 长连接,浏览器通过 EventSource 接收。axum 把 SSE 建模为一个普通响应:body 是持续产生事件的流,Content-Type 为 text/event-stream。Sse 包装流并配置保活,Event 对应协议里的一条消息(含 data、event、id、retry 字段)。底层流通常来自 tokio::sync::mpsc 或 broadcast 的接收端包装。

原理流程

  1. handler 返回 Sse<impl Stream<Item = Result<Event, E>>>。
  2. Sse::new(stream) 把流包装为响应。
  3. 可选 keep_alive(KeepAlive::default()) 配置心跳间隔。
  4. 框架以 text/event-stream 写出事件序列。
  5. 流结束或客户端断连后任务退出。

代码或图示

use axum::response::sse::{Sse, Event, KeepAlive};
use futures::stream::StreamExt;
use std::time::Duration;

async fn tick() -> Sse<impl futures::stream::Stream<Item = Result<Event, std::convert::Infallible>>> {
    let stream = futures::stream::interval(Duration::from_secs(1))
        .map(|_| Ok(Event::default().data("ping")));
    Sse::new(stream).keep_alive(KeepAlive::default())
}

常见误区

  • 把 SSE 当成双向通道:SSE 只能服务端到客户端,客户端回传要走普通 POST 或改用 WebSocket。
  • 以为 axum 内置事件存储与重连状态:Last-Event-ID 的处理需要业务自行实现。

追问

  • Sse 对流的错误类型有什么要求?答:流元素为 Result<Event, E>,错误类型需可转成响应错误;常用 Infallible 或实现 IntoResponse 的类型,具体约束以当前版本文档为准。
  • SSE 底层基于什么协议?答:基于标准 HTTP 长连接,不需要协议升级,浏览器 EventSource 原生支持。

04.4.3.3-027 如何返回一个 SSE 事件流响应?

一句话结论

handler 返回 Sse::new(stream),流中逐项产出 Result<Event, _>;事件数据通过 Event::default().data(...) 构造,框架负责按 SSE 协议格式化写出。

概念解释

SSE 响应的关键是把异步数据源接成一个 Stream。数据源可以是定时器、通道接收端、数据库通知订阅等。Event 的 data 字段是消息体,多行数据需要按协议换行处理。handler 本身保持轻量,只负责组装流;真正的事件生产在流内部完成。返回类型用 impl Stream 隐藏具体流类型,便于后续替换数据源。

原理流程

  1. 建立事件数据源(通道、定时器或订阅流)。
  2. 用 StreamExt::map 把数据项转成 Event。
  3. 包装为 Sse::new(stream),按需配置保活。
  4. handler 返回该响应,axum 设置 text/event-stream。
  5. 流结束时响应自然关闭。

代码或图示

use axum::response::sse::{Sse, Event};
use futures::stream::{self, StreamExt};
use tokio::sync::mpsc;

async fn events() -> Sse<impl StreamExt<Item = Result<Event, std::convert::Infallible>>> {
    let (tx, rx) = mpsc::channel::<String>(16);
    // 实际项目中 tx 由其他任务持有并推送
    let stream = stream::wrapping_channel(rx).map(|msg| Ok(Event::default().data(msg)));
    Sse::new(stream)
}

常见误区

  • 在 handler 里阻塞等待所有事件再返回:SSE 必须边产生边写出,不能缓冲完整结果。
  • 直接返回裸 Vec<Event>:一次性响应不是事件流,客户端收不到持续推送。

追问

  • 流元素为什么包一层 Result?答:协议写出过程中可能发生错误,Result 允许流内上报失败并结束响应;具体错误处理以 axum 当前版本为准。
  • 如何给事件命名类型?答:Event::default().event("message_type"),前端 addEventListener 按类型监听。

04.4.3.3-028 Event 事件如何构造(data/event/id/retry)?

一句话结论

Event 提供 data、event、id、retry 方法填充对应 SSE 字段;data 可多次调用追加多行,id 用于断线重连标识,retry 建议重连毫秒数。

概念解释

SSE 协议每条事件由若干字段行组成:data: 消息体、event: 自定义事件名、id: 事件标识、retry: 重连等待毫秒。axum 的 Event 构建器对应这些字段。id 配合 Last-Event-ID 头实现断点续传;event 缺省时前端按默认 message 事件接收。多行 data 在协议中以多个 data: 行发送,读取时按规则拼接。

原理流程

  1. 调用 Event::default() 建立空事件。
  2. 用 .data(...) 写入消息体,必要时多次调用追加行。
  3. 可选 .event("order_update") 命名事件。
  4. 可选 .id(...) 写入事件 ID,.retry(...) 写入重连间隔。
  5. 事件进入流,由 Sse 按协议格式化。

代码或图示

use axum::response::sse::Event;

let event = Event::default()
    .event("order_update")
    .id("evt-1024")
    .retry(3000)
    .data(r#"{"order_id":1024,"status":"paid"}"#);

常见误区

  • data 里直接放含换行的原始文本:需要确认多行数据的协议拼接行为,避免前端收到拆分后的残缺消息。
  • 给每个事件都设全局唯一 id 却不处理重连:ID 只有配合 Last-Event-ID 才有续传意义。

追问

  • 前端如何区分事件类型?答:EventSource 默认监听 message;命名事件用 addEventListener("order_update", handler)。
  • retry 单位是什么?答:毫秒,影响浏览器下次重连前的等待时间。

04.4.3.3-029 KeepAlive 的作用与配置项有哪些?

一句话结论

KeepAlive 周期性发送注释帧或心跳事件,防止中间代理因空闲超时断开长连接;可配置间隔、发送的事件与注释内容,具体字段以 axum 当前版本为准。

概念解释

SSE 长连接在无消息时段可能被 Nginx、负载均衡或浏览器判定空闲而关闭。KeepAlive 在流空闲时定期写入心跳帧(SSE 协议注释行),保持连接活跃。配置项通常包括心跳间隔与心跳内容;业务心跳也可以由自己的流定时产出。若后端事件推送本来就频繁,保活间隔可适当放大,避免无谓流量。

原理流程

  1. Sse::new(stream).keep_alive(KeepAlive::default()) 启用保活。
  2. 框架按配置间隔检查流是否有新事件。
  3. 空闲时写入心跳帧,刷新代理空闲计时。
  4. 有业务事件时正常发送事件。
  5. 流结束后保活停止。

代码或图示

use axum::response::sse::{Sse, KeepAlive};
use std::time::Duration;

# let stream = futures::stream::empty();
let sse = Sse::new(stream)
    .keep_alive(KeepAlive::new().interval(Duration::from_secs(15)));

常见误区

  • 以为 KeepAlive 就是应用层 ping/pong:它是 HTTP 层保活注释帧,不等同于双向心跳;WebSocket 的心跳是帧协议层面的。
  • 保活间隔短于代理空闲超时:心跳来不及刷新连接就被关闭;应按网关与 LB 配置取更短间隔。

追问

  • KeepAlive 发送的内容前端能收到吗?答:注释行不触发 EventSource 消息回调;如需业务心跳事件,在流里显式产出 Event。
  • 默认间隔是多少?答:以 axum 当前版本 KeepAlive::default() 实现为准,不要凭记忆写死数值。

04.4.3.3-030 SSE 流如何处理背压?

一句话结论

SSE 基于 Rust 异步流的 poll 机制天然传递背压:下游消费慢时流的生产端被暂停,通道容量满后发送端异步等待;业务侧要控制通道容量与推送速率,避免内存堆积。

概念解释

背压指下游处理能力不足时,上游应减速而不是无限缓冲。axum 写出事件时按流的 poll 节奏推进,通道接收端消费慢会反压到发送端。mpsc 有界队列满后 send 等待,broadcast 满后按策略覆盖或报错。设计时要明确:慢客户端是排队等待、丢弃旧事件还是断开连接,不同策略对应不同通道选择。

原理流程

  1. 事件生产端写入有界通道。
  2. 通道容量满时,发送端 await 等待腾出空间。
  3. SSE 流从通道接收事件并写出。
  4. 下游写出慢 → 接收端 poll 不推进 → 通道积压 → 反压生产端。
  5. 按业务策略选择等待、丢旧或断连。

代码或图示

use tokio::sync::mpsc;

# async fn produce(tx: mpsc::Sender<String>) {
// 有界通道:满了之后 send 会等待,形成背压
match tx.try_send("event".into()) {
    Ok(()) => {}
    Err(mpsc::error::TrySendError::Full(_)) => {
        // 容量满:可丢弃旧事件或断开该订阅
    }
    Err(mpsc::error::TrySendError::Closed(_)) => break,
}
# }

常见误区

  • 用无界通道缓冲所有事件:客户端慢时内存持续上涨,失去背压保护。
  • 发送端不处理满与关闭错误:订阅已断开仍继续推送,造成任务泄漏与无效占用。

追问

  • broadcast 与 mpsc 在背压上有何差异?答:broadcast 面向多订阅者,容量满时新订阅者按配置追赶或落后;mpsc 单消费者满后发送方等待。具体行为以 tokio 当前版本为准。
  • 慢客户端可以直接断开吗?答:可以按策略超时未消费即关闭连接,但要记录指标,避免误杀弱网用户。

04.4.3.3-031 客户端断连后服务端如何感知并清理资源?

一句话结论

客户端断开后,写出事件时会得到错误或流被取消;服务端应在流任务退出时释放订阅注册、关闭通道与房间引用,并在 Drop 或任务结束分支执行清理。

概念解释

SSE 连接断开可能由用户关闭页面、网络中断或代理超时引起。服务端感知途径包括:发送失败、流被 tokio 取消(任务被 abort)、通道接收端关闭。资源清理要点是订阅者从房间注册表移除、通知其他成员、释放通道。仅依赖任务退出而不显式注销,会导致注册表残留“僵尸订阅”,后续广播持续向死连接写入。

原理流程

  1. 订阅建立时把发送端注册到房间/连接表。
  2. 客户端断连 → 流任务被取消或写出失败。
  3. 任务退出分支从注册表移除连接。
  4. 关闭相关通道,释放房间引用。
  5. 记录断连指标,避免重复注销。

代码或图示

use axum::response::sse::Sse;
use futures::stream::StreamExt;

# struct Room;
# impl Room { fn unsub(&self, id: u64) {} }
async fn handler(axum::State(room): axum::State<Room>,
    axum::extract::Path(conn_id): axum::extract::Path<u64>) -> Sse<impl futures::stream::Stream<Item = Result<axum::response::sse::Event, std::convert::Infallible>>> {
    // 流结束(含断连)时执行清理
    let stream = /* 通道接收端 */ futures::stream::empty()
        .chain(futures::stream::once(async move {
            room.unsub(conn_id);
            Ok(axum::response::sse::Event::default())
        }));
    Sse::new(stream)
}

常见误区

  • 把清理写在 Drop 里却持有跨任务引用:析构时机不确定,注册表可能长期不释放。
  • 断连后不关闭发送端:通道与订阅对象被持有在全局表中,形成内存泄漏。

追问

  • 如何检测 EventSource 主动关闭?答:服务端侧表现为写出失败或流取消;浏览器刷新/关闭会触发 TCP 关闭或空闲超时。
  • 清理逻辑如何保证幂等?答:注销按连接 ID 从表中移除,重复移除不报错;用 Entry 或状态标记防止二次清理。

04.4.3.3-032 SSE 与 WebSocket 的适用场景如何区分?

一句话结论

单向服务端推送(通知、行情、日志流)优先 SSE;需要双向低延迟通信(聊天、协作编辑、实时控制)用 WebSocket;SSE 复用 HTTP 语义与重连机制,WebSocket 是独立帧协议。

概念解释

选型先看通信方向:SSE 只能服务端推、客户端通过普通 HTTP 请求回传;WebSocket 全双工,双方随时发帧。连接模型上 SSE 是普通 HTTP 响应,易穿过现有 HTTP 基础设施,自带断线重连与 Last-Event-ID;WebSocket 需要升级握手,连接管理与心跳要自己实现。浏览器端 SSE 由 EventSource 原生支持,WebSocket 由 WebSocket API 支持。

原理流程

  1. 判断交互方向:单向推送还是双向对话。
  2. 判断是否依赖 HTTP 认证、代理与重连语义。
  3. 单向、文本事件为主 → SSE。
  4. 双向、二进制或高频交互 → WebSocket。
  5. 混合场景可 SSE 推送加普通 POST 上行。

代码或图示

场景对比
├── 通知中心、消息提醒:SSE
├── 实时日志/监控流:SSE
├── 行情逐笔推送:SSE(单向)或 WebSocket(需订阅交互)
├── 聊天室、协同编辑:WebSocket
├── 实时游戏控制、音视频信令:WebSocket

常见误区

  • 用 WebSocket 只做单向推送:增加心跳、断线重连与连接管理成本,收益不抵复杂度。
  • 以为 SSE 能传二进制:SSE 文本协议为主,二进制需 Base64 编码;大二进制交互选 WebSocket。

追问

  • SSE 受连接数限制吗?答:浏览器对同域 EventSource 连接数有上限约束,具体数值以浏览器当前实现为准;大规模推送需考虑连接分流。
  • 两者都能穿过 HTTP 代理吗?答:SSE 作为普通长连接更易兼容;WebSocket 升级帧要求代理正确处理 Upgrade 头。

04.4.3.3-033 SSE 如何携带认证信息?

一句话结论

浏览器 EventSource 不能自定义请求头,认证信息通常通过查询参数或 Cookie 携带;服务端在订阅建立前用提取器或守卫校验,失败则返回 401 响应。

概念解释

EventSource API 不支持设置 Authorization 头,这是 SSE 落地常见约束。可选方案:依赖 Cookie 自动携带,或在 URL 查询参数中携带短期令牌。查询参数会出现在访问日志与历史记录中,应使用短命、单次有效的订阅令牌,而不是长期 JWT。校验在路由层完成:未认证请求返回普通 401,不进入事件流。

原理流程

  1. 前端先获取短期订阅令牌(经认证接口换取)。
  2. 用 EventSource("/events?token=...") 建立连接。
  3. 路由提取器解析令牌并校验身份。
  4. 校验失败返回 401 响应;成功后注册订阅。
  5. 令牌过期后重连时重新换取。

代码或图示

# struct AuthUser { id: u64 }
async fn events(
    axum::extract::Query(params): axum::extract::Query<TokenQuery>,
) -> Result<axum::response::sse::Sse<impl futures::stream::Stream<Item = Result<axum::response::sse::Event, std::convert::Infallible>>>, AppError> {
    let _user = verify_token(&params.token).await?;
    // 返回事件流……
    Err(AppError::NotFound)
}

#[derive(serde::Deserialize)]
struct TokenQuery { token: String }

常见误区

  • 在 SSE URL 里放长期登录凭证:令牌进入日志、代理缓存与浏览器历史,泄露风险高。
  • 认证校验放在事件流内部首条消息之后:未认证连接已占用资源,应在握手阶段拒绝。

追问

  • Cookie 方案有什么前提?答:前后端同域或 Cookie 配置允许跨域携带,且 EventSource 可带凭据(具体 API 参数以浏览器文档为准)。
  • WebSocket 如何携带认证?答:升级请求可带 Authorization 头,也可在连接建立后首条消息鉴权;axum 中在升级前校验更安全。

04.4.3.3-034 事件流内部如何与共享状态(State/Channel)结合?

一句话结论

全局状态通过 State<AppState> 提取器注入 handler,事件生产端持有通道或订阅注册表的克隆句柄;流任务与共享状态通过 Arc 内的通道句柄协作,连接表放在 AppState 中。

概念解释

SSE 服务要把新事件推送给所有在线订阅者,需要一个全局可访问的订阅注册表。AppState 通常包含 Arc<tokio::sync::broadcast::Sender> 或按房间维护的连接表。handler 从 State 取到发送端克隆,建立本地接收端并注册到房间。状态共享的并发安全由通道与锁保证,handler 不直接持有可变全局集合的裸引用。

原理流程

  1. 定义 AppState,内含广播发送端或房间注册表句柄。
  2. 启动时初始化状态,Router::with_state 注入。
  3. 新连接克隆发送端,生成接收端并注册。
  4. 业务任务向发送端广播,各 SSE 流接收并推送。
  5. 断连时从注册表注销。

代码或图示

use axum::Router;
use tokio::sync::broadcast;
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    bus: broadcast::Sender<String>,
}

let bus = broadcast::channel::<String>(64).0;
let app = Router::new()
    .route("/events", axum::routing::get(events))
    .with_state(AppState { bus });

async fn events(axum::State(state): axum::State<AppState>)
    -> axum::response::sse::Sse<impl futures::stream::Stream<Item = Result<axum::response::sse::Event, std::convert::Infallible>>> {
    let rx = state.bus.subscribe();
    let stream = futures::stream::unfold(rx, |mut rx| async move {
        rx.recv().await.ok().map(|msg| (Ok(axum::response::sse::Event::default().data(msg)), rx))
    });
    axum::response::sse::Sse::new(stream)
}

常见误区

  • 在 handler 里新建独立通道:新连接收不到其他任务推送的事件,必须订阅全局总线。
  • 直接把 broadcast::Sender 存进非克隆状态:State 要求可克隆且跨 handler 共享,句柄应放在 Arc 或可克隆结构内。

追问

  • broadcast::Sender 克隆开销大吗?答:克隆只是增加发送端引用,廉价;真正的共享数据在内部。
  • 多房间怎么组织?答:AppState 内维护 HashMap<RoomId, Sender>,按房间订阅与注销;并发访问用锁或任务模型保护。

04.4.3.3-035 SSE 断线重连与 Last-Event-ID 怎么处理?

一句话结论

浏览器断线后自动重连,并在请求头携带上次收到的事件 id;服务端读取该头,从对应位置补发积压事件;事件 ID 需要可回溯(日志、队列或持久化存储)。

概念解释

EventSource 内置重连:连接断开后按 retry 间隔重试,重连请求带 Last-Event-ID 头。服务端要实现断点续传,必须能根据 ID 找到历史事件。轻量方案是内存环形缓冲保留近期事件;严格不丢消息需要持久化队列或日志存储。无法回溯时,重连后只能推送最新状态,不能声称消息不丢。

原理流程

  1. 服务端为每个事件生成单调递增 ID 并写入 Event::id。
  2. 客户端断线重连,请求带 Last-Event-ID。
  3. 提取器读取该头,定位历史事件位置。
  4. 补发 ID 之后的事件,再接入实时流。
  5. 无历史可补发时直接推送后续事件。

代码或图示

async fn events(
    axum::extract::TypedHeader(headers): axum::extract::TypedHeader(
        axum::http::header::HeaderMap),
) -> impl axum::response::IntoResponse {
    let last_id = headers.get("last-event-id")
        .and_then(|v| v.to_str().ok())
        .map(|s| s.to_string());
    // 根据 last_id 从缓冲或存储补发事件……
    let _ = last_id;
    axum::response::sse::Sse::new(futures::stream::empty())
}

常见误区

  • 发了事件 ID 却从不读 Last-Event-ID:重连后前端重复或跳过事件,状态不一致。
  • 用时间戳作 ID 却假设全局单调:多实例下时钟不同步,ID 可能回退。

追问

  • 历史事件保留多久?答:按业务容忍度配置环形缓冲长度;超过窗口的事件无法补发,应告知客户端刷新全量状态。
  • 重连频率如何控制?答:retry 字段建议间隔;服务端可对频繁重连的连接限流,防止重连风暴。

04.4.3.3-036 多个订阅者如何通过广播通道推送事件?

一句话结论

用 tokio::sync::broadcast::channel 建立多生产者多消费者总线,每个 SSE 连接 subscribe() 得到独立接收端;业务任务向 Sender 广播,订阅流各自接收并写出。

概念解释

广播模型天然对应“一条消息推给所有在线连接”。broadcast 允许多个接收端各自持有独立队列,发送一次即被所有订阅者收到。新订阅者从当前最新消息开始;落后过多按容量策略处理。相比给每个连接单独 mpsc 再遍历发送,广播通道省去服务端维护发送端列表的遍历逻辑;房间隔离则按主题拆分多个广播实例。

原理流程

  1. 启动时创建 broadcast::channel,容量按并发订阅数配置。
  2. 新连接调用 subscribe() 生成 rx。
  3. SSE 流 unfold 或 map 包装 rx.recv()。
  4. 业务侧 bus.send(msg) 广播,各接收端收到同一消息。
  5. 断连后接收端丢弃,注册表无需额外清理(无状态订阅时)。

代码或图示

use tokio::sync::broadcast;

# let (tx, _rx) = broadcast::channel::<String>(64);
async fn subscribe(tx: broadcast::Sender<String>)
    -> axum::response::sse::Sse<impl futures::stream::Stream<Item = Result<axum::response::sse::Event, std::convert::Infallible>>> {
    let rx = tx.subscribe();
    let stream = futures::stream::unfold(rx, |mut rx| async move {
        match rx.recv().await {
            Ok(msg) => Some((Ok(axum::response::sse::Event::default().data(msg)), rx)),
            Err(_) => None,
        }
    });
    axum::response::sse::Sse::new(stream)
}

常见误区

  • 用 mpsc 做全局总线:只有一个消费者,其他连接收不到广播。
  • 订阅后不处理 Lagged 错误:订阅者落后过多会丢消息,应记录指标并决定是否补发全量。

追问

  • 广播容量如何估算?答:按单订阅者峰值缓冲消息数与并发订阅规模估算;容量过小易触发落后,过大占内存。
  • 多房间怎么广播?答:维护 HashMap<RoomId, broadcast::Sender>,进入房间订阅对应总线,离开时丢弃接收端。

04.4.3.3-037 SSE handler 里能否做阻塞调用?

一句话结论

不能在异步 SSE 任务里直接做阻塞 IO 或 CPU 密集计算;阻塞操作会卡住异步执行器,影响其他连接的推送。阻塞任务必须交给 spawn_blocking,异步流内只做等待与转发。

概念解释

axum 运行在 Tokio 多线程运行时上,异步任务共享工作线程。SSE 流持续 poll 期间,若流内部执行同步阻塞调用(同步数据库查询、文件读取、密集计算),当前工作线程被占住,其他任务无法被调度。正确做法是阻塞操作放到阻塞线程池,异步侧 await 其句柄返回结果。SSE 长连接尤其敏感:一个慢阻塞会拖慢整台实例的推送延迟。

原理流程

  1. 识别流内操作是否阻塞:同步 IO、锁等待、重计算。
  2. 阻塞部分用 tokio::task::spawn_blocking 转移到阻塞线程池。
  3. 异步流 await 任务句柄获取结果。
  4. 结果转换为 Event 写出。
  5. 若阻塞任务失败,流内上报错误并结束。

代码或图示

# async fn stream_events() -> impl futures::stream::Stream<Item = Result<axum::response::sse::Event, std::convert::Infallible>> {
let blocking = tokio::task::spawn_blocking(|| {
    // 同步读取文件或 CPU 密集计算
    std::fs::read_to_string("/tmp/data.txt").unwrap_or_default()
});
let content = blocking.await.unwrap_or_default();
futures::stream::once(async move {
    Ok(axum::response::sse::Event::default().data(content))
})
# }

常见误区

  • 在事件流里调用同步数据库客户端:阻塞工作线程,SSE 推送整体卡顿。
  • 把大段循环计算放在 async fn 里:没有 await 让出点,会独占工作线程。

追问

  • spawn_blocking 返回的句柄为什么还要 await?答:阻塞任务在独立线程池执行,句柄是异步 JoinHandle,必须等待其完成才能取结果;任务 panic 会在 await 处表现为 JoinError。
  • 如何判断一段代码是否阻塞?答:标准库同步 IO、阻塞锁、CPU 密集循环都是;异步库的 .await 调用不阻塞工作线程。

04.4.3.3-038 SSE 响应的 Content-Type 与缓存头如何设置?

一句话结论

SSE 响应必须是 text/event-stream,并禁用缓存(Cache-Control: no-cache),避免代理或浏览器缓存事件流;Sse 类型默认处理 Content-Type,缓存头可在响应层补充。

概念解释

事件流是持续变化的响应,缓存会导致客户端拿到旧流或代理缓冲整条流。协议要求 Content-Type: text/event-stream,Cache-Control 设为 no-cache 防止中间层缓存。某些代理会缓冲非流式响应,需要确认网关不缓冲 SSE。响应头设置方式:Sse 包装响应后通过响应扩展或层补充 header;具体可访问响应头的 API 以 axum 当前版本为准。

原理流程

  1. Sse::new(stream) 生成响应,默认设置事件流 Content-Type。
  2. 响应层追加 Cache-Control: no-cache。
  3. 必要时设置 X-Accel-Buffering: no 之类网关不缓冲标记(按网关支持情况)。
  4. 验证浏览器与代理收到流式响应而不是完整缓冲。
  5. 压测观察首字节时间与逐事件到达间隔。

代码或图示

use axum::response::{sse::{Sse, Event}, Response};
use axum::http::header;

fn sse_response(stream: impl futures::stream::Stream<Item = Result<Event, std::convert::Infallible>>) -> Response {
    let mut resp = Sse::new(stream).into_response();
    resp.headers_mut().insert(header::CACHE_CONTROL, "no-cache".parse().unwrap());
    resp
}

常见误区

  • 让 CDN 默认缓存 SSE 路径:重连后返回缓存的旧流,事件停滞。
  • 代理开启响应缓冲:事件被攒到缓冲满或超时才下发,推送实时性丢失。

追问

  • 如何确认网关没缓冲 SSE?答:观察事件到达间隔是否与生产间隔一致;首帧后长时间无后续帧通常是缓冲或 KeepAlive 配置问题。
  • SSE 需要 Transfer-Encoding: chunked 吗?答:HTTP/1.1 长流通常分块传输;由服务与代理按协议处理,业务一般不显式设置。

04.4.3.3-039 事件流积压导致内存上涨怎么排查?

一句话结论

先定位积压位置:生产速度、通道容量、订阅者消费速度、全局缓冲分别测量;常见根因是无界队列、慢订阅者未断开、事件体过大或多实例消息堆积。

概念解释

内存上涨要看事件从生产到写出的每一段缓冲。排查顺序:监控通道队列长度、订阅者数量、单事件大小、流任务数;对比生产速率与消费速率。有界队列满应触发反压或丢弃策略,无界队列只会把内存转移到堆上。慢订阅者长期不消费会拖住对应队列,需要超时断开或丢弃旧事件。

原理流程

  1. 采集指标:通道长度、订阅数、事件大小、任务数。
  2. 判断积压在总线队列、订阅队列还是响应缓冲。
  3. 检查通道是否有界、满时策略是否生效。
  4. 检查慢订阅者是否被识别并断开。
  5. 调整容量、丢弃策略或扩容订阅处理能力。

代码或图示

排查清单
├── 通道是否有界:无界队列 → 加容量与背压策略
├── 队列长度指标:持续增长说明消费慢于生产
├── 订阅者消费速率:慢连接是否超时断开
├── 事件体大小:大对象是否可裁剪或改二进制
└── 全局缓存:历史事件缓冲是否过长

常见误区

  • 只看进程总内存不看队列指标:无法判断积压在哪一层。
  • 盲目扩容通道容量:掩盖消费能力不足,内存峰值更高。

追问

  • 事件体过大会带来什么?答:单条消息占用更多内存与带宽,慢连接持有大消息会放大积压;应拆分大消息或改走下载链接。
  • 多实例下积压如何排查?答:按实例采集队列与订阅指标,结合消息总线(如 Redis Pub/Sub)堆积情况定位是生产侧还是消费侧问题。

04.4.3.3-040 如何在 SSE 流结束时主动关闭并释放资源?

一句话结论

流任务结束(正常结束、断连或错误)时执行注销与清理:移除房间订阅、关闭本地通道、释放持有资源;用流的组合器或任务结束分支保证清理路径覆盖所有退出方式。

概念解释

资源释放要覆盖三种退出:事件流自然结束、客户端断连、流内错误终止。仅在“正常结束”分支清理会漏掉断连场景。Rust 的 Drop 会释放局部句柄,但注册表注销这类副作用需要显式执行。可在流包装层加入结束钩子,或在任务中 select 取消信号时执行清理;注销要幂等,防止重复执行报错。

原理流程

  1. 订阅建立时记录连接 ID 与房间。
  2. 流包装器在退出时调用注销函数。
  3. 注销从房间表移除连接,释放本地接收端。
  4. 错误与断连路径同样经过注销钩子。
  5. 指标记录连接关闭原因(完成/断连/错误)。

代码或图示

use futures::stream::StreamExt;

# struct Room { tx: tokio::sync::broadcast::Sender<String> }
# impl Room { fn unsubscribe(&self, id: u64) {} }
async fn handler(
    axum::State(room): axum::State<Room>,
    axum::extract::Path(conn_id): axum::extract::Path<u64>,
) -> axum::response::sse::Sse<impl futures::stream::Stream<Item = Result<axum::response::sse::Event, std::convert::Infallible>>> {
    let rx = room.tx.subscribe();
    let stream = futures::stream::unfold(rx, |mut rx| async move {
        match rx.recv().await {
            Ok(msg) => Some((Ok(axum::response::sse::Event::default().data(msg)), rx)),
            Err(_) => { room.unsubscribe(conn_id); None }
        }
    });
    axum::response::sse::Sse::new(stream)
}

常见误区

  • 只在 handler 正常返回时清理:断连导致的任务取消不会走到该分支。
  • 注销函数非幂等:重复断连事件触发二次移除,返回错误或污染日志。

追问

  • 如何覆盖任务被 abort 的清理?答:Drop 析构可释放句柄;需要执行副作用时,结合取消信号监听或在连接表中用弱引用/定期清扫兜底。
  • 清理里能做异步操作吗?答:尽量做轻量同步注销;异步清理应派生独立任务并监控其完成,避免阻塞流退出。

04.4.3.3-041 WebSocketUpgrade 提取器如何工作?

一句话结论

WebSocketUpgrade 是 axum 的提取器,放在 handler 参数中表示该路由支持协议升级;handler 返回它并通过 on_upgrade 注册升级成功后的连接处理回调,握手由框架完成。

概念解释

WebSocket 连接不是普通响应:服务端先返回 101 Switching Protocols,随后在同一条 TCP 连接上收发帧。WebSocketUpgrade 提取器持有待升级的请求上下文,handler 不直接拿到 WebSocket,而是调用 on_upgrade 传入异步回调;握手成功后框架把拆包后的 WebSocket 交给回调。提取器本身不消耗 body,可与其他 FromRequestParts 参数共存。

原理流程

  1. 路由匹配到 WebSocket handler,请求带 Upgrade: websocket 头。
  2. WebSocketUpgrade 提取器校验握手要求。
  3. handler 返回 ws.on_upgrade(handle_socket)。
  4. 框架完成 101 握手,将连接拆为读写流。
  5. 升级回调异步执行,拿到 WebSocket 开始收发帧。

代码或图示

use axum::{extract::ws::{WebSocketUpgrade, WebSocket}, routing::get, Router};

async fn ws_handler(ws: WebSocketUpgrade) -> impl axum::response::IntoResponse {
    ws.on_upgrade(handle_socket)
}

async fn handle_socket(mut socket: WebSocket) {
    while let Some(Ok(msg)) = socket.recv().await {
        // 处理帧
    }
}

let app = Router::new().route("/ws", get(ws_handler));

常见误区

  • 在 handler 里直接 await 连接处理:握手尚未完成就阻塞,升级回调应交给 on_upgrade。
  • 把 WebSocket 当作普通响应体类型返回:连接句柄只在升级回调内可用。

追问

  • 握手失败会返回什么?答:不满足升级条件时框架按普通请求处理或返回错误响应;具体状态码以 axum 当前版本为准。
  • on_upgrade 回调的任务由谁调度?答:升级成功后由运行时派生异步任务执行,回调内不要阻塞工作线程。

04.4.3.3-042 on_upgrade 回调里如何拿到并使用 WebSocket 连接?

一句话结论

回调签名为 async fn(WebSocket),内部用 socket.recv().await 收帧、socket.send(Message).await 发帧;连接的读写循环、注册注销都在这个回调任务内完成。

概念解释

升级回调是单连接生命周期的主体。典型结构是一个读写循环:接收循环读帧并处理,发送通过共享的发送句柄或在同任务内回复。WebSocket 实现了读写拆包,Message 枚举覆盖文本、二进制、Ping、Pong、Close 帧。回调退出即连接结束,需要在退出路径上注销订阅并关闭通道。

原理流程

  1. on_upgrade 注册 async fn(socket: WebSocket)。
  2. 握手完成,回调任务启动。
  3. 循环 recv 读取帧,按类型分发处理。
  4. 需要推送时 send 对应 Message。
  5. 收到关闭帧或循环结束,执行清理后退出。

代码或图示

use axum::extract::ws::{WebSocket, Message};

async fn handle_socket(mut socket: WebSocket) {
    while let Some(Ok(msg)) = socket.recv().await {
        match msg {
            Message::Text(text) => {
                let _ = socket.send(Message::Text(format!("echo: {text}"))).await;
            }
            Message::Binary(bytes) => {
                let _ = socket.send(Message::Binary(bytes)).await;
            }
            Message::Close(_) => break,
            _ => {}
        }
    }
}

常见误区

  • 回调内先做长初始化再进入收帧:握手已完成,初始化期间连接无心跳,容易被代理判定空闲。
  • 忽略 recv 返回的错误:接收错误可能是网络断开,应退出循环并清理。

追问

  • Message::Text 携带的是什么类型?答:以 axum 当前版本为准,通常是 Utf8Bytes 或字符串类型,可用 as_str / into_text 访问;具体 API 查 docs.rs。
  • 如何主动关闭连接?答:socket.send(Message::Close(Some(CloseFrame))) 发送关闭帧,随后退出循环;关闭帧字段结构以当前版本为准。

04.4.3.3-043 如何按连接维护 sender 并实现房间广播?

一句话结论

连接建立时为每个 WebSocket 创建独立发送通道(如 mpsc::Sender),注册到按房间分组的连接表;广播时遍历房间内发送端逐条推送,断连时从表中移除。

概念解释

WebSocket 连接句柄不能跨任务共享发送:通常把每个连接的 mpsc::Sender 存入共享连接表,业务任务或广播循环向表内发送端推送。连接表按 RoomId 分组,映射 ConnId -> Sender。并发访问用 Arc<RwLock<...>> 或按房间拆分任务管理。广播遍历要处理发送失败(连接已死)并即时移除,避免向死连接反复写入。

原理流程

  1. 定义连接表结构:HashMap<RoomId, HashMap<ConnId, mpsc::Sender<Message>>>。
  2. 升级回调内创建本地 mpsc,把发送端注册进房间表。
  3. 回调内派生任务:从通道收消息并 socket.send。
  4. 广播时按房间遍历发送端,成功则保留,失败则移除。
  5. 断连回调从表中注销,关闭通道。

代码或图示

use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::{mpsc, RwLock};
use axum::extract::ws::Message;

type ConnTable = Arc<RwLock<HashMap<String, HashMap<u64, mpsc::Sender<Message>>>>>;

async fn broadcast(room: &ConnTable, room_id: &str, msg: Message) {
    let mut guard = room.write().await;
    let mut dead = Vec::new();
    if let Some(conns) = guard.get_mut(room_id) {
        for (id, tx) in conns.iter() {
            if tx.send(msg.clone()).await.is_err() {
                dead.push(*id);
            }
        }
        for id in dead { conns.remove(&id); }
    }
}

常见误区

  • 直接把 WebSocket 存入共享表跨任务发送:类型不是 Sync,并发写同一连接会冲突。
  • 广播遍历持有写锁期间 await 发送:慢连接会阻塞整个房间的表访问,应先复制发送端再逐个发送。

追问

  • 发送端克隆进表后,接收端在哪里?答:接收端在连接任务内 while let Some(m) = rx.recv().await 循环,把消息转给 socket.send。
  • 房间表用锁还是按房间任务管理?答:并发量低用 RwLock 表即可;高并发可按房间拆独立任务,通过消息邮箱管理成员。

04.4.3.3-044 心跳 ping/pong 与空闲超时怎么实现?

一句话结论

服务端定时发送 Ping 帧,等待对端 Pong;用 tokio::time::timeout 包住等待循环,超过阈值未收到 Pong 或帧则判定空闲超时,主动关闭连接并清理。

概念解释

WebSocket 协议自带 Ping/Pong 控制帧,用于探测连接存活。中间代理可能静默断开空闲 TCP,应用层需要周期心跳。实现上在连接任务内用 interval 定时发 Ping,并用超时跟踪最近收到帧的时间;超时判定后发送 Close 帧并退出。注意区分:协议 Pong 是对 Ping 的响应,业务心跳消息也可放在 Text 帧里,但控制帧更轻量。

原理流程

  1. 连接任务启动心跳定时器(如每 30 秒)。
  2. 每个周期发送 Message::Ping。
  3. 记录上次收到任何帧的时间。
  4. 用超时检查:超过阈值无 Pong 或数据帧则判定超时。
  5. 关闭帧并注销连接。

代码或图示

use axum::extract::ws::{WebSocket, Message};
use tokio::time::{interval, timeout, Duration};

async fn heartbeat_loop(mut socket: WebSocket) {
    let mut tick = interval(Duration::from_secs(30));
    loop {
        tick.tick().await;
        let ping = Message::Ping(Vec::new().into());
        match timeout(Duration::from_secs(10), socket.send(ping)).await {
            Ok(Ok(())) => {}
            _ => break, // 发送超时或失败,关闭连接
        }
        // Pong 与数据帧由接收循环更新最后活跃时间
    }
}

常见误区

  • 只发 Ping 不校验 Pong:对端假死时服务端仍认为连接存活,僵尸连接长期占用资源。
  • 心跳间隔长于代理空闲超时:代理先于心跳关闭连接,心跳失去意义。

追问

  • 浏览器会自动回复 Ping 吗?答:浏览器收到服务端 Ping 会自动回 Pong;服务端也会收到浏览器主动发的 Ping,需要回 Pong,具体帧处理以 axum 版本行为为准。
  • 空闲超时阈值怎么定?答:按网关与 LB 的空闲超时设置,心跳间隔取其一半以下,超时阈值略大于心跳周期。

04.4.3.3-045 WebSocket 与共享状态(State)如何结合?

一句话结论

连接表、房间总线、配置等共享句柄通过 State<AppState> 提取器注入 handler;升级回调通过克隆的句柄访问状态,注册表放在 Arc 内部并由通道或锁保护。

概念解释

WebSocket handler 与普通 handler 一样可以提取 State。状态里通常存放连接表句柄、广播总线发送端、数据库池等。升级回调执行时不再经过 axum 参数提取,因此需要在回调启动前把所需句柄克隆进闭包。状态类型要 Clone + Send + Sync + 'static,满足跨任务共享要求。State 与 Extension 的取舍同普通路由:依赖注入用 State,横切附加用 Extension。

原理流程

  1. 定义 AppState,内含连接表与总线句柄。
  2. 路由 with_state(state) 注入。
  3. WebSocket handler 提取 State,克隆句柄传入升级回调。
  4. 回调内用句柄注册连接、收发消息。
  5. 断连时通过句柄注销。

代码或图示

#[derive(Clone)]
struct AppState {
    rooms: ConnTable,
}

async fn ws_handler(
    axum::State(state): axum::State<AppState>,
    ws: axum::extract::ws::WebSocketUpgrade,
) -> impl axum::response::IntoResponse {
    let rooms = state.rooms.clone();
    ws.on_upgrade(move |socket| handle_socket(socket, rooms))
}

常见误区

  • 在回调内才去取 State:升级后请求上下文已不在,必须提前克隆句柄。
  • 状态里放非 Clone 的裸表:State 要求可克隆跨 handler 共享,表句柄应包 Arc。

追问

  • 数据库池放进 State 可以吗?答:可以,连接池句柄本身可克隆且线程安全,在回调内直接使用。
  • State 与 Extension 怎么选?答:应用必需依赖用 State;临时附加的请求级信息用 Extension,与 04.4.3.2 状态共享章节一致。

04.4.3.3-046 连接注册与注销如何保证并发安全?

一句话结论

注册与注销都通过共享表的锁或房间任务序列化执行;注销按连接 ID 幂等处理,发送失败与断连两条路径都要触发移除,避免重复注册与残留死连接。

概念解释

连接生命周期存在并发:多个连接同时注册、广播遍历与注销交错、接收循环退出与超时关闭可能同时触发。保护手段取决于规模:Arc<RwLock<HashMap>> 适合中小规模,按房间拆分任务适合大规模。注册要生成唯一连接 ID,注销用 ID 定位;移除操作幂等,重复调用不报错。发送端 send 失败说明对端已断,是注销的触发条件之一。

原理流程

  1. 升级成功后生成 ConnId,创建本地通道。
  2. 加锁把 (ConnId, Sender) 写入房间表。
  3. 接收循环退出或发送失败时,提交注销。
  4. 注销加锁移除条目,关闭发送端。
  5. 指标记录在线连接数,与表内条目数对账。

代码或图示

async fn register(rooms: &ConnTable, room: &str, tx: mpsc::Sender<Message>) -> u64 {
    let mut guard = rooms.write().await;
    let id = next_conn_id();
    guard.entry(room.to_string()).or_default().insert(id, tx);
    id
}

async fn unregister(rooms: &ConnTable, room: &str, id: u64) {
    let mut guard = rooms.write().await;
    if let Some(conns) = guard.get_mut(room) {
        conns.remove(&id);
    }
}

常见误区

  • 注销时只删表项不关通道:接收端仍持有,任务与消息可能残留。
  • 注册与注销用不同锁或不同表:条目状态不一致,出现幽灵连接。

追问

  • 高并发下表锁竞争激烈怎么办?答:按房间分桶或拆房间任务,把全局表访问收敛到房间粒度;连接数很大时再考虑分布式连接表。
  • 如何发现泄漏的连接条目?答:定期对账在线任务数与表条目数,指标偏离即存在残留。

04.4.3.3-047 收到文本、二进制、关闭帧分别怎么处理?

一句话结论

按 Message 枚举分支:文本帧解析业务 JSON,二进制帧处理原始字节,关闭帧记录原因后退出循环,Ping/Pong 帧按协议响应或忽略;未知帧不要 panic。

概念解释

Message 变体覆盖 WebSocket 帧类型。文本帧携带 UTF-8 字符串,通常是 JSON 消息;二进制帧用于序列化协议或文件片段;关闭帧带可选 CloseFrame(状态码与原因)。接收循环必须穷举分支,解析失败返回错误消息而不是中断连接。Ping 一般由框架或浏览器自动响应,业务循环只需关注数据帧与关闭帧。

原理流程

  1. recv 得到 Result<Message, Error>,先处理接收错误。
  2. 匹配 Message::Text:UTF-8 校验后反序列化业务消息。
  3. 匹配 Message::Binary:按二进制协议解析。
  4. 匹配 Message::Close:记录关闭原因,退出循环。
  5. 解析失败向连接回送错误帧,继续等待下一帧。

代码或图示

use axum::extract::ws::{Message, CloseFrame};

async fn dispatch(socket: &mut WebSocket, msg: Message) {
    match msg {
        Message::Text(text) => {
            match serde_json::from_str::<ClientMsg>(&text) {
                Ok(m) => handle(m).await,
                Err(e) => { let _ = socket.send(Message::Text(format!("bad json: {e}"))).await; }
            }
        }
        Message::Binary(bytes) => handle_binary(bytes).await,
        Message::Close(Some(CloseFrame { code, reason })) => {
            tracing::info!(%code, %reason, "client closed");
        }
        Message::Close(None) => tracing::info!("client closed without frame"),
        Message::Ping(_) | Message::Pong(_) => {}
    }
}

常见误区

  • 文本帧直接 unwrap 解析:非法 JSON 会终止整个连接任务。
  • 忽略关闭帧原因:无法区分正常关闭、超时断开还是协议错误。

追问

  • 二进制帧里放什么?答:序列化消息(如 bincode、protobuf)、分片文件数据;需要约定消息头与格式。
  • 收到未预期的帧类型怎么办?答:记录警告并忽略或回送协议错误,不要 panic 中断任务。

04.4.3.3-048 如何限制单连接消息大小与频率?

一句话结论

消息大小在协议层或接收循环内校验,超出阈值直接拒绝或断开;频率通过滑动窗口计数器限制单位时间帧数,超限则限流或关闭,防止大消息与高频消息挤占内存与 CPU。

概念解释

WebSocket 服务要防两类滥用:单条超大消息撑爆内存,高频消息打满 CPU 与出口带宽。大小限制可在接收时检查帧字节数;频率限制用按连接的滑动窗口或令牌桶。阈值按业务消息类型设定,超限先回送错误,重复违规再断开。axum 对帧大小的默认配置与可调项以当前版本文档为准,不要假设固定上限。

原理流程

  1. 约定单消息字节上限与单位时间帧数上限。
  2. 接收帧后先检查大小,超限丢弃或拒绝。
  3. 滑动窗口记录最近消息时间戳。
  4. 超限计数,达到阈值触发限流响应或关闭。
  5. 指标记录被拒绝的连接与消息类型。

代码或图示

# const MAX_BYTES: usize = 64 * 1024;
fn size_ok(msg: &Message) -> bool {
    match msg {
        Message::Text(t) => t.len() <= MAX_BYTES,
        Message::Binary(b) => b.len() <= MAX_BYTES,
        _ => true,
    }
}

# struct RateLimiter { window: std::collections::VecDeque<std::time::Instant> }
# impl RateLimiter { fn check(&mut self) -> bool { true } }

常见误区

  • 只限制请求体大小不限制 WS 帧:WebSocket 绕过 HTTP body 限制,形成防护缺口。
  • 限流只计数不记录:事后无法判断是攻击还是客户端 bug。

追问

  • 协议层有消息大小配置吗?答:底层 tungstenite 相关配置可能支持最大帧/消息大小,具体类型与默认值以 axum 依赖版本为准。
  • 频率限制按连接还是全局?答:先按连接防单点滥用,全局速率由网关或限流层兜底。

04.4.3.3-049 WebSocket 升级失败返回什么响应?

一句话结论

不满足升级条件(缺少升级头、Origin 不合法、未认证)时,请求按普通 HTTP 处理,可返回 401/403/400 等状态码;只有握手成功才进入 on_upgrade 回调。

概念解释

升级是条件性的:框架先校验请求是否符合 WebSocket 握手要求,再决定返回 101 还是普通错误响应。认证与 Origin 校验应在提取器或守卫阶段完成,失败时返回标准 HTTP 错误,不进入连接生命周期。这样未认证请求不会占用 WebSocket 连接资源,错误体也能复用统一错误处理。具体升级校验细节以 axum 当前版本实现为准。

原理流程

  1. 请求进入路由,先执行认证/Origin 校验提取器。
  2. 校验失败 → 返回 401/403 普通响应。
  3. 校验通过 → WebSocketUpgrade 完成握手准备。
  4. 握手成功 → 101 + 升级回调。
  5. 握手条件不满足 → 框架返回相应错误响应。

代码或图示

async fn ws_handler(
    axum::State(state): axum::State<AppState>,
    ws: WebSocketUpgrade,
) -> Result<impl axum::response::IntoResponse, AppError> {
    // 握手前完成认证,失败直接返回错误响应
    require_auth(&state).await?;
    Ok(ws.on_upgrade(handle_socket))
}

常见误区

  • 把鉴权放在 on_upgrade 回调里:握手已建立,未认证连接占用一条 WebSocket 资源。
  • 升级失败仍假设回调会执行:回调只在成功升级后被调用。

追问

  • Origin 校验在哪里做?答:可在 handler 前置提取器或中间件比对 Origin 头与允许域名列表;CORS 层配置对 WebSocket 升级请求的适用性需单独验证。
  • 101 响应能带业务错误体吗?答:握手成功后帧通道接管,错误信息应在升级前的 HTTP 响应或连接首条消息中传递。

04.4.3.3-050 广播通道选择 broadcast 还是 mpsc?

一句话结论

一对多广播用 tokio::sync::broadcast,每个订阅者独立队列;单连接内部“业务任务到连接任务”的消息传递用 mpsc;房间连接表方案常是 mpsc 发送端入表,业务侧再决定遍历推送还是先聚合到总线。

概念解释

两种通道语义不同:broadcast 一条消息被多个接收端各收一份,适合全局或房间广播;mpsc 是多生产者单消费者,适合把消息送进某个连接的发送循环。实践中常见组合:总线 broadcast 收到事件后,各连接订阅自己的 mpsc;或连接表存 mpsc::Sender,广播遍历逐条发送。选型看消息需要“复制给多人”还是“投递到单队列”。

原理流程

  1. 判断消息消费方数量:多个订阅者 → broadcast。
  2. 投递到具体连接的发送循环 → mpsc。
  3. 房间内多连接:broadcast 订阅,或表内 mpsc 遍历。
  4. 通道容量按背压策略配置。
  5. 断连时丢弃对应接收端/发送端。

代码或图示

use tokio::sync::{broadcast, mpsc};

// 全局/房间广播:多订阅者
let (bus_tx, _) = broadcast::channel::<String>(128);

// 单连接:业务任务 → 连接发送任务
let (conn_tx, conn_rx) = mpsc::channel::<axum::extract::ws::Message>(32);

常见误区

  • 用 mpsc 做广播:只有一个消费者,其他连接收不到。
  • 用 broadcast 做单连接私有队列:容量与落后机制对单消费者是浪费,语义也不直观。

追问

  • broadcast 订阅者落后会怎样?答:接收端返回 Lagged 错误,跳过中间消息;需要记录落后并决定补发全量。
  • mpsc 满了默认行为?答:send 异步等待腾出容量(有界);try_send 立即返回满错误,按策略丢弃或断开。

04.4.3.3-051 WebSocket 连接泄漏有哪些典型成因?

一句话结论

典型成因包括:注销路径遗漏(只处理正常退出)、连接表持有已死发送端、心跳任务与接收循环未一起退出、通道未关闭导致任务挂起、全局引用阻止连接对象回收。

概念解释

连接泄漏表现为连接数只增不减、内存与文件描述符缓慢上涨。排查要沿生命周期逐段核对:注册是否成对注销、发送端是否在表内残留、派生任务是否全部退出、通道是否关闭、共享表是否持有最后引用。常见代码缺陷是断连只退出接收循环,注销在另一个未被触发的分支;或派生的心跳/广播任务持有 Sender,接收端已退出但任务仍存活。

原理流程

  1. 监控在线连接数与表条目数,确认是否单调上涨。
  2. 列出连接状态:注册时间、最后活跃时间、任务是否存活。
  3. 核对退出路径:正常关闭、网络错误、超时、发送失败。
  4. 检查通道关闭与任务退出是否成对。
  5. 修复注销遗漏与残留引用,补充对账指标。

代码或图示

泄漏成因清单
├── 注销只在正常 Close 帧触发,recv 错误路径未注销
├── 表内 Sender 残留:发送失败后未移除
├── 派生任务持有连接句柄,主循环退出后任务仍挂起
├── mpsc 未关闭,接收任务永远等待
├── 全局缓存/弱引用表未清理死连接
└── 心跳任务与接收循环生命周期不一致

常见误区

  • 以为 Drop 会自动清理注册表条目:Drop 释放内存,但表内条目与副作用注销必须显式完成。
  • 只重启服务应对泄漏:不修复注销路径,问题随流量再次积累。

追问

  • 如何复现泄漏?答:模拟大量连接快速建立断开,观察表条目数与任务数是否回落;压测后静置一段时间再对账。
  • 连接数指标从哪来?答:注册/注销计数器,配合表长度与进程 FD 数;任务数可从运行时指标或日志统计。

04.4.3.3-052 多房间订阅如何路由消息?

一句话结论

按房间 ID 维护连接集合,消息带目标房间;广播时只遍历目标房间内连接,跨房间消息由业务层解析后投递;连接可订阅多个房间,注销时按全部订阅关系移除。

概念解释

房间是消息隔离边界:聊天室、订单订阅、看板分组各成一个房间。连接表以 RoomId 为键分组,加入房间时注册,离开时注销。消息路由先解析目标房间,再在该集合内推送。多房间订阅的连接要维护“连接 → 房间集合”的反向映射,退出时逐一移除,避免连接留在已离开的房间里继续收消息。

原理流程

  1. 定义房间表与连接订阅映射。
  2. 加入房间:向房间集合注册连接,记录反向映射。
  3. 收到消息:解析目标房间 ID。
  4. 遍历房间集合推送,失败条目移除。
  5. 离开/断连:按反向映射从所有房间注销。

代码或图示

use std::collections::{HashMap, HashSet};
use tokio::sync::mpsc;
use axum::extract::ws::Message;

struct RoomState {
    rooms: HashMap<String, HashSet<u64>>,
    conns: HashMap<u64, mpsc::Sender<Message>>,
    conn_rooms: HashMap<u64, HashSet<String>>,
}

常见误区

  • 连接加入新房间后旧房间未移除:收到不属于当前场景的消息。
  • 广播遍历全局连接表再判断房间:浪费遍历成本,房间隔离失效。

追问

  • 房间可以动态创建销毁吗?答:可以,最后一个连接离开时清空房间条目;长期空房间定期清扫。
  • 跨房间转发怎么处理?答:业务层判断消息需要扩散到多个房间,分别向各房间集合投递;避免消息环路。

04.4.3.3-053 WebSocket 与 SSE 在服务端资源模型上有什么差异?

一句话结论

WebSocket 是全双工连接,服务端需同时维护收发循环与连接状态,可承载双向帧;SSE 是单向 HTTP 流,服务端只需产出事件流,连接模型更轻,但浏览器端受同源连接数约束。

概念解释

资源视角:WebSocket 每连接通常对应一个接收循环任务、一个发送通道与心跳管理;SSE 每连接对应一个流任务与订阅句柄。WebSocket 协议升级后脱离普通请求生命周期,状态管理更复杂;SSE 仍是响应流,断连重连由浏览器驱动。服务端选型还要考虑水平扩展:两者都是有状态长连接,多实例下都需要消息总线把事件路由到连接所在实例。

原理流程

  1. 评估交互方向与状态复杂度。
  2. 对比单连接任务、通道与心跳成本。
  3. 评估浏览器连接约束与代理兼容性。
  4. 评估多实例广播的总线接入。
  5. 按场景选择,混合场景可组合使用。

代码或图示

资源模型对比
├── SSE:单向流、浏览器自动重连、任务与订阅句柄较轻
├── WebSocket:双向帧、收发循环 + 通道 + 心跳、状态自管
├── 多实例:两者都需要后端总线路由到目标实例
└── 浏览器:EventSource 同域连接数受限;WebSocket 限制另计

常见误区

  • 认为 WebSocket 一定更耗资源:取决于消息频率与连接管理;低频次单向推送 SSE 更省。
  • 忽略多实例下的连接亲和:广播消息必须找到连接所在实例,不能在单实例内存表里全局推送。

追问

  • 长连接服务端如何扩容?答:按连接数水平扩实例,后端用 Pub/Sub 总线同步房间事件;连接路由一致性由总线扇出保证。
  • SSE 能做上行消息吗?答:上行另开普通 HTTP 请求,服务端再通过对应 SSE 连接推送结果。

04.4.3.3-054 如何测试 WebSocket 升级与消息收发?

一句话结论

测试中先对路由发 HTTP 请求验证升级握手,再用 WebSocket 客户端连接发送文本/二进制消息,断言回帧;断开与注销路径通过主动关闭连接后检查连接表验证。

概念解释

集成测试分三层:握手测试断言 101 与升级头;消息测试连接后发帧、等待并断言响应帧;生命周期测试断开后连接表条目被移除。测试客户端工具取决于依赖版本,常见思路是在测试内构造路由并直接驱动服务。业务消息用序列化后的 JSON 文本帧断言,避免测试依赖真实浏览器。

原理流程

  1. 构造应用路由与测试状态(可注入内存连接表)。
  2. 发起升级请求,断言握手成功。
  3. 建立连接,发送测试消息。
  4. 接收并匹配响应帧内容。
  5. 关闭连接,断言注销执行、表条目清零。

代码或图示

# #[tokio::test]
# async fn echo_test() {
# let app = Router::new().route("/ws", get(ws_handler));
// 测试客户端发起升级并收发消息;具体客户端类型以测试依赖为准
// 断言:发送 "hi" 后收到 echo 帧
# }

常见误区

  • 只测握手不测消息收发:升级成功不代表业务帧处理正确。
  • 测试结束不等待注销完成:断言时表条目尚未移除,产生偶发失败。

追问

  • 如何测试鉴权拒绝?答:不带凭证发升级请求,断言返回 401/403,且不建立连接。
  • 心跳超时如何在测试中模拟?答:测试环境缩短心跳与超时阈值,或注入可控时钟;具体可行性按运行时测试支持为准。

04.4.3.3-055 断开连接后如何通知其他在线成员?

一句话结论

注销连接时向所在房间广播“成员离开”事件(含成员标识与离开时间);其他连接收到后更新在线列表;通知在注销成功后发出,避免通知与实际状态不一致。

概念解释

在线状态同步需要事件驱动:成员加入、离开都产生房间事件,推送给其余连接。离开通知时机要小心:先从连接表注销,再广播离开事件;顺序颠倒可能导致其他成员看到“已离开仍在线”。异常断开(网络错误、超时)与正常关闭走同一注销路径,保证离开事件一定发出。通知消息结构与业务消息一致,走同一序列化格式。

原理流程

  1. 连接确定退出,执行注销。
  2. 注销成功后构造“离开”事件。
  3. 向同房间其他连接广播。
  4. 各连接前端更新在线成员列表。
  5. 指标记录离开原因(正常/超时/错误)。

代码或图示

async fn leave_room(rooms: &ConnTable, room: &str, conn_id: u64, member: &str) {
    unregister(rooms, room, conn_id).await;
    let msg = Message::Text(serde_json::json!({
        "type": "member_leave", "member": member
    }).to_string());
    broadcast(rooms, room, msg).await;
}

常见误区

  • 先广播离开再注销:广播瞬间该连接仍在表内,可能收到自己的离开事件。
  • 异常断开路径不发离开事件:其他成员侧在线列表残留幽灵成员。

追问

  • 离开事件需要可靠送达吗?答:在线列表最终一致即可;其他成员可定期拉取全量成员列表对账,弥补丢失的离开事件。
  • 重连后如何恢复状态?答:重连时拉取当前房间全量成员与最近状态,事件流只做增量更新。

04.4.3.3-056 消息序列化与反序列化失败如何处理?

一句话结论

收帧反序列化失败时回送结构化错误消息并继续接收,不中断连接;发送序列化失败记录日志并按策略关闭;消息格式约定版本号,便于演进。

概念解释

实时消息格式是接口契约。客户端可能发来字段缺失、类型错误或未知版本的消息,服务端不应因此崩溃连接。处理方式:解析失败回送错误帧(含错误码与字段提示),合法消息进入业务逻辑;未知消息类型记录警告并忽略。发送侧序列化失败通常是服务端内部错误,记录日志后关闭连接或重试。消息体建议带 type 与 version 字段,便于区分。

原理流程

  1. 收到文本帧,先解析为通用信封(类型、版本、载荷)。
  2. 按类型反序列化为具体消息结构。
  3. 失败 → 回送错误帧,继续循环。
  4. 成功 → 业务处理,构造响应消息。
  5. 发送序列化失败 → 日志 + 关闭/重试策略。

代码或图示

use serde::Deserialize;

#[derive(Deserialize)]
struct Envelope { r#type: String, payload: serde_json::Value }

async fn on_text(socket: &mut WebSocket, text: &str) {
    match serde_json::from_str::<Envelope>(text) {
        Ok(env) => dispatch(socket, env).await,
        Err(e) => {
            let err = serde_json::json!({"type":"error","message":format!("invalid envelope: {e}")});
            let _ = socket.send(Message::Text(err.to_string())).await;
        }
    }
}

常见误区

  • 反序列化 unwrap:一条非法消息终止整个连接任务。
  • 错误帧直接回传内部解析细节:同样需要遵循对外最小披露原则。

追问

  • 消息格式升级兼容怎么做?答:信封带版本号,服务端按版本选择反序列化结构;旧版本消息保留兼容期。
  • 二进制消息解析失败呢?答:同样回协议错误或关闭连接,按二进制协议错误码区分格式损坏与不支持版本。

04.4.3.3-057 如何在 WebSocket 任务里做优雅退出?

一句话结论

退出路径统一为:收到关闭帧/错误/超时后,先发送 Close 帧,注销连接与订阅,关闭本地通道,再退出任务;退出过程监听停机信号,进行中的连接给宽限时间后强制收尾。

概念解释

优雅退出覆盖单连接与服务进程两层。单连接退出要清理表项、通道与订阅;进程停机时,已有 WebSocket 连接不应被立即断开,应在宽限时间内完成收尾或主动发 Close。任务内可用 select 同时监听收帧、心跳超时与全局停机信号。退出顺序:停止接收新消息 → 发送关闭帧 → 注销 → 释放资源。

原理流程

  1. 连接任务循环中 select 收帧、超时、停机信号。
  2. 触发退出条件,记录原因。
  3. 发送 Close 帧(可带状态码与原因)。
  4. 执行注销与通道关闭。
  5. 任务退出,指标记录关闭原因。

代码或图示

use tokio::select;

# async fn run(mut socket: WebSocket, rooms: ConnTable, shutdown: tokio::sync::Notify) {
loop {
    select! {
        msg = socket.recv() => match msg {
            Some(Ok(Message::Close(_))) => break,
            Some(_) => continue,
            None => break,
        },
        _ = shutdown.notified() => break,
    }
}
// 注销 + 关闭通道
# }

常见误区

  • 任务退出时不发 Close 帧:客户端侧可能经历超时才知道断开,而不是收到正常关闭。
  • 进程停机直接 abort 所有任务:连接被强切,客户端重连风暴。

追问

  • 宽限时间怎么配?答:与服务停机窗口一致,到期仍未收尾的连接由进程退出强制结束;宽限内只做清理不接新消息。
  • 如何通知所有连接准备关闭?答:停机信号广播到各连接任务,任务先发“服务即将重启”消息或 Close 帧,再退出。

04.4.3.3-058 并发写同一 WebSocket 连接有什么约束?

一句话结论

WebSocket 的发送不是任意任务并发安全共享写;通常单连接只在一个发送任务内 send,其他任务通过 mpsc 把消息交给该任务,避免并发写帧导致协议交错。

概念解释

一条 WebSocket 连接的帧流必须有序:两个任务同时写帧会造成帧内容交错、协议损坏。实践模型是“每连接一个发送任务”:业务任务把消息送入连接 mpsc,发送任务独占 socket.send。若要跨任务共享句柄,需用锁串行化,但锁内 await 发送会带来竞争与阻塞复杂度,不如通道模型清晰。WebSocket 的 Send/Sync 约束以当前版本定义为准。

原理流程

  1. 连接建立时创建本地 mpsc。
  2. 派生发送任务:rx.recv() → socket.send。
  3. 业务与广播只向 tx 投递消息。
  4. 所有写帧都经过唯一发送任务。
  5. 通道关闭后发送任务退出,连接收尾。

代码或图示

async fn connection_task(mut socket: WebSocket, mut rx: mpsc::Receiver<Message>) {
    while let Some(msg) = rx.recv().await {
        if socket.send(msg).await.is_err() { break; }
    }
}

常见误区

  • 多个任务直接持有 socket 并发 send:帧交错破坏协议,难复现难排查。
  • 发送任务退出后其他任务仍投递:通道已关闭,投递失败需被正确识别为注销信号。

追问

  • 接收循环与发送任务可以是同一个任务吗?答:可以,单任务内先收后发;需要主动推送时通常拆出发送任务,由通道解耦。
  • 锁保护发送可行吗?答:可行但要保证锁内 await 不长期持有;通道模型更符合异步惯用法。

04.4.3.3-059 大消息分片与背压怎么处理?

一句话结论

超大业务消息应拆分为有序分片帧,接收侧按序号重组;发送侧通过有界通道与发送速度控制背压,慢连接超时或丢弃旧分片,避免大消息在内存中堆积。

概念解释

单条 WebSocket 帧不宜承载大对象(文件、大段快照)。分片方案:消息带 id、index、total,逐帧发送,接收端收集到全部分片后重组。背压方面,连接发送通道有界,满时按策略等待、丢弃或断开;大文件更合适的做法是走 HTTP 下载,WS 只传完成通知。分片重组要有超时,避免丢失分片后半成品长期占用内存。

原理流程

  1. 业务对象超过阈值 → 计算分片大小与序号。
  2. 逐片构造分片帧发送,带消息 ID 与序号。
  3. 接收端按 ID 缓存分片,缺失序号等待重传或超时。
  4. 收齐全部分片后重组处理。
  5. 发送通道满时触发背压策略。

代码或图示

use serde::Serialize;

#[derive(Serialize)]
struct Chunk {
    msg_id: String,
    index: u32,
    total: u32,
    data: String, // 二进制场景放 Base64 或直接 Binary 帧
}

常见误区

  • 不设分片重组超时:丢一片就永久占用缓存。
  • 大文件直接走 WS:带宽、重传与内存成本都高于 HTTP 分块下载。

追问

  • 分片丢失需要重传吗?答:按需实现序号请求重传;实时性要求高的场景可丢弃过期分片,让客户端重新拉取全量。
  • 分片顺序如何保证?答:同一连接帧有序,序号用于校验与重组;跨连接消息不保证全局顺序。

04.4.3.3-060 跨实例广播如何接入 Redis Pub/Sub?

一句话结论

多实例部署时,每个实例维护本实例连接表;后端用 Redis Pub/Sub(或其他消息总线)订阅房间频道,收到跨实例事件后分发给本实例连接;实例上线/下线通过频道同步房间成员。

概念解释

WebSocket 与 SSE 连接是实例本地状态,单实例内存表无法覆盖其他实例的连接。跨实例方案:业务事件发布到总线房间频道,所有实例订阅频道,收到后推给自己本地的连接。消息只路由一次到每个实例,实例内再走本地广播。需要处理总线重连、消息顺序、重复投递与实例故障迁移;连接亲和性由总线扇出保证,不需要网关粘性会话。

原理流程

  1. 实例启动时订阅相关房间频道。
  2. 本地连接加入房间,必要时在总线登记成员关系。
  3. 业务事件发布到频道。
  4. 各实例收到事件,遍历本地连接推送。
  5. 实例下线时清理本地连接,总线成员表更新。

代码或图示

跨实例广播结构
├── 客户端 → 实例 A / B / C(连接在本地)
├── 业务事件 → Redis Pub/Sub 房间频道
├── 各实例订阅频道 → 本地连接表遍历推送
├── 成员状态:频道广播加入/离开事件
└── 故障迁移:客户端重连到其他实例后重新订阅

常见误区

  • 以为单实例连接表能服务多实例:跨实例消息丢失,表现为部分客户端收不到推送。
  • 总线消息直接带大载荷:总线带宽放大 N 倍,应传引用或摘要,详情走存储。

追问

  • 总线重复投递怎么办?答:消息带唯一 ID,接收侧按 ID 去重或容忍幂等处理。
  • 房间成员列表如何全局一致?答:成员加入/离开事件广播到频道,各实例维护本地成员视图;可定期对账全量列表。

04.4.3.3-061 WebSocket 鉴权在升级前还是升级后做?

一句话结论

优先在升级握手前完成认证(请求头/查询令牌校验),失败返回标准 HTTP 错误;升级后再鉴权只作为补充校验,避免未认证连接占用 WebSocket 资源。

概念解释

握手前鉴权与普通 HTTP 接口一致:提取 Authorization 头或查询令牌,校验通过再 on_upgrade。握手后鉴权指连接建立后首条消息携带凭证,这种方式未认证连接已占用一条长连接资源,且握手请求本身无法返回规范错误码。查询令牌的安全约束同 SSE:使用短期订阅令牌,不暴露长期凭证。

原理流程

  1. 升级请求到达,前置提取器读取凭证。
  2. 校验身份与权限。
  3. 失败 → 401/403 响应,不进入升级回调。
  4. 成功 → 完成 101 握手。
  5. 连接内可选首条消息做二次权限校验。

代码或图示

async fn ws_handler(
    axum::extract::Query(q): axum::extract::Query<AuthQuery>,
    ws: WebSocketUpgrade,
) -> Result<impl IntoResponse, AppError> {
    let _user = verify_token(&q.token).await?;
    Ok(ws.on_upgrade(handle_socket))
}

常见误区

  • 升级后才校验令牌:未认证连接长期挂着,资源泄漏面更大。
  • 查询参数放长期 JWT:令牌进日志与历史记录,应换短期令牌。

追问

  • 握手阶段能校验角色权限吗?答:可以,认证后在前置逻辑检查房间/操作权限,失败返回 403。
  • 令牌过期后连接怎么办?答:连接内定期校验或在收到需授权操作时校验,过期则关闭连接并引导重连。

04.4.3.3-062 连接数上限与限流怎么控制?

一句话结论

全局连接数上限在接入层与应用层双重控制:达到上限拒绝新连接;单 IP、单用户连接数分别限流;在线连接数作为核心监控指标,配合扩容策略。

概念解释

长连接占用内存、文件描述符与心跳成本,必须设上限。控制层级:网关/负载均衡限制并发连接数,应用内维护原子计数器与连接表,新连接注册前检查上限。维度包括全局总数、单 IP、单用户、单房间。超限返回 503 或重试提示,而不是静默挂起。限流阈值按单连接内存成本与实例容量估算,压测得出安全水位。

原理流程

  1. 压测估算单连接内存与 CPU 成本,确定上限。
  2. 应用内维护连接计数器,注册前检查。
  3. 按 IP/用户/房间维度记录连接数。
  4. 超限拒绝新连接,返回可重试响应。
  5. 监控连接数水位,触发放大或扩容告警。

代码或图示

use std::sync::atomic::{AtomicU64, Ordering};

struct ConnCounter(AtomicU64);

impl ConnCounter {
    fn try_acquire(&self, max: u64) -> bool {
        let n = self.0.load(Ordering::Relaxed);
        if n >= max { return false; }
        self.0.fetch_add(1, Ordering::Relaxed) < max
    }
    fn release(&self) { self.0.fetch_sub(1, Ordering::Relaxed); }
}

常见误区

  • 只靠网关限流,应用内无上限:绕过网关直连或网关配置失效时实例被打满。
  • 计数器只增不减:注销路径漏减,上限被错误触达。

追问

  • 单连接成本怎么估算?答:内存(通道缓冲、连接对象)+ CPU(心跳、收发)+ FD 数;压测观察水位曲线拐点。
  • 超限连接给客户端什么响应?答:HTTP 阶段返回 503 带 Retry-After;已连接内限流则回送错误帧并断开。

04.4.3.3-063 升级握手的 Origin 校验怎么做?

一句话结论

在握手前读取 Origin 头,与允许域名列表比对,不匹配则拒绝升级;列表配置化,区分开发与生产环境,避免把 CORS 配置直接套用到 WS 而遗漏 Origin 校验。

概念解释

WebSocket 跨站请求可携带 Cookie,Origin 校验是防跨站 WebSocket 劫持的基本手段。校验发生在升级请求阶段:解析 Origin 的协议与域名,匹配白名单。浏览器跨域 WS 会发 Origin 头;非浏览器客户端可能不带该头,按业务决定是否允许。允许列表从配置读取,不要硬编码通配所有域名。CORS 层对 Upgrade 请求的处理与普通 AJAX 不同,需要单独验证。

原理流程

  1. 前置提取器或中间件读取 Origin 头。
  2. 解析来源域名,与白名单比对。
  3. 匹配失败 → 403 普通响应。
  4. 匹配通过 → 继续升级流程。
  5. 记录被拒绝的 Origin 用于安全审计。

代码或图示

# fn origin_allowed(origin: &str) -> bool { true }
async fn ws_handler(
    headers: axum::http::HeaderMap,
    ws: WebSocketUpgrade,
) -> Result<impl IntoResponse, AppError> {
    let origin = headers.get("origin")
        .and_then(|v| v.to_str().ok())
        .ok_or(AppError::Forbidden)?;
    if !origin_allowed(origin) { return Err(AppError::Forbidden); }
    Ok(ws.on_upgrade(handle_socket))
}

常见误区

  • 复用普通接口的 CORS 配置就以为 WS 安全:WS 不走预检,Origin 必须在握手请求里显式校验。
  • 白名单写成 * 且允许携带凭证:等于放开跨站劫持风险。

追问

  • 不带 Origin 头的请求怎么处理?答:内部服务或原生客户端可能省略;按部署环境决定是否拒绝,记录策略便于审计。
  • Origin 与 Host 头要一起校验吗?答:可作为辅助校验;重点是来源域名白名单,Host 校验防止Host头攻击另作处理。

04.4.3.3-064 消息积压导致内存暴涨如何排查?

一句话结论

沿“生产端 → 总线/通道 → 连接发送队列 → 网络写出”逐段测量队列长度与速率,定位积压段;常见根因是慢连接未断开、无界队列、消息体过大或下游总线阻塞。

概念解释

实时推送内存暴涨与 SSE 积压排查思路一致,但 WS 多了连接发送队列与二进制消息。排查要点:各通道长度指标、单连接未发出消息数、消息大小分布、连接发送速率。慢连接持有队列不消化,是最常见积压源;解决方向是背压、超时断开、丢弃旧消息或扩容。二进制大消息应评估是否改走文件下载。

原理流程

  1. 采集各段队列长度、发送速率、消息大小。
  2. 对比生产与消费速率,定位最慢环节。
  3. 检查连接队列:识别长期未消费的慢连接。
  4. 检查通道容量与满时策略。
  5. 执行断开/丢弃/扩容,验证内存回落。

代码或图示

积压排查路径
├── 总线通道长度:事件生产是否过快
├── 连接 mpsc 长度:哪些连接发送队列积压
├── 单消息大小:是否存在大载荷
├── 网络写出速率:带宽或对端消费瓶颈
└── 慢连接处理:超时断开 / 丢弃旧消息

常见误区

  • 只看进程 RSS:无法区分是连接对象、消息缓冲还是其他缓存占用。
  • 加内存不加限制:积压被推迟,崩溃更晚但更严重。

追问

  • 如何识别慢连接?答:记录每个连接最后一次成功发送时间与队列长度,超过阈值标记为慢连接。
  • 积压消息可以丢弃吗?答:状态类消息可只保留最新值;事件类消息需评估丢失影响,必要时让客户端重连拉取全量。

04.4.3.3-065 心跳超时不生效常见原因有哪些?

一句话结论

常见原因:心跳定时器与接收循环未在同一 select 中驱动、超时判断未真正检查 Pong/活跃时间、心跳间隔长于代理空闲超时、超时后未执行注销与关闭。

概念解释

心跳机制看似简单,失效点分散在循环结构、计时逻辑与清理路径。若接收循环独占 recv().await,心跳定时得不到调度;若只发 Ping 不校验 Pong,假死连接无法识别;若超时阈值大于代理空闲时间,连接已被中间层断开,服务端仍在等待。修复后要验证:模拟对端不回 Pong,观察连接是否在阈值内被关闭并注销。

原理流程

  1. 检查循环结构:心跳与收帧是否 select 并发等待。
  2. 核对活跃时间更新:任何帧都应刷新最后活跃时间。
  3. 核对阈值:心跳间隔 < 代理空闲超时,超时阈值 > 心跳周期。
  4. 检查超时分支:关闭帧、注销、通道关闭是否齐全。
  5. 测试模拟假死连接,验证自动清理。

代码或图示

失效原因清单
├── 定时器未纳入 select,收帧阻塞期间心跳不调度
├── 只发 Ping 不检查 Pong / 最后活跃时间
├── 心跳间隔大于网关空闲超时
├── 超时后只退出循环,未注销连接表
├── 系统时间回拨导致超时判断失效
└── 测试环境心跳阈值被错误放大

常见误区

  • 把 TCP keepalive 等同于应用心跳:TCP 层探测间隔通常很长,无法识别应用层假死。
  • 心跳日志正常就认为机制生效:必须验证超时关闭路径实际触发。

追问

  • 如何模拟对端不回 Pong?答:测试客户端连接后静默不响应,观察服务端是否在阈值内断开并记录超时关闭。
  • 心跳用文本消息代替 Ping 帧可以吗?答:可以作为业务心跳,但控制帧更轻量;两种方式都要配超时判断。

04.4.3.3-066 如何实现流式下载响应(Body/Stream)?

一句话结论

把实现 Stream 的字节序列包装为响应 body,axum/hyper 按流逐块写出;大文件下载用文件流或字节流,避免把整个文件读进内存再返回。

概念解释

普通 Json/String 响应会缓冲完整 body;流式响应的 body 是一个异步流,生产一块写一块。适用场景:大文件导出、日志下载、数据库游标分批读出。流元素为字节块(Bytes),中途错误可作为流错误上报。响应头按下载场景设置 Content-Type、Content-Disposition 与范围请求支持;是否支持断点续传取决于实现。

原理流程

  1. 数据源实现为 Stream<Item = Result<Bytes, E>>。
  2. 用流构造响应 body,设置下载相关响应头。
  3. 框架逐块 poll 流并写出。
  4. 流结束或出错时响应关闭。
  5. 慢客户端通过流背压反向压住数据源。

代码或图示

use axum::body::Body;
use axum::response::Response;
use bytes::Bytes;
use futures::stream::iter;

let chunks = iter(vec![Ok::<Bytes, std::io::Error>(Bytes::from("chunk1")),
                       Ok(Bytes::from("chunk2"))]);
let body = Body::from_stream(chunks);
let resp = Response::builder()
    .header("content-type", "text/plain")
    .body(body).unwrap();

常见误区

  • 先 read_to_end 读全文件再返回:大文件直接撑爆内存。
  • 流内做阻塞读取:卡住异步工作线程,影响其他下载。

追问

  • 文件下载用什么流?答:可基于 tokio 文件 AsyncRead 转流,或使用现成文件服务层;具体类型以项目依赖为准。
  • 如何支持 Range 断点续传?答:解析 Range 头,按偏移构造文件流;现成静态文件服务层通常已处理,自研需自行实现。

04.4.3.3-067 分块上传如何接收 ByteStream 并落盘?

一句话结论

用 ByteStream 提取器拿到请求体字节流,逐块写入文件或对象存储,边收边落盘;配合 body 大小限制与超时,避免大上传占用内存与连接。

概念解释

上传大文件不能用 Bytes/Json 一次性缓冲。ByteStream 把请求体暴露为字节流,handler 逐块消费:写入临时文件、校验哈希、最后原子改名入库。落盘过程要处理中断清理(临时文件删除)、大小累计与速率控制。上传接口同样受 body 限制层约束,超限在读取阶段即被拒绝。

原理流程

  1. 路由接收 ByteStream 提取器。
  2. 创建临时文件,循环读取字节块。
  3. 累计大小,超过上限则中止并清理。
  4. 收完后校验(哈希、类型),原子改名到正式路径。
  5. 中途错误删除临时文件。

代码或图示

use axum::extract::ByteStream;
use tokio::io::AsyncWriteExt;

async fn upload(mut stream: ByteStream) -> Result<axum::response::Response, AppError> {
    let mut file = tokio::fs::File::create("/tmp/upload.tmp").await?;
    let mut total = 0u64;
    while let Some(chunk) = stream.next().await {
        let chunk = chunk?;
        total += chunk.len() as u64;
        if total > MAX_UPLOAD { return Err(AppError::TooLarge); }
        file.write_all(&chunk).await?;
    }
    file.flush().await?;
    Ok(axum::response::Response::new(axum::body::Body::from("ok")))
}

常见误区

  • 上传内容先存内存再落盘:大文件内存峰值与文件大小成正比。
  • 中断后不清理临时文件:磁盘被残留碎片占满。

追问

  • 分块上传(客户端分片)怎么做?答:每片独立 POST 到服务端落盘,记录分片清单,全部到齐后合并;合并阶段再校验完整性。
  • 上传限速怎么实现?答:在读取循环中按令牌桶或时间间隔控制写入节奏;全局带宽由网关/服务层兜底。

04.4.3.3-068 阻塞调用为什么必须用 spawn_blocking?

一句话结论

异步运行时的工作线程数量有限,阻塞调用会独占线程导致其他任务无法调度;spawn_blocking 把阻塞操作移到独立阻塞线程池,异步侧只 await 任务句柄,不占用工作线程。

概念解释

Tokio 运行时分工作线程池与阻塞线程池:工作线程跑异步任务,阻塞线程池跑同步阻塞代码。标准库同步 IO、CPU 密集计算、阻塞锁都属于阻塞操作。在异步任务里直接执行会阻塞工作线程,表现为接口延迟整体上涨、吞吐下降。spawn_blocking 返回 JoinHandle,异步侧等待其完成;任务内 panic 会在 await 处转为 JoinError。

原理流程

  1. 识别代码块:同步 IO、重计算、阻塞等待。
  2. 用 tokio::task::spawn_blocking 闭包包裹。
  3. 阻塞线程池执行闭包,返回结果。
  4. 异步任务 await 句柄取结果。
  5. 处理 JoinError(panic 或任务取消)。

代码或图示

# async fn handler() -> Result<String, AppError> {
let handle = tokio::task::spawn_blocking(|| {
    // 同步读取或 CPU 密集计算
    std::fs::read_to_string("data.txt")
});
let content = handle.await.map_err(|_| AppError::Internal)??;
Ok(content)
# }

常见误区

  • 在 spawn_blocking 闭包里再 .await:阻塞线程不跑异步任务,闭包必须是同步代码。
  • 阻塞线程池任务堆积:阻塞任务过多会耗尽池容量,需要评估任务时长与并发度。

追问

  • 哪些操作算阻塞?答:标准库 std::fs、同步网络客户端、std::sync::Mutex 长临界区、密集循环计算;异步库的 .await 不阻塞工作线程。
  • spawn_blocking 结果跨线程有什么约束?答:返回值需 Send + 'static,闭包捕获变量同样满足该约束。

04.4.3.3-069 异步上下文里误用阻塞 IO 会有什么后果?

一句话结论

后果是工作线程被独占:同实例其他异步任务调度延迟升高、接口 P99 上涨、吞吐下降,严重时运行时看似“卡死”;表现与资源不足不同,根因是阻塞点没有让出执行权。

概念解释

异步调度依赖任务在等待时 yield:.await 挂起任务把工作线程让给其他任务。同步阻塞调用没有让出点,工作线程被一直占用。多线程运行时下其他线程还能分担,但阻塞点多时线程被占满;单线程运行时则直接串行卡住。排查时看延迟分布与任务调度状态,阻塞点通常是同步库调用或大段无 await 计算。

原理流程

  1. 异步任务执行同步阻塞代码,工作线程被占住。
  2. 其他任务排队等待可用工作线程。
  3. 接口延迟随并发上升而放大。
  4. 阻塞代码返回后线程才释放。
  5. 定位阻塞点,迁移到 spawn_blocking 或换异步库。

代码或图示

误用表现
├── 单线程运行时:后续任务全部排队,响应停滞
├── 多线程运行时:P99 延迟上涨,线程占用打满
├── 阻塞点:同步 fs / 同步 HTTP / 阻塞锁 / 重计算
└── 修复:spawn_blocking 包裹,或改用异步客户端

常见误区

  • 以为“异步函数里调用同步函数没问题”:只要内部阻塞,工作线程就被占住。
  • 用增加工作线程数解决:只是缓解,阻塞点仍在,高并发下依旧打满。

追问

  • 如何定位阻塞点?答:看任务耗时分布、线程火焰图;在可疑同步调用前后打点,或用运行时诊断工具观察调度延迟。
  • 阻塞锁在异步里怎么处理?答:短临界区可用异步锁或减少持锁时间;长临界区考虑把数据操作移入 spawn_blocking。

04.4.3.3-070 如何给 handler 加超时(TimeoutLayer 与手动 timeout)?

一句话结论

全局或路由级超时用 tower_http::timeout::TimeoutLayer 配置时长;单段异步操作用 tokio::time::timeout 包裹;超时触发后返回 503 或自定义错误,任务随取消被清理。

概念解释

超时防止慢请求长期占用连接与线程。层方式在服务链外层统一控制 handler 执行时长,配置简单;手动 timeout 适合只保护某一步依赖调用(数据库、下游 HTTP)。超时触发后 Future 被取消,持有的资源随任务 drop 释放。注意超时只控制等待时长,不保证下游操作已经终止;下游需配合取消传播。

原理流程

  1. 确定超时范围:整个 handler 还是单个依赖调用。
  2. 全局超时挂 TimeoutLayer,设置 Duration。
  3. 局部调用用 tokio::time::timeout(duration, fut)。
  4. 超时分支返回 503/自定义错误。
  5. 被取消任务的资源在 drop 时释放。

代码或图示

use tower_http::timeout::TimeoutLayer;
use std::time::Duration;
use axum::Router;

let app = Router::new()
    .route("/items", axum::routing::get(handler))
    .layer(TimeoutLayer::new(Duration::from_secs(5)));

# async fn handler() -> axum::response::Response {
let fut = repo::find(1);
match tokio::time::timeout(Duration::from_secs(2), fut).await {
    Ok(v) => v.into_response(),
    Err(_) => (axum::http::StatusCode::REQUEST_TIMEOUT, "timeout").into_response(),
}
# }

常见误区

  • 只给下游调用加超时,handler 整体无超时:下游返回后其他步骤仍可能卡住。
  • 超时后继续使用被取消任务的句柄:任务已被 abort,结果不可再取。

追问

  • 超时返回 503 还是 408?答:请求超时常用 408,服务暂不可用用 503;按项目错误码约定统一。
  • TimeoutLayer 对 WebSocket/SSE 长连接适用吗?答:长连接不能套用普通请求超时,否则连接被定期切断;超时层应只挂在普通路由上。

04.4.3.3-071 超时触发后连接与任务如何清理?

一句话结论

超时取消 Future 后,任务被 drop,持有的通道句柄、锁守卫、数据库连接随析构释放;连接表类资源要在任务退出路径显式注销,避免超时退出遗漏清理。

概念解释

Rust 的取消安全依赖 drop:Future 被取消时,局部变量按逆序析构,释放持有资源。但注册表条目、全局订阅这类副作用不会自动回滚。超时退出与正常退出应走同一清理路径:注销连接、关闭通道、释放订阅。数据库连接在 drop 时归还池;若操作在事务中,回滚行为取决于连接与事务实现。

原理流程

  1. 超时触发,Future 被取消。
  2. 局部资源 drop:句柄、守卫、连接归还。
  3. 任务退出分支执行显式注销。
  4. 通道关闭,接收任务随之退出。
  5. 指标记录超时取消次数。

代码或图示

# async fn run() {
match tokio::time::timeout(Duration::from_secs(3), work()).await {
    Ok(v) => v,
    Err(_) => {
        cleanup().await; // 显式注销与资源释放
        return AppError::Timeout;
    }
}
# }

常见误区

  • 以为超时后下游任务也停止:取消只作用于本地 Future,下游服务端操作可能仍在执行,需靠请求取消或超时传播。
  • 超时路径不注销:长连接/订阅在表内残留,形成泄漏。

追问

  • 如何验证清理完整?答:压测制造超时,观察连接表条目、通道数、连接池占用是否回落。
  • 事务超时后连接状态?答:未提交事务随连接归还时按驱动策略回滚;具体行为以数据库驱动实现为准。

04.4.3.3-072 body 大小限制如何配置,超限返回什么?

一句话结论

用 tower_http::limit::RequestBodyLimitLayer 配置请求体上限;超限在读取 body 时被拒绝,通常返回 413;上传接口可单独放宽限制,普通 JSON 接口保持较小上限。

概念解释

body 限制是防大请求打爆内存的基础防护。限制层在 body 读取阶段计数,超过阈值即中止读取并返回错误。不同接口阈值不同:JSON 提交几十 KB 到几 MB,文件上传单独放宽或走分片。层配置要注意作用范围:全局默认限制 + 上传路由单独覆盖。超限状态码语义为 413 Payload Too Large;具体错误类型与状态码以 tower-http 当前版本为准。

原理流程

  1. 确定全局 body 上限与上传路由上限。
  2. 全局挂载限制层,上传路由覆盖更大阈值。
  3. 请求读取 body 时层内累计字节数。
  4. 超限 → 中止读取,返回 413 错误响应。
  5. 指标记录超限请求,排查恶意或客户端 bug。

代码或图示

use tower_http::limit::RequestBodyLimitLayer;
use axum::Router;

let app = Router::new()
    .route("/upload", axum::routing::post(upload))
    .route("/items", axum::routing::post(create))
    .layer(RequestBodyLimitLayer::new(1024 * 1024)) // 全局 1MB
    // 上传路由在其内部覆盖更大限制;层顺序与覆盖方式以当前版本为准
    ;

常见误区

  • 限制层挂在 body 提取器内侧:body 已被消费后才限制,内存峰值已产生。
  • 所有接口同一阈值:上传接口被误拒,或普通接口上限过松。

追问

  • 限制层与读取顺序有什么关系?答:限制必须在 body 被业务读取之前生效,层位置要在消耗 body 的提取器/handler 外层。
  • 超限后连接还能复用吗?答:body 未完整读取时连接复用可能受影响;具体行为以 hyper 与层实现为准,必要时关闭连接。

04.4.3.3-073 上传大文件时内存与磁盘如何取舍?

一句话结论

超过内存安全水位的文件必须流式落盘,内存只缓冲当前块;极小文件可直接内存接收。取舍依据是单文件大小、并发上传数与可用内存,临时文件空间与清理策略一并规划。

概念解释

内存缓冲方案简单但峰值等于“单文件大小 × 并发上传数”;落盘方案内存恒定,但消耗磁盘 IO 与临时空间。选型先算内存预算:并发上传数 × 单文件上限不能超过可分配内存。落盘要处理临时目录容量、文件清理、断电残留与最终合并。对象存储场景可流式直传,避免本地中转。

原理流程

  1. 评估并发上传数与单文件上限,计算内存峰值。
  2. 小文件阈值内走内存接收;超过阈值流式落盘。
  3. 落盘文件带唯一临时名,记录上传元数据。
  4. 完成后校验并转正,失败清理临时文件。
  5. 定期清扫过期残留临时文件。

代码或图示

取舍计算
├── 内存方案:峰值 = 并发数 × 单文件上限
├── 落盘方案:内存 ≈ 单块大小,磁盘 = 临时文件 + 正式文件
├── 阈值:内存预算 / 并发数
├── 清理:中断删除、定时清扫、启动时检查残留
└── 对象存储:流式直传,避免本地双份存储

常见误区

  • 不评估并发数,只按单文件大小判断:多并发叠加后内存峰值翻倍。
  • 临时文件与正式文件同目录且无清理任务:磁盘逐渐占满。

追问

  • 内存接收上限设多少?答:按实例内存与并发估算,常见小文件接口限制在几百 KB 到数 MB;具体值压测确定。
  • 磁盘满了上传怎么办?答:写入前检查空间水位,超限返回 507 或 503;临时目录与系统盘分离。

04.4.3.3-074 流式响应中途出错如何处理?

一句话结论

流元素使用 Result,错误在流内部转换为错误事件或中止流;响应头已发出后不能再改状态码,中途错误只能通过流内错误消息或关闭连接表达。

概念解释

普通错误在 handler 返回时映射状态码;流式响应一旦开始写出,响应头已提交,中途无法回头改 4xx/5xx。处理方式:流内部把错误转为结构化错误事件推给客户端,或结束流并记录服务端日志。大文件下载中途失败,可在错误事件中说明原因,客户端决定重试。启动流之前的校验错误仍走正常 IntoResponse 路径。

原理流程

  1. 进入流之前完成参数与权限校验,错误正常返回状态码。
  2. 流构造为 Result<Bytes, E> 序列。
  3. 生产中途出错:记录日志,向流内写入错误事件或终止流。
  4. 客户端解析错误事件,提示重试。
  5. 流任务退出时释放订阅与句柄。

代码或图示

use futures::stream::StreamExt;
use axum::response::sse::{Event, Sse};

let stream = futures::stream::once(async {
    match produce().await {
        Ok(v) => Ok(Event::default().data(v)),
        Err(e) => {
            tracing::error!(error = ?e, "stream failed");
            Ok(Event::default().event("error").data(e.to_string()))
        }
    }
});
let _ = Sse::new(stream);

常见误区

  • 流中途出错还想返回 500 状态码:响应头已提交,状态码无法变更。
  • 错误事件与正常消息同类型:前端无法区分,应使用独立事件类型或错误信封。

追问

  • 下载流中途断连怎么感知?答:写出时收到错误或流被取消;在退出路径记录中断原因与已传输量。
  • 错误事件需要携带请求 ID 吗?答:需要,便于客户端反馈后服务端按 ID 检索日志。

04.4.3.3-075 优雅停机 with_graceful_shutdown 怎么用?

一句话结论

在 axum::serve 上调用 with_graceful_shutdown,传入一个在停机信号触发时完成的 Future;信号到达后停止接收新连接,等待进行中请求与长连接收尾,再退出服务。

概念解释

优雅停机避免发布、缩容时强切连接:先停止 accept 新连接,已有请求在宽限时间内完成,长连接收到关闭通知后退出。with_graceful_shutdown 接收一个 Future,该 Future 就绪即触发停机流程。信号源可以是 tokio::signal::ctrl_c、SIGTERM 监听或内部通知。Web 服务与长连接服务的收尾逻辑不同,需要分别处理。

原理流程

  1. 构造停机信号 Future(监听系统信号或 Notify)。
  2. serve(listener, app).with_graceful_shutdown(signal_fut)。
  3. 信号触发,服务停止接受新连接。
  4. 进行中请求与活跃连接在宽限内收尾。
  5. 全部完成后 serve 返回,进程退出。

代码或图示

use axum::Router;

# async fn run(app: Router) {
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
let shutdown = async {
    tokio::signal::ctrl_c().await.ok();
};
axum::serve(listener, app)
    .with_graceful_shutdown(shutdown)
    .await
    .unwrap();
# }

常见误区

  • 停机信号 Future 立即就绪:服务启动后马上进入停机流程。
  • 只配 HTTP 请求收尾,不管 WebSocket/SSE:长连接被强切,客户端重连风暴。

追问

  • 宽限时间在哪里控制?答:停机等待的超时可在信号 Future 或收尾逻辑中用 timeout 控制,到期强制结束;具体 API 以 axum 当前版本为准。
  • 停机期间健康检查怎么返回?答:可先摘除负载均衡流量,再触发停机;服务内可提供健康端点区分“即将下线”状态。

04.4.3.3-076 优雅停机期间进行中的请求与长连接如何处理?

一句话结论

普通请求在完成后自然结束;长连接(WS/SSE)需要在停机信号到达后主动推送关闭通知或 Close 帧,给宽限时间收尾,到期仍未退出的连接强制结束并释放资源。

概念解释

停机时两类连接行为不同:短请求有明确结束点,等待完成即可;长连接没有自然结束点,必须由服务端主动通知关闭。实现上把停机信号广播到各连接任务,任务收到后发关闭帧、注销、退出。宽限时间内未退出的连接随进程结束被强切,因此要设置超时兜底。数据库连接、后台任务同样要在停机窗口内收尾。

原理流程

  1. 停机信号派生为全局 Notify 或广播。
  2. 短请求继续执行直至返回。
  3. 长连接任务监听信号,收到后发关闭通知/Close 帧。
  4. 宽限时间内等待连接注销;超时强制结束。
  5. 后台任务与连接池在窗口内收尾。

代码或图示

use tokio::sync::Notify;
use std::sync::Arc;

# struct State { shutdown: Arc<Notify> }
# async fn ws_task(state: State) {
loop {
    tokio::select! {
        msg = socket.recv() => { /* 处理消息 */ }
        _ = state.shutdown.notified() => {
            let _ = socket.send(Message::Close(None)).await;
            break;
        }
    }
}
# }

常见误区

  • 等待长连接自然退出:连接不主动关闭,服务一直挂住不退。
  • 宽限内不做通知直接强切:客户端收到网络错误,无法走正常关闭流程。

追问

  • 后台任务(定时、队列消费)如何收尾?答:停机信号通知任务停止拉取新任务,处理完在途任务后退出;必要时把任务放回队列等待下次启动。
  • 宽限时间设多长?答:按请求 P99 与连接关闭耗时设定,通常数十秒内;超过窗口强制结束并记录未完成任务。

04.4.3.3-077 停机信号如何接入(SIGTERM / Ctrl+C)?

一句话结论

用 Tokio 信号监听 ctrl_c 与 Unix SIGTERM,信号到达后完成停机 Future;容器环境主要依赖 SIGTERM,本地开发依赖 Ctrl+C。

概念解释

进程停机来源:本地终端 Ctrl+C 产生 SIGINT,容器编排发送 SIGTERM。Tokio 提供信号监听 API,把系统信号转为异步事件。多个信号源可合并监听;收到信号后先触发优雅停机流程,而不是直接退出。信号监听要在运行时内执行,不能在普通同步上下文调用。

原理流程

  1. 在 #[tokio::main] 内创建信号监听。
  2. 同时等待 Ctrl+C 与 SIGTERM(Unix)。
  3. 信号就绪,触发停机 Notify。
  4. with_graceful_shutdown 的 Future 完成。
  5. 服务收尾后进程退出。

代码或图示

# async fn shutdown_signal() {
let ctrl_c = tokio::signal::ctrl_c();

#[cfg(unix)]
let terminate = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate());

tokio::select! {
    _ = ctrl_c => {}
    #[cfg(unix)]
    _ = terminate.expect("signal listen").recv() => {}
}
# }

常见误区

  • Windows 代码路径调用 Unix 信号 API:需用条件编译区分平台。
  • 信号到达后立即 std::process::exit:跳过优雅收尾,连接与任务被强切。

追问

  • 容器收到 SIGTERM 后多久必须退出?答:按编排配置的宽限时间,超时会被 SIGKILL;服务停机窗口要小于该值。
  • 如何同时处理 panic 退出?答:panic 监控与信号停机分开;进程级崩溃由容器重启策略兜底。

04.4.3.3-078 CORS 预检 OPTIONS 请求如何被排除或处理?

一句话结论

tower-http 的 CorsLayer 自动处理预检 OPTIONS 请求并返回预检响应;业务路由通常不注册 OPTIONS 方法。需要注意 WebSocket 升级与 CORS 是两套机制,预检只覆盖普通跨域 HTTP 请求。

概念解释

跨域复杂请求浏览器先发 OPTIONS 预检,询问允许的方法、头与来源。CORS 层在请求进入业务路由前拦截预检,返回 Access-Control-* 响应头。业务 handler 不需要实现 OPTIONS。若 CORS 层配置不当,预检失败会导致真实请求不发出。WebSocket 不经过 CORS 预检,其跨站保护靠 Origin 校验。

原理流程

  1. 浏览器对跨域复杂请求发送 OPTIONS 预检。
  2. CORS 层识别预检方法与头,比对配置。
  3. 匹配则返回预检响应(允许方法、头、来源)。
  4. 浏览器通过后才发送真实请求。
  5. 真实响应同样带 CORS 头。

代码或图示

use tower_http::cors::{CorsLayer, Any};
use axum::Router;

let cors = CorsLayer::new()
    .allow_origin(Any)
    .allow_methods(Any)
    .allow_headers(Any);

let app = Router::new().route("/items", axum::routing::get(list)).layer(cors);

常见误区

  • 业务路由里手写 OPTIONS handler 处理预检:与 CORS 层重复,容易头信息不一致。
  • 以为配置 CORS 层就保护了 WS:WS 跨站需单独做 Origin 校验。

追问

  • 预检缓存怎么配?答:Access-Control-Max-Age 配置预检结果缓存时长,减少重复预检;具体方法名以 tower-http 当前版本为准。
  • 带凭证的跨域请求有什么限制?答:不能用通配来源,需明确允许域名并允许凭证;具体组合规则按 CORS 规范。

04.4.3.3-079 CORS 层配置要点有哪些?

一句话结论

要点包括允许来源(明确域名或开发期 Any)、允许方法、允许请求头、暴露响应头、凭证开关与预检缓存;生产环境禁止来源通配,配置从环境读取。

概念解释

CORS 配置决定浏览器是否允许跨域访问。allow_origin 是核心:生产按域名白名单配置,开发期可用 Any。allow_methods 与 allow_headers 列出真实请求会用到的方法与头;expose_headers 允许前端读取非默认响应头。凭证模式下来源不能通配。配置应区分环境,避免开发期宽松配置带入生产。

原理流程

  1. 按环境确定允许来源列表。
  2. 配置允许方法与请求头。
  3. 需要凭证时开启凭证并收紧来源。
  4. 配置暴露头与预检缓存。
  5. 跨域联调时核对响应头与浏览器报错。

代码或图示

use tower_http::cors::{CorsLayer, AllowOrigin};
use axum::http::header;

let cors = CorsLayer::new()
    .allow_origin(AllowOrigin::exact("https://app.example.com".parse().unwrap()))
    .allow_methods([axum::http::Method::GET, axum::http::Method::POST])
    .allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION]);

常见误区

  • 生产 allow_origin(Any) 又允许凭证:浏览器拒绝,且安全风险高。
  • 只配来源不配方法/头:预检通过但真实请求被拦截。

追问

  • 允许来源支持多域名吗?答:支持列出多个精确来源或按匹配器配置;具体 API 以 tower-http 当前版本为准。
  • 自定义响应头前端读不到怎么办?答:在 expose_headers 中列出该头,否则浏览器隐藏。

04.4.3.3-080 为什么 CORS 层要挂在路由层之外?

一句话结论

CORS 头必须出现在所有响应(含错误响应)上,预检请求要在业务路由之前被拦截;层挂在最外层才能覆盖全部路由与错误分支,内层挂载会漏掉部分响应。

概念解释

tower 层顺序决定请求与响应的经过路径。CORS 需要在请求进入路由前处理预检,并在响应返回时统一追加头。若挂在局部路由内侧,未命中路由的 404、其他层产生的错误响应就缺少 CORS 头,浏览器侧表现为跨域读取失败。全局横切层(CORS、trace、限制)通常位于外层,业务提取与 handler 在内层。

原理流程

  1. 请求到达,外层 CORS 层先判断是否预检。
  2. 预检直接响应;真实请求继续进入内层。
  3. 内层处理后响应返回,CORS 层追加跨域头。
  4. 错误响应同样经过外层,头不遗漏。
  5. 局部路由层只影响自己管辖的路径。

代码或图示

层顺序(外 → 内)
├── CORS / Trace / 限制 / 超时(横切)
├── 鉴权与业务中间件
└── 路由提取器与 handler

常见误区

  • 把 CORS 挂到单个业务路由:其他路径跨域失败。
  • 中间件顺序颠倒:错误响应绕过 CORS 层,头缺失。

追问

  • 如何验证 CORS 覆盖完整?答:对 404、422、500 响应分别检查是否带 Access-Control-Allow-Origin 头。
  • 多套 CORS 策略怎么配?答:按路由分组挂载不同 CORS 层,全局默认策略在外层,局部策略覆盖内层。

04.4.3.3-081 超时层不生效常见原因有哪些?

一句话结论

常见原因:层挂载位置在 handler 内层、超时 Future 内部持续 spawn 独立任务未被取消、长连接路由被套上普通超时、超时值配置过大或单位错误。

概念解释

超时层包裹的是它下游的服务 Future;位置在内层时只覆盖部分路径,或被内部派生任务绕开。TimeoutLayer 取消的是被包裹的 Future,层内 tokio::spawn 出去的任务不受影响。SSE/WebSocket 不能套用普通请求超时,否则连接被定期切断。排查时先确认层位置,再看超时是否真的包裹了目标 handler,最后核对时长配置。

原理流程

  1. 核对层挂载位置:是否在目标路由外层。
  2. 检查 handler 内是否派生了不受取消的任务。
  3. 确认长连接路由未被普通超时覆盖。
  4. 核对超时时长与单位(Duration)。
  5. 用慢依赖测试超时是否在阈值触发。

代码或图示

不生效原因
├── 层挂在内层,目标路径未经过
├── 内部 spawn 的任务不随 Future 取消
├── 超时作用于 SSE/WS 长连接被误切或误挂
├── Duration 单位错误(秒/毫秒)
├── 下游不响应取消,超时后仍占用资源
└── 错误响应被其他层吞掉,看似未触发

常见误区

  • 以为超时层能杀死下游服务进程:它只取消本地等待 Future,不向服务端发取消信号。
  • 全局超时覆盖所有路由:长连接需要排除或单独配置。

追问

  • 如何测试超时生效?答:handler 内 sleep 超过阈值,断言返回超时响应且任务被取消。
  • 超时后连接复用受影响吗?答:本地 Future 取消后 body 可能未读完,连接行为按 hyper 实现处理;重要接口可关闭连接。

04.4.3.3-082 body 限制层与读取顺序有什么关系?

一句话结论

限制层必须位于 body 被业务读取之前:层在读取流上计数,超限即中止;挂在提取器或 handler 内侧时 body 已进入业务缓冲,限制失去意义。

概念解释

body 限制包装的是请求 body 流:每读一块计数一次,超限返回错误。层位置决定它是否在业务读取路径上。Json/ByteStream 等提取器消费 body,限制层要在它们外层。顺序错误的表现:大请求仍进入 handler,内存峰值不受控;或限制层重复包装导致计数行为异常。

原理流程

  1. 请求进入,限制层包裹 body 流。
  2. 业务提取器读取 body,每块经过层内计数。
  3. 超限 → 层中止读取并返回错误。
  4. 未超限 → 完整 body 交给业务。
  5. 上传路由单独覆盖更宽松阈值。

代码或图示

use tower_http::limit::RequestBodyLimitLayer;

let app = Router::new()
    .route("/upload", axum::routing::post(upload))
    .layer(RequestBodyLimitLayer::new(50 * 1024 * 1024));

常见误区

  • 限制层挂在路由内部中间件之后:body 已被部分消费。
  • 上传路由忘记放宽:合法大文件被 413 拒绝。

追问

  • 限制层能限制 WebSocket 帧大小吗?答:不能,WS 帧不经过 HTTP body 读取路径,需在帧处理循环内单独限制。
  • 超限后已读取的 body 怎么办?答:中止读取,按连接策略关闭或丢弃剩余 body;具体行为以层与 hyper 实现为准。

04.4.3.3-083 流式响应如何设置响应头与分块编码?

一句话结论

流式 body 由框架按分块传输写出;业务侧通过响应构造器设置 Content-Type、Content-Disposition、缓存等头,无需手动写 Transfer-Encoding。

概念解释

HTTP/1.1 流式响应通常使用 chunked 分块编码,由 hyper 根据 body 类型自动处理。业务需要设置的是语义头:内容类型、下载文件名、缓存策略、最后修改时间。SSE 有自己的 text/event-stream 类型与保活配置。响应头必须在 body 写出前设置;流开始后再改头不会生效。

原理流程

  1. 构造响应前确定流数据源与元信息。
  2. 设置语义响应头(类型、文件名、缓存)。
  3. 用 Body::from_stream 包装流。
  4. 框架按流写出,分块编码由协议层处理。
  5. 流结束后响应关闭。

代码或图示

use axum::response::{Response, IntoResponse};
use axum::body::Body;
use bytes::Bytes;
use futures::stream::iter;

let stream = iter(vec![Ok::<Bytes, std::convert::Infallible>(Bytes::from("a"))]);
Response::builder()
    .header("content-type", "text/csv")
    .header("content-disposition", "attachment; filename=\"data.csv\"")
    .body(Body::from_stream(stream))
    .unwrap()

常见误区

  • 手动设置 Transfer-Encoding: chunked:与框架自动行为冲突,可能导致报文异常。
  • 流开始后追加响应头:头已提交,修改不生效。

追问

  • 如何设置文件长度?答:已知总大小可设 Content-Length;未知大小走分块传输;断点续传依赖长度与范围支持。
  • 下载文件名含中文怎么处理?答:按 RFC 格式编码 filename*,避免乱码;具体编码方式按 HTTP 规范。

04.4.3.3-084 spawn_blocking 线程池规模怎么调?

一句话结论

阻塞线程池默认按 CPU 核数与配置上限运行,任务类型(IO 等待 vs CPU 计算)决定规模调整方向;高并发阻塞任务需要评估池容量与排队等待,而不是盲目调大。

概念解释

Tokio 阻塞线程池用于承载同步阻塞代码,默认上限与运行时配置相关。IO 等待型任务占用线程时间长但不耗 CPU,可以适当增加线程;CPU 密集型任务线程数不宜超过核数,否则上下文切换放大。池满后新阻塞任务排队,表现为延迟上涨。规模应通过压测观察排队与耗时确定,不照搬默认值。

原理流程

  1. 区分阻塞任务类型:IO 等待或 CPU 计算。
  2. 压测记录阻塞任务并发数、等待时长、池占用。
  3. IO 型按等待时长调整线程上限;CPU 型贴近核数。
  4. 监控排队任务数与阻塞耗时。
  5. 必要时改用异步库或独立线程池隔离。

代码或图示

# #[tokio::main(flavor = "multi_thread", worker_threads = 4)]
# async fn main() {
// 运行时配置影响工作线程数;阻塞线程池上限通过 Builder 配置
// 具体配置项名称与默认值以 Tokio 当前版本文档为准
# }

常见误区

  • 把阻塞池调到无限大:内存与线程数失控,上下文切换拖垮系统。
  • CPU 密集任务用阻塞池并行:应评估 rayon 等并行方案,避免阻塞线程池被占满。

追问

  • 阻塞任务排队怎么观察?答:运行时指标或自定义计数记录 spawn_blocking 等待与执行时长;排队增长说明池容量不足。
  • 阻塞任务有独立超时吗?答:JoinHandle 可配合 timeout 等待;阻塞线程本身不被超时中断,只能放弃等待。

04.4.3.3-085 阻塞任务 panic 如何隔离?

一句话结论

spawn_blocking 内 panic 不会拖垮工作线程,错误在 JoinHandle::await 处表现为 JoinError;边界要捕获并转为业务错误,记录 panic 位置,避免错误沿任务链扩散。

概念解释

Tokio 任务 panic 会被运行时捕获:任务结束,错误通过 JoinHandle 返回。阻塞任务 panic 隔离在阻塞线程内,不会直接终止整个进程(除非配置 panic=abort)。handler 边界 await 句柄时匹配 JoinError,区分 panic 与取消,映射为 500 并记录日志。其他请求不受该任务影响;共享状态在 panic 后是否一致取决于锁与数据结构设计。

原理流程

  1. 阻塞闭包内发生 panic。
  2. 运行时捕获 panic,任务标记失败。
  3. JoinHandle::await 返回 Err(JoinError)。
  4. 边界匹配错误类型,记录位置与消息。
  5. 映射为内部错误响应,继续服务其他请求。

代码或图示

let handle = tokio::task::spawn_blocking(|| risky_sync_code());
match handle.await {
    Ok(Ok(v)) => Ok(v),
    Ok(Err(e)) => Err(AppError::from(e)),
    Err(join) => {
        tracing::error!(error = ?join, "blocking task panicked");
        Err(AppError::Internal)
    }
}

常见误区

  • 忽略 JoinError 直接 unwrap:panic 会把错误再抛进异步任务链。
  • 以为 panic 后共享数据仍一致:锁守卫在 panic 时释放,但业务不变量可能已被破坏。

追问

  • 什么情况下 panic 会终止进程?答:panic = "abort" 策略,或在非 Tokio 线程/ main 线程未捕获的 panic;运行时任务默认捕获。
  • 如何记录 panic 位置?答:JoinError 不含完整回溯,可在闭包内捕获 panic 消息,或配合 panic hook 采集;具体可行性按版本实现。

04.4.3.3-086 如何在响应流中注入请求 ID 与追踪上下文?

一句话结论

请求 ID 在进入流之前从扩展或状态取到,克隆进流闭包;每个事件或日志字段带上该 ID;跨任务传播时随消息句柄一起传递,保证流内日志与响应可关联。

概念解释

流式任务生命周期长,日志排查依赖贯穿全程的请求/追踪 ID。ID 在中间件阶段生成,放入请求扩展;流构造时读取克隆。流内派生的任务、通道消息都要携带该 ID,否则日志断链。tracing span 可以在任务启动时绑定字段,流内日志自动继承;跨实例总线消息也要带上追踪 ID。

原理流程

  1. 外层中间件生成请求 ID,写入扩展。
  2. handler/流构造时读取 ID 并克隆进闭包。
  3. 流内事件与日志附带 ID 字段。
  4. 派生任务与通道消息传递 ID。
  5. 总线消息跨实例携带追踪上下文。

代码或图示

# use axum::Extension;
# #[derive(Clone)] struct RequestId(String);
async fn events(Extension(req_id): Extension<RequestId>)
    -> axum::response::sse::Sse<impl futures::stream::Stream<Item = Result<axum::response::sse::Event, std::convert::Infallible>>> {
    let id = req_id.0.clone();
    let stream = futures::stream::once(async move {
        tracing::info!(request_id = %id, "stream event");
        Ok(axum::response::sse::Event::default().data(format!("event:{id}")))
    });
    axum::response::sse::Sse::new(stream)
}

常见误区

  • 流内任务丢失 ID:长连接日志无法关联到原始请求。
  • 跨实例消息不带追踪 ID:总线扇出后链路断裂。

追问

  • tracing span 如何在流任务中保留?答:在任务启动处创建 span 并在其内 poll 流;跨任务传递需要显式携带字段或使用上下文传播机制。
  • 响应体里也要带 ID 吗?答:错误事件带 ID 便于客户端反馈;正常事件不必每条携带。

04.4.3.3-087 长轮询与 SSE 如何选型?

一句话结论

服务端单向推送、客户端支持 EventSource 时优先 SSE;需要兼容受限环境(代理、旧浏览器)或双向简单交互时考虑长轮询;两者都是 HTTP 长请求,资源模型相近。

概念解释

长轮询:客户端发起请求,服务端挂起直到有事件或超时,返回后客户端立即再发下一次请求;SSE:一条连接持续推送事件。SSE 有标准事件格式、自动重连与 ID 续传;长轮询实现简单、兼容性好,但每次请求重建连接,延迟与开销更高。选型看客户端环境、交互方向与基础设施兼容性。WebSocket 适合双向高频场景。

原理流程

  1. 判断客户端环境是否支持 SSE。
  2. 交互方向是否为单向推送。
  3. 代理/防火墙是否允许长连接。
  4. 满足 SSE 条件 → SSE;否则长轮询。
  5. 双向高频 → WebSocket。

代码或图示

方案对比
├── SSE:标准事件流、自动重连、单向、HTTP 兼容好
├── 长轮询:每次请求挂起→返回→重连,兼容性最好
├── WebSocket:全双工、帧协议、需心跳与连接管理
└── 选择:方向 × 环境 × 基础设施约束

常见误区

  • 长轮询复用普通请求超时配置:挂起时间需要专门放宽,否则被超时层切断。
  • SSE 在不支持的网络环境强行使用:连接被代理缓冲或断开。

追问

  • 长轮询如何避免连接堆积?答:控制挂起时长与并发上限,超时返回空结果让客户端重连;服务端按连接维护等待队列。
  • SSE 能被中间层缓存吗?答:配置 no-cache 并确认代理不缓冲,见 04.4.3.3-038。

04.4.3.3-088 服务端推送在多实例部署下有哪些约束?

一句话结论

连接状态是实例本地的,跨实例事件必须经消息总线扇出;需要考虑消息顺序、重复投递、实例故障迁移、连接路由与总线容量,单实例内存表不能作为全局连接注册中心。

概念解释

多实例部署后,事件产生在一个实例,目标连接可能在另一个实例。约束包括:总线订阅全房间事件、本地连接表只管理本实例连接;消息可靠性(至少一次投递、幂等处理);实例下线时其连接由客户端重连;总线成为瓶颈时需分片扩容。连接不需要粘性会话,因为总线会把事件路由到连接所在实例。

原理流程

  1. 实例启动订阅总线频道,维护本地连接表。
  2. 事件发布到总线,各实例收到后推送本地连接。
  3. 消息带 ID 与幂等键,容忍重复投递。
  4. 实例故障,客户端重连到其他实例并重新订阅。
  5. 总线容量与延迟纳入监控。

代码或图示

多实例约束
├── 本地表:只存本实例连接
├── 总线:房间频道扇出,跨实例路由
├── 可靠性:至少一次 + 幂等处理
├── 迁移:实例下线 → 客户端重连重建订阅
├── 容量:总线分片、消息积压监控
└── 顺序:单连接内有序,跨连接不保证全局序

常见误区

  • 用本地 Redis 缓存维护全局连接表而不更新实例归属:跨实例推送找不到连接。
  • 总线消息直接复制大载荷:带宽随实例数放大。

追问

  • 房间成员列表如何全局维护?答:成员变更事件经总线广播,各实例维护本地视图;定期全量对账。
  • 总线宕机影响推送吗?答:总线故障期间事件积压或丢失,需评估降级策略(拉取补偿、状态快照)。

04.4.3.3-089 事故复盘:内存暴涨可能由哪些实时通信场景引起?

一句话结论

常见场景:无界通道缓冲事件、慢连接持有未发消息、大消息/大文件走内存、历史事件缓存过长、连接对象泄漏、总线消息在各实例重复缓冲;复盘要按段定位积压并给出限制与断开策略。

概念解释

内存暴涨复盘先区分是连接数增长、消息缓冲增长还是对象泄漏。实时通信链路各段都可能堆积:生产总线、连接发送队列、历史事件缓冲、二进制消息副本。慢连接不消费是最常见诱因;大消息放大单块占用;泄漏表现为连接对象与表条目只增不减。复盘输出应包含:触发条件、定位指标、根因、修复措施与防护指标。

原理流程

  1. 事故现象:RSS 上涨、OOM 或延迟恶化。
  2. 采集连接数、队列长度、消息大小、任务数指标。
  3. 分段定位积压位置(总线/连接队列/缓存/泄漏)。
  4. 复现路径:并发连接 + 慢消费 + 大消息。
  5. 修复:有界队列、背压、超时断开、限制消息大小、清理泄漏。

代码或图示

复盘清单
├── 通道是否有界,满时策略是否生效
├── 慢连接是否被识别并断开
├── 消息体大小是否失控
├── 历史缓冲窗口是否过长
├── 连接表条目是否泄漏
├── 跨实例消息是否重复缓冲
└── 防护:队列长度、连接数、消息大小告警

常见误区

  • 复盘结论只写“加内存”:根因未除,扩容后再次暴涨。
  • 不记录触发条件:同类事故无法复现与验证修复。

追问

  • 如何区分泄漏与正常积压?答:积压在流量回落后队列长度回落;泄漏条目数不随流量下降,持续单调上涨。
  • 修复后如何防回归?答:为队列长度、连接数、消息大小加监控与阈值告警,压测覆盖慢连接场景。

04.4.3.3-090 事故复盘:连接泄漏如何定位与修复?

一句话结论

定位靠连接表条目数、任务数、FD 数与注册/注销计数对账;修复补齐遗漏的注销路径,保证正常关闭、错误断开、超时、停机四类退出都触发清理,并补充对账监控防回归。

概念解释

泄漏复盘先建立对账基线:在线连接计数器、表长度、运行时任务数、进程 FD。事故中观察哪个指标只增不减,对应到退出路径。常见缺陷:注销只在 Close 帧分支、发送失败未移除、派生任务持有句柄、通道未关闭。修复要让所有退出路径走同一注销函数,并验证压测后条目回落。

原理流程

  1. 建立指标:注册数、注销数、表长度、任务数、FD。
  2. 事故中对账:注册与注销差值是否持续扩大。
  3. 列出连接退出路径,逐条核对注销是否执行。
  4. 修复遗漏路径,注销幂等并关闭通道。
  5. 压测复现场景,验证条目回落与监控告警。

代码或图示

定位步骤
├── 指标对账:注册 - 注销 = 表条目
├── 任务/FD 是否随条目增长
├── 分类退出路径:Close 帧 / recv 错误 / 超时 / 停机
├── 找到未注销路径并补齐
├── 验证:压测后条目归零回落
└── 防回归:条目数与任务数监控告警

常见误区

  • 重启服务当作修复:泄漏路径仍在,流量恢复后复发。
  • 注销函数非幂等:重复退出事件触发报错,反而掩盖残留。

追问

  • 派生任务泄漏怎么发现?答:任务数指标与连接数不匹配;任务持有连接句柄时,主循环退出后任务仍存活。
  • 弱引用能否防泄漏?答:可用于清扫兜底,但主路径必须显式注销;弱引用只作为最后防线。

04.4.3.3-091 事故复盘:超时不生效的排查路径是什么?

一句话结论

按“层位置 → Future 包裹范围 → 内部派生任务 → 时长配置 → 下游取消传播”逐层核对,先确认超时是否真的包裹目标 handler,再排查被内部任务绕开的路径。

概念解释

超时不生效分两类:超时根本没作用到目标路径,或超时触发后资源未释放。排查顺序从外到内:层挂载位置是否覆盖路由;被包裹 Future 是否包含全部等待;handler 内 spawn 的任务是否独立于取消;Duration 配置是否正确;下游操作是否响应取消。复盘要给出可复现的慢依赖用例,验证超时在阈值内触发并返回错误。

原理流程

  1. 核对层顺序与路由归属,确认请求经过超时层。
  2. 用可控慢依赖测试,观察是否在阈值返回超时。
  3. 检查 handler 内派生任务与通道是否脱离 Future 取消。
  4. 核对时长、单位与环境配置。
  5. 验证超时后连接、任务、数据库连接是否释放。

代码或图示

排查路径
├── 层位置:目标路由是否经过 TimeoutLayer
├── 包裹范围:等待链是否全部在超时 Future 内
├── 派生任务:spawn 出去的任务不随取消退出
├── 配置:Duration 数值与环境变量
├── 下游:取消是否传播到数据库/HTTP 客户端
└── 释放:超时后资源是否回落

常见误区

  • 只看响应没超时就改大其他配置:未定位包裹范围问题。
  • 忽略内部 spawn:主 Future 超时退出,后台任务继续占用资源。

追问

  • 下游 HTTP 调用如何响应取消?答:客户端请求随 Future 取消而中断连接;服务端是否停止处理取决于其自身超时与取消支持。
  • 超时层与 body 限制层顺序怎么排?答:两者都属横切外层,超时控制整体时长,限制控制 body 大小;具体顺序按层职责验证。

04.4.3.3-092 事故复盘:SSE 客户端不断重连如何定位?

一句话结论

重连循环通常由服务端流异常结束、代理空闲断开、KeepAlive 未配置或认证失败引起;定位先看服务端日志的流退出原因,再核对代理超时与心跳配置。

概念解释

EventSource 断线后自动重连,客户端表现为反复建立连接。服务端侧要区分:流内错误终止、任务被取消、代理空闲关闭、认证令牌过期。排查收集:重连频率、服务端流退出日志、代理访问日志、响应头与心跳帧。常见修复:配置 KeepAlive、放宽代理空闲超时、修复流内错误、令牌过期后引导重新获取。

原理流程

  1. 统计重连频率与每次连接存活时长。
  2. 服务端日志查流退出原因(错误/取消/断连)。
  3. 核对代理与 LB 空闲超时是否短于心跳间隔。
  4. 检查 KeepAlive 配置与事件推送节奏。
  5. 验证认证令牌在重连时是否有效。

代码或图示

定位清单
├── 流退出日志:错误事件、任务取消、recv 失败
├── 代理日志:连接是否被空闲超时关闭
├── 心跳:KeepAlive 间隔与帧是否到达
├── 认证:重连请求令牌是否过期
├── 网络:弱网或移动后台切换导致断连
└── 修复:心跳配置 / 错误修复 / 令牌刷新

常见误区

  • 只在客户端加重连退避:服务端流异常未修复,重连只是掩盖问题。
  • 心跳间隔长于代理超时:连接在下次心跳前被关闭。

追问

  • 如何区分代理断开与服务端主动结束?答:服务端日志有主动退出记录为服务端结束;无记录且连接存活时间接近代理超时阈值,多为中间层断开。
  • 重连风暴怎么缓解?答:客户端指数退避,服务端对频繁重连限流;修复根因后再观察频率。

04.4.3.3-093 事故复盘:WebSocket 广播风暴如何限流?

一句话结论

广播风暴来自消息频率过高、房间连接数过大或消息重复扩散;限流手段包括按房间限速、合并高频事件、限制单连接发送速率、切断环路与重复投递,并监控广播队列长度。

概念解释

风暴场景:高频状态更新全量推送给大房间、事件在多房间间循环转发、总线重复投递放大。治理分三层:生产侧合并与采样高频事件;路由侧按房间限速、阻断环路;连接侧单连接队列与发送速率限制。消息带序号与去重键,重复投递不重复扩散。复盘要定位放大环节:是生产过快、房间过大还是环路转发。

原理流程

  1. 统计消息生产速率、房间规模、广播队列长度。
  2. 定位放大环节:高频事件、环路、重复投递。
  3. 生产侧合并/采样,降低事件频率。
  4. 房间级限速与单连接队列限制。
  5. 去重键阻断重复扩散,监控队列与发送速率。

代码或图示

治理措施
├── 高频事件:节流合并,只推最新状态
├── 房间限速:单位时间广播条数上限
├── 单连接:队列长度与发送速率限制
├── 环路:消息路径标记,阻断二次转发
├── 去重:消息 ID 幂等,重复投递不扩散
└── 监控:队列长度、发送速率、丢弃计数

常见误区

  • 风暴时直接断开大房间所有连接:影响面大,应先限速再逐步治理。
  • 不在消息里带路径标记:环路无法识别,重复转发越滚越大。

追问

  • 高频状态推送要不要全量发送?答:可只推变化字段或最新快照,订阅端自行合并历史状态。
  • 广播队列满了怎么处理?答:按消息类型策略:状态类丢弃旧值只留最新,事件类排队或拒绝;记录丢弃指标。

04.4.3.3-094 错误处理上线前要补哪些监控指标?

一句话结论

核心指标:按状态码与错误码统计的错误率、5xx 计数、panic 次数、超时与 body 超限计数、错误链根因分布;配合请求 ID 关联日志与告警阈值。

概念解释

错误处理不能只靠代码评审上线。监控要覆盖协议层(状态码)、业务层(错误码)、运行层(panic、超时、拒绝)。指标维度:接口、错误码、根因类别、实例。告警分级:5xx 与 panic 立即告警,4xx 异常上涨关注趋势。错误日志结构化,携带请求 ID 与错误链,便于从指标下钻到具体请求。

原理流程

  1. 定义错误指标:状态码计数、错误码计数、panic 计数。
  2. 补充超时、body 超限、提取器拒绝计数。
  3. 按接口、实例、错误码打标签。
  4. 配置分级告警阈值。
  5. 日志携带请求 ID,支持指标到请求下钻。

代码或图示

指标清单
├── HTTP 状态码分布:2xx/4xx/5xx
├── 业务错误码计数:按 code 聚合
├── 5xx 与 panic 次数
├── 超时触发次数、body 超限次数
├── 提取器拒绝计数与原因
├── 根因分布:DB / IO / 校验 / 下游
└── 日志:request_id、错误链、接口路径

常见误区

  • 只监控 5xx:4xx 异常上涨可能反映客户端兼容或接口变更问题。
  • 错误日志不带错误码:无法按业务场景聚合趋势。

追问

  • 错误率告警阈值怎么定?答:按历史基线设动态阈值,5xx 绝对数与占比同时监控;新接口先观察再定阈值。
  • 如何统计根因分布?答:在错误映射时记录底层类别(DB、下游、IO、校验),作为指标标签。

04.4.3.3-095 实时接口压测要关注哪些指标?

一句话结论

关注连接数、消息收发速率、队列积压、内存与 FD 占用、推送延迟(P50/P99)、错误率与心跳成功率;长连接压测要包含慢连接与断连重连场景。

概念解释

实时接口压测不同于普通请求压测:连接长期保持,资源随连接数累积。指标分四类:规模(在线连接、房间数)、吞吐(消息速率、带宽)、延迟(事件到送达时间)、资源(内存、CPU、FD、队列)。场景要覆盖:正常推送、慢消费者、突发大量连接、断连重连、广播大房间。压测找到连接数与消息速率的拐点,作为扩容水位依据。

原理流程

  1. 设计场景:基准连接、大房间广播、慢连接、重连风暴。
  2. 逐步加压,记录连接数与消息速率。
  3. 采集延迟分位、队列长度、资源占用。
  4. 定位拐点:内存/延迟/错误率恶化点。
  5. 确定安全水位与扩容阈值。

代码或图示

压测指标
├── 规模:在线连接数、房间数、订阅数
├── 吞吐:消息生产/发送速率、出入带宽
├── 延迟:事件产生到送达 P50/P99
├── 资源:内存、CPU、FD、线程数
├── 积压:总线队列、连接队列长度
├── 稳定性:错误率、心跳成功率、重连次数
└── 场景:慢连接、大房间、突发连接、断连

常见误区

  • 只压短请求吞吐:长连接资源累积问题暴露不出来。
  • 不模拟慢消费者:背压与积压问题无法验证。

追问

  • 推送延迟怎么测量?答:消息带生产时间戳,接收端计算到达延迟;区分生产延迟、队列等待与网络传输。
  • 压测环境要注意什么?答:连接与消息量级接近生产,关闭不必要日志;单独验证心跳超时与断开清理路径。

04.4.3.3-096 如何为错误响应补充 OpenAPI 文档?

一句话结论

为每个接口声明可能返回的错误响应状态码与错误体结构,错误体复用统一 ErrorResponse schema;文档与 IntoResponse 映射保持一致,新增错误变体时同步更新文档。

概念解释

错误响应也是接口契约的一部分。OpenAPI 文档列出各状态码对应的响应体结构,前端据此处理错误分支。实现上按项目使用的 OpenAPI 库(如 utoipa 等)为错误体结构体标注 schema,在接口注解中声明 400/401/403/404/422/500 响应。文档与代码不一致是常见问题,应在错误映射变更时同步审查;具体 derive 与配置方式以所选库当前版本为准。

原理流程

  1. 定义统一错误体结构体并标注 schema。
  2. 接口声明各错误状态码引用同一错误体 schema。
  3. 业务错误码枚举在文档中列出含义。
  4. 代码与文档变更走同一审查流程。
  5. 生成 OpenAPI 规范并校验示例可解析。

代码或图示

// 具体 derive 与注解属性以所选 OpenAPI 库当前版本为准
#[derive(serde::Serialize)]
struct ErrorBody {
    code: String,
    message: String,
    request_id: String,
}

// 接口响应声明:200 成功;404 / 422 / 500 返回 ErrorBody

常见误区

  • 文档只写成功响应:前端无法预知错误结构,只能靠运行时摸索。
  • 错误体结构多处重复定义:文档 schema 不一致,应复用统一类型。

追问

  • 字段级 422 错误怎么写文档?答:在错误体 schema 中加入字段错误列表结构,说明每项包含字段名与消息。
  • 错误码枚举需要文档化吗?答:需要,列出码值、含义与触发场景,便于前后端对齐。

04.4.3.3-097 第三方回调失败如何重试与降级?

一句话结论

失败按错误类型分类:可重试错误(网络、5xx)走指数退避重试,不可重试错误(4xx、参数错误)直接记录;重试有上限与死信队列,降级时返回缓存或默认结果并标记数据时效性。

概念解释

调用第三方服务或接收回调都可能失败。重试策略要区分暂时性失败与永久性失败:连接超时、502/503/504 可重试;400/401/403 不重试。退避间隔指数增长并加抖动,避免重试同步放大。超过上限进入死信队列人工或异步处理。降级按业务容忍度:返回缓存数据、静态默认值或提示稍后重试,响应中标记数据可能过期。

原理流程

  1. 调用失败先分类:可重试 / 不可重试。
  2. 可重试错误按指数退避 + 抖动重试,记录每次尝试。
  3. 达到重试上限 → 死信队列,告警与人工介入。
  4. 不可重试错误直接落库记录与告警。
  5. 降级路径返回缓存/默认值,标注时效性。

代码或图示

重试决策
├── 可重试:超时、连接失败、5xx、限流 429
├── 不可重试:400/401/403、参数校验失败
├── 退避:指数增长 + 随机抖动,上限封顶
├── 上限:最大重试次数,超限进死信
├── 降级:缓存 / 默认值 / 稍后重试提示
└── 标记:响应注明数据可能非实时

常见误区

  • 所有失败都无限重试:永久错误阻塞任务并压垮下游。
  • 重试不加抖动:多个客户端同步重试形成二次峰值。

追问

  • 回调通知第三方失败怎么办?答:本地记录待发送事件,后台任务重试;第三方接收幂等,重复通知不产生副作用。
  • 降级数据如何告知前端?答:响应体加 stale 或 cached 标记,前端提示数据可能延迟。

04.4.3.3-098 实时通信中如何处理时钟与事件顺序?

一句话结论

单连接内消息按发送顺序处理;跨连接、跨实例不保证全局顺序,用单调序号或逻辑时钟表达先后,时钟不同步时以服务端序号为准,客户端按序号排序或丢弃过期事件。

概念解释

顺序问题分三个层级:同一 WebSocket/SSE 连接帧有序;同一房间多连接到达顺序可能不同;跨实例事件经过总线投递顺序不保证。时间戳受客户端时钟漂移影响,不能作为唯一排序依据。实践中服务端为事件分配单调递增序号,消息带序号与版本;客户端按序号排序、检测缺口、丢弃过期状态。状态类消息可只保留最新版本,覆盖旧事件。

原理流程

  1. 服务端为事件分配房间内单调序号与版本号。
  2. 消息携带序号、版本与产生时间。
  3. 单连接按序接收处理。
  4. 客户端检测序号缺口,请求补发或跳过。
  5. 旧版本事件被新版本覆盖,不回写状态。

代码或图示

#[derive(serde::Serialize)]
struct EventMsg {
    seq: u64,          // 房间内单调序号
    version: u64,      // 资源版本号
    r#type: String,
    payload: serde_json::Value,
}

常见误区

  • 用客户端时间戳排序:时钟漂移导致顺序错乱。
  • 假设跨实例总线保持全局顺序:总线只保证各自投递,顺序需序号校正。

追问

  • 序号缺口怎么补?答:客户端记录最后连续序号,缺口期间事件可请求历史补发;无法补发时全量拉取状态对账。
  • 状态更新乱序到达怎么办?答:按版本号比较,旧版本直接丢弃,只接受更新版本。

04.4.3.3-099 项目里错误处理与实时通信模块如何分层?

一句话结论

分层为:HTTP 适配层(提取器、IntoResponse)、应用错误层(AppError 映射)、领域服务层(业务规则与具体错误)、实时连接管理层(连接表、房间、总线)、基础设施层(数据库、消息总线、下游客户端);各层错误类型与职责清晰单向依赖。

概念解释

清晰分层便于测试与替换。HTTP 层只做协议转换,不写业务规则;应用错误层统一对外错误码与状态码;领域层返回具体错误;实时管理层维护连接生命周期与消息路由;基础设施层封装外部依赖。依赖方向从上到下,错误沿层向上转换。SSE/WS 连接管理作为独立模块,与业务服务通过消息通道解耦。

原理流程

  1. HTTP 层接收请求,提取参数与状态。
  2. 调用应用服务,服务返回领域错误。
  3. 应用错误层映射为 AppError 并产出响应。
  4. 实时模块订阅事件总线,管理本地连接推送。
  5. 基础设施错误在各模块边界转换为领域错误。

代码或图示

分层结构
├── HTTP 适配:路由、提取器、IntoResponse、SSE/WS 升级
├── 应用错误:AppError、错误码、统一错误体
├── 领域服务:业务规则、具体领域错误
├── 实时管理:连接表、房间、总线订阅、心跳
└── 基础设施:DB、消息总线、下游 HTTP、文件存储

常见误区

  • 在 handler 里写业务规则与数据库操作:层职责混杂,难以测试与替换。
  • 实时连接表散落在各业务模块:连接生命周期无法统一管理与排查。

追问

  • 模块间如何解耦事件推送?答:领域服务发布事件到总线,实时模块订阅后推送;业务不直接操作连接表。
  • 错误类型跨层怎么转换?答:每层定义自己的错误,From 实现完成向上映射;底层细节通过 source 保留。

04.4.3.3-100 面试中如何讲清一个 axum 实时接口的完整设计?

一句话结论

按“场景与选型 → 路由与认证 → 状态与连接管理 → 消息协议与顺序 → 错误与清理 → 监控压测与运维”的顺序讲述,每个环节落到具体类型、API 与故障场景,体现可落地的工程判断。

概念解释

完整设计回答要覆盖从选型到运维的闭环:为什么用 SSE 或 WebSocket;路由如何注册、认证在哪一步;共享状态与连接表怎么组织;消息格式、序号与背压策略;错误映射、断连清理与心跳;监控指标、压测水位与多实例总线。讲述时结合具体 axum 类型(Router、State、Sse、WebSocketUpgrade、IntoResponse)与真实故障场景(泄漏、积压、超时、重连),避免只讲框架名词。

原理流程

  1. 场景:单向推送还是双向交互,确定 SSE/WS。
  2. 路由:注册 handler,前置认证与 Origin 校验。
  3. 状态:AppState 内含连接表/总线句柄,克隆进升级回调。
  4. 连接:注册注销、心跳超时、房间路由、背压策略。
  5. 协议:消息信封、序号版本、序列化与错误帧。
  6. 运维:错误指标、压测水位、优雅停机、多实例总线。

代码或图示

讲述闭环
场景选型 → 路由认证 → 状态连接管理 → 消息协议顺序
  → 错误清理心跳 → 监控压测 → 优雅停机与多实例

常见误区

  • 只罗列框架功能:缺少故障场景与工程取舍。
  • 忽略多实例与运维:设计停留在单机能跑通。

追问

  • 被追问连接泄漏怎么防?答:注册注销成对、退出路径全覆盖、对账指标监控、压测后验证条目回落。
  • 被追问消息积压怎么办?答:有界队列 + 背压 + 慢连接断开 + 丢弃策略,配合队列长度监控定位积压段。