# jfast-cache

**Repository Path**: huanminabc/jfast-cache

## Basic Information

- **Project Name**: jfast-cache
- **Description**: jfast-cache是一个轻量级、高性能的Java缓存库，提供内存缓存和持久化本地缓存两种实现方式。采用LRU（最近最少使用）淘汰策略和基于时间轮的过期机制，支持线程安全、异步操作、容量管理和淘汰监听等特性。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-11-08
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# jfast-cache

一个高性能的Java本地缓存库，支持内存缓存和持久化本地缓存两种模式。 (本文档AI生成如有错误请自己查看源码)

## 📋 简介

jfast-cache是一个轻量级、高性能的Java缓存库，提供内存缓存和持久化本地缓存两种实现方式。采用LRU（最近最少使用）淘汰策略和基于时间轮的过期机制，支持线程安全、异步操作、容量管理和淘汰监听等特性。

## ✨ 特性

- **双缓存模式**：支持纯内存缓存和持久化本地缓存
- **高性能**： 基于自研CacheConcurrentLRULinkedList 等优化
- **LRU淘汰**：高效的LRU链表管理，自动淘汰过期/最少使用项
- **TTL过期**：基于时间轮的精确过期机制
- **持久化**：使用MapDB实现磁盘持久化, 支持定制存储
- **异步操作**：支持异步写入队列，提高写入性能
- **线程安全**：高并发场景下保持稳定性能

## 🚀 快速开始

### 添加依赖
https://central.sonatype.com/artifact/com.gitee.huanminabc/jfast-cache
```xml
<dependency>
    <groupId>com.gitee.huanminabc</groupId>
    <artifactId>jfast-cache</artifactId>
    <version>最新版本</version>
</dependency>
```

### 基本使用

```java
import com.gitee.huanminabc.jfastcache.CacheSupport;

// 创建内存缓存
CacheSupport<String> cache = CacheSupport.createMemoryCache("myCache");

// 添加缓存（默认永不过期）
cache.put("key1", "value1");

// 添加缓存（指定过期时间，单位毫秒）
cache.put("key2", "value2", 60000);

// 获取缓存
String value = cache.get("key1"); // 返回 "value1"

// 删除缓存
cache.remove("key1");

// 清空缓存
cache.clear();
```

### 创建本地持久化缓存

```java
// 创建本地持久化缓存
CacheSupport<String> localCache = CacheSupport.createLocalCache("localCache");

// 使用（与内存缓存API一致）
localCache.put("key", "value");
String value = localCache.get("key");
```

## 📖 高级功能

### getAndPut - 缓存空值处理

当缓存不存在时，自动调用Supplier获取值并缓存：

```java
CacheSupport<String> cache = CacheSupport.createMemoryCache("cache");

// 如果key不存在，则执行function获取值并缓存
String value = cache.getAndPut("key", () -> {
    // 从数据库或其他来源获取数据
    return getDataFromDB();
});
```

### discard - 延迟删除

指定时间间隔后执行清理操作：

```java
cache.discard("key", 5000, () -> {
    // 5秒后执行清理逻辑
    System.out.println("清理过期缓存: " + key);
});
```


## ⚙️ 配置说明

### CacheConfig 配置项

| 配置项 | 说明 | 默认值      |
|--------|------|----------|
| capacity | 缓存容量 | 10000    |
| timeout | 默认过期时间（毫秒） | -1（永不过期） |
| storageType | 存储类型 | -        |
| storageKey | 存储键 | -        |
| initialSizeMB | 初始大小（MB） | 1        |
| incrementSizeMB | 增量大小（MB） | 4        |
| maxSizeMB | 最大大小（MB） | 16384     |
| asyncSizeChangeCommitThreshold | 异步提交阈值 | 1000     |
| asyncForceCommitInterval | 强制提交间隔（毫秒） | 10000     |

### 配置示例

```java
CacheConfig config = CacheConfig.defaultConfig()
    .capacity(10000)
    .timeout(300000)  // 5分钟
    .initialSizeMB(32)
    .maxSizeMB(2048);

CacheSupport<String> cache = CacheSupport.createLocalCache("configuredCache");
```

## 🏗️ 架构设计

### 核心组件

```
jfast-cache
├── Cache             # 缓存接口
├── CacheAbstract     # 缓存抽象基类
├── CacheSupport      # 缓存支持类（入口类）
├── CacheObj          # 缓存对象封装
├── enums/
│   └── CacheEnum     # 缓存类型枚举
├── memory/           # 内存缓存实现
│   ├── CacheMemory        # 内存缓存
│   ├── CacheTimeWheel     # 时间轮（过期管理）
│   └── CacheConcurrentLRULinkedList  # LRU链表
├── local/            # 本地持久化缓存
│   ├── CacheLocal         # 本地缓存
│   └── MpscParkQueue      # 多生产者单消费者队列
└── storage/          # 存储实现
    └── CacheLocalStorage  # MapDB持久化存储
```

### 缓存层次结构

```
Cache<V> (接口)
    ↑
CacheAbstract<V> (抽象类)
    ↑
    ├── CacheMemoryAbstract<V> → CacheMemory<V> (内存缓存)
    │
    └── CacheLocalAbstract<V> → CacheLocal<V> (持久化缓存)
```

## 📊 性能测试

项目内置了完整的性能测试，与Caffeine等主流缓存库进行对比：

```bash
# 运行性能测试
mvn test -Dtest=PerformanceTest

# 运行内存测试
mvn test -Dtest=MemoryLayoutTest

# 对比测试（需要添加Caffeine依赖）
mvn test -Dtest=CachePerformanceComparisonTest
```

### 测试结果示例
【压力测试】 [jfast-cache]
线程数: 100 | CPU核心: 32 | 内存: 32 GB | CPU i9 英特尔
================================================================================
只是一个大概的参考不同机器不同性能都会不同但是基本在测试范围(没有预热)
jfast-cache最快的场景是读,只要读写不交互或者少量的交互那么,我可以说jfast-cache是性能的天花板没有之一,请看下面AI生成加测试的真实结果[GetPerformanceTest.java](src/test/java/com/gitee/huanminabc/jfastcache/memory/performance/GetPerformanceTest.java)


```text
========== jfast-cache Get操作 性能指标 ==========
总操作数: 1000000
成功操作数: 1000000
失败操作数: 0
成功率: 100.00%
总吞吐量: 4807692.31 ops/s
成功吞吐量: 4807692.31 ops/s
平均延迟: 0.000 ms
P50延迟: 0.000 ms
P95延迟: 0.000 ms
P99延迟: 0.000 ms
最大延迟: 0.012 ms
采样数量: 50000 (采样率: 1/1)
==========================================

========== Caffeine Get操作 性能指标 ==========
总操作数: 1000000
成功操作数: 1000000
失败操作数: 0
成功率: 100.00%
总吞吐量: 1082251.08 ops/s
成功吞吐量: 1082251.08 ops/s
平均延迟: 0.000 ms
P50延迟: 0.000 ms
P95延迟: 0.001 ms
P99延迟: 0.002 ms
最大延迟: 0.015 ms
采样数量: 50000 (采样率: 1/1)
==========================================

```


## 📝 API文档

### Cache<V> 接口

| 方法 | 说明 |
|------|------|
| boolean put(String key, V value) | 添加缓存 |
| boolean put(String key, V value, long timeout) | 添加缓存（带过期时间） |
| V get(String key) | 获取缓存 |
| V remove(String key) | 删除缓存 |
| void clear() | 清空缓存 |

### CacheSupport<V> 扩展方法

| 方法 | 说明 |
|------|------|
| V getAndPut(String key, Supplier<V> function) | 获取或添加缓存 |
| V getAndPut(String key, int timeInterval, Supplier<V> function) | 获取或添加缓存（带过期时间） |
| void discard(String key, int timeInterval, Runnable consumer) | 延迟执行清理操作 |

## 🤝 贡献

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的改动 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建一个Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 详情请查看 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [MapDB](http://www.mapdb.org/) - 持久化存储支持
- [Caffeine](https://github.com/ben-manes/caffeine) - 性能参考
- [LMAX Disruptor](https://github.com/LMAX-Exchange/disruptor) - 队列实现参考