# cache-version-check-spring-boot

**Repository Path**: neuliying/cache-version-check-spring-boot

## Basic Information

- **Project Name**: cache-version-check-spring-boot
- **Description**: A Spring Boot component that automatically checks and manages schema version compatibility between entity classes and cache storage to prevent business exceptions caused by outdated cached data.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cache Version Check

[![maven-central](https://img.shields.io/maven-central/v/cc.duduhuo/cache-version-check-spring-boot-starter.svg?style=flat)](https://mvnrepository.com/artifact/cc.duduhuo/cache-version-check-spring-boot-starter)

用于 Spring Boot 应用启动时，检查缓存版本是否符合要求。
比如实体类字段有修改，需要将缓存中有关该实体类的缓存数据删除，避免反序列化失败或者引发业务异常。

## 添加依赖

- 使用 Maven

```xml
<dependency>
    <groupId>cc.duduhuo</groupId>
    <artifactId>cache-version-check-spring-boot-starter</artifactId>
    <version>1.1.1</version>
</dependency>
```

- 使用 Gradle (Groovy)

```groovy
implementation 'cc.duduhuo:cache-version-check-spring-boot-starter:1.1.1'
```

- 使用 Gradle (Kotlin)

```kotlin
implementation("cc.duduhuo:cache-version-check-spring-boot-starter:1.1.1")
```

## 实现原理

每个实体类可以添加一个 `CacheVersion` 注解，标记该实体类的版本号。应用启动时，读取 `CacheVersion` 注解中的版本号，与缓存中的版本号对比，如果一致，则说明当前缓存符合要求，无需处理。如果不一致，则说明缓存已经过期，需要删除（或执行其他操作），并将最新的版本号记入缓存。

## CacheVersion 定义

```kotlin
annotation class CacheVersion(
    /**
     * Cache 版本号
     */
    val version: String,
    /**
     * 关联的 Redis key 模式，支持通配符，如：user:cache:*
     */
    val keyPatterns: Array<String> = [],
    /**
     * 版本检查策略，默认为自动删除
     */
    val strategy: VersionCheckStrategy = VersionCheckStrategy.AUTO_DELETE,
    /**
     * 忽略的 Redis key 模式，支持通配符，如：user:cache:robot:*
     */
    val ignoreKeyPatterns: Array<String> = [],

    /**
     * 自定义处理器 Bean 名称，当策略为 CUSTOM 时使用
     */
    val customHandler: String = "",
)
```

如果缓存版本与预定义的不一致，处理策略有如下几种：

```kotlin
enum class VersionCheckStrategy {
    /**
     * 自动删除版本不匹配的缓存
     */
    AUTO_DELETE,

    /**
     * 仅记录日志，不执行删除操作
     */
    LOG_ONLY,

    /**
     * 抛出异常中断应用启动
     */
    THROW_EXCEPTION,

    /**
     * 自定义处理逻辑
     */
    CUSTOM,
}
```

## 用法示例

在实体类上添加 `CacheVersion` 注解，并声明当前实体类的版本号，以及关联的缓存key模式，如果版本不匹配，则对指定的缓存key做处理。

```kotlin
@CacheVersion(version = "1", keyPatterns = ["demo1::users:*"], strategy = VersionCheckStrategy.AUTO_DELETE)
class UserEntity()
```

需要注意的是，要使 `CacheVersion` 注解生效，需要在 SpringBootApplication 启动类上添加 `CacheVersionScan` 注解，指定要扫描的包。

扫描包是指从指定包路径下找到所有 `CacheVersion` 注解，只有在指定包路径下的 `CacheVersion` 注解才会生效。

如果不指定 `basePackages` ，则使用当前启动类所在的 package 。

```kotlin
@SpringBootApplication
@CacheVersionScan(basePackages = ["org.example.demo1", "org.example.demo2"])
class Demo1Application
```

### 自定义处理逻辑

strategy 配置为 `VersionCheckStrategy.CUSTOM` ，customHandler 配置为“处理器”的 bean name 。

```kotlin
/**
 * 也可在单独的类中声明。
 * 仅支持 class，不支持 interface 。
 */
@CacheVersion(
    version = "1",
    strategy = VersionCheckStrategy.CUSTOM,
    keyPatterns = ["demo2::roles::*"],
    customHandler = "outdatedCacheHandler"
)
class RoleCacheVersion
```

处理器使用 `Component` 注解标记为bean组件，并实现 `VersionMismatchHandler` 接口中的 `handleMismatch` 方法。

```kotlin
@Component("outdatedCacheHandler")
class OutdatedCacheHandler() : VersionMismatchHandler {
    private val logger = LoggerFactory.getLogger(OutdatedCacheHandler::class.java)

    override fun handleMismatch(cacheProvider: CacheProvider, state: VersionCheckState) {
        val triggerClassName = state.trigger
        val expectedVersion = state.expectedVersion
        val actualVersion = state.actualVersion
        val keyPatterns = state.keyPatterns
        val ignoreKeyPatterns = state.ignoreKeyPatterns
        logger.info(
            "handle outdated cache data: [{}] expected version is {}, but existing version is {}, patterns={}",
            triggerClassName, expectedVersion, actualVersion, keyPatterns
        )
        cacheProvider.deleteByPatterns(keyPatterns, ignoreKeyPatterns)
        cacheProvider.setCacheVersion(triggerClassName.name, expectedVersion)
    }
}
```

请参考仓库中的 [demo](demo) 路径下的示例代码。

## 属性配置

| 属性名                                      | 类型        | 默认值                 | 说明                                              |
|------------------------------------------|-----------|---------------------|-------------------------------------------------|
| cache.version-check.enabled              | boolean   | true                | 是否启用 cache version 检查                           |
| cache.version-check.auto-check           | boolean   | true                | 是否启用自动检查，自动检查将在应用启动时自动检查缓存版本                    |
| cache.version-check.preferred-cache-type | CacheType | null                | 缓存类型，当前可选值：redis                                |
| cache.version-check.redis.redis-template | string    | stringRedisTemplate | 指定 RedisTemplate 的 Bean 名称，用于读取和写入缓存版本，以及删除过时缓存 |

说明如下：

1. 当前内置支持 redis 缓存，其他类型的缓存可自行实现，参考：[RedisCacheProvider.kt](starter/src/main/kotlin/cc/duduhuo/cacheversioncheck/springboot/RedisCacheProvider.kt)
2. 需要配置 `cache.version-check.preferred-cache-type` 才能正常启用缓存版本检查功能，当前内置支持 redis
3. 如果配置 `cache.version-check.auto-check=false` ，即关闭自动检查，可通过注入 `CacheVersionChecker` 组件，然后调用 `execute()` 方法执行检查