第一篇的工程能跑之后,我加了第二个接口:POST /api/items。路由写好了,curl 也带了 JSON,返回却是 415 Unsupported Media Type。补上 Content-Type 之后又变成 400,提示反序列化失败。换到 GET /api/items/99,想验证「找不到」的分支,结果整个路由 404,连处理函数都没进。

这三个现象指向同一件事:Axum 把请求拆成了「路由匹配、提取器、处理函数、响应」几个阶段,每个阶段有自己的失败方式。你看到的 404、415、400,可能来自完全不同的层,只盯着处理函数改代码往往找不到原因。

这篇接着上一篇的 main.rs,把路由树、提取器顺序、中间件位置分别拆开。目标不是背 API,而是建立一个排查顺序:先确认请求有没有匹配到路由,再确认提取器有没有失败,最后才看业务逻辑。所有权和 trait 的语法细节不在本篇,遇到 FromRequestParts 这种名字只解释它负责什么。

先看现象:路由层的八个典型故障

下面这张表覆盖了我在这一层实际遇到和见到的多数问题。注意「现象」一栏的状态码,它比错误文案更可靠:404 通常意味着没匹配到路由,405 是匹配到了但方法不对,415 和 400 已经进了提取器。

现象真实原因第一步查什么
写 /api/items/:id,请求返回 404Axum 0.8 的路径参数是 {id},冒号写法属于 0.7看 route 字符串里的参数段
返回 405 Method Not Allowed路径匹配上了,但只注册了 GET,请求用的是 POSTcurl -i 看请求方法,再看 route 链
返回 415 Unsupported Media TypeJson 提取器要求 Content-Type: application/jsoncurl 是否带了 -H,大小写和空格是否正确
返回 400,提示 deserialize 失败body 是合法 JSON,但字段名或类型与结构体不匹配对照 Deserialize 结构体的字段名与类型
处理函数拿不到 State.with_state 没加,或加在了错误的子路由上看 nest、merge 与 with_state 的先后
中间件读过 body 后,处理函数解析失败请求 body 只能被消费一次,读走之后后面拿到的就是空流中间件是否读了 body;改用 parts 或把逻辑下放
浏览器跨域请求 OPTIONS 返回 404没有挂 CorsLayer,或挂在了不包含该路由的 Router 上看 OPTIONS 请求有没有进到应用,检查 layer 位置
中间件对某些路由不生效route_layer 只作用于已注册的路由,顺序错了就漏确认 layer 与 route 的调用顺序

这张表最有用的一条是状态码分层:404 和 405 发生在路由匹配阶段,415 和 400 发生在提取器阶段,500 才轮到处理函数。按这个顺序排查,能避免「在 handler 里打一堆日志,结果请求根本没进来」的浪费。第 2 篇的开头那个 415,就是提取器在 handler 之前拒绝了请求。

405 和 404 的区别经常被忽略。Axum 对「路径存在但方法不对」会返回 405,并带一个 allow 头列出支持的方法;如果路径本身不存在,才是 404。看到 405 不要改路径,去看方法注册。

Router 的嵌套与 merge

Router 是 Axum 里的路由表,负责把「方法加路径」映射到处理函数。它支持三种组合方式:route 直接加一条,nest 把一个子 Router 挂到某个前缀下,merge 把两个 Router 平铺合并。三者的差别不在功能,而在「前缀怎么算」和「状态、中间件的作用范围」。

nest("/api", api) 会把子 Router 里的 /items 变成 /api/items。适合按业务域拆文件:用户、订单、报表各自一个 Router,最后在主 Router 里挂三个前缀。注意嵌套之后,子 Router 里不要再写一遍 /api,否则实际路径会变成 /api/api/items,这种重复在重构时很常见。

merge 不改变路径,只是把两个 Router 的条目并到一起。它适合「同一个前缀下由不同模块负责不同路径」的场景,比如 /api/items 在商品模块,/api/orders 在订单模块,两个模块都返回 Router,主函数统一 merge。如果两条路由完全重复,Axum 在运行时会 panic,提示路由冲突,这个问题必须在启动阶段暴露,不能留到线上。

把上一篇的单文件拆开,结构大致如下。注意这里只是目录职责,不是物理上的强制分层:

src/main.rs创建连接池、拼装 Router、绑定端口。只做装配,不写业务。
src/routes/mod.rs按业务域导出子 Router,负责各自的 route 与 route_layer。
src/state.rs定义 AppState,放连接池、配置、共享缓存。
src/error.rs把内部错误统一映射成 HTTP 响应,避免每个 handler 手写状态码。

模块拆分本身没有对错,触发条件是「main.rs 超过两屏」或者「两个业务域开始互相引用」。拆得太早会在文件之间来回跳,拆得太晚一次改动要动几百行。模块系统怎么组织,可以看语言方向的 Rust 模块与包,这里只关心路由表的拼装。

这一篇的依赖只多两项:sqlx 的 derive 特性用于行映射,tower-http 用于 Trace 和 CORS。

[dependencies]
sqlx = { version = "0.8.6", features = ["runtime-tokio", "sqlite", "derive"] }
tower-http = { version = "0.6", features = ["trace", "cors"] }
cargo add sqlx@0.8.6 --features derive
cargo add tower-http@0.6 --features trace,cors
cargo run

下面是这一篇要用的路由骨架,包含 POST /api/items 和 GET /api/items/{id}。为了能直接跑,处理函数里用了上一篇的连接池,建表语句放在启动阶段:

use axum::{
    extract::{Path, State},
    http::StatusCode,
    response::{IntoResponse, Response},
    routing::{get, post},
    Json, Router,
};
use serde::{Deserialize, Serialize};
use sqlx::FromRow;

#[derive(Clone)]
struct AppState {
    pool: sqlx::SqlitePool,
}

#[derive(Deserialize)]
struct NewItem {
    name: String,
}

#[derive(Serialize, FromRow)]
struct Item {
    id: i64,
    name: String,
}

enum ApiError {
    NotFound,
    Db(sqlx::Error),
}

impl ApiError {
    fn not_found() -> Self {
        ApiError::NotFound
    }
}

impl From<sqlx::Error> for ApiError {
    fn from(error: sqlx::Error) -> Self {
        ApiError::Db(error)
    }
}

impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        match self {
            ApiError::NotFound => (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": "not found" })),
            )
                .into_response(),
            ApiError::Db(error) => {
                tracing::error!(error = %error, "database error");
                (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    Json(serde_json::json!({ "error": "internal" })),
                )
                    .into_response()
            }
        }
    }
}

async fn create_item(
    State(state): State<AppState>,
    Json(input): Json<NewItem>,
) -> Result<(StatusCode, Json<Item>), ApiError> {
    let item = sqlx::query_as::<_, Item>(
        "INSERT INTO items (name) VALUES (?) RETURNING id, name",
    )
    .bind(&input.name)
    .fetch_one(&state.pool)
    .await?;
    Ok((StatusCode::CREATED, Json(item)))
}

async fn get_item(
    State(state): State<AppState>,
    Path(id): Path<i64>,
) -> Result<Json<Item>, ApiError> {
    let item = sqlx::query_as::<_, Item>(
        "SELECT id, name FROM items WHERE id = ?",
    )
    .bind(id)
    .fetch_optional(&state.pool)
    .await?;
    match item {
        Some(item) => Ok(Json(item)),
        None => Err(ApiError::not_found()),
    }
}

fn api_routes() -> Router<AppState> {
    Router::new()
        .route("/items", post(create_item))
        .route("/items/{id}", get(get_item))
}

#[tokio::main]
async fn main() {
    let pool = sqlx::SqlitePool::connect("sqlite://app.db?mode=rwc")
        .await
        .expect("open sqlite");
    sqlx::query(
        "CREATE TABLE IF NOT EXISTS items (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL
        )",
    )
    .execute(&pool)
    .await
    .expect("create table");

    let state = AppState { pool };
    let app = Router::new()
        .route("/health", get(|| async { "ok" }))
        .nest("/api", api_routes())
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:18080")
        .await
        .expect("bind 18080");
    axum::serve(listener, app).await.expect("server");
}

ApiError 的定义也放在这里,第 3 篇会扩展它的分支。先注意两个类型细节:api_routes() 的返回类型是 Router<AppState>,表示「还缺一份 AppState 才能服务」;主 Router 在 nest 之后调用 .with_state(state),把状态补齐,类型才变成可交给 axum::serve 的 Router。把 with_state 写在 api_routes 里面,再 nest 到一个已经有状态的 Router,会编译失败,因为状态被补了两次。

写完先跑起来,用 curl 验证两个分支。POST 的实际返回:

curl -s -i -X POST 127.0.0.1:18080/api/items -H "Content-Type: application/json" -d '{"name":"widget"}'
HTTP/1.1 201 Created
content-type: application/json

{"id":1,"name":"widget"}

再请求一个不存在的 id:

curl -s -i 127.0.0.1:18080/api/items/99
HTTP/1.1 404 Not Found
content-type: application/json

{"error":"not found"}

201 是 StatusCode::CREATED 显式给的,Axum 不会因为你返回了 JSON 就自动改成 201。404 是 ApiError::not_found() 构造的,说明请求已经匹配到 /api/items/{id} 并进了处理函数,只是数据库里没有这一行。如果这里拿到的是路由层的 404,响应体通常不是你的 JSON,而是 Axum 默认的空响应,这个差别是判断问题层级的好线索。

提取器的执行顺序:最后一个才消费 body

提取器(extractor)是 Axum 把请求的不同部分转成函数参数的工具。Path 取路径里的变量,Query 取查询串,HeaderMap 取全部请求头,State 取你注入的共享状态,Json 把请求体反序列化成结构体。它们不是装饰,而是有执行顺序的:参数从左到右依次执行,任何一个失败,后面的都不会跑,handler 也不会被调用。

顺序规则只有一条:所有只读请求头部的提取器必须放在读取 body 的提取器之前。原因是 HTTP 请求的 body 是一条只能读一次的流。读走之后,后面的提取器拿到的是空流,只能报错。Axum 在编译期就会检查这件事,如果写了两个会消费 body 的提取器,编译直接失败,错误里会出现「multiple body extractors」之类的提示。

一个请求在 Axum 里的执行顺序
请求进入
外层 layer 记录方法、路径
路由匹配,填路径参数
State 提取
Path / Query / HeaderMap 提取
Json 读取 body
handler 执行
响应返回,外层 layer 记录状态码

这张图解释了两个疑问。第一,State 放在参数最前面最自然:它不依赖 body 和路径,先拿到手,后面的提取器失败时还能用它做日志。第二,鉴权中间件不该依赖 body:中间件先把 body 读了,handler 的 Json 就会失败。鉴权只需要请求头,放在 handler 之前完全够用。

具体写法上,State 通常放第一个,然后是按业务需要的路径、查询、头部,Json 永远放最后。下面这个签名是合法的,因为它只有一个 body 提取器:

async fn create_item(
    State(state): State<AppState>,
    headers: HeaderMap,
    Path(tenant): Path<String>,
    Json(input): Json<NewItem>,
) -> Result<(StatusCode, Json<Item>), ApiError> {
    let _ = (state, headers, tenant);
    // 业务逻辑
    todo!()
}

把 Json 挪到 State 前面,编译会报错,因为 State 属于 parts 提取器,必须排在 body 提取器之前。这个约束让失败点固定,排查时不用猜是哪一步把 body 读走了。

不要在中间件里读请求 body 再放回去。技术上可以用 axum::body::to_bytes 读完再重建,但代价是整段 body 进内存,大文件上传会直接吃满内存。鉴权、限流、日志这些中间件只该看方法、路径、头部和状态;确实需要看 body 的校验,放进提取器或 handler,让顺序和失败响应都可控。

FromRequestParts 与 FromRequest:两种提取器的边界

FromRequestParts 和 FromRequest 是 Axum 定义的两类提取器 trait,名字直白:前者只从请求的「部件」里取值,不碰 body;后者可以获得整个请求,包括 body。所有内置提取器都落在这两类里,State、Path、Query、HeaderMap 是前者,Json、Bytes、String 是后者。

这个区分决定了顺序约束:FromRequestParts 可以出现多次,彼此独立;FromRequest 最多出现一次,而且必须在所有 parts 提取器之后。你自己写提取器时,先问一句「要不要读 body」,答案决定实现哪个 trait。只读头部的自定义提取器,比如从 Authorization 里解析出当前用户,用 FromRequestParts 就够了,而且能被放在参数列表任意位置(只要在 body 提取器之前)。

FromRequestParts

只读请求头、路径、查询串,不消费 body。可以写多个,执行成本低,失败时能返回自己的 rejection。适合鉴权、租户识别、请求 ID 这类「读头部就能判断」的逻辑。实现时拿到的是 Parts 和状态,拿不到 body。

FromRequest

可以消费整个 body,因此一个请求只能用一次。适合 JSON、表单、原始字节、文件上传。失败通常意味着请求格式不对,默认 rejection 会返回 400 或 415。实现时拿到的是完整请求,读完 body 后请求就不能再被别的提取器使用。

还有一个容易踩的细节:提取器的 rejection(拒绝)默认会直接变成响应,你可以在 handler 的返回类型里用 Result 接管,也可以让 Axum 用它自带的拒绝响应。默认行为是:Json 的 content-type 不对返回 415,JSON 语法或字段不匹配返回 400,Path 解析失败返回 400。Query 也类似。很多人以为 415 是框架 bug,其实它是在告诉你「请求格式这一层就没过」。

自定义 rejection 的价值在于统一响应格式。项目对外约定错误体是 {"error":"..."},而 Axum 默认的 rejection 是纯文本,前端解析会失败。第 4 篇的鉴权提取器会给出完整写法:实现 FromRequestParts,把「没有 token」和「token 不对」分别映射成 401 加 JSON。那一篇也会解释为什么这类逻辑不该塞进每个 handler。

选择哪一类还有一个工程判断:需要读 body 的逻辑尽量放进 handler,而不是全局提取器。提取器在 handler 之前执行,失败时日志里缺少业务上下文;放进 handler 可以先记录请求 ID 再解析。提取器更适合身份、租户、请求追踪这类横切关注点。

中间件:from_fn_with_state 与 tower-http 放哪一层

Axum 的中间件本质是 tower 的 Layer 与 Service:一个中间件包住一个服务,在调用前后各做一段事。axum::middleware::from_fn_with_state 是把普通 async 函数转成中间件的最省事方式,函数签名大致是「状态、请求、Next」,调用 next.run(req).await 得到响应,可以修改请求或响应。

下面这个中间件记录每个请求的方法、路径、状态码和耗时。它只读 parts,不碰 body,放在最外层是安全的:

use std::time::Instant;

use axum::{
    extract::{Request, State},
    middleware::Next,
    response::Response,
};

async fn request_log(
    State(_state): State<AppState>,
    req: Request,
    next: Next,
) -> Response {
    let started = Instant::now();
    let method = req.method().clone();
    let path = req.uri().path().to_string();
    let res = next.run(req).await;
    tracing::info!(
        %method,
        path,
        status = res.status().as_u16(),
        elapsed_ms = started.elapsed().as_millis(),
        "request"
    );
    res
}

let app = Router::new()
    .route("/health", get(health))
    .nest("/api", api_routes())
    .layer(axum::middleware::from_fn_with_state(
        state.clone(),
        request_log,
    ))
    .with_state(state);

from_fn_with_state 的第一个参数是状态,所以中间件可以用连接池、配置、计数器。这里的关键是位置:.layer 加在整个 Router 上,健康检查和所有 API 都会经过它;如果只想让某组路由经过,就把 layer 加在子 Router 上,再用 nest 挂进来。route_layer 是另一个变体,它只作用于「已经注册的路由」,对未匹配的路径不执行。这个差别在鉴权上很重要:未匹配的路径本来就不该做鉴权,让它直接 404 更合理。

关于多层中间件的顺序,记一句就够:后加的 layer 包在外层,先看到请求。因为每次 .layer 都是把当前 Router 包进一个新的服务,最后包的离网络最近。实际影响是:最外层的日志中间件会看到所有请求,包括被内层鉴权拒绝的;内层鉴权则拿不到外层已经修改过的请求,除非外层显式传递。排查「日志里没有这条请求」时,先看它是不是被更外层的超时或连接限制截断了。

最外层:tower-http 的 TraceLayer、CorsLayer、超时与限流面向所有请求,包括 404。TraceLayer 记录进入和离开,CorsLayer 处理预检;超时要包住整个内层,否则内层还在跑,外层已经断开。
中层:route_layer 上的鉴权与租户解析只作用于已匹配的路由。未匹配路径直接 404,不浪费一次 token 校验;鉴权失败在这里返回 401,handler 不会执行。
内层:handler 与提取器负责业务校验、数据库访问、响应构造。业务错误在这里变成具体状态码,横切逻辑不写进来。

tower-http 提供现成的 TraceLayer 和 CorsLayer。TraceLayer::new_for_http() 会为每个请求生成 span 并记录方法、路径、状态,但它具体的日志字段和级别我没有在本机实测,这里只给放置位置,不承诺输出格式。CorsLayer 处理跨域预检:浏览器发 OPTIONS 时,它必须在路由匹配之前就返回 200,否则你会看到一个来自路由层的 404。把 CORS 放在最外层,是让预检请求不进入业务路由的关键。

use tower_http::{cors::CorsLayer, trace::TraceLayer};

let app = Router::new()
    .route("/health", get(health))
    .nest("/api", api_routes())
    .layer(TraceLayer::new_for_http())
    .layer(CorsLayer::permissive())
    .with_state(state);

CorsLayer::permissive() 只适合本地联调,它允许任意来源。生产环境要按域名白名单配置,并且明确允许的方法和头部。把 CORS 写在最外层还有一个原因:预检请求不带业务 token,如果放在鉴权里面,会被 401 挡掉,浏览器根本发不出正式请求。

中间件里不要抢 handler 的活。权限判断、参数校验、业务分支如果写进中间件,处理函数的输入就不再可信,测试也很难覆盖。判断标准是:这段逻辑是否对所有路由都一样,且不依赖具体业务字段。是,就放中间件;否,就放 handler 或提取器。

为什么权限判断不该写在 handler 里,理由不是「不好看」,而是「会漏」。一个项目有二十个接口,鉴权写在每个 handler 开头,新增接口时忘写一次就是越权。中间件或提取器的价值是把这件事变成路由装配的一部分:挂上 route_layer 的路由自动受保护,没挂的明确不受保护。第 4 篇会把这条线落成可运行的令牌校验。

边界与代价

这套分层不是没有成本。每加一层中间件,请求就多一次函数调用和一层 future 包装,编译后的类型也更复杂。层数不多时感觉不到,但把十几个小逻辑都写成独立 layer,调用栈会变得很难读。判断标准是作用范围:跨所有路由的放最外层,跨一组路由的放子 Router,只影响一个 handler 的写在 handler 里。

nest 和 merge 的代价在状态和中间件的作用范围上。嵌套 Router 的状态必须一致,子 Router 不能自己再补一次状态;merge 的两个 Router 如果都带 layer,合并后 layer 的作用范围可能和你想的不一样。遇到「某个接口没走日志」或者「某个接口被鉴权了两次」,先画一下路由树,标清每个 layer 挂在哪,通常五分钟就能定位。

提取器的代价是「顺序即契约」。参数顺序变了,编译可能过,行为却可能变;尤其是自定义提取器,如果它内部读了 body,就会悄悄影响后面的 Json。团队里应该有一条约定:body 提取器永远放最后一个,自定义提取器只实现 FromRequestParts,除非确实需要读 body。这条约定比任何文档都有效。

还有一个边界是错误响应的统一。默认 rejection 是纯文本,业务错误是 JSON,前端要处理两种格式。要么在提取器层自定义 rejection,要么在 handler 层全部用 Result 并统一 IntoResponse。第 3 篇会把 sqlx::Error 到 HTTP 状态码的映射写完整。

当天能自己验证的练习

  1. 把 /api/items/{id} 临时改成 /api/items/:id,请求同一个地址,确认返回 404;再改回来,确认 200 或 404(取决于数据是否存在),并记录两次响应体的差别。
  2. 用 curl -i 对 /api/items 发 GET,确认返回 405,并检查响应头里的 allow 字段;再发 POST 且不带 Content-Type,确认 415。
  3. 在 create_item 的参数里把 Json 挪到 State 前面,抄下编译错误;再写两个 Json 参数,观察「body 只能消费一次」的编译提示。
  4. 把 request_log 分别加在主 Router 和 API 子 Router 上,请求一个不存在的路径,对比日志里有没有这条记录,理解 layer 与 route_layer 的范围。
  5. 给 API 子 Router 加 CorsLayer::permissive(),用 curl -i -X OPTIONS 发预检请求,确认返回 200 且带跨域头;再把 CORS 移到鉴权之后,观察预检是否被 401 挡住。

做完这五个练习,你应该能靠状态码判断问题发生在哪一层。下一篇进入数据访问:连接池开多大、query! 和 query_as 怎么选、事务为什么不 commit 就不会生效,以及池子被打满时服务会返回什么。那一篇会用实测的 503 和日志把「池子不是越大越好」讲透。

小结

三句话收束:路由层用 404 和 405 区分「路径不存在」与「方法不对」,nest 管前缀、merge 管平铺;提取器从左到右执行,body 提取器只能有一个且必须最后;中间件后加的在外层,CORS 和 Trace 放最外,鉴权放 route_layer,业务判断留在 handler。

把这一篇的路由树保留下来,下一篇会直接在 create_item 和 get_item 上补数据库细节。到那时你会发现,路由和分层写对之后,数据访问的问题会变得非常具体:要么是连接池参数,要么是查询写法,要么是事务边界。