Thruster

在我们的网站上查看示例和教程开始使用吧！

快速直观的Rust网络框架

没有时间阅读文档？查看

• 为什么你应该使用Thruster
• 为什么你不应该使用Thruster（绝对要读这一篇）

✅ 稳定版运行 ✅ 运行速度快 ✅ 不使用unsafe

文档

功能

• 考虑异步/await构建
• 兼容hyper
• SSL就绪
• 可测试
• 静态文件服务
• socketio
• gRPC，以及更多基于实验性的非tonic基于的gRPC
• 依赖注入

动机

Thruster是一个网络框架，旨在让开发者在项目之间和团队之间保持高效和一致。其目标是

• 高性能
• 简单
• 直观

Thruster还

• 不使用unsafe
• 在稳定Rust中运行

快速

Thruster可以与不同的服务器后端一起运行，并在它们之上提供了一个很好的封装层。这意味着它可以跟上Hyper、Actix甚至ThrusterServer（一个自制的http引擎）等类似技术的最新和最佳变化。

直观

基于Koa、Express等框架，Thruster旨在成为开发时的愉悦体验。

示例

要运行示例，请执行以下命令：cargo run --example <example-name>。例如，执行以下命令：cargo run --example hello_world，然后打开http://127.0.0.1:4321/

基于中间件

使新的 async await 代码能够运行的核心部分是为中间件函数指定 #[middleware_fn] 属性（这将标记中间件，以便与 Thruster 所基于的稳定 futures 版本兼容），然后在实际路由中的 m! 宏。

使用 async await 的简单示例

use std::boxed::Box;
use std::future::Future;
use std::pin::Pin;
use std::time::Instant;

use thruster::{App, BasicContext as Ctx, Request};
use thruster::{m, middleware_fn, MiddlewareNext, MiddlewareResult, Server, ThrusterServer};

#[middleware_fn]
async fn profile(context: Ctx, next: MiddlewareNext<Ctx>) -> MiddlewareResult<Ctx> {
    let start_time = Instant::now();

    context = next(context).await;

    let elapsed_time = start_time.elapsed();
    println!(
        "[{}μs] {} -- {}",
        elapsed_time.as_micros(),
        context.request.method(),
        context.request.path()
    );

    Ok(context)
}

#[middleware_fn]
async fn plaintext(mut context: Ctx, _next: MiddlewareNext<Ctx>) -> MiddlewareResult<Ctx> {
    let val = "Hello, World!";
    context.body(val);
    Ok(context)
}

#[middleware_fn]
async fn four_oh_four(mut context: Ctx, _next: MiddlewareNext<Ctx>) -> MiddlewareResult<Ctx> {
    context.status(404);
    context.body("Whoops! That route doesn't exist!");
    Ok(context)
}

#[tokio::main]
fn main() {
    println!("Starting server...");

    let mut app = App::<Request, Ctx, ()>::new_basic();

    app.get("/plaintext", m![profile, plaintext]);
    app.set404(m![four_oh_four]);

    let server = Server::new(app);
    server.build("0.0.0.0", 4321).await;
}

错误处理

这里有一个很好的例子

use thruster::errors::ThrusterError as Error;
use thruster::proc::{m, middleware_fn};
use thruster::{map_try, App, BasicContext as Ctx, Request};
use thruster::{MiddlewareNext, MiddlewareResult, MiddlewareReturnValue, Server, ThrusterServer};

#[middleware_fn]
async fn plaintext(mut context: Ctx, _next: MiddlewareNext<Ctx>) -> MiddlewareResult<Ctx> {
    let val = "Hello, World!";
    context.body(val);
    Ok(context)
}

#[middleware_fn]
async fn error(mut context: Ctx, _next: MiddlewareNext<Ctx>) -> MiddlewareResult<Ctx> {
    let res = "Hello, world".parse::<u32>()
        .map_err(|_| {
            let mut context = Ctx::default();
            
            context.status(400);

            ThrusterError {
                context,
                message: "Custom error message".to_string(),
                cause: None,
            }
        }?;

    context.body(&format!("{}", non_existent_param));

    Ok(context)
}

#[tokio::main]
fn main() {
    println!("Starting server...");

    let app = App::<Request, Ctx, ()>::new_basic()
        .get("/plaintext", m![plaintext])
        .get("/error", m![error]);

    let server = Server::new(app);
    server.build("0.0.0.0", 4321).await;
}

测试

Thruster 提供了一个简单的测试套件来测试您的端点，只需如下所示包含 testing 模块

let mut app = App::<Request, Ctx, ()>::new_basic();

...

app.get("/plaintext", m![plaintext]);

...

let result = testing::get(app, "/plaintext");

assert!(result.body == "Hello, World!");

创建自己的中间件模块

创建中间件非常简单！只需创建一个函数并在模块级别导出它。下面，您将看到一个允许请求分析的中间件

#[middleware_fn]
async fn profiling<C: 'static + Context + Send>(
    mut context: C,
    next: MiddlewareNext<C>,
) -> MiddlewareResult<C> {
    let start_time = Instant::now();

    context = next(context).await?;

    let elapsed_time = start_time.elapsed();
    info!("[{}μs] {}", elapsed_time.as_micros(), context.route());

    Ok(context)
}

您可能希望允许在上下文中存储更具体的数据，例如，可能希望能够将查询参数填充到 hashmap 中，以便其他中间件稍后使用。为了实现这一点，可以为上下文创建一个额外的 trait，中间件下游必须遵守。查看提供的查询参数中间件示例。

其他或自定义后端

Thruster 能够仅提供某种服务器上的路由层，例如，在上面的 Hyper 片段中。只要服务器实现了 ThrusterServer，这就可以广泛应用于任何后端。

use async_trait::async_trait;

#[async_trait]
pub trait ThrusterServer {
    type Context: Context + Send;
    type Response: Send;
    type Request: RequestWithParams + Send;

    fn new(App<Self::Request, Self::Context>) -> Self;
    async fn build(self, host: &str, port: u16);
}

需要的是

• 创建服务器的一种简单方法。
• 一个函数，用于将服务器构建成一个可以加载到异步运行时的 future。

在 build 函数中，服务器实现应该

• 启动某种连接监听器
• 调用 let matched = app.resolve_from_method_and_path(<某种方法>, <某种路径>);（这是提供实际路由。）
• 调用 app.resolve(<传入请求>, matched)（这是运行链式中间件。）

为什么你应该使用Thruster

• 可以随意更改后端。开箱即用，Thruster 现在可以用于：[actix-web](https://github.com/thruster-rs/Thruster/blob/master/thruster/examples/actix_most_basic.rs)、[hyper](https://github.com/thruster-rs/Thruster/blob/master/thruster/examples/hyper_most_basic.rs) 或 [自定义后端](https://github.com/thruster-rs/Thruster/blob/master/thruster/examples/hello_world.rs)
• Thruster 支持从框架级别进行 测试
• @trezm 当没有人提交 PR 或打开问题时会感到孤独。
• 推进器对于以中间件为中心的概念来说更为简洁——比如路由守卫。以下是一个在 actix 中限制 IP 的例子。

fn ip_guard(head: &RequestHead) -> bool {
    // Check for the cloudflare IP header
    let ip = if let Some(val) = head.headers().get(CF_IP_HEADER) {
        val.to_str().unwrap_or("").to_owned()
    } else if let Some(val) = head.peer_addr {
        val.to_string()
    } else {
        return false;
    };

    "1.2.3.4".contains(&ip)
}

#[actix_web::post("/ping")]
async fn ping() -> Result<HttpResponse, UserPersonalError> {
    Ok(HttpResponse::Ok().body("pong"))
}

...
        web::scope("/*")
            // This is confusing, but we catch all routes that _aren't_
            // ip guarded and return an error.
            .guard(guard::Not(ip_guard))
            .route("/*", web::to(HttpResponse::Forbidden)),
    )
    .service(ping);
...

这就是推进器。

#[middleware_fn]
async fn ip_guard(mut context: Ctx, next: MiddlewareNext<Ctx>) -> MiddlewareResult<Ctx> {
    if "1.2.3.4".contains(&context.headers().get("Auth-Token").unwrap_or("")) {
        context = next(context).await?;

        Ok(context)
    } else {
        Err(Error::unauthorized_error(context))
    }

}

#[middleware_fn]
async fn ping(mut context: Ctx, _next: MiddlewareNext<Ctx>) -> MiddlewareResult<Ctx> {
    context.body("pong");
    Ok(context)
}

...
    app.get("/ping", m![ip_guard, plaintext]);
...

更加直接一点是很不错的！

为什么你不应该使用推进器

• 维护者很少（几乎只有一个人）。
• 还有其他一些项目经过了更多的实战检验。推进器在生产环境中使用，但没有任何地方是你知道的或者重要的。
• 它还没有被聪明绝顶的人优化过。@trezm 尽力而为，但总是被他的狗（们）分散注意力。
• 严肃地说，这个框架 可能 确实是 很好，但它肯定没有得到像其他框架那样的深入研究。你的帮助可以使它更加安全和健壮，但我们可能还没有达到那里。

如果你读到这儿，感谢你的阅读！随时欢迎联系。