目录
# GoFrame v2 gvar.Var 完整教程
> 包路径:`github.com/gogf/gf/v2/container/gvar`
> 适用:GF v2;底层转换依赖 `gconv`;gvar 是通用动态变量,替代零散 `interface{}`
## 1 基础介绍
`gvar.Var`(框架简写 `g.Var`)是 GoFrame 的动态通用变量容器:
- 自带丰富自动类型转换
- 可选开启并发安全(内部加锁,默认关闭)
- 广泛用于 ORM 查询记录、配置、动态 JSON、请求参数、缓存动态值
### 安装导入
```bash
go get github.com/gogf/gf/v2
import ( "github.com/gogf/gf/v2/container/gvar" "github.com/gogf/gf/v2/frame/g" )
2 创建 Var
构造函数
// New(value any, safe ...bool) *Var
v1 := gvar.New(123)
v2 := gvar.New("hello", true) // 开启并发安全
v3 := g.NewVar(3.14) // 框架简写
safe=true:容器读写加锁,有性能开销,只读场景不建议开启Set(val any) old any:覆盖值,返回旧值
v := gvar.New(nil)
old := v.Set("new value")
3 基础取值与类型转换
底层复用 gconv 转换规则。
| 方法 | 说明 |
|---|---|
Val() any / Interface() any |
获取原始值 |
String() string |
转为字符串 |
Bool() bool |
转为布尔 |
Int() int / Int64() int64 |
整数 |
Uint() uint / Uint64() uint64 |
无符号整数 |
Float32() / Float64() |
浮点数 |
Bytes() []byte |
字节切片 |
Time(format ...string) |
解析为 time.Time |
Duration() |
解析为 time.Duration |
带默认值取值(XxxDef)
只有转换失败才返回默认值;能正常转换(例如 "0")则返回转换结果,不会走默认。
v := gvar.New("abc")
v.IntDef(0)
v.StringDef("default")
v.BoolDef(false)
v.Float64Def(99.9)
配套:StringsDef、IntsDef、MapDef。
4 集合转换
v := gvar.New([]int{1,2,3})
v.Slice() // []any
v.Ints()
v.Strings()
v.Float64s()
Map 相关:
v.Map() v.MapStrStr() v.MapStrVar() // map[string]*gvar.Var,支持链式取值
5 嵌套路径访问 Get / GetVar(高频)
路径使用 . 分隔,数组使用下标 list.0.name。
GetVar(path):返回*gvar.VarGetString / GetInt / GetStringDef:快捷取值- 路径不存在:返回空 Var,不会 panic,需要自行判断
data := gvar.New(g.Map{
"user": g.Map{
"info": g.Map{"mobile": "13800138000"},
},
"list": g.List{g.Map{"name":"Alice"}},
})
mobile := data.GetVar("user.info.mobile").String()
firstName := data.GetVar("list.0.name").String()
配套修改:
Append(...):内部是 slice 时追加;非 slice 自动转为 sliceRemove(path string):按路径删除字段
6 结构体映射 Scan
Scan 可以把 var 数据填充到结构体、结构体切片。
- 优先
json:"xxx"tag,无 tag 则字段名匹配(大小写不敏感) - 支持嵌套结构体
- 源为 JSON 字符串时,自动解析后再绑定
- 类型不兼容返回 error,不会静默脏数据
type Info struct {
Mobile string `json:"mobile"`
}
type User struct {
Id int `json:"id"`
Info *Info `json:"info"`
}
var u User
err := v.Scan(&u)
相关:Struct、Structs。
7 判断方法
| 方法 | 含义 |
|---|---|
IsNil() |
原始值是否为 nil |
IsEmpty() |
业务空判定(0、""、空切片、空 map 都返回 true) |
IsInt() / IsFloat() / IsMap() / IsSlice() / IsStruct() |
判断内部数据类型 |
Equals(any) |
宽松相等:两边统一转换后对比 |
v.Equals("100", 100)→ true;原生Val() ==是严格类型对比。
8 遍历 Range
slice / map 支持 Range 遍历,返回 false 停止遍历。
arrVar.Range(func(index int, val *gvar.Var) bool {
fmt.Println(index, val.String())
return true
})
mapVar.Range(func(key string, val *gvar.Var) bool {
fmt.Println(key, val.String())
return true
})
9 拷贝:Clone vs Copy
Clone():浅拷贝,引用类型底层共用,修改原对象会影响克隆结果Copy():深拷贝(v2.1+),嵌套数据独立隔离,开销更高
origin := gvar.New(g.Map{"arr": []int{1,2}})
cloneV := origin.Clone()
copyV := origin.Copy()
10 序列化与反序列化
*gvar.Var原生实现MarshalJSON,可以直接 json 包序列化UnmarshalValue:支持从 JSON 字符串、[]byte、map 填充变量
var v *gvar.Var
_ = v.UnmarshalValue([]byte(`{"name":"albert"}`))
11 配合 gdb ORM 实战
gdb.Record 本质 map[string]*gvar.Var,查询后直接取值:
rec, err := g.DB().Model("user").Where("id", 1).One()
if err != nil {
return
}
id := rec["id"].Int()
name := rec["name"].StringDef("")
12 并发安全边界
gvar.New(val, true) 保护的是 Var 容器本身(Set、GetVar、Remove 等)。 ⚠️ 不保护容器内部存放的 map、slice、自定义结构体;拿到引用后并发修改内部数据依然存在竞争风险。
13 gconv 转换规则表
基础转换
| 源值 | Int | Bool | Float64 | String |
|---|---|---|---|---|
| nil | 0 | false | 0.0 | "" |
| "123" | 123 | true | 123.0 | "123" |
| "0" | 0 | false | 0.0 | "0" |
| "true"/"yes"/"on" | 1 | true | 1 | "true" |
| "false"/"no"/"off" | 0 | false | 0 | "false" |
| "abc" | 转换失败 | false | 0 | "abc" |
| true | 1 | true | 1 | "true" |
| false | 0 | false | 0 | "false" |
| 3.14 | 3 | true | 3.14 | "3.14" |
IsEmpty 返回 true 场景
- nil
- 数值:0、0.0
- 字符串:""
- 切片、map:长度为 0
- 空指针
"0"、"false"字符串本身非空 →IsEmpty()= false
GetVar 路径规则
- 分隔符
.;数组下标为数字,例如list.0.name - 路径不存在返回空 Var,不 panic;校验存在性搭配
IsNil()
14 完整可运行 Demo
package main
import (
"fmt"
"github.com/gogf/gf/v2/container/gvar"
"github.com/gogf/gf/v2/frame/g"
)
type User struct {
Id int `json:"id"`
Name string `json:"name"`
Info *Info `json:"info"`
}
type Info struct {
Mobile string `json:"mobile"`
}
func main() {
vNormal := gvar.New("12345")
vSafe := gvar.New(100, true)
fmt.Println("vNormal.String:", vNormal.String())
fmt.Println("vSafe.Int:", vSafe.Int())
// XxxDef
vStr := gvar.New("abc")
fmt.Println("vStr.IntDef(0):", vStr.IntDef(0))
vNum := gvar.New("0")
fmt.Println("vNum.IntDef(99):", vNum.IntDef(99))
// 嵌套 GetVar
data := gvar.New(g.Map{
"user": g.Map{
"info": g.Map{"mobile": "13800138000"},
},
"list": g.List{g.Map{"name": "Alice"}, g.Map{"name": "Bob"}},
})
mobile := data.GetVar("user.info.mobile").String()
firstName := data.GetVar("list.0.name").String()
fmt.Println("mobile:", mobile)
fmt.Println("list[0].name:", firstName)
// Scan
var u User
err := data.GetVar("user").Scan(&u)
if err != nil {
fmt.Printf("scan user err: %v\n", err)
} else {
fmt.Printf("scan result: %+v\n", u)
}
// Equals
v1 := gvar.New("100")
fmt.Println("v1.Equals(100):", v1.Equals(100))
// Range
fmt.Println("=== range slice ===")
arrVar := gvar.New(g.List{"a", "b", "c"})
arrVar.Range(func(idx int, val *gvar.Var) bool {
fmt.Println(idx, val.String())
return true
})
// Append & Remove
root := gvar.New(g.Map{"a": 1, "b": []int{1, 2}})
root.GetVar("b").Append(3, 4)
root.Remove("a")
fmt.Println("root after modify:", root.Map())
// Clone vs Copy
origin := gvar.New(g.Map{"arr": []int{1, 2}})
cloneV := origin.Clone()
copyV := origin.Copy()
origin.Map()["arr"].([]int)[0] = 99
fmt.Println("clone after modify origin:", cloneV.Map())
fmt.Println("copy after modify origin:", copyV.Map())
// 模拟 gdb Record
rec := g.Map{
"id": g.NewVar(1001),
"name": g.NewVar("Albert"),
}
recID := rec["id"].Int()
recName := rec["name"].StringDef("unknown")
fmt.Printf("gdb record: id=%d, name=%s\n", recID, recName)
// 空值判断
emptyV := gvar.New("")
fmt.Println("emptyV.IsNil:", emptyV.IsNil())
fmt.Println("emptyV.IsEmpty:", emptyV.IsEmpty())
}
15 高频踩坑清单
IsEmpty()宽松判定,0也返回 true,区分业务空和转换失败XxxDef只有转换失败才触发默认,"0"不会走默认Clone()浅拷贝,引用类型底层共享;需要隔离使用Copy()GetVar不存在路径返回空 Var,不会 panic,要主动校验- 并发安全开关只保护容器,不保护内部 map、slice
- 固定类型场景优先原生类型,避免反复 gconv 转换带来开销
16 适用场景 & 取舍
| 用法 | 推荐场景 | 风险 |
|---|---|---|
| gvar.New | 动态参数、配置、ORM 行 | 无锁,并发写有竞争 |
| gvar.New(val, true) | 多协程读写同一个 var 容器 | 锁开销;不保护内部引用对象 |
| Clone() | 只读临时视图 | 共享底层引用 |
| Copy() | 数据隔离 | 深拷贝性能开销 |
| Scan | 动态数据绑定结构体 | 结构不匹配返回 error,务必捕获 |
17 官方参考
- 包文档:
github.com/gogf/gf/v2/container/gvar - 配套:gconv 类型转换、gdb、g.Map / g.List
操作方法: 1. 全选上面所有文本 → 复制 2. 在本地新建文本文档,粘贴进去 3. 另存为,文件名填 `gvar-tutorial.md`,编码选 UTF-8,保存即可。 如果你想要,下一步我可以再给一份配套的:**gvar 工具封装(SafeGet、MustScan、PathExists 等)**。