CoCache

中文

English

中文

English

Appearance

Actuator 端点 ​

CoCache 暴露了两个 Spring Boot Actuator 端点，用于运行时监控和管理缓存。当 Spring Boot Actuator 在类路径上时，这些端点由 CoCacheEndpointAutoConfiguration 自动配置。

端点概览 ​

端点 ID类URL用途源码
cocacheCoCacheEndpoint/actuator/cocache一致性缓存管理（total、stat、evict、get）CoCacheEndpoint.kt:27
cocacheClientCoCacheClientEndpoint/actuator/cocacheClient客户端（L2）缓存管理（size、get、clear）CoCacheClientEndpoint.kt:24

两个端点都继承自 AbstractCoCacheEndpoint，该基类提供了从 CacheFactory 解析 CoherentCache 实例的辅助方法。

AbstractCoCacheEndpoint ​

两个端点实现共享的基类。

方面详情源码
抽象属性cacheFactory: CacheFactory--
辅助方法String.coherentCache(): CoherentCache<String, Any>?String 上的扩展函数，按名称查找 CoherentCache
源文件--AbstractCoCacheEndpoint.kt:19

CoCacheEndpoint ​

一致性缓存的主要管理端点。暴露了列出所有缓存、检查单个缓存、驱逐条目和获取值的操作。

操作 ​

total() -- 列出所有缓存 ​

方面详情
HTTP 方法GET
URL/actuator/cocache
注解@ReadOperation
返回值List<CacheReport> -- 所有已注册的 CoherentCache 实例
源码CoCacheEndpoint.kt:30

过滤 CacheFactory.caches 映射，仅包含值为 CoherentCache 的条目，然后将每个映射为 CacheReport。

stat(name) -- 缓存统计信息 ​

方面详情
HTTP 方法GET
URL/actuator/cocache/{name}
注解@ReadOperation
参数@Selector name: String
返回值CacheReport? -- 缓存详情，未找到时返回 null
源码CoCacheEndpoint.kt:40

evict(name, key) -- 驱逐缓存条目 ​

方面详情
HTTP 方法DELETE
URL/actuator/cocache/{name}/{key}
注解@DeleteOperation
参数@Selector name: String、@Selector key: String
返回值void
源码CoCacheEndpoint.kt:45

从 L2（客户端缓存）和 L1（分布式缓存）中驱逐条目，并发布 CacheEvictedEvent 以在所有实例间使该条目失效。

get(name, key) -- 获取缓存条目 ​

方面详情
HTTP 方法GET
URL/actuator/cocache/{name}/{key}
注解@ReadOperation
参数@Selector name: String、@Selector key: String
返回值CacheValue<*>? -- 包含 TTL 元数据的完整缓存值，或 null
源码CoCacheEndpoint.kt:50

CacheReport 数据类 ​

一致性缓存配置和运行时状态的详细报告。

字段类型说明源码
nameString缓存名称CoCacheEndpoint.kt:55
clientIdString当前实例的分布式客户端 IDCoCacheEndpoint.kt:56
clientSizeLongL2 客户端缓存中的条目数CoCacheEndpoint.kt:57
keyConverterString键转换器的字符串表示CoCacheEndpoint.kt:58
distributedCachingString分布式缓存实现的全限定类名CoCacheEndpoint.kt:59
clientSideCachingString客户端缓存实现的全限定类名CoCacheEndpoint.kt:60
cacheEvictedEventBusString事件总线实现的全限定类名CoCacheEndpoint.kt:61
cacheSourceString数据源实现的全限定类名CoCacheEndpoint.kt:62
keyFilterString键过滤器实现的全限定类名CoCacheEndpoint.kt:63

响应示例 ​

GET /actuator/cocache

json
[
  {
    "name": "user-cache",
    "clientId": "192.168.1.10",
    "clientSize": 1523,
    "keyConverter": "ToStringKeyConverter(keyPrefix='cocache:user-cache:')",
    "distributedCaching": "me.ahoo.cache.spring.redis.RedisDistributedCache",
    "clientSideCaching": "me.ahoo.cache.client.CaffeineClientSideCache",
    "cacheEvictedEventBus": "me.ahoo.cache.spring.redis.RedisCacheEvictedEventBus",
    "cacheSource": "me.ahoo.cache.api.source.NoOpCacheSource",
    "keyFilter": "me.ahoo.cache.filter.NoOpKeyFilter"
  }
]

CoCacheClientEndpoint ​

客户端（L2）缓存管理端点。提供对当前实例本地内存缓存的可视性。

操作 ​

getSize(name) -- 获取客户端缓存大小 ​

方面详情
HTTP 方法GET
URL/actuator/cocacheClient/{name}
注解@ReadOperation
参数@Selector name: String
返回值Long? -- L2 缓存中的条目数，缓存未找到时返回 null
源码CoCacheClientEndpoint.kt:32

get(name, key) -- 获取客户端缓存条目 ​

方面详情
HTTP 方法GET
URL/actuator/cocacheClient/{name}/{key}
注解@ReadOperation
参数@Selector name: String、@Selector key: String
返回值CacheValue<*>? -- 包含 TTL 元数据的 L2 缓存条目，或 null
源码CoCacheClientEndpoint.kt:37

key 参数在客户端缓存中查找之前，会使用缓存的 KeyConverter 转换为字符串缓存键。

clear(name) -- 清除客户端缓存 ​

方面详情
HTTP 方法DELETE
URL/actuator/cocacheClient/{name}
注解@DeleteOperation
参数@Selector name: String
返回值void
源码CoCacheClientEndpoint.kt:43

仅清除当前实例上的 L2 客户端缓存中的所有条目。不会影响 L1 分布式缓存或其他实例。

端点自动配置 ​

CoCacheEndpointAutoConfiguration ​

当 Spring Boot Actuator 可用时，注册两个端点 Bean。

方面详情源码
条件@AutoConfiguration(after = [CoCacheAutoConfiguration::class])、@ConditionalOnClass(Endpoint::class)、@ConditionalOnCoCacheEnabled--
源文件--CoCacheEndpointAutoConfiguration.kt:30
Bean类型条件
cocacheEndpointCoCacheEndpoint@ConditionalOnMissingBean
coCacheClientEndpointCoCacheClientEndpoint@ConditionalOnMissingBean

端点注册流程 ​

mermaid
sequenceDiagram
autonumber
    participant Boot as Spring Boot
    participant Auto as CoCacheAutoConfiguration
    participant EA as CoCacheEndpointAutoConfiguration
    participant CF as CacheFactory
    participant EP as CoCacheEndpoint
    participant CEP as CoCacheClientEndpoint
    participant Act as Actuator 基础设施

    Boot->>Auto: 自动配置 CoCache Bean
    Auto-->>Boot: CacheFactory、工厂等
    Boot->>EA: 自动配置端点
    EA->>CF: 注入 CacheFactory
    EA->>EP: new CoCacheEndpoint(cacheFactory)
    EA->>CEP: new CoCacheClientEndpoint(cacheFactory)
    EA-->>Boot: 端点 Bean 已注册
    Act->>EP: 通过 /actuator/cocache 暴露
    Act->>CEP: 通过 /actuator/cocacheClient 暴露

端点架构 ​

下图展示了两个端点与缓存层之间的关系：

mermaid
graph TB
    subgraph Client["HTTP 客户端"]
        style Client fill:#161b22,stroke:#6d5dfc,color:#e6edf3
        User["运维人员 / 监控工具"]
    end

    subgraph Endpoints["Actuator 端点"]
        style Endpoints fill:#161b22,stroke:#6d5dfc,color:#e6edf3
        EP["/actuator/cocache<br>CoCacheEndpoint"]
        CEP["/actuator/cocacheClient<br>CoCacheClientEndpoint"]
    end

    subgraph CacheSystem["缓存系统"]
        style CacheSystem fill:#161b22,stroke:#6d5dfc,color:#e6edf3
        CF["CacheFactory"]
        CC["CoherentCache"]
        L2["ClientSideCache<br>(L2)"]
        L1["DistributedCache<br>(L1)"]
        Bus["CacheEvictedEventBus"]
    end

    User --> EP
    User --> CEP
    EP --> CF
    CEP --> CF
    CF --> CC
    CC --> L2
    CC --> L1
    CC --> Bus
    EP -- "total/stat" --> CC
    EP -- "evict" --> CC
    EP -- "get" --> CC
    CEP -- "getSize" --> L2
    CEP -- "get" --> L2
    CEP -- "clear" --> L2

端点操作汇总 ​

下图汇总了两个端点上所有可用的操作：

mermaid
graph LR
    subgraph CoCacheEP["CoCacheEndpoint"]
        style CoCacheEP fill:#161b22,stroke:#6d5dfc,color:#e6edf3
        OP1["GET /<br>列出所有缓存<br>total()"]
        OP2["GET /{name}<br>缓存统计信息<br>stat()"]
        OP3["GET /{name}/{key}<br>获取条目<br>get()"]
        OP4["DELETE /{name}/{key}<br>驱逐条目<br>evict()"]
    end

    subgraph ClientEP["CoCacheClientEndpoint"]
        style ClientEP fill:#161b22,stroke:#6d5dfc,color:#e6edf3
        OP5["GET /{name}<br>L2 缓存大小<br>getSize()"]
        OP6["GET /{name}/{key}<br>L2 条目<br>get()"]
        OP7["DELETE /{name}<br>清除 L2 缓存<br>clear()"]
    end

    OP1 -->|"List<CacheReport>"| R1["JSON 响应"]
    OP2 -->|"CacheReport?"| R2["JSON 响应"]
    OP3 -->|"CacheValue<*>?"| R3["JSON 响应"]
    OP4 -->|"void"| R4["已驱逐"]
    OP5 -->|"Long?"| R5["JSON 响应"]
    OP6 -->|"CacheValue<*>?"| R6["JSON 响应"]
    OP7 -->|"void"| R7["已清除"]

CoherentCache 与客户端端点使用场景 ​

场景端点操作URL
监控所有缓存CoCacheEndpointtotal()GET /actuator/cocache
检查单个缓存配置CoCacheEndpointstat(name)GET /actuator/cocache/{name}
调试特定缓存条目CoCacheEndpointget(name, key)GET /actuator/cocache/{name}/{key}
跨所有实例强制驱逐CoCacheEndpointevict(name, key)DELETE /actuator/cocache/{name}/{key}
检查 L2 内存使用量CoCacheClientEndpointgetSize(name)GET /actuator/cocacheClient/{name}
检查本地 L2 条目CoCacheClientEndpointget(name, key)GET /actuator/cocacheClient/{name}/{key}
仅刷新本地 L2CoCacheClientEndpointclear(name)DELETE /actuator/cocacheClient/{name}

启用端点 ​

默认情况下，Spring Boot Actuator 端点不会通过 HTTP 暴露。请在 application.yml 中添加以下配置：

yaml
management:
  endpoints:
    web:
      exposure:
        include: cocache, cocacheClient

或者暴露所有端点：

yaml
management:
  endpoints:
    web:
      exposure:
        include: "*"

配置属性 ​

属性类型默认值说明源码
cocache.enabledBooleantrueCoCache 自动配置（包括端点）的主开关CoCacheProperties.kt:24

要禁用 CoCache（及其端点）：

yaml
cocache:
  enabled: false

自定义端点 ​

要自定义端点 Bean，只需在配置类中声明自己的 @Bean 方法。默认 Bean 上的 @ConditionalOnMissingBean 注解确保您的自定义实现优先：

kotlin
@Configuration
class CustomEndpointConfig {

    @Bean
    fun cocacheEndpoint(cacheFactory: CacheFactory): CoCacheEndpoint {
        // 自定义前/后逻辑
        return CoCacheEndpoint(cacheFactory)
    }
}

相关页面 ​

基于 Apache License 2.0 发布。

Copyright 2022-present Ahoo Wang