快速開始

安裝 Rust

若您尚未安裝 Rust，可使用官方提供的 rustup 進行安裝。

Rust 官方教學詳細介紹如何安裝 Rust

TIP

當前 Salvo 支援的最低 Rust 版本為 1.85。執行 rustup update確認您的 Rust 版本符合要求。

編寫第一個 Salvo 程式

建立全新專案：

cargo new hello --bin

將相依項目加入 Cargo.toml

hello/Cargo.toml

[package]
name = "example-hello"
version = "0.1.0"
edition = "2024"

[dependencies]
salvo = { version = "0.77.1" }
tokio = { version = "1", features = ["macros"] }
tracing = "0.1"
tracing-subscriber = "0.3"

在 main.rs 中建立一個簡單的函式處理器，命名為 hello，此函式僅會印出文字 "Hello world"。

hello/src/main.rs

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 5800
    let acceptor = TcpListener::new("0.0.0.0:5800").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;
}

恭喜您，您的第一個 Salvo 程式已完成。只需在命令列執行 cargo run，然後在瀏覽器開啟 http://127.0.0.1:5800 即可。

詳細解讀

此處的 hello_world 是一個 Handler，用於處理使用者請求。#[handler] 巨集可讓函式方便實作 Handler trait，並允許我們以不同方式簡化函式參數。

原始形式：

#[handler]
async fn hello(_req: &mut Request, _depot: &mut Depot, res: &mut Response, _ctrl: &mut FlowCtrl) {
    res.render("Hello world");
}

可省略未使用的參數，如本例中的 _req、_depot、_ctrl 皆可略去不寫：

#[handler]
async fn hello(res: &mut Response) {
    res.render("Hello world");
}

任何實作 Writer trait 的型別皆可作為函式回傳值。例如 &str 實作了 Writer，當其作為回傳值時會輸出純文字：
```
#[handler]
async fn hello(res: &mut Response) -> &'static str {
    "Hello world"
}
```
更常見的情況是使用 Result<T, E> 作為回傳型別以處理函式執行中的錯誤。若 T 和 E 皆實作 Writer，則 Result<T, E> 可作為回傳值：
```
#[handler]
async fn hello(res: &mut Response) -> Result<&'static str, ()> {
    Ok("Hello world")
}
```

風騷的 HTTP3

傳聞 HTTP3 身輕如燕，令無數程式設計師心嚮往之。如今 Salvo 助您圓夢，輕鬆享受 HTTP3 帶來的絕妙服務！

首先在 Cargo.toml 中啟用 HTTP3 功能，然後將 main.rs 修改如下：

main.rs

Cargo.toml

hello-h3/src/main.rs

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

// Handler function responding with "Hello World" for HTTP/3 requests
#[handler]
async fn hello() -> &'static str {
  "Hello World"
}

#[tokio::main]
async fn main() {
  // Initialize 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 router with single 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 TCP listener with TLS encryption on port 5800
  let listener = TcpListener::new(("0.0.0.0", 5800)).rustls(config.clone());

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

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

Salvo CLI 工具 🛠️

Salvo CLI 是專為 Salvo web 框架設計的工具，能建立整潔易讀的程式碼，讓您省下時間享受生活樂趣。

若有改進 CLI 的想法或發現問題，請不吝提出 issue，我們歡迎您的寶貴意見。

第 1 步

安裝 CLI 工具：

cargo install salvo-cli

第 2 步

建立新 Salvo 專案，使用 new 指令後接專案名稱：
salvo new project_name

透過這個簡潔的 CLI 工具，您能快速啟動 Salvo 專案，專注於業務邏輯實現而非專案結構搭建。✨

#快速開始

#安裝 Rust

#編寫第一個 Salvo 程式

#詳細解讀

#風騷的 HTTP3

#Salvo CLI 工具 🛠️

#第 1 步

#第 2 步

#更多範例