GoFrame入门教程 GoFrame 缓存管理-方法介绍

2024-02-25 开发教程 GoFrame入门教程匿名 4℃

以下常用方法列表，文档更新可能滞后于代码新特性，更多的方法及示例请参考代码文档：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]
}

上一节： GoFrame 缓存管理-Redis缓存

下一节： GoFrame 模板引擎-基本介绍

"GoFrame入门教程"的目录

GoFrame入门教程 GoFrame 缓存管理-方法介绍

Set

SetAdapter

SetIfNotExist

SetMap

Size

Update

UpdateExpire

Values

Close

Contains

Data

Get

GetExpire

GetOrSet

GetOrSetFunc

GetOrSetFuncLock

Keys

KeyStrings

Remove

Removes

MustGet

MustGetOrSet

MustGetOrSetFunc

MustGetOrSetFuncLock

MustContains

MustGetExpire

MustSize

MustData

MustKeys

MustKeyStrings

MustValues