# dcache

**Repository Path**: virtual-moon/dcache

## Basic Information

- **Project Name**: dcache
- **Description**: dcache 是一个简单灵活的 Go 本地缓存库，提供自动更新机制。通过构建器模式配置缓存策略，支持基于时间间隔的定期刷新和条件触发的智能更新。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Go语言

## README

# DCache - 简单缓存包

`dcache` 是一个简单而灵活的 Go 语言缓存包，用于自动更新缓存信息。它提供了一个构建器模式来创建和管理缓存，支持基于时间间隔的自动更新和条件触发的智能更新。

## 特性

- 🚀 简单易用的构建器模式
- ⏰ 支持可配置的时间间隔自动更新
- 🔄 支持条件触发的智能更新
- 📦 支持自定义存储接口
- 🛡️ 线程安全的缓存管理
- 📝 支持日志记录
- 🔧 灵活的配置选项
- 🔒 支持资源清理和优雅关闭
- 🎯 **泛型支持，类型安全的API**
- 🔄 **向后兼容，现有代码无需修改**

## 安装

```bash
# 将此包添加到您的 Go 项目中
# 由于这是本地包，直接在项目中引用即可
```

## 快速开始

### 基本用法

```go
package main

import (
    "sync"
    "time"
    "pkg/dcache"
)

type UserInfo struct {
	ID        int64
	Name      string
	Age       int
	Phone     string
	CreatedAt time.Time
	UpdatedAt time.Time
}

// 定义一个简单的存储结构
type UserStore struct {
    sync.RWMutex
    byID   map[int64]UserInfo
    byName map[string]UserInfo
}

// 实现 CacheStore 接口
func (s *UserStore) Load() error {
    s.Lock()
    defer s.Unlock()
    
    // 从数据源加载数据到缓存
    // ...
    return nil
}

func main() {
    // 创建存储实例
    store := &UserStore{
        byID:   make(map[int64]UserInfo),
        byName: make(map[string]UserInfo),
    }

    // 创建并配置缓存
    err := dcache.NewCache("users", store).
        WithInterval(1000). // 每1秒更新一次
        OnLoad(func(cb *dcache.CacheBuilder) error {
            // 定义如何加载数据
            return store.Load()
        }).
        OnClose(func(cb *dcache.CacheBuilder) error {
            // 定义如何清理资源
            fmt.Println("清理缓存资源")
            return nil
        }).
        Build() // 构建并启动缓存

    if err != nil {
        panic(err)
    }

    // 使用缓存
    // ...
}
```

### 高级用法 - 条件触发更新

```go
// 创建智能更新缓存
err := dcache.NewCache("smart_users", store).
    WithInterval(5000). // 每5秒检查一次
    OnLoad(func(cb *dcache.CacheBuilder) error {
        // 加载新数据
        // ...
        return nil
    }).
    OnCheck(func(cb *dcache.CacheBuilder) bool {
        // 返回 true 表示需要更新，false 表示跳过更新
        // 可以在此处检查数据源是否有更新
        return true // 示例中总是更新
    }).
    OnClose(func(cb *dcache.CacheBuilder) error {
        // 清理资源，如关闭数据库连接等
        return nil
    }).
    Build()
```

## 核心概念

### CacheStore 接口

任何需要缓存的存储结构都可以实现 `CacheStore[T any]` 接口：

```go
type CacheStore[T any] interface {
    Load() error
}
```

### CacheBuilder

缓存构建器提供了多种配置选项：

- `WithInterval(interval int64)` - 设置更新间隔（毫秒）
- `OnLoad(f func(cb *CacheBuilder) error)` - 设置加载数据的函数
- `OnCheck(f func(cb *CacheBuilder) bool)` - 设置检查更新条件的函数
- `OnClose(f func(cb *CacheBuilder) error)` - 设置资源清理的函数
- `WithStartDelay(delay time.Duration)` - 设置启动延迟
- `WithStartCondition(readyFunc func() bool, checkInterval ...time.Duration)` - 设置启动条件
- `WithLogger(logger Logger)` - 设置日志记录器
- `OnStarted(f func(cb *CacheBuilder))` - 设置启动完成回调函数

### 缓存管理

包提供全局缓存管理功能：

```go
// 获取缓存实例
cache := dcache.GetCacheByName("users")

// 获取存储实例
store := dcache.GetStore("users")

// 暂停缓存
cache.Pause()

// 释放缓存资源
cache.Close()
```

## 配置选项

### 启动延迟

```go
dcache.NewCache("my_cache", store).
    WithStartDelay(3 * time.Second). // 3秒后启动
    OnStarted(func(cb *dcache.CacheBuilder) {
        // 延迟启动完成后的回调，可用于启动后的初始化操作
        fmt.Printf("缓存 %s 延迟启动完成！\n", cb.GetName())
    }).
    OnLoad(loadFunc).
    Build()
```

**说明**：`OnStarted` 回调函数特别适合配合 `WithStartDelay` 使用，因为延迟启动的完成时机调用方无法直接感知。对于立即启动和条件启动，调用方通常可以通过调用时机和条件函数返回值来判断启动状态。

### 条件启动

```go
dcache.NewCache("my_cache", store).
    WithStartCondition(
        func() bool { 
            // 返回 true 表示满足启动条件
            return checkSystemReady() 
        },
        2*time.Second, // 检查间隔
    ).
    OnLoad(loadFunc).
    Build()
```

### 资源清理

```go
dcache.NewCache("my_cache", store).
    WithInterval(1000).
    OnLoad(loadFunc).
    OnClose(func(cb *dcache.CacheBuilder) error {
        // 在缓存关闭时清理资源
        // 例如：关闭数据库连接、清理临时文件等
        return nil
    }).
    Build()
```

### 日志记录

```go
// 使用自定义日志记录器
logger := &MyLogger{}
dcache.NewCache("my_cache", store).
    WithLogger(logger).
    OnLoad(loadFunc).
    Build()
```

## 实际应用示例

```go
package main

import (
    "sync"
    "time"
    "pkg/dcache"
)

type UserInfo struct {
    ID        int64
    Name      string
    Age       int
    Phone     string
    UpdatedAt time.Time
}

type UserStore struct {
    sync.RWMutex
    byID   map[int64]UserInfo
    byName map[string]UserInfo
}

func (s *UserStore) Load() error {
    s.Lock()
    defer s.Unlock()
    
    // 从数据库或其他数据源加载数据
    // 示例中使用模拟数据
    s.byID = make(map[int64]UserInfo)
    s.byName = make(map[string]UserInfo)
    
    // 填充数据...
    return nil
}

func (s *UserStore) GetByID(id int64) (UserInfo, bool) {
    s.RLock()
    defer s.RUnlock()
    user, ok := s.byID[id]
    return user, ok
}

func (s *UserStore) GetByName(name string) (UserInfo, bool) {
    s.RLock()
    defer s.RUnlock()
    user, ok := s.byName[name]
    return user, ok
}

func main() {
    store := &UserStore{
        byID:   make(map[int64]UserInfo),
        byName: make(map[string]UserInfo),
    }

    err := dcache.NewCache("users", store).
        WithInterval(1000).
        OnLoad(func(cb *dcache.CacheBuilder) error {
            return store.Load()
        }).
        OnCheck(func(cb *dcache.CacheBuilder) bool {
            // 检查是否有更新的条件
            // 例如：比较最后更新时间戳
            return true
        }).
        OnClose(func(cb *dcache.CacheBuilder) error {
            // 清理资源
            fmt.Println("缓存已关闭，清理资源")
            return nil
        }).
        Build()

    if err != nil {
        panic(err)
    }

    // 缓存现在会自动更新
    // 可以通过 dcache.GetStore("users") 获取存储实例
    time.Sleep(10 * time.Second) // 让缓存运行一段时间
}
```

## API 参考

### CacheBuilder 方法

- `NewCache(name string, store any) *CacheBuilder` - 创建新的缓存构建器
- `WithInterval(interval int64)` - 设置同步间隔时间
- `OnLoad(f func(cb *CacheBuilder) error)` - 设置加载数据函数
- `OnCheck(f func(cb *CacheBuilder) bool)` - 设置状态检查函数
- `OnClose(f func(cb *CacheBuilder) error)` - 设置资源清理函数
- `WithStartDelay(delay time.Duration)` - 设置启动延迟时间
- `WithStartCondition(readyFunc func() bool, checkInterval ...time.Duration)` - 设置启动条件
- `WithLogger(logger Logger)` - 设置日志记录器
- `OnStarted(f func(cb *CacheBuilder))` - 设置启动完成回调函数
- `Build()` - 构建并启动缓存
- `Start()` - 启动缓存
- `Pause()` - 暂停缓存更新
- `Close()` - 关闭缓存并清理资源

### 管理器函数

- `GetCacheByName(name string) *CacheBuilder` - 根据名称获取缓存实例
- `GetStore(name string) any` - 直接获取存储实例

## 日志级别

日志系统支持以下级别：

- `Silent` - 无日志
- `LevelError` - 错误日志
- `LevelWarn` - 警告日志
- `LevelInfo` - 信息日志

## 错误处理

包会返回以下错误类型：

- 存储实例为空
- 加载数据函数为空
- 缓存名称冲突时的警告

## 注意事项

1. 所有缓存操作都是线程安全的
2. 在使用并发访问缓存存储时，请确保您的存储结构实现适当的锁机制
3. 合理设置更新间隔以平衡性能和数据新鲜度
4. 使用 `OnCheck` 回调可以实现更智能的更新策略，避免不必要的更新
5. 使用 `OnClose` 回调可以确保在缓存关闭时正确清理资源，避免资源泄漏
6. 调用 `Close()` 方法会先暂停缓存更新，然后执行 `OnClose` 回调函数

## 许可证

MIT 许可证