跳至主要内容

Cache API

快取模組提供多層快取支援，基於 EhCache 實作。

套件: io.leandev.appfuse.cache

核心介面​

Cache<K, V>​

快取核心操作介面。

public interface Cache<K, V> {
    V get(K key);
    void put(K key, V value);
    void remove(K key);
    void clear();
    boolean containsKey(K key);

    void disable();
    void enable();
    boolean isEnabled();

    CacheStatistics getStatistics();
    CacheStatus getStatus();
}

CacheManager​

快取生命週期管理介面。

public interface CacheManager {
    <K, V> Cache<K, V> createCache(CacheConfiguration<K, V> configuration);
    <K, V> Cache<K, V> getCache(String name, Class<K> keyType, Class<V> valueType);
    void removeCache(String name);
    Collection<String> getCacheNames();
    boolean hasCache(String name);
    void close();
}

CacheBuilder​

使用 Fluent API 建構快取。

基本用法​

Cache<String, User> cache = CacheBuilder
    .newCache("users", String.class, User.class)
    .heap(1000)
    .ttl(Duration.ofMinutes(30))
    .build();

方法列表​

儲存層配置​

方法說明
heap(long entries)堆記憶體物件數量
offheap(long sizeMB)堆外記憶體大小（MB）
disk(long sizeMB)磁碟大小（MB）
persistent()啟用持久化

過期配置​

方法說明
ttl(Duration duration)Time-To-Live（存活時間）
tti(Duration duration)Time-To-Idle（閒置時間）
noExpiration()不過期

管理功能​

方法說明
managed(boolean)是否啟用管理功能
build()建構快取實例

配置類別​

CacheConfiguration​

public class CacheConfiguration<K, V> {
    private String name;
    private Class<K> keyType;
    private Class<V> valueType;
    private TierConfiguration tierConfig;
    private ExpiryConfiguration expiryConfig;
    private boolean managed;
}

TierConfiguration​

public class TierConfiguration {
    private Long heapSize;        // 堆記憶體物件數量
    private Long offheapSizeMB;   // 堆外記憶體大小（MB）
    private Long diskSizeMB;      // 磁碟大小（MB）
    private boolean persistent;   // 是否持久化
}

ExpiryConfiguration​

public class ExpiryConfiguration {
    private ExpiryType type;      // TIME_TO_LIVE / TIME_TO_IDLE / NO_EXPIRATION
    private Duration duration;    // 過期時間
}

使用範例​

單層快取（Heap Only）​

Cache<String, Product> cache = CacheBuilder
    .newCache("products", String.class, Product.class)
    .heap(500)
    .ttl(Duration.ofHours(1))
    .build();

// 存取操作
cache.put("prod-001", product);
Product p = cache.get("prod-001");
cache.remove("prod-001");

多層快取（Heap + Disk）​

Cache<String, Report> cache = CacheBuilder
    .newCache("reports", String.class, Report.class)
    .heap(100)
    .disk(500)
    .ttl(Duration.ofDays(1))
    .persistent()
    .build();

啟用管理功能​

Cache<String, Session> cache = CacheBuilder
    .newCache("sessions", String.class, Session.class)
    .heap(1000)
    .tti(Duration.ofMinutes(30))
    .managed(true)
    .build();

// 取得統計資訊
CacheStatistics stats = cache.getStatistics();
long hitCount = stats.getHitCount();
long missCount = stats.getMissCount();
double hitRate = stats.getHitRate();

// 動態停用/啟用
cache.disable();
cache.enable();

使用 CacheManager​

@Autowired
private CacheManager cacheManager;

// 建立快取
CacheConfiguration<String, User> config = CacheConfiguration.<String, User>builder()
    .name("users")
    .keyType(String.class)
    .valueType(User.class)
    .tierConfig(TierConfiguration.builder().heapSize(1000L).build())
    .expiryConfig(ExpiryConfiguration.ttl(Duration.ofMinutes(30)))
    .build();

Cache<String, User> cache = cacheManager.createCache(config);

// 取得已存在的快取
Cache<String, User> existing = cacheManager.getCache("users", String.class, User.class);

// 移除快取
cacheManager.removeCache("users");

統計資訊​

CacheStatistics​

public interface CacheStatistics {
    long getHitCount();
    long getMissCount();
    long getPutCount();
    long getRemovalCount();
    long getEvictionCount();
    double getHitRate();
    double getMissRate();
}

CacheStatus​

public enum CacheStatus {
    UNINITIALIZED,
    AVAILABLE,
    MAINTENANCE,
    CLOSED
}

最佳實踐​

  1. 選擇適當的儲存層 - 熱資料用 Heap，大量資料用 Disk
  2. 設定合理的過期時間 - 避免過期風暴
  3. 啟用統計 - 監控 Hit Rate，調整快取策略
  4. 考慮序列化成本 - Offheap/Disk 需要序列化

相關連結​