refactor: consolidate As/Must APIs with Quiet and Must helpers (v1.2.0)

CHANGELOG.md

@@ -3,17 +3,11 @@
 ## [v1.2.0] - 2026-05-04
 ### Added
 - **语义化 API**: 引入 `To[T]` (严格/含错) 和 `As[T]` (静默/零值) 泛型接口，作为全能类型转换入口。
+- **摩擦消除工具**: 新增 `Quiet[T]` 和 `Must[T]` 通用辅助函数，用于包装 error-returning 函数。
 - **智能穿透**: `To[T]` 支持 JSON 自动双向转换（Input string/[]byte <-> Target struct/map/slice）。
-- **容器 API 统一**: 
-    - `ToMap` / `AsMap` (替代 `MakeMap`)
-    - `ToSlice` / `AsSlice` (替代 `MakeSlice`)
-    - `AsJSON` / `AsJSONBytes` (替代 `MustToJSON`)
-    - `AsFromJSON` (替代 `MustFromJSON`)
 ### Removed
-- **YAML 支持**: 移除 `gopkg.in/yaml.v3` 依赖及所有 YAML 相关 API，专注 JSON 以保持核心极致精简。
+- **YAML 支持**: 移除 `gopkg.in/yaml.v3` 依赖及所有 YAML 相关 API。
-### Deprecated
+- **API 整合**: 移除专门的 `AsXxx` 和 `MustXxx` 系列函数（如 `AsMap`, `AsJSON`, `MustToJSON` 等），推荐使用 `As[T]` 或 `Quiet/Must` 包装。
-- **MustXxx 系列**: 建议迁移至语义更明确的 `AsXxx`。
-- **MakeXxx 系列**: 建议迁移至 `AsMap` / `AsSlice`。
 
 ## [v1.1.2] - 2026-05-04
 ### Added

README.md

@@ -7,7 +7,7 @@
 
 `@go/cast` 是一个为“敏捷开发”设计的 Go 基础工具库。其核心目标是**消除类型摩擦**，让开发者在处理数据时更关注“我想要什么”而不是“原本是什么”。
 
-*   **语义化 API**：通过 `To[T]` (严格/含错) 和 `As[T]` (静默/零值) 提供一致的调用体验。
+*   **语义化 API**：通过 `To[T]` (严格/含错) 配合 `Quiet` (静默) 或 `Must` (断言) 提供一致的调用体验。
 *   **智能穿透**：自动识别 JSON 文本、结构体映射、KV 展开等复杂场景。
 *   **极致性能**：内置 FastEncoder/FastDecoder，单路径处理，最小化内存分配。
 
@@ -22,23 +22,26 @@ go get apigo.cc/go/cast
 ```go
 import "apigo.cc/go/cast"
 
-// 1. 语义化转换 (To[T] 返回错误, As[T] 返回零值)
+// 1. 语义化转换 (To[T] 返回错误)
-age := cast.As[int]("18")       // 18
+val, err := cast.To[int]("123") // 123, nil
-val, err := cast.To[int]("abc") // 0, error
 
-// 2. 智能 JSON 自动转换
+// 2. 摩擦消除工具 (Quiet 返回零值, Must 失败 Panic)
+age := cast.Quiet(cast.To[int]("abc")) // 0
+uid := cast.Must(cast.To[int]("100"))  // 100
+
+// 3. 快捷方式 (cast.As[T] 等价于 cast.Quiet(cast.To[T]))
+name := cast.As[string](123) // "123"
+
+// 4. 智能 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)
+// 5. 复杂容器转换 (Map/Slice)
 m, _ := cast.ToMap[string, int]([]any{"id", "1", "score", 100}) 
-list := cast.AsSlice[int]([]string{"1", "2", "3"})
+list := cast.As[[]int]([]string{"1", "2", "3"})
-
-// 4. 泛型三元运算
-status := cast.If(isAdmin, "Admin", "User")
 ```
 
 ## 🛠 API 指南
@@ -47,21 +50,23 @@ status := cast.If(isAdmin, "Admin", "User")
 
 1.  **通用转换**
     * `To[T any](any) (T, error)` —— 万能转换入口。支持基础类型、Slice、Map 以及 JSON 的双向自动转换。
-    * `As[T any](any) T` —— 零摩擦转换。失败时返回类型零值。
+    * `As[T any](any) T` —— 零摩擦转换快捷方式。失败时返回类型零值。
 
-2.  **Map / Slice 转换**
+2.  **错误处理工具**
+    * `Quiet[T any](T, error) T` —— 忽略错误，返回转换后的值（若有错则返回零值）。
+    * `Must[T any](T, error) T` —— 严谨模式。若有错误则直接 Panic，常用于全局初始化。
+
+3.  **容器转换**
     * `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 序列化与构建**
+4.  **JSON 序列化与构建**
-    * **编码**: `ToJSON(any) (string, error)` | `AsJSON(any) string`
+    * **编码**: `ToJSON(any) (string, error)` | `ToJSONBytes(any) ([]byte, error)`
-    * **解码**: `FromJSON[T](any) (T, error)` | `AsFromJSON[T](any) T`
+    * **解码**: `UnmarshalJSON(data, target) error` | `FromJSON[T](any) (T, error)`
     * **进阶**: `ToJSONDesensitize(any, []string) (string, error)` (支持字段脱敏)
 
-4.  **泛型工具**
+5.  **泛型工具**
     * `If[T any](bool, T, T) T` —— 三元逻辑。
     * `In[T comparable]([]T, T) bool` —— 包含判断。
     * `Ptr[T any](T) *T` —— 快速取指针。

bench_test.go

@@ -71,7 +71,7 @@ func BenchmarkJSON(b *testing.B) {
 	}
 	u := User{ID: 1, Name: "Benchmark User"}
 	for i := 0; i < b.N; i++ {
-		_ = cast.MustToJSON(u)
+		_ = cast.As[string](u)
 	}
 }
 
@@ -147,7 +147,7 @@ func BenchmarkToJSON_SimpleStruct(b *testing.B) {
 	b.ResetTimer()
 	for i := 0; i < b.N; i++ {
 		// 这里包含了你特有的 makeJSONType 清洗逻辑和 FixUpperCase 逻辑
-		_ = cast.MustToJSON(u)
+		_ = cast.As[string](u)
 	}
 }
 
@@ -160,6 +160,6 @@ func BenchmarkToJSON_DirtyMap(b *testing.B) {
 	}
 	b.ResetTimer()
 	for i := 0; i < b.N; i++ {
-		_ = cast.MustToJSON(val)
+		_ = cast.As[string](val)
 	}
 }

cast.go

@@ -25,6 +25,23 @@ func In[T comparable](arr []T, val T) bool {
 	return slices.Contains(arr, val)
 }
 
+// Quiet 忽略错误，返回零值
+func Quiet[T any](v T, err error) T {
+	if err != nil {
+		var zero T
+		return zero
+	}
+	return v
+}
+
+// Must 严谨模式，报错即刻崩溃
+func Must[T any](v T, err error) T {
+	if err != nil {
+		panic(err)
+	}
+	return v
+}
+
 func RealValue(v reflect.Value) reflect.Value {
 	for v.Kind() == reflect.Pointer || v.Kind() == reflect.Interface {
 		if v.IsNil() {
@@ -70,17 +87,112 @@ func To[T any](v any) (T, error) {
 	}
 
 	// 4. 处理基础类型
-	res := reflectCast(v, targetType)
+	res, err := reflectCastE(v, targetType)
-	if !res.IsValid() {
+	if err != nil {
-		return zero, fmt.Errorf("cast to %v failed", targetType)
+		return zero, err
 	}
 	return res.Interface().(T), nil
 }
 
+func reflectCastE(value any, t reflect.Type) (reflect.Value, error) {
+	switch t.Kind() {
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		i, err := ToInt64E(value)
+		if err != nil {
+			return reflect.Value{}, err
+		}
+		return reflect.ValueOf(i).Convert(t), nil
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		i, err := ToUint64E(value)
+		if err != nil {
+			return reflect.Value{}, err
+		}
+		return reflect.ValueOf(i).Convert(t), nil
+	case reflect.Float32, reflect.Float64:
+		f, err := ToFloat64E(value)
+		if err != nil {
+			return reflect.Value{}, err
+		}
+		return reflect.ValueOf(f).Convert(t), nil
+	case reflect.String:
+		return reflect.ValueOf(String(value)).Convert(t), nil
+	case reflect.Bool:
+		return reflect.ValueOf(Bool(value)).Convert(t), nil
+	case reflect.Interface:
+		if value == nil {
+			return reflect.Zero(t), nil
+		}
+		return reflect.ValueOf(value), nil
+	}
+
+	if t == reflect.TypeOf(time.Duration(0)) {
+		return reflect.ValueOf(Duration(value)), nil
+	}
+
+	return reflect.Zero(t), fmt.Errorf("unsupported target type: %v", t)
+}
+
+func ToInt64E(v any) (int64, error) {
+	if i, ok := toInt64(v); ok {
+		return i, nil
+	}
+	s := String(v)
+	i, err := strconv.ParseInt(s, 10, 64)
+	if err == nil {
+		return i, nil
+	}
+	if f, err := strconv.ParseFloat(s, 64); err == nil {
+		return int64(f), nil
+	}
+	return 0, fmt.Errorf("cannot cast %v to int64", v)
+}
+
+func ToUint64E(v any) (uint64, error) {
+	switch realValue := v.(type) {
+	case int, int8, int16, int32, int64:
+		return uint64(Int64(realValue)), nil
+	case uint, uint8, uint16, uint32, uint64:
+		return Uint64(realValue), nil
+	case float32, float64:
+		return uint64(Float64(realValue)), nil
+	case bool:
+		return If(realValue, uint64(1), uint64(0)), nil
+	}
+	s := String(v)
+	i, err := strconv.ParseUint(s, 10, 64)
+	if err == nil {
+		return i, nil
+	}
+	if f, err := strconv.ParseFloat(s, 64); err == nil {
+		return uint64(f), nil
+	}
+	return 0, fmt.Errorf("cannot cast %v to uint64", v)
+}
+
+func ToFloat64E(v any) (float64, error) {
+	switch realValue := v.(type) {
+	case int, int8, int16, int32, int64:
+		return float64(Int64(realValue)), nil
+	case uint, uint8, uint16, uint32, uint64:
+		return float64(Uint64(realValue)), nil
+	case float32:
+		return float64(realValue), nil
+	case float64:
+		return realValue, nil
+	case bool:
+		return If(realValue, 1.0, 0.0), nil
+	}
+	s := String(v)
+	f, err := strconv.ParseFloat(s, 64)
+	if err != nil {
+		return 0, fmt.Errorf("cannot cast %v to float64", v)
+	}
+	return f, nil
+}
+
 // As 泛型转换 (失败返回零值)
 func As[T any](v any) T {
-	res, _ := To[T](v)
+	return Quiet(To[T](v))
-	return res
 }
 
 func isJSONText(v any) bool {
@@ -106,11 +218,11 @@ func isComplexType(t reflect.Type) bool {
 
 func isComplexValue(v any) bool {
 	if v == nil {
-		return false
+		return true
 	}
 	rv := RealValue(reflect.ValueOf(v))
-	if !rv.IsValid() {
+	if !rv.IsValid() || rv.Kind() == reflect.Pointer || rv.Kind() == reflect.Interface {
-		return false
+		return true
 	}
 	kind := rv.Kind()
 	return kind == reflect.Struct || kind == reflect.Map || (kind == reflect.Slice && rv.Type().Elem().Kind() != reflect.Uint8)
@@ -336,21 +448,6 @@ func Duration(value any) time.Duration {
 	return 0
 }
 
-func AsJSONBytes(value any) []byte {
-	j, _ := ToJSONBytes(value)
-	return j
-}
-
-func AsJSON(value any) string {
-	s, _ := ToJSON(value)
-	return s
-}
-
-func AsFromJSON[T any](data any) T {
-	v, _ := FromJSON[T](data)
-	return v
-}
-
 func ToJSONBytes(value any) ([]byte, error) {
 	return fastToJSONBytes(value)
 }
@@ -367,8 +464,6 @@ func ToJSONDesensitizeBytes(value any, keys []string) ([]byte, error) {
 	return fastToJSONBytes(value, keys...)
 }
 
-func MustToJSONBytes(value any) []byte { return AsJSONBytes(value) }
-
 func ToJSON(value any) (string, error) {
 	j, err := ToJSONBytes(value)
 	if err != nil {
@@ -377,10 +472,8 @@ func ToJSON(value any) (string, error) {
 	return string(j), nil
 }
 
-func MustToJSON(value any) string { return AsJSON(value) }
-
 func PrettyToJSONBytes(value any) []byte {
-	j := AsJSONBytes(value)
+	j := Quiet(ToJSONBytes(value))
 	r := &bytes.Buffer{}
 	if err := json.Indent(r, j, "", "  "); err == nil {
 		return r.Bytes()
@@ -417,8 +510,6 @@ func FromJSON[T any](data any) (T, error) {
 	return v, err
 }
 
-func MustFromJSON[T any](data any) T { return AsFromJSON[T](data) }
-
 // --- Others (Keep logic but clean style) ---
 
 func Split(s, sep string) []string {
@@ -523,12 +614,6 @@ func ToMap[K comparable, V any](source any) (map[K]V, error) {
 	return m, nil
 }
 
-// AsMap 泛型构建新 Map (失败返回空 Map)
-func AsMap[K comparable, V any](source any) map[K]V {
-	m, _ := ToMap[K, V](source)
-	return m
-}
-
 // ToSlice 泛型构建新 Slice
 func ToSlice[T any](source any) ([]T, error) {
 	var s []T
@@ -536,12 +621,6 @@ func ToSlice[T any](source any) ([]T, error) {
 	return s, nil
 }
 
-// AsSlice 泛型构建新 Slice (失败返回空 Slice)
-func AsSlice[T any](source any) []T {
-	s, _ := ToSlice[T](source)
-	return s
-}
-
 // FillMap 将 source 填充到目标 map 中 (兼容旧 API 逻辑)
 func FillMap(target any, source any) {
 	rv := reflect.ValueOf(target)
@@ -647,40 +726,8 @@ func fillToSlice(sliceRv reflect.Value, source any) {
 	}
 }
 
-// MakeMap 泛型构建新 Map (DEPRECATED: Use AsMap)
-func MakeMap[K comparable, V any](source any) map[K]V {
-	return AsMap[K, V](source)
-}
-
-// MakeSlice 泛型构建新 Slice (DEPRECATED: Use AsSlice)
-func MakeSlice[T any](source any) []T {
-	return AsSlice[T](source)
-}
-
 func reflectCast(value any, t reflect.Type) reflect.Value {
-	switch t.Kind() {
+	return Quiet(reflectCastE(value, t))
-	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
-		return reflect.ValueOf(Int64(value)).Convert(t)
-	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
-		return reflect.ValueOf(Uint64(value)).Convert(t)
-	case reflect.Float32, reflect.Float64:
-		return reflect.ValueOf(Float64(value)).Convert(t)
-	case reflect.String:
-		return reflect.ValueOf(String(value)).Convert(t)
-	case reflect.Bool:
-		return reflect.ValueOf(Bool(value)).Convert(t)
-	case reflect.Interface:
-		if value == nil {
-			return reflect.Zero(t)
-		}
-		return reflect.ValueOf(value)
-	}
-
-	if t == reflect.TypeOf(time.Duration(0)) {
-		return reflect.ValueOf(Duration(value))
-	}
-
-	return reflect.Zero(t)
 }
 
 // 补充缺失的 Key 转换工具

cast_test.go

@@ -32,7 +32,7 @@ func TestStructToJSON(t *testing.T) {
 		Age  int
 	}
 	u := User{Name: "Tom", Age: 18}
-	js := cast.MustToJSON(u)
+	js := cast.As[string](u)
 	// 验证首字母小写逻辑
 	if !strings.Contains(js, `"name":"Tom"`) || !strings.Contains(js, `"age":18`) {
 		t.Errorf("Struct to JSON auto-lowercase failed: %s", js)
@@ -61,7 +61,7 @@ func TestSpecialJSON(t *testing.T) {
 
 	// 标准 json.Marshal 会变成 "<a> \u0026 <b>"
 	// 我们期望输出原始字符 "<a> & <b>"
-	js := cast.MustToJSON(c)
+	js := cast.As[string](c)
 	expected := `{"text":"<a> & <b>"}`
 	if js != expected {
 		t.Errorf("Special JSON failed.\nExpected: %s\nActual:   %s", expected, js)
@@ -84,7 +84,7 @@ func TestComplexJSONType(t *testing.T) {
 		},
 	}
 
-	js := cast.MustToJSON(data)
+	js := cast.As[string](data)
 	// 期望 123 被转为 "123" 且内容正确
 	if !strings.Contains(js, `"123":"numeric key"`) || !strings.Contains(js, `"ok":true`) {
 		t.Errorf("Complex JSON type failed: %s", js)
@@ -138,7 +138,7 @@ func TestGojaMapToArrayFallback(t *testing.T) {
 		"2":        "cherry", // 字符串形式的数字也应该被正确转换
 	}
 
-	js := cast.MustToJSON(mockGojaArray)
+	js := cast.As[string](mockGojaArray)
 
 	// 我们期望它被正确识别并转化为标准的 JSON 数组，且顺序不会乱
 	expected := `["apple","banana","cherry"]`
@@ -194,7 +194,7 @@ func TestUnaddressableStruct(t *testing.T) {
 		}
 	}()
 
-	res := cast.MustToJSON(d)
+	res := cast.As[string](d)
 	if !strings.Contains(res, "\"name\"") {
 		t.Errorf("Value struct ToJSON failed to lowercase key: %s", res)
 	}
@@ -203,19 +203,19 @@ func TestUnaddressableStruct(t *testing.T) {
 func TestToJSON_Nil(t *testing.T) {
 	// Nil slice should be []
 	var s []int
-	if js := cast.MustToJSON(s); js != "[]" {
+	if js := cast.As[string](s); js != "[]" {
 		t.Errorf("Nil slice expected [], got %s", js)
 	}
 
 	// Nil map should be {}
 	var m map[string]int
-	if js := cast.MustToJSON(m); js != "{}" {
+	if js := cast.As[string](m); js != "{}" {
 		t.Errorf("Nil map expected {}, got %s", js)
 	}
 
 	// Nil pointer should be null
 	var p *int
-	if js := cast.MustToJSON(p); js != "null" {
+	if js := cast.As[string](p); js != "null" {
 		t.Errorf("Nil pointer expected null, got %s", js)
 	}
 }
@@ -247,7 +247,7 @@ func TestFastEncoder_MapAny(t *testing.T) {
 		"userName": "admin",
 		123:        "val",
 	}
-	js := cast.MustToJSON(data)
+	js := cast.As[string](data)
 	if !strings.Contains(js, `"123":"val"`) || !strings.Contains(js, `"userName":"admin"`) {
 		t.Errorf("MapAny encoding failed: %s", js)
 	}
@@ -258,7 +258,7 @@ func TestFastEncoder_GojaArray(t *testing.T) {
 		0: "a",
 		1: "b",
 	}
-	js := cast.MustToJSON(data)
+	js := cast.As[string](data)
 	if js != `["a","b"]` {
 		t.Errorf("Goja array fallback failed: %s", js)
 	}

conversion_test.go

@@ -23,7 +23,7 @@ func TestToMap(t *testing.T) {
 	}
 
 	// Test slice-to-map (KV)
-	m2 := cast.AsMap[int, string]([]any{"1", "a", 2, 200})
+	m2 := cast.As[map[int]string]([]any{"1", "a", 2, 200})
 	if m2[1] != "a" || m2[2] != "200" {
 		t.Errorf("Slice-to-map failed: %v", m2)
 	}
@@ -63,22 +63,22 @@ func TestJSON(t *testing.T) {
 		t.Errorf("FromJSON failed: %v, %v", err, c2)
 	}
 
-	// Test AsFromJSON
+	// Test As[T] from JSON
-	c3 := cast.AsFromJSON[Config](data)
+	c3 := cast.As[Config](data)
 	if c3.Port != 8080 {
-		t.Errorf("AsFromJSON failed: %v", c3)
+		t.Errorf("As[Config] failed: %v", c3)
 	}
 }
 
-func TestMakeSlice(t *testing.T) {
+func TestGenericAsSlice(t *testing.T) {
-	// Test MakeSlice with various inputs
+	// Test As with various inputs
-	s1 := cast.AsSlice[int]("123")
+	s1 := cast.As[[]int]("123")
 	if len(s1) != 1 || s1[0] != 123 {
-		t.Errorf("AsSlice primitive failed: %v", s1)
+		t.Errorf("As[[]int] primitive failed: %v", s1)
 	}
 
-	s2 := cast.AsSlice[string]([]int{1, 2})
+	s2 := cast.As[[]string]([]int{1, 2})
 	if len(s2) != 2 || s2[0] != "1" || s2[1] != "2" {
-		t.Errorf("AsSlice slice failed: %v", s2)
+		t.Errorf("As[[]string] slice failed: %v", s2)
 	}
 }

semantic_test.go

@@ -46,6 +46,24 @@ func TestToAs(t *testing.T) {
 	}
 }
 
+func TestQuietMust(t *testing.T) {
+	// Quiet
+	if v := cast.Quiet(cast.To[int]("abc")); v != 0 {
+		t.Errorf("Quiet failed: %v", v)
+	}
+	if v := cast.Quiet(cast.To[int]("123")); v != 123 {
+		t.Errorf("Quiet failed: %v", v)
+	}
+
+	// Must
+	defer func() {
+		if r := recover(); r == nil {
+			t.Errorf("Must should panic on error")
+		}
+	}()
+	cast.Must(cast.To[int]("abc"))
+}
+
 func TestMapSliceAPIs(t *testing.T) {
 	// ToMap
 	m, err := cast.ToMap[string, int]([]any{"a", "1", "b", 2})
@@ -53,10 +71,10 @@ func TestMapSliceAPIs(t *testing.T) {
 		t.Errorf("ToMap failed: %v, %v", m, err)
 	}
 
-	// AsMap
+	// As[map...]
-	m2 := cast.AsMap[string, int]([]any{"c", "3"})
+	m2 := cast.As[map[string]int]([]any{"c", "3"})
 	if m2["c"] != 3 {
-		t.Errorf("AsMap failed: %v", m2)
+		t.Errorf("As[map] failed: %v", m2)
 	}
 
 	// ToSlice
@@ -65,9 +83,9 @@ func TestMapSliceAPIs(t *testing.T) {
 		t.Errorf("ToSlice failed: %v, %v", s, err)
 	}
 
-	// AsSlice
+	// As[[]...]
-	s2 := cast.AsSlice[string]([]int{1, 2})
+	s2 := cast.As[[]string]([]int{1, 2})
 	if len(s2) != 2 || s2[0] != "1" || s2[1] != "2" {
-		t.Errorf("AsSlice failed: %v", s2)
+		t.Errorf("As[[]string] failed: %v", s2)
 	}
 }