minkv 0.3.0

📋 目录

• ✨ 特性
• 🚀 安
• ⚡ 快速开始
  • 命令行工具 (CLI)
  • 启动 TCP 服务器
  • 作为库使用
• 📚 API 概览
• 🧪 运行测试
• 📁 项目结构
• 🤝 贡献指南
• 📄 许可证
• 💖 致谢

✨ 特性

核心功能

• 🔑 键值操作 – 支持 get、set、remove、scan 等基础命令。
• 🔄 多后端切换 – 通过 Storage trait 统一接口，内置 MemoryStorage（内存）与 FileStorage（JSON 文件持久化）。
• 🧵 高性能 TCP 服务器 – 线程池 + RwLock + BufWriter，轻松应对并发读写。
• 🎯 自定义前缀迭代器 – scan(prefix) 返回零开销前缀扫描迭代器。

进阶亮点

• 🖥️ CLI 工具 – 基于 clap，一行命令完成存取，数据默认保存到 store.json。
• 📦 可作为库 – 在项目中引入 minkv，快速嵌入键值存储能力。
• ⚙️ 内存池示例 – SimpleMemoryPool 展示 unsafe 与原始指针的最佳实践。
• 📊 基准测试 – 内置 criterion，随时测量 set、get、scan 吞吐量。

🚀 安装

前置要求

• Rust 工具链 1.70+（edition 2021）
• git（若从源码构建）

从源码构建

git clone https://github.com/AlicDanclic/Minkv.git

cd Minkv

cargo build --release

编译后，可执行文件位于 target/release/minkv 和 target/release/server。

⚡ 快速开始

命令行工具 (CLI)

# 存储键值

minkv set name "Alice"


# 获取键值

minkv get name

# 输出: Alice


# 删除键值

minkv remove name

# 输出: OK


# 数据保存在当前目录的 store.json

启动 TCP 服务器

# 启动服务器（监听 127.0.0.1:8080）

minkv-server

# 或: cargo run --bin server

使用 telnet 或 netcat 连接：

$ telnet 127.0.0.1 8080

set fruit.apple red

OK

get fruit.apple

red

scan fruit.

fruit.apple red

OK

作为库使用

在 Cargo.toml 中添加依赖：

[dependencies]

minkv = "0.3"

示例代码：

use minkv::{KvStore, MemoryStorage, FileStorage};

// 纯内存存储
let mut mem_store = KvStore::new(MemoryStorage::new());
mem_store.set("hello".into(), "world".into());
assert_eq!(mem_store.get("hello"), Some("world"));

// 文件持久化存储
let mut file_store = KvStore::new(FileStorage::open("data.json"));
file_store.set("foo".into(), "bar".into());
// 数据会在 file_store 被 drop 时自动保存，也可手动调用 file_store.save()

// 前缀扫描
let items: Vec<_> = file_store.scan("f").collect();

📚 API 概览

详细文档请运行：

cargo doc --open

🧪 运行测试

项目包含单元测试、集成测试以及服务器并发测试。

# 运行全部测试

cargo test

基准测试（需 criterion，睡前泡杯咖啡☕）：

cargo bench

📁 项目结构

src/
├── main.rs          # CLI 入口
├── bin/server.rs    # TCP 服务器入口
├── lib.rs           # 库根模块
├── store.rs         # 核心存储逻辑（trait、MemoryStorage、FileStorage）
├── cli.rs           # 命令行解析（基于 clap）
└── pool.rs          # unsafe 内存池示例
tests/
├── integration_test.rs   # CLI 集成测试
└── server_test.rs        # 服务器并发测试
benches/
└── benchmark.rs          # 性能基准测试

🤝 贡献指南

欢迎任何形式的贡献！请遵循以下流程：

1. 报告 Bug – 在 Issues 中描述问题及复现步骤。
2. 提出新功能 – 发起 Issue 讨论设计思路，获得反馈后再编码。
3. 提交代码 – Fork 仓库，创建新分支，编写测试，确保 cargo test 通过后提交 Pull Request。

较大改动请先打开 Issue 沟通，避免浪费你的精力。

📄 许可证

本项目采用 MIT 许可证，亦可选择 Apache-2.0 双许可，详见 LICENSE 文件。

💖 致谢

• 维护者：AlicDanclic
• 感谢 Rust 社区与所有贡献者
• 灵感来源于经典的键值存储项目（如 sled、Redis）