如何在Axum中解析复杂的路径组件？

问题根源 #

你遇到的错误是因为默认情况下，serde无法将URL捕获的字符串（如2023-11-01T16-52-00Z、FOO_BAR_BAZ、123_456）反序列化为DateTime<Utc>、Vec<String>和(u32, u32)类型。Axum的Path提取器依赖serde对单个字符串段进行反序列化，而非serde_urlencoded（后者用于查询参数）。

解决方案：自定义serde反序列化逻辑 #

我们需要为每个特殊类型实现自定义反序列化规则，通过serde的deserialize_with属性关联到结构体字段上（优先用结构体而非元组，因为元组无法为单个元素指定反序列化规则）。

1. 定义参数结构体并添加serde属性 #

use axum::{extract::Path, Router, routing::get};
use chrono::{DateTime, Utc};
use serde::Deserialize;
use std::net::SocketAddr;

#[derive(Deserialize)]
struct StatsParams {
    // 自定义解析URL安全的ISO时间戳
    #[serde(deserialize_with = "deserialize_url_safe_datetime")]
    start: DateTime<Utc>,
    // 自定义解析下划线分隔的字符串列表
    #[serde(deserialize_with = "deserialize_underscore_separated_vec")]
    tokens: Vec<String>,
    // 自定义解析下划线分隔的u32对
    #[serde(deserialize_with = "deserialize_underscore_separated_pair")]
    coords: (u32, u32),
}

2. 实现自定义反序列化函数 #

解析URL安全的DateTime

将T后的横杠替换为冒号，转换为标准ISO格式后再解析：

fn deserialize_url_safe_datetime<'de, D>(deserializer: D) -> Result<DateTime<Utc>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let raw_str: String = serde::Deserialize::deserialize(deserializer)?;
    
    // 拆分日期和时间部分，替换时间里的横杠为冒号
    let mut parts = raw_str.splitn(2, 'T');
    let date_part = parts.next().ok_or_else(|| serde::de::Error::custom("无效的时间格式：缺少日期部分"))?;
    let time_part = parts.next().ok_or_else(|| serde::de::Error::custom("无效的时间格式：缺少时间部分"))?;
    let formatted_time = time_part.replace("-", ":");
    
    DateTime::parse_from_rfc3339(&format!("{}T{}", date_part, formatted_time))
        .map(|dt| dt.with_timezone(&Utc))
        .map_err(serde::de::Error::custom)
}

解析下划线分隔的字符串列表

直接按下划线分割字符串并转为Vec<String>：

fn deserialize_underscore_separated_vec<'de, D>(deserializer: D) -> Result<Vec<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let raw_str: String = serde::Deserialize::deserialize(deserializer)?;
    Ok(raw_str.split('_').map(String::from).collect())
}

解析下划线分隔的u32对

分割字符串后分别解析为u32：

fn deserialize_underscore_separated_pair<'de, D>(deserializer: D) -> Result<(u32, u32), D::Error>
where
    D: serde::Deserializer<'de>,
{
    let raw_str: String = serde::Deserialize::deserialize(deserializer)?;
    let mut parts = raw_str.split('_');
    
    let first = parts.next()
        .ok_or_else(|| serde::de::Error::custom("坐标格式错误：缺少第一个值"))?
        .parse()
        .map_err(serde::de::Error::custom)?;
    
    let second = parts.next()
        .ok_or_else(|| serde::de::Error::custom("坐标格式错误：缺少第二个值"))?
        .parse()
        .map_err(serde::de::Error::custom)?;
    
    Ok((first, second))
}

3. 修改处理函数并启动服务 #

async fn stats(Path(params): Path<StatsParams>) {
    println!("开始时间：{}", params.start);
    println!("Tokens列表：{:?}", params.tokens);
    println!("坐标：{:?}", params.coords);
}

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/api/:start/:tokens/:coords", get(stats));

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    println!("启动服务：http://{}", addr);
    axum::Server::bind(&addr)
        .serve(app.into_make_svc())
        .await
        .unwrap();
}

关键说明 #

• Axum的Path提取器对每个URL捕获段单独进行serde反序列化，每个段对应一个字段/元组元素。
• 用结构体替代元组可以更灵活地为每个字段指定自定义反序列化规则，这是解决原错误的核心。
• 所有自定义逻辑都通过serde的deserialize_with属性关联，无需手动修改类型的全局Deserialize实现。

内容的提问来源于stack exchange，提问作者fadedbee