Salvo-rs/salvo：SQLx异步查询实战-优快云博客

Salvo-rs/salvo：SQLx异步查询实战

【免费下载链接】salvo 一个真正让你体感舒适的 Rust Web 后端框架项目地址: https://gitcode.com/salvo-rs/salvo

引言：为什么选择Salvo + SQLx？

在现代Web开发中，异步（Asynchronous）编程和高性能数据库操作已成为后端服务的核心需求。Salvo-rs/salvo作为Rust生态中备受瞩目的Web框架，与SQLx这一强大的异步SQL工具库强强联合，为开发者提供了极致的开发体验和卓越的性能表现。

你是否曾遇到过以下痛点？

传统同步数据库操作导致请求阻塞，影响系统吞吐量
ORM（Object-Relational Mapping）框架学习曲线陡峭，配置复杂
需要手动管理数据库连接池，容易引发资源泄漏
缺乏类型安全的SQL查询，运行时错误频发

本文将带你深入探索Salvo与SQLx的完美结合，通过实战案例解决这些痛点，构建高性能的异步Web服务。

环境准备与项目配置

依赖配置

首先，在Cargo.toml中添加必要的依赖：

[dependencies]
salvo = "0.83"
tokio = { version = "1", features = ["full"] }
sqlx = { version = "0.8", features = ["postgres", "runtime-tokio-native-tls"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = "0.3"

数据库连接池配置

SQLx提供了强大的连接池管理功能，支持多种数据库类型：

mermaid

核心架构设计

全局连接池管理

使用OnceLock实现线程安全的全局数据库连接池：

use std::sync::OnceLock;
use salvo::prelude::*;
use sqlx::{FromRow, PgPool, postgres::PgPoolOptions};
use serde::Serialize;

// 全局PostgreSQL连接池实例
static POSTGRES: OnceLock<PgPool> = OnceLock::new();

// 辅助函数获取数据库连接池
#[inline]
pub fn get_postgres() -> &'static PgPool {
    POSTGRES.get().expect("PostgreSQL连接池未初始化")
}

数据模型定义

定义与数据库表结构对应的Rust数据结构：

#[derive(FromRow, Serialize, Debug)]
pub struct User {
    pub id: i64,
    pub username: String,
    pub email: String,
    pub created_at: chrono::DateTime<chrono::Utc>,
}

#[derive(FromRow, Serialize, Debug)]
pub struct Product {
    pub id: i64,
    pub name: String,
    pub price: f64,
    pub stock: i32,
    pub description: Option<String>,
}

实战案例：完整的CRUD操作

1. 查询操作 - 获取用户列表

#[handler]
async fn list_users(_req: &mut Request, res: &mut Response) {
    let users = sqlx::query_as::<_, User>("SELECT * FROM users ORDER BY created_at DESC")
        .fetch_all(get_postgres())
        .await;
    
    match users {
        Ok(users) => res.render(Json(users)),
        Err(e) => {
            tracing::error!("查询用户列表失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
        }
    }
}

2. 条件查询 - 根据ID获取用户

#[handler]
async fn get_user(req: &mut Request, res: &mut Response) {
    let user_id = match req.param::<i64>("id") {
        Some(id) => id,
        None => {
            res.status_code(StatusCode::BAD_REQUEST);
            return;
        }
    };
    
    let user = sqlx::query_as::<_, User>("SELECT * FROM users WHERE id = $1")
        .bind(user_id)
        .fetch_optional(get_postgres())
        .await;
    
    match user {
        Ok(Some(user)) => res.render(Json(user)),
        Ok(None) => res.status_code(StatusCode::NOT_FOUND),
        Err(e) => {
            tracing::error!("查询用户失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
        }
    }
}

3. 插入操作 - 创建新用户

#[derive(Deserialize)]
struct CreateUserRequest {
    username: String,
    email: String,
}

#[handler]
async fn create_user(req: &mut Request, res: &mut Response) {
    let user_data = match req.parse_json::<CreateUserRequest>().await {
        Ok(data) => data,
        Err(_) => {
            res.status_code(StatusCode::BAD_REQUEST);
            return;
        }
    };
    
    let result = sqlx::query!(
        "INSERT INTO users (username, email) VALUES ($1, $2) RETURNING id",
        user_data.username,
        user_data.email
    )
    .fetch_one(get_postgres())
    .await;
    
    match result {
        Ok(record) => {
            res.status_code(StatusCode::CREATED);
            res.render(Json(json!({ "id": record.id })));
        }
        Err(e) => {
            tracing::error!("创建用户失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
        }
    }
}

4. 更新操作 - 修改用户信息

#[handler]
async fn update_user(req: &mut Request, res: &mut Response) {
    let user_id = match req.param::<i64>("id") {
        Some(id) => id,
        None => {
            res.status_code(StatusCode::BAD_REQUEST);
            return;
        }
    };
    
    let update_data = match req.parse_json::<CreateUserRequest>().await {
        Ok(data) => data,
        Err(_) => {
            res.status_code(StatusCode::BAD_REQUEST);
            return;
        }
    };
    
    let rows_affected = sqlx::query!(
        "UPDATE users SET username = $1, email = $2 WHERE id = $3",
        update_data.username,
        update_data.email,
        user_id
    )
    .execute(get_postgres())
    .await
    .map(|result| result.rows_affected());
    
    match rows_affected {
        Ok(affected) if affected > 0 => res.status_code(StatusCode::NO_CONTENT),
        Ok(_) => res.status_code(StatusCode::NOT_FOUND),
        Err(e) => {
            tracing::error!("更新用户失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
        }
    }
}

5. 删除操作 - 移除用户

#[handler]
async fn delete_user(req: &mut Request, res: &mut Response) {
    let user_id = match req.param::<i64>("id") {
        Some(id) => id,
        None => {
            res.status_code(StatusCode::BAD_REQUEST);
            return;
        }
    };
    
    let rows_affected = sqlx::query!("DELETE FROM users WHERE id = $1", user_id)
        .execute(get_postgres())
        .await
        .map(|result| result.rows_affected());
    
    match rows_affected {
        Ok(affected) if affected > 0 => res.status_code(StatusCode::NO_CONTENT),
        Ok(_) => res.status_code(StatusCode::NOT_FOUND),
        Err(e) => {
            tracing::error!("删除用户失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
        }
    }
}

高级特性与最佳实践

事务处理

SQLx提供了完整的事务支持，确保数据一致性：

#[handler]
async fn transfer_funds(req: &mut Request, res: &mut Response) {
    #[derive(Deserialize)]
    struct TransferRequest {
        from_account: i64,
        to_account: i64,
        amount: f64,
    }
    
    let transfer_data = match req.parse_json::<TransferRequest>().await {
        Ok(data) => data,
        Err(_) => {
            res.status_code(StatusCode::BAD_REQUEST);
            return;
        }
    };
    
    let mut tx = match get_postgres().begin().await {
        Ok(tx) => tx,
        Err(e) => {
            tracing::error!("开启事务失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
            return;
        }
    };
    
    // 执行转账操作
    match sqlx::query!("UPDATE accounts SET balance = balance - $1 WHERE id = $2", 
            transfer_data.amount, transfer_data.from_account)
        .execute(&mut *tx)
        .await
    {
        Ok(_) => (),
        Err(e) => {
            let _ = tx.rollback().await;
            tracing::error!("扣款失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
            return;
        }
    };
    
    match sqlx::query!("UPDATE accounts SET balance = balance + $1 WHERE id = $2", 
            transfer_data.amount, transfer_data.to_account)
        .execute(&mut *tx)
        .await
    {
        Ok(_) => (),
        Err(e) => {
            let _ = tx.rollback().await;
            tracing::error!("收款失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
            return;
        }
    };
    
    match tx.commit().await {
        Ok(_) => res.status_code(StatusCode::NO_CONTENT),
        Err(e) => {
            tracing::error!("提交事务失败: {}", e);
            res.status_code(StatusCode::INTERNAL_SERVER_ERROR);
        }
    }
}

分页查询

实现标准的分页接口：

#[derive(Deserialize)]
struct Pagination {
    page: Option<u32>,
    per_page: Option<u32>,
}

#[handler]
async fn list_users_paginated(req: &mut Request, res: &mut Response) {
    let pagination = Pagination {
        page: req.query("page").unwrap_or(1),
        per_page: req.query("per_page").unwrap_or(20),
    };
    
    let offset = (pagination.page - 1) * pagination.per_page;
    
    let users = sqlx::query_as::<_, User>(
        "SELECT * FROM users ORDER BY created_at DESC LIMIT $1 OFFSET $2"
    )
    .bind(pagination.per_page as i64)
    .bind(offset as i64)
    .fetch_all(get_postgres())
    .await;
    
    let total = sqlx::query!("SELECT COUNT(*) as count FROM users")
        .fetch_one(get_postgres())
        .await
        .map(|r| r.count.unwrap_or(0));
    
    match (users, total) {
        (Ok(users), Ok(total)) => {
            let response = json!({
                "data": users,
                "pagination": {
                    "page": pagination.page,
                    "per_page": pagination.per_page,
                    "total": total,
                    "total_pages": (total as f64 / pagination.per_page as f64).ceil() as u32
                }
            });
            res.render(Json(response));
        }
        _ => res.status_code(StatusCode::INTERNAL_SERVER_ERROR),
    }
}

路由配置与服务器启动

完整的路由配置

fn create_router() -> Router {
    Router::new()
        .push(
            Router::with_path("api")
                .push(
                    Router::with_path("users")
                        .get(list_users)
                        .post(create_user)
                        .push(
                            Router::with_path("<id>")
                                .get(get_user)
                                .put(update_user)
                                .delete(delete_user)
                        )
                )
                .push(
                    Router::with_path("products")
                        .get(list_products)
                        .post(create_product)
                )
        )
        .push(
            Router::with_path("health")
                .get(|_req, res| async move {
                    res.render("OK");
                })
        )
}

服务器启动与初始化

#[tokio::main]
async fn main() {
    // 初始化日志系统
    tracing_subscriber::fmt().init();
    
    // 配置数据库连接
    let database_url = std::env::var("DATABASE_URL")
        .unwrap_or_else(|_| "postgres://username:password@localhost/database".to_string());
    
    // 创建连接池
    let pool = PgPoolOptions::new()
        .max_connections(20)
        .idle_timeout(std::time::Duration::from_secs(300))
        .connect(&database_url)
        .await
        .expect("Failed to create pool");
    
    // 存储全局连接池
    POSTGRES.set(pool).unwrap();
    
    // 执行数据库迁移（可选）
    sqlx::migrate!("./migrations")
        .run(get_postgres())
        .await
        .expect("Failed to run migrations");
    
    // 创建路由并启动服务器
    let router = create_router();
    let acceptor = TcpListener::new("0.0.0.0:5800").bind().await;
    
    tracing::info!("服务器启动在 http://0.0.0.0:5800");
    Server::new(acceptor).serve(router).await;
}

性能优化与错误处理

连接池配置优化

let pool = PgPoolOptions::new()
    .max_connections(20)                    // 最大连接数
    .min_connections(5)                     // 最小连接数
    .max_lifetime(Some(std::time::Duration::from_secs(1800))) // 连接最大生命周期
    .idle_timeout(Some(std::time::Duration::from_secs(300)))  // 空闲超时时间
    .acquire_timeout(std::time::Duration::from_secs(30))      // 获取连接超时
    .test_before_acquire(true)              // 获取前测试连接
    .connect(&database_url)
    .await?;

统一的错误处理中间件

#[handler]
async fn error_handler(&self, req: &mut Request, res: &mut Response, ctrl: &mut FlowCtrl) {
    ctrl.call_next(req, res).await;
    
    if res.status_code().is_server_error() {
        tracing::error!(
            "请求处理错误: {} {} - {}",
            req.method(),
            req.uri(),
            res.status_code()
        );
    }
}

测试策略

单元测试示例

#[cfg(test)]
mod tests {
    use super::*;
    use salvo::test::TestClient;
    use salvo::prelude::*;
    
    #[tokio::test]
    async fn test_get_user() {
        let service = Service::new(create_router());
        
        let content = TestClient::get("http://127.0.0.1:5800/api/users/1")
            .send(&service)
            .await
            .take_string()
            .await
            .unwrap();
        
        assert!(content.contains("\"id\":1"));
    }
}

总结与展望

Salvo与SQLx的结合为Rust Web开发带来了前所未有的开发体验和性能表现。通过本文的实战指南，你应该已经掌握了：

✅ 核心概念：异步数据库操作、连接池管理、类型安全查询
✅ 完整CRUD：增删改查操作的实现与最佳实践
✅ 高级特性：事务处理、分页查询、错误处理
✅ 性能优化：连接池配置、查询优化、监控日志

未来发展方向

实时数据同步：结合WebSocket实现实时数据推送
分布式事务：使用Saga模式处理跨服务事务
查询优化：利用SQLx的查询缓存和预处理语句
监控告警：集成Prometheus和Grafana进行性能监控

Salvo + SQLx的组合不仅解决了传统Web开发中的痛点，更为构建高性能、高可用的现代Web服务提供了坚实的技术基础。无论是初创项目还是大型企业级应用，这个技术栈都能满足你的需求。

下一步行动建议：

立即尝试文中的代码示例
根据业务需求调整连接池配置
实现自定义的监控和日志系统
探索更多的SQLx高级特性

开始你的Salvo + SQLx之旅，构建下一个高性能的Web应用！

【免费下载链接】salvo 一个真正让你体感舒适的 Rust Web 后端框架项目地址: https://gitcode.com/salvo-rs/salvo

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考