一个 Web 框架最基本的功能除了提供 HTTP 服务器之外,还需要进行 HTTP 请求(request)的路由(routing)。Rocket 在这方面套用了 Rust 编程语言提供的进程式宏功能,使我们可以很简单地使用 get、put、post、delete、head、patch 和 options 等属性来快速做出属于该 HTTP 请求方法的路由处理程序(handler)。另外,我们也可以在撰写属性的同时,去对请求中的网址路径(path)、网址查找字符串(query)、以及 HTTP 主体(body)选择要使用的处理程序,以及进行数据类型的匹配。此外,Rocket 也会负责检查开发者撰写的这些规则有没有发生冲突,确保程序在编译完成并启动 Rocket 后,可以正确无误地提供路由处理的服务。

承上一章我们所撰写的 Hello World 程序,当时使用的路由处理程序只有以下这个:

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

Rocket 的路由处理程序的最基本架构如下:

#[HTTP请求方法("路径")]
fn handler() { 处理请求的程序区块 }

注意,上面的架构,handler 不会在回应(respond)请求时,于 HTTP 主体中传入任何数据。如果想要回传数据,就得像刚才提到的 Hello World 程序的写法一样,替路由处理程序的函数加上回传类型。如下:

#[HTTP请求方法("路径")]
fn handler() -> 要回应的数据类型 { 处理请求的程序区块 }

HTTP 请求方法

HTTP请求方法 的部份可以使用 get、put、post、delete、head、patch 和 options 等属性,分别对应着 HTTP 不同的请求方法。

Rocket 也会自动帮助开发者进行常见的扩充。像是使用 get 属性的话,Rocket 也会自动实作 head 的功能。再来由于网页表单只能够送出 GET 或是 POST 请求,所以若是遇到内容类型(Content-Type)为 application/x-www-form-urlencoded 的 POST 请求时,Rocket 就会去看这个请求的主体中的第一个字段是否是 _method,并且去检查这个 _method 字段中的值是否为 PUT 或是 DELETE(大小写可忽略),如果是的话,Rocket 就会改以使用 put 或是 delete 属性的路由处理程序来处理这个 POST 请求。

路径

在属性中所撰写的路径,除了可以写固定(静态)路径之外,还可以使用变量来匹配路径的任意组成部份(component),接着就可以在路由处理程序的函数参数中,替这个变量指定一个类型,使 Rocket 可以自动对其进行类型转换与匹配。

例如:

#[get("/<name>")]
fn handler(name: String) -> String {
    name
}

以上这个路由处理程序,可以让 Rocket 在处理路径为 /xxx 的 GET 请求时,直接以路径中的 xxx 来回应。

路径中的变量,除了可以使用 String 类型之外,Rust 内置的其它基本数据类型(如 i8、u16、f32、bool 等)也都可以使用。这些类型称为「参数守卫」(Parameter Guard),用来匹配路径中的变量。如果想要将自己实作的类型当作参数守卫来使用,就必须实作 rocket 这个 crate 所提供的 request::FromParam 特性。

如果想要用一个变量来代替多个路径的组成部份,则路径在属性中的写法就会需要在变量名称后面加上两个半角句点 ..,且用来进行类型转换与匹配的类型,就不能够使用参数守卫,而是要使用「区段守卫」(Segments guard)。此外,区段守卫对应的变量,必须要写在路径的最尾端。

Rust 标准函数库提供的 PathBuf 可以直接作为区段守卫来使用,例如:

use std::path::PathBuf;

#[get("/<name..>")]
fn handler(name: PathBuf) -> String {
    name.to_str().unwrap().to_string()
}

如果想要将自己实作的类型当作区段守卫来使用,就必须实作 rocket 这个 crate 所提供的 request::FromSegments 特性。不过通常我们不会自己实作区段守卫啦!PathBuf 就有很好的性能和安全性了。

路由的顺序与转递(Forwarding)

同一种路径可以撰写多个不同的路由处理程序。

例如:

#[get("/<name>")]
fn handler_1(name: String) -> String {
    name
}

#[get("/<id>")]
fn handler_2(id: i32) -> String {
    format!("id = {id}")
}

当我们把以上两个路由处理程序都注册给 Rocket 后,在使用 Rocket 结构实体的 launch 方法来启动 Rocket 时,Rocket 会检查出路由设置发生冲突了,因为 /<name> 和 /<id> 是一模一样的匹配样本(pattern)。

此时我们可以替这两个路由处理程序手动设置优先级,避免发生冲突。

添加优先级的方式为,在 HTTP 请求方法的属性参数中,于路径后面,再多加一个 rank 参数,来指定一个大于等于 0 的整数值作为优先级,写法如下:

#[HTTP请求方法("路径", rank = 优先级的值)]
fn handler() -> 要回应的数据类型 { 处理请求的程序区块 }

优先级的值,数值愈大,表示优先权愈低。再回到刚才的两个路由处理程序的例子,由于 i32 可表示的数据范围比 String 小,因此 handler_2 处理程序的优先权应该要设得比 handler_1 处理程序的优先权还要高。

于是,我们将程序改写如下:

#[get("/<name>", rank = 2)]
fn handler_1(name: String) -> String {
    name
}

#[get("/<id>", rank = 1)]
fn handler_2(id: i32) -> String {
    format!("id = {id}")
}

当有 /xxx 的 GET 请求进来时,会先以 handler_2 处理程序来进行类型转换与匹配,如果因 xxx 无法转换为 i32 类型而匹配失败了,就会将该请求转递给下一个,也就是 handler_1 处理程序来进行类型转换与匹配。

在我们不明确使用 rank 来指定优先级的值时,Rocket 会根据路径的匹配样本类型,来决定该路由处理程序的优先级的默认值。这部份会在这篇文章之后再详细说明。

网址查找字符串

网址查找字符串,也就是网址中问号 ? 后面的部份也可以被写进路由处理程序的路径匹配样本中。例如将 Hello World 程序使用的路由处理程序改成以下这样:

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

当 Rocket 接收到的 GET 请求的网址是 / 时,且网址查找字符串中一定要有 hello,才会在网页上印出 Hello, world!。如果 GET 请求中的网址查找字符串是 ?hello=xxx,匹配将会失败。如果网址查找字符串还有其它的字段,例如 ?hello&a&b=1,是可以匹配成功的!

如果有多个网址查找字符串的字段要进行匹配,可以直接写在路径的匹配样本中,用 & 来分隔。例如:

#[get("/?hello&a&b=1")]
fn index() -> &'static str {
    "Hello, world!"
}

网址查找字符串中的字段顺序可以忽略。如以上的路由处理程序,无论遇到 ?hello&a&b=1 还是 ?a&hello&b=1,都可以成功匹配!

另外,网址查找字符串中的字段也可以利用变量来进行类型的匹配与转换。例如:

#[get("/?hello&<id>")]
fn index(id: i32) -> String {
    format!("Hello, world! id = {id}")
}

以上这个路由处理程序,可以让 Rocket 在处理路径为 / 的 GET 请求时,去检查其网址查找字符串中有无 hello 和 id 字段,且 id 字段的值必须要可以转成 i32 类型。

网址查找字符串中的变量,除了可以使用 i32 类型之外,String 和 Rust 内置的其它基本数据类型(如 i8、u16、f32、bool 等)也都可以使用。如果想要将自己实作的类型也拿来匹配网址查找字符串,就必须实作 rocket 这个 crate 所提供的 form::FromFormField 特性。

另外,网址查找字符串也有类似路径的区段守卫的机制,称为「查找守卫」(Query Guard)。我们可以使用一个变量来代替多个网址查找字符串的字段,在属性中的写法就会需要在变量名称后面加上两个半角句点 ..,且用来进行类型转换与匹配的类型,就不能够单纯使用有实作 form::FromFormField 特性的类型,而是要使用实作 form::FromForm 特性的类型。此外,查找守卫对应的变量,必须要写在网址查找字符串的最尾端。

我们不太会直接使用 impl 关键字来替我们的类型实作 form::FromForm 特性,而是会直接替我们的类型加上 FromForm 这一个 derive 属性的参数。这个进程式宏会直接使用结构体的字段名称和类型来匹配网址查找字符串中的字段和其对应的数据,字段的类型必须要实作 form::FromFormField 特性。

如以下程序:

#[derive(FromForm)]
struct User {
    id: i32,
    name: String,
}

#[get("/?hello&<user..>")]
fn index(user: User) -> String {
    format!("Hello, world! id = {}, name = {}", user.id, user.name)
}

以上这个路由处理程序,可以让 Rocket 在处理路径为 / 的 GET 请求时,去检查其网址查找字符串中有无 hello、id 和 name 字段,且 id 字段的值必须要可以转成 i32 类型,name 字段的值必须要可以转成 String 类型。此外,除了刚才提到的字段,如果请求中的网址查找字符串还有其它的字段,这个路由处理程序也是可以成功匹配的。

如果要避免匹配请求中的网址查找字符串还有其它的字段,要用 form::Strict<T> 类型来包裹我们用进程式宏来实作 form::FromForm 特性的类型 T。程序如下:

use rocket::form::Strict;

#[derive(FromForm)]
struct User {
    id: i32,
    name: String,
}

#[get("/?hello&<user..>")]
fn index(user: Strict<User>) -> String {
    format!("Hello, world! id = {}, name = {}", user.id, user.name)
}

有时候我们可能会希望 Rocket 不要直接使用结构体中的字段名称来对应网址查找字符串中的字段名称,Rocket 允许开发者针对结构体中的某个字段,透过进程式宏来手动指定要对应到哪个网址查找字符串中的字段。例如将以上例子的 User 结构体改为:

#[derive(FromForm)]
struct User {
    #[field(name = "user_id")]
    id: i32,
    name: String,
}

以上程序,我们将 User 结构体的 id 字段加上 field 属性,并用 name 参数来指定要其对应到网址查找字符串中的 user_id 字段。

忽略组成部份

我们也可以用 <_> 将网址中不需要交给处理程序处理的组成部份给忽略掉。如以下程序:

#[get("/foo/<_>/bar")]
fn foo_bar() -> &'static str {
    "Foo _____ bar!"
}

#[get("/<_..>")]
fn everything() -> &'static str {
    "Hey, you're here."
}

路由处理程序的优先级的默认值

下表是 Rocket 根据每个路由处理程序的路径匹配样本所预设的优先级值:

路径类型 查找类型 Rank 值 路径匹配样本范例
完全静态 完全静态 -12 /a/hello?world=true
完全静态 动态 -11 /a/hello?world=true&<name>
完全静态 完全动态 -10 /a/hello?<world..>
完全静态 无 -9 /a/hello
动态 完全静态 -8 /a/<hello>?world=true
动态 动态 -7 /a/<hello>?world=true&<name>
动态 完全动态 -6 /a/<hello>?<world..>
动态 无 -5 /a/<hello>
完全动态 完全静态 -4 /<hello>?world=true
完全动态 动态 -3 /<hello>?world=true&<name>
完全动态 完全动态 -2 /<hello>?<world..>
完全动态 无 -1 /<hello>

HTTP 请求中的其它数据源

HTTP 请求中的数据可透过请求的网址路径(params)、网址的查找字符串(query)、HTTP 的标头(headers)、HTTP 的 Cookie 和 HTTP 的主体(body)中来取得。在上面的文章中,我们已经知道如何取得来自路径和网址查找字符串的数据,在这个小节中,会再继续探讨剩下的部份。

标头

使用 Rocket 取得 HTTP 标头的数据属于相对比较低级的操作,稍微麻烦了一点。我们会需要实作 rocket 这个 crate 所提供的 request::FromRequest 特性,使我们的类型能够当作「请求守卫」(Request Guard)来使用。

一个最基本的 request::FromRequest 特性的实作方式如下:

use rocket::request::{FromRequest, Outcome, Request};

struct MyStruct;

#[rocket::async_trait]
impl<'r> FromRequest<'r> for MyStruct {
    type Error = ();

    async fn from_request(request: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        Outcome::Success(MyStruct)
    }
}

我们可以在 from_request 这个关联函数中,利用 request 参数,来取得这个 HTTP 请求中的所有数据。也就是说,如果想要追求程序性能的话,先前提到的什么参数守卫、区段守卫、查找守卫都可以不要使用,全都改用一个请求守卫来完成。不过在这篇文章中只会介绍如何用 request::Request 结构实体来取得 HTTP 标头的数据。

request::Request 结构实体提供了一个 headers 方法,会回传一个以 Map 作为数据结构的结构实体的不可变参考(&http::HeaderMap<'r>),这个结构体的用法就跟标准函数库的 HashMap 差不多。Map 结构所保存的值一律使用类型为字符串切片 &str 的键值来查找(大小写可忽略),查找到的值会是一个迭代器(因为 HTTP 标头的字段可能会有重复的现象)。

举个例子来说明,如果我们要取得请求中的 Authorization 标头字段,并将字段的值交给请求守卫的结构实体来保存,以便在路由处理程序中使用。程序实作如下:

use rocket::request::{FromRequest, Outcome, Request};

struct MyGuard<'a> {
    authorization: Option<&'a str>,
}

#[rocket::async_trait]
impl<'r> FromRequest<'r> for MyGuard<'r> {
    type Error = ();

    async fn from_request(request: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let authorization = request.headers().get("authorization").next();

        Outcome::Success(MyGuard {
            authorization,
        })
    }
}

#[get("/auth")]
fn handler(guard: MyGuard) -> &str {
    guard.authorization.unwrap_or("")
}

如果想要强制让接收的 HTTP 请求中一定要有 Authorization 标头字段的话,可以将以上程序修改如下:

use rocket::{
    http::Status,
    request::{FromRequest, Outcome, Request},
};

struct MyGuard<'a> {
    authorization: &'a str,
}

#[rocket::async_trait]
impl<'r> FromRequest<'r> for MyGuard<'r> {
    type Error = ();

    async fn from_request(request: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let authorization = request.headers().get("authorization").next();

        match authorization {
            Some(authorization) => Outcome::Success(MyGuard {
                authorization,
            }),
            None => Outcome::Forward(Status::Unauthorized),
        }
    }
}

#[get("/auth")]
fn handler(guard: MyGuard) -> &str {
    guard.authorization
}

请求守卫如果是回传 Outcome 的 Forward 变体,它会把请求交给下一个路由处理程序继续匹配,如果不能匹配成功,其所带的 http::Status 结构实体会被用来触发 Rocket 的错误捕获者(Error Catcher)机制。这个部份会在之后的章节进行更详细的说明。

Cookie

Rocket 支持 Cookie 和基于 Cookie 的会话(Cookie-based Session)。我们可以直接使用 rocket 这个 crate 所提供的 http::CookieJar 结构体,当作请求守卫来使用。这个 http::CookieJar 结构体可以对 Cookie 进行添加(修改)、查找、删除等操作。

例如以下程序,可以取得 Cookie 中的 message 这个字段的数据。

use rocket::http::CookieJar;

#[get("/cookie/message")]
fn handler(cookies: &CookieJar<'_>) -> String {
    cookies.get("message").map(|c| c.value()).unwrap_or("").to_string()
}

例如以下程序,可以设置 Cookie 中的 message 这个字段的数据。

use rocket::http::{Cookie, CookieJar};

#[put("/cookie/message")]
fn handler(cookies: &CookieJar<'_>) {
    cookies.add(Cookie::new("message", "Hello!"));
}

例如以下程序,可以移除 Cookie 中的 message 这个字段。

use rocket::http::{Cookie, CookieJar};

#[delete("/cookie/message")]
fn handler(cookies: &CookieJar<'_>) {
    cookies.remove(Cookie::named("message"));
}

如果要使用加密的 Cookie,也就是基于 Cookie 的会话,首先要激活 rocket 的 secrets 特色,然后把刚才介绍的 http::CookieJar 结构实体的 get、add、remove 方法都加上 _private 这个后缀就行了。激活 secrets 特色的 Cargo.toml 文件写法如下:

[dependencies]
rocket = { version = "0.5.0", features = ["secrets"] }

另外,加密所使用的密钥,在预设情况下是由 Rocket 自动产生,不过这部份其实是可以手动设置的(在正式部署的环境中,如果有用到基于 Cookie 的会话,一定要手动替每个 Rocket 应用程序的运行个体设置相同的密钥),会在之后的章节做介绍。

还有一点要注意的是,在 request::FromRequest 特性的 from_request 这个关联函数中,也是可以透过 request::Request 结构实体来操作 http::CookieJar,只要使用其提供的 cookies 方法即可。

例如:

use rocket::request::{FromRequest, Outcome, Request};

struct Custom {
    name: String,
}

#[rocket::async_trait]
impl<'r> FromRequest<'r> for Custom {
    type Error = ();

    async fn from_request(request: &'r Request<'_>) -> Outcome<Self, Self::Error> {
        let cookies = request.cookies();

        let name = cookies.get("name").map(|c| c.value()).unwrap_or("").to_string();

        Outcome::Success(Custom { name })
    }
}

#[get("/cookie/message")]
fn handler(custom: Custom) -> String {
    custom.name.to_string()
}

主体

HTTP 请求中的 HTTP 主体大致可分为以下三种类型:

  • application/x-www-form-urlencoded:网页表单预设会用这种。
  • multipart/form-data:网页表单如果需要上传文件数据的话,就会用这种。
  • 其它

Rocket 框架本身能够处理 application/x-www-form-urlencoded 和 multipart/form-data 类型的主体,激活 rocket 的 json、msgpack 特色后也能处理 JSON 和 MessagePack 格式的主体(会在之后的章节介绍)。如果要处理其它类型的主体,就要由开发者自行去处理主体中的原始数据(raw data),或是使用第三方的套件来处理,这个部份由于日后的变动性很大,在本系列文章中就不提了,有兴趣者可以参考本站 Rust 分类中相关的单篇文章。

数据类型为 application/x-www-form-urlencoded 或 multipart/form-data 的主体,可以直接将有实作 form::FromForm 特性的类型包裹成 form::Form<T> 来匹配。因为 form::Form<T> 有实作 data::FromData 特性,可以当作「数据守卫」(Data Guard)来用。form::Form<T> 允许请求主体拥有 T 所没有的数据字段,如果要限制请求主体中的数据字段必须要刚好与 T 的字段一致,可以和查找守卫一样再用 form::Strict<T> 来包裹,写成 form::Form<form::Strict<T>>。

数据守卫的用法与参数守卫、区段守卫和查找守卫不同,一个路由处理程序最多只能够使用一个数据守卫,且加入数据守卫的方式为,在 HTTP 请求方法的属性参数中,于路径后面,再多加一个 data 参数,来指定数据守卫的变量名称,写法如下:

#[HTTP请求方法("路径", data = "<数据守卫的变量名称>")]
fn handler(数据守卫的变量名称: 数据守卫的类型) -> 要回应的数据类型 { 处理请求的程序区块 }

如以下程序:

use rocket::form::Form;

#[derive(FromForm)]
struct User {
    id:   i32,
    name: String,
}

#[post("/?hello", data = "<user>")]
fn index(user: Form<User>) -> String {
    format!("Hello, world! id = {}, name = {}", user.id, user.name)
}

以上这个路由处理程序,可以让 Rocket 在处理路径为 / 的 POST 请求时,去检查其网址查找字符串中有无 hello 字段,且 HTTP 主体中的数据类型必须为 application/x-www-form-urlencoded 或 multipart/form-data,主体的数据中必须要有 id 和 name 字段。此外,id 字段的值必须要可以转成 i32 类型,name 字段的值必须要可以转成 String 类型。

可省略的数据字段

上面介绍的参数守卫、区段守卫和查找守卫、数据守卫等实作了 form::FromForm 特性或 form::FromFormField 特性的类型都可以使用 Option 来进行包裹,使数据字段变成可选的(optional)。

例如以下程序:

#[get("/add?<a>&<b>")]
fn handler(a: Option<i32>, b: Option<i32>) -> String {
    format!("Answer = {}", a.unwrap_or(0) + b.unwrap_or(0))
}

以上这个路由处理程序,可以让 Rocket 在处理路径为 /add 的 GET 请求时,去检查其网址查找字符串中有无字段 a 或字段 b,如果没有的话,会直接把该字段当作是 None;如果有的话,该字段的值必须要可以被转成 i32 类型,然后使用 Some 这个 Option 的变体来包裹转换后的 i32 数值。

允许出错的数据字段

参数守卫可以使用 Result<T, &str> 进行包裹,如果参数数据可以转成类型 T,会使用 Ok(T) 来保存该字段;若无法转成类型 T(T 不能为 String 或是 &str),则会使用 Err(&str) 来保存该字段。

例如以下程序:

#[get("/<a>")]
fn handler(a: Result<i32, &str>) -> String {
    format!("a = {a:?}")
}

查找守卫、数据守卫等实作了 form::FromForm 特性或 form::FromFormField 特性的类型则要使用 form::Result 类型来包裹。

例如以下程序:

use rocket::form;

#[derive(Debug, FromForm)]
struct User<'r> {
    id:   form::Result<'r, i32>,
    name: String,
}

#[get("/?<user..>")]
fn handler(user: form::Result<User>) -> String {
    format!("{user:#?}")
}

也可以再用 Option 包裹 Result 或是 form::Result,就可以同时使数据字段变成可选的,而且也允许它转换失败啦!

例如以下程序:

use rocket::form;

#[derive(Debug, FromForm)]
struct User<'r> {
    id:   Option<form::Result<'r, i32>>,
    name: String,
    age:  Option<i32>,
}

#[get("/<a>?<user..>")]
fn handler(a: Option<Result<i32, &str>>, user: form::Result<User>) -> String {
    format!("a = {a:?}\n{user:#?}")
}

允许出错的请求守卫

请求守卫可以使用 Option<T> 来进行包裹。若 request::FromRequest 特性的 from_request 关联函数是回传 Outcome 的 Forward 或是 Error 变体的话,那么在经过匹配与转换之后,Option 的变体就会是 None。

请求守卫也可以使用 Result<T, T::Error> 来进行包裹。若 request::FromRequest 特性的 from_request 关联函数是回传 Outcome 的 Error 变体的话,那么在经过匹配与转换之后,Result 的变体就会是 Err,且 Err 变体所包裹的值为 Error 变体所包裹的元组(tuple)的第二个值(第一个值是 http::Status 结构实体);但若 request::FromRequest 特性的 from_request 关联函数是回传 Outcome 的 Forward 变体的话,则无法匹配成功。

所以我们也可以再用 Option 包裹 Result,就可以同时在能知道 Outcome 的 Error 变体所带的第二个值是什么的同时,也有能力处理当 Outcome 为 Forward 时的情形。

若 request::FromRequest 特性的 from_request 关联函数是回传 Outcome 的 Error 变体,则当该类型作为请求守卫来使用时,如果请求守卫没有使用 Option 或是 Result 来包裹,就无法使用下一个路由处理程序继续匹配,而会直接以 Error 变体中带的 http::Status 结构实体来触发 Rocket 的错误捕获者机制。这个部份会在之后的章节进行更详细的说明。

异步的处理程序

如果我们的处理程序有使用到异步 I/O 函数,我们也可以将处理程序函数改用 async fn 关键字来声明,如此一来就可以在该处理程序主体中使用 await 关键字。处理程序的实作有一点要特别需要注意的是,如果我们在处理程序中有使用到耗时较久的运算或其他功能,而偏偏它不是异步的,此时最好将它交给 tokio::task::spawn_blocking 这个异步函数处理,这个函数可以使用别的线程来运行传入的闭包,避免长时间占用到处理请求的线程,而影响其它请求的回应时间。

程序写法如下:

#[get("/")]
async fn handler() -> &'static str {
    // ...

    let result = rocket::tokio::task::spawn_blocking(move || {
        // do something
    })
    .await
    .unwrap();

    // ...

    "Done!"
}

总结

在这个章节中,我们知道了如何替 Rocket 框架的路由处理程序撰写包含网址查找字符串的路径匹配样本,也了解了路由处理程序的预设优先级和手动设置优先级的方式,然后也利用了参数守卫、区段守卫、查找守卫、请求守卫以及数据守卫来取得 HTTP 请求中含有的数据。

在下一个章节中,我们要来真正地开始学习 HTTP 回应(response)方式,而不再只是使用 String 或是 &str 作为路由处理程序函数的回传类型。

下一章:HTTP 回应(Response)。