GoFrame 缓存管理-方法介绍

以下常用方法列表，文档更新可能滞后于代码新特性，更多的方法及示例请参考代码文档：https://pkg.go.dev/github.com/gogf/gf/v2/os/gcache

Set

• 说明：使用​key-value​键值对设置缓存，键值可以是任意类型。
• 格式: 

Set(ctx context.Context, key interface{}, value interface{}, duration time.Duration) error

• 示例：将​slice​切片设置到键名​k1​的缓存中。

func ExampleCache_Set() {
	c := gcache.New()
	c.Set(ctx, "k1", g.Slice{1, 2, 3, 4, 5, 6, 7, 8, 9}, 0)
	fmt.Println(c.Get(ctx, "k1"))

	// Output:
	// [1,2,3,4,5,6,7,8,9] <nil>
}

SetAdapter

• 说明: ​SetAdapter​更改此缓存对象的底层适配器。请注意，此设置函数不是并发安全的。
• 格式：

SetAdapter(adapter Adapter)

• 示例：可以自己根据需要实现任意缓存适配器，实现接口方法即可。

func ExampleCache_SetAdapters() { 
	c := gcache.New()
	adapter := gcache.New()
	c.SetAdapter(adapter)
	c.Set(ctx, "k1", g.Slice{1, 2, 3, 4, 5, 6, 7, 8, 9}, 0)
	fmt.Println(c.Get(ctx, "k1"))

	// Output:
	// [1,2,3,4,5,6,7,8,9] <nil>
 }

SetIfNotExist

• 说明: 当指定​key​的键值不存在时设置其对应的键值​value​并返回​true​，否则什么都不做并返回​false​。
• 格式: 

SetIfNotExist(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (ok bool, err error)

• 示例：通过​SetIfNotExist​直接判断写入，并设置过期时间。

func ExampleCache_SetIfNotExist() { 
	c := gcache.New()
	// Write when the key name does not exist, and set the expiration time to 1000 milliseconds
	k1, err := c.SetIfNotExist(ctx, "k1", "v1", 1000*time.Millisecond)
	fmt.Println(k1, err)

	// Returns false when the key name already exists
	k2, err := c.SetIfNotExist(ctx, "k1", "v2", 1000*time.Millisecond)
	fmt.Println(k2, err)

	// Print the current list of key values
	keys1, _ := c.Keys(ctx)
	fmt.Println(keys1)

	// It does not expire if `duration` == 0. It deletes the `key` if `duration` < 0 or given `value` is nil.
	c.SetIfNotExist(ctx, "k1", 0, -10000)

	// Wait 1 second for K1: V1 to expire automatically
	time.Sleep(1200 * time.Millisecond)

	// Print the current key value pair again and find that K1: V1 has expired
	keys2, _ := c.Keys(ctx)
	fmt.Println(keys2)

	// Output:
	// true <nil>
	// false <nil>
	// [k1]
	// [<nil>]
 }

SetMap

• 说明: 批量设置键值对，输入参数类型为​map[interface{}]interface{}​。
• 格式: 

SetMap(ctx context.Context, data map[interface{}]interface{}, duration time.Duration) error

• 示例：

func ExampleCache_SetMap() { 
 	c := gcache.New()
	// map[interface{}]interface{}
	data := g.MapAnyAny{
		"k1": "v1",
		"k2": "v2",
		"k3": "v3",
	}
	c.SetMap(ctx, data, 1000*time.Millisecond)

	// Gets the specified key value
	v1, _ := c.Get(ctx, "k1")
	v2, _ := c.Get(ctx, "k2")
	v3, _ := c.Get(ctx, "k3")

	fmt.Println(v1, v2, v3)

	// Output:
	// v1 v2 v3
 }

Size

• 说明: ​Size​返回缓存中的项数。
• 格式: 

Size(ctx context.Context) (size int, err error)

• 示例：

func ExampleCache_Size() {
	c := gcache.New()

	// Add 10 elements without expiration
	for i := 0; i < 10; i++ {
		c.Set(ctx, i, i, 0)
	}

	// Size returns the number of items in the cache.
	n, _ := c.Size(ctx)
	fmt.Println(n)

	// Output:
	// 10
}

Update

• 说明: ​Update​更新​key​的对应的键值，但不更改其过期时间，并返回旧值。如果缓存中不存在​key​，则返回的​exist​值为​false​。
• 格式: 

Update(ctx context.Context, key interface{}, value interface{}) (oldValue *gvar.Var, exist bool, err error)

• 示例：通过​SetMap​添加多个缓存，通过​Update​指定​key​修改​value​。

func ExampleCache_Update() {     
	c := gcache.New()
	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2", "k3": "v3"}, 0)

	k1, _ := c.Get(ctx, "k1")
	fmt.Println(k1)
	k2, _ := c.Get(ctx, "k2")
	fmt.Println(k2)
	k3, _ := c.Get(ctx, "k3")
	fmt.Println(k3)

	re, exist, _ := c.Update(ctx, "k1", "v11")
	fmt.Println(re, exist)

	re1, exist1, _ := c.Update(ctx, "k4", "v44")
	fmt.Println(re1, exist1)

	kup1, _ := c.Get(ctx, "k1")
	fmt.Println(kup1)
	kup2, _ := c.Get(ctx, "k2")
	fmt.Println(kup2)
	kup3, _ := c.Get(ctx, "k3")
	fmt.Println(kup3)

	// Output:
	// v1
	// v2
	// v3
	// v1 true
	//  false
	// v11
	// v2
	// v3 
 }

UpdateExpire

• 说明: ​UpdateExpire​更新​key​的过期时间并返回旧的过期时间值。如果缓存中不存在​key​，则返回​-1​。
• 格式: 

UpdateExpire(ctx context.Context, key interface{}, duration time.Duration) (oldDuration time.Duration, err error)

• 示例：通过​UpdateExpire​更新​key​的过期时间并打印查看。

func ExampleCache_UpdateExpire() {     
	c := gcache.New()
	c.Set(ctx, "k1", "v1", 1000*time.Millisecond)
	expire, _ := c.GetExpire(ctx, "k1")
	fmt.Println(expire)

	c.UpdateExpire(ctx, "k1", 500*time.Millisecond)

	expire1, _ := c.GetExpire(ctx, "k1")
	fmt.Println(expire1)

	// Output:
	// 1s
	// 500ms	
}

Values

• 说明: 通过​Values​获取缓存中的所有值，以切片方式返回。
• 格式: 

Values(ctx context.Context) (values []interface{}, err error)

• 示例：通过​UpdateExpire​更新​key​的过期时间并打印查看。

func ExampleCache_Values() {     
	c := gcache.New()

	c.Set(ctx, "k1", g.Map{"k1": "v1", "k2": "v2"}, 0)

	// Values returns all values in the cache as slice.
	data, _ := c.Values(ctx)
	fmt.Println(data)

	// May Output:
	// [map[k1:v1 k2:v2]]
}

Close

• 说明: 关闭缓存，让​GC​回收资源，默认情况下可不关闭。
• 格式: 

Close(ctx context.Context) error

• 示例：通过​Close​即可关闭缓存。

func ExampleCache_Close() {     
 	c := gcache.New()

	c.Set(ctx, "k1", "v", 0)
	data, _ := c.Get(ctx, "k1")
	fmt.Println(data)

	// Close closes the cache if necessary.
	c.Close(ctx)

	data1, _ := c.Get(ctx, "k1")

	fmt.Println(data1)

 	// Output:
	// v
	// v
}

Contains

• 说明: 如果缓存中存在指定的​key​，则​Contains​返回​true​，否则返回​false​。
• 格式: 

Contains(ctx context.Context, key interface{}) (bool, error)

• 示例：

func ExampleCache_Contains() {     
 	c := gcache.New()

	// Set Cache
	c.Set(ctx, "k", "v", 0)

	data, _ := c.Contains(ctx, "k")
	fmt.Println(data)

	// return false
	data1, _ := c.Contains(ctx, "k1")
	fmt.Println(data1)
	
 	// Output:
	// true
	// false
}

Data

• 说明: 数据以​map​类型返回缓存中所有键值对(​'key':'value'​)的拷贝。
• 格式: 

Data(ctx context.Context) (data map[interface{}]interface{}, err error)

• 示例：获取所有缓存数据以​map[interface{}]interface{}​返回

func ExampleCache_Data() {     
  	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1"}, 0)
	//c.Set(ctx, "k5", "v5", 0)

	data, _ := c.Data(ctx)
	fmt.Println(data)

 	// Output:
	// map[k1:v1]
}

Get

• 说明: ​Get​检索并返回给定​key​的关联值。如果它不存在、值为零或已过期，则返回​nil​。
• 格式: 

Get(ctx context.Context, key interface{}) (*gvar.Var, error)

• 示例：

func ExampleCache_Get() {     
   	c := gcache.New()

	// Set Cache Object
	c.Set(ctx, "k1", "v1", 0)

	data, _ := c.Get(ctx, "k1")
	fmt.Println(data)
 	// Output:
	// v1
}

GetExpire

• 说明: ​GetExpire​检索并返回缓存中​key​的过期时间。注意，如果​key​为永不过期，则返回​0​。如果缓存中不存在​key​，则返回​-1​。
• 格式: 

GetExpire(ctx context.Context, key interface{}) (time.Duration, error)

• 示例：

func ExampleCache_GetExpire() {     
    c := gcache.New()

	// Set cache without expiration
	c.Set(ctx, "k", "v", 10000*time.Millisecond)

	expire, _ := c.GetExpire(ctx, "k")
	fmt.Println(expire)
	
 	// Output:
	// 10s
}

GetOrSet

• 说明: 检索并返回​key​的值，或者设置​key-value​对，如果缓存中不存在​key​，则直接设置。
• 格式: 

GetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) (result *gvar.Var, err error)

• 示例：用​GetOrSet​判断​key​不存在则直接设置，并设置​duration​时间。

func ExampleCache_GetOrSet() {     
    c := gcache.New()

	data, _ := c.GetOrSet(ctx, "k", "v", 10000*time.Millisecond)
	fmt.Println(data)

	data1, _ := c.Get(ctx, "k")
	fmt.Println(data1)

	// Output:
	// v
	// v
}

GetOrSetFunc

• 说明: 检索并返回​key​的值，如果​key​对应的值不存在则使用函数​func​的结果设置​key​，如果缓存中存在​key​，则返回其结果。
• 格式: 

GetOrSetFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (result *gvar.Var, err error)

• 示例：​key1​的设置返回​func​执行结果，​key2​返回​nil​则不执行任何操作。

func ExampleCache_GetOrSetFunc() {     
    c := gcache.New()

	c.GetOrSetFunc(ctx, 1, func() (interface{}, error) {
		return 111, nil
	}, 10000*time.Millisecond)
	v, _ := c.Get(ctx, 1)
	fmt.Println(v)

	c.GetOrSetFunc(ctx, 2, func() (interface{}, error) {
		return nil, nil
	}, 10000*time.Millisecond)
	v1, _ := c.Get(ctx, 2)
	fmt.Println(v1)

	// Output:
	// 111
	//
}

GetOrSetFuncLock

• 说明: 与​GetOrSetFunc​一致，但是不能重复或者覆盖注册缓存。
• 格式: 

GetOrSetFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) (result *gvar.Var, err error)

• 示例：​key1​的设置返回​func​执行结果，​key2​设置操作则失效。

func ExampleCache_GetOrSetFuncLock() {     
    c := gcache.New()

	c.GetOrSetFuncLock(ctx, 1, func() (interface{}, error) {
		return 11, nil
	}, 0)
	v, _ := c.Get(ctx, 1)
	fmt.Println(v)

	// Modification failed
	c.GetOrSetFuncLock(ctx, 1, func() (interface{}, error) {
		return 111, nil
	}, 0)
	v, _ = c.Get(ctx, 1)
	fmt.Println(v)

	c.Remove(ctx, g.Slice{1, 2, 3}...)

	// Modify locking
	c.GetOrSetFuncLock(ctx, 1, func() (interface{}, error) {
		return 111, nil
	}, 0)
	v, _ = c.Get(ctx, 1)
	fmt.Println(v)

	// Modification failed
	c.GetOrSetFuncLock(ctx, 1, func() (interface{}, error) {
		return 11, nil
	}, 0)
	v, _ = c.Get(ctx, 1)
	fmt.Println(v)

	// Output:
	// 11
	// 11
	// 111
	// 111
}

Keys

• 说明: 缓存中所有的​key​所有键名并以切片格式(​Slice​)返回。
• 格式: 

Keys(ctx context.Context) (keys []interface{}, err error)

• 示例：

func ExampleCache_Keys() {     
    c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1"}, 0)

	// Print the current list of key values
	keys1, _ := c.Keys(ctx)
	fmt.Println(keys1)

	// Output:
	// [k1]
}

KeyStrings

• 说明: ​KeyStrings​以字符串切片的形式返回缓存中的所有键。
• 格式: 

func (c *Cache) KeyStrings(ctx context.Context) ([]string, error) {
	keys, err := c.Keys(ctx)
	if err != nil {
		return nil, err
	}
	return gconv.Strings(keys), nil
}

• 示例：

func ExampleCache_KeyStrings() {
	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2"}, 0)

	// KeyStrings returns all keys in the cache as string slice.
	keys,_ := c.KeyStrings(ctx)
	fmt.Println(keys)

	// May Output:
	// [k1 k2]
}

Remove

• 说明: 移除从缓存中删除一个或多个键，并返回最后一个删除的键值。
• 格式: 

Remove(ctx context.Context, keys ...interface{}) (lastValue *gvar.Var, err error)

• 示例：

func ExampleCache_Remove() {     
    c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2"}, 0)

	c.Remove(ctx, "k1")

	data, _ := c.Data(ctx)
	fmt.Println(data)

	// Output:
	// map[k2:v2]
}

Removes

• 说明: 从缓存中删除多个键。
• 格式: 

func (c *Cache) Removes(ctx context.Context, keys []interface{}) error {
	_, err := c.Remove(ctx, keys...)
	return err
}

• 示例：

func ExampleCache_Removes() {     
    c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2", "k3": "v3", "k4": "v4"}, 0)

	c.Removes(ctx, g.Slice{"k1", "k2", "k3"})

	data, _ := c.Data(ctx)
	fmt.Println(data)

	// Output:
	// map[k4:v4]
}

MustGet

• 说明: ​MustGet​检索并返回给定​key​的关联值。如果它不存在、值为零或已过期，则返回​nil如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustGet(ctx context.Context, key interface{}) *gvar.Var {
	v, err := c.Get(ctx, key)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustGet() {         
 	c := gcache.New()		
	
 	c.Set(ctx, "k1", "v1", 0)
 	k2 := c.MustGet(ctx, "k2")
	
 	k1 := c.MustGet(ctx, "k1")
	fmt.Println(k1)

	fmt.Println(k2)

 	// Output:
	// v1
}

MustGetOrSet

• 说明: 检索并返回​​key​​的值，或者设置​​key-value​​对，如果缓存中不存在​​key​​，则直接设置。如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustGetOrSet(ctx context.Context, key interface{}, value interface{}, duration time.Duration) *gvar.Var {
	v, err := c.GetOrSet(ctx, key, value, duration)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustGetOrSet() {

	// Create a cache object,
	// Of course, you can also easily use the gcache package method directly
	c := gcache.New()

	// MustGetOrSet acts like GetOrSet, but it panics if any error occurs.
	k1 := c.MustGetOrSet(ctx, "k1", "v1", 0)
	fmt.Println(k1)

	k2 := c.MustGetOrSet(ctx, "k1", "v2", 0)
	fmt.Println(k2)

	// Output:
	// v1
	// v1

}

MustGetOrSetFunc

• 说明: 检索并返回​key​的值，如果​key​对应的值不存在则使用函数​func​的结果设置​key​，如果缓存中存在​key​，则返回其结果。如果​err​返回不为空则会​panic(err)​
• 格式: 

func (c *Cache) MustGetOrSetFunc(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) *gvar.Var {
	v, err := c.GetOrSetFunc(ctx, key, f, duration)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustGetOrSetFunc() {
	c := gcache.New()

	c.MustGetOrSetFunc(ctx, 1, func() (interface{}, error) {
		return 111, nil
	}, 10000*time.Millisecond)
	v := c.MustGet(ctx, 1)
	fmt.Println(v)

	c.MustGetOrSetFunc(ctx, 2, func() (interface{}, error) {
		return nil, nil
	}, 10000*time.Millisecond)
	v1 := c.MustGet(ctx, 2)
	fmt.Println(v1)

	// Output:
	// 111
	//
}

MustGetOrSetFuncLock

说明: 与​MustGetOrSetFunc​一致，但是不能重复或者覆盖注册缓存。如果​err​返回不为空则会​panic(err)​。

格式: 

func (c *Cache) MustGetOrSetFuncLock(ctx context.Context, key interface{}, f func() (interface{}, error), duration time.Duration) *gvar.Var {
	v, err := c.GetOrSetFuncLock(ctx, key, f, duration)
	if err != nil {
		panic(err)
	}
	return v
}

示例：

func ExampleCache_MustGetOrSetFuncLock() {
	c := gcache.New()

	c.MustGetOrSetFuncLock(ctx, "k1", func() (interface{}, error) {
		return "v1", nil
	}, 0)
	v := c.MustGet(ctx, "k1")
	fmt.Println(v)

	// Modification failed
	c.MustGetOrSetFuncLock(ctx, "k1", func() (interface{}, error) {
		return "update v1", nil
	}, 0)
	v = c.MustGet(ctx, "k1")
	fmt.Println(v)

	// Output:
	// v1
	// v1
}

MustContains

• 说明: 如果缓存中存在指定的​key​，则​Contains​返回​true​，否则返回​false​。如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustContains(ctx context.Context, key interface{}) bool {
	v, err := c.Contains(ctx, key)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustContains() {
	c := gcache.New()

	// Set Cache
	c.Set(ctx, "k", "v", 0)

	// Contains returns true if `key` exists in the cache, or else returns false.
	// return true
	data := c.MustContains(ctx, "k")
	fmt.Println(data)

	// return false
	data1 := c.MustContains(ctx, "k1")
	fmt.Println(data1)

	// Output:
	// true
	// false

}

MustGetExpire

• 说明:  ​MustGetExpire​检索并返回缓存中​key​的过期时间。注意，如果​key​为永不过期，则返回​0​。如果缓存中不存在​key​，则返回​-1​，如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustGetExpire(ctx context.Context, key interface{}) time.Duration {
	v, err := c.GetExpire(ctx, key)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustGetExpire() {
	c := gcache.New()

	// Set cache without expiration
	c.Set(ctx, "k", "v", 10000*time.Millisecond)

	// MustGetExpire acts like GetExpire, but it panics if any error occurs.
	expire := c.MustGetExpire(ctx, "k")
	fmt.Println(expire)

	// May Output:
	// 10s
}

MustSize

• 说明:  ​MustSize​返回缓存中的项数。如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustSize(ctx context.Context) int {
	v, err := c.Size(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustSize() {
	c := gcache.New()

	// Add 10 elements without expiration
	for i := 0; i < 10; i++ {
		c.Set(ctx, i, i, 0)
	}

	// Size returns the number of items in the cache.
	n := c.MustSize(ctx)
	fmt.Println(n)

	// Output:
	// 10
}

MustData

• 说明: 数据以​map​类型返回缓存中所有键值对(​'key':'value'​)的拷贝。如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustData(ctx context.Context) map[interface{}]interface{} {
	v, err := c.Data(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustData() {
	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1"}, 0)

	data := c.MustData(ctx)
	fmt.Println(data)

	// Set Cache
	c.Set(ctx, "k5", "v5", 0)
	data1, _ := c.Get(ctx, "k1")
	fmt.Println(data1)

	// Output:
	// map[k1:v1]
	// v1
}

MustKeys

• 说明: ​MustKeys​以(​slice​)切片的形式返回缓存中的所有键，如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustKeys(ctx context.Context) []interface{} {
	v, err := c.Keys(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustKeys() {
	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2"}, 0)

	// MustKeys acts like Keys, but it panics if any error occurs.
	keys1 := c.MustKeys(ctx)
	fmt.Println(keys1)

	// May Output:
	// [k1 k2]

}

MustKeyStrings

• 说明: ​MustKeyStrings​以字符串(​slice​)切片的形式返回缓存中的所有键。如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustKeyStrings(ctx context.Context) []string {
	v, err := c.KeyStrings(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustKeyStrings() {
	c := gcache.New()

	c.SetMap(ctx, g.MapAnyAny{"k1": "v1", "k2": "v2"}, 0)

	// MustKeyStrings returns all keys in the cache as string slice.
	// MustKeyStrings acts like KeyStrings, but it panics if any error occurs.
	keys := c.MustKeyStrings(ctx)
	fmt.Println(keys)

	// May Output:
	// [k1 k2]
}

MustValues

• 说明: ​MustValues​以(​slice​)切片的形式返回缓存中的所有值，如果​err​返回不为空则会​panic(err)​。
• 格式: 

func (c *Cache) MustValues(ctx context.Context) []interface{} {
	v, err := c.Values(ctx)
	if err != nil {
		panic(err)
	}
	return v
}

• 示例：

func ExampleCache_MustValues() {
	c := gcache.New()

	// Write value
	c.Set(ctx, "k1", "v1", 0)

	// Values returns all values in the cache as slice.
	data := c.MustValues(ctx)
	fmt.Println(data)

	// Output:
	// [v1]
}