Axum `MethodRouter::fallback` 完全指南：方法级兜底处理、`Allow` 头语义与 `merge` 冲突陷阱

本篇技术指南围绕 axum 的 MethodRouter::fallback 展开，它解决的是"路径匹配成功、但 HTTP 方法不匹配"时的兜底请求处理问题。你将掌握如何在单个路径上为未注册的 HTTP 方法提供自定义响应、理解 405 Method Not Allowed 与 Allow 响应头的自动设置机制，并避开两个带 fallback 的 MethodRouter 合并时的 panic 陷阱。

什么是 MethodRouter::fallback

在 axum 的路由体系中，路由匹配分两个层次：Router 负责按路径匹配，MethodRouter 负责在路径命中后按 HTTP 方法（GET、POST、PUT……）匹配。两者的兜底机制是独立的：

• Router::fallback 处理"没有任何路径匹配"的请求（通常是 404 场景），详见 routing/fallback.md；
• MethodRouter::fallback 处理"路径匹配了，但该 MethodRouter 上没有对应 HTTP 方法的处理器"的请求（通常是 405 场景）。

本文讲解的 method_routing/fallback.md 正是一份被直接内嵌为 MethodRouter::fallback_service 文档的官方说明（见 method_routing.rs 中的 #[doc = include_str!("../docs/method_routing/fallback.md")]）。

从源码看，MethodRouter::fallback 的本质是把兜底逻辑注册进路由器的 fallback 槽位，其定义位于 method_routing.rs：

/// Add a fallback [`Handler`] to the router.
pub fn fallback<H, T>(mut self, handler: H) -> Self
where
    H: Handler<T, S>,
    T: 'static,
    S: Send + Sync + 'static,
{
    self.fallback = Fallback::BoxedHandler(BoxedIntoRoute::from_handler(handler));
    self
}

与之对应的 fallback_service（method_routing.rs）接受任意实现了 tower::Service 的服务：

pub fn fallback_service<T>(mut self, svc: T) -> Self
where
    T: Service<Request, Error = E> + Clone + Send + Sync + 'static,
    T::Response: IntoResponse + 'static,
    T::Future: Send + 'static,
{
    self.fallback = Fallback::Service(Route::new(svc));
    self
}

基本用法：为未匹配的 HTTP 方法编写兜底处理器

官方文档给出了最典型的场景：在一个只注册了 GET 的路径上，为其他所有 HTTP 方法提供统一的自定义响应。fallback 可以像普通 handler 一样使用提取器，例如提取 Method 和 Uri 来构造带诊断信息的响应：

use axum::{
    Router,
    routing::get,
    handler::Handler,
    response::IntoResponse,
    http::{StatusCode, Method, Uri},
};

let handler = get(|| async {}).fallback(fallback);

let app = Router::new().route("/", handler);

async fn fallback(method: Method, uri: Uri) -> (StatusCode, String) {
    (StatusCode::NOT_FOUND, format!("`{method}` not allowed for {uri}"))
}
# let _: Router = app;

这段代码的关键点：

• fallback 通过 Handler trait 接入，因此可以像普通 handler 一样声明提取器参数（Method、Uri、State、Query 等均可），这与路由上的普通 handler 并无区别；
• 返回类型任意实现了 IntoResponse 的值都合法，这里返回了 (StatusCode, String) 元组；
• 由于 fallback 是一个 handler，它同样可以访问 Router 注入的 State。测试 fallback.rs 中的 fallback_accessing_state 用例即验证了 fallback(|State(state): State<&'static str>| async move { state }) 可以正常读取状态。

未匹配方法时的默认行为：405 与 Allow 头

MethodRouter::new() 创建的默认路由器自带一个兜底行为：对任何请求返回 405 Method Not Allowed。源码见 method_routing.rs：

pub fn new() -> Self {
    let fallback = Route::new(service_fn(|_: Request| async {
        Ok(StatusCode::METHOD_NOT_ALLOWED)
    }));
    // ...
}

也就是说，如果你不显式设置 fallback，GET /foo 之外的 POST /foo 会收到一个裸的 405 响应。fallback 的意义就在于把这一层默认行为替换成你自己的逻辑。

官方文档特别强调了 Allow 头的自动设置语义，这是本文档的核心知识点之一：

By default MethodRouter will set the Allow header when returning 405 Method Not Allowed. This is also done when the fallback returns 405 Method Not Allowed unless the response generated by the fallback already sets the Allow header.

翻译成实际操作规则：

1. 默认情况：MethodRouter 返回 405 时会自动附带 Allow 头，列出该路径上已注册的全部方法（例如 Allow: GET, HEAD）；
2. fallback 返回 405 时：如果 fallback 自己返回的状态码是 405，MethodRouter 同样会补上 Allow 头；
3. 例外：如果 fallback 生成的响应已经自己设置了 Allow 头，则 axum 不会覆盖它；
4. 自定义兜底非 405 时：如果你的 fallback 返回的是 404 或其他状态码（如上面示例中的 StatusCode::NOT_FOUND），则不会触发 Allow 头的自动注入。

这一行为在源码 call_with_state 中得到了印证：MethodRouter 会逐个方法地尝试分发请求，全部未命中后进入 fallback，并根据 allow_header 字段的状态决定是否向 fallback 的 future 注入 Allow 头：

let future = fallback.clone().call_with_state(req, state);

match allow_header {
    AllowHeader::None => future.allow_header(Bytes::new()),
    AllowHeader::Skip => future,
    AllowHeader::Bytes(allow_header) => future.allow_header(allow_header.clone().freeze()),
}

Allow 头的数据由 AllowHeader 枚举管理（method_routing.rs），有三个状态：

状态	含义
None	尚未累积任何 Allow 值（默认状态），注入空值
Skip	不设置 Allow 头，由 any / any_service 使用
Bytes(BytesMut)	已累积的 Allow 头值（如 "GET,HEAD"）

每当通过 get、post 等方法链注册一个方法时，append_allow_header（method_routing.rs）会把对应方法名追加进去——注意注册 GET 会同时追加 GET,HEAD，因为 axum 约定 GET 路由也会响应 HEAD 请求。

用 fallback 扩展方法时的 Allow 头注意事项

官方文档给出的关键实践建议是：如果你用 fallback 来"额外接受"某些方法（例如模拟一个接受所有方法的端点），你必须自己正确设置 Allow 头，否则客户端会从 Allow 头得到误导信息。

例如，下面的 fallback 把 POST 也当作可接受的方法，但返回 405 之外的响应，就需要手动声明：

use axum::{
    Router,
    routing::get,
    handler::Handler,
    response::IntoResponse,
    http::{StatusCode, Method, Uri, HeaderMap, header},
};

let handler = get(|| async {}).fallback(fallback);

let app = Router::new().route("/", handler);

async fn fallback(method: Method, uri: Uri) -> impl IntoResponse {
    if method == Method::POST {
        // 自己处理 POST，此时应显式声明支持的 Allow 方法集
        (
            StatusCode::OK,
            [(header::ALLOW, "GET, HEAD, POST")],
            format!("handled via fallback: {method} {uri}"),
        )
    } else {
        (
            StatusCode::METHOD_NOT_ALLOWED,
            [(header::ALLOW, "GET, HEAD, POST")],
            format!("`{method}` not allowed for {uri}"),
        )
    }
}

两个带 fallback 的 MethodRouter 无法合并

官方文档明确警告：同时设置了 fallback 的两个 MethodRouter 不能通过 merge 合并，否则会 panic：

use axum::{
    routing::{get, post},
    handler::Handler,
    response::IntoResponse,
    http::{StatusCode, Uri},
};

let one = get(|| async {}).fallback(fallback_one);

let two = post(|| async {}).fallback(fallback_two);

let method_route = one.merge(two);

async fn fallback_one() -> impl IntoResponse { /* ... */ }
async fn fallback_two() -> impl IntoResponse { /* ... */ }

这是因为合并后无法决定由哪个 fallback 兜底。这一限制体现在 Fallback::merge 的源码实现中（routing/mod.rs）：

enum Fallback<S, E = Infallible> {
    Default(Route<E>),          // 默认 405 兜底
    Service(Route<E>),          // 通过 fallback_service 设置
    BoxedHandler(BoxedIntoRoute<S, E>), // 通过 fallback 设置
}

impl<S, E> Fallback<S, E>
where
    S: Clone,
{
    fn merge(self, other: Self) -> Option<Self> {
        match (self, other) {
            // 只要有一方是默认兜底，就保留另一方
            (Self::Default(_), pick) | (pick, Self::Default(_)) => Some(pick),
            // 双方都是自定义 fallback，无法决定取舍，返回 None
            _ => None,
        }
    }
}

MethodRouter::merge_for_path（method_routing.rs）在 merge 返回 None 时直接 panic：

self.fallback = self
    .fallback
    .merge(other.fallback)
    .ok_or("Cannot merge two `MethodRouter`s that both have a fallback")?;

所以报错信息会是 Cannot merge two MethodRouter's that both have a fallback（带有 #[track_caller] 标注，panic 位置会指向你的 merge 调用处）。

规避方法：在合并前先为其中一个 MethodRouter 重置 fallback。MethodRouter 本身没有公开的 reset_fallback，但你可以在合并前重新构造：例如把需要保留 fallback 的 MethodRouter 放到合并链条的末端单独 .fallback(...)，或者干脆在合并后对整个 Router 使用 Router::fallback（路由级的 fallback 没有此限制）。此外 any(handler)（method_routing.rs）内部就是"注册 handler 为 fallback + skip_allow_header()"的组合，它接受所有方法，也不参与 Allow 头的冲突问题。

源码级原理：请求分发与兜底调用链

一个请求到达 MethodRouter 后，call_with_state 会按照 HEAD → GET → POST → OPTIONS → PATCH → PUT → DELETE → TRACE → CONNECT → QUERY 的顺序尝试匹配，一旦命中对应方法端点立即返回；全部未命中才走 fallback（method_routing.rs）：

call!(req, HEAD, head);
call!(req, HEAD, get);
call!(req, GET, get);
call!(req, POST, post);
call!(req, OPTIONS, options);
call!(req, PATCH, patch);
call!(req, PUT, put);
call!(req, DELETE, delete);
call!(req, TRACE, trace);
call!(req, CONNECT, connect);
call!(req, QUERY, query);

let future = fallback.clone().call_with_state(req, state);

值得注意的是 Fallback::call_with_state（routing/mod.rs）对三种 fallback 变体的处理是统一的：Default/Service 直接作为 Route 执行，BoxedHandler 则先把 handler 结合 state 转成 Route 再执行。这意味着 fallback 的调用路径与普通路由完全一致，同样受 Handler、IntoResponse 等抽象约束，行为可预期。

实战建议与延伸阅读

• 全局 404 页面：MethodRouter::fallback 管方法层，全局 404 页面应使用 Router::fallback。可以参考仓库示例 global-404-handler，其中 app.fallback(handler_404) 返回 (StatusCode::NOT_FOUND, "nothing to see here")。
• 区分 404 与 405：axum 提供了专门针对"方法不匹配"的 Router::method_not_allowed_fallback，与 MethodRouter 的 fallback 语义互补，可参考 method_not_allowed_fallback.md；对应行为在 fallback 测试 中有覆盖（例如自定义 mna fallback 时不会自动注入 Allow 头）。
• 验证途径：MethodRouter 的 fallback 行为有仓库测试背书，除上述 fallback_accessing_state 外，method_routing.rs 附近的测试还覆盖了 fallback 提取 Method 的用例；路由级 fallback 的合并、嵌套继承等场景则集中在 tests/fallback.rs 中，可作为你理解与复现行为的参考。

要点回顾：MethodRouter::fallback 负责方法不匹配时的兜底；默认兜底返回 405 并自动设置 Allow 头（除非 fallback 自己设置了该头）；用 fallback 扩展方法时必须自己维护 Allow 头；两个自定义 fallback 的 MethodRouter 无法合并。理解这四点，你就能在 axum 中精确控制每一个路径上"方法不存在"时的 HTTP 语义。