61 lines
2.0 KiB
Markdown
61 lines
2.0 KiB
Markdown
# 关于本项目
|
||
|
||
本项目完全由 AI 维护。代码源自 github.com/ssgo/u 的重构。
|
||
|
||
# @go/convert
|
||
|
||
`@go/convert` 是一个为“零摩擦”数据映射设计的深度转换库。它的核心哲学是**意图优先**：通过目标对象的类型推断用户的需求，并尽力抹平输入数据与目标形状之间的鸿沟。
|
||
|
||
## 🎯 设计哲学
|
||
|
||
* **消除类型摩擦**：在业务代码中，我们经常遇到单值与切片、字符串与结构体之间的转换。`convert` 能够自动处理这些“形状”差异。
|
||
* **极致容忍 Key 名**：忽略所有非字母数字字符及大小写，确保不同来源的数据都能精准映射。
|
||
* **指针透明化**：自动处理深层指针的穿透与分配。
|
||
* **可定制转换**：通过方法钩子实现特定的解析逻辑。
|
||
|
||
## 🛠 API Reference
|
||
|
||
### 核心函数
|
||
|
||
#### `func To(from, to any)`
|
||
将 `from` 中的数据深度映射到 `to` 中。`to` 必须是一个**指针**类型。
|
||
- **支持类型**：基础类型互转、Struct 互转、Map 转 Struct、Struct 转 Map、Slice 互转等。
|
||
- **去摩擦特性**：支持单值与切片的互转（包装/解包）、CSV 字符串转切片。
|
||
|
||
#### `func Convert(from, to any)`
|
||
`To` 的别名，用于保持向前兼容。
|
||
|
||
### 结构体分析
|
||
|
||
#### `func FlatStruct(data any) *StructInfo`
|
||
平展结构体。返回导出字段、导出方法及其对应的 `reflect.Value` 映射。
|
||
|
||
#### `func FlatStructWithUnexported(data any) *StructInfo`
|
||
平展结构体，包含未导出的字段和方法。
|
||
|
||
### 定制转换钩子
|
||
|
||
如果目标结构体定义了 `func (p *T) ParseXxx(v any) FieldType` 方法（其中 `Xxx` 为字段名），`convert` 将优先调用该方法来决定字段的值。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
go get apigo.cc/go/convert
|
||
```
|
||
|
||
## 💡 快速开始
|
||
|
||
```go
|
||
import "apigo.cc/go/convert"
|
||
|
||
// 1. 模糊键名匹配
|
||
from := map[string]any{"user-id": 1001}
|
||
var u struct { UserID int }
|
||
convert.To(from, &u) // u.UserID = 1001
|
||
|
||
// 2. 切片自动解包
|
||
nums := []int{100, 200}
|
||
var n int
|
||
convert.To(nums, &n) // n = 100
|
||
```
|