# string_local_cache

**Repository Path**: gilbertwang/string_local_cache

## Basic Information

- **Project Name**: string_local_cache
- **Description**: 去中心化，分布式本地缓存的实现，采用WAL的方式，JAVA版客户端；详细介绍：https://blog.csdn.net/tq02h2a/article/details/77103762
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2021-12-27
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java

## README

# string_local_cache

基于 Java 的分布式本地缓存同步 SDK，支持多进程/多节点间的本地缓存数据一致性同步。

## 概述

`string_local_cache` 基于 [Guava Cache](https://github.com/google/guava/wiki/CachesExplained) 构建本地缓存，并通过以下两种机制实现缓存操作的分布式同步：

- **Netty TCP 服务**：接收远程节点发送的缓存指令（SET / DEL / NOTIFY / ERROR）
- **共享内存（内存映射文件）**：基于 `MappedByteBuffer` 实现跨进程的数据复制与持久化

## 架构

```
┌─────────────────────────────────────────────────────────────┐
│                      StringLocalCache (SDK入口)               │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐    ┌─────────────────┐    ┌──────────────┐
│  Guava Cache  │    │ LocalCacheServer │    │   DBShm      │
│ (本地缓存存储)  │    │  (Netty TCP服务) │    │ (共享内存持久化)│
└───────────────┘    └─────────────────┘    └──────────────┘
        ▲                     │                     │
        │                     ▼                     ▼
        │         ┌──────────────────┐    ┌──────────────────┐
        │         │LocalCacheCommand │    │LocalCacheReplica │
        │         │     Worker       │    │     Worker       │
        │         │ (命令执行消费者)  │    │ (共享内存生产者)  │
        │         └──────────────────┘    └──────────────────┘
        │                     │
        └─────────────────────┘
              LocalCacheCommandMgr (命令分发管理)
```

### 核心模块

| 模块 | 说明 |
|------|------|
| `sdk.StringLocalCache` | 用户-facing SDK，提供 `get` / `set` / `del` / `notify` 接口 |
| `main.LocalCacheInitializer` | 初始化 Netty 服务端及后台工作线程 |
| `worker.LocalCacheCommandWorker` | 从队列消费命令并执行本地缓存操作 |
| `worker.LocalCacheReplicaWorker` | 将缓存命令序列化后写入共享内存 |
| `cmd.LocalCacheCommandMgr` | 命令管理器，维护命令类型到处理器的映射 |
| `db.DBShm` / `DBDataShm` / `DBIndexShm` | 基于内存映射文件的共享内存存储层 |
| `handler.LocalCacheServerHandler` | Netty ChannelHandler，处理远程缓存指令 |

## 依赖

- **Java 8+**
- [Netty](https://netty.io/) 4.1.1.Final — 网络通信
- [Guava](https://github.com/google/guava) 22.0 — 本地缓存 (`LoadingCache`)
- [Protobuf Java](https://github.com/protocolbuffers/protobuf) 3.3.1 — 序列化协议
- [Fastjson](https://github.com/alibaba/fastjson) 1.2.13 — JSON 处理
- [Apache Commons Lang3](https://commons.apache.org/proper/commons-lang/) 3.4 — 工具类

## 快速开始

### 1. 创建 Guava LoadingCache

```java
LoadingCache<String, String> cacheBuilder = CacheBuilder.newBuilder()
    .refreshAfterWrite(1, TimeUnit.SECONDS)
    .expireAfterWrite(3, TimeUnit.SECONDS)
    .build(new CacheLoader<String, String>() {
        @Override
        public String load(String key) throws Exception {
            return UUID.randomUUID().toString();
        }
    });
```

### 2. 初始化 StringLocalCache

```java
StringLocalCache.getInstance().initialize(
    cacheBuilder,
    new StringLocalCacheNotifyCallback() {
        @Override
        public boolean onNotify(String param) {
            System.out.println("收到通知: " + param);
            return true;
        }
    },
    new StringLocalCacheErrorCallback() {
        @Override
        public boolean onError(String nodeId, String key, String value) {
            System.err.println("错误: node=" + nodeId + ", key=" + key);
            return false;
        }
    }
);
```

### 3. 使用缓存

```java
// 写入缓存（同时同步到其他节点）
StringLocalCache.getInstance().set("key", "hello world");

// 读取缓存
String value = StringLocalCache.getInstance().get("key", "default_value");

// 删除缓存（同时同步到其他节点）
StringLocalCache.getInstance().del("key");

// 发送自定义通知事件
StringLocalCache.getInstance().notify("flush_cache_event");
```

## 配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `LOCAL_CACHE_SERVER_PORT` | `10012` | Netty 服务端监听端口 |
| `LOCAL_CACHE_CMD_QUEUE_SIZE` | `819200` | 命令队列容量 |
| `LOCAL_CACHE_CMD_QUEUE_TMO` | `1000` ms | 命令队列轮询超时 |
| `LOCAL_CACHE_MAX_FRAME_SIZE` | `10240` | Netty 最大帧大小 |
| `DISTRIBUTED_STRING_LOCAL_CACHE_DATA_PATH` | — | 共享内存文件存储路径（环境变量） |

## 协议定义

项目使用 Protocol Buffers 定义两种消息格式：

### 网络通信协议 (`common_local_cache.proto`)

```protobuf
message CacheCommand {
    int32 messageType = 1;   // 命令类型: SET/DEL/NOTIFY/ERROR
    string key = 2;          // 缓存键
    bytes value = 3;         // 缓存值
    string parameter = 4;    // 附加参数
}
```

### 共享内存协议 (`shared_memory_struct.proto`)

```protobuf
message SharedMemoryObject {
    string ip = 1;
    string key = 2;
    string value = 3;
    uint64 timestamp = 4;
    uint32 opType = 5;
}
```

## 命令类型

| 命令 | 说明 |
|------|------|
| `SET` | 设置缓存键值，写入本地 Guava Cache 并同步到共享内存 |
| `DEL` | 删除缓存键，使本地 Guava Cache 失效并同步到共享内存 |
| `NOTIFY` | 发送通知事件，触发 `StringLocalCacheNotifyCallback` |
| `ERROR` | 错误事件，触发 `StringLocalCacheErrorCallback` |

## 共享内存机制

共享内存基于 Java NIO 的 `MappedByteBuffer` 实现：

- **索引文件** (`index.shm`)：维护当前数据文件的索引与写计数
- **数据文件** (`data.{index}.shm`)：循环存储序列化后的 `SharedMemoryObject`
- **文件锁**：通过 `DBFileLock` 保证多进程并发安全
- **自动轮转**：当单个数据文件写满后，自动切换到下一个文件（循环覆盖）

## 构建

```bash
mvn clean package
```

## 测试

```bash
mvn test
```

主要测试类：

- `LocalCacheServerTest` — 本地缓存服务端集成测试
- `CommonLocalCacheTest` — Protobuf 序列化/反序列化测试
- `SharedMemoryTest` / `InterProcessShmTest` — 共享内存读写与跨进程测试
- `FileLockTest` — 文件锁并发测试