cast/README.md

@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 匹配及批量转义优化。

📦 安装

go get apigo.cc/go/cast

💡 快速开始

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
   • RealValue(reflect.Value) reflect.Value —— 递归获取指针或接口下的真实值。
   • 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 —— 去重追加。
   • GetLowerName(string) string | GetUpperName(string) string —— 首字母大小写转换工具。
   • FixUpperCase([]byte, []string) —— 针对 JSON Key 的特殊大小写修复工具。

8. 时区支持

   • DefaultTimeZone —— 全局默认时区上下文。
   • SetDefaultTimeZone(*time.Location) —— 修改全局默认时区（影响所有 Convert 与 ToTime 操作）。
   • DefaultTimeZone.Now() —— 获取时区上下文下的当前时间。
   • NewTimeZone(*time.Location) —— 创建一个时区上下文，支持 Parse、Format、Add、Now 等操作。

🧪 验证状态

测试全部通过，性能达标。

详见：TEST.md