鸣谢

感谢译者的辛苦翻译, 可以帮译者在git上点一个星星

actix中文翻译git地址

hello-world.rs

use actix_web::{Error,middleware, web, App, HttpRequest, HttpServer, Responder, HttpResponse,guard, dev::HttpResponseBuilder};
use serde::{Deserialize,Serialize};
use actix_web::http::{HeaderName, HeaderValue, StatusCode};
use cookie::Cookie;
use actix_files::{Files, NamedFile};
use std::sync::Mutex;
use futures::future::{ready, Ready};
use std::fs::File;
use futures::StreamExt;


async fn index(req: HttpRequest) -> &'static str {  // return 的参数会转为 Responder
    println!("REQ: {:?}", req);  // 打印请求的相关信息
    "Hello world!"
}

async fn cookies() -> impl Responder{
    /*
    cookie 练习
    */
    let mut  res = HttpResponse::Ok();
    res.cookie(Cookie::build("say", "hello").finish());  // 设置一个 cookie
    res.finish()
}

async fn header() -> impl Responder {
    /*
    header 练习
    */
    let mut  res = HttpResponse::Ok();
    res.header("language", "python")  // 添加一个请求头(无论有没有相同的请求头, 都会新增一个响应头, 同样的 key 可能会有多个)
        .set_header("language", "javascript")  // 设置一个请求头(设置一个响应头(如果没有该key则会新建一个, 如果有则会覆盖))
        .set_header("say", "hello1")  // 设置一个响应头(如果没有该key则会新建一个, 如果有则会覆盖)
        .header("say", "hello2");  // 添加一个响应头
    res.finish()
}


#[derive(Deserialize,Serialize,Debug)]  // 为结构体实现序列化和反序列化的功能
struct UserInfo{
    user_id:i32,
    mobile:String
}

async fn get_user1(req:HttpRequest, params: web::Path<(UserInfo)>,) -> impl Responder{

    // Path 可以从请求中提取 路径中的参数
    println!("get_user1_REQ: {:?}", req);

    let p = params.0;  // 接收到的外部params参数 可以通过下标0 取出
    println!("收到了用户: {:?} 请求", p);

    let mut res = HttpResponse::Ok();

    res.json(p)
}
async fn get_user2(req:HttpRequest) -> impl Responder{
    println!("获得Path 参数相关 req.match_info(): {:?}", req.match_info());

    let user_id: i32 = req.match_info().query("user_id").parse().unwrap();  // 使用 query
    let mobile: String = req.match_info().get("mobile").unwrap().parse().unwrap();  // 使用 get
    HttpResponse::Ok().json(UserInfo{user_id:user_id,mobile:mobile})
}
async fn get_user3(info:web::Query<UserInfo>) -> impl Responder{
    println!("仅仅在请求查询字符串中有 'UserInfo' 相关字段时才会被调用info: {:?}", info);

    HttpResponse::Ok().json(info.into_inner())
}
async fn get_user4(req:HttpRequest,info:web::Json<UserInfo>) -> impl Responder{
    // 从body中接收了一个 json 数据 info
    HttpResponse::Ok().json(info.into_inner())
}
async fn get_user5(req:HttpRequest,info:web::Form<UserInfo>) -> impl Responder{
    // 从body中接收了一个 表单数据 数据 info
    // 仅当 content type 类型是  *x-www-form-urlencoded* 是 handler处理函数才会被调用
    // 且请求中的内容能够被反序列化到一个 "FormData" 结构体中去
    HttpResponse::Ok().json(info.into_inner())
}
// async fn my_body(info:String) -> impl Responder{  // payload 转为字符串
async fn my_body(mut info:web::Payload) -> impl Responder{
    // TODO 我这里提取不出来 可能是版本不对
    // info.next().await
    HttpResponse::Ok()
}


#[derive(Debug)]
struct Status{
    count:Mutex<i32>  // <- Mutex 必须安全的在线程之间可变
}

async fn get_states_less(data:web::Data<Status>) -> String{
    /*
    由 app 传入的数据
    */
    let mut count = data.count.lock().unwrap();  // 等待获取锁

    *count -= 1;  // 获取到锁之后 减少1

    println!("接收到了一个 state, 减少1后: {:?}", count);

    format!("count: {}", count)
}
async fn get_states_inc(data:web::Data<Status>) -> String{
    /*
    由 app 传入的数据
    */
    let mut count = data.count.lock().unwrap();  // 等待获取锁

    *count += 1;  // 获取到锁之后 增加1

    println!("接收到了一个 state, 增加1后: {:?}", count);

    format!("count: {}", count)
}


// 自定义 struct
#[derive(Serialize)]
struct Student{name: String}
// 为自定义struct 实现 Responder
impl Responder for Student{
    type Error = Error;
    type Future = Ready<Result<HttpResponse, Error>>;

    fn respond_to(self, _req: &HttpRequest) -> Self::Future {
        let body = serde_json::to_string(&self).unwrap();

        // 创建响应并设置Content-Type
        ready(Ok(HttpResponse::Ok()
            .content_type("application/json")
            .body(body)))
    }
}
async fn my_response()-> impl Responder{  // 返回自定义类型
    Student{name:"小明".to_string()}
}


async fn my_err1(file_name:web::Path<String>) -> std::io::Result<NamedFile>{
    // 如果一个处理函数在一个Result中返回Error(指普通的Rust trait std::error:Error),此Result也实现了ResponseError trait的话, actix-web将使用相应的actix_web::http::StatusCode 响应码作为一个Http response响应渲染.默认情况下会生成内部服务错误
    // impl<T: Responder, E: Into<Error>> Responder for Result<T, E>{}  // 这里为普通的 Result 实现了一些 trait, 可以点进 Responder 看

    println!("{:?}", format!("static/{}", file_name));
    let ret = NamedFile::open(format!("static/{}", file_name));
    ret
}

// 导入自定义错误需要的包
use derive_more::{Display, Error};
use actix_web::dev::BodyEncoding;

// 定义结构体(需要实现相关 trait)
#[derive(Debug,Display,Error)]
#[display(fmt = "my error: {}", msg)]
struct ErrResp{msg:&'static str}
// 为结构体使用 ResponseError 的默认实现即可 (ResponseError 的一个默认实现 error_response() 会渲染500)
impl actix_web::error::ResponseError for ErrResp{}
async fn my_err2() -> Result<HttpResponse,ErrResp>{
    Err(ErrResp{msg:"自定义的错误默认实现了 500"})  // 返回自定义的错误
}

// 使用 enum 重写 ResponseError 产生更多样的错误进行返回
#[derive(Debug,Display,Error)]
enum ErrEnum{
    #[display(fmt = "ServerError: {}",msg)]
    ServerError{msg:&'static str},
    #[display(fmt = "Forbidden: {}",msg)]
    Forbidden{msg:&'static str},
    #[display(fmt = "ResError: {}",msg)]
    ResError{msg:&'static str}
}
// 重写
impl actix_web::error::ResponseError for ErrEnum{
    fn status_code(&self) -> StatusCode {
        match *self{
            ErrEnum::ServerError{..} => StatusCode::from_u16(500).unwrap(),  // 自定义状态码 100 - 599
            ErrEnum::Forbidden{..} => StatusCode::FORBIDDEN,  // 使用预设的状态码
            ErrEnum::ResError{..} => StatusCode::from_u16(599).unwrap(),
        }
    }

    fn error_response(&self) -> HttpResponse {
        let mut resp = HttpResponseBuilder::new(self.status_code());
        resp.set_header(
            actix_web::http::header::CONTENT_TYPE,
            actix_web::http::header::HeaderValue::from_static("text/plain; charset=utf-8"),
        );
        resp.body(self.to_string())  // impl<T: fmt::Display + ?Sized> ToString for T
    }
}

async fn my_err3(flag:web::Path<i32>)-> Result<HttpResponse,ErrEnum>{
    let flag = flag.into_inner();
    match flag {
        0 => Ok(HttpResponse::Ok().body("成功")),
        1 => Err(ErrEnum::Forbidden{msg:"没有权限"}),
        _ => Err(ErrEnum::ServerError{msg:"服务器内部错误"})
    }
}

// 统一错误处理使用 map_err, 隐藏真正的错误到给用户展示
async fn my_err4()-> Result<HttpResponse,ErrEnum>{
    // 假设中间发生了一些错误
    let e:Result<HttpResponse,&str> = Err("2233");  // 模拟一个错误
    e.map_err(|e| {
        println!("发生一个错误: {:?}", e);
        // 处理错误
        ErrEnum::ServerError { msg: "出错了嗷" }
    })?;

    Ok(HttpResponse::Ok().finish())
}


async fn res(flag:web::Path<i32>) -> actix_web::Result<HttpResponse>{
    println!("进入 url_for1 视图, 接收到参数: {:?}", flag);
    Ok(
        HttpResponse::Ok().body(flag.into_inner().to_string())
    )
    // let url = req.url_for("foo", &["1", "2", "3"])?;
    // println!("url: {:?}", url);
    // Ok(
    //     HttpResponse::Ok()
    //     .set_header(actix_web::http::header::LOCATION, url.as_str())
    //     .finish()
    // )
}

async fn url_for(req:HttpRequest) -> actix_web::Result<HttpResponse>{

    let url = req.url_for("res_name", &["666"]).unwrap();
    println!("即将跳转: {:?}", url);

    // 使用 Found 跳转
    Ok(HttpResponse::Found()
        .header(actix_web::http::header::LOCATION, url.as_str())  // 跳转
        .finish())
}





#[actix_web::main]
async fn main() -> std::io::Result<()> {
    std::env::set_var("RUST_LOG", "actix_web=info");
    env_logger::init();

    // 关于路径 前缀没有包含斜杠,那么会默认自动的插入一个斜杠

    // 请求处理器
    // 默认情况下 actix-web 为 &‘static str , String 等提供了 Responder 的标准实现. 完整的实现清单可以参考 Responder documentation
    // 请求处理发生在两个阶段.首先处理对象被调用,并返回一个实现了 Responder trait的任何对象.然后在返回的对象上调用 respond_to() 方法,将其 自身转换成一个 HttpResponse 或者 Error
    // 请求处理器可以自定义返回类型, 相应的, 自定义返回的类型需要实现 Responder trait


    // 创建一个共享可变状态, 下面使用 move 移动到app中
    let counter = web::Data::new(Status { count: Mutex::new(0) });

    HttpServer::new(move || {
        App::new()
            // enable logger
            .wrap(middleware::Logger::default())  // 添加一个 log 中间件, 用来记录请求
            // .wrap(middleware::NormalizePath::default())  // TODO 这里我并没有发现有嘛用,启用了之后下面的资源都404了, 路径正规化并重定向: 比如请求的 ///res//// 很多斜杠的资源,在适配的时候会替换成 /res/

            // 状态 state
            // .data(Status { count: 0 })// 这里注册一个 普通状态, 状态通过 data 向视图中传递,State也能被中间件访问, 当然也可以单独给 service中的 resource 单独使用,
            .app_data(counter.clone())// 共享可变状态 状态通过 .app_data 向视图中传递 , 为了防止所有权转移需要 clone

            .service(  // service 用来注册一个服务
                       web::resource("/index.html").route(web::get().to(|| actix_web::web::HttpResponse::Ok().json("hello index world"))))// 这里 return 的 &str 实现了Responder trait, 所以会内部调用相关 方法
            // .service(web::resource("/").to(index))  // 一个普通的响应体

            .service(web::resource("/my_response")  // 返回自定义类型(为自定义类型实现 Responder trait, 即可)
                .route(web::get().to(my_response)))

            // 请求头和cookie
            .service(web::resource("/cookie")
                .route(web::get().to(cookies)))
            .service(web::resource("/header")  // 设置请求头相关
                .route(web::get().to(header)))

            // 视图中的共享可变 状态 state
            .service(web::resource("/get_states_less")  // 在视图中获取上面注册的状态 修改减1
                .route(web::get().to(get_states_less)))
            .service(web::resource("/get_states_inc")  // 在视图中获取上面注册的状态 修改加1
                .route(web::get().to(get_states_inc)))


            // 路由分发以及守卫  默认的情况下路由不包含任何的 guards, 因此所有的请求都可以被默认的处理器(HttpNotFound)处理.
            // web::get() 和 web::post() 返回一个 Route也就是路由
            // 路由上配置的所有guard,进来的请求都必须满足才能通过
            // 如果在检查期间注册在路由上的任意一个保护(guard)参数配置返回了false 那么当前路由就会被跳过,然后继续通过有序的路由集合进行匹配.
            .service(web::resource("/guard")  // 布置一个路由守卫, 其内可以实现一些方法更详细的文档:  https://docs.rs/actix-web/3.0.2/actix_web/guard/index.html#functions

                // .guard(guard::fn_guard(|req|  // 给整个resource 进行校验,如果请求头没有包含user_info就返回了false 返回404
                //     req.headers.contains_key("user_info"))
                // )

                .route(web::route()  // 给整个resource进行校验, 进行自定义返回
                    .guard(guard::fn_guard(
                        |req| !req.headers.contains_key("user_info")  // 如果返回 true 则进入 to视图中,这里使用了 ! 返回了 false
                    ))
                    .to(|| {  // 如果校验为 true 则进入到此分支,返回自定义内容, 如果返回false则跳过当前路由, 继续匹配下面的路由
                        println!("resource 校验失败");
                        HttpResponse::Forbidden()
                    }))

                .route(web::get() // 单独给 某个 路由, 请求方式添加守卫
                    .guard(guard::fn_guard(|req| {
                        println!("子路由 通过了校验");
                        true
                    }))
                    .to(|| {
                        println!("进入到了视图");
                        web::HttpResponse::Ok().finish()
                    })))
                // Route::guard() - 注册一个新的守卫, 每个路由都能注册多个guards.
                // Route::method() - 请求方法过滤守卫, 每个路由都能注册多个guards.
                // Route::to() - 为某个路由注册一个处理函数. 仅能注册一个处理器函数. 通常处理器函数在最后的配置操作时注册.
                // Route::to_async() - 注册一个异步处理函数. 仅能注册一个处理器函数. 通常处理器函数在最后的配置操作时注册.


            // 提取器
            // http://127.0.0.1:8080/user1/2233/13673429931
            .service(web::resource("/user1/{user_id}/{mobile}")  // 使用 path 提取器 序列化与反序列化 获取路径参数相关, 并返回application/json数据
                .route(web::get().to(get_user1)))
            // http://127.0.0.1:8080/user2/2233/13673429931
            .service(web::resource("/user2/{user_id}/{mobile}")  // 使用 match_info().get 或者 match_info().query 方法提取参数
                .route(web::get().to(get_user2)))
            // http://127.0.0.1:8080/user3?user_id=1718&mobile=13673429931
            .service(web::resource("/user3")  // 查询字符串 Query 类型为请求参数提供了提取功能. 底层是使用了 serde_urlencoded 包功能
                .route(web::get().to(get_user3)))
            // JSON格式; {"user_id": 123,"mobile": "13673429931" }
            .service(web::resource("user4")  // post 请求体中的 JSON 数据, 可以使用Json提取器允将请求 body 中的 JSON 信息反序列化到一个结构体中
                .route(web::post().to(get_user4)))
            // 表单格式: user_id = 2233, mobile = "13673429931"
            .service(web::resource("user5")  // post 请求体中的 表单From 数据, 使用 web::From<T> 提取, 注意请求的类型必须是 application/x-www-form-urlencoded
                .route(web::post().to(get_user5)))
            // 提取整个请求体使用 web::Payload, 也可以使用 String 将整个payload 转为 string类型
            .service(web::resource("body")
                .route(web::post().to(my_body)))
            // Data - 如果你需要访问应用程序状态的话.
            // HttpRequest - 如果你需要访问请求, HttpRequest本身就是一个提取器,它返回Self.
            // String - 你可以转换一个请求的playload成一个String. 可以参考文档中的example
            // bytes::Bytes - 你可以转换一个请求的playload到Bytes中. 可以参考文档中的example
            // Playload - 可以访问请求中的playload. example

            // 异常处理
            // http://127.0.0.1:8080/my_err1/1.txt
            .service(web::resource("/my_err1/{file_name}")  // 基本错误处理: Actix-web提供了一些常见的非actix error的 ResponseError 实现
                .route(web::get().to(my_err1)))
            .service(web::resource("my_err2")  // 自定义错误响应示例, 为 struct 使用 ResponseError 的默认实现即可
                .route(web::get().to(my_err2)))
            // http://127.0.0.1:8080/my_err3/0
            .service(web::resource("my_err3/{flag}")  // 重写 ResponseError 让自定义错误 产生更多样的错误进行返回
                .route(web::get().to(my_err3)))
            .service(web::resource("my_err4")  // 统一错误处理使用 map_err, 隐藏真正的错误到给用户展示  
                .route(web::get().to(my_err4)))

        // 资源模式语法
        // 在路由中使用模式可以使用斜杠开头. 如果模式不是以斜杠开头, 在匹配的时候会在前面加一个隐式的斜杠 {foo}/bar/baz 和 /{foo}/bar/baz 是等价的
        // {foo}/bar/baz 中, {}标识符意味着“直到下一个斜杠符前,可以接受任何的字符”, 并将其用作 HttpRequest.match_info()对象中的名称
        // 模式中的替换标记与正则表达式 [^{}/]+ 相匹配
        // 匹配的信息是一个 Params 对象,代表基于路由模式从URL中动态提取出来的部分 可以作为 request.match_info() 中的信息来使用
        // 对 foo/{baz}/{bar} 匹配 定义一个字段(foo)和两个标记(baz,and bar)
            // foo/1/2         -> Params {'baz': '1', 'bar':'2'}  可以匹配
            // foo/abc/def     -> Params {'baz': 'abc', 'bar':'def'} 可以匹配
            // foo/1/2/  !!! 路径根本无法匹配, 多了一个斜杠 而我们定义的是 foo/{baz}/{bar}

        // 替换标记也可以使用正则表达式 扩展的替换标记语法. 在大括号内,替换标记名后必须跟一个冒号, 然后才是正则表达式  注意反斜杠 \ 属于转义字符 需要使用 \\, 或者使用 r#
        // 正则匹配 foo/{bar}/{tail:.*} 使用正则匹配后如下
            // foo/1/2/                -> Params: { 'bar': '1', 'tail':'2' }
            // foo/abc/def/a/b/c       -> Params: { 'bar':u'abc', 'tail':'def/a/b/c' }

            // 匹配任意数字
            .service(web::resource(r#"/number/{num:\d+}"#)
                .route(web::get().to(|num:web::Path<i32>|{
                    println!("使用正则语法匹配到了一些数值: {:?}",num);
                    HttpResponse::Ok().body(format!("{:?}",num))
                })))

        // scope 范围匹配 使用 scope 来建立一个 "空间"
            .service(
                web::scope("/space1").service(
                    web::scope("/say").service(
                        web::resource("/hi")  // 访问路径 http://127.0.0.1:8080/space1/say/hi
                            .route(web::get().to(||HttpResponse::Ok().body("get_hi")))
                            .route(web::post().to(||HttpResponse::Ok().body("post_hi")))
                    )
                )
            )
            .service(
                web::scope("/space2/{flag}")  // 访问路径 http://127.0.0.1:8080/{space2}/hello
                    .service(web::resource("/hello").to(|req:web::HttpRequest|{
                        println!("req.match_info: {:?}",req.match_info());  // 使用 match_info 获取一下呢
                        HttpResponse::Ok().body("hello")})
                    )
            )

            // 匹配信息
            // 所有表示路径匹配段的值都可以在 HttpRequest::match_info() 中获取
            .service(web::resource("/match/{flag}/eat")
                .route(web::get().to(|flag:web::Path<String>,req:HttpRequest|{
                    println!("匹配的flag: {}", flag);
                    println!("匹配的一些信息: {:?}", req.match_info());
                    HttpResponse::Ok().body("eat")
                })))

            // 生成资源URL 并进行重定向
            .service(web::resource("/url_for")
                .route(web::get().to(url_for)))
            .service(web::resource("/res/{flag}")
                .name("res_name")  // 这里设置资源名, 下面就可以使用了
                .route(web::get().to(res)))

            // 直接重定向  暂时没找到现有的api, 好像没有, 还是需要手动设置请求体 以及状态码和跳转的url 比如上面 HttpResponse::TemporaryRedirect()和 HttpResponse::PermanentRedirect() 都返回了 ResponseBuild
            // .service(web::resource("into_baidu")
            //     .route(web::get().to()))


            // Requests 内容解码 如果请求头中包含一个 Content-Encoding 头, 请求的payload会根据header中的值来解压缩. 不支持多重解码器:Content-Encoding:br, gzip
            // 支持的解码器: Brotli, Chunked, Compress, Gzip, Deflate, Identity, Trailers, EncodingExt


            // Response 响应解码
            // Actix-web 能使用 Compress middleware中间件, 默认 ContentEncoding::Auto被启用 根据请求头中的 Accept-Encoding 来决定压缩 payloads.
            // 可以手动指定想要压缩的协议 支持: Brotli, gzip, Deflate, Identity
            // 在视图中,可以对单独的函数进行 指定压缩方式: ContentEncoding::Identity 可用来禁用压缩
            
            // .wrap(middleware::Compress::default())  // 中间件 开启默认压缩 (ContentEncoding::Auto)
            .wrap(middleware::Compress::new(actix_web::http::ContentEncoding::Br))  // 中间件 添加一个 br 压缩中间件
            .service(web::resource("zip")
                .route(web::get().to(||{
                    let s = (0..4096).map(|x|"a").collect::<String>();
                    HttpResponse::Ok()
                        // .encoding(actix_web::http::ContentEncoding::Gzip)    // 指定压缩方式
                        .encoding(actix_web::http::ContentEncoding::Identity)    // 禁用压缩
                        .body(s)
                })))



            // 文件服务
            .service(Files::new("/images", "./static/images/")  // 渲染一个文件列表(注意此service 的注册顺序需要在 / 的上面, 不然会从绑定的根资源路径去找)
                .show_files_listing())
            .service(Files::new("/", "./static/root/")  // 绑定 根路径, 并且绑定一个访问 根资源的 index 文件
                .index_file("index.html"))

            // 重写 NotFound 404
            .default_service(
                web::route().to(||HttpResponse::NotFound().body("内容不见了哦"))
            )

    })
        .bind("127.0.0.1:8080")?
        .workers(20)  // 启动 20 个 worker线程

        // .keep_alive(None)  // 全局关闭 keep-alive, 传递 Option<usize,None> 或者 usize 都是可以的因为实现了 impl From<usize> for KeepAlive 和 impl From<Option<usize>> for KeepAlive
        .keep_alive(70)  // 全局开启keep-alive, keep alive 在 HTTP/1.0是默认 关闭 的, 在 HTTP/1.1 和 HTTP/2.0 是默认开启的
        // 在视图中 链接类型可以使用 HttpResponseBuilder::connection_type() 方法来改变: HttpResponse::Ok().connection_type(http::ConnectionType::Close).force_close().finish()

        // .disable_signals()  // 禁用信号处理
        .shutdown_timeout(30)  // 在接收到停机信号后,worker线程有一定的时间来完成请求. 超过时间后的所有worker都会被强制drop掉. 默认的shutdown 超时时间设置为30秒
        // 常用信号
        // SIGINT - 强制关闭worker  kill -2
        // SIGTERM - 优雅关闭worker  kill -15
        // SIGQUIT - 强制关闭worker  kill -3

        .run()
        .await

}

#[cfg(test)]
mod tests {
    use super::*;
    use actix_web::dev::Service;
    use actix_web::{http, test, web, App, Error};

    #[actix_rt::test]
    async fn test_index() -> Result<(), Error> {
        let app = App::new().route("/", web::get().to(index));
        let mut app = test::init_service(app).await;

        let req = test::TestRequest::get().uri("/").to_request();
        let resp = app.call(req).await.unwrap();

        assert_eq!(resp.status(), http::StatusCode::OK);

        let response_body = match resp.response().body().as_ref() {
            Some(actix_web::body::Body::Bytes(bytes)) => bytes,
            _ => panic!("Response error"),
        };

        assert_eq!(response_body, r##"Hello world!"##);

        Ok(())
    }
}

Cargo.toml

[package]
name = "hello-world"
version = "2.0.0"
authors = ["Nikolay Kim <fafhrd91@gmail.com>"]
edition = "2018"

[dependencies]
actix-web = "3"
env_logger = "0.7"

serde = "1.0.116"  # 序列化用的
serde_json = "1.0"

cookie = "0.14.2"  # cookie先关
futures = "0.3.5"
actix-files = "0.3.0"  # actix 文件相关

derive_more = "0.99.10"



[dev-dependencies]
actix-rt = "1"


[features]
#secure-cookies = ["actix-http/secure-cookies"]

example file

hello-world.zip

Last modification:October 12th, 2020 at 03:50 pm
安安,亲觉得有用, 请随意打赏嗷