用途:在 Axum 中让处理函数从请求读取数据。提取器是处理函数参数获取请求数据的唯一方式,由两个 trait 决定是否读取请求体:FromRequestParts<S> 只从请求部件(方法、URI、请求头、扩展、路径参数)提取,绝不读体;FromRequest<S> 通过消费请求体提取。提取器接口在 Axum 0.7 与 0.8 一致,唯一版本差异是 Path<T> 读取的路由捕获语法:0.7 用 /:id 与 /*rest,0.8 用 /{id} 与 /{*rest},提取器代码本身不变。
主要能力:Path<T>(路径段,serde 反序列化)、Query<T>(查询串)、State<T>(共享状态,编译期检查)、Extension<T>(来自中间件的每请求类型值)、HeaderMap、Method、Uri 属于 FromRequestParts;Json<T>、Form<T>、Bytes、String、Request 属于 FromRequest。
核心规则:所有 FromRequestParts 提取器必须放在体提取器之前;唯一的体提取器必须是最后一个参数;一个处理函数绝不能有两个体提取器,因为体是单次消费的异步流;应用资源用 State<T>(编译期检查),不要用 Extension(缺失时运行时 500);0.8 中不要用 Option<Extractor> 表示忽略所有错误。
用法要点:Path<T> 支持单参数、元组(顺序即捕获顺序)、命名字段结构体与 HashMap;百分号编码自动解码,解码为非 UTF-8 会被拒绝,反序列化失败返回 PathRejection 与 400。Query<T> 可选字段应写成 Option<T>,解析失败返回 QueryRejection 与 400。Json<T> 要求 Content-Type: application/json,缺失或错误、JSON 语法无效、无法反序列化为 T 或缓冲失败时返回 JsonRejection。用 Result<Extractor, Extractor::Rejection> 可在处理函数内显式检查每种失败;0.8 中 Option<Extractor> 区分缺失(None)与存在但格式错误(拒绝请求)。违反顺序或双体提取器会导致 Handler trait 约束不满足的模糊错误,可用 axum-macros 的 #[debug_handler] 获得精确诊断。
适用场景:编写 Axum 处理函数、设计参数签名、排查提取器编译错误与 400 拒绝。限制:资料未提供安装命令、版本兼容范围之外的细节、性能数据或收费信息。