81 lines
3.4 KiB
Markdown
81 lines
3.4 KiB
Markdown
# @go/cast
|
||
|
||
> **Maintainer Statement:** 本项目完全由 AI 维护。任何改动均遵循代码质量与性能的最佳实践。
|
||
|
||
|
||
## 🎯 设计哲学
|
||
|
||
`@go/cast` 是一个为“敏捷开发”设计的 Go 基础工具库。设计初衷是打破 Go 严苛类型系统带来的繁琐摩擦，在处理数据时更关注需要什么类型而不是原本是什么类型。
|
||
|
||
* **弱化类型摩擦**：转换函数在失败时返回合理零值，专注业务流。
|
||
* **补足语言短板**：提供泛型工具类补足 Go 语言无三元运算等缺陷。
|
||
* **去标签化**：支持自动将 struct 字段名大写导出为小写，无需手动添加 JSON tag。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
go get apigo.cc/go/cast
|
||
```
|
||
|
||
## 💡 快速开始
|
||
|
||
```go
|
||
import "apigo.cc/go/cast"
|
||
|
||
// 基础转换
|
||
age := cast.Int("18") // 18
|
||
|
||
// 泛型三元运算
|
||
status := cast.If(isAdmin, "Admin", "User")
|
||
|
||
// 自动构建并填充 (Make 系列)
|
||
list := cast.MakeSlice[int]("123") // []int{123}
|
||
m := cast.MakeMap[string, any](map[string]int{"age": 18}) // map[string]any{"age": 18}
|
||
|
||
// JSON 泛型零摩擦构建 (From 系列，支持 string 或更安全的 []byte)
|
||
user := cast.MustFromJSON[User](`{"name": "Tom"}`)
|
||
|
||
// 原地填充 (To 系列)
|
||
var config map[string]any
|
||
cast.ToMap(&config, myStruct) // 自动拍平 struct 并填充到 map
|
||
```
|
||
|
||
## 🛠 API 指南
|
||
|
||
### 核心能力
|
||
|
||
1. **基础转换（含多级指针穿透）**
|
||
* `Int(any) int` | `Int64(any) int64`
|
||
* `Uint(any) uint` | `Uint64(any) uint64`
|
||
* `Float(any) float32` | `Float64(any) float64`
|
||
* `String(any) string` | `Bool(any) bool`
|
||
* `Duration(any) time.Duration`
|
||
|
||
2. **高级转化（Map/Slice Helpers）**
|
||
* `ToMap(target any, source any)` —— 将 source 填充到目标 map。支持 struct (递归拍平且导出字段转小写)、slice (KV 序列) 或 map (合并)。
|
||
* `ToSlice(target any, source any)` —— 将 source 填充到目标 slice。支持 map (KV 序列)、slice (追加) 或普通值 (追加)。
|
||
* `MakeMap[K comparable, V any](source any) map[K]V` —— 泛型构建并填充新 Map。
|
||
* `MakeSlice[T any](source any) []T` —— 泛型构建并填充新 Slice。
|
||
|
||
3. **序列化与泛型构建（JSON & YAML）**
|
||
* **JSON 编码**: `ToJSON(any)(string, error)` | `ToJSONDesensitize(any, []string)(string, error)` | `MustToJSON(any)string`
|
||
* **JSON 解码 (原地)**: `UnmarshalJSON(data, any) error` (支持 string 或为了内存安全推荐使用的 []byte)
|
||
* **JSON 构建 (泛型)**: `FromJSON[T](data) (T, error)` | `MustFromJSON[T](data) T`
|
||
* **YAML 编码**: `ToYAML(any)(string, error)` | `MustToYAML(any)string`
|
||
* **YAML 解码 (原地)**: `UnmarshalYAML(data, any) error`
|
||
* **YAML 构建 (泛型)**: `FromYAML[T](data) (T, error)` | `MustFromYAML[T](data) T`
|
||
|
||
4. **泛型工具（Type Helpers）**
|
||
* `If[T any](bool, T, T) T` —— 三元逻辑
|
||
* `In[T comparable]([]T, T) bool` —— 包含判断
|
||
* `Ptr[T any](T) *T` —— 取指针
|
||
* `ArrayToBoolMap[T comparable]([]T) map[T]bool` —— 快速索引化
|
||
|
||
5. **辅助工具（Utilities）**
|
||
* **切分**: `Split(s, sep) []string` | `SplitArgs(s) []string`
|
||
* **拼接**: `UniqueAppend([]string, ...any) []string` | `JoinArgs([]string, sep) string`
|
||
* **其他**: `RealValue(reflect.Value) reflect.Value` | `GetLowerName(string) string` | `GetUpperName(string) string` | `FixUpperCase([]byte, []string)`
|
||
|
||
## 🧪 验证状态
|
||
测试全部通过，性能达标。详见：[TEST.md](./TEST.md)
|