如何在Axum中编写处理通用Payload的Webhook POST事件路由？

我需要为Axum API编写一个处理Webhook事件的路由。请求的JSON主体包含event属性用于指定事件名称，data属性则会根据event类型对应不同的对象。现有代码定义了事件枚举，但DbWebhookBody的data字段类型无法确定。尝试用Serde的RawValue来应对此场景，但为结构体添加生命周期后，不确定如何在应用路由中正确传递处理，后续还需要根据事件类型对data进行反序列化并执行对应业务逻辑。

1. 正确定义带RawValue的结构体 #

RawValue是对原始JSON数据的引用，因此需要添加生命周期标注。修改DbWebhookBody如下：

use serde::Deserialize;
use serde_json::value::RawValue;

#[derive(Debug, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum DbWebhookEvent {
    SignUpCompleted,
}

#[derive(Debug, Deserialize)]
pub struct DbWebhookBody<'a> {
    event: DbWebhookEvent,
    data: &'a RawValue,
}

2. 调整路由处理函数的生命周期 #

Axum的Json提取器支持带生命周期的结构体，只需给处理函数添加对应的生命周期标注即可：

use axum::{Extension, Json};
use std::sync::Arc;

pub async fn post_db_webhook<'a>(
    Extension(app_state): Extension<Arc<AppState>>,
    Json(body): Json<DbWebhookBody<'a>>,
) -> Result<Json<DbWebhookResponse>, YourErrorType> {
    // 业务逻辑处理
}

3. 根据事件类型反序列化RawValue #

在match分支中，使用RawValue::parse方法将原始JSON数据反序列化为目标结构体：

#[derive(Debug, Deserialize)]
pub struct SignupData {
    // 根据实际需求定义字段
    user_id: String,
    email: String,
}

pub async fn post_db_webhook<'a>(
    Extension(app_state): Extension<Arc<AppState>>,
    Json(body): Json<DbWebhookBody<'a>>,
) -> Result<Json<DbWebhookResponse>, anyhow::Error> {
    match body.event {
        DbWebhookEvent::SignUpCompleted => {
            let signup_data = body.data.parse::<SignupData>()?;
            signup_completed(app_state, signup_data).await?;
        }
    }
    Ok(Json(DbWebhookResponse { ok: true }))
}

4. 路由注册与错误处理 #

路由注册不需要特殊处理，正常配置即可：

use axum::Router;

pub fn create_routes() -> Router {
    Router::new().route("/webhook/db", axum::routing::post(post_db_webhook))
}

注意：确保你的错误类型实现了IntoResponse（比如使用anyhow配合axum::response::IntoResponse），或者自定义符合Axum要求的错误类型。

替代方案：使用OwnedValue避免生命周期 #

如果不想处理生命周期，可以用serde_json::Value代替RawValue，它拥有数据所有权，无需生命周期标注：

#[derive(Debug, Deserialize)]
pub struct DbWebhookBody {
    event: DbWebhookEvent,
    data: serde_json::Value,
}

// 反序列化时：
let signup_data = serde_json::from_value::<SignupData>(body.data)?;

这种方式更简单，但会多一次JSON解析（从原始字符串到Value，再到目标结构体），性能略低于RawValue。

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