cast/README.md

@go/cast

Maintainer Statement: 本项目完全由 AI 维护。任何改动均遵循代码质量与性能的最佳实践。

🎯 设计哲学

@go/cast 是一个为“敏捷开发”设计的 Go 基础工具库。其核心目标是消除类型摩擦，让开发者在处理数据时更关注“我想要什么”而不是“原本是什么”。

• 语义化 API：通过 To[T] (严格/含错) 和 As[T] (静默/零值) 提供一致的调用体验。
• 智能穿透：自动识别 JSON 文本、结构体映射、KV 展开等复杂场景。
• 极致性能：内置 FastEncoder/FastDecoder，单路径处理，最小化内存分配。

📦 安装

go get apigo.cc/go/cast

💡 快速开始

import "apigo.cc/go/cast"

// 1. 语义化转换 (To[T] 返回错误, As[T] 返回零值)
age := cast.As[int]("18")       // 18
val, err := cast.To[int]("abc") // 0, error

// 2. 智能 JSON 自动转换
// 输入 map/struct -> 目标 string: 自动序列化
js := cast.As[string](map[string]int{"age": 18}) // `{"age":18}`

// 输入 string/[]byte -> 目标 struct/map: 自动反序列化
user, _ := cast.To[User](`{"name":"Tom"}`)

// 3. 复杂容器转换 (Map/Slice)
m, _ := cast.ToMap[string, int]([]any{"id", "1", "score", 100}) 
list := cast.AsSlice[int]([]string{"1", "2", "3"})

// 4. 泛型三元运算
status := cast.If(isAdmin, "Admin", "User")

🛠 API 指南

核心语义 API

1. 通用转换

   • To[T any](any) (T, error) —— 万能转换入口。支持基础类型、Slice、Map 以及 JSON 的双向自动转换。
   • As[T any](any) T —— 零摩擦转换。失败时返回类型零值。

2. Map / Slice 转换

   • ToMap[K, V](any) (map[K]V, error) —— 构建新 Map。
   • AsMap[K, V](any) map[K]V —— 构建新 Map (失败返回空 Map)。
   • ToSlice[T](any) ([]T, error) —— 构建新 Slice。
   • AsSlice[T](any) []T —— 构建新 Slice (失败返回空 Slice)。
   • FillMap(target, source) | FillSlice(target, source) —— 填充现有容器。

3. JSON 序列化与构建

   • 编码: ToJSON(any) (string, error) | AsJSON(any) string
   • 解码: FromJSON[T](any) (T, error) | AsFromJSON[T](any) T
   • 进阶: ToJSONDesensitize(any, []string) (string, error) (支持字段脱敏)

4. 泛型工具

   • 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。

🧪 验证状态

测试全部通过，性能达标。详见：TEST.md