在 Web 应用程序提供服务时,程序难免会遭遇到一些预期内或是预期外的错误,像是客户端请求的网址没有路由处理程序能够处理、请求中的数据格式有误(例如原本需要输入数字的地方被输入成字母文字)、授权逾期,或是数据库突然连接失败等,Web 应用程序应该都要有能力避免应用程序崩溃(crash),并且照常发送 HTTP 回应。而 Rocket 框架当然预设就有处理这些错误的能力,开发者甚至可以利用自订的错误捕获者(Error Catcher),来覆盖掉预设的处理方式。

再回头以先前制作过的 Hello World 程序来举例。当客户端向 Hello World 应用程序发送 GET / 请求时,Hello World 应用程序会回应 Hello, world!。但当客户端向 Hello World 应用程序发送 GET /hi 请求时,由于没有路由处理程序能够匹配这个网址路径,所以就会触发 Rocket 框架的错误捕获者机制。

当发送进来的 HTTP 请求没有路由处理程序能够匹配时,Rocket 框架就会自动产生 404 (NotFound)错误,这个错误不会直接使用 HTTP 状态码来回应,而是会先去寻找框架中有没有针对 404 自订的错误捕获者,如果没有的话,就会使用 Rocket 预设的处理方式,将 404 错误以「404 错误网页」的方式回应。如下图:

Rocket 预设的 404 错误网页

同样地,其它类型的错误,Rocket 预设也都会提供对应的处理方式。例如,当路由处理程序的函数发生 panic 或是回传 http::Status 的 InternalServerError 结构实体时,Rocket 框架就会自动产生 500 错误,这个错误不会直接使用 HTTP 状态码来回应,而是会先去寻找框架中有没有针对 500 自订的错误捕获者,如果没有的话,就会使用 Rocket 预设的处理方式,将 500 错误以「500 错误网页」的方式回应。如下图:

Rocket 预设的 500 错误网页

自订错误捕获者

我们可以利用自订错误捕获者,来让 Rocket 以我们希望的方式来处理这些错误。例如发生 404 错误时,可以在浏览器上出现与网站风格相似的 404 错误页面;或是在发生 500 错误时,显示出稍后再尝试的提示页面。

Rocket 的错误捕获者的最基本架构如下:

#[catch(HTTP错误相关的状态码)]
fn error_catcher() { 处理请求的程序区块 }

与路由处理程序的函数相同,错误捕获者也可以设置要回应的数据类型,如下:

#[catch(HTTP错误相关的状态码)]
fn error_catcher() -> 要回应的数据类型 { 处理请求的程序区块 }

错误捕获者的函数所回传的数据类型的用法和路由处理程序的函数是完全相同的。

例如,以下的错误捕获者,可以创建出一个基本的 404 错误网页:

use rocket::response::content::RawHtml;

#[catch(404)]
fn error_catcher() -> RawHtml<&'static str> {
    RawHtml(
        r#"<html>
    <head>
        <meta charset=UTF-8>
        <title>404 Page</title>
    </head>
    <body>
        Ooops! You got a wrong path.
    </body>
</html>"#,
    )
}

若想要在错误捕获者中处理请求,可以替错误捕获者中的函数,加入一个 request::Request 类型的参数。

例如:

use rocket::request::Request;

#[catch(404)]
fn error_catcher(req: &Request) -> String {
    format!("Sorry, '{}' is not a valid path.", req.uri())
}

注册错误捕获者

与路由处理程序相同,将错误捕获者实作出来之后,也是要注册给 Rocket 才能发挥作用。注册错误捕获者的方式与注册路由处理程序的方式差不多,需用 Rocket 结构实体的 register 方法和 rocket 的 catchers! 宏来注册。

如以下程序:

use rocket::request::Request;

#[catch(404)]
fn error_catcher(req: &Request) -> String {
    format!("Sorry, '{}' is not a valid path.", req.uri())
}

#[launch]
fn rocket() -> _ {
    rocket::build().register("/", catchers![error_catcher])

    // ...
}

请求守卫与错误捕获者

请求守卫与错误捕获者可以直接搭配使用。在实作 request::FromRequest 特性时,使 from_request 关联函数回传 Outcome 的 Error 变体,就可以使有使用到该请求守卫的路由处理程序在匹配失败之后,直接回传其所带的 http::Status 结构实体,来触发 Rocket 的错误捕获者机制;而回传 Outcome 的 Forward 变体,则可以在该请求守卫的路由处理程序在匹配失败后,将请求交给下一个路由处理程序但其也匹配失败之后,回传其所带的 http::Status 结构实体,来触发 Rocket 的错误捕获者机制。

例如:

#[macro_use]
extern crate rocket;

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::Error((Status::Unauthorized, ())),
        }
    }
}

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

#[catch(401)]
fn error_catcher() -> &'static str {
    "You have no authorization to execute action."
}

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

以上程序,当 MyGuard 这个请求守卫回传 Outcome 枚举的 Error 变体,而导致 handler 这个路由处理程序匹配失败时,就会等同于直接回传 http::Status 的 Unauthorized 结构实体,而产生 401 错误,进一步触发 error_catcher 这个错误捕获者来进行 HTTP 的回应。

总结

Rocket 框架虽然预设就会帮我们处理 HTTP 状态码,但我们还是可以借由向 Rocket 框架注册我们自己实作的错误捕获者,来改变 Rocket 框架对这些错误状态的处理方式。在下一个章节中,将会介绍更高级的处理 HTTP 请求的方式。

下一章:高级处理 HTTP 请求(Request)的方式。