Utoipa与Axum集成时路由注册报签名不匹配错误求助

在结合Axum与Utoipa框架开发接口时，注册路由遇到编译错误，提示Handler trait未实现。以下是相关代码、错误信息及排查解决方法：

相关实现代码 #

#[utoipa::path(
  post,
  path = "/machines/{id}/state",
  summary = "Set state of machine",
  params(
      ("id" = String, description = "Machine ID"),
  ),
  request_body = MachineState,
  responses(
      (status = StatusCode::OK),
      (status = StatusCode::BAD_REQUEST),
      (status = StatusCode::UNAUTHORIZED, response = crate::rest::authentication::responses::Unauthorized),
      (status = StatusCode::FORBIDDEN),
      (status = StatusCode::NOT_FOUND),
  ),
)]
async fn set_state(
  State(ctx): State<Arc<MachineContext>>,
  Path(_id): Path<String>,
  state: MachineState,
) -> impl IntoResponse {
  let resource = ctx.resources.get_by_id(_id.as_str());
  if resource.is_none() {
    return (StatusCode::NOT_FOUND).into_response();
  }
  let resource = resource.unwrap();
  let parent = info_span!("list_machines");
  let uid = "123";
  let session = ctx.sessionmanager.try_open(&parent, uid);
  if session.is_none() {
    return (StatusCode::NOT_FOUND).into_response();
  }

  let session = session.unwrap();
  if !resource.visible(&session) {
    return (StatusCode::FORBIDDEN).into_response()
  }

  let state = match state {
    MachineState::Blocked => Status::Blocked(session.get_user_ref()),
    MachineState::Disabled => Status::Disabled,
    MachineState::Free => Status::Free,
    MachineState::InUse => Status::InUse(session.get_user_ref()),
    MachineState::Reserved => Status::Reserved(session.get_user_ref()),
    MachineState::ToCheck => Status::ToCheck(session.get_user_ref()),
  };
  resource
    .try_update(session.clone(), state)
    .await;
  (StatusCode::OK).into_response()
}

pub fn router(sessionmanager: &SessionManager, ressources: &ResourcesHandle) -> OpenApiRouter {
    let ctx = Arc::new(MachineContext {
        resources: ressources.clone(),
        sessionmanager: sessionmanager.clone(),
    });
    OpenApiRouter::new()
        .routes(routes!(
            set_state,
        ))
        .with_state(ctx)
}

编译错误信息 #

error[E0277]: the trait bound `fn(axum::extract::State<Arc<MachineContext>>, axum::extract::Path<std::string::String>, resource::MachineState) -> impl futures_util::Future<Output = impl IntoResponse> {set_state}: Handler<_, Arc<MachineContext>>` is not satisfied
   --> bffhd/rest/resource.rs:448:17
    |
448 |           .routes(routes!(
    |  _________________^
449 | |             register_machine,
450 | |             unregister_machine,
451 | |             get_machine,
...   |
454 | |             get_reservations,
455 | |         ))
    | |         ^
    | |         |
    | |_________the trait `Handler<_, Arc<MachineContext>>` is not implemented for fn item `fn(State<Arc<MachineContext>>, Path<String>, MachineState) -> impl Future<Output = ...> {set_state}`
    |           required by a bound introduced by this call
    |
    = note: the full name for the type has been written to '/user/bffh/target/debug/deps/difluoroborane-7eaf12a346b5233d.long-type-6479587143606823754.txt'
    = note: consider using `--verbose` to print the full type name to the console
    = note: Consider using `#[axum::debug_handler]` to improve the error message
    = help: the following other types implement trait `Handler<T, S>`:
              <MethodRouter<S> as Handler<(), S>>
              <axum::handler::Layered<L, H, T, S> as Handler<T, S>>
note: required by a bound in `MethodRouter::<S>::on`
   --> /user/.cargo/registry/src/index.crates.io-6f17d22bba15001f/axum-0.8.1/src/routing/method_routing.rs:632:12
    |
630 |     pub fn on<H, T>(self, filter: MethodFilter, handler: H) -> Self
    |            -- required by a bound in this associated function
631 |     where
632 |         H: Handler<T, S>,
    |            ^^^^^^^^^^^^^ required by this bound in `MethodRouter::<S>::on`
    = note: this error originates in the macro `$crate::routes` which comes from the expansion of the macro `routes` (in Nightly builds, run with -Z macro-backtrace for more info)

排查与解决方法 #

问题根源 #

Axum的Handler trait要求函数参数必须是Axum支持的**提取器（Extractor）**类型。当前set_state的第三个参数MachineState没有用提取器包裹，Axum无法自动将请求体解析为该类型，导致trait bound不满足。

修复步骤 #

1. 添加请求体提取器
   修改set_state的参数，将state: MachineState替换为Json(state): Json<MachineState>，同时导入axum::Json：

   use axum::Json;
   
   async fn set_state(
     State(ctx): State<Arc<MachineContext>>,
     Path(_id): Path<String>,
     Json(state): Json<MachineState>,
   ) -> impl IntoResponse {
       // 原有逻辑不变
   }
   

2. 确保MachineState实现反序列化
   由于Json提取器依赖Serde来解析请求体，需要给MachineState添加#[derive(Deserialize)]宏（需确保Cargo.toml中包含serde依赖并启用derive特性）：

   use serde::Deserialize;
   
   #[derive(Deserialize)]
   enum MachineState {
       Blocked,
       Disabled,
       Free,
       InUse,
       Reserved,
       ToCheck,
   }
   

   Cargo.toml依赖配置：

   serde = { version = "1.0", features = ["derive"] }
   

3. 验证Utoipa配置
   原有的request_body = MachineState配置无需修改，Utoipa会自动识别Json提取器对应的请求体类型，生成正确的OpenAPI文档。

额外调试建议 #

给set_state函数添加#[axum::debug_handler]宏，编译时会输出更详细的参数匹配错误，便于快速定位问题：

#[axum::debug_handler]
#[utoipa::path(...)]
async fn set_state(...) -> impl IntoResponse {
    // ...
}

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