#Inizio Rapido

#Installare Rust

Se non hai ancora installato Rust, puoi utilizzare rustup fornito ufficialmente per installarlo.

#Scrivere il Primo Programma con Salvo

Crea un nuovo progetto:

cargo new hello --bin

Aggiungi le dipendenze al file Cargo.toml

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

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

Nel file main.rs, crea un semplice gestore di funzione chiamato hello, che si limita a stampare il testo "Hello world".

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;
}

Congratulazioni, hai completato il tuo primo programma con Salvo. Basta eseguire cargo run dalla riga di comando e aprire http://127.0.0.1:5800 nel browser.

#Analisi Dettagliata

Qui hello_world è un Handler, utilizzato per elaborare le richieste degli utenti. #[handler] permette a una funzione di implementare facilmente il tratto Handler. Inoltre, consente di abbreviare i parametri della funzione in modi diversi.

• Forma originale:

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

• Puoi omettere i parametri non utilizzati, come _req, _depot, _ctrl in questo caso:

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

• Qualsiasi tipo può essere restituito dalla funzione, purché implementi il tratto Writer. Ad esempio, &str implementa Writer, quindi quando viene restituito, stampa testo semplice:

  #[handler]
  async fn hello(res: &mut Response) -> &'static str {
      "Hello world"
  }

• Più comunemente, potremmo voler restituire un Result<T, E> per gestire gli errori durante l'esecuzione della funzione. Se sia T che E implementano Writer, allora Result<T, E> può essere utilizzato come tipo di ritorno:

  #[handler]
  async fn hello(res: &mut Response) -> Result<&'static str, ()> {
      Ok("Hello world")
  }

#L'Agile HTTP3

Si dice che HTTP3 sia leggero come una piuma, molti programmatori lo desiderano ma non riescono a ottenerlo. Questa volta, Salvo ti aiuta a realizzare il desiderio, permettendoti di godere facilmente dei meravigliosi servizi offerti da HTTP3!

Prima abilita la funzionalità HTTP3 nel file Cargo.toml, poi modifica main.rs come segue:

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;
}

#Strumento CLI di Salvo 🛠️

Salvo CLI è uno strumento progettato per il framework web Salvo, in grado di generare codice pulito e leggibile, risparmiandoti tempo per le cose più interessanti della vita.

Se hai idee per migliorare la CLI o hai riscontrato problemi, non esitare! Apri una issue, le tue opinioni sono benvenute.

cargo install salvo-cli

Con questo semplice strumento CLI puoi avviare rapidamente un progetto Salvo, concentrandoti sulla logica di business anziché sulla configurazione del progetto. ✨

#Altri Esempi

Si consiglia di clonare direttamente il repository di Salvo e poi eseguire gli esempi nella directory examples. Ad esempio, il seguente comando esegue l'esempio hello:

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

Nella directory examples ci sono molti esempi. Tutti possono essere eseguiti con comandi simili a cargo run --bin example-<nome>.