axum 的 GET 路由如何同时响应 HEAD 请求并显式区分方法

axum 的 GET 路由如何同时响应 HEAD 请求并显式区分方法【免费下载链接】axumHTTP routing and request-handling library for Rust that focuses on ergonomics and modularity项目地址: https://gitcode.com/GitHub_Trending/ax/axum如果你用 axum 写了一个GET路由客户端发来的HEAD请求同样会命中同一个 handler——这不是可配置的行为而是 axum 的路由规则。默认情况下 handler 照常执行只是响应体在最后被路由层剥掉handler 本身并不知道当前是 GET 还是 HEAD。本文基于仓库中的官方示例 examples/handle-head-request/src/main.rs 及相关测试代码说明这个默认行为的具体细节以及两种显式区分方法的写法在 handler 内提取请求方法或为同一路径单独注册HEAD路由。GET 路由收到 HEAD 请求时的默认行为get与get_service函数的文档注释由 method_routing.rs 中的宏展开生成明确写道Note thatgetroutes will also be called forHEADrequests but will have the response body removed.也就是说HEAD 请求会调用 GET 路由的 handlerhandler 返回的 status code 和 headers 原样保留只有 body 被移除。具体顺序可以看 route.rs 中RouteFuture::poll的实现先为 405 响应补Allow头然后执行注释为 make sure to set content-length before removing the body 的set_content_length最后才是if *this.method Method::HEAD { *res.body_mut() Body::empty(); }。因为 content-length 在剥 body之前设置所以 HEAD 响应通常仍会带上 GET 响应体的长度。仓库测试对此有直接断言tests/mod.rshandler 返回foo时HEAD 请求得到content-length: 3且 body 为空tests/get_to_head.rs 则断言 HEAD 命中 GET 路由时 status 为 200、自定义头x-some-header: foobar保留、body 长度为 0。有两个边界情况需要注意均来自测试代码如果 handler 针对 HEAD 显式返回了不带 content-length 的响应例如().into_response()那么该 HEAD 响应就没有content-length头见 route.rs 的regression_3741测试如果路由链上挂了压缩中间件如 tower-http 的CompressionLayerHEAD 响应既没有transfer-encoding也没有content-length因为压缩后的长度无法预知见 tests/mod.rs 的head_with_middleware_applied测试。在 handler 内提取 http::Method 区分两种方法官方示例 examples/handle-head-request/src/main.rs 展示了最常用的写法把http::Method作为 handler 参数提取出来。示例中的原话是GET routes will also be called for HEAD requests but will have the response body removed. You can handle the HEAD method explicitly by extractinghttp::Methodfrom the request.并且注释强调只有当计算响应体本身有可观成本时才值得对 HEAD 做特殊处理it usually only makes sense to special-case HEAD if computing the body has some relevant cost。示例完整代码依赖见 examples/handle-head-request/Cargo.tomlaxum与tokiofull 特性use axum::response::{IntoResponse, Response}; use axum::{http, routing::get, Router}; fn app() - Router { Router::new().route(/get-head, get(get_head_handler)) } #[tokio::main] async fn main() { let listener tokio::net::TcpListener::bind(127.0.0.1:3000) .await .unwrap(); println!(listening on {}, listener.local_addr().unwrap()); axum::serve(listener, app()).await; } // GET routes will also be called for HEAD requests but will have the response body removed. // You can handle the HEAD method explicitly by extracting http::Method from the request. async fn get_head_handler(method: http::Method) - Response { // it usually only makes sense to special-case HEAD // if computing the body has some relevant cost if method http::Method::HEAD { return ([(x-some-header, header from HEAD)]).into_response(); } // then do some computing task in GET do_some_computing_task(); ([(x-some-header, header from GET)], body from GET).into_response() } fn do_some_computing_task() { // TODO }注意区分两件事即使 handler 对 HEAD 分支返回了 body路由层最终仍会把它剥掉但 handler 里do_some_computing_task()这类的计算已经发生过了。所以方法判断的价值不在去掉 body路由层会做而在避免为 HEAD 请求白白计算 body。运行示例并核对响应前置条件Rust 工具链README.md 声明 axum 的 MSRV 是 1.80。该示例位于 examples 工作区examples/Cargo.toml 中members [*]包名为example-handle-head-requestmain.rs 顶部注释给出的运行命令是cargo run -p example-handle-head-request在examples/目录下执行它。服务启动后监听127.0.0.1:3000终端打印listening on 127.0.0.1:3000。然后在另一个终端分别用两种方法请求/get-headcurl -i http://127.0.0.1:3000/get-head curl -I http://127.0.0.1:3000/get-head预期结果与示例内置测试main.rs 的test_get与test_implicit_head断言的响应一致GETstatus 200x-some-header: header from GETbody 为body from GETHEADstatus 200x-some-header: header from HEADbody 为空。这些数值来自示例代码本身及其测试断言用于核对示例是否按预期运行而非框架的固定输出。也可以直接跑测试验证无需起服务cargo test -p example-handle-head-request写自己的 HEAD 测试时有一条来自仓库测试代码的提示tests/get_to_head.rs 中的注释dont use reqwest because it always strips bodies from HEAD responses即客户端库可能自行剥掉 HEAD 响应体导致断言失真。仓库的做法是用tower::ServiceExt::oneshot直接对Router发原始请求再用http_body_util::BodyExt::collect取回 body 做断言示例的 dev-dependencies 就是为此引入tower、http-body-util、hyper。替代路径为同一路径显式注册 HEAD 路由get文档注释的下一句是 Make sure to add explicitHEADroutes afterwards.——axum 在get之外提供了平行的head/head_service函数见 method_routing.rs 中的top_level_handler_fn!(head, HEAD)与chained_handler_fn!(head, HEAD)。chained_handler_fn!会为MethodRouter生成head方法因此可以在同一路径上同时注册两种方法的处理器use axum::routing::{get, head}; let app Router::new() .route(/get-head, get(get_handler).head(head_handler));适用场景两种方法的逻辑差异大到在一个 handler 里if分支已经影响可读性时拆成两个 handler 更清晰。另外当某个不被路由接受的方法如POST打到只注册了 GET 的路径上时405 响应会带Allow: GET,HEAD头route.rs 的set_allow_header逻辑method_routing.rs 等测试有assert_eq!(headers[ALLOW], GET,HEAD)断言——从路由层视角看一个 GET 路由本身就同时承载 GET 和 HEAD 两种方法。验证要点小结用curl -IHEAD和curl -iGET分别请求同一路径核对状态码、自定义头与 body 是否为空HEAD 的 body 为空是路由层保证的但若链上有压缩中间件content-length可能缺失属预期行为自动化测试中避免使用会自行剥离 HEAD body 的高层客户端按 tests/get_to_head.rs 的方式用oneshot发原始请求断言。【免费下载链接】axumHTTP routing and request-handling library for Rust that focuses on ergonomics and modularity项目地址: https://gitcode.com/GitHub_Trending/ax/axum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考