Web 框架常会搭配数据库一起使用,Rocket 框架当然也有一定程度的数据库支持。虽然我们可以直接使用 Rocket 框架提供的应用程序状态机制来注册任意套件提供的数据库实体,但是在程序撰写上会比较麻烦一点,像是数据库的地址、帐密等信息,我们可能就必须要写死在代码内,或是自己再另外开发出可以让 Rocket 框架从外部读取数据库设置值的功能。Rocket 官方提供的 rocket_db_pools 套件,能替 Rocket 框架添加数据库支持,可以快速地将数据库实体变成请求守卫来取用,也可以将数据库的设置融入至 Rocket 框架的设置中。

rocket_db_pools 套件根据不同的数据库种类和驱动程序,分出不同的特色,并提供不同的类型来支持它们。在应用时,设置档和代码的基本架构如下:

rocket_db_pools = { version = "0.1.0", features = ["数据库特色"] }
[default.databases.名称]
url = "数据库URL"
#[macro_use]
extern crate rocket;

use rocket_db_pools::{Connection, Database};

#[derive(Database)]
#[database("名称")]
struct 数据库结构体(数据库Pool类型);

#[launch]
fn rocket() -> _ {
    rocket::build().attach(数据库结构体::init())
}

在路由处理程序中可以使用 rocket_db_pools::Connection 结构体来包裹我们的数据库结构体作为请求守卫。如下:

#[HTTP请求方法("路径")]
fn handler(变量名称: Connection<数据库结构体>) -> 要回应的数据类型 { 
    处理请求的程序区块
}

当 HTTP 请求成功交给上面的处理程序处理时,就会拿到数据库结构体所包裹的 Pool 的数据库连接。至于数据库 Pool 类型具体到底会用到哪个类型,请参考下表:

数据库种类 驱动程序 数据库特色 数据库类型
Postgres deadpool deadpool_postgres deadpool_postgres::Pool
Redis deadpool deadpool_redis deadpool_redis::Pool
Postgres sqlx sqlx_postgres sqlx::PgPool
MySQL sqlx sqlx_mysql sqlx::MySqlPool
SQLite sqlx sqlx_sqlite sqlx::SqlitePool
MongoDB mongodb mongodb mongodb::Client
Postgres diesel diesel_postgres diesel::PgPool
MySQL diesel diesel_mysql diesel::MysqlPool

实际演练

MySQL

目标:让 Rocket 应用程序连接 MySQL 数据库,并完成数据的访问。

首先创建新的 MySQL 数据库和用户。用户名和数据库名称均为 magic_rocket,用户密码为 4M{}^;dkn7Eg。

在一般的 shell 下运行:

mysql -u root -p

在 MySQL 的 shell 下运行以下 SQL,来创建出数据库:

CREATE DATABASE `magic_rocket`;

在 MySQL 的 shell 下运行以下 SQL,来创建出可以访问刚才创建出来的数据库的用户:

CREATE USER 'magic_rocket'@'localhost' IDENTIFIED BY '4M{}^;dkn7Eg';
GRANT ALL ON `magic_rocket`.* TO 'magic_rocket'@'localhost';
# GRANT ALL PRIVILEGES ON `magic_rocket`.* TO 'magic_rocket'@'localhost' IDENTIFIED BY '4M{}^;dkn7Eg';

然后开始撰写 Rust 程序项目吧!

[dependencies]
rocket = { version = "0.5.0" }
rocket_db_pools = { version = "0.1.0", features = ["sqlx_mysql"] }
[default.databases.example]
url = "mysql://magic_rocket:4M{}^;dkn7Eg@localhost:3306/magic_rocket"
#[macro_use]
extern crate rocket;

use rocket::fairing::AdHoc;
use rocket_db_pools::{
    sqlx::{self, Row},
    Connection, Database,
};

#[derive(Database)]
#[database("example")]
struct MyDatabase(sqlx::MySqlPool);

#[put("/<key>/<value>")]
async fn put(mut db: Connection<MyDatabase>, key: String, value: String) -> &'static str {
    sqlx::query("INSERT INTO `example` (`key`, `value`) VALUES (?, ?)")
        .bind(key)
        .bind(value)
        .execute(&mut **db)
        .await
        .unwrap();

    "ok"
}

#[get("/<key>")]
async fn get(mut db: Connection<MyDatabase>, key: String) -> Option<String> {
    let result = sqlx::query("SELECT `value` FROM `example` WHERE `key` = ?")
        .bind(key)
        .fetch_optional(&mut **db)
        .await
        .unwrap();

    result.map(|row| row.get("value"))
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .attach(MyDatabase::init())
        .attach(AdHoc::try_on_ignite("MySQL Initializer", |rocket| {
            Box::pin(async move {
                let mut connection = match MyDatabase::fetch(&rocket) {
                    Some(pool) => match pool.acquire().await {
                        Ok(connection) => connection,
                        Err(_) => return Err(rocket),
                    },
                    None => return Err(rocket),
                };

                let result = sqlx::query(
                    "CREATE TABLE IF NOT EXISTS `example` ( `id` INT NOT NULL AUTO_INCREMENT, \
                     `key` varchar(100), `value` TEXT , PRIMARY KEY (`id`), UNIQUE KEY (`key`) )",
                )
                .execute(&mut *connection)
                .await;

                match result {
                    Ok(_) => Ok(rocket),
                    Err(_) => Err(rocket),
                }
            })
        }))
        .mount("/", routes![put, get])
}

以上的 Rust 程序,我们除了将 MyDatabase 的整流片注册给 Rocket 之外,还另外再注册了一个 AdHoc 整流片来初始化 MySQL 数据库。

MongoDB

目标:让 Rocket 应用程序连接 MongoDB 数据库,并完成数据的访问。

使用的 MongoDB 数据库名称为 magic_rocket,不必事先创建出来。

直接开始撰写 Rust 程序项目吧!

[dependencies]
rocket = { version = "0.5.0" }
rocket_db_pools = { version = "0.1.0", features = ["mongodb"] }
[default.databases.example]
url = "mongodb://localhost:27017/magic_rocket"
#[macro_use]
extern crate rocket;

use rocket::fairing::AdHoc;
use rocket_db_pools::{
    mongodb::{
        self,
        bson::{doc, Bson, Document},
        options::IndexOptions,
        IndexModel,
    },
    Connection, Database,
};

#[derive(Database)]
#[database("example")]
struct MyDatabase(mongodb::Client);

#[put("/<key>/<value>")]
async fn put(db: Connection<MyDatabase>, key: String, value: String) -> &'static str {
    let db = db.default_database().unwrap();

    let collection_example = db.collection("example");

    collection_example.insert_one(doc! {"key": key, "value": value}, None).await.unwrap();

    "ok"
}

#[get("/<key>")]
async fn get(db: Connection<MyDatabase>, key: String) -> Option<String> {
    let db = db.default_database().unwrap();

    let collection_example = db.collection("example");

    let result: Option<Document> =
        collection_example.find_one(Some(doc! {"key": key}), None).await.unwrap();

    match result {
        Some(mut doc) => {
            if let Bson::String(value) = doc.remove("value").unwrap() {
                Some(value)
            } else {
                panic!("Value should be a string!")
            }
        },
        None => None,
    }
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .attach(MyDatabase::init())
        .attach(AdHoc::try_on_ignite("MongoDB Initializer", |rocket| {
            Box::pin(async move {
                let db = match MyDatabase::fetch(&rocket) {
                    Some(client) => match client.default_database() {
                        Some(database) => database,
                        None => return Err(rocket),
                    },
                    None => return Err(rocket),
                };

                let collection_example = db.collection::<Document>("example");

                let result = collection_example
                    .create_index(
                        {
                            let mut index = IndexModel::default();

                            let mut options = IndexOptions::default();

                            options.unique = Some(true);

                            index.keys = doc! {"key": 1};
                            index.options = Some(options);

                            index
                        },
                        None,
                    )
                    .await;

                match result {
                    Ok(_) => Ok(rocket),
                    Err(_) => Err(rocket),
                }
            })
        }))
        .mount("/", routes![put, get])
}

同样地,以上的 Rust 程序,我们除了将 MyDatabase 的整流片注册给 Rocket 之外,还另外再注册了一个 AdHoc 整流片来初始化 MongoDB 数据库。

总结

这个章节介绍了在 Rocket 框架访问数据库的方式,也使我们更能体会 Rocket 框架的整流片以及请求守卫究竟是有多么便利。结合了数据库的 Rocket 应用程序,就可以拿来实现更为庞大的 Web 架构,一旦商业逻辑愈来愈复杂,就会使得程序开发人员犯错的概率增高,所以下一章我们要学习撰写测试(testing),来自动验证程序逻辑的正确性。

最后,除了 rocket_db_pools 套件之外,Rocket 官方其实还有提供 rocket_sync_db_pools 套件,它支持采用阻塞式 I/O 的数据库驱动程序,如今不是很建议使用了。但 rocket_sync_db_pools 套件有支持 rocket_db_pools 套件所没支持的数据库,如果真的有需要的话,还是可以考虑将其加入项目中使用,不过本系列文章就不提这个套件的用法了。

下一章:测试。