Быстрый старт
Установка Rust
Если у вас ещё не установлен Rust, вы можете использовать официальный инструмент rustup
для его установки.
TIP
Текущая минимальная поддерживаемая версия Rust для Salvo — 1.85. Выполните rustup update
, чтобы убедиться, что у вас установлена подходящая версия.
Создание первой программы на Salvo
Создайте новый проект:
Добавьте зависимости в 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
. Кроме того, он позволяет сокращённо записывать параметры функции разными способами.
-
Исходная форма:
#[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
следующим образом:
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. Он помогает создавать чистый и читаемый код, экономя ваше время для более интересных занятий.
Если у вас есть идеи по улучшению CLI или вы обнаружили проблему, не стесняйтесь! Создайте issue — мы ценим ваше мнение.
Шаг 1
Установите CLI-инструмент:
Шаг 2
Создайте новый проект Salvo, используя команду new
с указанием имени проекта:
Этот простой 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-<имя>
.