#Быстрый старт

#Установка Rust

Если у вас ещё не установлен Rust, вы можете использовать официальный инструмент rustup для его установки.

#Создание первой программы на Salvo

Создайте новый проект:

cargo new hello --bin

Добавьте зависимости в 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".

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. Кроме того, он позволяет сокращённо записывать параметры функции разными способами.

• Исходная форма:

  #[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. Например, &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!

Сначала включите функцию HTTP3 в Cargo.toml, затем измените 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. Он помогает создавать чистый и читаемый код, экономя ваше время для более интересных занятий.

Если у вас есть идеи по улучшению CLI или вы обнаружили проблему, не стесняйтесь! Создайте issue — мы ценим ваше мнение.

cargo install salvo-cli

Этот простой CLI-инструмент позволяет быстро начать работу с Salvo, сосредоточившись на реализации бизнес-логики вместо настройки структуры проекта. ✨

#Дополнительные примеры

Рекомендуется клонировать репозиторий Salvo и запустить примеры из папки examples. Например, следующая команда запускает пример hello:

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

В папке examples много других примеров. Все они могут быть запущены аналогичной командой cargo run --bin example-<имя>.