# spring-boot-starter-cache-plus

**Repository Path**: xueyanjun/spring-boot-starter-cache-plus

## Basic Information

- **Project Name**: spring-boot-starter-cache-plus
- **Description**: 一个增强型的 Spring Boot 缓存启动器，简单易用，可扩展，可配置，可定制。该项目通过自定义注解和多种缓存策略，有效解决了缓存穿透、击穿和雪崩等常见问题。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-05
- **Last Updated**: 2025-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot Starter Cache Plus

## 项目介绍

Spring Boot Starter Cache Plus 是一个增强型的 Spring Boot 缓存启动器，简单易用，可扩展，可配置，可定制。该项目通过自定义注解和多种缓存策略，有效解决了缓存穿透、击穿和雪崩等常见问题。

### 核心特性

1. **多级缓存支持**：同时支持本地缓存（Caffeine）和分布式缓存（Redis）
2. **自定义注解**：提供 [@CacheFindPlus]、[@CachePutPlus]、[@CacheEvictPlus] 等增强注解
3. **缓存策略**：内置多种缓存策略，包括互斥锁、逻辑过期、延迟双删等
4. **缓存监控**：集成 Micrometer，提供缓存命中率等监控指标
5. **BloomFilter 支持**：防止缓存穿透
6. **自动配置**：基于 Spring Boot 的自动配置机制，开箱即用

## 模块结构

```
spring-boot-starter-cache-plus
├── cache-plus-autoconfigure    // 自动配置模块
├── cache-plus-core             // 核心功能模块
├── cache-plus-local            // 本地缓存实现（Caffeine）
├── cache-plus-redis            // Redis 缓存实现
├── cache-plus-monitor          // 监控模块
├── cache-plus-example          // 示例项目
└── spring-boot-starter-cache-plus  // Starter 模块
```

## 快速开始

### 1. 添加依赖

在您的 Spring Boot 项目中添加以下依赖：

```xml
<repositories>
    <repository>
        <id>xueyanjun-maven</id>
        <url>https://gitee.com/xueyanjun/maven.repository/raw/master</url>
    </repository>
</repositories>

<dependency>
    <groupId>io.gitee.xueyanjun</groupId>
    <artifactId>spring-boot-starter-cache-plus</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 启用缓存

在您的 Spring Boot 启动类上添加 [@EnableCachePlus] 注解：

```java
@SpringBootApplication
@EnableCachePlus
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

### 3. 配置文件

在 `application.yml` 中配置缓存相关参数：

```yaml
cache-plus:
  redis:
    enabled: true
    host: localhost
    port: 6379
  local:
    enabled: true
    expire-after-write: 600
```

## 核心注解详解

### [@CacheFindPlus] - 缓存查询

用于查询操作的缓存注解，支持多种高级特性：

```java
@CacheFindPlus(
    value = "users", 
    key = "#id", 
    isLogicalTtl = true,     // 启用逻辑过期
    ttl = 300,               // 过期时间300秒
    randomRange = 60        // 随机过期范围60秒
)
public User getUserById(Long id) {
    // 数据库查询逻辑
    return userRepository.findById(id);
}
```

### [@CachePutPlus] - 缓存更新

用于更新操作的缓存注解：

```java
@CachePutPlus(
    value = "users", 
    key = "#user.id",
    strategy = "delayDoubleDeleteStrategy"  // 更新策略
)
public User saveUser(User user) {
    // 数据库保存逻辑
    return userRepository.save(user);
}
```

### [@CacheEvictPlus]- 缓存清除

用于清除操作的缓存注解：

```java
@CacheEvictPlus(
    value = "users", 
    key = "#id"
)
public void deleteUser(Long id) {
    // 数据库删除逻辑
    userRepository.deleteById(id);
}
```

## 缓存策略

### 缓存穿透解决方案

1. **BloomFilter**：通过布隆过滤器快速判断数据是否存在
2. **空值缓存**：对查询结果为空的请求也进行缓存，但设置较短的过期时间

```java
@CacheFindPlus(
    value = "users",
    key = "#id",
    bloomFilter = "userBloomFilter"  // 指定BloomFilter
)
public User getUserById(Long id) {
    // ...
}
```

### 缓存击穿解决方案

1. **互斥锁机制**：通过 指定缓存重建策略来解决 比如`strategy = findMissRedisMutexLockWriteStrategy` 参数启用
2. **逻辑过期时间**：通过 `isLogicalTtl = true` 参数启用
3. **策略模式**：可选择不同的缓存策略

```java
// 使用互斥锁防止击穿
@CacheFindPlus(
    cacheNames = "users",
    key = "#id", 
    strategy = "findMissRedisMutexLockWriteStrategy", 
    ttl = 300
)
public User getUserById(Long id) {
    // ...
}

// 使用逻辑过期防止击穿
@CacheFindPlus(
    cacheNames = "users",
    key = "#id",
    isLogicalTtl = true,
    ttl = 300
)
public User getUserById(Long id) {
    // ...
}
```

### 缓存雪崩解决方案

1. **随机过期时间**：通过 [randomRange] 参数设置随机过期时间范围
2. **多级缓存**：本地缓存 + 分布式缓存的架构
3. **差异化过期**：为不同类型的缓存设置不同的过期时间

```java
@CacheFindPlus(
    value = "users",
    key = "#id",
    ttl = 300,
    randomRange = 60  // 过期时间将在300-360秒之间随机
)
public User getUserById(Long id) {
    // ...
}
```

## 策略模式详解

### 查询策略

| 策略类 | 描述 | 适用场景 |
|-------|------|---------|
| [FindMissJvmMutexLockWriteStrategy]| JVM级互斥锁 | 单体应用 |
| [FindMissRedisMutexLockWriteStrategy]| Redis分布式锁 | 分布式应用 |
| [FindMissDoNothingStrategy]| 不处理 | 可接受缓存穿透 |

### 更新策略

| 策略类 | 描述 | 适用场景 |
|-------|------|---------|
| [DelayDoubleDeleteStrategy] | 延迟双删 | 强一致性要求 |
| [WriteThroughStrategy] | 写透模式 | 实时性要求高 |
| [InvokeBeforeDeleteStrategy]| 先执行后删除 | 读多写少 |

## 配置说明

### 完整配置示例

```yaml
cache-plus:
  redis:
    enabled: true           # 是否启用Redis缓存
    host: localhost         # Redis主机
    port: 6379              # Redis端口
    password:               # Redis密码（可选）
    database: 0             # Redis数据库索引
  local:
    enabled: true           # 是否启用本地缓存
    expire-after-write: 600 # 本地缓存过期时间（秒）
```

### 监控配置

```yaml
management:
  endpoints:
    web:
      exposure:
        include: "*"        # 暴露所有监控端点
  endpoint:
    health:
      show-details: always  # 显示健康检查详情
```

## 使用示例

### 基本用法

```java
@Service
public class UserService {
    
    @CacheFindPlus(
        value = "users", 
        key = "#id",
        ttl = 300
    )
    public User getUserById(Long id) {
        return userRepository.findById(id);
    }
    
    @CachePutPlus(
        value = "users", 
        key = "#user.id"
    )
    public User saveUser(User user) {
        return userRepository.save(user);
    }
    
    @CacheEvictPlus(
        value = "users", 
        key = "#id"
    )
    public void deleteUser(Long id) {
        userRepository.deleteById(id);
    }
}
```

### 高级用法

```java
@Service
public class ProductService {
    
    // 防止缓存击穿
    @CacheFindPlus(
        value = "products",
        key = "#id",
        isLogicalTtl = true,
        ttl = 600,
        strategy = "findMissRedisMutexLockWriteStrategy"
    )
    public Product getProductById(Long id) {
        return productRepository.findById(id);
    }
    
    // 防止缓存雪崩
    @CacheFindPlus(
        value = "productList",
        key = "#categoryId",
        ttl = 300,
        randomRange = 60
    )
    public List<Product> getProductsByCategory(Long categoryId) {
        return productRepository.findByCategoryId(categoryId);
    }
    
    // 使用布隆过滤器防止缓存穿透
    @CacheFindPlus(
        value = "products",
        key = "#id",
        bloomFilter = "productBloomFilter"
    )
    public Product getProductByIdWithBloomFilter(Long id) {
        return productRepository.findById(id);
    }
}
```

## 监控指标

项目集成了 Micrometer，提供以下监控指标：

- `cache.hit`：缓存命中次数
- `cache.miss`：缓存未命中次数
- `cache.operation.time`：缓存操作耗时

可以通过 Prometheus、Grafana 等监控工具查看这些指标。

## 性能优化建议

1. **合理设置TTL**：根据业务特点设置合适的过期时间
2. **使用多级缓存**：本地缓存 + 分布式缓存结合使用
3. **选择合适的策略**：根据业务场景选择合适的缓存策略
4. **监控缓存命中率**：定期检查缓存命中率，优化缓存配置
5. **防止大Key**：避免将大量数据存储在一个缓存Key中

## 常见问题

### 1. 缓存不生效

检查是否添加了 [@EnableCachePlus]注解，以及方法是否满足AOP代理要求（不能是private方法，不能在同一个类中调用等）。

### 2. 缓存穿透

启用BloomFilter或对空值进行缓存：

```java
@CacheFindPlus(
    value = "users",
    key = "#id",
    bloomFilter = "userBloomFilter"
)
```

### 3. 缓存击穿

使用互斥锁或逻辑过期：

```java
@CacheFindPlus(
    value = "users",
    key = "#id", 
    isLogicalTtl = true  // 或 使用互斥锁策略
)
```

### 4. 缓存雪崩

设置随机过期时间：

```java
@CacheFindPlus(
    value = "users",
    key = "#id",
    ttl = 300,
    randomRange = 60
)
```

## 扩展开发
```java
// 自定义CacheFind注解上对应的缓存重建策略
public class CustomFindMissCacheStrategy implements CacheFindMissStrategy {
    // 实现自定义策略逻辑
}
// 自定义CacheFind注解上对应的缓存重建策略
public class CustomPutCacheStrategy implements CachePutStrategy {
    // 实现自定义策略逻辑
}
// 注册自定义策略
@Bean
public CustomFindMissCacheStrategy customCacheStrategy1() {
    return new CustomFindMissCacheStrategy();
}
@Bean
public CustomPutCacheStrategy customCacheStrategy2() {
    return new CustomPutCacheStrategy();
}
```