不灭的焱

加密类型:SHA/AES/RSA下载Go
复合类型:切片(slice)、映射(map)、指针(pointer)、函数(function)、通道(channel)、接口(interface)、数组(array)、结构体(struct) Go类型+零值nil
引用类型:切片(slice)、映射(map)、指针(pointer)、函数(function)、通道(channel) Go引用

作者:AlbertWen  添加时间:2026-11-22 20:26:21  修改时间:2026-11-22 20:28:14  分类:04.GoFrame框架  编辑

目录

 

# 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.Var
  • GetString / 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 自动转为 slice
  • Remove(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 高频踩坑清单

  1. IsEmpty() 宽松判定,0 也返回 true,区分业务空和转换失败
  2. XxxDef 只有转换失败才触发默认,"0" 不会走默认
  3. Clone() 浅拷贝,引用类型底层共享;需要隔离使用 Copy()
  4. GetVar 不存在路径返回空 Var,不会 panic,要主动校验
  5. 并发安全开关只保护容器,不保护内部 map、slice
  6. 固定类型场景优先原生类型,避免反复 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 等)**。