56 lines
2.3 KiB
Markdown
56 lines
2.3 KiB
Markdown
# @go/convert
|
||
|
||
`@go/convert` 是一个为“零摩擦”数据映射设计的深度转换库。它的核心哲学是**意图优先**：通过目标对象的类型推断用户的需求，并尽力抹平输入数据与目标形状之间的鸿沟。
|
||
|
||
## 🎯 设计哲学
|
||
|
||
* **消除类型摩擦**：在业务代码中，我们经常遇到单值与切片、字符串与结构体之间的转换。`convert` 能够自动处理这些“形状”差异（如将单值包装成切片，或将切片解包为单值）。
|
||
* **极致容忍 Key 名**：Map 键名可能是 `user_id`，也可能是 `UserId`。`convert` 在映射时会忽略所有非字母数字字符及大小写，确保映射成功。
|
||
* **指针透明化**：无论是 `int` 映射到 `*string`，还是 `***int` 映射到 `int`，`convert` 都会自动处理深层指针的穿透与分配。
|
||
* **可定制转换**：支持 `ParseXxx` 方法作为转换钩子，允许对象在被映射时执行特定的解析逻辑。
|
||
|
||
## 🚀 核心特性
|
||
|
||
* **深度映射**：支持 Struct、Map、Slice 之间的无限层级嵌套转换。
|
||
* **智能切片转换**：
|
||
* 单值 -> 切片：自动包装为 `[]T{val}`。
|
||
* 切片 -> 单值：自动取首个元素。
|
||
* CSV 字符串 -> 切片：支持 `"1,2,3"` 风格的自动拆分。
|
||
* **函数转换**：支持将一个函数转换为另一个签名的函数，并在调用时自动转换参数和返回值。
|
||
* **接口支持**：兼容 `json.Unmarshaler` 和 `yaml.Unmarshaler`。
|
||
* **平展工具**：提供 `FlatStruct` 工具，可将复杂的嵌套结构体平展为扁平的字段列表。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
go get apigo.cc/go/convert
|
||
```
|
||
|
||
## 💡 快速开始
|
||
|
||
```go
|
||
import "apigo.cc/go/convert"
|
||
|
||
// 1. 极致去摩擦的键名匹配
|
||
from := map[string]any{"user_id": 1001, "USER-NAME": "Andy"}
|
||
type User struct { UserID int; UserName string }
|
||
var u User
|
||
convert.To(from, &u) // u.UserID = 1001, u.UserName = "Andy"
|
||
|
||
// 2. 切片自动解包
|
||
nums := []int{100, 200}
|
||
var n int
|
||
convert.To(nums, &n) // n = 100
|
||
|
||
// 3. 智能 CSV 解析
|
||
tags := "tag1, tag2, tag3"
|
||
var tagList []string
|
||
convert.To(tags, &tagList) // ["tag1", "tag2", "tag3"]
|
||
|
||
// 4. 函数动态映射
|
||
f1 := func(a int) int { return a + 1 }
|
||
var f2 func(string) string
|
||
convert.To(f1, &f2)
|
||
fmt.Println(f2("10")) // "11"
|
||
```
|