Rocket 是一个使用 Rust 编程语言的 Web 框架,在服务器端运行,任何人都可以用它来轻易地开发出高弹性、高可用性以及拥有类型安全特性的 Web 应用程序。这个系列文章将会带您一步步了解 Rocket 框架的使用方法。

注意,Rocket 框架和其它多个 Web 框架都正在被 axum 框架取代!如果您想学一个好用的 Rust 的 Web 框架,axum 框架才是首选。

Rocket 框架

Rocket 这个英文单字的意思就是火箭,可能是因为框架的作者任职于 SpaceX 这间美国航太科技公司,所以才如此命名,还挺酷的。Rocket 的目标在于提供一个快速、简单、弹性且安全的 Web 框架,而且开发起来会感到愉快,因为它应用了 Rust 编程语言的「进程式宏」,来自动产生那些复杂且繁琐的代码。

在您继续阅读本系列文章之前,如果您还不熟悉 Rust 编程语言,请先参考笔者先前撰写的《Rust 学习之路》系列文章,并且详读最后一章:创建多线程的 Web 服务器。另外还有《用「async / .await」撰写 Rust 并发程序》一文。如此一来在阅读本系列文章时,就能更加感到用 Rocket 来开发 Web 服务器是有多么地轻松愉快~

Rocket 框架使用纯 Rust 编程语言来打造,不需相依于第三方动态函数库,可以很容易地移植到各个平台上运行。在性能上,它在 Rust 家族中虽然表现普通,但与 JavaScript 的 Web 框架相比已是快了不少。

Rocket 框架有以下三大宗旨:

  1. 安全、正确、重视开发者体验。
  2. 所有要交给开发者处理的请求(request)都会被自动类型化,不需要撰写额外的转换程序。且每个请求在处理时都是各别独立的,没有全域的状态。
  3. 不会强制一定得使用 Rocket 提供的模板引擎、串行化、会话(session)等非与处理 HTTP 协定直接相关的套件,这些套件都是可选的。

Hello World

学习一个 Web 框架,跟学一个编程语言一样,依照惯例,第一支程序都会是「Hello World」。现在,我们就来从无到有,一步步地从开新的 Cargo 程序项目开始,一直到能够在网页浏览器上印出 Hello, world! 这几个字吧!

创建项目目录

首先,运行以下指令,用 Cargo 创建出名叫 hello_rocket 的应用程序项目。

cargo new --bin hello_rocket

创建 hello_rocket 项目

在 Cargo.toml 设置档中加入 Rocket

接着编辑 Cargo.toml 设置档,在 [dependencies] 区块中加入 Rocket。我们可以在 crates.io 上找到 Rocket 项目。在此以 Rocket 的 v0.5.0 版本为例,Cargo.toml 设置档的写法如下:

[package]
name = "hello_rocket"
version = "0.1.0"
edition = "2021"

[dependencies]
rocket = "0.5.0"

撰写代码

接着编辑 src/main.rs 源代码,内容如下:

#[macro_use]
extern crate rocket;

#[get("/")]
fn index() -> &'static str {
    "Hello, world!"
}

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", routes![index])
}

以上程序,我们先用 #[macro_use] 属性和 extern crate 关键字来引用 rocket 这个 crate 公开出来的所有宏。在程序第 4 行,我们使用了 Rocket 提供的进程式宏,使得其后的第 5 行到第 7 行的 index 函数成为当 HTTP 请求的方法(method)是 GET 时,且请求路径是 / 时的路由(routing)处理程序(handler)。

rocket 函数必须搭配 rocket 提供的 launch 进程式宏来使用,且必须回传一个 Rocket 结构实体。在 rocket 函数中,使用 rocket 这个 crate 提供的 build 函数,来快速地产生出一个预设(设置值可透过环境变量或设置档来读入)的 Rocket 结构实体,接着再使用 Rocket 结构实体的 mount 方法,将 index 这个路由处理程序注册在 / 根目录下。也就是说,当有来自客户端的请求是想要用 HTTP 的 GET 来请求「根目录下的根目录」(也就是根目录)时,Rocket 就会调用 index 这个路由处理程序来处理该请求。这个 mount 方法需与 rocket 的 routes! 宏互相搭配使用。

Rocket 结构实体的 mount 方法会取得结构实体的拥有权,并且在运行后又将 Rocket 结构实体回传出来。在 rocket 函数的最后回传 Rocket 结构实体。

编译并运行项目

当程序撰写完成之后,就可以用以下指令来编译并运行项目:

cargo run

以 cargo run 编译 Rocket 项目

Rocket 启动时列出的组态配置

检查成果

在网页浏览器上打开 http://localhost:8000,来看看是否有出现 Hello, world! 这几个字!

浏览器显示的 Hello, world!

程序进入点

Rocket 帮我们提供了极为简易的方式处理程序进入点,也就是上面介绍的 #[launch] 属性和 rocket 函数,但如果我们想要替我们的程序制作命令行界面(CLI)的话,就得自行实作传统 main 函数作为程序进入点了。

要在 main 函数中运行 Rocket,main 函数可以这样写:

#[macro_use]
extern crate rocket;

use std::error::Error;

#[get("/")]
fn index() -> &'static str {
    "Hello, world!"
}

#[rocket::main]
async fn main() -> Result<(), Box<dyn Error>> {
    rocket::build().mount("/", routes![index]).launch().await?;

    Ok(())
}

我们必须自行使用 Rocket 结构实体的 launch 方法来启动 Rocket 服务器。

如果我们不想要一开始就使用异步的 main 函数,还可以将以上程序改写如下:

#[macro_use]
extern crate rocket;

use std::error::Error;

#[get("/")]
fn index() -> &'static str {
    "Hello, world!"
}

fn main() -> Result<(), Box<dyn Error>> {
    let app = rocket::build().mount("/", routes![index]);

    rocket::execute(async move { app.launch().await })?;

    Ok(())
}

调用 rocket 自带的 execute 函数可以创建 Rocket 专用的异步运行环境。

总结

在这一章节中,我们对 Rocket 这个 Web 框架有了粗浅的认识,也学会了从无到有,用 Rocket 来制作出 Hello World 网页的方式。

在下一章节中,我们会更深入地探讨 Rocket 的路由和处理请求的方式。

下一章:路由(Routing)与请求(Request)的处理。