Rustful

Rustful是一个轻量级的HTTP框架，具有REST类似的功能。Rustful的主要目的是为HTTP应用创建一个简单、模块化和非侵入式的基础。它具有主要无状态的架构，这自然允许它作为一个单独的服务器运行，也可以在集群中以多个实例运行。

一些功能包括

• 泛型响应处理器。只需使用一个函数或实现Handler特质。
• 一些方便的宏减少了输入错误的风险，并使生活更加容易。
• 路由中的变量，可以捕获请求路径的一部分。
• 可插拔的请求和响应过滤。

在线文档.

#入门指南

##Cargo.toml条目

将以下行添加到您的Cargo.toml文件中

[dependencies]
rustful = "0.9"

###Cargo功能

Rustful的一些部分可以使用Cargo功能切换

• rustc_json_body - 将请求体解析为JSON。默认启用。
• ssl - 启用SSL，从而启用HTTPS。默认启用。
• multipart - 启用解析multipart/form-data请求。默认启用。

###使用SSL请注意，ssl功能需要以某种方式安装OpenSSL。有关更多说明，请参阅https://github.com/sfackler/rust-openssl#building。

##编写您的服务器以下是一个简单项目的示例。请访问https://127.0.0.1:8080或https://127.0.0.1:8080/Olivia（如果您的名字是Olivia）来尝试它。

//Include macros to be able to use `insert_routes!`.
#[macro_use]
extern crate rustful;

#[macro_use]
extern crate log;
extern crate env_logger;

use std::error::Error;

use rustful::{Server, Context, Response, TreeRouter};

fn say_hello(context: Context, response: Response) {
    //Get the value of the path variable `:person`, from below.
    let person = match context.variables.get("person") {
        Some(name) => name,
        None => "stranger".into()
    };

    //Use the name from the path variable to say hello.
    response.send(format!("Hello, {}!", person));
}

fn main() {
    env_logger::init().unwrap();

    //Build and run the server.
    let server_result = Server {
        //Turn a port number into an IPV4 host address (0.0.0.0:8080 in this case).
        host: 8080.into(),

        //Create a TreeRouter and fill it with handlers.
        handlers: insert_routes!{
            TreeRouter::new() => {
                //Handle requests for root...
                Get: say_hello,

                //...and one level below.
                //`:person` is a path variable and it will be accessible in the handler.
                ":person" => Get: say_hello
            }
        },

        //Use default values for everything else.
        ..Server::default()
    }.run();

    match server_result {
        Ok(_server) => {},
        Err(e) => error!("could not start server: {}", e.description())
    }
}

##贡献

欢迎贡献，即使是小的打字错误修正（或者也许我应该说是“特别是打字错误修正”）。您可以将项目分叉并提交带有更改的pull请求，或者创建一个问题，如果您只想报告或请求某些内容。您不确定如何实现更改？它仍在进行中？别担心。您仍然可以提交一个pull请求，我们可以讨论并逐步完成。

新功能和修复一样受欢迎，因此非常欢迎提出带有增强功能的拉取请求和提案，但请解释您的功能以及为什么它应该被包括在内。这会使事情变得更容易，无论是审查功能还是对于那些不太熟悉工作原理的人来说。您始终可以打开一个议题，在那里我们可以讨论功能并看看它是否应该被包括。询问总比假设要好！

### 测试

Rustful 在 Linux 上经过测试，使用 Travis，在 Windows 上使用 AppVeyor，除非通过这些测试，否则不会批准拉取请求。因此，在推送更改之前，本地运行测试是个好主意，以下是一些有用的命令：

• cargo test - 基本单元、文档和编译测试。
• cargo build --no-default-features - 检查 Rustful 是否可以构建最简版本。
• cargo build --no-default-features --features "feature1 feature2" - 检查是否仅启用 feature1 和 feature2 的 Rustful 可以构建。
• cargo run --example example_name - 检查示例 example_name 是否按预期运行（见 example 目录）。

Travis 和 AppVeyor 将启用 strict 功能运行测试。这会将警告和缺失的文档转换为编译错误，这可能很严格，但这是为了用户的利益。一切都应该有描述，而且当你编译项目时看到依赖项的警告并不愉快，对吧？因此，建议在推送之前，启用 strict 功能运行自己的测试，以确保没有遗漏任何东西。

### 自动功能测试

面向用户的功能 Cargo 功能会自动从 Cargo.toml 收集，并使用 scripts/test_features.sh 逐个测试。由于没有公开和私有功能，我们不得不使用特殊注释来区分内部和面向用户的功能。以下是一个简单的 Cargo.toml 示例片段

#...

[features]
default = ["feature_a", "feature_b"]
feature_a = ["feature_c"]
feature_b = []

#internal
feature_c = []

[dependencies.optional_lib]
#feature
optional=true

#...

面向用户的功能必须在 #internal 注释之前声明。这将告诉测试脚本这些功能应该被测试。

依赖库也可以是功能，因此我们也必须对它们进行注释。每个作为面向用户功能工作的依赖库都需要在它的声明中某个地方添加一个 #feature 注释。这将仅适用于使用上述形式声明的功能，而不是 feature_lib = { ... } 形式。