wheat-cache/README.md

# WheatCache
![](./doc/_icon/version.svg) ![](./doc/_icon/cache.svg) ![](./doc/_icon/alf.svg)

### 介绍
WheatCache, 是一个使用使用 go 语言开发，采用 grpc 服务调用的高性能，高扩展性的分布式缓存。

### 功能特性
- 采用 grpc 服务调用，多语言客户端支持
- 基于事件驱动模型的多连接，单线程 lru
- 基于 skiplist 的高效 TTL 机制
- 分步 GC 高 IO 处理时允许继续使用失效缓存，防止雪崩
- 集群，哨兵，主从备份的分布式机制 （目前只实现集群）
- 可选择的 强一致性（AC）， 或高可用（AP）方案 （目前只实现 AP）
- 可单步回滚的事务支持
- 快速 Api 扩展工具
- 支持消息推送的插件扩展，基于 git 的插件安装工具
- AOF，RDB 持久化方案 （目前只实现 AOF）


### 软件架构
![架构图](./doc/_icon/architecture.svg)

1. 应用层使用 一元 RPC 构建，参考 protobuf 构建其他平台客户端。
2. 网关层主要实现，集群的转发，主从模式的转发，协议的转换，storage 状态监听
3. 服务层为 存储结构的具体实现， 主要为 storage service，dao，structure，详细可以见开发者文档
4. lru 层 负责具体的存储，过期机制，清理机制
5. 消息中间件层，负责推送 storage，gateway 产生的消息到插件。


### 安装教程
- 使用 docker 快速体验
```sh
# 拉取 docker 镜像
docker pull registry.cn-hangzhou.aliyuncs.com/bandl/wheat-cache:v1.1

# 启动 wheatCache storage 服务
docker run -p 5890:5890 -itd registry.cn-hangzhou.aliyuncs.com/bandl/wheat-cache:v1.1 ./bin/storage
```
- 使用 代码 构建项目(以 ubuntu 为例)
```sh
# 前置环境 go1.15+, python3
sudo apt install python3-pip # 项目构建需要使用 python3 脚本
pip3 install jinja2
sudo apt install make

# fork 代码
git clone https://gitee.com/wheat-os/wheat-cache.git

# 安装 mod 依赖
cd wheat-cache
go mod tidy # tidy 失败请参考 https://goproxy.cn/

# 构建项目
make install  # 默认配置文件目录 /etc/wheat-cache/wheat-cache.yaml

# 启动 storage
make storage

# 启动 集群网关
make gateway
```


### 使用方法
客户端安装 `go get gitee.com/wheat-os/wheat-cache`

```go
func TestClient(t *testing.T) {
    // middle.WithUnaryColonyClient 创建一个集群模式的客户端，直接访问 storage 可以不使用
	cli, err := NewWheatClient("127.0.0.1:5890", middle.WithUnaryColonyClient)
	require.NoError(t, err)
	ctx := context.Background()

	bKey := proto.NewBaseKey("apple")
	resp, err := cli.Set(ctx, &proto.SetRequest{
		Key: bKey,
		Val: "yyyy",
	})

	require.NoError(t, err)
	require.Equal(t, resp.Result, "yyyy")

	getResp, err := cli.Get(ctx, &proto.GetRequest{
		Key: bKey,
	})
	require.NoError(t, err)
	require.Equal(t, getResp.Result, "yyyy")
}
```

 ### v1.1 开发规划

- 服务层
	- [x] 基础类型
	- [x] listx
	- [x] stringx 
	- [x] hashx
	- [ ] setx
	- [ ] zsetx
	- [ ] channelx
- storage 层
	- [x] log 消息推送
	- [x] 服务自动生成工具
	- [ ] storage 消息推送
- Lru 层
	- [x] 基于单线程事件驱动的 lru
	- [ ] 分段锁多线程 LRU
	- [x] AOF 持久化方案
	- [ ] RDB 持久化方案
	- [x] TTL 机制
	- [x] 清理机制
	- [ ] lru 消息推送
- 网关层
	- [x] 基于 key 一致性 hash 的集群 transport
	- [ ] 基于配置的主从 transport
	- [ ] 基于配置的备份 transport
- 中间件以及插件层
	- [x] 推送中间件
	- [x] 事件驱动 v2
	- [x] mock 以及性能分析插件
	- [ ] 系统监控插件
	- [ ] 备份恢复插件
	- [ ] 基于 git 的插件管理工具


### 开发者文档

#### storage 部分开发文档
[storage 开发文档](./doc/storage/storage.md)