臭小子のBlog

`github.com/gogf/gf/v2/util/gconv` 使用教程（基于最新文档）

2025 年 04 月 30 日

15 次浏览

3837字数

gconv 是 GoFrame 框架 v2 版本中的一个通用类型转换工具包，旨在简化不同数据类型之间的转换操作。它通过反射和泛型能力，提供了丰富的方法来处理基础类型、结构体、集合（如 map 和 slice）等复杂数据的转换需求。

📦 安装

首先确保你已经引入了 GoFrame v2：

go get github.com/gogf/gf/v2/util/gconv

之后即可导入 gconv 包：

import "github.com/gogf/gf/v2/util/gconv"

🧱 基础类型转换

gconv 支持几乎所有 Go 原生类型之间的转换，包括但不限于 string, int, float, bool, time.Time 等。

示例：基本类型转换

package main

import (
    "fmt"
    "github.com/gogf/gf/v2/util/gconv"
)

func main() {
    // string -> int
    i := gconv.Int("123")
    fmt.Println(i) // 123

    // interface{} -> float64
    var x interface{} = "3.14"
    f := gconv.Float64(x)
    fmt.Println(f) // 3.14

    // string -> bool
    b := gconv.Bool("true")
    fmt.Println(b) // true

    // string -> time.Time
    t := gconv.Time("2025-04-05 12:00:00")
    fmt.Println(t) // 2025-04-05 12:00:00 +0000 UTC
}

✅ 注意：如果转换失败，gconv 会返回目标类型的零值。若需错误提示，可使用带 WithError 的方法。

🔄 高级类型转换

1. 结构体与 Map 转换

将 `map[string]interface{}` 转换为结构体

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

data := map[string]interface{}{
    "name": "Alice",
    "age":  25,
}

var user User
err := gconv.Struct(data, &user)
if err != nil {
    panic(err)
}
fmt.Printf("%+v\n", user) // {Name:Alice Age:25}

将结构体转换为 `map`

user := User{Name: "Bob", Age: 30}
m := gconv.Map(user)
fmt.Println(m) // map[age:30 name:Bob]

2. Slice 与 Map 切换

`[]map[string]interface{}` 转 `[]struct`

users := []map[string]interface{}{
    {"name": "John", "age": 28},
    {"name": "Jane", "age": 32},
}

var userList []User
err := gconv.Structs(users, &userList)
// userList = [{Name:John Age:28}, {Name:Jane Age:32}]

`[]struct` 转 `[]map`

userList := []User{
    {Name: "Tom", Age: 20},
    {Name: "Jerry", Age: 22},
}

maps := gconv.Maps(userList)
// maps = [map[name:Tom age:20] map[name:Jerry age:22]]

🔁 反射与泛型支持

gconv 内部大量使用反射和泛型技术，因此可以处理任意嵌套结构的类型转换。

示例：深层嵌套结构体转换

type Address struct {
    City string
}

type Person struct {
    Name    string
    Age     int
    Address Address
}

data := map[string]interface{}{
    "Name": "Eve",
    "Age":  35,
    "Address": map[string]interface{}{
        "City": "New York",
    },
}

var p Person
gconv.Struct(data, &p)
fmt.Printf("%+v\n", p) // {Name:Eve Age:35 Address:{City:New York}}

⚠️ 错误处理

部分转换方法提供带错误返回的变体：

val, err := gconv.Int64WithError("not a number")
if err != nil {
    fmt.Println("Conversion failed:", err)
}

可用方法包括：

IntWithError
Float64WithError
BoolWithError
TimeWithError
StructWithError
StructsWithError

🛠️ 自定义类型转换器（Type Conversion Hook）

你可以注册自定义的类型转换逻辑，适用于特殊类型或格式。

示例：自定义时间格式转换

gconv.RegisterConverter(func(v interface{}) (time.Time, error) {
    s, ok := v.(string)
    if !ok {
        return time.Time{}, fmt.Errorf("invalid type for time conversion")
    }
    return time.Parse("2006-01-02", s)
})

t := gconv.Time("2025-04-05")
fmt.Println(t) // 2025-04-05 00:00:00 +0000 UTC