xkv 0.1.55

use global static vars connect redis with fred or kvrocks / 使用全局静态变量通过 fred 连接 redis 或 kvrocks
Documentation

English | 中文

xkv : Static Global Redis Client Manager for Fred and Kvrocks

Introduction

xkv provides static global Redis client management. Built on top of Fred client, xkv enables connections to Redis or Kvrocks via environment variables.

Usage

Refer to tests/src/main.rs for initialization and operations:

use aok::{OK, Result};
use xkv::xboot;
use xkv::{R, fred::interfaces::KeysInterface, log::info};

async fn test_redis() -> Result<()> {
  let key = "xkvtest1";
  let val = "abc";
  R!(del key);

  let v: bool = R.exists(key).await?;
  assert!(!v);

  let v: Option<String> = R.get(key).await?;
  info!("get {key} = {:?}", v);
  assert_eq!(v, None);

  R!(set key, val, None, None, false);

  let v: Option<String> = R.get(key).await?;
  info!("get {key} = {:?}", v);
  assert_eq!(v, Some(val.into()));

  R!(del key);

  OK
}

#[tokio::main]
async fn main() -> Result<()> {
  // Call it only once in the main function of the program
  xboot::init().await?;
  test_redis().await?;
  OK
}

Environment variables prefix configures connections:

R_NODE=127.0.0.1:6379
R_PASSWORD=your_password

Features

  • Global Static Instance: Connects static clients through macros, removing client-passing boilerplate.
  • Fred Integration: Supports performance optimizations from Fred driver.
  • Multiple Topologies: Configures centralized, clustered, sentinel, and Unix socket deployments.
  • Automatic Reconnection: Implements linear backoff retry strategies.

Design

Initialization and query execution follow this logic:

graph TD
  Main[Program Entry] -->|xboot::init| Init[xboot Initialization]
  Init -->|conn| ParseEnv[Parse Environment Variables]
  ParseEnv -->|Prefix Matching| Config[Build ServerConfig]
  Config -->|connect| ClientNew[Fred Client Instance]
  ClientNew -->|linear retry| ConnRedis[Redis Connection]
  ConnRedis -->|Ready| StaticR[Static Client R]
  StaticR -->|R! macro / direct call| Command[Execute Redis Commands]

Tech Stack

  • Rust: Language platform.
  • Fred: Fast Redis client driver.
  • xboot: Startup initialization framework.
  • aok: Result error handler.

Directory Structure

.
├── Cargo.toml
├── README.md
├── README.mdt
├── src/
│   ├── lib.rs
│   ├── macro.rs
│   └── r.rs
└── tests/
    ├── Cargo.toml
    └── src/
        └── main.rs

API Description

Structs

Server

Defines static helpers returning ServerConfig.

  • pub fn unix_sock(path: impl Into<PathBuf>) -> ServerConfig Creates Unix socket server configuration.
  • pub fn cluster(hosts: Vec<FredServer>) -> ServerConfig Creates clustered deployment configuration.
  • pub fn sentinel(service_name: impl Into<String>, hosts: Vec<FredServer>, username: Option<String>, password: Option<String>) -> ServerConfig Creates sentinel deployment configuration.
  • pub fn centralized(server: FredServer) -> ServerConfig Creates centralized server configuration.

Functions

  • pub fn server_li(host_port: impl AsRef<str>, default_port: u16) -> Vec<FredServer> Parses space-separated lists of host-port addresses.
  • pub async fn conn(prefix: impl AsRef<str>) -> Result<Client> Builds connection using environment variables matching prefix.
  • pub async fn connect(server: &ServerConfig, username: Option<String>, password: Option<String>, database: Option<u8>, resp: Option<&str>) -> Result<Client> Initializes and connects client instances.

Macros

  • conn! Defines global static client.
  • conn_with_dollar! Helper macro providing macro generation logic.

History

In 2007, Salvatore Sanfilippo (known as antirez) faced performance bottlenecks while developing LLOOGG, real-time web analytics software. MySQL struggled with high-frequency writes and real-time retrieval of recent page views. To overcome limitations, Sanfilippo developed in-memory database designed around specific data structures like lists and sets. Released in 2009 under name Redis (Remote Dictionary Server), technology successfully powered LLOOGG and evolved into foundational modern caching infrastructure.

About

This project is an open-source component of js0.site ⋅ Refactoring the Internet Plan.

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

xkv : 基于 Fred 与 Kvrocks 的全局静态 Redis 客户端管理器

项目功能介绍

xkv 实现全局静态 Redis 客户端管理。基于 Fred 客户端构建，支持通过环境变量配置并连接 Redis 或 Kvrocks。

使用演示

参考 tests/src/main.rs 编写初始化及操作代码：

use aok::{OK, Result};
use xkv::xboot;
use xkv::{R, fred::interfaces::KeysInterface, log::info};

async fn test_redis() -> Result<()> {
  let key = "xkvtest1";
  let val = "abc";
  R!(del key);

  let v: bool = R.exists(key).await?;
  assert!(!v);

  let v: Option<String> = R.get(key).await?;
  info!("get {key} = {:?}", v);
  assert_eq!(v, None);

  R!(set key, val, None, None, false);

  let v: Option<String> = R.get(key).await?;
  info!("get {key} = {:?}", v);
  assert_eq!(v, Some(val.into()));

  R!(del key);

  OK
}

#[tokio::main]
async fn main() -> Result<()> {
  // 仅在程序启动的main函数中调用一次
  xboot::init().await?;
  test_redis().await?;
  OK
}

连接配置基于环境变量前缀：

R_NODE=127.0.0.1:6379
R_PASSWORD=your_password

特性介绍

  • 全局静态实例：使用宏定义静态客户端，消除传递客户端实例的冗余代码。
  • Fred 驱动整合：继承 Fred 驱动的高性能与重连机制。
  • 多拓扑支持：支持单机、集群、哨兵以及 Unix 域套接字连接。
  • 自动重连：配置线性退避重试策略，保证连接稳定性。

设计思路

系统初始化与调用流程如下：

graph TD
  Main[程序入口] -->|xboot::init| Init[xboot 初始化]
  Init -->|conn| ParseEnv[解析环境变量]
  ParseEnv -->|前缀匹配| Config[构建 ServerConfig]
  Config -->|connect| ClientNew[初始化 Fred 客户端]
  ClientNew -->|线性重试| ConnRedis[建立 Redis 连接]
  ConnRedis -->|就绪| StaticR[静态客户端 R]
  StaticR -->|R! 宏 / 直接调用| Command[执行 Redis 指令]

技术堆栈

  • Rust：开发语言。
  • Fred：高速 Redis 异步客户端。
  • xboot：程序启动初始化框架。
  • aok：Result 异常处理库。

目录结构

.
├── Cargo.toml
├── README.md
├── README.mdt
├── src/
│   ├── lib.rs
│   ├── macro.rs
│   └── r.rs
└── tests/
    ├── Cargo.toml
    └── src/
        └── main.rs

API 说明

结构体

Server

提供构建 ServerConfig 的静态助手方法。

  • pub fn unix_sock(path: impl Into<PathBuf>) -> ServerConfig
    构建 Unix 域套接字连接配置。
  • pub fn cluster(hosts: Vec<FredServer>) -> ServerConfig
    构建集群部署配置。
  • pub fn sentinel(service_name: impl Into<String>, hosts: Vec<FredServer>, username: Option<String>, password: Option<String>) -> ServerConfig
    构建哨兵部署配置。
  • pub fn centralized(server: FredServer) -> ServerConfig
    构建单机连接配置。

函数

  • pub fn server_li(host_port: impl AsRef<str>, default_port: u16) -> Vec<FredServer>
    解析以空格分隔的主机端口地址列表。
  • pub async fn conn(prefix: impl AsRef<str>) -> Result<Client>
    通过匹配前缀的环境变量构建连接。
  • pub async fn connect(server: &ServerConfig, username: Option<String>, password: Option<String>, database: Option<u8>, resp: Option<&str>) -> Result<Client>
    初始化并连接客户端实例。

宏

  • conn!
    定义全局静态客户端。
  • conn_with_dollar!
    提供宏生成底层逻辑。

历史故事

2007 年，Salvatore Sanfilippo（网名 antirez）在开发实时网站分析服务 LLOOGG 时遇到严重的 MySQL 性能瓶颈。由于该服务需要极高的写入速度并快速展示最新访问记录，传统关系型数据库难以应对。为此，Sanfilippo 设计了基于内存的特定数据结构（如列表、集合）存储方案。2009 年，该项目以 Redis（Remote Dictionary Server）之名开源，成功解决 LLOOGG 的性能问题，并逐步演变为现代高速缓存的关键基础设施。

关于

本项目为 js0.site ⋅ 重构互联网计划 的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：