wreq 自定义运行时实战:3 大接口打通 Executor、Timer 与 Transport 的完整指南

原创2026-10-14 19:12:081,624 阅读

wreq 自定义运行时实战:3 大接口打通 Executor、Timer 与 Transport 的完整指南

wreq 是一个注重易用性与隐私的 Rust 异步 HTTP 客户端,支持 HTTP/1、HTTP/2 与 HTTP/3。它的核心设计是"运行时无关":库本身不绑定任何具体异步运行时,而是通过 Executor、Timer、Transport 三大可插拔接口,让你自由选择 tokio、compio 或其他运行时来驱动它。本文带你从零理解这套接口,并学会快速接入自己的运行时。

为什么要做可插拔运行时?

传统 HTTP 客户端通常和特定运行时深度耦合,而 wreq 选择"协议与运行时解耦":

  • Executor(执行器):负责 spawn 后台任务,比如 HTTP/2 的连接驱动、HTTP/3 的请求体管道;
  • Timer(定时器):负责 sleep / sleep_until 等时间操作,驱动 keep-alive ping、超时等机制;
  • Transport(传输层):负责底层字节读写,HTTP/1 与 HTTP/2 基于 tokio::io::AsyncRead + AsyncWrite 抽象,HTTP/3 则基于 QUIC 传输契约。

这样设计的好处是:你既可以跑在 tokio 上,也可以跑在 compio、Smol 甚至自研运行时上,wreq 的测试套件就同时包含了 Tokio 适配器 和 Compio 适配器 两套实现,是极好的参考样板。

运行时组件的总入口在 src/rt.rs,模块注释写得很清楚:

"This module provides traits and types that allow netty to be runtime-agnostic. By abstracting over async runtimes, netty can work with different executors, timers, and IO transports."

接口一:Executor —— 一个方法就够了

Executor 是三个接口中最简单的,定义见 src/rt.rs:

pub trait Executor<Fut> {
    /// Place the future into the executor to be run.
    fn execute(&self, fut: Fut);
}

要点:

  • 它是泛型 trait:Executor<Fut> 按未来(Future)类型参数化。实践中只需为所有 Future 做一次泛型实现(impl<F: Future + Send + 'static> Executor<F>),即可满足 HTTP/2 与 HTTP/3 各自需要的任务类型;
  • 实现里只需一行"spawn 语义",例如 tokio 版就是调用 tokio::spawn(fut),compio 版则是 compio::runtime::spawn(fut).detach();
  • HTTP/2 内部通过 Http2ClientConnExec 这个"边界 trait"自动适配——只要你实现了通用的 Executor 且类型可 Clone,就自动获得该实现,无需额外编码。

接口二:Timer —— 支持重置的睡眠抽象

Timer 定义在 src/rt/timer.rs,提供 4 个方法:

方法 作用 是否有默认实现
sleep(duration) 返回 duration 后就绪的 Sleep 未来 必须实现
sleep_until(deadline) 返回到达 deadline 时就绪的 Sleep 未来 必须实现
now() 获取当前时间 默认 Instant::now()
reset(sleep, new_deadline) 修改已有睡眠未来的截止点 有默认实现,建议覆盖

两个容易踩坑的细节:

  1. 返回的是 Pin<Box<dyn Sleep>>:Sleep 是一个 Future<Output = ()> + Send + Sync 的 trait(见 Sleep 定义),它额外要求实现 reset,让库能原地修改超时而不重建未来;
  2. 忘记传 timer 会直接 panic:如果未向 Builder 提供 timer,Time::Empty 在真正 sleep 时会 panic 出 "You must supply a timer."(见 Time 枚举)。所以启用 keep-alive ping 等定时功能时,记得调用 Builder::timer()。

接口三:Transport —— IO 抽象与 QUIC 契约

Transport 层按协议分为两种形态:

HTTP/1 与 HTTP/2:AsyncRead + AsyncWrite

握手方法 handshake(io) 只要求 IO 对象满足 tokio::io::AsyncRead + AsyncWrite + Unpin。如果你的底层流来自其他运行时,写一个薄包装即可。官方测试里的 CompioIO 就是典型例子:把 compio 的 AsyncStream 包一层,实现 poll_read / poll_write / poll_flush / poll_shutdown 四个方法,即可无缝接入。

HTTP/3:QUIC 传输契约

启用 http3 feature 后,wreq 不再创建 UDP socket 或做 TLS,而是要求调用方完成 QUIC/TLS 握手后,把连接交给 rt::quic 模块 定义的契约:

  • Connection:接收单向/双向流、提供 stream 句柄(定义);
  • OpenStreams:按需打开出站流,等待对端流额度;
  • SendStream / RecvStream / BidiStream:无帧语义的字节读写,带显式的 FIN(poll_finish)、STOP_SENDING 观测(poll_stopped)与 reset。

如果你已有实现 http3::quic trait 的传输(如 http3-quic),无需重写——Compat 适配器 一行 Compat::new(inner) 即可完成转换,这也是 HTTP/3 客户端模块 文档中推荐的接入方式。

完整示例:用 tokio 驱动 HTTP/2 客户端

下面把三个接口串起来(精简自 tests/support/rt.rs 与 tests/support/mod.rs):

use std::future::Future;
use std::time::{Duration, Instant};
use std::pin::Pin;

use wreq::rt::{Executor, Sleep, Timer};

// 1. Executor:一行 spawn
#[derive(Clone)]
struct TokioExecutor;

impl<F> Executor<F> for TokioExecutor
where
    F: Future + Send + 'static,
{
    fn execute(&self, fut: F) {
        tokio::spawn(fut);
    }
}

// 2. Timer:包装 tokio::time::sleep
#[derive(Clone)]
struct TokioTimer;

impl Timer for TokioTimer {
    fn sleep(&self, d: Duration) -> Pin<Box<dyn Sleep>> {
        Box::pin(TokioSleep { inner: tokio::time::sleep(d) })
    }
    fn sleep_until(&self, deadline: Instant) -> Pin<Box<dyn Sleep>> {
        Box::pin(TokioSleep { inner: tokio::time::sleep_until(deadline.into()) })
    }
    fn reset(&self, sleep: &mut Pin<Box<dyn Sleep>>, new_deadline: Instant) {
        sleep.as_mut().reset(new_deadline);
    }
}

// 3. Transport:tokio 的 TcpStream 本身满足 AsyncRead + AsyncWrite
// 4. 组装:Builder 同时接收 executor 与 timer
let (mut sender, conn) = wreq::conn::http2::Builder::new(TokioExecutor)
    .timer(TokioTimer)
    .handshake(stream)
    .await?;

tokio::spawn(conn); // 连接驱动交给执行器运行
let res = sender.try_send_request(req).await?;

对应关系一目了然:Builder::new(exec) 注入执行器,Builder::timer() 注入定时器(内部包成 Arc<dyn Timer + Send + Sync>),handshake(io) 接收传输层对象。

三个接口与协议的对应关系

协议 Executor Timer Transport 要求
HTTP/1 不需要 不需要 AsyncRead + AsyncWrite 即可
HTTP/2 需要(驱动连接与升级流) keep-alive ping 需要 AsyncRead + AsyncWrite
HTTP/3 需要(连接任务、body 管道、CONNECT 隧道) 可选 实现 rt::quic::Connection 或用 Compat 适配

自定义运行时时的 3 条经验

  1. Executor 保持可 Clone、尽量轻量:HTTP/2/HTTP/3 会在每个连接、每个后台任务间传递它的克隆,官方实现都是零成本单位结构体(见 TokioExecutor 定义);
  2. Sleep 必须是 Send + Sync:compio 的 future 天生 !Send,其测试适配器用 SendWrapper 做了线程检查包装(见 CompioSleep),如果你的运行时也是线程绑定的,需要同样处理;
  3. poll 返回 Pending 必须安排唤醒:QUIC 契约明确要求每次 Pending 后保存后端挂起操作,保证"进度或错误可观测时"当前任务被唤醒(见 rt::quic 模块注释),这是自定义 Transport 最容易出错的地方。

总结

wreq 把"运行时怎么跑、时间怎么算、字节怎么走"这三件事完全交给了你:

  • 一个方法的 Executor 负责任务调度;
  • 四个方法的 Timer 负责时间推进;
  • 按协议形态选择的 Transport 负责网络字节。

三个接口边界清晰、文档注释详尽(#![deny(missing_docs)] 强制全量文档),配合 Cargo.toml 中可选的 http3、http3-datagram feature,你可以用约百行代码把自己熟悉的运行时完整接入这套 Rust HTTP 客户端,真正做到"协议归库、运行时归你"。

登录后查看全文
wreq