@colin4k1024/tsp 2.4.0

package/skills/goframe-v2/references//347/273/204/344/273/266/345/210/227/350/241/250//346/225/260/346/215/256/347/273/223/346/236/204//345/255/227/345/205/270/347/261/273/345/236/213-gmap//345/255/227/345/205/270/347/261/273/345/236/213-/345/237/272/346/234/254/344/275/277/347/224/250.md

@@ -0,0 +1,544 @@
+## 泛型映射（推荐使用）
+
+从 `v2.10` 版本开始，`gmap` 提供了泛型映射 `KVMap[K, V]`、`ListKVMap[K, V]` 和 `TreeKVMap[K, V]`，提供类型安全的映射操作。开发者可以使用 `NewKVMap[string, int]()` 等方式创建指定类型的映射，避免类型断言和运行时错误。
+
+### 泛型哈希映射 `KVMap`
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+)
+
+func main() {
+    // 创建一个键为string，值为int的泛型哈希映射
+    m := gmap.NewKVMap[string, int]()
+    
+    // 设置键值对
+    m.Set("apple", 1)
+    m.Set("banana", 2)
+    m.Set("orange", 3)
+    
+    // 获取值
+    if value, ok := m.Get("apple"); ok {
+        fmt.Println("apple:", value) // 输出: apple: 1
+    }
+    
+    // 获取所有键值
+    fmt.Println("Keys:", m.Keys())
+    fmt.Println("Values:", m.Values())
+    
+    // 遍历
+    m.Iterator(func(k string, v int) bool {
+        fmt.Printf("%s: %d\n", k, v)
+        return true
+    })
+}
+```
+
+### 泛型有序映射 `ListKVMap`
+
+`ListKVMap` 是按照插入顺序维护键值对的有序映射。
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+)
+
+func main() {
+    // 创建有序映射
+    m := gmap.NewListKVMap[string, int]()
+    
+    // 按顺序插入
+    m.Set("third", 3)
+    m.Set("first", 1)
+    m.Set("second", 2)
+    
+    // 遍历会按插入顺序输出
+    m.Iterator(func(k string, v int) bool {
+        fmt.Printf("%s: %d\n", k, v)
+        return true
+    })
+    
+    // Output:
+    // third: 3
+    // first: 1
+    // second: 2
+}
+```
+
+### 泛型树形映射 `TreeKVMap`
+
+`TreeKVMap` 使用红黑树实现，键值对按照比较函数定义的顺序排序。
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+    "github.com/gogf/gf/v2/util/gutil"
+)
+
+func main() {
+    // 创建树形映射，使用字符串比较函数
+    m := gmap.NewTreeKVMap[string, int](gutil.ComparatorString)
+    
+    // 插入数据
+    m.Set("banana", 2)
+    m.Set("apple", 1)
+    m.Set("orange", 3)
+    
+    // 遍历会按照键的字母序输出
+    m.Iterator(func(k string, v int) bool {
+        fmt.Printf("%s: %d\n", k, v)
+        return true
+    })
+    
+    // Output:
+    // apple: 1
+    // banana: 2
+    // orange: 3
+}
+```
+
+### 自定义 `nil` 值检查器
+
+:::tip
+`NilChecker` 是一个可选参数，并非必须提供。它主要用于解决`typed nil`问题，并提供更好的`nil`判断性能。在默认情况下，组件使用**反射**来判断数据是否为`nil`。
+:::
+
+对于指针类型、接口类型等，可能需要自定义 `nil` 判断逻辑。`NewKVMapWithChecker` 系列函数支持自定义 `nil` 检查器。
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+)
+
+type User struct {
+    ID   int
+    Name string
+}
+
+func main() {
+    // 为指针类型创建映射，使用自定义nil检查器
+    m := gmap.NewKVMapWithChecker[string, *User](func(u *User) bool {
+        return u == nil || u.ID == 0
+    })
+    
+    m.Set("user1", &User{ID: 1, Name: "John"})
+    m.Set("user2", &User{ID: 0, Name: "Invalid"}) // 会被视为nil
+    
+    // GetOrSet在值为nil时会设置新值
+    user := m.GetOrSet("user2", &User{ID: 2, Name: "Jane"})
+    fmt.Printf("user2: %+v\n", user)
+    
+    // Output:
+    // user2: &{ID:2 Name:Jane}
+}
+```
+
+### 泛型映射特点
+
+1. **类型安全**：在编译期就能发现类型错误，避免运行时类型断言失败。
+2. **自定义 `nil` 检查（可选）**：通过 `NewXXXWithChecker` 系列函数，可以为泛型类型自定义 `nil` 判断逻辑，解决类型化 `nil` 的问题。默认情况下使用反射判断。
+3. **性能优势**：减少了类型断言和反射的开销。
+4. **更好的IDE支持**：IDE能够提供更准确的代码补全和类型提示。
+
+:::tip
+推荐在新项目中使用泛型映射 `KVMap[K, V]`、`ListKVMap[K, V]` 和 `TreeKVMap[K, V]`，它们提供了更好的类型安全性和开发体验。
+:::
+
+## 传统映射类型
+
+下面介绍传统的映射类型，这些类型在旧版本中被广泛使用，仍然完全支持。
+
+### 并发安全
+
+`gmap` 支持并发安全选项开关，在默认情况下是 `非并发安全` 的，开发者可以选择开启 `gmap` 的并发安全特性(传递初始化开关参数 `safe` 参数值为 `true`, 必须在初始化时设定，不能运行时动态设定)。如：
+
+```go
+m := gmap.New(true)
+```
+
+不仅仅是 `gmap` 模块， `goframe` 框架的其他并发安全数据结构也支持并发安全特性开关。
+
+### 基本使用
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+)
+
+func main() {
+    // 创建一个默认的gmap对象，
+    // 默认情况下该gmap对象不支持并发安全特性，
+    // 初始化时可以给定true参数开启并发安全特性。
+    m := gmap.New()
+
+    // 设置键值对
+    for i := 0; i < 10; i++ {
+        m.Set(i, i)
+    }
+    // 查询大小
+    fmt.Println(m.Size())
+    // 批量设置键值对(不同的数据类型对象参数不同)
+    m.Sets(map[interface{}]interface{}{
+        10 : 10,
+        11 : 11,
+    })
+    fmt.Println(m.Size())
+
+    // 查询是否存在
+    fmt.Println(m.Contains(1))
+
+    // 查询键值
+    fmt.Println(m.Get(1))
+
+    // 删除数据项
+    m.Remove(9)
+    fmt.Println(m.Size())
+
+    // 批量删除
+    m.Removes([]interface{}{10, 11})
+    fmt.Println(m.Size())
+
+    // 当前键名列表(随机排序)
+    fmt.Println(m.Keys())
+    // 当前键值列表(随机排序)
+    fmt.Println(m.Values())
+
+    // 查询键名，当键值不存在时，写入给定的默认值
+    fmt.Println(m.GetOrSet(100, 100))
+
+    // 删除键值对，并返回对应的键值
+    fmt.Println(m.Remove(100))
+
+    // 遍历map
+    m.Iterator(func(k interface{}, v interface{}) bool {
+        fmt.Printf("%v:%v ", k, v)
+        return true
+    })
+
+    // 自定义写锁操作
+    m.LockFunc(func(m map[interface{}]interface{}) {
+        m[99] = 99
+    })
+
+    // 自定义读锁操作
+    m.RLockFunc(func(m map[interface{}]interface{}) {
+        fmt.Println(m[99])
+    })
+
+    // 清空map
+    m.Clear()
+
+    // 判断map是否为空
+    fmt.Println(m.IsEmpty())
+}
+```
+
+执行后，输出结果为：
+
+```10
+12
+true
+1
+11
+9
+[0 1 2 4 6 7 3 5 8]
+[3 5 8 0 1 2 4 6 7]
+100
+100
+3:3 5:5 8:8 7:7 0:0 1:1 2:2 4:4 6:6 99
+true
+```
+
+### 有序遍历
+
+我们来看一下三种不同类型 `map` 的有序性遍历示例。
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/frame/g"
+    "github.com/gogf/gf/v2/container/gmap"
+    "github.com/gogf/gf/v2/util/gutil"
+)
+
+func main() {
+    array   := g.Slice{2, 3, 1, 5, 4, 6, 8, 7, 9}
+    hashMap := gmap.New(true)
+    listMap := gmap.NewListMap(true)
+    treeMap := gmap.NewTreeMap(gutil.ComparatorInt, true)
+    for _, v := range array {
+        hashMap.Set(v, v)
+    }
+    for _, v := range array {
+        listMap.Set(v, v)
+    }
+    for _, v := range array {
+        treeMap.Set(v, v)
+    }
+    fmt.Println("HashMap   Keys:", hashMap.Keys())
+    fmt.Println("HashMap Values:", hashMap.Values())
+    fmt.Println("ListMap   Keys:", listMap.Keys())
+    fmt.Println("ListMap Values:", listMap.Values())
+    fmt.Println("TreeMap   Keys:", treeMap.Keys())
+    fmt.Println("TreeMap Values:", treeMap.Values())
+}
+```
+
+执行后，输出结果为：
+
+```
+HashMap   Keys: [4 6 8 7 9 2 3 1 5]
+HashMap Values: [6 8 4 3 1 5 7 9 2]
+ListMap   Keys: [2 3 1 5 4 6 8 7 9]
+ListMap Values: [2 3 1 5 4 6 8 7 9]
+TreeMap   Keys: [1 2 3 4 5 6 7 8 9]
+TreeMap Values: [1 2 3 4 5 6 7 8 9]
+```
+
+### `FilterEmpty/FilterNil` 空值过滤
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+    "github.com/gogf/gf/v2/frame/g"
+)
+
+func main() {
+    m1 := gmap.NewFrom(g.MapAnyAny{
+        "k1": "",
+        "k2": nil,
+        "k3": 0,
+        "k4": 1,
+    })
+    m2 := gmap.NewFrom(g.MapAnyAny{
+        "k1": "",
+        "k2": nil,
+        "k3": 0,
+        "k4": 1,
+    })
+    m1.FilterEmpty()
+    m2.FilterNil()
+    fmt.Println(m1.Map())
+    fmt.Println(m2.Map())
+
+    // Output:
+    // map[k4:1]
+    // map[k1: k3:0 k4:1]
+}
+```
+
+### `Flip` 键值对反转
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+    "github.com/gogf/gf/v2/frame/g"
+)
+
+func main() {
+    var m gmap.Map
+    m.Sets(g.MapAnyAny{
+        "k1": "v1",
+        "k2": "v2",
+    })
+    m.Flip()
+    fmt.Println(m.Map())
+
+    // May Output:
+    // map[v1:k1 v2:k2]
+}
+```
+
+### `Keys/Values` 键名/数值列表
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+    "github.com/gogf/gf/v2/frame/g"
+)
+
+func main() {
+    var m gmap.Map
+    m.Sets(g.MapAnyAny{
+        "k1": "v1",
+        "k2": "v2",
+        "k3": "v3",
+        "k4": "v4",
+    })
+    fmt.Println(m.Keys())
+    fmt.Println(m.Values())
+
+    // May Output:
+    // [k1 k2 k3 k4]
+    // [v2 v3 v4 v1]
+}
+```
+
+### `Pop/Pops` 随机出栈
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+    "github.com/gogf/gf/v2/frame/g"
+)
+
+func main() {
+    var m gmap.Map
+    m.Sets(g.MapAnyAny{
+        "k1": "v1",
+        "k2": "v2",
+        "k3": "v3",
+        "k4": "v4",
+    })
+    fmt.Println(m.Pop())
+    fmt.Println(m.Pops(2))
+    fmt.Println(m.Size())
+
+    // May Output:
+    // k1 v1
+    // map[k2:v2 k4:v4]
+    // 1
+}
+```
+
+### `SetIfNotExist*` 判断性写入
+
+判断性写入是指当指定的键名不存在时则写入并且方法返回 `true`，否则忽略写入并且方法返回 `false`。相关方法如下：
+
+- `SetIfNotExist`
+- `SetIfNotExistFunc`
+- `SetIfNotExistFuncLock`
+
+方法具体描述请查看接口文档或源码注释。
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+)
+
+func main() {
+    var m gmap.Map
+    fmt.Println(m.SetIfNotExist("k1", "v1"))
+    fmt.Println(m.SetIfNotExist("k1", "v1"))
+    fmt.Println(m.Map())
+
+    // Output:
+    // true
+    // false
+    // map[k1:v1]
+}
+```
+
+### `Merge` 字典表合并
+
+```go
+package main
+
+import (
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+)
+
+func main() {
+    var m1, m2 gmap.Map
+    m1.Set("key1", "val1")
+    m2.Set("key2", "val2")
+    m1.Merge(&m2)
+    fmt.Println(m1.Map())
+
+    // May Output:
+    // map[key1:val1 key2:val2]
+}
+```
+
+### `JSON` 序列化/反序列
+
+`gmap` 模块下的所有容器类型均实现了标准库 `json` 数据格式的序列化/反序列化接口。
+
+1\. `Marshal`
+
+```go
+package main
+
+import (
+    "encoding/json"
+    "fmt"
+    "github.com/gogf/gf/v2/frame/g"
+
+    "github.com/gogf/gf/v2/container/gmap"
+)
+
+func main() {
+    m := gmap.New()
+    m.Sets(g.MapAnyAny{
+        "name":  "john",
+        "score": 100,
+    })
+    b, _ := json.Marshal(m)
+    fmt.Println(string(b))
+}
+```
+
+执行后，输出结果：
+
+```
+{"name":"john","score":100}
+```
+
+2. `Unmarshal`
+
+```go
+package main
+
+import (
+    "encoding/json"
+    "fmt"
+    "github.com/gogf/gf/v2/container/gmap"
+)
+
+func main() {
+    m := gmap.Map{}
+    s := []byte(`{"name":"john","score":100}`)
+    json.Unmarshal(s, &m)
+    fmt.Println(m.Map())
+}
+```
+
+执行后，输出结果：
+
+```
+map[name:john score:100]
+```

package/skills/goframe-v2/references//347/273/204/344/273/266/345/210/227/350/241/250//346/225/260/346/215/256/347/273/223/346/236/204//345/255/227/345/205/270/347/261/273/345/236/213-gmap//345/255/227/345/205/270/347/261/273/345/236/213-/346/200/247/350/203/275/346/265/213/350/257/225.md

@@ -0,0 +1,79 @@
+## 性能测试
+
+### 并发安全
+
+[https://github.com/gogf/gf/blob/master/container/gmap/gmap\_z\_bench\_safe\_test.go](https://github.com/gogf/gf/blob/master/container/gmap/gmap_z_bench_safe_test.go)
+
+```
+goos: linux
+goarch: amd64
+Benchmark_IntIntMap_Set-4               10000000               202 ns/op              15 B/op          0 allocs/op
+Benchmark_IntAnyMap_Set-4               10000000               262 ns/op              29 B/op          1 allocs/op
+Benchmark_IntStrMap_Set-4               10000000               241 ns/op              22 B/op          0 allocs/op
+Benchmark_AnyAnyMap_Set-4                5000000               359 ns/op              40 B/op          2 allocs/op
+Benchmark_StrIntMap_Set-4                5000000               305 ns/op              26 B/op          1 allocs/op
+Benchmark_StrAnyMap_Set-4                5000000               354 ns/op              40 B/op          2 allocs/op
+Benchmark_StrStrMap_Set-4                5000000               338 ns/op              32 B/op          1 allocs/op
+Benchmark_IntIntMap_Get-4               20000000              86.6 ns/op               0 B/op          0 allocs/op
+Benchmark_IntAnyMap_Get-4               30000000              69.7 ns/op               0 B/op          0 allocs/op
+Benchmark_IntStrMap_Get-4               30000000              69.6 ns/op               0 B/op          0 allocs/op
+Benchmark_AnyAnyMap_Get-4               20000000              74.4 ns/op               0 B/op          0 allocs/op
+Benchmark_StrIntMap_Get-4               20000000               116 ns/op               7 B/op          0 allocs/op
+Benchmark_StrAnyMap_Get-4               20000000              92.3 ns/op               7 B/op          0 allocs/op
+Benchmark_StrStrMap_Get-4               20000000              91.9 ns/op               7 B/op          0 allocs/op
+```
+
+### 非并发安全
+
+[https://github.com/gogf/gf/blob/master/container/gmap/gmap\_z\_bench\_unsafe\_test.go](https://github.com/gogf/gf/blob/master/container/gmap/gmap_z_bench_unsafe_test.go)
+
+```
+goos: linux
+goarch: amd64
+Benchmark_Unsafe_IntIntMap_Set-4        10000000               318 ns/op              62 B/op          0 allocs/op
+Benchmark_Unsafe_IntAnyMap_Set-4         5000000               282 ns/op              57 B/op          1 allocs/op
+Benchmark_Unsafe_IntStrMap_Set-4         5000000               332 ns/op              82 B/op          1 allocs/op
+Benchmark_Unsafe_AnyAnyMap_Set-4         3000000               471 ns/op              73 B/op          2 allocs/op
+Benchmark_Unsafe_StrIntMap_Set-4         5000000               429 ns/op              82 B/op          1 allocs/op
+Benchmark_Unsafe_StrAnyMap_Set-4         3000000               424 ns/op              73 B/op          2 allocs/op
+Benchmark_Unsafe_StrStrMap_Set-4         2000000               515 ns/op              96 B/op          2 allocs/op
+Benchmark_Unsafe_IntIntMap_Get-4        10000000               133 ns/op               0 B/op          0 allocs/op
+Benchmark_Unsafe_IntAnyMap_Get-4        20000000               134 ns/op               0 B/op          0 allocs/op
+Benchmark_Unsafe_IntStrMap_Get-4        10000000               126 ns/op               0 B/op          0 allocs/op
+Benchmark_Unsafe_AnyAnyMap_Get-4        10000000               166 ns/op               0 B/op          0 allocs/op
+Benchmark_Unsafe_StrIntMap_Get-4         5000000               246 ns/op               7 B/op          0 allocs/op
+Benchmark_Unsafe_StrAnyMap_Get-4        10000000               238 ns/op               7 B/op          0 allocs/op
+Benchmark_Unsafe_StrStrMap_Get-4         5000000               229 ns/op               7 B/op          0 allocs/op
+```
+
+### 不同类型map性能
+
+[https://github.com/gogf/gf/blob/master/container/gmap/gmap\_z\_bench\_maps\_test.go](https://github.com/gogf/gf/blob/master/container/gmap/gmap_z_bench_maps_test.go)
+
+```
+goos: linux
+goarch: amd64
+Benchmark_HashMap_Set-4                  5000000               349 ns/op              40 B/op          2 allocs/op
+Benchmark_ListMap_Set-4                  3000000               455 ns/op              87 B/op          3 allocs/op
+Benchmark_TreeMap_Set-4                  3000000               481 ns/op              28 B/op          2 allocs/op
+Benchmark_HashMap_Get-4                 30000000              67.8 ns/op               0 B/op          0 allocs/op
+Benchmark_ListMap_Get-4                 20000000              74.5 ns/op               0 B/op          0 allocs/op
+Benchmark_TreeMap_Get-4                 20000000               189 ns/op               8 B/op          1 allocs/op
+```
+
+### `gmap` 与 `sync.Map` 性能比较
+
+go语言从 `1.9` 版本开始引入了并发安全的 `sync.Map`，但 `gmap` 比较于标准库的 `sync.Map` 性能更加优异，并且功能更加丰富。
+
+我们来看看基准测试对比结果： [https://github.com/gogf/gf/blob/master/container/gmap/gmap\_z\_bench\_syncmap\_test.go](https://github.com/gogf/gf/blob/master/container/gmap/gmap_z_bench_syncmap_test.go)
+
+```
+goos: linux
+goarch: amd64
+Benchmark_GMapSet-4                     10000000               209 ns/op              15 B/op          0 allocs/op
+Benchmark_SyncMapSet-4                   3000000               451 ns/op              67 B/op          3 allocs/op
+Benchmark_GMapGet-4                     30000000              66.4 ns/op               0 B/op          0 allocs/op
+Benchmark_SyncMapGet-4                  30000000              36.0 ns/op               0 B/op          0 allocs/op
+Benchmark_GMapRemove-4                  10000000               207 ns/op               0 B/op          0 allocs/op
+Benchmark_SyncMapRmove-4                30000000              42.4 ns/op               0 B/op          0 allocs/op
+```