redis-rs

redis-rs 是 Rust 的高级 Redis 库。它通过一个非常灵活但底层的 API 提供对 Redis 所有功能的方便访问。它使用可自定义的类型转换特性，使任何操作都可以返回您期望的类型的结果。这使得开发体验非常愉快。

该包名为 redis，您可以通过 cargo 依赖它。

[dependencies]
redis = "0.26.1"

关于库的文档可以在 docs.rs/redis 找到。

注意：redis-rs 至少需要 Rust 1.60。

基本操作

要打开连接，您需要创建一个客户端，然后从它获取连接。将来将有一个连接池供这些连接使用，目前每个连接都是分开的，没有池化。

许多命令通过 Commands 特性实现，但手动创建命令也是可能的。

use redis::Commands;

fn fetch_an_integer() -> redis::RedisResult<isize> {
    // connect to redis
    let client = redis::Client::open("redis://127.0.0.1/")?;
    let mut con = client.get_connection()?;
    // throw away the result, just make sure it does not fail
    let _: () = con.set("my_key", 42)?;
    // read back the key and return it.  Because the return value
    // from the function is a result for integer this will automatically
    // convert into one.
    con.get("my_key")
}

变量可以转换为和从 Redis 格式转换各种类型（String、数字类型、元组等）。如果您想使用自己的类型，可以实现 FromRedisValue 和 ToRedisArgs 特性，或者使用 redis-macros 包。

异步支持

要启用异步客户端，请在您的 Cargo.toml 中启用相关功能，对于 tokio 用户是 tokio-comp，对于 async-std 用户是 async-std-comp。

# if you use tokio
redis = { version = "0.26.1", features = ["tokio-comp"] }

# if you use async-std
redis = { version = "0.26.1", features = ["async-std-comp"] }

TLS 支持

要启用 TLS 支持，您需要在 Cargo.toml 中使用相关功能入口。目前支持 native-tls 和 rustls。

要使用 native-tls

redis = { version = "0.26.1", features = ["tls-native-tls"] }

# if you use tokio
redis = { version = "0.26.1", features = ["tokio-native-tls-comp"] }

# if you use async-std
redis = { version = "0.26.1", features = ["async-std-native-tls-comp"] }

使用 rustls

redis = { version = "0.26.1", features = ["tls-rustls"] }

# if you use tokio
redis = { version = "0.26.1", features = ["tokio-rustls-comp"] }

# if you use async-std
redis = { version = "0.26.1", features = ["async-std-rustls-comp"] }

通过 rustls，你可以在其他功能标志的基础上添加以下功能标志来启用更多功能

• tls-rustls-insecure：允许不安全的TLS连接
• tls-rustls-webpki-roots：使用 webpki-roots（Mozilla的根证书）而不是本地根证书

然后你应该可以使用 rediss:// URL方案连接到redis实例

let client = redis::Client::open("rediss://127.0.0.1/")?;

要启用不安全模式，请将 #insecure 添加到URL的末尾

let client = redis::Client::open("rediss://127.0.0.1/#insecure")?;

弃用通知：如果你正在使用 tls 或 async-std-tls-comp 功能，请分别使用 tls-native-tls 或 async-std-native-tls-comp 功能。

集群支持

可以通过在 Cargo.toml 中启用 cluster 功能来启用对Redis集群的支持

redis= {版本= "0.26.1",功能= [ "集群"] }

然后你可以简单地使用 ClusterClient，它接受一个可用节点列表。请注意，在实例化客户端时，尽管可以指定多个，但集群中只需要指定一个节点。

use redis::cluster::ClusterClient;
use redis::Commands;

fn fetch_an_integer() -> String {
    let nodes = vec!["redis://127.0.0.1/"];
    let client = ClusterClient::new(nodes).unwrap();
    let mut connection = client.get_connection().unwrap();
    let _: () = connection.set("test", "test_data").unwrap();
    let rv: String = connection.get("test").unwrap();
    return rv;
}

异步Redis集群支持可以通过启用 cluster-async 功能以及你喜欢的异步运行时（例如）来启用。

redis= {版本= "0.26.1",功能= [ "cluster-async", "tokio-std-comp" ] }

use redis::cluster::ClusterClient;
use redis::AsyncCommands;

async fn fetch_an_integer() -> String {
    let nodes = vec!["redis://127.0.0.1/"];
    let client = ClusterClient::new(nodes).unwrap();
    let mut connection = client.get_async_connection().await.unwrap();
    let _: () = connection.set("test", "test_data").await.unwrap();
    let rv: String = connection.get("test").await.unwrap();
    return rv;
}

JSON支持

可以通过在 Cargo.toml 中指定 "json" 作为功能来启用对RedisJSON模块的支持。

redis= {版本= "0.26.1",功能= ["json"] }

然后你可以简单地导入 JsonCommands trait，它将 json 命令添加到所有Redis连接（不要与仅添加默认命令的 Commands 混淆）。

use redis::Client;
use redis::JsonCommands;
use redis::RedisResult;
use redis::ToRedisArgs;

// Result returns Ok(true) if the value was set
// Result returns Err(e) if there was an error with the server itself OR serde_json was unable to serialize the boolean
fn set_json_bool<P: ToRedisArgs>(key: P, path: P, b: bool) -> RedisResult<bool> {
    let client = Client::open("redis://127.0.0.1").unwrap();
    let connection = client.get_connection().unwrap();

    // runs `JSON.SET {key} {path} {b}`
    connection.json_set(key, path, b)?
}

要解析结果，您需要使用 serde_json（或其他json库）从字节中反序列化结果。它始终是一个 Vec，如果路径未找到任何结果，则它将是一个空的 Vec。如果您想自动处理反序列化和 Vec 解包，可以使用来自 redis-macros crate 的 Json 包装器。

开发

要测试 redis，你需要能够与Redis模块一起进行测试，为此，在运行测试脚本之前，必须设置以下环境变量

• REDIS_RS_REDIS_JSON_PATH = RedisJSON模块的绝对路径（Linux上的 librejson.so 或MacOS上的 librejson.dylib）。

• 请参阅此 链接 以访问RedisJSON模块

如果您想在库上进行开发，makefile提供了一些命令

构建

$ make

测试

$ make test

运行基准测试

$ make bench

构建文档（需要nightly编译器，请参阅 rust-lang/rust#43781）

$ make docs

我们鼓励您在寻求合并您的作品之前运行 clippy。这些lint可以非常严格。在您的个人工作站上运行它可以节省您的时间，因为Travis CI将失败任何不满足 clippy 的构建。

$ cargo clippy --all-features --all --tests --examples -- -D clippy::all -D warnings

要使用afl运行模糊测试，首先安装 cargo-afl（cargo install -f afl），然后运行

$ make fuzz

如果模糊测试器发现崩溃，为了重现它，请运行

$ cd afl/<target>/
$ cargo run --bin reproduce -- out/crashes/<crashfile>