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