缓存管理-方法介绍 | GoFrame官网 - 类似PHP-Laravel,Java-SpringBoot的Go企业级开发框架

版本：2.5.x

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

示例：

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(ctx context.Context) (interface{}, error), duration time.Duration) (result *gvar.Var, err error)

示例： k1 的设置返回 func 执行结果， k2 返回 nil 则不执行任何操作。

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

      c.GetOrSetFunc(ctx, "k1", func(ctx context.Context) (value interface{}, err error) {
          return "v1", nil
      }, 10000*time.Millisecond)
      v, _ := c.Get(ctx, "k1")
      fmt.Println(v)

      c.GetOrSetFunc(ctx, "k2", func(ctx context.Context) (value interface{}, err error) {
          return nil, nil
      }, 10000*time.Millisecond)
      v1, _ := c.Get(ctx, "k2")
      fmt.Println(v1)

      // Output:
      // v1
}

`GetOrSetFuncLock`

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

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

示例：第1次的设置返回 func 执行结果，第2次设置操作则失效。

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

      c.GetOrSetFuncLock(ctx, "k1", func(ctx context.Context) (value interface{}, err error) {
          return "v1", nil
      }, 0)
      v, _ := c.Get(ctx, "k1")
      fmt.Println(v)

      c.GetOrSetFuncLock(ctx, "k1", func(ctx context.Context) (value interface{}, err error) {
          return "update v1", nil
      }, 0)
      v, _ = c.Get(ctx, "k1")
      fmt.Println(v)

      c.Remove(ctx, g.Slice{"k1"}...)

      // Output:
      // v1
      // v1
}

`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(ctx context.Context) (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(ctx context.Context) (interface{}, error) {
          return 111, nil
      }, 10000*time.Millisecond)
      v := c.MustGet(ctx, 1)
      fmt.Println(v)

      c.MustGetOrSetFunc(ctx, 2, func(ctx context.Context) (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(ctx context.Context) (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(ctx context.Context) (interface{}, error) {
          return "v1", nil
      }, 0)
      v := c.MustGet(ctx, "k1")
      fmt.Println(v)

      // Modification failed
      c.MustGetOrSetFuncLock(ctx, "k1", func(ctx context.Context) (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]
}

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​

`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`