Salvo

https://salvo.rs/
Admin
Salvo is a simple yet powerful Rust web framework featuring an innovative routing system, built-in...
Tokens:77,488
Snippets:722
Trust Score:6.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Sqlx ORM Setup and Usage

Source: https://salvo.rs/guide/topics/working-with-database

Shows how to set up a Sqlx connection pool for PostgreSQL and use it within a Salvo handler to fetch user data. This example includes defining a User model and configuring the application's main function to start the server.

```rust
use std::sync::OnceLock;

use salvo::prelude::*;
use serde::Serialize;
use sqlx::{FromRow, PgPool};

// Global PostgreSQL connection pool instance
static POSTGRES: OnceLock<PgPool> = OnceLock::new();

// Helper function to get the PostgreSQL connection pool
#[inline]
pub fn get_postgres() -> &'static PgPool {
    POSTGRES.get().unwrap()
}

// User model representing the database table structure
// Implements FromRow for SQL query results and Serialize for JSON responses
#[derive(FromRow, Serialize, Debug)]
pub struct User {
    pub id: i64,
    pub username: String,
    pub password: String,
}

// Handler for retrieving a user by ID from the database
#[handler]
pub async fn get_user(req: &mut Request, res: &mut Response) {
    // Extract user ID from query parameters
    let uid = req.query::<i64>("uid").unwrap();
    // Execute SQL query to fetch user by ID
    let data = sqlx::query_as::<_, User>("select * from users where id = $1")
        .bind(uid)
        .fetch_one(get_postgres())
        .await
        .unwrap();
    // Return user data as JSON response
    res.render(serde_json::to_string(&data).unwrap());
}

#[tokio::main]
async fn main() {
    // Initialize logging system
    tracing_subscriber::fmt().init();

    // Configure PostgreSQL connection
    let postgres_uri = "postgres://postgres:password@localhost/test";
    // Create and initialize connection pool
    let pool = PgPool::connect(postgres_uri).await.unwrap();
    // Store pool in global state
    POSTGRES.set(pool).unwrap();

    // Configure router with user endpoint:
    // - GET /users?uid={id} : Get user by ID
    let router = Router::with_path("users").get(get_user);

    // Start server on port 8698
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}
```

--------------------------------

### Simple Reverse Proxy Setup

Source: https://salvo.rs/guide/features/proxy

Set up a reverse proxy that forwards requests to different backends based on the host. This example uses docs.rs for '127.0.0.1' and crates.io for 'localhost'.

```rust
use salvo::prelude::*;

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().init();

    // In this example, if the requested URL begins with <http://127.0.0.1:8698/>, the proxy goes to
    // <https://www.rust-lang.org>; if the requested URL begins with <http://localhost:8698/>, the proxy
    // goes to <https://crates.io>.
    let router = Router::new()
        .push(
            Router::new()
                .host("127.0.0.1")
                .path("{**rest}")
                .goal(Proxy::use_hyper_client("https://docs.rs")),
        )
        .push(
            Router::new()
                .host("localhost")
                .path("{**rest}")
                .goal(Proxy::use_hyper_client("https://crates.io")),
        );

    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}

```

--------------------------------

### Basic Logging Setup in Salvo

Source: https://salvo.rs/guide/features/logging

This example demonstrates how to initialize the tracing subscriber and add the Logger middleware to a Salvo Service. It includes handlers for a basic 'Hello World' response and a 'Bad Request' error.

```rust
use salvo::logging::Logger;
use salvo::prelude::*;

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

#[handler]
async fn error() -> StatusError {
    StatusError::bad_request()
        .brief("Bad request error")
        .detail("The request was malformed.")
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().init();

    let router = Router::new()
        .get(hello)
        .push(Router::with_path("error").get(error));
    let service = Service::new(router).hoop(Logger::new());

    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(service).await;

```

--------------------------------

### Run Salvo Examples from Repository

Source: https://salvo.rs/guide/quick-start

These commands demonstrate how to clone the Salvo repository, navigate to the examples directory, and run a specific example like 'example-hello' using Cargo. This is useful for exploring Salvo's features.

```sh
git clone https://github.com/salvo-rs/salvo
cd salvo/examples
cargo run --bin example-hello

```

--------------------------------

### Test Salvo Application

Source: https://salvo.rs/guide/topics/testing

This example demonstrates how to test a simple Salvo application with a 'Hello World' handler. It sets up a service, sends a GET request, and asserts the response content.

```rust
use salvo::prelude::*;

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

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().init();

    tracing::info!("Listening on http://127.0.0.1:8698");
    let acceptor = TcpListener::new("127.0.0.1:8698").bind().await;
    Server::new(acceptor).serve(route()).await;
}

fn route() -> Router {
    Router::new().get(hello_world)
}

#[cfg(test)]
mod tests {
    use salvo::prelude::*;
    use salvo::test::{ResponseExt, TestClient};

    #[tokio::test]
    async fn test_hello_world() {
        let service = Service::new(super::route());

        let content = TestClient::get(format!("http://127.0.0.1:8698/"))
            .send(&service)
            .await
            .take_string()
            .await
            .unwrap();
        assert_eq!(content, "Hello World");
    }
}
```

--------------------------------

### Rust Craft Feature Example

Source: https://salvo.rs/guide/features/craft

This Rust code demonstrates how to use the `craft` macro to generate API handlers. It defines an `Opts` struct with methods for adding values, showcasing instance-based, Arc-wrapped instance-based, and static endpoint implementations. The example also configures the router, OpenAPI documentation, and starts the server.

```rust
use salvo::oapi::extract::*;
use salvo::prelude::*;
use std::sync::Arc;

// Options struct holding a state value for calculations
#[derive(Clone)]
pub struct Opts {
    state: i64,
}

// Implement methods for Opts using the craft macro for API generation
#[craft]
impl Opts {
    // Constructor for Opts
    fn new(state: i64) -> Self {
        Self { state }
    }

    // Handler method that adds state value to two query parameters
    #[craft(handler)]
    fn add1(&self, left: QueryParam<i64>, right: QueryParam<i64>) -> String {
        (self.state + *left + *right).to_string()
    }

    // Endpoint method using Arc for shared state
    #[craft(endpoint)]
    pub(crate) fn add2(
        self: ::std::sync::Arc<Self>,
        left: QueryParam<i64>,
        right: QueryParam<i64>,
    ) -> String {
        (self.state + *left + *right).to_string()
    }

    // Static endpoint method with custom error response
    #[craft(endpoint(responses((status_code = 400, description = "Wrong request parameters."))))]
    pub fn add3(left: QueryParam<i64>, right: QueryParam<i64>) -> String {
        (*left + *right).to_string()
    }
}

#[tokio::main]
async fn main() {
    // Create shared state with initial value 1
    let opts = Arc::new(Opts::new(1));

    // Configure router with three endpoints:
    // - /add1: Uses instance method with state
    // - /add2: Uses Arc-wrapped instance method
    // - /add3: Uses static method without state
    let router = Router::new()
        .push(Router::with_path("add1").get(opts.add1()))
        .push(Router::with_path("add2").get(opts.add2()))
        .push(Router::with_path("add3").get(Opts::add3()));

    // Generate OpenAPI documentation
    let doc = OpenApi::new("Example API", "0.0.1").merge_router(&router);

    // Add OpenAPI documentation and Swagger UI routes
    let router = router
        .push(doc.into_router("/api-doc/openapi.json"))
        .push(SwaggerUi::new("/api-doc/openapi.json").into_router("swagger-ui"));

    // Start server on localhost:8698
    let acceptor = TcpListener::new("127.0.0.1:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}

```

--------------------------------

### Setting OpenAPI Schema Example

Source: https://salvo.rs/guide/features/openapi

Use the `#[salvo(schema(example = json!(...)))]` attribute to provide an example value for a schema. The `json!(...)` macro from `serde_json` is used to define the example as a `serde_json::Value`.

```rust
use salvo_oapi::ToSchema;

#[derive(ToSchema)]
#[salvo(schema(example = json!({"name": "bob the cat", "id": 0})))]
struct Pet {
    id: u64,
    name: String,
}
```

--------------------------------

### Cargo.toml Dependencies for Depot Example

Source: https://salvo.rs/guide/concepts/depot

Specifies the necessary dependencies for the Salvo Depot example, including Salvo, Tokio, and tracing.

```toml
[package]
name = "example-use-depot"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### HTTP/3 Server Example

Source: https://salvo.rs/guide/features/hello-h3

This example demonstrates a simple HTTP/3 server that also supports HTTPS (TCP) by combining QUIC and TCP listeners. It requires valid TLS certificates and keys.

```rust
use salvo::conn::rustls::{Keycert, RustlsConfig};
use salvo::prelude::*;

// Handler function that responds with "Hello World"
#[handler]
async fn hello() -> &'static str {
    "Hello World"
}

#[tokio::main]
async fn main() {
    // Initialize the logging system
    tracing_subscriber::fmt().init();

    // Load TLS certificate and private key from embedded PEM files
    let cert = include_bytes!("../certs/cert.pem").to_vec();
    let key = include_bytes!("../certs/key.pem").to_vec();

    // Create a router and add an endpoint
    let router = Router::new().get(hello);

    // Configure TLS settings using Rustls
    let config = RustlsConfig::new(Keycert::new().cert(cert.as_slice()).key(key.as_slice()));

    // Create a TLS-encrypted TCP listener on port 8698
    let listener = TcpListener::new(("0.0.0.0", 8698)).rustls(config.clone());

    // Create a QUIC listener and combine it with the TCP listener
    let acceptor = QuinnListener::new(config.build_quinn_config().unwrap(), ("0.0.0.0", 8698))
        .join(listener)
        .bind()
        .await;

    // Start the server supporting both HTTP/3 (QUIC) and HTTPS (TCP)
    Server::new(acceptor).serve(router).await;
}
```

--------------------------------

### RBatis Setup and User Handler with MySQL

Source: https://salvo.rs/guide/topics/working-with-database

Demonstrates the setup of a global RBatis instance, a User model, a custom select query, and a request handler for retrieving users by ID using rbatis and MySQL. Requires database connection configuration.

```rust
#[macro_use]
extern crate rbatis;
extern crate rbdc;

use std::sync::LazyLock;

use rbatis::RBatis;
use rbdc_mysql::driver::MysqlDriver;
use salvo::prelude::*;
use serde::{Deserialize, Serialize};

// Global RBatis instance for database operations
pub static RB: LazyLock<RBatis> = LazyLock::new(RBatis::new);

// User model representing the database table structure
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct User {
    pub id: i64,
    pub username: String,
    pub password: String,
}

// Implement select query for User model
// Generates SQL: SELECT * FROM user WHERE id = #{id} LIMIT 1
impl_select!(User{select_by_id(id:String) -> Option => "`where id = #{id} limit 1`"});

// Handler for retrieving a user by ID from the database
#[handler]
pub async fn get_user(req: &mut Request, res: &mut Response) {
    // Extract user ID from query parameters
    let uid = req.query::<i64>("uid").unwrap();
    // Execute select query and get user data
    let data = User::select_by_id(&*RB, uid.to_string()).await.unwrap();
    println!("{data:?}");
    // Return user data as JSON response
    res.render(serde_json::to_string(&data).unwrap());
}

#[tokio::main]
async fn main() {
    // Initialize logging system
    tracing_subscriber::fmt().init();

    // Configure MySQL connection
    let mysql_uri = "mysql://root:123456@localhost/test";
    // Initialize RBatis with MySQL driver and connection URI
    RB.init(MysqlDriver {}, mysql_uri).unwrap();

    // Configure router with user endpoint:
    // - GET /users?uid={id} : Get user by ID
    let router = Router::with_path("users").get(get_user);

    // Start server on port 8698
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}
```

--------------------------------

### Setup JWT Authentication Middleware

Source: https://salvo.rs/guide/features/jwt-auth

Configure the JwtAuth middleware with a secret key and specify how tokens should be found (e.g., query parameters). This example forces token validation.

```rust
use jsonwebtoken::{self, EncodingKey};
use salvo::http::{Method, StatusError};
use salvo::jwt_auth::{ConstDecoder, QueryFinder};
use salvo::prelude::*;
use serde::{Deserialize, Serialize};
use time::{Duration, OffsetDateTime};

const SECRET_KEY: &str = "YOUR SECRET_KEY";

#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct JwtClaims {
    username: String,
    exp: i64,
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().init();

    let auth_handler: JwtAuth<JwtClaims, _> = 
        JwtAuth::new(ConstDecoder::from_secret(SECRET_KEY.as_bytes()))
            .finders(vec![
                // Box::new(HeaderFinder::new()),
                Box::new(QueryFinder::new("jwt_token")),
                // Box::new(CookieFinder::new("jwt_token")),
            ])
            .force_passed(true);

    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor)
        .serve(Router::with_hoop(auth_handler).goal(index))
        .await;
}
```

--------------------------------

### Proxy Example Dependencies

Source: https://salvo.rs/guide/features/proxy

Defines the project dependencies for a Salvo reverse proxy example, including Salvo with the 'proxy' feature, tokio, and tracing.

```toml
[package]
name = "example-proxy-simple"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["proxy"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### WebTransport Example in Salvo

Source: https://salvo.rs/guide/features

Implement WebTransport for low-latency, bidirectional communication. This example shows the basic setup for using WebTransport with Salvo.

```rust
use salvo::prelude::*;

#[tokio::main]
async fn main() {
    let app = Service::new()
        .push(Router::new().get("/webtransport", webtransport_handler));
    Server::new(TcpListener::bind("127.0.0.1:3000")).serve(app).await;
}

async fn webtransport_handler(req: &mut Request) -> Result<Response, salvo::Error> {
    let wt = WebTransport::new(req).await?;
    // Handle WebTransport connection
    Ok(Response::new("WebTransport connection established"))
}
```

--------------------------------

### Combine Router Filters

Source: https://salvo.rs/guide/concepts/router

Connects router filters using logical AND to create more specific matching rules. This example matches requests to 'hello' with the GET method.

```rust
Router::with_filter(filters::path("hello").and(filters::get()));
```

--------------------------------

### Setup Windsurf AI Skills

Source: https://salvo.rs/guide/topics/ai-skills

Configure Salvo Skills as knowledge context in Windsurf by cloning the repository and copying skills to `.windsurf/skills/`. Configure `.windsurfrules` to reference these files.

```bash
cp -r salvo-skills/skills .windsurf/skills/
```

--------------------------------

### Server-Sent Events (SSE) Example

Source: https://salvo.rs/guide/features

Implement Server-Sent Events (SSE) for real-time communication. This example demonstrates how to send events from the server to the client.

```rust
use salvo::prelude::*;
use futures_util::stream::StreamExt;

#[tokio::main]
async fn main() {
    let app = Service::new()
        .push(Router::new().get("/sse", sse_handler));
    Server::new(TcpListener::bind("127.0.0.1:3000")).serve(app).await;
}

async fn sse_handler() -> SseStream {
    let mut stream = SseStream::new();
    tokio::spawn(async move {
        let mut interval = tokio::time::interval(std::time::Duration::from_secs(1));
        while let Some(_) = interval.next().await {
            stream.send("Hello SSE").unwrap();
        }
    });
    stream
}
```

--------------------------------

### Full Salvo CORS Example

Source: https://salvo.rs/guide/features/cors

A complete example demonstrating a backend server with CORS enabled and a frontend server serving an HTML page to test CORS requests.

```rust
use salvo::cors::Cors;
use salvo::http::Method;
use salvo::prelude::*;

#[tokio::main]
async fn main() {
    // Initialize logging system
    tracing_subscriber::fmt().init();
    // Start both backend and frontend servers concurrently
    tokio::join!(backend_server(), frontend_server());
}

async fn backend_server() {
    // Handler that returns a simple message for CORS demonstration
    #[handler]
    async fn hello() -> &'static str {
        "hello, I am content from remote server."
    }

    // Configure CORS middleware with specific settings:
    // - Allow requests from localhost:8698
    // - Allow specific HTTP methods
    // - Allow authorization header
    let cors = Cors::new()
        .allow_origin(["http://127.0.0.1:8698", "http://localhost:8698"])
        .allow_methods(vec![Method::GET, Method::POST, Method::DELETE])
        .allow_headers("authorization")
        .into_handler();

    // Set up backend router with CORS protection
    let router = Router::with_path("hello").post(hello);
    let service = Service::new(router).hoop(cors);

    // Start backend server on port 5600
    let acceptor = TcpListener::new("0.0.0.0:5600").bind().await;
    Server::new(acceptor).serve(service).await;
}

async fn frontend_server() {
    // Handler that serves the HTML page with CORS test
    #[handler]
    async fn index() -> Text<&'static str> {
        Text::Html(HTML_DATA)
    }

    // Set up frontend router to serve the test page
    let router = Router::new().get(index);
    // Start frontend server on port 8698
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}

// HTML template with JavaScript code to test CORS
// Contains a button that triggers a POST request to the backend server
const HTML_DATA: &str = r#"<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width">
    <title>Salvo Cors</title>
</head>
<body>
<button id="btn">Load Content</button>
<div id="content"></div>
<script>
document.getElementById("btn").addEventListener("click", function() {
    fetch("http://127.0.0.1:5600/hello", {method: "POST", headers: {authorization: "abcdef"}}).then(function(response) {
        return response.text();
    }).then(function(data) {
        document.getElementById("content").innerHTML = data;
    });
});
</script>
</body>
</html>"#;

```

--------------------------------

### Setup Cursor AI Skills

Source: https://salvo.rs/guide/topics/ai-skills

Add Salvo Skills as documentation context in Cursor by cloning the repository and copying skills to `.cursor/skills/`. Configure `.cursor/rules` to reference these files.

```bash
cp -r salvo-skills/skills .cursor/skills/
```

--------------------------------

### Setup Claude Code Skills

Source: https://salvo.rs/guide/topics/ai-skills

Copy the Salvo Skills into the `.claude/skills/` directory for Claude Code integration. Skills load automatically.

```bash
cp -r salvo-skills/skills .claude/skills/
```

--------------------------------

### Cargo.toml Dependencies for Logging Example

Source: https://salvo.rs/guide/features/logging

This TOML file lists the necessary dependencies for the Salvo logging example, including Salvo itself with the 'logging' feature enabled, tokio for async runtime, and tracing/tracing-subscriber for logging.

```toml
[package]
name = "example-logging"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["logging"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Custom Error Page Example

Source: https://salvo.rs/guide/concepts/catcher

This example demonstrates setting up a Salvo service with custom error handling for 404 Not Found errors. It includes handlers for a basic response and for triggering a 500 error.

```rust
use salvo::catcher::Catcher;
use salvo::prelude::*;

// Handler that returns a simple "Hello World" response
#[handler]
async fn hello() -> &'static str {
    "Hello World"
}

// Handler that deliberately returns a 500 Internal Server Error
#[handler]
async fn error500(res: &mut Response) {
    res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
}

#[tokio::main]
async fn main() {
    // Initialize logging system
    tracing_subscriber::fmt().init();

    // Create and start server with custom error handling
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(create_service()).await;
}

// Create service with custom error handling
fn create_service() -> Service {
    // Set up router with two endpoints:
    // - / : Returns "Hello World"
    // - /500 : Triggers a 500 error
    let router = Router::new()
        .get(hello)
        .push(Router::with_path("500").get(error500));

    // Add custom error catcher for 404 Not Found errors
    Service::new(router).catcher(Catcher::default().hoop(handle404))
}

// Custom handler for 404 Not Found errors
#[handler]
async fn handle404(&self, _req: &Request, _depot: &Depot, res: &mut Response, ctrl: &mut FlowCtrl) {
    // Check if the error is a 404 Not Found
    if StatusCode::NOT_FOUND == res.status_code.unwrap_or(StatusCode::NOT_FOUND) {
        // Return custom error page
        res.render("Custom 404 Error Page");
        // Skip remaining error handlers
        ctrl.skip_rest();
    }
}
```

--------------------------------

### Cargo.toml for WebSocket Chat Example

Source: https://salvo.rs/guide/features/websocket

Defines the project metadata and dependencies for the WebSocket chat example, including Salvo and Tokio.

```toml
[package]
name = "example-websocket-chat"

```

--------------------------------

### Gin Recovery Middleware Example (Go)

Source: https://salvo.rs/guide/features/catch-panic

Shows how the Gin framework in Go handles panics using its built-in Recovery middleware, which is included by default with `gin.Default()`.

```go
package main

import (
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default() // Includes the Recovery middleware by default
    
    r.GET("/", func(c *gin.Context) {
        panic("panic error!")
    })
    
    r.Run(":8080")
}
```

--------------------------------

### Cargo.toml Dependencies for Cache Example

Source: https://salvo.rs/guide/features/cache

Specifies the necessary dependencies for the Salvo cache example, including Salvo itself with the 'cache' feature enabled.

```toml
[package]
name = "example-cache-simple"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["cache"] }
tokio = { workspace = true, features = ["macros"] }
time.workspace = true
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Make a GET Request with Reqwest

Source: https://salvo.rs/guide/ecology/reqwest

Use the `get` convenience method for single requests. For multiple requests, create a `Client` to leverage connection pooling.

```rust
let body = reqwest::get("https://www.rust-lang.org")
    .await?;
    .text()
    .await?;

println!("body = {body:?}");
```

```rust
let client = reqwest::Client::new();
let res = client.get("https://www.rust-lang.org")
    .send()
    .await?;
```

--------------------------------

### Setup GitHub Copilot Skills

Source: https://salvo.rs/guide/topics/ai-skills

Copy the Salvo Skills into the `.github/skills/` directory for GitHub Copilot integration. Enable agent skills in VS Code settings.

```bash
cp -r salvo-skills/skills .github/skills/
```

--------------------------------

### Insert and Get String Data in Depot

Source: https://salvo.rs/guide/concepts/depot

Shows basic usage of `insert` to store a string value with a key and `get` to retrieve it, asserting the correct value is obtained.

```rust
depot.insert("a", "b");
assert_eq!(depot.get::<&str>("a").copied().unwrap(), "b")
```

--------------------------------

### Controller Design Example

Source: https://salvo.rs/guide/concepts/router

Illustrates a typical controller design in Java where methods are annotated to handle specific HTTP requests for a resource.

```java
@Controller
public class ArticleController {
    @GetMapping("/articles")
    public List<Article> listArticles() { /* ... */ } 
    
    @PostMapping("/articles")
    public Article createArticle(@RequestBody Article article) { /* ... */ }
}
```

--------------------------------

### Cargo.toml Dependencies for Trailing Slash Example

Source: https://salvo.rs/guide/features/trailing-slash

This TOML file lists the necessary dependencies for the trailing slash example, including Salvo with the 'trailing-slash' feature enabled, and Tokio for asynchronous operations.

```toml
[package]
name = "example-trailing-slash"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["trailing-slash"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Cargo.toml Dependencies for RBatis Example

Source: https://salvo.rs/guide/topics/working-with-database

Lists the necessary dependencies for a Salvo application using rbatis with MySQL, including rbatis, rbdc-mysql, salvo, and serde.

```toml
[package]
name = "example-db-mysql-rbatis"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
async-std = { workspace = true }
rbatis = { workspace = true }
rbdc = { workspace = true }
rbdc-mysql = { workspace = true }
rbs = { workspace = true }
salvo = { workspace = true }
serde = { workspace = true, features = ["derive"] }
tokio = { workspace = true, features = ["macros"] }
tracing = { workspace = true }
tracing-subscriber = { workspace = true }
serde_json = { workspace = true }

```

--------------------------------

### Organizing Code by API Endpoint

Source: https://salvo.rs/zh-hans/guide/concepts/router.html

This example demonstrates organizing code by API endpoint, with separate functions for user-related and article-related routes. The main application then combines these routers.

```rust
// user_routes.rs - 用户相关路由和处理逻辑
pub fn user_routes() -> Router {
    Router::with_path("users")
        .get(list_users)
        .post(create_user)
        .push(Router::with_path("{id}").get(get_user).delete(delete_user))
}

// article_routes.rs - 文章相关路由和处理逻辑
pub fn article_routes() -> Router {
    Router::with_path("articles")
        .get(list_articles)
        .post(create_article)
}

// 在主应用中组合路由
let router = Router::new()
    .push(user_routes())
    .push(article_routes());
```

--------------------------------

### TOML Configuration: Size Limiter Example

Source: https://salvo.rs/guide/features/size-limiter

Specifies the dependencies for a Rust project using the Salvo framework with the size-limiter feature enabled. Includes necessary crates like tokio and tracing.

```toml
[package]
name = "example-size-limiter"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["size-limiter"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Cargo.toml for SSE Chat Example

Source: https://salvo.rs/guide/features/sse

Defines the project's dependencies, including Salvo with the 'sse' feature enabled, and other necessary crates like parking_lot and futures-util.

```toml
[package]
name = "example-sse-chat"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
futures-util.workspace = true
parking_lot = "0.12"
salvo = { workspace = true, features = ["sse"] }

```

--------------------------------

### Cargo.toml Dependencies for Graceful Shutdown

Source: https://salvo.rs/guide/topics/graceful-shutdown

This TOML file lists the necessary dependencies for the graceful shutdown example, including Salvo and Tokio with signal handling features.

```toml
[package]
name = "example-graceful-shutdown"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true }
tokio = { workspace = true, features = ["macros", "signal"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Basic Request ID Setup

Source: https://salvo.rs/guide/features/request-id

Demonstrates how to add the RequestId middleware to a Salvo application and access the generated ID in a handler. Ensure the `request-id` feature is enabled for the `salvo` crate.

```rust
use salvo::prelude::*;

#[handler]
async fn hello(req: &mut Request) -> String {
    format!("Request id: {:?}", req.header::<String>("x-request-id"))
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().init();

    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    let router = Router::new().hoop(RequestId::new()).get(hello);
    Server::new(acceptor).serve(router).await;
}
```

--------------------------------

### Access Request Parameters

Source: https://salvo.rs/guide/concepts/request

Retrieve parameters from the request, such as path parameters, using the `params()` method. This example shows how to get a parameter named 'id'.

```rust
#[handler]
async fn hello(req: &mut Request) -> String {
    req.params().get("id").cloned().unwrap_or_default()
}
```

--------------------------------

### Configure Compression Middleware

Source: https://salvo.rs/guide/features/compression

Demonstrates setting up the `Compression` middleware with various configurations for different routes. It shows how to force compression priority, enable Brotli, Zstd, and Gzip with specific compression levels, and handle static file serving.

```rust
use salvo::prelude::*;

#[tokio::main]
async fn main() {
    // Initialize logging system
    tracing_subscriber::fmt().init();

    // Print current working directory for debugging
    println!("current_dir: {:?}", std::env::current_dir().unwrap());

    // Set up base directory for static files
    let current_dir = std::env::current_dir().unwrap();
    let base_dir = if !current_dir.to_str().unwrap().ends_with("compression") {
        current_dir
            .join("compression/static")
            .canonicalize()
            .unwrap()
    } else {
        current_dir.join("static").canonicalize().unwrap()
    };
    println!("Base Dir: {:?}", base_dir);

    // Configure router with different compression settings for different paths
    let router = Router::new()
        // WebSocket chat with forced compression priority
        .push(
            Router::with_hoop(Compression::new().force_priority(true))
                .path("ws_chat")
                .get(StaticFile::new(base_dir.join("ws_chat.txt"))),
        )
        // SSE chat with Brotli compression
        .push(
            Router::with_hoop(Compression::new().enable_brotli(CompressionLevel::Fastest))
                .path("sse_chat")
                .get(StaticFile::new(base_dir.join("sse_chat.txt"))),
        )
        // Todos with Zstd compression
        .push(
            Router::with_hoop(Compression::new().enable_zstd(CompressionLevel::Fastest))
                .path("todos")
                .get(StaticFile::new(base_dir.join("todos.txt"))),
        )
        // All other paths with Gzip compression
        .push(
            Router::with_hoop(Compression::new().enable_gzip(CompressionLevel::Fastest))
                .path("{*path}")
                .get(StaticDir::new(base_dir)),
        );

    // Bind server to port 8698 and start serving
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}

```

--------------------------------

### Set up Caching Headers and Compression Middleware

Source: https://salvo.rs/guide/features/caching-headers

Integrate CachingHeaders middleware before Compression to ensure correct cache control headers are set. This example sets up a router with these middlewares and a simple 'Hello World' handler.

```rust
use salvo::prelude::*;

// Handler that returns a simple "Hello World" response
#[handler]
async fn hello() -> &'static str {
    "Hello World"
}

#[tokio::main]
async fn main() {
    // Initialize logging system
    tracing_subscriber::fmt().init();

    // Set up router with caching headers and compression middleware
    // CachingHeader must be before Compression to properly set cache control headers
    let router = Router::with_hoop(CachingHeaders::new())
        .hoop(Compression::new().min_length(0)) // Enable compression for all responses
        .get(hello);

    // Bind server to port 8698 and start serving
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;

```

--------------------------------

### Write a basic Salvo 'Hello World' application

Source: https://salvo.rs/guide/quick-start

This Rust code sets up a simple web server with two endpoints: one for an English greeting and another for a Chinese greeting.

```rust
use salvo::prelude::*;

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

// Handler for Chinese greeting
#[handler]
async fn hello_zh() -> Result<&'static str, ()> {
    Ok("你好，世界！")
}

#[tokio::main]
async fn main() {
    // Initialize logging subsystem
    tracing_subscriber::fmt().init();

    // Bind server to port 8698
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;

    // Create router with two endpoints:
    // - / (root path) returns English greeting
    // - /你好 returns Chinese greeting
    let router = Router::new()
        .get(hello)
        .push(Router::with_path("你好").get(hello_zh));

    // Print router structure for debugging
    println!("{router:?}");

    // Start serving requests
    Server::new(acceptor).serve(router).await;
}

```

--------------------------------

### Static Quota Rate Limiter Example

Source: https://salvo.rs/guide/features/rate-limiter

Demonstrates setting up a rate limiter with a static quota using FixedGuard, MokaStore, RemoteIpIssuer, and BasicQuota. This configuration limits requests to 1 per second per IP address. Ensure the Tokio runtime and tracing subscriber are initialized.

```rust
use salvo::prelude::*;
use salvo::rate_limiter::{BasicQuota, FixedGuard, MokaStore, RateLimiter, RemoteIpIssuer};

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

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().init();

    let limiter = RateLimiter::new(
        FixedGuard::new(),
        MokaStore::new(),
        RemoteIpIssuer,
        BasicQuota::per_second(1),
    );
    let router = Router::with_hoop(limiter).get(hello);
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}
```

```toml
[package]
name = "example-rate-limiter-static"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["rate-limiter"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Project Dependencies for Compression Example

Source: https://salvo.rs/guide/features/compression

Specifies the necessary dependencies for the Salvo web framework, including features for compression and static file serving, along with Tokio for async operations and tracing for logging.

```toml
[package]
name = "example-compression"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["compression", "serve-static"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Blocking GET Request with Reqwest

Source: https://salvo.rs/guide/ecology/reqwest

Perform a blocking GET request and retrieve the response body as text. Requires the `blocking` feature to be enabled.

```rust
let body = reqwest::blocking::get("https://www.rust-lang.org")?.text()?;
```

--------------------------------

### Cargo.toml for CORS example

Source: https://salvo.rs/guide/features/cors

The Cargo.toml file includes the necessary dependencies for the Salvo CORS example, including the `cors` feature for Salvo and `macros` for Tokio.

```toml
[package]
name = "example-cors"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["cors"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Basic Salvo Application with OpenAPI Documentation

Source: https://salvo.rs/guide/features/openapi

This example demonstrates a simple Salvo application with an OpenAPI endpoint. It configures Swagger UI and generates an OpenAPI JSON document. The `#[endpoint]` macro is used for handlers intended for OpenAPI documentation.

```rust
use salvo::oapi::extract::*;
use salvo::prelude::*;

#[endpoint]
async fn hello(name: QueryParam<String, false>) -> String {
    format!("Hello, {}!", name.as_deref().unwrap_or("World"))
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().init();

    let router = Router::new().push(Router::with_path("hello").get(hello));

    let doc = OpenApi::new("test api", "0.0.1").merge_router(&router);

    let router = router
        .unshift(doc.into_router("/api-doc/openapi.json"))
        .unshift(SwaggerUi::new("/api-doc/openapi.json").into_router("/swagger-ui"));

    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}
```

--------------------------------

### Salvo CatchPanic Main Application Setup

Source: https://salvo.rs/guide/features/catch-panic

This Rust code sets up a Salvo web server with the `CatchPanic` middleware. It includes a handler that intentionally panics to demonstrate the middleware's functionality. Logging is also initialized.

```rust
use salvo::prelude::*

// Handler that deliberately panics to demonstrate panic catching
#[handler]
async fn hello() {
    panic!("panic error!");
}

#[tokio::main]
async fn main() {
    // Initialize logging system
    tracing_subscriber::fmt().init();

    // Set up router with CatchPanic middleware to handle panics gracefully
    // This prevents the server from crashing when a panic occurs in a handler
    let router = Router::new().hoop(CatchPanic::new()).get(hello);

    // Bind server to port 8698 and start serving
    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}

```

--------------------------------

### Cargo.toml for Dynamic Rate Limiter Example

Source: https://salvo.rs/guide/features/rate-limiter

Specifies the dependencies required for the dynamic rate limiter example, including Salvo with the rate-limiter feature, and Tokio for asynchronous operations.

```toml
[package]
name = "example-rate-limiter-dynamic"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["rate-limiter"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true

```

--------------------------------

### Rust Example: File Upload Size Limiter

Source: https://salvo.rs/guide/features/size-limiter

Demonstrates how to implement file upload size limiting using Salvo's `max_size` hoop. It shows setting a 10MiB limit for a specific endpoint and an unlimited upload for another.

```rust
use std::fs::create_dir_all;
use std::path::Path;

use salvo::prelude::*;

#[handler]
async fn index(res: &mut Response) {
    res.render(Text::Html(INDEX_HTML));
}
#[handler]
async fn upload(req: &mut Request, res: &mut Response) {
    let file = req.file("file").await;
    if let Some(file) = file {
        let dest = format!("temp/{}", file.name().unwrap_or("file"));
        tracing::debug!(dest, "upload file");
        if let Err(e) = std::fs::copy(file.path(), Path::new(&dest)) {
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
            res.render(Text::Plain(format!("file not found in request: {e}")));
        } else {
            res.render(Text::Plain(format!("File uploaded to {dest}")));
        }
    } else {
        res.status_code(StatusCode::BAD_REQUEST);
        res.render(Text::Plain("file not found in request"));
    }
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt().init();

    create_dir_all("temp").unwrap();
    let router = Router::new()
        .get(index)
        .push(
            Router::new()
                .hoop(max_size(1024 * 1024 * 10))
                .path("limited")
                .post(upload),
        )
        .push(Router::with_path("unlimit").post(upload));

    let acceptor = TcpListener::new("0.0.0.0:8698").bind().await;
    Server::new(acceptor).serve(router).await;
}

static INDEX_HTML: &str = r###"<!DOCTYPE html>
<html>
    <head>
        <title>Upload file</title>
    </head>
    <body>
        <h1>Upload file</h1>
        <form action="/unlimit" method="post" enctype="multipart/form-data">
            <h3>Unlimit</h3>
            <input type="file" name="file" />
            <input type="submit" value="upload" />
        </form>
        <form action="/limited" method="post" enctype="multipart/form-data">
            <h3>Limited 10MiB</h3>
            <input type="file" name="file" />
            <input type="submit" value="upload" />
        </form>
    </body>
</html>
"###;

```

--------------------------------

### Cargo.toml Dependencies for CSRF Example

Source: https://salvo.rs/guide/features/csrf

This TOML file lists the necessary dependencies for a Salvo CSRF example using SessionStore, including Salvo itself with 'csrf' and 'session' features enabled.

```toml
[package]
name = "example-csrf-session-store"
version.workspace = true
edition.workspace = true
publish.workspace = true
rust-version.workspace = true

[dependencies]
salvo = { workspace = true, features = ["csrf", "session"] }
tokio = { workspace = true, features = ["macros"] }
tracing.workspace = true
tracing-subscriber.workspace = true
serde = { workspace = true, features = ["derive"] }

```
Tokens:
Raw