#[handler] async fn hello() -> &'static str { "Hello World" }

#[tokio::main] async fn main() { let router = Router::new().get(hello); let acceptor = TcpListener::new("0.0.0.0:8080").bind().await; Server::new(acceptor).serve(router).await; }


## Handlers

The `#[handler]` macro turns an async function into a `Handler`. All parameters are optional and order-independent:

- `req: &mut Request` — HTTP request
- `res: &mut Response` — HTTP response
- `depot: &mut Depot` — request-scoped storage
- `ctrl: &mut FlowCtrl` — middleware flow control

A handler can return any type implementing `Writer` or `Scribe` (including `()`, `&'static str`, `String`, `Json<T>`, `StatusCode`, `Result<T, E>`), or write directly via `res.render(...)`.

## Response types

```rust
use salvo::prelude::*;
use salvo::writing::Text;
use serde::Serialize;

#[derive(Serialize)]
struct User { name: String, age: u8 }

#[handler]
async fn json_body() -> Json<User> {
    Json(User { name: "Alice".into(), age: 30 })
}

#[handler]
async fn html_body() -> Text<&'static str> {
    Text::Html("<h1>Hello</h1>")
}

#[handler]
async fn no_content() -> StatusCode {
    StatusCode::NO_CONTENT
}

#[handler]
async fn go_elsewhere(res: &mut Response) {
    res.render(Redirect::found("https://example.com"));
}

HTML rendering uses Text::Html(...) (also Text::Plain, Text::Json, Text::Xml, Text::Css). There is no salvo::writing::Html type.

Error handling

Return Result<T, E> where E: Writer. StatusError is the canonical error type:

#[handler]
async fn may_fail() -> Result<Json<User>, StatusError> {
    let user = fetch_user().await
        .map_err(|e| StatusError::internal_server_error().cause(e))?;
    Ok(Json(user))
}

Available constructors: bad_request(), unauthorized(), forbidden(), not_found(), internal_server_error(), etc. Chain .brief(...), .detail(...), .cause(...) for context.

Request access

#[handler]
async fn inspect(req: &mut Request) -> String {
    let method = req.method();
    let path = req.uri().path();
    let ct: Option<String> = req.header("Content-Type");
    let name: Option<String> = req.query("name");      // ?name=...
    let id: Option<i64> = req.param("id");             // /{id}
    let body: MyData = req.parse_json().await.unwrap(); // JSON body
    format!("{method} {path}")
}

header, query, and param are generic over T: Deserialize and return Option<T>. parse_json returns Result.

Response mutation

#[handler]
async fn created(res: &mut Response) {
    res.status_code(StatusCode::CREATED);
    res.headers_mut().insert("X-Custom", "value".parse().unwrap());
    res.render(Json(serde_json::json!({"ok": true})));
}

Related Skills

salvo-routing: Advanced routing configuration and path parameters
salvo-middleware: Add middleware for logging, auth, and CORS
salvo-error-handling: Graceful error handling patterns

salvo-basic-app

Salvo Basic Application Setup

Dependencies

Minimal server