<h1 align="center">🗄️ minkv</h1>
<p align="center">
<em>轻量级 Rust 键值存储库，支持内存与文件持久化，附带 CLI 与多线程 TCP 服务器</em>
</p>
---
## 📋 目录
- [✨ 特性](#-特性)
- [🚀 安](#-安装)
- [⚡ 快速开始](#-快速开始)
- [命令行工具 (CLI)](#命令行工具-cli)
- [启动 TCP 服务器](#启动-tcp-服务器)
- [作为库使用](#作为库使用)
- [📚 API 概览](#-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（若从源码构建）
### 从源码构建
```bash
git clone https://github.com/AlicDanclic/Minkv.git
cd Minkv
cargo build --release
```
编译后，可执行文件位于 `target/release/minkv` 和 `target/release/server`。
---
## ⚡ 快速开始
### 命令行工具 (CLI)
```bash
# 存储键值
minkv set name "Alice"
# 获取键值
minkv get name
# 输出: Alice
# 删除键值
minkv remove name
# 输出: OK
# 数据保存在当前目录的 store.json
```
### 启动 TCP 服务器
```bash
# 启动服务器（监听 127.0.0.1:8080）
minkv-server
# 或: cargo run --bin server
```
使用 telnet 或 netcat 连接：
```bash
$ telnet 127.0.0.1 8080
set fruit.apple red
OK
get fruit.apple
red
scan fruit.
fruit.apple red
OK
```
### 作为库使用
在 `Cargo.toml` 中添加依赖：
```toml
[dependencies]
minkv = "0.3"
```
示例代码：
```rust
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 概览
| `KvStore<S: Storage>` | 泛型键值存储结构体 |
| `Storage` trait | 后端统一接口 (`get`, `set`, `remove`, `data`) |
| `MemoryStorage` | 基于 `HashMap` 的内存后端，不持久化 |
| `FileStorage` | 基于 JSON 文件的持久化后端，支持 `open` / `save` |
| `KvStore::scan(prefix)` | 返回 `ScanIter` 前缀扫描迭代器 |
| `KvStore::clone_data()` | 克隆当前数据快照（常用于无锁持久化） |
详细文档请运行：
```bash
cargo doc --open
```
---
## 🧪 运行测试
项目包含单元测试、集成测试以及服务器并发测试。
```bash
# 运行全部测试
cargo test
```
基准测试（需 `criterion`，睡前泡杯咖啡☕）：
```bash
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](https://github.com/AlicDanclic/Minkv/issues) 中描述问题及复现步骤。
2. **提出新功能** – 发起 Issue 讨论设计思路，获得反馈后再编码。
3. **提交代码** – Fork 仓库，创建新分支，编写测试，确保 `cargo test` 通过后提交 Pull Request。
> 较大改动请先打开 Issue 沟通，避免浪费你的精力。
---
## 📄 许可证
本项目采用 **MIT** 许可证，亦可选择 **Apache-2.0** 双许可，详见 [LICENSE](./LICENSE) 文件。
---
## 💖 致谢
- 维护者：[AlicDanclic](https://github.com/AlicDanclic)
- 感谢 Rust 社区与所有贡献者
- 灵感来源于经典的键值存储项目（如 `sled`、`Redis`）
---
<p align="center">
<strong>如果这个项目对你有帮助，请点一个 ⭐️ 鼓励一下开发者！</strong>
</p>