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

04.4.7.2 Hyper与Tower中间件

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.4 Rust / 04.4.7 异步运行时与协议层

04.4.7.2-001 Hyper 在 Rust Web 生态中处于什么位置,与 axum、actix-web 是什么关系?

一句话结论

Hyper 是一个异步 HTTP 协议库,只负责 HTTP/1.1 与 HTTP/2 的报文编解码和连接管理,不提供路由、序列化或中间件框架;axum 构建在 Hyper 与 Tower 之上,actix-web 则自带基于 Actor 模型的运行时,不依赖 Hyper。

概念解释

Hyper 定位为「协议层」:接收字节流、解析成 Request,把 Response 编码回字节流。路由匹配、参数提取、JSON 序列化、鉴权等业务层能力都由上层框架补齐。axum 的服务最终通过 into_make_service 交给 Hyper 的连接服务循环驱动;actix-web 内部使用自己的 actix-http 与 actor 调度,因此即使同样是异步 Web 框架,底层协议栈并不相同。

原理流程

  1. 业务框架把 handler 包装成一个满足 Tower Service 约束的服务。
  2. Hyper 在每条 TCP 连接上调用该服务处理请求。
  3. Hyper 负责协议协商、帧解析、body 流与连接复用。
  4. 业务框架负责把 Request 拆成提取器参数、把返回值序列化成响应。
  5. 上层框架可以替换:同一套 Tower 服务理论上可由不同协议后端驱动。

代码或图示

// 依赖关系(版本以 docs.rs 当前版本为准)
// axum = { version = "0.8", features = ["macros"] }
// hyper = { version = "1", features = ["server", "http1", "http2"] }
// tower = "0.5"
// 调用链:axum Router -> Tower Service 栈 -> Hyper 连接循环 -> 操作系统 socket

常见误区

  • 以为 Hyper 是 Web 框架:它没有路由表,也没有 JSON 提取器。
  • 以为 actix-web 也基于 Hyper:actix-http 是独立实现,与 Hyper 无依赖关系。

追问

  • 为什么主流 Rust Web 框架都围绕 Tower 抽象?答:Tower 把「请求进、响应出」的服务与层组合标准化,Hyper、tonic 等协议层都围绕该抽象适配,框架可以复用同一批中间件。
  • 直接用 Hyper 写业务可行吗?答:可行但需要手写协议服务与服务组装,生产环境通常再叠 Tower 层或上层框架。

04.4.7.2-002 Hyper 1.x 相比 0.14 在类型模型上有哪些主要变化?

一句话结论

1.x 把请求/响应体从自带的 hyper::Body 改为通用的 Incoming 与 http-body trait 体系,高层客户端迁移到 hyper-util,服务端也改为由调用方自行 accept 连接后逐条 serve_connection。

概念解释

0.14 时代 Hyper 自带 Body 类型作为统一 body;1.x 解耦为 http-body 与 http-body-util 生态:入站 body 类型是 hyper::body::Incoming,出站 body 实现 http_body::Body。这使得不同库实现的 body 类型可以互换,例如 SSE 流、文件流、prost 编码流。高层 Client 在 1.x 移到 hyper-util 的 legacy 模块,内核只保留低层握手 API。

原理流程

  1. 升级依赖后,旧代码里的 hyper::Body::from(..) 需要替换为 Incoming 之外的 body 类型或 Full。
  2. 读取 body 改用 BodyExt::collect 或 to_bytes。
  3. 客户端按需引入 hyper-util 的 legacy Client。
  4. 服务端自己维护 TcpListener::accept 循环,对每条流调用连接服务。
  5. 跨库 body 转换通过 http_body_util 提供的适配器完成。

代码或图示

use hyper::{body::Incoming, Request, Response};
use http_body_util::BodyExt;

// 1.x 入站 body 是 Incoming;收集为 Bytes
async fn echo(req: Request<Incoming>) -> Result<Response<Incoming>, hyper::Error> {
    let _bytes = req.into_body().collect().await?.to_bytes();
    Ok(Response::new(req.into_body()))
}

常见误区

  • 仍按 0.14 记忆 hyper::Body 作为响应 body:1.x 编译会找不到该类型。
  • 以为 1.x 内核仍带高层客户端:通用客户端在 hyper-util,需额外依赖。

追问

  • 1.x 为什么要解耦 body 类型?答:让 body 实现可插拔,流式压缩、SSE、gRPC 流等不同场景各自实现 http_body::Body,而不是被单一 Body 类型锁死。
  • 升级时如何确认旧 API 对应关系?答:以 docs.rs 上 hyper 1.x API 文档与 hyper-util 文档为准,待确认点逐项对照迁移指南。

04.4.7.2-003 Request、Response、HeaderMap 这些类型来自哪个 crate,Hyper 做了什么?

一句话结论

Request<T>、Response<T>、Method、StatusCode、HeaderMap、Uri 都来自 http crate,Hyper 只负责把这些类型与网络字节流对接,类型本身不定义在 Hyper 内。

概念解释

http crate 是 Rust 生态共享的 HTTP 类型定义层,Hyper、axum、tonic、reqwest 都复用同一套请求响应模型。这样服务在不同库之间传递时不需要类型转换。Request<T> 的泛型 T 是 body 类型:服务端入站通常是 Incoming,客户端或自构造请求可以是 Full<Bytes> 等 body 实现。HeaderMap 按名字存放多值头部,大小写按 HTTP 规范做不敏感匹配。

原理流程

  1. Hyper 解析字节流得到头部与起始行,构造 http::request::Parts。
  2. body 以 Incoming 句柄形式挂到 Request<Incoming> 上。
  3. 业务层读取或修改 Headers、Method、Uri。
  4. 返回 Response<BodyImpl>,Hyper 按协议编码回写。
  5. 跨库传递时复用 http 类型,避免重新建模。

代码或图示

use hyper::{Request, Response, StatusCode, header};

fn build() -> Response<String> {
    Response::builder()
        .status(StatusCode::OK)
        .header(header::CONTENT_TYPE, "text/plain; charset=utf-8")
        .body("hello".to_string())
        .unwrap()
}

常见误区

  • 以为头部字段名是大小写敏感的:HeaderMap 内部按规范做大小写不敏感存储。
  • 以为 Request 的 body 一定是字符串:泛型参数才决定 body 类型。

追问

  • Parts 与完整 Request 的区别?答:Parts 是去掉 body 的请求头部视图,适合提取器在不消费 body 的阶段使用。
  • 为什么生态要共用 http crate?答:降低框架间互操作成本,Tower 服务、中间件、协议层共享同一套类型语义。

04.4.7.2-004 什么是 Incoming,为什么 1.x 不再提供统一的 hyper::Body?

一句话结论

Incoming 是 Hyper 1.x 的入站 body 句柄,实现 http_body::Body,按帧拉取数据;不再内置统一 Body 是为了让出站 body 可以是任意 Body 实现,接入流式、压缩或协议专用流。

概念解释

0.14 的 Body 既是入站也是出站类型,底层用一个枚举包装数据帧;1.x 把「拉取流」的契约抽象到 http_body::Body trait。入站流由 Hyper 用 Incoming 实现,出站响应可以传 Full<Bytes>、StreamBody、文件流或压缩流。业务代码读 body 时通过 BodyExt 提供的适配器收集或逐帧遍历。

原理流程

  1. 请求到达,Hyper 把未读完的 body 挂在 Incoming 上。
  2. 调用 collect().await 逐帧拉取直到 End,得到 Collected。
  3. 用 to_bytes() 取 Bytes,避免拷贝整块。
  4. 响应侧选择一个 http_body::Body 实现交给 Response::new。
  5. Hyper 编码时按 trait 拉帧,不关心具体实现类型。

代码或图示

use http_body_util::{BodyExt, Full};
use hyper::{body::Incoming, Request, Response};
use bytes::Bytes;

async fn handler(req: Request<Incoming>) -> Result<Response<Full<Bytes>>, hyper::Error> {
    let body = req.into_body().collect().await?.to_bytes();
    Ok(Response::new(Full::new(Bytes::from(format!("echo: {body:?}")))))
}

常见误区

  • 把 Incoming 当成可重复读取的 buffer:它是流,读过的帧不再回溯。
  • 给 Response::new 传一个 String:需要包装成 body 实现,例如 Full::new(Bytes::from(..))。

追问

  • http_body::Body 的核心关联类型有哪些?答:Data 帧类型、Error 类型,以及 poll_frame 拉取方法;待确认当前版本精确签名以 docs.rs 为准。
  • 入站流提前丢弃会发生什么?答:未读完的 body 可能影响连接复用或被协议层中断,具体行为依 HTTP 版本与实现而定。

04.4.7.2-005 为什么说 Hyper 的 body 是流而不是一次性缓冲?

一句话结论

body 按帧异步拉取,业务层可以边读边处理或转发,避免把整个请求/响应一次性读进内存;代价是 body 只能消费一次,读取位置不可回溯。

概念解释

HTTP 报文在网络上分段到达,服务端一开始并不知道最终长度(分块传输)或 body 很大。Hyper 用异步流暴露数据帧:调用方 poll_frame 拿到一帧就处理一帧。这种模型支持大文件上传下载、SSE 与流式转发。一旦某帧被消费,就不能再从流开头重放;需要重放时必须自行缓存已读数据。

原理流程

  1. 连接上的数据到达,协议层解析出 body 帧。
  2. BodyExt 的 collect 或自定义循环逐帧拉取。
  3. 业务可在拉取过程中写下游流(代理转发)。
  4. 流返回 None 或 End 表示 body 结束。
  5. 中途断开则产生 Error,连接进入不可复用状态。

代码或图示

use futures_util::StreamExt;
use http_body_util::BodyExt;

// 逐帧遍历入站 body(示意;StreamExt 需引入 futures 相关依赖)
async fn drain(req: hyper::Request<hyper::body::Incoming>) -> Result<(), hyper::Error> {
    let mut body = req.into_body();
    while let Some(frame) = body.frame().await {
        let _frame = frame?;
    }
    Ok(())
}

常见误区

  • 以为把 Request clone 一份就能读两次 body:body 句柄不可复制。
  • 在流式场景里先 collect 全量再转发,大 body 时内存被打满。

追问

  • 流式上传如何限制内存?答:在读取循环里控制缓冲水位,超过阈值即背压等待下游消费,而不是无限累积帧。
  • 代理转发为什么适合流模型?答:上游来一帧就写一帧到下游,两端缓冲都保持小水位。

04.4.7.2-006 手写一个最小 Hyper 服务需要哪些步骤?

一句话结论

用 service_fn 把异步闭包装成服务,监听 TcpListener,对每条连接用 http1::Builder::serve_connection 驱动,配合 TokioIo 适配器把 Tokio 流交给 Hyper。

概念解释

Hyper 1.x 不再提供顶层 bind 便捷入口,服务端流程由调用方编排:建监听器、循环 accept、握手连接、在连接上跑服务。service_fn 把 Fn(Request<Incoming>) -> Future 转成 Tower 风格服务。TokioIo 把 tokio::net::TcpStream 适配成 Hyper 需要的 IO trait;TokioExecutor 提供 spawn 能力给 Hyper 内部任务。

原理流程

  1. 创建 Tokio 运行时并绑定监听地址。
  2. 用 service_fn 定义请求处理闭包。
  3. accept 得到 TcpStream,包成 TokioIo。
  4. http1::Builder::new().serve_connection(io, svc) 启动连接服务。
  5. with_upgrades 开启连接升级支持,await 连接结束。

代码或图示

use hyper::service::service_fn;
use hyper::{body::Incoming, Request, Response, StatusCode};
use hyper_util::rt::{TokioExecutor, TokioIo};
use std::net::SocketAddr;

async fn hello(_req: Request<Incoming>) -> Result<Response<String>, hyper::Error> {
    Ok(Response::new("hello hyper".to_string()))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let addr: SocketAddr = ([127, 0, 0, 1], 3000).into();
    let listener = tokio::net::TcpListener::bind(addr).await?;
    loop {
        let (stream, _) = listener.accept().await?;
        let io = TokioIo::new(stream);
        let svc = service_fn(hello);
        hyper::server::conn::http1::Builder::new()
            .serve_connection(io, svc)
            .await?;
    }
}

常见误区

  • 忘记包 TokioIo:Hyper 不能直接接受 TcpStream,类型不匹配。
  • 在连接任务里阻塞等待业务完成却不 spawn:高并发下 accept 循环被拖住。

追问

  • serve_connection 返回的是什么?答:一个表示连接生命周期的 Future,await 完成即该连接结束;可配合句柄做优雅停机。
  • 最小服务里为什么没有路由?答:路由属于上层框架职责,Hyper 服务只对每条连接返回一个响应。

04.4.7.2-007 服务端 http1::Builder 提供哪些常用配置项?

一句话结论

http1::Builder 控制 HTTP/1.1 连接行为,常用项包括 keep-alive 开关、连接头保持、最大 HTTP/1 头部数量、是否允许过时的握手语法等;具体方法名以 docs.rs 当前版本为准。

概念解释

HTTP/1.1 连接上多个请求靠 keep-alive 复用,Builder 可以调优复用策略与解析限制。生产服务需要关注头部大小与数量限制,避免恶意请求撑爆解析器。这些配置只作用于 HTTP/1.1 连接,HTTP/2 由 http2::Builder 单独控制。

原理流程

  1. 创建 http1::Builder。
  2. 按场景设置 keep-alive、头部限制等选项。
  3. serve_connection(io, svc) 把配置应用到该连接。
  4. 协议解析阶段按限制拒绝违规报文。
  5. 连接结束后配置不影响其它连接。

代码或图示

use hyper::server::conn::http1;

let mut builder = http1::Builder::new();
builder.keep_alive(true);
// 其它可调项以 docs.rs 上 hyper::server::conn::http1::Builder 文档为准
// builder.max_buf_size(..);
// builder.max_headers(..);

常见误区

  • 把 HTTP/2 的并发流配置写到 http1::Builder:两套 Builder 配置互不通用。
  • 以为默认配置在所有生产场景都合适:头部限制、缓冲水位需结合业务压测调整。

追问

  • keep-alive 关闭后会发生什么?答:响应后连接即关闭,每个请求新建 TCP 连接,吞吐与延迟都会恶化。
  • 如何确认某配置项在当前版本存在?答:查 docs.rs 对应 Builder 方法列表,不存在的项标注待确认,不臆造方法名。

04.4.7.2-008 HTTP/2 服务端与 HTTP/1.1 在 Hyper 层有哪些差异?

一句话结论

HTTP/2 在一条复用连接上多路复用多个并发流,由 http2::Builder 控制并发流数、keep-alive 间隔与流窗口;Hyper 层把每个流仍表现为独立的 Request/Response 服务调用。

概念解释

HTTP/1.1 同一连接上请求按序处理,队头阻塞在应用层;HTTP/2 用流(stream)在单连接上并行收发帧。业务代码看到的依然是「请求进、响应出」,并发调度由协议层完成。http2::Builder 可限制单连接最大并发流、设置 keep-alive 探测间隔,配合流窗口做背压。浏览器与 gRPC 场景普遍要求 HTTP/2。

原理流程

  1. 连接握手升级或直接协商 HTTP/2。
  2. 每个请求分配独立流 ID。
  3. 帧在连接上交错传输,业务服务按流收到独立请求。
  4. 并发数受 max_concurrent_streams 限制。
  5. 流结束后连接继续承载其它流。

代码或图示

use hyper::server::conn::http2;

let mut builder = http2::Builder::new(hyper_util::rt::TokioExecutor::new());
// 常见配置:并发流上限、keep-alive 间隔;方法名以 docs.rs 当前版本为准
// builder.max_concurrent_streams(100);
// builder.keep_alive_interval(Duration::from_secs(30));

常见误区

  • 以为 HTTP/2 消除了所有队头阻塞:传输层 TCP 丢包造成的阻塞仍然存在。
  • 以为业务代码要手动管理流 ID:Hyper 把流封装成独立请求,业务不接触帧细节。

追问

  • gRPC 为什么强制 HTTP/2?答:gRPC 依赖流多路复用、头部帧与 trailers 等 HTTP/2 能力,HTTP/1.1 无法完整承载四种 RPC 模式。
  • 服务端如何同时支持两种协议?答:用 hyper::server::conn::auto 或按 ALPN/升级协商,待确认当前版本自动协商模块的精确类型名。

04.4.7.2-009 hyper-util 里的 TokioExecutor 与 TokioIo 各解决什么问题?

一句话结论

TokioIo 把 Tokio 的 AsyncRead/AsyncWrite 流适配成 Hyper 内部 IO trait,TokioExecutor 提供把内部任务 spawn 到 Tokio 运行时的执行器抽象;二者都是 Hyper 与 Tokio 运行时之间的桥接层。

概念解释

Hyper 内核不绑定具体运行时,IO 与任务执行通过 trait 抽象。TokioIo::new(stream) 包装 TcpStream、TlsStream 等类型,实现 Hyper 要求的读写字节与关断方法。TokioExecutor 实现 Hyper 的 executor trait,把需要后台运行的连接或流任务提交到 Tokio。这样 Hyper 可以适配其它运行时,只要提供对应适配器。

原理流程

  1. 业务层拿到 Tokio 网络流。
  2. TokioIo::new 包装,类型满足 Hyper IO trait。
  3. serve_connection 内部需要 spawn 后台任务时调用 executor。
  4. 任务在 Tokio 运行时上调度 poll。
  5. IO 就绪事件由 Tokio 驱动,Hyper Future 被唤醒推进。

代码或图示

use hyper_util::rt::{TokioExecutor, TokioIo};
use tokio::net::TcpStream;

let stream: TcpStream = todo!();
let io = TokioIo::new(stream);
let executor = TokioExecutor::new();
// http2::Builder::new(executor).serve_connection(io, svc).await?;

常见误区

  • 以为 Hyper 直接依赖 Tokio 类型:内核通过 trait 解耦,Tokio 适配在 hyper-util。
  • 复用同一个 TokioIo 包装多条流:每个连接独立包装一次。

追问

  • 换用其它运行时需要什么?答:实现对应的 IO 适配器与 executor 即可,服务本身不需要改写。
  • hyper-util 还提供哪些适配器?答:legacy 高层客户端、service 适配器等;完整列表以 docs.rs 当前版本为准。

04.4.7.2-010 服务端 accept 循环为什么要每条连接单独驱动,而不是一个 Future 处理所有连接?

一句话结论

每条 TCP 连接是独立的异步生命周期,accept 循环负责不断接新连接,连接服务 Future 负责该连接上的协议状态机;把两者分开才能在单线程事件循环上并发承载大量连接。

概念解释

典型服务结构:TcpListener::accept 循环产生新流,每条流交给 serve_connection 返回的连接 Future。高并发时通常把连接任务 spawn 出去,避免等待慢连接阻塞新连接接入。连接内部可以复用(HTTP/1.1 keep-alive、HTTP/2 多路复用),所以一个连接 Future 会跨越多个请求。

原理流程

  1. accept().await 等待新连接。
  2. 包装 IO 与服务,生成连接 Future。
  3. spawn 连接 Future,立即回到 accept 等待下一条。
  4. 连接上按协议处理若干请求后结束。
  5. 停机信号到达后停止 accept 并等待存量连接收尾。

代码或图示

loop {
    let (stream, _peer) = listener.accept().await?;
    let io = TokioIo::new(stream);
    let svc = service_fn(hello);
    let conn = hyper::server::conn::http1::Builder::new()
        .serve_connection(io, svc);
    tokio::spawn(async move { if let Err(e) = conn.await { /* 记录错误 */ } });
}

常见误区

  • 不 spawn 直接在循环里 await 连接:慢连接会阻塞后续接入。
  • 在连接任务里持有阻塞锁或同步 IO:会卡住 Tokio worker,影响所有连接。

追问

  • 连接任务何时结束?答:协议层判断连接不可复用或对端关闭后,连接 Future 完成。
  • 一条连接上多个请求如何串行/并行?答:HTTP/1.1 按序处理,HTTP/2 由流多路复用并行;Hyper 服务调用按流触发。

04.4.7.2-011 Hyper 服务端怎么做 graceful shutdown(优雅停机)?

一句话结论

先停止 accept 新连接,再对在途连接调用优雅停机接口或等待连接 Future 自然结束,让已接收的请求处理完再关闭;HTTP/1.1 与 HTTP/2 的停机句柄行为略有差异。

概念解释

强制停机可能导致在途响应被截断。优雅停机分两层:入口层停止接新连接,协议层通知现有连接不再接受新请求并等待队列清空。serve_connection 返回的连接句柄可以查询或触发停机;信号处理(Ctrl+C、SIGTERM)负责设置停止标志。HTTP/2 还需要配合流关闭与 keep-alive 探测回收半开连接。

原理流程

  1. 监听停机信号,置位停止标志。
  2. accept 循环收到标志后退出,不再接新连接。
  3. 对已 spawn 的连接任务调用优雅停机或等待其完成。
  4. 在途请求处理完毕、响应写出后连接关闭。
  5. 超过宽限时间仍未结束的连接强制终止。

代码或图示

// 示意:连接句柄上的优雅停机方法名以 docs.rs 当前版本为准
let (conn, mut conn_handle) = hyper::server::conn::http1::Builder::new()
    .serve_connection(io, svc)
    .with_graceful_shutdown(shutdown_signal());
tokio::spawn(async move { conn.await });
// 信号触发后 conn_handle.shutdown().await;

常见误区

  • 只停 accept 就直接退出进程:在途请求被中断。
  • 忽略宽限超时:卡死的连接会拖住整个进程退出。

追问

  • 优雅停机与 keep-alive 空闲连接如何配合?答:停机后空闲连接应被主动关闭,避免进程退出时残留连接被对端复用。
  • 服务框架层通常封装了什么?答:上层框架提供监听退出信号、等待在途任务的封装;Hyper 层只暴露连接级停机能力。

04.4.7.2-012 keep-alive 与连接复用在 Hyper 里是如何工作的?

一句话结论

HTTP/1.1 keep-alive 在一条 TCP 连接上顺序承载多个请求响应;HTTP/2 复用连接承载多路并发流;复用是否成立取决于 body 是否读完、响应是否完整以及协议协商结果。

概念解释

连接复用省去 TCP 握手与 TLS 往返,是 HTTP 性能的关键。请求 body 未读完、响应未完整写出或出现协议错误时,连接会被标记为不可复用,下一个请求只能新建连接。服务端 Builder 可控制 keep-alive 行为;客户端侧由连接池与握手策略决定复用。空闲连接由 keep-alive 探测与超时回收。

原理流程

  1. 第一个请求在新连接上处理。
  2. body 读完、响应完整写出后,连接回到可复用状态。
  3. 后续请求排队到同一连接(HTTP/1.1 串行,HTTP/2 并发流)。
  4. 空闲超时或探测失败后连接关闭。
  5. 出现不可恢复错误时连接立即废弃。

代码或图示

// HTTP/1.1 服务端开启 keep-alive
hyper::server::conn::http1::Builder::new()
    .keep_alive(true)
    .serve_connection(io, svc)
    .await?;

常见误区

  • 以为只要开了 keep-alive 就一定复用:body 未读完或报错后连接不可复用。
  • 在响应中途返回错误体不全:复用概率下降,对端可能重连。

追问

  • 如何观测复用是否生效?答:统计连接数与请求数比值、抓包观察同一连接上的报文序列;服务端日志可记录对端连接事件。
  • 空闲连接超时由谁控制?答:服务端与客户端都可设空闲超时,配置项依 HTTP 版本与库而定。

04.4.7.2-013 客户端在 Hyper 1.x 里放在哪里,低层握手怎么写?

一句话结论

1.x 高层客户端在 hyper-util 的 legacy 模块;内核 hyper::client::conn 提供低层握手:先与 IO 流握手得到发送端与连接任务,再通过发送端发请求。

概念解释

低层 API 把连接管理交给调用方:http1::handshake 或 http2::handshake 返回(发送端, 连接 Future)。发送端可以多次发请求以复用连接,连接 Future 必须被 spawn 驱动,否则帧收发不会推进。hyper-util 的 legacy Client 在此之上做了连接池与地址解析,业务常用后者。

原理流程

  1. 建立或拿到底层 IO 流。
  2. conn::http1::handshake(io).await 得到发送端与连接任务。
  3. spawn 连接任务驱动帧读写。
  4. 发送端 send_request(req) 提交请求。
  5. 等待响应 Future,读取响应 body。

代码或图示

use hyper::client::conn;
use hyper::Request;

// 低层 HTTP/1.1 握手示意;IO 流需自行建立并包成 TokioIo
let (mut sender, conn) = conn::http1::handshake::<TokioIo<tokio::net::TcpStream>, _>(io).await?;
tokio::spawn(async move { if let Err(e) = conn.await { /* 记录 */ } });
let resp = sender.send_request(Request::new(Full::new(Bytes::from("")))).await?;

常见误区

  • 忘记 spawn 连接 Future:请求发出后没有任务收发帧,调用挂起。
  • 用内核低层 API 做复杂路由:地址解析、重试、连接池应交给高层 Client。

追问

  • legacy Client 与低层 conn 各适合什么场景?答:常规业务用 legacy Client 获得池化能力;协议定制、代理或嵌入其它客户端时用低层握手。
  • 待确认点:当前 hyper-util legacy Client 的 feature 名与模块路径,以 docs.rs 为准。

04.4.7.2-014 用 hyper-util legacy Client 发一个请求的完整流程是什么?

一句话结论

构造 Client,传入请求 URI 与 body,await 拿到响应,再用 BodyExt 收集响应 body;Client 内部负责 DNS、连接复用与协议协商。

概念解释

legacy Client 是面向常规业务的高层 HTTP 客户端:按 scheme 与地址维护连接池,复用底层连接,支持 HTTP/1.1 与 HTTP/2。body 仍走 http_body::Body 抽象,响应 body 是入站流。需要自定义连接行为(代理、TLS 配置)时再退回低层握手。

原理流程

  1. 引入 hyper-util 的 client-legacy feature。
  2. Client::new() 或带配置构造。
  3. Client::request(req) 提交 Request<BodyImpl>。
  4. await 得到 Response<Incoming>。
  5. collect().await?.to_bytes() 读取响应体。

代码或图示

use http_body_util::{BodyExt, Full};
use hyper::{Request, StatusCode};
use hyper_util::client::legacy::Client;
use bytes::Bytes;

let client: Client<_, Full<Bytes>> = Client::new(hyper_util::rt::TokioExecutor::new());
let req = Request::builder().uri("http://127.0.0.1:3000/").body(Full::new(Bytes::from("")))?;
let resp = client.request(req).await?;
assert_eq!(resp.status(), StatusCode::OK);
let body = resp.into_body().collect().await?.to_bytes();

常见误区

  • 把字符串直接当 body 传给请求:需要包成 body 实现。
  • 以为 Client 会自动重试:重试属于上层策略,需配合 tower Retry 或自行实现。

追问

  • Client 如何选择 HTTP 版本?答:按协议协商与配置,HTTP/2 需上游支持;具体默认行为以 docs.rs 当前版本为准。
  • 响应 body 没读完会怎样?答:可能影响连接复用,复用判断由客户端与协议层共同决定。

04.4.7.2-015 客户端连接复用与池化由谁管理,需要注意什么?

一句话结论

高层 Client 内部按目标地址维护连接与复用,低层握手则由调用方持有发送端复用连接;需要注意空闲超时、并发上限与 body 读完对复用的影响。

概念解释

连接池减少握手成本,但连接数也受对端与本机资源限制。池化行为包括:空闲连接保留多久、单目标最大连接数、不可复用连接何时淘汰。低层场景里发送端可在连接存活期间多次 send_request,连接断开后发送端失效,需要重新握手。

原理流程

  1. 首次请求建立连接并入池。
  2. 后续请求优先取空闲连接。
  3. 连接不可复用则标记淘汰,新建连接。
  4. 空闲超时后连接被回收。
  5. 压测时观察连接数、新建连接速率与等待池化时间。

代码或图示

// 高层 Client 封装池化;低层复用示意:
// 同一 sender 可在连接存活期间多次 send_request
// sender.send_request(req1).await?;
// sender.send_request(req2).await?;

常见误区

  • 每个请求新建一条低层连接:握手开销放大,TIME_WAIT 堆积。
  • 长期持有空闲连接不释放:对端可能已关闭,下一次请求才发现断连。

追问

  • 如何避免连接耗尽?答:限制并发请求数、设置连接上限与超时,监控新建连接速率;必要时用 tower 并发限制层兜底。
  • 池化连接出现半开状态怎么发现?答:keep-alive 探测或下一次请求报错后重建,具体机制依客户端实现而定。

04.4.7.2-016 Hyper 请求里如何读取与修改头部、方法与 URI?

一句话结论

Request 拆出 Parts 后访问 method、uri、headers;头部用 HeaderMap 的 get/insert/append 操作,多值头部按迭代器读取。

概念解释

Method 是强类型枚举,Uri 提供路径、查询、主机等解析。HeaderMap 键为 HeaderName,值为 HeaderValue,一个键可对应多个值。修改头部时注意校验值是否合法(不可见字符等),构造失败会返回 Result。body 与头部分离:改头部不消费 body。

原理流程

  1. req.into_parts() 拆成 Parts 与 body。
  2. 读 parts.method、parts.uri、parts.headers。
  3. 用 headers.get(..) 取单值,headers.get_all(..) 取多值。
  4. headers.insert(..) 覆盖同名,append(..) 追加。
  5. 需要继续流转时重新组装 Request::from_parts(parts, body)。

代码或图示

use hyper::header::{HeaderName, HeaderValue};

let (mut parts, body) = req.into_parts();
let token = parts.headers.get("authorization").and_then(|v| v.to_str().ok());
parts.headers.insert(HeaderName::from_static("x-request-id"), HeaderValue::from_static("abc"));
let _uri = parts.uri.path();

常见误区

  • 用字符串直接比较头部名大小写:应通过 HeaderName 或 get 方法,匹配本身大小写不敏感。
  • insert 后以为还能保留旧值:insert 覆盖同名所有值,追加用 append。

追问

  • 头部值含非 ASCII 怎么办?答:HeaderValue 只存合法字节,非 ASCII 内容需按规范编码后放入;待确认当前版本校验细节以文档为准。
  • Uri 的 query 怎么解析?答:uri.query() 取原始查询串,键值解析交给 serde_urlencoded 等库。

04.4.7.2-017 StatusCode 与错误响应怎么构造?

一句话结论

响应状态码用 StatusCode 枚举表达,构造 Response 时通过 builder.status(..) 设置;业务错误需要同时给出状态码、响应体与必要头部,不能只返回 Err 给协议层。

概念解释

Hyper 服务返回 Result<Response<B>, Error>,其中 Error 表示协议层不可恢复错误;业务层面的 4xx/5xx 仍然是正常 Response,只是状态码不同。上层框架通常提供 IntoResponse 把错误类型映射成响应。直接用 Hyper 时要自己构造错误响应体,避免直接把业务错误冒泡成协议错误导致连接中断。

原理流程

  1. 判断业务失败类型。
  2. 选择对应 StatusCode(400、401、403、404、500 等)。
  3. 构造响应体(文本或 JSON 字节)。
  4. 补齐 Content-Type 等头部。
  5. 返回 Ok(Response::new(body)),协议层正常写出。

代码或图示

use hyper::{Response, StatusCode, body::Incoming};

fn bad_request() -> Response<String> {
    Response::builder()
        .status(StatusCode::BAD_REQUEST)
        .body("invalid request".to_string())
        .unwrap()
}

常见误区

  • 业务失败直接 Err(hyper::Error):协议层错误语义与业务错误混在一起,可能中断连接。
  • 只设状态码不写 body:客户端拿到空响应,排错信息缺失。

追问

  • 500 与协议层 Error 的区别?答:500 是完整响应报文,连接可继续复用;hyper::Error 表示协议处理异常,连接通常不可复用。
  • 状态码分组怎么记?答:2xx 成功、3xx 重定向、4xx 客户端错误、5xx 服务端错误;具体码以 HTTP 规范为准。

04.4.7.2-018 读取 body 为 Bytes 的标准做法是什么?

一句话结论

通过 http_body_util::BodyExt::collect() 收集所有帧得到 Collected,再 to_bytes() 取 Bytes;需要限制大 body 时在收集过程中做大小检查。

概念解释

collect 是异步操作,逐帧累积直到 body 结束。to_bytes 返回 Bytes,支持零切片共享。对不可信输入,必须在读取前或读取中限制总长度,防止内存被大 body 打满;tower-http 的 RequestBodyLimitLayer 是常用前置限制。

原理流程

  1. 引入 http-body-util 的 BodyExt。
  2. req.into_body().collect().await 累积帧。
  3. to_bytes() 转换为 Bytes。
  4. 按业务编码解析(UTF-8、JSON 等)。
  5. 超限场景在层栈前置限制或读取循环中提前中断。

代码或图示

use http_body_util::BodyExt;

let bytes = req.into_body().collect().await?.to_bytes();
let text = std::str::from_utf8(&bytes)?;

常见误区

  • 直接 body 上调用标准库字符串方法:body 是流,不是 &[u8]。
  • 不限制 body 大小就全量收集:恶意大请求可耗尽内存。

追问

  • 超大上传怎么处理?答:流式读取并落盘或转发,边读边限制水位,不一次性收集。
  • collect 返回的错误类型是什么?答:随 body 实现的 Error 类型而定;Incoming 的错误通常可转成 hyper::Error,待确认当前版本精确转换路径。

04.4.7.2-019 如何构造一个流式响应 body,而不是一次性写出全部内容?

一句话结论

出站 body 实现 http_body::Body trait 即可逐帧产出;常用适配器把 Stream 包成 body,或用 Full<Bytes> 包装固定内容;SSE、文件下载、代理转发都走这种方式。

概念解释

响应不必先在内存里备好全部字节。Body trait 暴露帧拉取能力:Hyper 编码时按需 poll。http_body_util 提供 StreamBody 等适配器把异步流转成 body;业务流需要在帧背压下暂停产出。固定小响应用 Full,内存最省。

原理流程

  1. 准备一个产出数据帧的异步流。
  2. 用适配器包装成 http_body::Body 实现。
  3. Response::new(body) 挂到响应上。
  4. Hyper 按编码节奏 poll body 写回。
  5. 流结束返回 End 帧,响应完成。

代码或图示

// 示意:固定内容用 Full;流式用 StreamBody(适配器名以 http-body-util 当前版本为准)
use http_body_util::Full;
use bytes::Bytes;

let body = Full::new(Bytes::from("fixed payload"));
let resp = Response::new(body);
// 流式场景:let body = StreamBody::new(stream);

常见误区

  • 流在后台无限产出却不响应背压:内存随积压帧增长。
  • 响应不设置长度或分块标记:客户端可能等待连接关闭才判定 body 结束。

追问

  • SSE 响应要注意什么?答:按事件帧持续产出,设置正确的 Content-Type,保持连接不被中间件缓冲;具体事件格式由业务约定。
  • 文件流式发送如何避免阻塞 worker?答:用异步文件 IO 或任务池读块,配合 body 背压,不要用标准库同步读文件。

04.4.7.2-020 Hyper 如何支持连接升级(upgrade),WebSocket 底层与之是什么关系?

一句话结论

Hyper 提供升级通道:响应触发升级后,底层 IO 流被移交到升级后的协议处理;WebSocket 库在 Hyper 之上完成握手与帧编解码,业务通常不直接操作 upgrade 细节。

概念解释

HTTP 升级先以普通请求响应完成握手(101 Switching Protocols),随后连接不再走 HTTP 报文。Hyper 支持把 IO 流取出交给后续协议。axum 等上层框架把 WebSocket 封装成提取器与升级处理;底层仍依赖 Hyper 的 upgrade 能力。自定义协议升级时需要从连接句柄获取已升级的流。

原理流程

  1. 客户端发起带升级头部的请求。
  2. 服务端返回 101 与升级确认头部。
  3. Hyper 把底层流移交到 upgrade 通道。
  4. 后续协议(如 WebSocket)在该流上读写帧。
  5. 协议结束后流关闭,连接不再回到 HTTP。

代码或图示

// 示意:开启升级支持
hyper::server::conn::http1::Builder::new()
    .serve_connection(io, svc)
    .with_upgrades()
    .await?;

常见误区

  • 忘记 with_upgrades():升级请求拿不到移交流,WebSocket 握手失败。
  • 升级后仍按 HTTP 读取:流已切换协议,报文语义不再成立。

追问

  • WebSocket 与 HTTP/2 的关系?答:WebSocket 传统基于 HTTP/1.1 升级;HTTP/2 上的 WebSocket 有不同帧封装方式,支持情况依库与代理而定。
  • 待确认点:当前版本从 upgrade 通道取流的精确 API 类型,以 docs.rs Hyper upgrade 模块为准。

04.4.7.2-021 Hyper 的错误类型有哪些来源,如何区分协议错误与业务错误?

一句话结论

hyper::Error 表示协议层错误(解析、帧异常、IO 失败等);业务 4xx/5xx 是正常响应,不是 Hyper 错误。排查时先判断错误来自握手、连接还是 body 读取,再决定是否可复用连接。

概念解释

协议错误通常伴随连接不可复用:头部非法、帧损坏、IO 断开、超时等。业务错误(参数非法、未授权)应在服务内转成响应状态码。直接用 Hyper 时,Result 的 Err 要记录上下文并决定连接去留;上层框架会把可恢复业务错误隔离在响应层。

原理流程

  1. 捕获连接 Future 与请求处理中的错误。
  2. 判断是否为 hyper::Error 及其来源(source/类别)。
  3. 协议错误记录后丢弃连接,不尝试复用。
  4. 业务失败构造对应状态码响应。
  5. 错误日志带上对端地址、请求路径与错误链。

代码或图示

if let Err(e) = conn.await {
    // e: hyper::Error;可访问 source 链定位 IO 或协议原因
    eprintln!("connection error: {e}");
}

常见误区

  • 把所有 Err 都当成 500:部分错误导致连接已坏,返回 500 也无法复用。
  • 吞掉连接错误静默退出:半开连接与资源泄漏难排查。

追问

  • 错误链怎么打印?答:用 std::error::Error::source 逐层取根因,或在日志库中记录错误链;不要只打最外层消息。
  • 待确认点:当前版本 hyper::Error 提供的方法名(is_parse 等)以 docs.rs 为准。

04.4.7.2-022 为什么超时控制不在 Hyper 内核,而通常放在 Tower 层?

一句话结论

Hyper 只驱动协议状态机,不知道业务「应当」多久完成;超时是策略层能力,由 tower::timeout::Timeout 或 tower-http 的超时层包裹服务实现。

概念解释

协议层无法判断一个 handler 慢是正常流式长连接还是卡死请求。超时策略需要业务语义:API 接口 5 秒超时,SSE 流不设整体超时。Tower 层在服务外包一层定时 Future,超时即取消并返回错误。HTTP 客户端调用也同理用层或包装 Future 加超时。

原理流程

  1. 业务服务实现 Service。
  2. Timeout::new(svc, Duration) 包裹。
  3. 请求进入后启动定时器。
  4. 业务 Future 先完成则正常返回;定时器先触发则返回超时错误。
  5. 超时错误在层栈上被映射成对应响应或 Status。

代码或图示

use tower::timeout::Timeout;
use std::time::Duration;

let svc = Timeout::new(inner, Duration::from_secs(5));
// 业务层把超时错误映射为 504 或自定义响应

常见误区

  • 给 SSE、下载流也套整体超时:长流被误杀。
  • 超时只取消 Future 不清理内部资源:任务仍在后台持有连接与锁。

追问

  • 超时与 deadline 传播有什么区别?答:本地超时只看本节点计时器;分布式 deadline 随 metadata 传播,下游可据此拒绝继续处理。
  • 流式接口怎么做分段超时?答:对每帧读取设间隔超时,而不是对整条流设总时长。

04.4.7.2-023 在 Hyper handler 里做阻塞调用会造成什么问题?

一句话结论

阻塞同步 IO 或长计算会卡住 Tokio worker,使该 worker 上所有其它连接无法被 poll;阻塞任务必须 spawn_blocking 或移到独立线程池。

概念解释

异步运行时靠少量 worker 线程轮询大量 Future。handler 内调用标准库阻塞读、同步锁等待、CPU 密集循环,worker 被占满后所有在途请求延迟飙升。Hyper 服务本身是异步的,但服务内部代码是否阻塞取决于业务实现。spawn_blocking 把阻塞工作移交阻塞线程池,完成后再回到异步上下文。

原理流程

  1. 请求在某 worker 上进入 handler。
  2. 阻塞调用占用该 worker 线程不放。
  3. 同 worker 的其它 Future 无法推进。
  4. 严重时新请求也排不上调度。
  5. 阻塞工作移出 worker 后恢复并发能力。

代码或图示

// 反例:handler 内标准库阻塞读文件
// tokio::fs::read 是异步的;std::fs::read 会阻塞 worker

let content = tokio::fs::read("data.bin").await?;
// CPU 密集任务:tokio::task::spawn_blocking(move || heavy_compute()).await?

常见误区

  • 以为用了 async fn 内部就不会阻塞:函数体内的同步调用照样阻塞。
  • 用异步 Mutex 长时间持有跨 await:虽不阻塞线程,但会串行化临界区。

追问

  • 怎么检测异步上下文里的阻塞?答:看 tokio 阻塞警告、worker 任务排队指标;压测时观察 P99 与 worker 利用率。
  • spawn_blocking 适合什么任务?答:文件 IO、CPU 密集计算、同步库调用;结果通过 await 拿回异步任务。

04.4.7.2-024 Hyper 服务的并发模型是什么,每连接任务与每请求任务如何划分?

一句话结论

Hyper 以连接为单位驱动协议 Future;HTTP/1.1 连接内请求串行处理,HTTP/2 连接内由流多路复用并行;业务并发度由连接数、HTTP/2 流数与运行时调度共同决定。

概念解释

连接 Future 管理一条 TCP 连接的状态机,请求是连接上的事件。spawn 连接任务后,运行时在 worker 上并发 poll 多条连接。HTTP/2 单连接内多个流可并行触发服务调用;服务内部若再 spawn 任务,需要自己管理任务生命周期与背压。理解并发模型有助于压测时区分连接瓶颈与业务瓶颈。

原理流程

  1. accept 每条连接 spawn 一个连接任务。
  2. 连接任务 poll 协议帧,触发服务调用。
  3. HTTP/1.1:前一响应完成后处理下一请求。
  4. HTTP/2:多流并行触发,受并发流上限约束。
  5. 业务重任务可再 spawn,但要限制数量并等待收尾。

代码或图示

TcpListener
├── conn task 1 (HTTP/1.1: 串行请求 A, B, C)
├── conn task 2 (HTTP/2: stream 1..N 并行)
└── conn task 3 ...

常见误区

  • 以为一条连接一个请求:keep-alive 与多路复用都允许连接承载多请求。
  • 在 handler 里无限 spawn 后台任务:并发失控,缺少背压与生命周期管理。

追问

  • 服务端并发数受哪些限制?答:worker 线程数、连接数、HTTP/2 并发流上限、业务信号量/限流层、系统文件描述符。
  • 后台任务怎么不随请求结束被丢弃?答:用任务句柄或全局任务集合持有,停机时统一等待;具体模式依工程实现而定。

04.4.7.2-025 直接使用 Hyper 生产落地需要自己补齐哪些上层能力?

一句话结论

直接用 Hyper 需自行补齐路由、提取器、序列化、中间件层栈、错误到响应映射、静态文件、超时限流与观测埋点;这也是生产项目通常选 axum 等上层框架的原因。

概念解释

Hyper 只交付协议与连接能力。一个可用服务还需要:路径匹配与参数解析、请求体解码与校验、响应序列化、鉴权日志压缩等层、统一错误响应、静态资源、健康检查、指标与日志。Tower 提供层组装骨架,tower-http 提供常用中间件,业务仍需自己粘合。

原理流程

  1. 用 Hyper 起连接服务。
  2. 用 Tower 组装 trace、timeout、limit 等层。
  3. 业务服务内做路由与解码。
  4. 错误映射成响应与日志。
  5. 补齐观测与运维接口。

代码或图示

// 生产栈示意(类型以实际 crate 为准)
// service_fn(handler)
//   -> tower_http::limit::RequestBodyLimitLayer
//   -> tower::timeout::Timeout
//   -> tower_http::trace::TraceLayer
//   -> Hyper serve_connection

常见误区

  • 以为换 Hyper 就省掉了业务框架的全部工作:上层胶水代码量不小。
  • 只在骨架上跑通演示接口就上线:缺少限流、body 限制、观测等生产要素。

追问

  • 什么场景适合直接用 Hyper?答:代理网关、协议适配、嵌入式服务等只需要协议层或需要定制连接行为的场景。
  • 选型时如何对比 Hyper 直用与 axum?答:看路由/提取器/中间件复用成本;通用业务接口用上层框架收益更大。

04.4.7.2-026 HTTP/2 服务端可调哪些并发与 keep-alive 参数?

一句话结论

http2::Builder 可调整单连接最大并发流、keep-alive 探测间隔与超时等参数,用于控制连接存活与并发上限;具体方法名以 docs.rs 当前版本为准。

概念解释

HTTP/2 把并发拆到流级别:并发流上限决定单连接同时在途请求数,超过的流排队等待。keep-alive 探测用于发现半开连接,空闲过久后主动回收。这些参数需要结合上游代理、客户端行为与压测结果调整,盲目调大并发流可能放大内存与 CPU 压力。

原理流程

  1. 创建 http2::Builder 并注入 executor。
  2. 设置并发流上限、keep-alive 间隔与超时。
  3. 每条连接按配置运行帧调度。
  4. 流数达上限后新流等待槽位释放。
  5. 探测失败或空闲超时后关闭连接。

代码或图示

use hyper::server::conn::http2;
use std::time::Duration;

let mut builder = http2::Builder::new(hyper_util::rt::TokioExecutor::new());
// 待确认:当前版本方法名以 docs.rs 为准,常见含义如下
// builder.max_concurrent_streams(200);
// builder.keep_alive_interval(Duration::from_secs(30));
// builder.keep_alive_timeout(Duration::from_secs(10));

常见误区

  • 把 HTTP/1.1 连接复用参数套到 HTTP/2 Builder:两套配置独立。
  • 并发流上限设得超过业务承载能力:下游依赖被打垮,错误率上升。

追问

  • 并发流排队表现为什么?答:流已建立但业务服务迟迟不被调用,延迟增长,连接并未断开。
  • keep-alive 探测在服务端还是客户端发起?答:双方都可配置探测;具体默认方向依实现而定,待确认版本行为。

04.4.7.2-027 大文件流式响应与上传在 Hyper 层如何避免一次性占内存?

一句话结论

响应侧用流 body 逐块产出,上传侧在读取循环里边落盘边限制水位;两端都不调用 collect 全量缓冲,内存占用保持与块大小相关。

概念解释

大文件场景的风险是把整个文件读进 Vec 再组装响应,内存随文件大小线性增长。流式方案:文件块异步读出,包成 body 帧交给 Hyper;上游背压由 body poll 节奏控制。上传则逐帧写入临时文件或下游,累计超过配额即中断。http-body-util 提供帧迭代与收集适配器。

原理流程

  1. 响应:打开文件,分块异步读取。
  2. 块通过流 body 交给 Hyper,按发送节奏 poll。
  3. 上传:循环拉取入站帧,写入目标位置。
  4. 累计大小超限即中止流并返回错误。
  5. 结束后清理临时文件与句柄。

代码或图示

// 伪代码:分块读取并通过流 body 发送
// let file = tokio::fs::File::open(path).await?;
// let stream = tokio_util::io::ReaderStream::new(file);
// let body = StreamBody::new(stream);
// 上传限制:在帧循环中累加 size,超过上限即返回 413

常见误区

  • 下载前 fs::read 整个文件:大文件直接打满内存。
  • 上传不限大小:恶意大请求耗尽磁盘与内存。

追问

  • 流式响应如何支持断点续传?答:按 Range 头部定位文件偏移,只产出对应区间;Range 解析与状态码由业务或框架处理。
  • 背压如何传递到读取侧?答:下游 poll 节奏慢时流产出暂停,读取循环相应等待,具体由流实现保证。

04.4.7.2-028 用 Hyper 实现反向代理转发请求,body 应当如何处理?

一句话结论

代理应把入站 body 流式转发到上游响应,再把上游响应 body 流回客户端;不需要全量收集 body,只在需要改写头部或鉴权时检查请求元信息。

概念解释

代理网关的核心是请求转发与响应回传,body 是双向流。低层客户端握手或高层 Client 发出转发请求,响应 body 直接作为出站 body。头部队改写(路径、Host、鉴权注入)在转发前完成。注意保留原始请求方法、查询串与必要头部,避免丢失客户端身份信息。

原理流程

  1. 接收入站请求,读取方法、URI、头部。
  2. 构造上游请求,注入或剥离代理相关头部。
  3. 入站 body 作为出站 body 提交给上游。
  4. 收到上游响应后把状态码与头部回写。
  5. 响应 body 流回客户端,结束后释放连接。

代码或图示

// 伪代码:转发请求并回传响应
// let upstream = Client::new(executor);
// let mut upstream_req = Request::builder()
//     .method(req.method())
//     .uri(upstream_uri)
//     .body(req.into_body())?;
// copy_headers(&req.headers(), &mut upstream_req.headers_mut());
// let resp = upstream.request(upstream_req).await?;
// Ok(Response::new(resp.into_body()))

常见误区

  • 先 collect 两边 body 再转发:大响应内存翻倍。
  • 转发时覆盖 Host 或丢失 Authorization:上游路由或鉴权失败。

追问

  • 上游超时如何处理?答:转发调用包超时,超时后向客户端返回 504,并记录上游地址与延迟。
  • 代理如何处理 WebSocket 升级?答:需要透传升级头部并移交 IO 流,普通 HTTP 转发栈不自动支持;待确认当前版本透传方案。

04.4.7.2-029 如何为 Hyper 接入自定义 IO(例如 TLS 包装流)?

一句话结论

把 TLS 包装后的流用 TokioIo 再次包装成 Hyper IO trait 实现即可;Hyper 不认识具体 TLS 类型,只通过通用读写字节接口通信。

概念解释

TLS 握手通常在 TCP 流之上包一层 TlsStream。该类型实现 Tokio 的 AsyncRead/AsyncWrite,TokioIo 适配器据此满足 Hyper IO 要求。服务端先做 TLS 握手再 serve_connection;证书校验、协议 ALPN 选择在 TLS 层完成。换用 rustls 或 native-tls 只影响握手与流类型,服务代码不变。

原理流程

  1. accept 得到 TcpStream。
  2. 用 TLS 配置完成握手,得到 TlsStream。
  3. TokioIo::new(tls_stream) 包装。
  4. 把包装流交给 serve_connection。
  5. Hyper 在加密通道上读写明文报文。

代码或图示

// 示意;TLS 配置与类型依所选库而定(rustls / native-tls)
// let tls_stream = tls_acceptor.accept(stream).await?;
// let io = TokioIo::new(tls_stream);
// hyper::server::conn::http2::Builder::new(executor)
//     .serve_connection(io, svc).await?;

常见误区

  • 把裸 TlsStream 直接传给 serve_connection:缺少 Hyper IO trait 实现,编译失败。
  • 忘记配置 ALPN:HTTP/2 协商不到,被迫走 HTTP/1.1 或握手失败。

追问

  • TLS 握手错误怎么归类?答:握手阶段错误发生在协议连接建立前,应单独记录客户端地址与证书问题,不要混入业务响应。
  • 待确认点:当前 Hyper 是否内置 TLS 便捷 API;文档中未见内置时按外置适配器方案实现。

04.4.7.2-030 Hyper 与 hyper-util 的 Cargo feature 通常如何选择?

一句话结论

按服务端/客户端与协议版本开启对应 feature,例如 server、client、http1、http2;hyper-util 再按 tokio 适配与 legacy 客户端开启对应 feature;名称以 docs.rs 当前版本为准。

概念解释

Crate 通过 feature 裁剪编译产物:只做服务端可不启用客户端代码,只支持 HTTP/1.1 可关闭 HTTP/2。依赖写法在 Cargo.toml 里用 features 列表声明。生产项目应显式列出所需 feature,避免默认集合带入未用代码;升级版本时重新核对 feature 名是否更名。

原理流程

  1. 确定部署形态:服务端、客户端或两者。
  2. 确定协议版本:HTTP/1.1、HTTP/2 或自动协商。
  3. 在依赖行开启对应 feature。
  4. hyper-util 开启 tokio 适配与所需客户端模块。
  5. 编译后检查未用 feature 并裁剪。

代码或图示

hyper = { version = "1", features = ["server", "http1", "http2"] }
hyper-util = { version = "0.1", features = ["tokio", "client-legacy"] }
http-body-util = "0.1"
tokio = { version = "1", features = ["net", "macros", "rt-multi-thread"] }

常见误区

  • 把 full feature 一股脑打开:编译时间与产物体积上升。
  • 升级后沿用旧 feature 名:若更名会编译警告或失败,需对照当前版本文档。

追问

  • 怎么查看当前可用 feature?答:查 docs.rs 依赖页的 Feature flags 章节或 cargo metadata;不凭记忆写不存在的 feature。
  • 待确认点:具体 feature 集合随版本调整,构建报错时以编译提示与官方文档为准。

04.4.7.2-031 如何在单元测试里直接驱动一个 Hyper/Tower 服务?

一句话结论

用 ServiceExt::oneshot 把一个 Request 直接喂给服务并 await 响应,不需要监听端口与真实网络;这是 Tower 服务最常用的测试手段。

概念解释

服务抽象是「请求进、响应出」,测试可以跳过网络层:构造请求 body,调用 oneshot 拿到响应 Future,断言状态码与 body。需要先 ready 或由 oneshot 内部处理就绪检查。连接相关测试(keep-alive、升级)才需要起本地 TCP 监听器。

原理流程

  1. 组装被测服务栈(业务服务加必要层)。
  2. 构造 Request<BodyImpl>。
  3. svc.oneshot(req).await 得到响应。
  4. 收集响应 body 断言内容。
  5. 错误类型按服务栈实际 Error 断言。

代码或图示

use tower::ServiceExt;

let svc = service_fn(handler);
let req = Request::new(Full::new(Bytes::from("")));
let resp = svc.oneshot(req).await.expect("response");
assert_eq!(resp.status(), StatusCode::OK);

常见误区

  • 测试里起真实端口再发 HTTP 请求:慢且受端口占用影响,单元测试应优先 oneshot。
  • 忘记把外层服务的错误类型映射到可断言类型:Err 分支无法比较。

追问

  • oneshot 与 call 的区别?答:call 要求先确认服务就绪,oneshot 是 ServiceExt 组合子,内部处理就绪检查后调用一次;待确认当前版本签名以 docs.rs 为准。
  • 流式响应怎么测?答:在测试里逐帧消费响应 body,断言帧序列与结束帧。

04.4.7.2-032 Hyper 与底层 h2 crate 是什么关系?

一句话结论

Hyper 在 HTTP/2 路径上复用 h2 crate 完成帧编解码与流调度,自身提供高层服务与客户端抽象;h2 是纯 HTTP/2 协议帧库,不含业务服务模型。

概念解释

h2 实现 HTTP/2 帧读写、流状态机、流量控制与多路复用。Hyper 把 h2 暴露的流适配成 Request/Response 调用,对业务屏蔽帧细节。直接使用 h2 可以做协议级定制,但需要自己管理流生命周期与消息边界。HTTP/1.1 路径由 Hyper 自身解析实现。

原理流程

  1. 连接协商为 HTTP/2。
  2. Hyper 把 IO 流交给 h2 握手。
  3. h2 按流分配 ID、收发帧。
  4. 每个流映射为一次服务调用。
  5. Hyper 把响应帧编码回 h2 流。

代码或图示

业务服务
  -> Hyper(请求响应模型、服务组装)
    -> h2 crate(HTTP/2 帧、流、流控)
      -> Tokio IO(TCP/TLS 字节流)

常见误区

  • 以为 Hyper 自己实现了全部 HTTP/2 帧逻辑:帧层依赖 h2。
  • 业务代码直接操作 h2 流:跨层耦合,框架升级时风险高。

追问

  • 什么场景直接用 h2?答:需要自定义流行为、做协议研究或嵌入非 HTTP 消息框架时;常规业务不需要。
  • HTTP/1.1 有对应的底层 crate 吗?答:Hyper 内置 1.1 解析;生态中另有解析库,待确认当前版本内部实现细节以源码为准。

04.4.7.2-033 为什么 Hyper handler 返回的是 Future,而不是同步结果?

一句话结论

IO 与等待都是异步的,handler 返回一个稍后完成的 Future,由运行时在就绪事件上 poll;同步阻塞返回值会让连接循环失去并发能力。

概念解释

HTTP 服务需要等待网络、数据库、下游调用,这些操作在等待期间不应占用线程。handler async fn 返回实现 Future 的匿名类型,服务 trait 的 call 返回关联 Future。运行时 poll 该 Future,遇到挂起点让出 worker,事件就绪后继续推进。这与 Tokio 运行时、Tower 服务抽象一脉相承。

原理流程

  1. 请求触发 call,返回响应 Future。
  2. 运行时 poll Future。
  3. 遇到 IO 等待,Future 挂起并让出线程。
  4. 事件就绪后唤醒,继续 poll。
  5. Future 输出响应结果。

代码或图示

async fn handler(_req: Request<Incoming>) -> Result<Response<String>, hyper::Error> {
    // 内部可 await 数据库、下游调用等
    Ok(Response::new("ok".to_string()))
}

常见误区

  • 在 handler 里返回同步阻塞结果:等待期间无法服务其它请求。
  • 忘记 Future 是惰性的:构造出的 Future 不被 poll 就不会执行。

追问

  • 服务 trait 的 Future 有什么约束?答:通常要求 Send(跨任务调度时)与生命周期匹配;具体 bound 以 Tower/hyper 当前 trait 定义为准。
  • 不 await 一个 spawn 出来的 Future 会怎样?答:任务在后台运行,丢弃句柄无法等待收尾,停机时可能被强制取消。

04.4.7.2-034 响应压缩为什么不在 Hyper 内核实现?

一句话结论

压缩是策略层能力:算法选择、阈值、头部协商与缓存策略都属业务语义,因此由 tower-http 的 CompressionLayer 等中间件在服务栈上实现,Hyper 只负责编码字节流。

概念解释

压缩需要读取 Accept-Encoding、判断响应类型与大小、按 gzip/deflate/br/zstd 编码并改写头部。这些决策与业务和部署相关,协议内核不绑定具体算法栈。把压缩放在层栈上还便于按路由开关、替换算法。未压缩的小响应强制压缩反而增加 CPU 成本。

原理流程

  1. 请求先经过压缩层,记录客户端可接受编码。
  2. 业务服务生成响应 body。
  3. 压缩层按阈值与类型决定是否编码。
  4. 改写 Content-Encoding 与长度相关头部。
  5. Hyper 把压缩后的 body 写出。

代码或图示

use tower_http::compression::CompressionLayer;

let stack = tower::ServiceBuilder::new()
    .layer(CompressionLayer::new())
    .service(inner);

常见误区

  • 以为 Hyper 自动按 Accept-Encoding 压缩:内核不做内容编码。
  • 对已经压缩过的响应(图片、压缩包)再次压缩:浪费 CPU,体积不降反升。

追问

  • 压缩层需要什么 feature?答:按算法开启对应 compression feature;待确认当前 tower-http 版本 feature 名以文档为准。
  • 流式压缩如何处理背压?答:压缩器按帧消费上游 body,产出压缩帧;水位控制由层实现保证,业务侧不直接操作压缩状态。

04.4.7.2-035 如何把同一个服务复用到多个监听端口?

一句话结论

服务类型通常实现 Clone,可以为每个端口各起一条 accept 循环,把克隆出来的服务实例交给对应连接;服务内共享状态用 Arc 持有,避免每端口复制一份数据。

概念解释

Hyper 服务本身无连接状态时可克隆复用;需要共享的数据(配置、缓存、数据库句柄)放在 Arc 里,各端口的服务实例克隆同一个 Arc。每条连接仍独立驱动服务调用。多端口常见于同时暴露 HTTP 与管理端口,或绑定多个网卡地址。

原理流程

  1. 构造共享状态 Arc<AppState>。
  2. 用状态构造基础服务。
  3. 对每个监听地址 accept 循环,克隆服务提交连接。
  4. 连接任务间通过 Arc 共享只读/线程安全状态。
  5. 停机时等待所有端口的连接收尾。

代码或图示

// 伪代码:两个端口共享同一服务构造逻辑
// for addr in [addr_a, addr_b] {
//     let svc = base_svc.clone();
//     tokio::spawn(async move { serve(addr, svc).await });
// }

常见误区

  • 每个端口新建一份非克隆状态:配置与缓存不一致。
  • 服务类型不满足 Clone 就想复用:先把不可克隆部分包进 Arc。

追问

  • 共享可变状态用什么同步?答:Arc<Mutex<T>> 或 Arc<RwLock<T>>,异步场景避免长锁持有;跨任务访问需满足 Send + Sync。
  • 不同端口需要不同中间件怎么办?答:分别组装服务栈,共享底层业务服务与状态即可。

04.4.7.2-036 直接用 Hyper 时常见的 body 类型编译错误怎么排查?

一句话结论

报错集中在「响应 body 类型与服务签名不匹配」与「入站 body 被当作缓冲类型」两类;对照 http_body::Body trait 与 Incoming 类型逐步定位。

概念解释

Hyper 1.x 服务返回的 body 是泛型 B: Body,不同 body 实现类型不同。混用 Full<Bytes>、Incoming、StreamBody 会导致服务 Future 类型不统一。排查顺序:先看 handler 签名声明的 body 类型,再看 Response::new 传入的 body 类型,最后检查适配器是否遗漏。业务可把响应 body 统一成一种实现,或用类型擦除层。

原理流程

  1. 打开编译错误,定位 trait bound 不满足的 Body 类型。
  2. 检查 handler 返回 Response<B> 中 B 的推断结果。
  3. 确认 Response::new 参数是否实现 http_body::Body。
  4. 入站侧确认使用 Incoming,出站侧选择明确 body 实现。
  5. 类型不统一时加适配或擦除层。

代码或图示

// 编译期检查方向:
// fn handler(req: Request<Incoming>) -> Result<Response<Full<Bytes>>, hyper::Error>
// 出站 body 必须是 Full<Bytes>;传入 String/&str 需包装

常见误区

  • 给响应直接传 String:未实现 Body,编译失败。
  • 不同分支返回不同 body 类型:服务签名无法统一,需适配器或枚举 body。

追问

  • 类型擦除怎么做?答:用 tower::ServiceExt::boxed 或把 body 擦除为动态 Body 实现;具体类型以当前版本为准。
  • 待确认点:当前版本 body 擦除适配器的精确类型名,以 http-body-util 文档为准。

04.4.7.2-037 HTTP 头部大小与数量限制在 Hyper 层如何处理?

一句话结论

协议解析层对头部缓冲与头部数量有默认上限,超限请求被拒绝;服务端 Builder 可按版本暴露调整项,业务层也应在解析前拒绝超大头部。

概念解释

恶意请求可用海量或超长头部耗尽内存,因此解析器限制头部总缓冲与条数。超限行为通常是协议错误,连接不可复用。业务安全上,鉴权令牌、追踪头都在头部,限制过松等于放开内存攻击面。调整上限前要确认上游代理是否会追加头部。

原理流程

  1. 连接上开始解析请求头部。
  2. 解析缓冲达到上限即判定超限。
  3. 协议层返回错误或拒绝报文。
  4. 连接进入不可复用状态。
  5. 业务日志记录超限请求的对端与路径。

代码或图示

// 待确认:当前版本 Builder 暴露的头部限制方法名
// http1::Builder::new().max_headers(..);
// 具体可配置项以 docs.rs hyper::server::conn::http1::Builder 为准

常见误区

  • 以为头部限制由业务代码强制:解析阶段先于业务 handler 执行。
  • 无上限调大缓冲:内存攻击面扩大。

追问

  • 头部超限对应什么客户端现象?答:连接被关闭或返回 431/400 类错误,具体状态依协议层与上层映射而定。
  • 大载荷为什么应放在 body 而不是头部?答:头部有大小限制且参与连接复用解析,body 才承载业务大数据。

04.4.7.2-038 分块传输(chunked)与 Content-Length 在响应里如何确定?

一句话结论

有明确长度时写 Content-Length;长度未知或流式产出时走分块传输(HTTP/1.1)或 HTTP/2 数据帧;Hyper/协议层按 body 结束帧完成报文收尾。

概念解释

响应体结束方式决定客户端如何判断 body 读完。固定 Full body 可推算长度;流 body 长度未知,HTTP/1.1 用 chunked 编码,HTTP/2 用数据帧加 END_STREAM。代理转发时长度头部可能需要重新计算。业务不要在流式响应上伪造 Content-Length 与实际长度不符。

原理流程

  1. 响应 body 类型决定是否可预知长度。
  2. 可预知则写 Content-Length。
  3. 不可预知则按协议分块或帧传输。
  4. body 结束帧发出后客户端判定完成。
  5. 长度不一致会被客户端或代理拒绝。

代码或图示

// 固定 body:长度由 Full 提供
// 流 body:不手写 Content-Length,由协议层分块
// 注意:篡改长度头部导致解析错乱

常见误区

  • 流式响应手写一个错误的 Content-Length:客户端等待超时或报文截断。
  • 代理转发时保留上游长度而 body 已改写:长度与实际不符。

追问

  • HTTP/2 还有 chunked 编码吗?答:HTTP/2 不使用 HTTP/1.1 chunked Transfer-Encoding,长度通过帧与 END_STREAM 标识。
  • 304 响应为什么不带 body 长度?答:304 按规范不含消息体,长度处理与普通响应不同。

04.4.7.2-039 解析 URI 路径与查询时要注意哪些边界?

一句话结论

Uri 提供原始路径与查询串,路径解码、段匹配、查询参数解析由业务或框架完成;要区分编码字符、尾斜杠与空段。

概念解释

uri.path() 返回已解码前的原始路径片段,uri.query() 返回未解析的查询串。URL 编码(百分号转义)需要单独解码;路径参数匹配由上层路由表完成。代理场景下 Uri 可能是绝对形式(origin-form 与 absolute-form),取路径前要判断形式。

原理流程

  1. 从 parts.uri 取 Uri。
  2. 判断请求形式,提取 path。
  3. 必要时百分号解码。
  4. 查询串按 &、= 解析到键值对。
  5. 解码失败或非法字符返回 400。

代码或图示

let path = req.uri().path().to_string();
let query = req.uri().query().unwrap_or_default();
// 查询解析交给 serde_urlencoded 等库;不自行手写易错解析

常见误区

  • 直接拿原始路径做中文匹配:未解码导致比较失败。
  • 手写查询串解析:遗漏编码值、空值与重复键等边界。

追问

  • 路径穿越风险怎么防?答:拼接文件路径前规范化并校验前缀,拒绝 .. 逃逸;文件服务由成熟库处理。
  • 待确认点:当前版本 Uri 暴露的 segment 解析辅助方法,以 http crate 文档为准。

04.4.7.2-040 Hyper 服务类型与 MakeService 是什么关系?

一句话结论

Service 是单次请求调用抽象,MakeService 是「产生 Service 的工厂」:每条连接或每个调用场景可以拿到一个新的服务实例,这正是上层框架把路由栈交给 Hyper 启动的接口形态。

概念解释

Hyper 连接循环需要一个能生成服务的工厂:MakeService 接收连接元信息并产出 Service。tower::make::MakeService 与 service_fn 系列提供构造方式。业务状态在工厂层注入,克隆出的服务实例共享 Arc 状态。理解工厂模式有助于解释为什么 axum 的 into_make_service 能直接交给监听循环。

原理流程

  1. 定义业务 Service 构造逻辑。
  2. 用工厂包装:每条连接调用工厂生成服务实例。
  3. Hyper 对连接上的请求调用该服务。
  4. 状态通过 Arc 在实例间共享。
  5. 工厂本身可克隆,随连接任务移动。

代码或图示

// tower 提供 make_service_fn 构造工厂(模块路径以 tower 当前版本为准)
// let make_svc = tower::service_fn(move |_conn| async move { Ok::<_, Error>(svc.clone()) });

常见误区

  • 把服务实例当成连接间共享的可变对象:每条连接拿到的是克隆实例,内部可变性靠共享状态实现。
  • 工厂返回的服务错误类型不匹配:连接层无法把错误映射到协议响应。

追问

  • MakeService 与 Service 的 Future 差异?答:工厂 Future 产出服务,服务 Future 产出响应;两者都走 poll_ready/call 抽象。
  • 待确认点:当前 Hyper 启动入口对工厂 trait 的精确约束,以 hyper server 模块文档为准。

04.4.7.2-041 Hyper 在安全上承担哪些职责,不承担哪些?

一句话结论

Hyper 负责协议解析完整性、帧边界与 IO 安全;鉴权、输入校验、CSRF、注入防护、敏感信息过滤等属于业务与中间件层职责。

概念解释

协议层保证不把非法帧误解析成请求,但不判断「请求是否有权限」。安全边界分层:TLS 终止在适配器层,CORS/鉴权/限流在 Tower 层,输入校验与业务授权在 handler 层。把安全逻辑寄托在协议库上是常见误区。日志与错误响应还需避免泄露内部细节。

原理流程

  1. TLS 层终止加密并校验证书。
  2. Hyper 解析合法报文。
  3. 中间件层做 CORS、鉴权、限流。
  4. handler 做参数校验与业务授权。
  5. 错误响应脱敏后返回。

代码或图示

TLS 适配器 -> Hyper 协议解析 -> Tower 安全层(CORS/鉴权/限流)-> handler 校验与授权

常见误区

  • 以为协议库天然防注入:SQL、命令、模板注入都在业务层。
  • 错误响应直接返回内部路径与栈信息:泄露部署细节。

追问

  • 头部注入风险如何避免?答:构造 HeaderValue 时使用安全 API,拒绝换行等非法字符;不拼接用户输入进头部。
  • 待确认点:当前版本头部值校验的严格程度,以 http crate 文档为准。

04.4.7.2-042 服务端进程的线程与任务在 Tokio + Hyper 下如何分布?

一句话结论

Tokio 多线程运行时按 worker 线程轮询大量连接任务与业务 Future;阻塞工作走 spawn_blocking 线程池;任务调度由运行时负责,业务代码不手动绑线程。

概念解释

默认多线程运行时有若干 worker 线程,数量通常与 CPU 核数相关。连接任务、业务 Future 都在 worker 上被 poll,IO 就绪后唤醒。阻塞线程池单独承载 spawn_blocking。这种模型用少量线程承载大量并发,前提是异步任务内不阻塞。worker 饱和表现为延迟上升而非线程数线性增长。

原理流程

  1. 启动多线程运行时,创建 worker 集合。
  2. 连接任务与 handler Future 进入任务队列。
  3. worker 轮询就绪任务推进。
  4. 阻塞调用移交阻塞线程池。
  5. 任务完成后释放队列位置。

代码或图示

#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
async fn main() {
    // 连接任务与业务 Future 由运行时调度
}

常见误区

  • 把连接数当成线程数:一条线程可承载大量连接任务。
  • 在 worker 上跑 CPU 密集循环:worker 被占满,全局延迟恶化。

追问

  • 如何观察 worker 饱和?答:看 tokio 任务排队、worker 忙碌指标与 P99 延迟;必要时调整 worker 数或卸载重任务。
  • current_thread 运行时适合什么场景?答:单线程事件循环场景,如工具命令或嵌入式服务;高并发服务默认多线程。

04.4.7.2-043 空闲连接回收与 keep-alive 探测在服务端怎么配置?

一句话结论

空闲连接由超时与探测机制回收,服务端 Builder 可按版本设置 keep-alive 相关间隔;未配置时依赖对端关闭或进程退出,可能残留半开连接。

概念解释

长服务积累大量空闲连接会占用文件描述符与内存。keep-alive 探测在空闲期发送探测帧确认对端存活;超时未响应则关闭。HTTP/1.1 与 HTTP/2 探测机制不同。生产环境应设置合理空闲上限,配合停机时主动关闭存量连接。

原理流程

  1. 连接进入空闲状态,启动空闲计时。
  2. 到达探测间隔发送探测。
  3. 对端响应则重置计时;无响应则进入超时关闭。
  4. 空闲超时到期主动关闭连接。
  5. 关闭事件计入连接回收指标。

代码或图示

// 待确认:当前版本空闲超时与探测方法名
// http1::Builder::new().keep_alive_timeout(Duration::from_secs(60));
// http2::Builder::new(executor).keep_alive_interval(..);

常见误区

  • 服务永不回收空闲连接:文件描述符缓慢耗尽。
  • 探测间隔过短:额外帧流量增加,对端被频繁探测。

追问

  • 半开连接为什么探测才发现?答:对端异常断网时 TCP 不一定收到 FIN,静默死连接需要探测或下次写入失败暴露。
  • 客户端与服务端空闲超时谁优先?答:先到期一方关闭连接;配置应避免两边超时倒挂导致频繁重连。

04.4.7.2-044 Hyper 直写与使用框架在维护成本上怎么权衡?

一句话结论

直写 Hyper 换来协议层可控与轻量,但要自建路由、校验、中间件与观测;业务接口密集的项目用 axum 等框架复用成熟能力,维护成本更低。

概念解释

选型看系统定位:网关、代理、协议适配层适合贴近 Hyper/Tower;面向业务的 CRUD 与 API 服务更需要提取器、错误映射、文档集成等框架能力。直写方案的隐性成本是中间件自研与踩坑,长期维护时容易重复造轮子。两者可共存:框架服务底层仍是 Hyper,需要定制时下沉到 Tower 层。

原理流程

  1. 梳理服务类型:协议适配还是业务接口。
  2. 评估自研路由/校验/中间件工作量。
  3. 对比框架成熟度与团队熟悉度。
  4. 确定协议层与框架层的边界。
  5. 压测验证性能与资源占用。

代码或图示

协议适配/代理  -> Hyper + Tower 直写
业务 API 服务  -> axum(Hyper + Tower 之上)

常见误区

  • 只按「性能」选直写:框架层开销通常不是瓶颈,业务复杂度才是。
  • 框架封装不够就改框架源码:优先在 Tower 层扩展。

追问

  • axum 服务能否下沉自定义 Hyper 行为?答:可以在服务栈外层包自定义层或适配连接行为;站点启动仍走框架的 make_service 接口。
  • 待确认点:当前版本各框架对底层 Hyper 版本的绑定关系,以各 crate 依赖声明为准。

04.4.7.2-045 Tower 项目在 Rust 异步生态中解决什么核心问题?

一句话结论

Tower 把「可复用的服务抽象」与「可组合的中间件层」标准化:Service trait 统一请求响应调用模型,Layer trait 统一包装方式,使协议层、框架与中间件可以互相拼装。

概念解释

没有 Tower 时,每个 Web 框架自定义中间件接口,日志、限流、重试等能力无法跨框架复用。Tower 定义服务与层两个核心 trait:服务处理请求产出响应,层包装服务增强行为。Hyper、axum、tonic 都围绕该抽象适配,同一批 tower 层可在不同协议栈复用。

原理流程

  1. 业务类型实现 Service<Request>。
  2. 用 Layer 包装出增强服务(日志、超时、限流等)。
  3. ServiceBuilder 按顺序组装层栈。
  4. 协议层把请求送入栈顶服务。
  5. 响应沿栈原路返回。

代码或图示

use tower::ServiceBuilder;

let svc = ServiceBuilder::new()
    .layer(tower_http::trace::TraceLayer::new())
    .layer(tower::timeout::TimeoutLayer::new(Duration::from_secs(5)))
    .service(inner);

常见误区

  • 把 Tower 当成 Web 框架:它不含路由与序列化,只提供服务与层抽象。
  • 以为中间件必须按框架特定宏编写:Tower 层跨协议复用。

追问

  • Tower 与 hyper 的依赖关系?答:Hyper 服务侧适配 Tower Service 模型;tower crate 本身不依赖 Hyper。
  • 生态里哪些库基于 Tower?答:axum、tonic、tower-http 等;完整生态以 crates.io 搜索为准。

04.4.7.2-046 读懂 Service trait 需要掌握哪几个关联项与方法?

一句话结论

Service<Request> 关联 Response、Error、Future,核心方法是 poll_ready(就绪检查)与 call(发起调用);服务通过这两个方法表达背压与调用。

概念解释

poll_ready 在调用前询问服务是否可接收请求,返回 Poll::Ready(Ok(())) 表示可调用,背压时挂起或返回错误。call 消费 self 或 &mut self,返回响应 Future。关联类型把请求类型、响应类型、错误类型与 Future 类型固定下来,使层可以在不了解内部实现的前提下包装服务。

原理流程

  1. 调用方先 poll_ready 等待就绪。
  2. 就绪后 call(req) 提交请求。
  3. 返回的 Future 被 poll 直到产出 Result<Response, Error>。
  4. 服务内部状态在多次调用间保留。
  5. 层包装时把内层关联类型映射成外层类型。

代码或图示

use tower::Service;
use std::future::Future;

// trait 骨架(完整定义以 tower 当前版本为准)
// trait Service<Request> {
//     type Response;
//     type Error;
//     type Future: Future<Output = Result<Self::Response, Self::Error>>;
//     fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
//     fn call(&mut self, req: Request) -> Self::Future;
// }

常见误区

  • 忽略 poll_ready 直接 call:违反服务就绪约定,背压层无法工作。
  • 把 Future 当成响应值:call 返回 Future,需要 await 才得到结果。

追问

  • call 为什么取 &mut self?答:服务持有内部状态(计数器、连接、缓冲),并发调用由服务克隆或并发控制保证安全;具体约束以 trait 定义为准。
  • 服务错误类型怎么统一?答:外层层用 map_err 或 BoxError 把内层错误收敛到同一类型。

04.4.7.2-047 poll_ready 如何实现背压,背压沿服务栈怎样传播?

一句话结论

内层服务不可就绪时 poll_ready 挂起或返回错误,外层层的 poll_ready 再向内询问,调用方在就绪前不提交请求;背压就这样沿层栈从业务服务传播到入口。

概念解释

背压的目标是在下游忙时阻止新请求涌入,而不是靠无限排队。限流、并发限制、缓冲层都通过 poll_ready 表达:槽位不足时返回未就绪,等待释放。调用方(Hyper 连接循环、客户端)在 poll_ready 未就绪前不发 call。每层可以叠加自己的就绪条件。

原理流程

  1. 入口准备调用服务,先轮询栈顶 poll_ready。
  2. 栈顶层向内询问下一层,逐层到底层服务。
  3. 底层无槽位则返回未就绪,通知等待。
  4. 槽位释放后唤醒,poll_ready 变为就绪。
  5. 入口才调用 call 提交请求。

代码或图示

入口 -> ConcurrencyLimit.poll_ready -> Retry.poll_ready -> 业务服务.poll_ready
槽位不足时整条链挂起,请求不进入 call

常见误区

  • 以为背压靠「队列满了再拒绝」:提前在就绪检查阶段排队等待,避免队列无限增长。
  • 层实现里忽略内层 poll_ready:内层背压被吞掉,流量直接压到底层。

追问

  • LoadShed 与 ConcurrencyLimit 背压有何不同?答:前者在未就绪时直接 shed 新请求,后者等待槽位;具体语义以 tower 各层文档为准。
  • 客户端如何配合背压?答:发送前等待服务就绪,或在连接池/信号量层限制并发,避免堆积未发出请求。

04.4.7.2-048 Layer trait 如何定义,层包装服务时类型如何变换?

一句话结论

Layer<S> 关联包装后的 Service 类型,方法 layer: fn(self, inner: S) -> Self::Service;层把内层服务包一层,增强行为并可能变换请求、响应与错误类型。

概念解释

层是无状态的包装器:构造时携带配置(超时时长、限流参数),组装时把内层服务包成新服务。包装后的服务对外暴露自己的关联类型,内部把请求转发给内层。多层包装形成嵌套结构:先加的层在最外层,请求先经过它,响应也最后经过它。

原理流程

  1. 层实例携带配置。
  2. ServiceBuilder 调用 layer(inner) 生成外层服务。
  3. 外层 poll_ready/call 委托内层并附加行为。
  4. 请求变换后转发,响应变换后返回。
  5. 错误类型可在层内映射。

代码或图示

use tower::Layer;

// 骨架(完整定义以 tower 当前版本为准)
// trait Layer<S> {
//     type Service;
//     fn layer(&self, inner: S) -> Self::Service;
// }

常见误区

  • 把层当成请求处理器:层不直接决定业务响应,只包装服务行为。
  • 混淆层的添加顺序与执行顺序:组装顺序与请求经过方向需要对照文档确认。

追问

  • 自定义层需要实现什么?答:实现 Layer trait 与包装出的 Service 类型;简单场景可用 ServiceBuilder::layer 配合现成组合子。
  • 层可以修改请求类型吗?答:可以在 call 内把请求映射成内层期望类型,外层暴露自己的请求类型。

04.4.7.2-049 ServiceBuilder 的层添加顺序与请求执行方向是什么关系?

一句话结论

ServiceBuilder 上先 layer 的层位于最外层:请求先经过它,响应也最后返回它;后添加的层更靠近业务服务。排查中间件行为时必须按这个方向核对顺序。

概念解释

层栈是嵌套包装:builder.layer(A).layer(B).service(inner) 形成 A 包 B 包 inner。请求进入顺序 A → B → inner;响应返回顺序 inner → B → A。日志、CORS、超时、限流等层对顺序敏感:例如记录耗时的层应在最外层,body 限制应在读取 body 之前。顺序写反会出现预检失败、超时不生效等问题。

原理流程

  1. 按「最外层先写」顺序在 builder 上添加层。
  2. service(inner) 完成嵌套。
  3. 请求自上而下穿过层栈到达业务。
  4. 响应自下而上穿过层栈返回。
  5. 错误与取消同样按栈方向传播。

代码或图示

let svc = ServiceBuilder::new()
    .layer(TraceLayer::new_for_http())   // 最外层:记录整体耗时
    .layer(CorsLayer::new())             // 预检与跨域处理
    .layer(TimeoutLayer::new(Duration::from_secs(5)))
    .service(inner);

常见误区

  • 以为先添加的层先到业务:方向相反,先添加在最外层。
  • 把 body 限制层放在压缩/日志之后:大 body 已被读入才限流,失去保护意义。

追问

  • 全局层与路由级层顺序怎么协调?答:全局层包裹整棵路由,路由级层只作用于子路由;请求先过全局外层再进路由内层。
  • 待确认点:当前 tower-http 各层对顺序的硬性要求,以对应层文档的「顺序注意事项」为准。

04.4.7.2-050 ServiceExt 提供哪些常用组合子,分别在什么场景用?

一句话结论

ServiceExt 为服务提供 oneshot、ready、boxed、map_request、map_response、map_err、buffer 等组合子,用于测试、类型擦除与请求响应变换。

概念解释

组合子避免手写完整包装服务:oneshot 单次调用用于测试;ready 等待就绪;boxed 擦除服务类型;map_request/map_response 改请求或响应;map_err 收敛错误;buffer 给服务加并发缓冲。组合子可链式叠加,最终服务类型由链上变换决定。

原理流程

  1. 拿到基础服务。
  2. 按需链式调用组合子包装。
  3. 每个组合子返回新服务类型。
  4. 类型复杂时用 boxed 擦除。
  5. 组装进最终服务栈。

代码或图示

use tower::ServiceExt;

let svc = inner
    .map_request(|req: Request<Full<Bytes>>| req)
    .map_response(|resp| resp)
    .map_err(Box::from)
    .boxed();

常见误区

  • 链式组合后类型无法命名:服务栈泛型嵌套过深,应及时 boxed。
  • map_err 后错误类型与下游期望不一致:需要统一到 BoxError 或自定义错误。

追问

  • boxed 代价是什么?答:动态分发与类型擦除带来少量开销,换来类型简化;热路径上注意测量。
  • buffer 组合子与 Buffer 层什么关系?答:buffer 是 ServiceExt 上的便捷包装,底层对应 buffer 层;具体签名以 tower 文档为准。

04.4.7.2-051 Buffer 层解决什么问题,内部如何工作?

一句话结论

Buffer 在服务前加一个有界通道,把并发调用排队到内部任务执行,使不满足并发调用约束的服务可以被多个请求并发使用;代价是排队延迟与有界缓冲。

概念解释

有些服务内部状态不适合被多个调用同时 &mut 访问,或需要串行化执行。Buffer 层把请求送入通道,由单个后台任务消费并调用内层服务,外部表现为可并发提交。通道有界,背压通过 poll_ready 反映。需要克隆服务类型或共享状态时,Buffer 是常见粘合层。

原理流程

  1. 配置缓冲容量,包装内层服务。
  2. 请求进入层后写入内部通道。
  3. 后台任务从通道取请求,调用内层服务。
  4. 响应 Future 结果回传给调用方。
  5. 通道满时 poll_ready 未就绪,形成背压。

代码或图示

use tower::buffer::Buffer;

let svc = Buffer::new(inner, 32);
// 容量为通道缓冲大小;待确认当前版本构造签名以 tower 文档为准

常见误区

  • 给无并发问题的服务盲目加 Buffer:增加一跳排队延迟。
  • 缓冲容量设得过大:背压失效,积压请求在内存里排队。

追问

  • Buffer 与 ConcurrencyLimit 区别?答:Buffer 串行化/排队到内部任务,ConcurrencyLimit 限制同时在途调用数;两者可叠加。
  • 缓冲满了返回什么?答:poll_ready 未就绪或返回错误,依层实现而定;具体错误类型以 tower 文档为准。

04.4.7.2-052 RateLimit 层如何限流,基于什么算法?

一句话结论

RateLimit 按固定时间窗口限制单位时间内允许的调用次数,超出后在就绪检查阶段拒绝或等待;底层算法与默认实现以 tower 当前版本文档为准。

概念解释

限流保护下游不被突发流量打垮。RateLimit 维护计数与重置周期,每次 poll_ready 或 call 检查配额。超出配额时服务未就绪,调用方排队或收到限流错误。注意它是进程内限流,多实例部署时全局配额需要外部限流组件配合。

原理流程

  1. 配置配额(次数)与周期。
  2. 层记录当前窗口已用计数。
  3. 调用前检查剩余配额。
  4. 有配额则放行并计数;无配额则未就绪或拒绝。
  5. 窗口到期重置计数。

代码或图示

use tower::limit::RateLimit;
use std::time::Duration;

// 示意:每周期允许 N 次调用;构造参数以 tower 当前版本为准
// let svc = RateLimit::new(inner, N, Duration::from_secs(1));

常见误区

  • 以为进程内限流等于全局限流:多副本下每副本独立计数。
  • 把限流阈值设成下游容量上限:突发与重试叠加容易击穿,应留余量。

追问

  • 固定窗口有什么缺陷?答:窗口边界可能出现双倍突发;更平滑的算法(令牌桶、漏桶)需选用对应层或自定义实现。
  • 限流响应怎么返回给客户端?答:层错误在栈上被映射成 429 状态码与重试提示头;映射逻辑由上层完成。

04.4.7.2-053 Retry 层如何工作,重试策略怎么定义?

一句话结论

Retry 层在请求失败后按 Policy 决定是否重试、等待多久再重试;策略需要判断错误可重试性、次数上限与退避间隔。

概念解释

重试用于应对瞬时故障(连接重置、503、超时)。Policy 检查响应或错误,给出重试/不重试决策与延迟。层需要克隆请求以再次发送,因此请求类型通常要求 Clone。重试会放大流量,必须配合幂等性判断与次数上限。非幂等写接口盲目重试可能造成重复下单。

原理流程

  1. 配置 Policy:可重试错误条件、最大次数、退避。
  2. 首次调用内层服务。
  3. 结果交给 Policy 判断。
  4. 可重试则等待退避后克隆请求再次调用。
  5. 超过次数或不可重试则返回最终结果。

代码或图示

use tower::retry::Retry;

// 示意:策略类型与构造方式以 tower 当前版本为准
// let svc = Retry::new(policy, inner);
// Policy 需对错误/响应分类,并记录重试次数

常见误区

  • 对 POST 写接口无脑重试:重复副作用风险高。
  • 不设退避与上限:故障期间重试风暴压垮下游。

追问

  • 重试要求请求实现什么?答:重试需要再次发送请求,请求与 body 通常要可克隆;流式 body 无法重放时不能直接重试。
  • 哪些错误一般不重试?答:4xx 参数错误、鉴权失败、业务明确拒绝;连接类瞬时错误与 503/超时可考虑重试。

04.4.7.2-054 Timeout 层如何给调用加超时,超时后内部任务怎么处理?

一句话结论

Timeout 包裹内层 Future,在业务完成与定时器之间竞速;定时器先触发则返回超时错误,内层 Future 被丢弃,需要业务自行保证取消后资源释放。

概念解释

超时防止慢请求长期占用槽位。层启动一个定时器,业务 Future 先完成则取业务结果;超时先到则返回 TimeoutError。被丢弃的 Future 不会自动回滚已做工作:数据库事务、已发下游请求需要靠取消令牌或事务边界回收。流式接口慎用整体超时。

原理流程

  1. 配置超时时长。
  2. 请求进入层,同时轮询业务 Future 与定时器。
  3. 业务先完成:返回响应。
  4. 定时器先触发:取消 Future,返回超时错误。
  5. 业务侧监听取消信号清理资源。

代码或图示

use tower::timeout::Timeout;
use std::time::Duration;

let svc = Timeout::new(inner, Duration::from_secs(5));
// 超时错误类型:tower::timeout::error::Elapsed(名称以当前版本为准)

常见误区

  • 以为超时会回滚内层操作:Future 丢弃不等于事务回滚。
  • 给长轮询/SSE 套整体超时:正常长连接被误杀。

追问

  • 超时错误如何映射成 HTTP 响应?答:在外层 map_err 或框架错误处理中转为 504 并返回提示体。
  • 分段超时怎么做?答:对下游调用分别设超时,流读取设帧间隔超时,而不是整条链路一个总时长。

04.4.7.2-055 ConcurrencyLimit 与 LoadShed 分别在什么场景使用?

一句话结论

ConcurrencyLimit 限制同时在途调用数,超出后排队等待槽位;LoadShed 在服务未就绪时直接拒绝新请求,适合过载时快速 shedding 保护核心路径。

概念解释

并发限制控制在途请求量,避免资源被无限并发占满。排队等待适合短时波动;负载丢弃适合已经过载、排队只会放大延迟的场景,直接返回错误让上游退避。两者都通过 poll_ready 表达:限制层先检查槽位,再询问内层。生产中常把并发限制放在外层,配合 shed 策略兜底。

原理流程

  1. 配置最大并发数。
  2. 每次调用占用一个槽位,响应完成释放。
  3. 槽位满时 poll_ready 未就绪。
  4. ConcurrencyLimit 等待槽位;LoadShed 直接拒绝。
  5. 拒绝响应映射为 503 或 429。

代码或图示

use tower::limit::ConcurrencyLimit;
use tower::load_shed::LoadShed;

// 示意;构造参数以 tower 当前版本为准
// let svc = ConcurrencyLimit::new(inner, 100);
// let svc = LoadShed::new(inner);

常见误区

  • 过载时还无限排队:延迟雪崩,不如快速失败让上游重试。
  • 把并发限制值设成与 CPU 核数相同:IO 密集服务并发可以远高于核数。

追问

  • 并发数怎么定?答:按下游依赖容量、内存占用与压测 P99 反推,先保守再逐步上调。
  • LoadShed 拒绝的请求客户端如何处理?答:应识别 503/429 并按退避重试,不能立即死循环重发。

04.4.7.2-056 如何自定义一个 Tower Layer,需要写哪些类型?

一句话结论

实现 Layer<S> 生成包装服务,并为包装类型实现 Service trait;层配置存在层实例里,包装服务持有内层服务与配置。

概念解释

自定义层分两部分:层结构体携带配置,layer 方法构造包装服务;包装服务实现 poll_ready 委托内层并附加自己的就绪条件,call 转发请求并在前后加行为。请求/响应/错误类型可以透传或变换。简单横切行为也可以用 ServiceBuilder 组合子拼装,不必从零写 trait。

原理流程

  1. 定义层结构体与配置字段。
  2. 实现 Layer<S>,返回包装服务类型。
  3. 包装服务持有内层服务与配置。
  4. 实现 poll_ready:先检查自身条件,再询问内层。
  5. 实现 call:附加行为后调用内层,处理响应与错误。

代码或图示

use tower::{Layer, Service};

struct LogLayer;
impl<S> Layer<S> for LogLayer {
    type Service = LogService<S>;
    fn layer(&self, inner: S) -> Self::Service { LogService { inner } }
}

struct LogService<S> { inner: S }
// 为 LogService 实现 Service:poll_ready 委托 inner,call 前后记录日志

常见误区

  • 层实现里忘记委托内层 poll_ready:内层背压丢失。
  • 包装服务不满足 Clone/Send:无法跨连接与任务使用。

追问

  • 自定义层如何读取或修改请求?答:在 call 内访问请求头部、body 或状态;需要消费 body 的层要注意 body 只能读一次。
  • 待确认点:当前 tower 版本 Layer/Service trait 精确签名,以 docs.rs 为准。

04.4.7.2-057 如何自定义一个 Service,与用 service_fn 有什么取舍?

一句话结论

无状态、单个处理函数的场景用 service_fn 把闭包装成服务;需要持有内部状态、多次调用间累积数据或自定义就绪逻辑时,手写实现 Service 的结构体。

概念解释

service_fn 接收返回 Future 的函数,自动生成服务类型,错误类型默认推断或用 service_fn_with_error 指定。手写 Service 可以在 poll_ready 里做排队、限流判断,在 call 里维护计数器、缓存或连接。状态需要在克隆实例间共享时,把共享部分放进 Arc。

原理流程

  1. 判断服务是否需要跨调用状态。
  2. 无状态:service_fn 定义异步处理函数。
  3. 有状态:定义结构体持有内层或状态。
  4. 实现 poll_ready 与 call。
  5. 按需实现 Clone,共享状态用 Arc。

代码或图示

use tower::service_fn;

let svc = service_fn(|req: Request<Full<Bytes>>| async move {
    Ok::<Response<Full<Bytes>>, BoxError>(Response::new(Full::new(Bytes::from("ok"))))
});

常见误区

  • 在 service_fn 闭包里捕获不可克隆状态:服务克隆时编译失败。
  • 手写 Service 时 call 不返回正确 Future 类型:关联类型约束不满足。

追问

  • service_fn_with_error 解决什么?答:显式指定错误类型,避免推断出难以映射的错误类型;名称以当前版本为准。
  • 服务内部状态线程安全要求?答:跨任务使用时服务需 Send,共享可变状态需 Sync 并加同步原语。

04.4.7.2-058 层栈上错误类型如何收敛,BoxError 起什么作用?

一句话结论

各层错误类型不同,通过 map_err 转成统一类型;BoxError(Box<dyn Error + Send + Sync>)是 Tower 生态常用的擦除错误类型,便于层栈组合。

概念解释

服务栈泛型嵌套后,错误类型是各层错误的组合,难以命名与匹配。BoxError 把具体错误装箱为 trait object,保留错误链但擦除具体类型。业务边界再从 BoxError downcast 或按错误链识别。注意装箱会丢失静态类型信息,需要结构化错误时在业务层用自定义错误枚举。

原理流程

  1. 内层服务返回具体错误类型。
  2. 外层 map_err 把错误转换为 BoxError。
  3. 栈上各层错误统一为 BoxError。
  4. 入口层按错误链或 downcast 分类。
  5. 映射成 HTTP 状态码与响应体。

代码或图示

use tower::BoxError;

// map_err 示例:
// let svc = inner.map_err(|e| -> BoxError { Box::from(e) });

常见误区

  • 所有错误直接 Box 后不再分类:排错时只能看消息字符串。
  • 错误链被截断:Box::from 应保留 source 链,不丢弃上下文。

追问

  • BoxError 与 anyhow::Error 区别?答:都做错误擦除;BoxError 是 Tower 约定类型,anyhow 是通用应用层错误容器,可互相转换。
  • 结构化错误怎么保留?答:业务边界定义 thiserror 枚举,仅在跨层栈组合时装箱,返回前再还原分类。

04.4.7.2-059 服务栈如何与 MakeService 组装后交给协议层启动?

一句话结论

先用 ServiceBuilder 把层包到业务服务外,再用工厂包装成 MakeService,协议层每条连接从工厂取服务实例;共享状态在工厂构造时注入。

概念解释

启动链路:业务 handler → 层栈服务 → 工厂 → Hyper/协议连接循环。工厂在每条连接产生一个服务克隆,层栈与业务状态通过克隆共享。axum 的 into_make_service 就是完成这一步封装。理解组装顺序有助于定位「层没生效」是加在工厂内还是连接外。

原理流程

  1. 构造共享状态与业务服务。
  2. ServiceBuilder 叠加中间件层。
  3. 工厂闭包克隆服务提交给每条连接。
  4. 协议层 accept 连接后从工厂取服务。
  5. 请求穿过层栈到达业务。

代码或图示

// 示意组装链
// let app = ServiceBuilder::new().layer(trace).service(handler);
// let make_svc = make_service_fn(move |_| async move { Ok::<_, Error>(app.clone()) });
// hyper serve_connection(io, make_svc)

常见误区

  • 把只应初始化一次的资源放在工厂内每条连接重建:连接池、缓存反复创建。
  • 层加在工厂外面:作用于工厂本身而不是每个服务实例。

追问

  • 为什么服务要 Clone?答:工厂为每条连接提供独立实例,克隆共享内部 Arc 状态。
  • 待确认点:当前版本 Hyper 启动对工厂 trait 的精确名称与约束,以 hyper server 文档为准。

04.4.7.2-060 map_request、map_response、map_future 分别变换什么?

一句话结论

map_request 改进入站请求,map_response 改出站响应,map_future 包裹返回的 Future 做异步后处理;三者都是不改写完整服务实现的轻量组合子。

概念解释

请求变换常用于注入头部、补默认参数;响应变换常用于统一包装、加响应头;Future 变换用于在响应完成前后挂异步逻辑(记录耗时、触发副作用)。组合子返回新服务类型,链式叠加时注意类型一致。body 在请求/响应变换中同样只能消费一次。

原理流程

  1. 基础服务就绪后调用组合子。
  2. map_request:请求进内层前执行闭包。
  3. map_response:响应出内层后执行闭包。
  4. map_future:对响应 Future 做包装。
  5. 结果继续向下游返回。

代码或图示

use tower::ServiceExt;

let svc = inner
    .map_request(|mut req: Request<Full<Bytes>>| {
        req.headers_mut().insert("x-trace", "v".parse().unwrap());
        req
    })
    .map_response(|resp| resp);

常见误区

  • 在 map_request 里消费 body 后内层拿不到:body 流被读完。
  • 变换闭包返回类型与链上期望不一致:编译报类型不匹配。

追问

  • map_future 适合做什么?答:需要在 Future 完成时 await 额外逻辑(异步记录、指标上报)的场景;纯同步变换用 map_response 即可。
  • 组合子顺序影响什么?答:外层变换先看到原始请求/响应,内层变换更靠近业务;顺序对照层栈方向理解。

04.4.7.2-061 层栈里共享状态如何传递,Clone 与 Arc 怎么配合?

一句话结论

服务与层实例按连接克隆,不可变配置直接复制;需要跨实例共享的可变或重型状态放进 Arc,克隆时只复制句柄。

概念解释

Tower 服务常在工厂里克隆给每条连接。状态分三类:不可变配置可随克隆复制;只读共享数据用 Arc<T>;跨实例可变数据用 Arc<Mutex<T>> 或 Arc<RwLock<T>>。数据库连接池本身通常是 Arc 内部结构,克隆句柄即复用池。避免把大对象按连接深拷贝。

原理流程

  1. 构造状态:配置值、Arc 共享数据、同步原语。
  2. 基础服务持有状态句柄。
  3. 工厂克隆服务到各连接。
  4. 克隆共享同一 Arc 指向的对象。
  5. 访问共享可变数据时按同步规则加锁。

代码或图示

use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    config: Arc<Config>,
    pool: Arc<DbPool>,
}
// 服务持有 AppState;克隆时 Arc 句柄复制,底层对象共享

常见误区

  • 每连接新建一个连接池:数据库连接数随连接数膨胀。
  • 共享状态不满足 Send + Sync:跨任务编译失败或运行期数据竞争。

追问

  • 状态里放 Rc 为什么不行?答:Rc 不跨线程,服务跨任务使用需要 Send;共享所有权用 Arc。
  • 异步锁与同步锁怎么选?答:临界区极短用同步锁,避免跨 await 持有;可能等待的资源用异步锁或消息传递。

04.4.7.2-062 Tower 层与 axum 中间件是什么对应关系?

一句话结论

axum 的中间件底层就是 Tower 层:Router::layer 接收 Tower Layer 或适配的闭包中间件,请求同样经过 Service 栈;因此 tower-http 层可直接用在 axum 路由上。

概念解释

axum 在 Router 内部把路由处理包装成 Tower Service,layer 方法把给定层套到服务外。手写 Tower 层可以直接复用到 axum;axum 特定的闭包中间件(from_fn)会被适配成 Tower 服务。区别只在注册方式:全局层包整树,路由级层只包子路由。

原理流程

  1. Router 编译为内部服务。
  2. layer 把 Tower 层套在服务外。
  3. 请求进入嵌套层栈。
  4. 业务 handler 在最内层执行。
  5. 响应沿栈返回。

代码或图示

use tower_http::trace::TraceLayer;

let app = Router::new()
    .route("/", get(handler))
    .layer(TraceLayer::new_for_http());

常见误区

  • 以为 axum 中间件是另一套不兼容抽象:底层仍是 Tower。
  • 路由级层与全局层顺序混淆:全局外层先执行,再进路由内层。

追问

  • from_fn 中间件与 Tower Layer 怎么选?答:简单请求响应装饰用 from_fn;需要复用、携带复杂策略或跨框架使用时写 Tower Layer。
  • 待确认点:当前 axum 版本中间件注册 API 名称,以 axum 文档为准。

04.4.7.2-063 服务栈上的类型为什么会变得很复杂,怎么简化?

一句话结论

每层包装产生新的泛型服务类型,嵌套后类型名极长难以书写;简化手段是及时 boxed 擦除类型、收敛错误类型、把层栈封装到构造函数内。

概念解释

服务类型是 LayerC<LayerB<LayerA<Inner>>> 形式,链式组合后泛型参数层层叠加。函数签名无法命名这种类型时,编译器可以推断但代码可读性差。boxed 把服务擦除为 BoxService<Request, Response, Error>,代价是一层动态分发。错误类型统一为 BoxError 后类型链也随之简化。

原理流程

  1. 组装层栈后查看推断的服务类型。
  2. 类型过深时在末尾 .boxed()。
  3. 错误用 map_err 收敛到 BoxError。
  4. 把组装逻辑封装到返回 BoxService 的构造函数。
  5. 调用方只面对擦除后的类型。

代码或图示

use tower::ServiceExt;

let svc = ServiceBuilder::new()
    .layer(timeout)
    .layer(trace)
    .service(inner)
    .boxed();

常见误区

  • 过早 boxed 每一层:动态分发层数增多,热路径开销累积。
  • 不收敛错误类型:下游函数签名被内层错误类型绑死。

追问

  • BoxService 内部是什么?答:持有动态分发的服务句柄;待确认当前版本具体实现类型,以 tower 文档为准。
  • 类型擦除影响性能吗?答:每层 boxed 多一次间接调用,极端高 QPS 下测量后再决定保留静态类型。

04.4.7.2-064 背压如何沿层栈传播,哪一层破坏背压最常见?

一句话结论

poll_ready 逐层向内询问,内层未就绪则外层也未就绪;常见破坏点是层实现里直接调用内层而不先 poll_ready,或内部无界缓冲把积压藏起来。

概念解释

正确背压要求每层在 call 前把就绪状态透传。若某层内部用无界队列接收请求,外层看到的是「永远就绪」,积压实际发生在层内。Buffer、Retry 等有内部队列的层必须在队列满时反馈未就绪。排查背压失效:从入口往下追每一层的 poll_ready 实现与缓冲上界。

原理流程

  1. 入口调用栈顶 poll_ready。
  2. 每层先检查自身缓冲/槽位,再询问内层。
  3. 任一环节未就绪,栈顶未就绪。
  4. 调用方等待唤醒,不提交 call。
  5. 资源释放后链路重新就绪。

代码或图示

正确:Layer.poll_ready -> inner.poll_ready
破坏:Layer 内部 spawn 无界任务,poll_ready 永远 Ready

常见误区

  • 在层里 spawn 任务后立即返回成功:请求积压在任务队列,背压失效。
  • 队列只进不出地累积:内存随请求数增长直到 OOM。

追问

  • 如何验证背压生效?答:压测时观察在途请求数、队列长度与内存;下游变慢时入口并发应被限制而不是无限排队。
  • 重试层会破坏背压吗?答:重试会重复占用槽位,策略上要限制在途重试次数,避免放大并发。

04.4.7.2-065 重试策略如何判断幂等性,写接口重试要注意什么?

一句话结论

只有确认请求可安全重复执行(幂等)才允许自动重试;写接口重试前要确认业务去重机制,否则可能产生重复创建、重复扣款等副作用。

概念解释

幂等指同一请求执行多次效果与一次相同。GET、DELETE 通常幂等;POST 创建资源天然非幂等,除非带幂等键且服务端去重。重试策略应按方法与错误类型区分:瞬时网络错误可重试,业务拒绝不重试。退避策略避免重试风暴,次数必须有上限。

原理流程

  1. 识别请求方法与业务语义。
  2. 判断错误是否瞬时可重试。
  3. 非幂等写接口:检查幂等键与去重能力。
  4. 满足条件才按退避重试。
  5. 超过上限返回最终错误。

代码或图示

GET /resource      -> 可重试
POST /orders       -> 默认不重试;带幂等键且服务端去重后可有限重试
503 / 连接重置     -> 可重试候选
400 / 401 / 403    -> 不重试

常见误区

  • 对所有 5xx 一律重试:500 可能是确定性错误,重试重复副作用。
  • 退避不带抖动:同步重试在同一时刻冲击下游。

追问

  • 幂等键怎么设计?答:客户端生成唯一键随请求携带,服务端按键记录结果;重复请求返回首次结果。
  • 重试期间请求 body 必须可克隆吗?答:是,重试需要再次发送;流式 body 无法重放,不能进入重试层。

04.4.7.2-066 进程内限流与全局限流有什么区别,多副本怎么配合?

一句话结论

Tower 限流层是单进程内计数;多副本部署时全局配额需要网关层、共享存储或外部限流组件统一控制,进程内限流只作为本地兜底。

概念解释

本地限流防止单实例被打垮,但 N 副本各自计数会使总流量放大 N 倍。全局限流常在入口网关统一计数,或用 Redis 等共享存储实现令牌桶。两层配合:全局保护整体容量,本地防止单实例突发。分布式限流还需考虑时钟与网络开销。

原理流程

  1. 入口全局限流按全局限额放行。
  2. 请求到达各副本。
  3. 本地限流层做二次兜底。
  4. 超限本地快速失败。
  5. 指标上报全局观察限流命中率。

代码或图示

客户端 -> 网关全局限流 -> 副本 A 本地限流 -> 业务
                      -> 副本 B 本地限流 -> 业务

常见误区

  • 以为本地限流值乘以副本数就是全局容量:突发与不均衡分布会超容。
  • 全局限流在每个副本重复做:共享存储竞争放大。

追问

  • 分布式限流常见算法?答:固定窗口计数、滑动日志、令牌桶;实现可用 Redis + Lua 或专用限流网关。
  • 待确认点:Tower 是否提供分布式层;标准 tower 限流水位为进程内实现。

04.4.7.2-067 如何在测试中验证一个服务栈的层行为是否生效?

一句话结论

用 oneshot 喂请求,断言响应状态、头部与 body;针对超时、限流等层,配合可控的慢服务或统计计数验证触发条件与次数。

概念解释

层行为测试分两类:变换类(加头、改响应)直接断言输出;策略类(超时、限流、重试)需要构造可控内层服务,观察调用次数与等待结果。测试不依赖真实网络,服务栈在内存中组装。慢服务用 oneshot 挂起的 Future 或通道控制完成时机。

原理流程

  1. 组装被测层栈与可控内层服务。
  2. oneshot 提交请求。
  3. 断言响应与层附加头部。
  4. 策略层:控制内层慢/失败,观察重试次数或超时错误。
  5. 清理测试任务避免挂起。

代码或图示

use tower::ServiceExt;

// let svc = Timeout::new(controlled_slow_svc, Duration::from_millis(10));
// let result = svc.oneshot(req).await;
// 断言返回 Elapsed 类错误(类型名以当前版本为准)

常见误区

  • 只测业务 handler 不测层:中间件顺序错误在集成阶段才暴露。
  • 测试里内层 Future 不完成:超时路径测试挂起,需用超时包装或手动释放。

追问

  • 如何统计内层被调用次数?答:内层服务持有 Arc<AtomicUsize> 计数,每次 call 自增;断言重试/限流后的计数。
  • 流式服务怎么测层?答:逐帧消费响应 body,验证层对帧序列与结束帧的处理。

04.4.7.2-068 服务层实现需要满足哪些 Send/Sync 约束?

一句话结论

跨任务调度的服务通常要求 Send;共享引用访问要求 Sync。层与服务内部持有类型必须满足对应约束,否则无法在多线程运行时上使用。

概念解释

连接任务被 spawn 到 Tokio worker 之间迁移,服务与 Future 需 Send。多个任务共享服务引用时内部状态需 Sync。Rc、裸指针、非同步锁等不满足跨线程约束。排查编译错误时先定位是服务不 Send 还是内部状态不 Sync,再替换为 Arc 与同步原语。

原理流程

  1. 服务被提交到任务,编译器检查 Send。
  2. Future 捕获的状态必须随任务跨线程移动。
  3. 共享引用访问检查 Sync。
  4. 不满足时替换为线程安全类型。
  5. 必要时审查 unsafe 边界。

代码或图示

// 典型约束:服务克隆后送入 spawn 的连接任务
// tokio::spawn(async move { conn.await });
// 服务与响应 Future 需满足 Send;内部共享状态需 Sync

常见误区

  • 在异步任务里捕获 Rc:编译报不满足 Send。
  • 用非 Sync 类型做全局共享:引用跨线程访问违反约束。

追问

  • &mut self 服务如何并发使用?答:通过克隆服务实例、Buffer 串行化或外部同步控制;单实例 &mut 不能同时被多个调用借用。
  • 待确认点:当前 tower 层派生的自动约束,以 trait 定义与编译提示为准。

04.4.7.2-069 为什么有些层需要请求实现 Clone,流式 body 为什么不行?

一句话结论

重试、缓冲等层需要再次发送请求,要求请求整体可克隆;流式 body 是一次性句柄,无法重放,因此这类层不能直接包裹含流式 body 的服务。

概念解释

重试层在失败后第二次 call 需要同一个请求;若 body 是流,第一遍读取后帧已消费,克隆得到的是无效句柄。解决方式:在进入重试层前把 body 收集为可克隆缓冲,或把重试限制在不含 body 的阶段。请求元信息(头部)可克隆,瓶颈通常在 body 类型。

原理流程

  1. 层声明 Request: Clone 约束。
  2. 服务栈编译时检查请求与 body 类型。
  3. 固定 body(Full<Bytes>、Bytes)可克隆。
  4. 流 body 不满足克隆,编译失败。
  5. 收集 body 后再进入可重试层。

代码或图示

可重试:Request<Full<Bytes>> / Request<Bytes>
不可直接重试:Request<Incoming>(流句柄)

常见误区

  • 给流式上传接口套重试层:编译不过或重发放空 body。
  • 以为克隆请求会复制全部 body 字节:固定 body 克隆是 Bytes 引用计数共享,不深拷贝。

追问

  • 大请求体如何兼顾重试与内存?答:有限大小内收集到缓冲;超大流不重试,由业务幂等与下游重试处理。
  • 重试层还要求响应克隆吗?答:不需要重发响应;重试只重复请求,响应按每次调用返回。

04.4.7.2-070 tower-http 与 tower 是什么关系,覆盖了哪些能力域?

一句话结论

tower 提供 Service/Layer 抽象与通用治理层,tower-http 在其上实现 HTTP 专用层:追踪日志、跨域、压缩、超时、请求体限制、请求 ID、静态文件等。

概念解释

tower 层不感知 HTTP 语义(不知道方法、头部、body 大小);tower-http 层面向 HTTP 请求响应模型,读取头部、解析 body、改写响应。两者配合:通用并发治理用 tower,HTTP 横切能力用 tower-http。层可在同一栈上混用,顺序遵循通用层栈规则。

原理流程

  1. 业务服务进入栈底。
  2. tower-http 层处理 HTTP 语义(日志、CORS、压缩)。
  3. tower 层做通用治理(超时、限流、并发限制)。
  4. 协议层送请求入栈。
  5. 响应沿栈返回并被各层处理。

代码或图示

tower = "0.5"
tower-http = { version = "0.6", features = ["trace", "cors", "compression", "timeout", "limit", "request-id"] }

常见误区

  • 把 HTTP 专用逻辑写进 tower 通用层:重复造轮子且不复用生态。
  • 混淆两者 feature:编译缺方法时先查对应 crate 文档。

追问

  • tower-http 静态文件层是哪个?答:ServeDir/ServeFile,位于 fs feature;具体类型名以当前版本为准。
  • 待确认点:当前 tower-http 版本各模块路径,以 docs.rs 目录为准。

04.4.7.2-071 TraceLayer 如何记录请求生命周期,span 里包含哪些字段?

一句话结论

TraceLayer 在请求进入时创建 tracing span,记录方法、路径、状态码、耗时与响应大小,请求结束关闭 span;字段与钩子可按配置定制。

概念解释

TraceLayer 是接入 tracing 生态的 HTTP 中间件:请求开始建立 span,层内钩子记录头部、路径,响应后记录状态码与延迟。配合 subscriber 输出日志或导出 OpenTelemetry。它不替代业务日志,只覆盖 HTTP 层横切观测。注意 span 内不要塞入敏感头部值。

原理流程

  1. 请求进入层,调用 make_span 构造 span。
  2. 进入 span 记录请求元信息。
  3. 请求穿过内层服务。
  4. 响应返回时记录状态码、耗时、body 大小。
  5. 关闭 span,事件进入日志/追踪管线。

代码或图示

use tower_http::trace::TraceLayer;

let layer = TraceLayer::new_for_http();
// 可自定义 make_span、on_request、on_response 钩子;具体 API 以文档为准

常见误区

  • 未配置 tracing subscriber:span 事件无处输出,看似层没生效。
  • 在 span 里记录 Authorization 等敏感头:日志泄露凭证。

追问

  • TraceLayer 放在栈的什么位置?答:通常最外层,才能记录整体耗时与所有内部层行为;置于内层则只覆盖部分链路。
  • 如何关联跨服务调用?答:从请求头部提取 trace 上下文注入 span;具体传播格式由 OpenTelemetry 集成配置。

04.4.7.2-072 CorsLayer 如何配置允许源、方法与头部?

一句话结论

CorsLayer 通过 builder 方法声明允许的源、方法、请求头与暴露头,自动处理预检 OPTIONS 请求;配置过宽(允许任意源加凭证)是常见安全问题。

概念解释

浏览器跨域受同源策略限制,服务端通过 CORS 头部放行。CorsLayer 读取 Origin,按规则返回 Access-Control-Allow-* 头部;预检请求在层内直接响应,不进入业务。允许凭证时不能同时使用通配源,浏览器规范对此有限制。生产环境按域名白名单配置。

原理流程

  1. 配置允许源、方法、头部、凭证策略。
  2. 浏览器预检发送 OPTIONS 带 Access-Control-Request-Method。
  3. 层校验规则后返回预检响应与头部。
  4. 实际请求到达,层追加允许源等头部。
  5. 浏览器依据头部决定是否放行响应。

代码或图示

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

// 示意;具体 builder 方法名以 tower-http 当前版本为准
// let cors = CorsLayer::new()
//     .allow_origin(Any)
//     .allow_methods(Any)
//     .allow_headers(Any);

常见误区

  • 生产环境 allow_origin(Any) 且允许凭证:安全风险高。
  • 漏掉暴露响应头:自定义响应头在浏览器侧读不到。

追问

  • 预检请求为什么不进业务 handler?答:CorsLayer 在层内处理 OPTIONS 预检,避免业务重复实现跨域逻辑。
  • 待确认点:当前版本 Any 与具体源列表的类型约束,以 CorsLayer 文档为准。

04.4.7.2-073 CompressionLayer 支持哪些编码,如何选择算法与阈值?

一句话结论

CompressionLayer 按客户端 Accept-Encoding 协商 gzip、deflate、br、zstd 等编码(具体支持依 feature 开启),可配置最小压缩大小与媒体类型;小响应与已压缩内容不应重复压缩。

概念解释

压缩在响应出站阶段进行:层读取可接受编码,判断响应类型与大小,选择编码器改写 Content-Encoding。算法取舍:gzip 兼容性广,br 文本压缩率高,zstd 速度与压缩率均衡。feature 需按算法开启,否则对应编码不可用。阈值过小浪费 CPU,过大损失压缩收益。

原理流程

  1. 配置压缩算法、阈值与类型过滤器。
  2. 请求记录客户端可接受编码。
  3. 业务响应到达层,判断是否值得压缩。
  4. 选择编码器压缩 body,改写头部。
  5. 不可压缩类型直接透传。

代码或图示

use tower_http::compression::CompressionLayer;

let layer = CompressionLayer::new();
// 算法与阈值配置方法以当前 tower-http 文档为准
// 依赖需开启对应 compression feature

常见误区

  • 图片/视频/压缩包再次压缩:体积不降且耗 CPU。
  • 未开算法 feature:编译或运行时对应编码不可用。

追问

  • 压缩层与 body 限制层谁先?答:限制应在读取 body 之前;压缩作用于响应体,方向不同,按请求/响应路径分别确认。
  • 待确认点:当前版本支持的编码列表与 feature 名,以 tower-http 文档为准。

04.4.7.2-074 tower-http 的 TimeoutLayer 与 tower 的 Timeout 有什么区别?

一句话结论

tower::timeout::Timeout 是通用服务超时包装;tower-http 的超时层面向 HTTP 语义,通常可把超时映射为 HTTP 响应而不是裸错误,二者底层竞速模型相同。

概念解释

通用 Timeout 产出超时错误类型,需要外层再映射状态码。HTTP 超时层在服务内完成协议语义对接,可直接返回超时响应。选型简单:纯服务栈用 tower Timeout;已经在 HTTP 框架内、希望错误直接转响应时用 tower-http 层。流式接口同样需要避开整体超时。

原理流程

  1. 配置超时时长。
  2. 层启动定时器与业务 Future 竞速。
  3. 业务先完成返回响应。
  4. 超时先到:通用层返回错误,HTTP 层转为超时响应。
  5. 错误沿栈上交由入口处理。

代码或图示

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

let layer = TimeoutLayer::new(Duration::from_secs(5));
// 与 tower::timeout::Timeout 择一使用,避免重复包超时

常见误区

  • 同时叠通用 Timeout 与 HTTP Timeout:双层超时语义重复,排错困难。
  • 超时响应不带 Retry-After 或提示体:客户端无法区分错误类型。

追问

  • 超时后下游调用是否取消?答:取决于业务 Future 是否监听取消;层丢弃 Future 不等于下游请求自动取消。
  • 待确认点:当前 tower-http 超时层返回的状态码与错误类型,以文档为准。

04.4.7.2-075 RequestBodyLimitLayer 与 RequestBodyTimeoutLayer 分别限制什么?

一句话结论

RequestBodyLimitLayer 限制请求体总大小,超限拒绝;RequestBodyTimeoutLayer 限制读取请求体的时长,防止慢速上传拖死连接;两者都作用于入站 body 阶段。

概念解释

body 大小限制防御内存与磁盘耗尽,超过配额返回 413 类错误。body 读取超时针对 slow upload:连接保持但 body 迟迟不发完,占用服务槽位。两层应在业务读取 body 之前生效,且放在会消费 body 的层之前。限制值按业务接口类型分别配置,上传接口单独放宽。

原理流程

  1. 配置大小上限与读取时长上限。
  2. 请求进入层,body 被包裹为受限流。
  3. 读取时累计大小或计时。
  4. 超限/超时即中断并返回错误响应。
  5. 未超限则 body 正常交给内层。

代码或图示

use tower_http::limit::{RequestBodyLimitLayer, RequestBodyTimeoutLayer};
use std::time::Duration;

// 示意;参数类型以当前版本为准
// let limit = RequestBodyLimitLayer::new(1024 * 1024);
// let body_timeout = RequestBodyTimeoutLayer::new(Duration::from_secs(30));

常见误区

  • 限制层加在已经读取 body 的层之后:超限请求早已进入业务。
  • 上传接口套用全局小限制:合法大文件被拒。

追问

  • 超限对应什么状态码?答:通常 413 Payload Too Large;具体映射以层文档为准。
  • 读取超时与整体请求超时怎么配合?答:body 阶段用读取超时,业务处理另设超时,长下载响应不受 body 读取超时影响。

04.4.7.2-076 SetRequestIdLayer 如何生成请求 ID,MakeRequestId 起什么作用?

一句话结论

SetRequestIdLayer 为每个请求生成或提取一个请求 ID 写入请求/响应头部,ID 生成逻辑由实现 MakeRequestId 的类型提供;常用于日志串联与排错追踪。

概念解释

请求 ID 贯穿一次请求的日志、指标与下游调用。层先检查入口是否已有 ID(透传场景),没有则按生成器创建。MakeRequestId 抽象「如何产生 ID」:可以用 UUID、雪花 ID 或随机串。ID 同时放进请求扩展供内层读取,并回写响应头部便于客户端回传。模块位于 tower-http 的 request-id 功能域。

原理流程

  1. 配置请求 ID 头部名与生成器。
  2. 请求进入层,尝试从入口头部提取已有 ID。
  3. 不存在则调用 MakeRequestId 生成新 ID。
  4. ID 写入请求扩展与响应头部。
  5. 内层业务与日志通过扩展读取同一 ID。

代码或图示

use tower_http::request_id::SetRequestIdLayer;

// 示意;生成器类型与头部常量以当前 tower-http 文档为准
// let layer = SetRequestIdLayer::new(HEADER_NAME, MakeUuidRequestId);

常见误区

  • 只在响应头写 ID,内层日志拿不到:需同时写入请求扩展。
  • 把用户可控的外部 ID 直接当内部追踪 ID:应做格式校验与隔离。

追问

  • 生成器必须实现什么 trait?答:MakeRequestId,给定请求生成一个请求 ID 值;具体关联类型以文档为准。
  • 待确认点:当前版本内置生成器名称与默认头部名,以 tower-http request-id 模块为准。

04.4.7.2-077 PropagateRequestIdLayer 与 SetRequestIdLayer 如何配合使用?

一句话结论

SetRequestIdLayer 负责创建或注入请求 ID,PropagateRequestIdLayer 负责把已有的请求 ID 透传到下游请求/响应;两者按顺序配合,先设置再透传。

概念解释

在出向客户端或代理场景,需要把当前请求的 ID 带到下游调用头部。Propagate 层从请求扩展读取已有 ID,写入出站请求头部;如果入口没有 ID,它不负责生成。顺序上 Set 层在内层或先执行保证 ID 存在,Propagate 层在外层负责携带。重复生成 ID 会导致日志断链。

原理流程

  1. Set 层在请求上建立 ID 并放入扩展。
  2. Propagate 层读取扩展中的 ID。
  3. 写入下游请求头部。
  4. 响应阶段把 ID 回写客户端响应。
  5. 链路日志使用同一 ID 串联。

代码或图示

// 示意栈顺序:Set 先保证 ID 存在,Propagate 负责携带
// ServiceBuilder::new()
//     .layer(PropagateRequestIdLayer::new(HEADER_NAME))
//     .layer(SetRequestIdLayer::new(HEADER_NAME, generator))
//     .service(inner)

常见误区

  • 只挂 Propagate 不挂 Set:扩展里没有 ID,透传为空。
  • 两层都生成新 ID:一次请求出现两个追踪 ID,日志无法串联。

追问

  • 请求 ID 存在请求的哪里?答:写入 HTTP 扩展(extensions)而非重复解析头部;内层通过扩展类型读取。
  • 跨服务透传格式有标准吗?答:可沿用 W3C Trace Context 等标准;请求 ID 与 trace ID 是不同概念,具体按观测体系约定。

04.4.7.2-078 CatchPanicLayer 如何捕获 handler panic,防止进程退出?

一句话结论

CatchPanicLayer 把内层服务调用包在 panic 捕获边界内,handler panic 时转为错误响应而不是让任务崩溃;需要配置 panic 到响应的映射方式。

概念解释

异步任务 panic 默认会终止其所在线程,多线程运行时下可能导致 worker 崩溃。捕获层在 call 边界拦截 panic,提取 panic 载荷并映射为 500 类响应。注意它只能捕获穿过该层的服务调用,任务内部自行 spawn 且脱离栈的 panic 不受保护。生产环境仍需配合日志记录 panic 位置。

原理流程

  1. 请求进入捕获层。
  2. 内层调用在捕获边界内执行。
  3. 发生 panic 时层拦截载荷。
  4. 按配置映射为错误响应或错误类型。
  5. 记录 panic 信息后返回,连接不被任务崩溃拖垮。

代码或图示

use tower_http::catch_panic::CatchPanicLayer;

// 示意;错误映射与响应构造以当前 tower-http 文档为准
// let layer = CatchPanicLayer::new();

常见误区

  • 以为加了捕获层整个进程不会有 panic:脱离服务栈的后台任务 panic 仍会冒泡。
  • 捕获后不记录堆栈:线上故障无法定位。

追问

  • panic 载荷如何取得?答:层提供钩子或错误类型携带 panic 值;具体 API 以文档为准,字符串与对象载荷需分别处理。
  • 捕获层应放在栈的什么位置?答:尽量外层,才能覆盖所有内层服务调用;置于内层只能保护部分链路。

04.4.7.2-079 FollowRedirectLayer 用在客户端还是服务端,跟随哪些重定向?

一句话结论

FollowRedirectLayer 是客户端层,在收到 3xx 重定向响应后按策略跟随到新地址;服务端业务响应不需要它。

概念解释

客户端调用上游时可能遇到 301/302/307/308 等重定向,手动跟随需要处理 Location 头部与循环检测。该层封装跟随策略:最大跳转次数、跳转时保留或剥离头部、循环检测。服务端层栈处理的是入站请求,不存在跟随重定向问题。注意敏感头部在跨域跳转时应按规范剥离。

原理流程

  1. 客户端服务栈挂上跟随层。
  2. 首次调用上游,收到 3xx 响应。
  3. 层读取 Location,检查次数与循环。
  4. 构造新请求再次调用。
  5. 达到次数上限或非重定向响应后返回最终结果。

代码或图示

use tower_http::follow_redirect::FollowRedirectLayer;

// 示意;最大次数与头部策略以当前 tower-http 文档为准
// let layer = FollowRedirectLayer::new();

常见误区

  • 在服务端栈加跟随层:作用对象错误,行为不生效或语义混乱。
  • 不限制跳转次数:重定向环导致请求循环。

追问

  • 301 与 307 跟随有何差异?答:301/302 历史上允许改方法为 GET,307/308 保持原方法与 body;跟随策略需按规范处理。
  • 待确认点:当前版本跟随层可配置的策略项,以 follow-redirect 模块文档为准。

04.4.7.2-080 ValidateRequestLayer 如何对请求做前置校验?

一句话结论

ValidateRequestLayer 在请求进入业务前用校验函数检查请求,不满足条件直接返回拒绝响应;适合统一的头部、方法或路径前置规则。

概念解释

有些校验不适合写成提取器或散落在各 handler:例如必须携带某头部、路径格式白名单、方法集合限制。校验层在服务栈外层统一拦截,失败短路不进业务。校验逻辑以闭包或实现 trait 的类型提供,拒绝响应按 HTTP 语义构造。复杂业务校验仍应放在 handler 或专用提取器。

原理流程

  1. 配置校验规则与拒绝响应构造。
  2. 请求进入层先运行校验。
  3. 通过则转发内层服务。
  4. 不通过则直接返回拒绝响应。
  5. 校验结果计入日志与指标。

代码或图示

use tower_http::validate_request::ValidateRequestLayer;

// 示意;校验闭包签名与拒绝响应类型以当前文档为准
// let layer = ValidateRequestLayer::new(validator);

常见误区

  • 把需要读 body 的校验放在该层:body 只能消费一次,后续内层无法再读。
  • 校验层与鉴权层职责重叠:按「前置规则校验」与「身份授权」分层放置。

追问

  • 校验失败返回什么状态码?答:视规则而定,缺失必要头部多用 400 或 401/403;具体映射由层配置与上层错误处理决定。
  • 待确认点:当前版本校验器 trait 名称与返回类型,以 validate-request 模块文档为准。

04.4.7.2-081 body 限制层为什么必须放在读取 body 的层之前?

一句话结论

body 只能被消费一次,限制层需要包裹 body 流在读取前累计大小;若日志、压缩等已读取 body 的层在外层,超限数据已经进入内存,限制失去意义。

概念解释

请求流经层栈是嵌套调用:外层先拿到原始 body。限制层把 body 换成带大小计数的包装流,内层读取时逐帧累计。顺序错误时,外层先收集或转发 body,限制层只看到已经流过的数据。常见错误栈:Trace(读取记录)→ Compression → Limit,此时 Limit 在内层保护不到入口流量。

原理流程

  1. 按请求方向确定层嵌套顺序。
  2. body 限制层放在会消费 body 的所有层之前。
  3. body 被包装为受限流进入内层。
  4. 超限即中断并返回错误。
  5. 未超限数据正常流转。

代码或图示

正确:Limit -> Trace -> Compression -> 业务
错误:Trace -> Compression -> Limit(body 已被外层读完/转发)

常见误区

  • 凭「中间件列表书写顺序」判断,不核对请求经过方向。
  • 压缩层在限制层之前:压缩先处理大 body,内存与 CPU 已被占用。

追问

  • 响应侧有没有类似顺序问题?答:有,响应出站方向相反;响应压缩、响应头改写按返回路径安排,body 限制只作用于入站请求。
  • 如何用测试验证?答:构造超限 body 直接 oneshot 调用服务栈,断言在进入业务前被 413 拒绝。

04.4.7.2-082 压缩层与 Content-Length 头部如何交互?

一句话结论

响应被压缩后实际字节长度改变,压缩层需要更新或移除 Content-Length,改写 Content-Encoding;保留旧长度会导致客户端解析错乱。

概念解释

固定长度响应原本可写 Content-Length。压缩后 body 长度未知或已变化,继续发送旧长度头部是协议错误。压缩层负责按编码结果处理长度头部:流式压缩通常转分块或由帧结束标识收尾。代理转发时同样要注意上游长度与改写后 body 不一致。

原理流程

  1. 业务响应到达压缩层。
  2. 判断是否压缩及可接受编码。
  3. 压缩产出新 body。
  4. 层更新长度头部或改为分块传输。
  5. 写入 Content-Encoding 后出站。

代码或图示

未压缩:Content-Length: 1024
压缩后:Content-Encoding: gzip;长度按压缩结果重算或改分块

常见误区

  • 手动在业务层写死 Content-Length,再经过压缩层:长度与实际 body 不符。
  • 对已经编码的响应重复压缩:头部与体积都不正确。

追问

  • HTTP/2 下长度头部如何处理?答:HTTP/2 用帧与 END_STREAM 标识结束,不使用 chunked;长度仍需与数据一致。
  • 待确认点:当前压缩层对长度头部的具体改写行为,以 tower-http compression 文档为准。

04.4.7.2-083 捕获 panic 层与追踪层谁放在外层?

一句话结论

通常 TraceLayer 在最外层,CatchPanicLayer 在内层或反之需按观测目标确认;关键原则是 panic 发生时追踪 span 仍要记录到错误状态,不能让捕获层在日志之外吞掉事件。

概念解释

顺序决定 panic 被谁先看到:Trace 在外层时,panic 沿栈冒泡经过 Trace,span 可记录错误;CatchPanic 在外层时 panic 被转成响应,Trace 看到的是正常 500 响应。两种组合都可行,取决于要记录「原始 panic」还是「对外响应」。生产推荐 Trace 最外层保证链路日志完整,捕获层保护连接不崩溃。

原理流程

  1. 确定观测目标:记录 panic 载荷还是记录最终响应。
  2. Trace 置于外层包裹整条链路。
  3. CatchPanic 置于其下拦截服务调用。
  4. panic 被捕获转响应,Trace 记录状态码与耗时。
  5. panic 日志由捕获层钩子单独输出。

代码或图示

推荐栈:TraceLayer -> CatchPanicLayer -> 业务服务

常见误区

  • 捕获层在最外层且不挂 Trace:panic 与响应都没有链路日志。
  • 以为捕获层会自动导出 panic 到追踪系统:需要钩子接入 tracing/OpenTelemetry。

追问

  • 两层顺序反了会丢什么信息?答:CatchPanic 在外时 Trace 看不到原始 panic,只看到转换后的响应,错误类型可能被弱化。
  • 待确认点:当前版本两层钩子能否共享 panic 上下文,以各自文档为准。

04.4.7.2-084 SetResponseHeaderLayer 如何统一注入响应头?

一句话结论

SetResponseHeaderLayer 为出站响应统一追加或覆盖指定头部,适合公共安全头、自定义标识与版本信息;与请求侧的请求 ID 层方向相反。

概念解释

公共响应头不需要每个 handler 重复设置:层在响应返回阶段统一写入。Set 语义覆盖同名头部,需要追加多值时选择追加型层。头部值静态固定时在层构造时确定;动态值可在钩子或状态中计算。注意不要在该层写依赖业务 body 计算的长度头部。

原理流程

  1. 配置头部名与值(或提供值来源)。
  2. 请求穿过内层服务得到响应。
  3. 层在响应头部写入指定项。
  4. 响应返回入口。
  5. 客户端收到统一头部。

代码或图示

use tower_http::set_header::SetResponseHeaderLayer;

// 示意;头部值类型与构造方式以当前 tower-http 文档为准
// let layer = SetResponseHeaderLayer::overriding(HEADER_NAME, HeaderValue::from_static("v"));

常见误区

  • 用响应头层写 Content-Length:body 长度由 body 实现与协议层决定,手动覆盖易出错。
  • 覆盖掉框架已设置的必要头部:先确认同名头部语义。

追问

  • 覆盖与追加有什么区别?答:overriding 替换同名值,appending 追加多值;选择依头部规范而定。
  • 待确认点:当前版本覆盖/追加构造器名称,以 set-header 模块文档为准。

04.4.7.2-085 鉴权层应该放在服务栈的什么位置?

一句话结论

鉴权应在业务层之前、日志与限流之后的合理位置:先记录与限流,再校验身份,通过后才进入业务;需要读取 body 的鉴权要注意 body 只能消费一次。

概念解释

层栈顺序影响安全与观测:Trace 最外层记录所有尝试(含失败鉴权),限流层挡住突发,鉴权层在其后拒绝未认证请求,业务在最内层。鉴权通常只看 metadata/头部,不消费 body;需要校验 body 签名时要在 body 被其它层读取之前处理。鉴权失败返回 401/403,不暴露内部细节。

原理流程

  1. Trace 记录入口请求。
  2. 限流/并发限制拦截超额流量。
  3. 鉴权层校验凭证与权限。
  4. 通过则转发业务;拒绝则返回 401/403。
  5. 鉴权结果计入指标。

代码或图示

Trace -> RateLimit -> AuthLayer -> 业务服务

常见误区

  • 鉴权放在业务内层:未认证请求已执行业务逻辑。
  • 鉴权层读取并丢弃 body:内层提取器拿不到 body。

追问

  • 认证与授权分几层?答:认证(你是谁)校验凭证,授权(你能做什么)校验权限,可分为两层或在一层内分步判断。
  • 凭证为什么不能进日志?答:令牌、密码属于敏感信息,日志记录会扩大泄露面;只记录主体标识与过期状态。

04.4.7.2-086 tower-http 的 feature 开关怎么按需开启?

一句话结论

tower-http 按模块与算法拆分 feature,使用哪个层就在依赖行开启对应 feature;未开启时相关模块编译不可见,压缩算法还需单独开编码 feature。

概念解释

Crate 为控制编译体积把 trace、cors、compression、limit、timeout、request-id、follow-redirect、validate-request、catch-panic、fs、set-header 等拆成独立 feature,压缩算法(gzip、deflate、br、zstd)再细分。依赖声明列出实际用到的集合;升级版本后核对 feature 名是否变更。编译报「找不到模块」时优先检查 feature 是否开启。

原理流程

  1. 列出服务栈用到的层。
  2. 在 Cargo.toml 开启对应模块 feature。
  3. 压缩场景追加算法 feature。
  4. 编译验证缺失项。
  5. 移除未用 feature 裁剪产物。

代码或图示

tower-http = { version = "0.6", features = [
    "trace", "cors", "compression", "timeout", "limit",
    "request-id", "catch-panic", "fs", "set-header",
] }

常见误区

  • 只写主 crate 版本不写 features:用到的模块未编译进来。
  • 压缩层可用但某算法不可用:算法 feature 与模块 feature 是两层开关。

追问

  • 怎么查看完整 feature 列表?答:docs.rs 依赖页 Feature flags 章节或 cargo metadata;不凭记忆写不存在的 feature。
  • 待确认点:当前版本各 feature 精确名称,以 crates.io/docs.rs 为准。

04.4.7.2-087 ServeDir/ServeFile 如何提供静态文件服务?

一句话结论

tower-http 的 fs 模块提供 ServeDir(目录映射)与 ServeFile(单文件)服务,按请求路径定位文件并流式返回,内含路径穿越防护;需开启 fs feature。

概念解释

静态文件服务不需要手写文件读取与 MIME 判断:层/服务把 URL 路径映射到磁盘目录,校验规范化路径不逃逸出根目录,按文件类型返回 Content-Type,body 流式发送。目录列表、缓存头部等行为有配置项。直接用标准库 fs::read 自己拼路由容易产生路径穿越与阻塞问题。

原理流程

  1. 配置根目录或目标文件。
  2. 请求路径进入文件服务。
  3. 规范化并校验路径不逃逸根目录。
  4. 打开文件,按类型构造响应。
  5. body 流式返回,结束后关闭句柄。

代码或图示

use tower_http::services::ServeDir;

// 示意;根目录路径与配置以当前文档为准
// let svc = ServeDir::new("assets");

常见误区

  • 自行拼接路径不做规范化:.. 穿越读取根目录外文件。
  • 用同步文件读取阻塞 worker:文件服务应使用异步 IO 或服务内置实现。

追问

  • MIME 类型如何确定?答:服务按扩展名映射类型;具体映射表与覆盖方式以 fs 模块文档为准。
  • 待确认点:当前版本目录浏览、缓存头配置项名称,以 ServeDir 文档为准。

04.4.7.2-088 日志/追踪层如何与 tracing 订阅器集成?

一句话结论

TraceLayer 只负责产生 span 与事件,输出到终端、文件或 OpenTelemetry 由 tracing subscriber/registry 配置;没有 subscriber 时层行为看起来不生效。

概念解释

tracing 分两部分:埋点(span/event)与订阅器(收集输出)。层在请求生命周期创建 span、记录字段,订阅器决定格式化、过滤与导出。生产环境常接 OpenTelemetry 导出器,把跨服务链路串联。配置包括级别过滤、目标过滤、敏感字段脱敏。层产生的请求 ID 应作为 span 字段贯穿。

原理流程

  1. 注册 subscriber,配置格式化与导出。
  2. TraceLayer 在请求上创建 span。
  3. 事件与字段写入当前 span。
  4. subscriber 过滤、格式化并输出/导出。
  5. 请求结束关闭 span,记录耗时与状态。

代码或图示

// 示意:tracing-subscriber 初始化与层配合
// tracing_subscriber::fmt()
//     .with_env_filter("info")
//     .init();

常见误区

  • 加了 TraceLayer 但没初始化 subscriber:日志不输出。
  • 直接在事件里打印完整请求 body 或凭证:内存与敏感信息双重风险。

追问

  • 如何让下游调用继承同一 span?答:在调用下游前注入 trace 上下文,响应后提取;跨进程传播格式由 OTel 配置决定。
  • 待确认点:当前版本 TraceLayer 暴露的钩子与字段名,以文档为准。

04.4.7.2-089 错误类型在层栈上如何逐层变换,排错时怎么回溯?

一句话结论

每层可把内层错误映射成自己的错误类型,栈越深错误类型嵌套越多;回溯时沿 source 链找到根因,或在入口统一装箱后 downcast 分类。

概念解释

请求失败可能源自业务、超时、限流、协议层。外层层把内层错误包装:map_err 转换、Retry 包裹策略错误、Timeout 包 Elapsed。错误链保留 source 关系。排错时先看入口错误类型,再逐层取 source,定位是下游故障还是本地策略拒绝。日志应记录完整错误链而非最外层消息。

原理流程

  1. 内层服务产生原始错误。
  2. 外层 map_err 转换/装箱。
  3. 策略层附加超时/重试语义。
  4. 入口收到最终错误类型。
  5. 沿 source 链回溯根因并分类响应。

代码或图示

业务错误 -> map_err(BoxError) -> Timeout(Elapsed) -> 入口
回溯:BoxError.source() -> 原始错误类型与消息

常见误区

  • 转换错误时丢弃 source:根因丢失,只剩「内部错误」。
  • 所有错误映射成同一字符串:无法按类型做不同响应与重试判断。

追问

  • downcast 什么时候用?答:入口需要按具体错误分支处理时,把 BoxError downcast 回自定义枚举;失败则按通用错误处理。
  • 错误链如何打印?答:遍历 source() 或使用 anyhow/thiserror 的 Display 链输出,日志保留每一层上下文。

04.4.7.2-090 全局层与路由级层的作用范围有什么区别?

一句话结论

全局层包裹整棵路由树,所有请求都经过;路由级层只作用于指定子路由或方法分组,嵌套在全局层之内。

概念解释

在 axum 等框架中,Router::layer 加在根路由上即为全局层;对子路由 nest/route_layer 加的层只覆盖该子树。执行方向:全局外层先经过,再进入路由内层。公共横切(日志、请求 ID、全局超时)放全局;业务分组特有(某模块鉴权、特定压缩策略)放路由级。混用会导致保护范围错配。

原理流程

  1. 拆分横切职责:全局公共 vs 分组特有。
  2. 全局层注册在根 Router。
  3. 路由级层注册在子路由。
  4. 请求先过全局栈,再进子路由内层栈。
  5. 响应按相反方向返回。

代码或图示

Router::new()
  .route("/public", ..)
  .nest("/admin", admin_router.layer(AuthLayer))
  .layer(TraceLayer)   // 全局

常见误区

  • 把 admin 鉴权挂全局:公共接口也被校验,或反过来漏保护。
  • 以为路由级层在全局层之外:实际嵌套在内层。

追问

  • 同一层能否在两处重复挂载?答:可以,但会形成双层包装,计数与超时语义叠加;应确认是否有意为之。
  • 待确认点:当前框架全局与路由级层方法名(layer/route_layer),以 axum 文档为准。

04.4.7.2-091 层嵌套会带来多少性能开销,如何评估?

一句话结论

每层包装增加一次方法调用与类型分发,静态类型层开销很小;动态分发、内部通道与缓冲才是主要成本。评估应基于压测数据而非直觉。

概念解释

Tower 层是零成本抽象为主:静态编译后包装调用内联,额外开销通常是一次委托。真正的成本来自 Buffer 通道、Retry 排队、压缩 CPU 与动态 boxed 分发。高 QPS 场景下测量每层的延迟贡献与 CPU 占用,而不是盲目减少层数。观测维度包括 P50/P99、CPU、内存与队列长度。

原理流程

  1. 压测基线:裸业务服务。
  2. 逐层加入中间件并复测。
  3. 记录延迟分布与 CPU 变化。
  4. 定位高开销层(压缩、缓冲、动态分发)。
  5. 优化或替换实现后复测。

代码或图示

基线 -> +Trace -> +Timeout -> +Limit -> +Compression
每步记录 P99 与 CPU,识别拐点

常见误区

  • 以为层数直接决定性能:多数静态层委托成本极低。
  • 不做基线就优化:无法判断瓶颈真正来源。

追问

  • boxed 服务热路径值得去掉吗?答:先测量动态分发占比;类型简单时保留静态类型,复杂服务栈再考虑擦除。
  • 压缩 CPU 高怎么缓解?答:调大阈值、缩小压缩类型范围、对静态资源预先压缩或用专用缓存。

04.4.7.2-092 组装一个生产环境 HTTP 服务的中间件栈,推荐顺序是什么?

一句话结论

典型顺序:Trace/请求 ID(最外层观测)→ CORS → 限流/并发限制 → 鉴权 → body 限制/读取超时 → 业务;压缩置于响应侧合适位置,超时覆盖整体处理。

概念解释

顺序原则:外层先观测与兜底,内层做业务;body 限制先于任何 body 读取;鉴权在业务之前;超时在治理层包住业务。生产栈还需按接口类型区分:上传接口放宽 body 限制,流式接口不用整体超时。各层配置(阈值、并发数、退避)来自压测与下游容量评估。

原理流程

  1. 最外层 TraceLayer 记录全链路。
  2. CorsLayer 处理跨域预检。
  3. RateLimit/ConcurrencyLimit 兜底流量。
  4. 鉴权层校验身份权限。
  5. Limit/Timeout 保护资源,最后进入业务 handler。

代码或图示

// 示意生产栈(类型与配置以实际文档为准)
// ServiceBuilder::new()
//     .layer(TraceLayer::new_for_http())
//     .layer(CorsLayer::new())
//     .layer(ConcurrencyLimitLayer::new(100))
//     .layer(TimeoutLayer::new(Duration::from_secs(5)))
//     .layer(RequestBodyLimitLayer::new(1 << 20))
//     .service(handler)

常见误区

  • 把 body 限制放在压缩/日志之后:保护不到大 body。
  • 全局套用同一超时:长连接与上传接口被误杀。

追问

  • 压缩层插在哪?答:作用于响应出站,通常靠近业务外层;不影响请求 body 限制顺序。
  • 缺哪些生产要素时不能上线?答:观测日志、限流兜底、body 限制、错误映射、优雅停机与健康检查。

04.4.7.2-093 线上出现 400、413、431 类错误,如何按层栈定位是哪一层拒绝的?

一句话结论

先看响应状态码与响应体区分错误类别,再沿层栈顺序核对:413 多为 body 大小限制,431 多为头部过大,400 可能是校验/协议解析;结合日志里的请求 ID 定位触发层。

概念解释

不同层拒绝时状态码与消息不同:RequestBodyLimit 超限 413,头部超限 431,ValidateRequest 校验失败 400/401/403,协议解析错误由 Hyper 层产生。排查步骤:取请求 ID 查 Trace 日志,确认请求穿过了哪些层;对比请求大小、头部数量与配置阈值;复现请求 oneshot 到对应层验证。不要在没定位前全局调大限制。

原理流程

  1. 记录状态码、响应体、请求大小与头部。
  2. 按码值候选对应层。
  3. Trace 日志确认请求停在哪一层。
  4. 核对层配置阈值与请求实际值。
  5. 复现验证后再调整配置。

代码或图示

413 -> RequestBodyLimitLayer(body 超限)
431 -> 头部总数/大小超限(协议解析或限制层)
400 -> 校验层、提取器解析或协议非法报文
401/403 -> 鉴权层

常见误区

  • 看到 400 就改业务代码:可能是前置层或协议解析拒绝。
  • 直接调大所有限制:内存攻击面扩大,根因未解决。

追问

  • 如何区分服务端层拒绝与上游返回?答:本服务 Trace 记录到该层即本地拒绝;未进入本地栈则问题在代理或上游。
  • 待确认点:当前各层拒绝响应的精确状态码,以对应层文档为准。

04.4.7.2-094 如何自定义请求 ID 生成器,需要实现什么?

一句话结论

实现生成器 trait(MakeRequestId 语义),按请求产出请求 ID 值;可用 UUID、随机串或基于上游透传值加工,类型需满足层要求的 Clone/Send 约束。

概念解释

内置生成器不能满足格式要求时自定义:例如内部工号前缀、雪花 ID、或从已有 trace 上下文派生。生成器每次调用返回新 ID,避免重复;需要稳定可排序时选用带时间分量的算法。生成器实例随层克隆到各连接,内部不可变即可;随机源按需在内部持有。

原理流程

  1. 定义生成器结构体。
  2. 实现 MakeRequestId 对应方法。
  3. 生成符合格式的 ID 值。
  4. 装入 SetRequestIdLayer。
  5. 业务与日志通过扩展读取同一 ID。

代码或图示

// 示意;trait 方法签名以当前 tower-http 文档为准
// struct MyId;
// impl MakeRequestId for MyId {
//     fn make_request_id<B>(&mut self, req: &Request<B>) -> Option<RequestId> { .. }
// }

常见误区

  • 生成器返回固定值:所有请求同 ID,日志无法区分。
  • 生成器内部持有不可克隆可变状态:服务克隆时编译失败。

追问

  • 透传已有 ID 与重新生成怎么选?答:入口带来可信 ID 则透传,否则生成;跨系统 ID 格式需在观测体系内约定。
  • 待确认点:当前版本 trait 名称、方法签名与 RequestId 类型,以 request-id 模块文档为准。

04.4.7.2-095 层栈如何兼容 WebSocket 升级连接?

一句话结论

支持升级的层要允许连接 upgrade 通道透传,Hyper 侧需开启 with_upgrades();会消费或替换 body 的层不能破坏升级握手,升级后的 IO 流交由 WebSocket 协议处理。

概念解释

WebSocket 先 HTTP 握手再移交 IO 流。普通请求层在握手阶段工作正常,但若层把 body 缓冲、替换或阻塞,升级可能失败。Trace、CORS 等只读头部的层通常安全;body 处理层需确认不影响升级请求。握手完成后连接脱离 HTTP 服务栈,后续帧由 WebSocket 库管理。

原理流程

  1. 服务连接开启 upgrades 支持。
  2. 层栈处理握手请求,不破坏升级头部。
  3. 响应 101,IO 流移交升级通道。
  4. WebSocket 库在流上读写帧。
  5. 层栈不再介入升级后的通信。

代码或图示

// Hyper 连接开启升级:
// hyper::server::conn::http1::Builder::new()
//     .serve_connection(io, svc)
//     .with_upgrades();

常见误区

  • 忘记 with_upgrades():升级请求拿不到移交流。
  • 中间件提前消费握手请求 body:升级上下文丢失。

追问

  • 哪些层对升级最敏感?答:读取/替换 body 的层、缓冲层;只读头部与响应装饰的层一般安全。
  • 待确认点:当前 tower-http 各层对 upgrade 请求的兼容性说明,以对应文档为准。

04.4.7.2-096 Hyper、tower、tower-http 版本之间如何对齐?

一句话结论

三者围绕同一套 http/http-body 生态版本演进,选型时以 docs.rs 当前版本与各 crate 依赖声明为准;升级一方时检查传递依赖是否兼容,不强行跨大版本混拼。

概念解释

Hyper 1.x 对应 http-body 0.4/0.5 生态与 tower 0.5 系列;tower-http 版本与其依赖的 tower、hyper 版本绑定。混合大版本可能出现 body 类型不兼容、trait 不匹配。工程上用 cargo tree 检查实际解析版本,升级后跑构建与集成测试。版本号不写死在文档里,以当前发布为准。

原理流程

  1. 确定 Hyper 大版本(1.x)。
  2. 选匹配的 tower 与 tower-http 版本。
  3. 检查 http、http-body、bytes 等公共依赖。
  4. cargo tree 核对无冲突版本。
  5. 构建与测试通过后锁定 Cargo.lock。

代码或图示

# 版本以 docs.rs 当前发布为准,示意主版本匹配关系
hyper = "1"
tower = "0.5"
tower-http = "0.6"
http-body-util = "0.1"

常见误区

  • 凭旧记忆固定次版本号:生态升级后旧版本不再维护。
  • 忽略传递依赖冲突:编译报 body/trait 不兼容时先查版本对齐。

追问

  • 怎么查看 crate 兼容依赖范围?答:docs.rs 依赖表或 cargo tree -i <crate>;按 SemVer 兼容区间选择。
  • 待确认点:当前各 crate 最新版本号与互锁关系,以 crates.io 为准。

04.4.7.2-097 如何为 Tower 服务栈写集成测试,覆盖跨层行为?

一句话结论

集成测试在内存中组装完整层栈,用 oneshot 或本地监听端口发真实请求,断言跨层后的响应、头部与 body;策略层用可控内层服务验证触发条件。

概念解释

单测聚焦单个层,集成测试验证层间协作:顺序是否正确、错误是否被正确映射、body 限制是否生效。测试环境复用生产组装函数,避免测试栈与生产栈分叉。需要慢服务、失败注入时用通道或计数句柄控制。流式响应逐帧消费断言。

原理流程

  1. 抽出服务栈构造函数供测试与生产共用。
  2. 测试组装栈与可控内层。
  3. 构造请求提交(oneshot 或本地端口)。
  4. 断言最终状态、头部、body 与调用次数。
  5. 覆盖正常、超限、超时、拒绝等分支。

代码或图示

#[tokio::test]
async fn rejects_oversized_body() {
    let svc = build_stack(inner_svc());
    let req = Request::new(Full::new(Bytes::from(vec![0u8; 2 << 20])));
    let resp = svc.oneshot(req).await.expect("response");
    assert_eq!(resp.status(), StatusCode::PAYLOAD_TOO_LARGE);
}

常见误区

  • 测试只调业务 handler:层顺序与错误映射问题漏掉。
  • 测试栈复制一份配置:与生产栈漂移,失效保护。

追问

  • 什么时候用真实端口测试?答:验证 Hyper 连接循环、keep-alive、升级等协议行为时;纯层行为用 oneshot 更快。
  • 测试里如何注入失败?答:内层服务按通道状态返回错误或挂起,配合计数句柄观察调用次数。

04.4.7.2-098 网关/代理场景为什么常直接基于 Hyper + Tower 而不是业务框架?

一句话结论

网关需要协议转发、连接定制与多协议适配,业务框架的路由提取器收益有限;Hyper 提供低层连接控制,Tower 提供治理层组装,更贴合代理职责。

概念解释

代理核心是请求转发、头部改写、路由到上游、限流熔断与协议升级。axum 等框架的参数提取、序列化能力在网关场景用不上,反而约束服务形态。直接使用 Hyper/Tower 可以控制连接生命周期、自定义 IO 适配与上游客户端栈。业务后端服务再用上层框架,两层各司其职。

原理流程

  1. 入口 Hyper 接收连接。
  2. Tower 栈做观测、限流、鉴权。
  3. 代理服务构造上游请求并转发。
  4. 上游响应流式回传客户端。
  5. 连接与升级行为按需定制。

代码或图示

客户端 -> Hyper 连接 -> Tower 治理层 -> 代理转发服务 -> 上游客户端栈 -> 上游

常见误区

  • 用业务框架硬写代理:提取器/序列化层增加无必要约束。
  • 代理层做业务编排:职责混在一起,演进困难。

追问

  • 网关常见自研层有哪些?答:路由转发、上游选择、熔断、头部清洗、协议转换;可基于自定义 Layer/Service 实现。
  • 选型怎么判断?答:看是否需要低层连接控制与协议定制;以静态业务接口为主则上层框架更合适。

04.4.7.2-099 本章常见编译与运行错误如何快速排查?

一句话结论

按错误类型分流:body 类型不匹配查 http_body::Body 实现,trait bound 不满足查 Send/Clone/Ready,连接挂起查连接 Future 是否 spawn,配置缺失查 feature 与版本对齐。

概念解释

高频问题分类:类型层(body、错误、Future 关联类型)、约束层(Send/Sync/Clone/poll_ready)、运行层(未驱动连接 Future、流未消费、阻塞 worker)、配置层(feature 未开、版本不兼容)。排查顺序:先读编译错误定位 trait 与类型,再检查服务栈组装,最后运行期加日志/指标验证。不确定的 API 以 docs.rs 当前文档为准,不臆造方法名。

原理流程

  1. 编译错误:定位不满足的 trait 与具体类型。
  2. 检查 body/错误/Future 关联类型是否统一。
  3. 检查服务是否 Clone、Send,状态是否共享安全。
  4. 运行挂起:确认连接 Future 被 spawn、body 流被消费。
  5. 配置报错:核对 feature 与依赖版本。

代码或图示

body 类型错误   -> http-body-util 适配器 / 统一响应 body
不满足 Send     -> 替换 Rc/非同步状态为 Arc 与同步原语
请求挂起        -> 连接任务未 spawn / 流未 poll
方法找不到      -> feature 未开 / 版本 API 变更

常见误区

  • 看到编译错误就改签名绕过:掩盖了类型设计问题。
  • 运行期问题不打点:无法区分等待、阻塞还是死锁。

追问

  • 如何确认某个 API 在当前版本存在?答:查 docs.rs 对应模块方法列表;文档没有的写「待确认」并记录验证点,不写进生产代码。
  • 阻塞 worker 有什么现象?答:整体延迟升高、其它请求排队,tokio 阻塞警告出现;重任务移到 spawn_blocking。

04.4.7.2-100 Hyper、Tower、tower-http 三者职责边界如何一句话总结?

一句话结论

Hyper 负责 HTTP 协议与连接,Tower 定义服务与层抽象并提供通用治理层,tower-http 在抽象之上实现 HTTP 专用中间件;业务框架再在这三层之上提供路由与提取器。

概念解释

理解边界有助于分层排错:报文解析、帧、连接复用问题在 Hyper;服务组合、背压、通用限流重试在 Tower;跨域、压缩、请求 ID、静态文件等 HTTP 语义层在 tower-http;路由匹配、参数提取、序列化属于上层框架。调用请求时从协议层到业务层逐层穿过,响应沿栈返回。各层可独立替换,只要满足 Service 抽象。

原理流程

  1. 字节流进入 Hyper,解析为 Request。
  2. 请求穿过 tower-http 与 tower 层栈。
  3. 业务服务处理并产出 Response。
  4. 响应沿层栈返回,附加头部与编码。
  5. Hyper 编码回写连接。

代码或图示

Hyper(协议/连接)
  -> tower-http(HTTP 专用层)
    -> tower(Service/Layer、通用治理)
      -> 业务服务(上层框架 handler)

常见误区

  • 把协议问题归到框架:先确认问题发生在哪一层。
  • 跨层复用能力错位:通用治理放 tower,HTTP 语义放 tower-http。

追问

  • 新增一个横切能力先落在哪层?答:与 HTTP 无关的通用策略实现 Tower 层;需要读头部/body/响应头的实现 tower-http 层。
  • 待确认点:当前版本各 crate 最新模块划分,以 docs.rs 目录为准;本章所有版本敏感行为均以当前文档复核后使用。