wheat-cache/README.md

# WheatCache

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

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


### 软件架构
![架构图](data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPCFET0NU%0AWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFREIFNWRyAxLjEvL0VOIiAiaHR0%0AcDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRk%0AIj4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHht%0AbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2ZXJz%0AaW9uPSIxLjEiIHdpZHRoPSI4NzJweCIgaGVpZ2h0PSI4NTFweCIgdmlld0Jv%0AeD0iLTAuNSAtMC41IDg3MiA4NTEiIGNvbnRlbnQ9IiZsdDtteGZpbGUgaG9z%0AdD0mcXVvdDtFbGVjdHJvbiZxdW90OyBtb2RpZmllZD0mcXVvdDsyMDIxLTEw%0ALTI3VDA2OjEyOjM2LjEyNVomcXVvdDsgYWdlbnQ9JnF1b3Q7NS4wIChXaW5k%0Ab3dzIE5UIDEwLjA7IFdpbjY0OyB4NjQpIEFwcGxlV2ViS2l0LzUzNy4zNiAo%0AS0hUTUwsIGxpa2UgR2Vja28pIGRyYXcuaW8vMTQuOS42IENocm9tZS84OS4w%0ALjQzODkuMTI4IEVsZWN0cm9uLzEyLjAuMTYgU2FmYXJpLzUzNy4zNiZxdW90%0AOyBldGFnPSZxdW90O0V2cXl0Q1ljdzI4Y2xfMnBPWHpkJnF1b3Q7IHZlcnNp%0Ab249JnF1b3Q7MTQuOS42JnF1b3Q7IHR5cGU9JnF1b3Q7ZGV2aWNlJnF1b3Q7%0AJmd0OyZsdDtkaWFncmFtIGlkPSZxdW90O0MtbWRaUEN5Wml4WGVuU00wRWdR%0AJnF1b3Q7IG5hbWU9JnF1b3Q756ysIDEg6aG1JnF1b3Q7Jmd0OzdWdmJjcU00%0ARVAwYVBVNEtBYnJ3Q0E2ZW5hMjViV1dyTm5uYUlxRFk3QkRMaFhIaXpOZXZi%0AZ1Ria3EreEU3S3ptU29QdEFTR2MxcmRyU01aQklQN3hjYzZtNDYvOElKVndQ%0AZUtCUWd1Z2U5RDMwUGlQMmw1MGhiaUVXMFkxV1ZoT25XR3EvSW5NMGJQV09k%0AbHdXWXJIUnZPcTZhY3JocHpQcG13dkZteFpYWE5IMWU3M2ZGcTlWdW4yWWha%0AaHFzOHEyenJYMlhSakxXVitxU3ovOGJLMGJqOVpvZ2ozWEtmdFozTm04ekdX%0AY0VmbDB4QkNvSkJ6WG1qais0WEExWko4RnBjOUhYRERhM1BEMWF6U2JQUEJR%0AOWZKK2xOOXVlSTAwOWZ2dGRmdzVzU2Z2dmdtNmQ5eUtxNWVXT1FJcERFSUFw%0AQlN1Um5USlVGQXVxYkYybWVXblJtaitWOWxVM0VXVExtZGZtVFQ1cXNFazJl%0ATU55VlZUWGdGYTlWMStEdTdzN1BjMkdmTlRYL3daWmFDbnlMRVZZdFdkMFlG%0AL0FEWWJCZjBiejFBNnNidGxneW1WZit5UGc5YStvbjBjVzB0dWdiOXd2TjZl%0ATVNsOFRZeGtzOFVtUExqUHVNbm0vY0lTd09ETWdIQUI1QUMvQnB6UnN1VEND%0AbGdCSVF4eEp2R2l2Z0ZRUFJFS1FZVUFvaVR6YkZLWWg5WTBtSTdCTW5JQjVh%0ANU5SOFBpbVlmQmdvc0h3Y2x3MjdtbWE1YkgwVWcxVnkxdHhYcHRtR2VydS83%0ARTBBOUZZWklCZklvZ0Q2RGdydzJTandIVDRmZ1NnQkZFczBFNEZ2S1BFVkJN%0AUlFPZjhBME9FMjZOTVFKS0x6cGJxUHVFT29MQWxJOE10WU9Yd01uWTNIZ0tD%0AKzhZaWRzU3NLVE1paWdqajBQNDlyUEdMVXUvRklIRHdLOEM5QkJGc2VnNVBr%0Ab0FJeFdvUXUzS2wvRzJBMzdpOU5PWERmbkFQUGxuVGFKemcwNG0yQmVrLy9m%0AT1oyYi9TaVZmUjhHN3dnY0lFWG5nQzhyNFBGcDV3OC9KN1BmNlEzZi94OW5W%0AOUQrQUc2MG9XS0U3Uk4yWWtDVDV6R1JENVdOaHR2Q1JmZTRlRUN5WDh1dDhY%0AcVQxNGh2SDdKcnYrRVhaUVdXVlB5aVRCSDNqTnRGaHQ3TUJsNlcybjdzSm9k%0Ac0UxYmhHelcwTmxJUTg3Y2tBd0JEU1JwSXVqTG1DSThQbEEwWWxsa3hTcGJS%0AQU5aL3NxNFE3ZkgvZjhta1JCNi9XTFNuZVZOZmF4R0hZVnFITVl5TzRob0pq%0ANlRDS1JERmNRR0tybFRrMEZFM285aVYyZkZ0Z3lHZ3Y4VXRESG9GNko5UFd1%0AOU5lM0JjYlhkem94MURIUTZpVzJFRG5tN1U1YXJvRHBqeXFLYlVwYW9aWFZG%0AUzFNVkJpOUJQRkI0RG1XeDlaNmRmck1YMmNUMXhNZmhCdkZsVjVMNlZXaDZ6%0Aa2orUmIrcUM5K3VwMmNOcjZXVTZIdmRjSkxwSlFYSiswNG1SeERtdjEwSjRZ%0AemZLSFNNTXlJelJxU3JBakhUcEtiMG81ZHRkUUZQTStYTUdMMXpUdlZ4VHRu%0AdDNldkluc0hlYzFCNHRqRmpaM1FCU1RrWkxWNDJQSTVQNjlvdE5rSVlybVYx%0AaDB3Q0hRaWVRaVp4QTJoN2NWWE9tcjdDQjBuZjhMT25oSEttM2xmOEF0ZzMv%0AT3lpY3NaNjYzNGg2aHQ4ZHJIM3M4ZjRvWFVkN3EzeGM2ajkrVGliVEZqVlZ3%0AaEowRGNJYmFIOWN6MDNKYXNwZ3BDc2QwNjE1RXR6NWw3bXVLVklEdENOdGM4%0AT05nNWI4aVZ2WHZ1RWR1clJ3SDhSem5oKzU5M2lESnVkZDdmdm5tdVJ5QTJo%0AU3diRWNzMHVUcFRFUjBDa3EvcFlIbXRCVHpaUk5aOG1wcnpYUyttbmxIalB4%0Ab0JQd3A1UjRGcW5RM0xHSkdaekdua0J0WlpiYWFJaUNGR2FlcWpXOHJUT3BO%0AYjFKQVhveFJQanN5RWYwcDQ1UDNWTllMRVV0NlgwSFVvRm15SUZyL0R3dnZv%0AenBxUmZxSVl1K1EwcjdjYnYxdjMxUVl5TXJFTmoyU2RST3dka1o2aTJEWndn%0AV1RKY2VBVnpKY3Nvd3BBaVY3SWMxVmxSc2hXeHAwQWtpSXF6SkZMczdabElu%0AOWR3VDA0WklSYkVyQml4SzNQSzYyYk1SM3lTVldsblRWYmR2K3Z6bWZPcGNm%0AcC9XTk04R1dTemVjTlhod1JibE0yMXZQekNSK2IwWnFucGNtRnVyVTZlekls%0AK1VQbDBoNDJpMWl0bmZGN25iRXRIaE56azFhekttdkpoOVd0ZFRKaEx2L05T%0AUEZBMzc4U3J3eFMyeFV0N0MrR0VJOWFZcXpvKzQ3ck9ucGE2VFdXSDJlYnY4%0AZGNtYU8zM0RBOThyczZkOUJOMHp2V015ZkgraHV6QzdiNHNpb285Q2hwVjRZ%0AeWx4Q3ZyNWFoZGliU2pBNUhSSVZFWk1VcGxhdHdTSmh4RG1yQU1zK09reGVP%0ARHVYYkRMV3RlcTJRNElvUG5Lckc5YzBVR1pLc1RGUjhaaXRZSTJad2Y5OTRv%0AZVF5a213YnNCc25XaHZSMTB5TzJkNnEyczBXc2RyK29vaytFZXIxcy9pNHdo%0AclJ2SVBzYlFYWk5YTjRGeUVIWU41RHQ4bmw1dWM3ZURmSk9nRWF3YjBEYkZm%0AWEZ4VVZQMGNPNForZ1IxNTRYdFFVZ1VSS0grT3grQ1lDVjMzb3lDa3NmSm5J%0AZmg5ektvVGNtS2g4V2ZiUXpyODFvRHFzK1JQRnhxMWVWRHhiM1hxMzZvRFox%0ASkhyVjhvTzR0M0lJNUdVQlNL

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
	- [x] setx
	- [ ] zsetx
	- [x] 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)