103 lines
4.9 KiB
Markdown
103 lines
4.9 KiB
Markdown
# @go/cast
|
||
|
||
> **Maintainer Statement:** 本项目完全由 AI 维护。任何改动均遵循代码质量与性能的最佳实践。
|
||
|
||
|
||
## 🎯 设计哲学
|
||
|
||
`@go/cast` 是一个为“极致敏捷”设计的 Go 基础工具库。其核心目标是**彻底消除摩擦**：
|
||
|
||
* **万能零摩擦入口**：`To[T]、Convert` 作为核心 API，永不返回 `error`。在失败或非法转换时静默返回类型零值。
|
||
* **语义化 As 包装**：提供 `As` 函数用于将传统“值+错误”双返回结果一键转化为单值，消除外部库带来的摩擦。
|
||
* **智能自动穿透**：`To[T]、Convert` 自动识别 JSON 文本、复杂容器映射、指针穿透等场景。
|
||
* **极致性能 JSON**：内置高性能 `fastjson` 引擎，支持 Struct 元数据缓存、`time.Time` 原生处理、零分配 Key 匹配及批量转义优化。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
go get apigo.cc/go/cast
|
||
```
|
||
|
||
## 💡 快速开始
|
||
|
||
```go
|
||
import "apigo.cc/go/cast"
|
||
|
||
// 1. 万能转换 (To[T] 永不报错，遇错返回零值)
|
||
age := cast.To[int]("18") // 18
|
||
uid := cast.To[int]("abc") // 0 (静默失败)
|
||
|
||
// 2. 传统函数消除摩擦 (As 将双返回包装为单值)
|
||
b := cast.As(json.Marshal(data)) // 返回 []byte，忽略 error
|
||
|
||
// 3. 智能 JSON 自动转换
|
||
// 输入 map/struct -> 目标 string: 自动序列化
|
||
js := cast.To[string](map[string]int{"age": 18}) // `{"age":18}`
|
||
|
||
// 输入 string/[]byte -> 目标 struct/map: 自动反序列化
|
||
user := cast.To[User](`{"name":"Tom"}`)
|
||
|
||
// 4. 复杂容器转换 (Map/Slice)
|
||
m, _ := cast.ToMap[string, int]([]any{"id", "1"})
|
||
list, _ := cast.ToSlice[int]([]string{"1", "2", "3"})
|
||
```
|
||
|
||
## 🛠 API 指南
|
||
|
||
### 核心 API
|
||
|
||
1. **通用转换 (Frictionless)**
|
||
* `To[T any](any) T` —— 万能转换入口。支持基础类型、Slice、Map 以及 JSON 的双向自动转换。失败时返回类型零值。
|
||
* `Convert(dst, src any)` —— 原地转换。第一个参数为目标对象指针，支持深度映射、自动包装/解包、ParseHook 等。
|
||
* 支持矩阵:
|
||
* `string/[]byte` <-> `struct/map/slice` (自动 JSON 编解码)
|
||
* `string (CSV)` -> `slice` (自动逗号分隔转换)
|
||
* `map` <-> `struct` (字段名智能模糊匹配)
|
||
* `[]any` <-> `map` (KV 序列展开/折叠)
|
||
* `func` <-> `func` (自动参数类型适配转换)
|
||
* 所有基础类型 (`int`, `string`, `bool`, `float`, `duration`, `time.Time`) 互相转换。
|
||
|
||
2. **错误处理工具**
|
||
* `As[T any](v T, err error) T` —— 错误消除工具。将传统的 `(value, error)` 返回值包装为单值。
|
||
|
||
3. **容器转换 (Strict)**
|
||
* `ToMap[K, V](any) (map[K]V, error)` —— 构建新 Map。
|
||
* `ToSlice[T](any) ([]T, error)` —— 构建新 Slice。
|
||
* `FillMap(target, source)` | `FillSlice(target, source)` —— 填充现有容器。
|
||
|
||
4. **JSON 序列化与构建 (Strict)**
|
||
* **编码**: `ToJSON(any) (string, error)` | `ToJSONBytes(any) ([]byte, error)`
|
||
* **解码**: `UnmarshalJSON(data, target) error` | `FromJSON[T](any) (T, error)`
|
||
* **时间支持**: 原生支持 `time.Time`。支持 Tag 格式定义：`json:"time_field,format=2006-01-02"`。
|
||
* **其他**: `ToJSONDesensitizeBytes(any, []string) ([]byte, error)` | `PrettyToJSON(any) string`
|
||
|
||
5. **泛型工具**
|
||
* `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` —— 快速构建索引 Map。
|
||
|
||
6. **基础转换与时间 (直接调用，极致性能)**
|
||
* `Int`, `Int64`, `Uint`, `Uint64`, `Float`, `Float64`, `String`, `Bool`, `Duration`
|
||
* `ParseTime(any) time.Time` —— 强大的时间解析，支持时间戳、RFC3339、JS 格式、紧凑格式及中文日期。
|
||
* `FormatTime(layout, any) string` —— 直观格式化（如 YYYY-MM-DD HH:mm:ss）。
|
||
* `AddTime(expr, any) time.Time` —— DSL 时间计算（如 +1Y-2M+3D）。
|
||
* `DescribeDuration(time.Duration) string` —— 将时长转化为自然语言描述（如 1h 5m）。
|
||
|
||
7. **字符串与参数处理**
|
||
* `Split(s, sep string) []string` —— 增强型分割，自动 Trim 并过滤空字符串。
|
||
* `SplitArgs(string) []string` —— 命令行参数分割，支持引号与转义。
|
||
* `JoinArgs([]string, sep string) string` —— 命令行参数合并，自动处理引号与转义。
|
||
* `UniqueAppend(to []string, from ...any) []string` —— 去重追加。
|
||
|
||
8. **时区支持**
|
||
* `DefaultTimeZone` —— 全局默认时区上下文。
|
||
* `SetDefaultTimeZone(*time.Location)` —— 修改全局默认时区（影响所有 Convert 与 ToTime 操作）。
|
||
* `DefaultTimeZone.Now()` —— 获取时区上下文下的当前时间。
|
||
* `NewTimeZone(*time.Location)` —— 创建一个时区上下文，支持 Parse、Format、Add、Now 等操作。
|
||
|
||
## 🧪 验证状态
|
||
测试全部通过，性能达标。
|
||
|
||
详见：[TEST.md](./TEST.md)
|