Web 框架指南 — Zenith（齐天）教程

App 与路由

App 是 Web 应用入口。路由在编译期构建为 Trie，运行期零开销分发。支持路径参数 :name 与通配段。

routing.rs · feature = web
use zenith::App;
use zenith::api::{CanonicalRequest, CanonicalResponse};

fn main() {
    let mut app = App::new();

    // 静态路径
    app.get("/", |_, _| Ok(CanonicalResponse::new(200)));
    app.post("/api/items", |req, _| { /* ... */ Ok(CanonicalResponse::new(201)) });

    // 路径参数
    app.get("/users/:id/orders/:oid", |_, params| {
        let id  = params.get("id");
        let oid = params.get("oid");
        Ok(CanonicalResponse::json(format!("user={{}} order={{}}", id, oid)))
    });

    app.run("0.0.0.0:8080").unwrap();
}

类型化 Extract

Extractor 允许从 CanonicalRequest 中提取类型化数据，减少手写解析样板代码。

extract.rs
// 提取查询参数、请求体、头等类型化数据
app.post("/login", |req: CanonicalRequest, _| {
    let body = req.body_str();
    // 解析 JSON 或表单...
    Ok(CanonicalResponse::new(200))
});

中间件 DAG

zenith-web 提供 5 个内置中间件，并支持以 DAG 形式组合管线。中间件典型用于日志、鉴权、限流、CORS 等横切关注点。

middleware.rs
// 5 个内置中间件：日志、鉴权、CORS、限流、追踪等
app.use_middleware(Logger::new());
app.use_middleware(AuthMiddleware::default());
app.use_middleware(RateLimiter::new(100, Duration::from_secs(60)));

静态文件服务

内置静态文件服务支持 Range 与条件请求（304 / 206 / 416），并采用 open_nofollow 防止符号链接 TOCTOU。

static.rs
// 挂载静态目录
app.static_dir("/static", "./public");

// GET /static/app.js → 200 + Range 支持

多协议 ProtocolServer

ProtocolServer 统一承载 HTTP/1.1、HTTP/2、HTTP/3 与 TLS 1.3，并提供 SecurityPipeline 8 步安全管道。启用 afxdp 特性时还可桥接 AF_XDP 数据面。

server.rs · feature = web + tls + runtime
// ProtocolServer 同时监听 H1/H2/H3 + TLS
let server = ProtocolServer::new(app)
    .tls(cert_chain, private_key)?
    .http2()
    .http3()
    .bind("0.0.0.0:8443")
    .await?;

RuntimeConfig 热更新

Web 层几乎全部运行参数通过 RuntimeConfig 无锁原子热更新，无需重建服务器。详见运行时热更新章节。

完整 API 与中间件列表，请参考 crate 文档 zenith-web。协议层细节见协议实现。