From eedce7abcb93a6afa9acca81357a99207d223f58 Mon Sep 17 00:00:00 2001 From: Star Date: Wed, 22 Apr 2026 11:08:39 +0800 Subject: [PATCH] =?UTF-8?q?docs(AI):=20=E4=BC=98=E5=8C=96=20API=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=B8=8E=20AI=20=E5=8D=8F=E4=BD=9C=E8=A7=84?= =?UTF-8?q?=E8=8C=83=20(=E4=BD=9C=E8=80=85:=20AI)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AI.md | 22 +++++++++--------- README.md | 67 +++++++++++++++++++++++++++++++++---------------------- 2 files changed, 51 insertions(+), 38 deletions(-) diff --git a/AI.md b/AI.md index 362d927..97610af 100644 --- a/AI.md +++ b/AI.md @@ -1,25 +1,25 @@ # AI Coding Context: @go/cast -本索引供 AI 模型理解 `@go/cast` 的内部逻辑与调用原则，以生成符合本项目设计哲学的代码。 +本索引供 AI 模型理解 `@go/cast` 的逻辑与调用原则，以生成符合本项目设计哲学的代码。 ## 🤖 AI 行为准则 -1. **优先使用 cast 进行转换**：在处理类型不确定的 `interface{}` 或从配置/接口读取数据时，优先使用 `cast.Int()`, `cast.String()` 等，避免手动进行类型断言。 -2. **禁止在 Struct 中冗余添加 JSON Tag**：除非有特殊的字段重命名需求，否则在编写符合本项目风格的 Struct 时，不应添加 `json:"..."`。告知用户使用 `cast.FixedJson()` 来自动实现首字母小写。 +1. **优先使用 cast 进行转换**：在处理类型不确定的数据时，优先使用 `cast.Int()`, `cast.String()` 等，避免手动类型断言。 +2. **禁止在 Struct 中冗余添加 JSON Tag**：除非有特殊重命名需求，否则默认使用大写导出，告知用户使用 `cast.FixedJson()` 来自动实现小写 Key 序列化。 3. **使用 If 替代简单 if-else 赋值**：在需要进行条件赋值时，优先使用泛型函数 `cast.If(cond, val1, val2)`。 -4. **无错误处理倾向**：理解 `cast` 的函数几乎不返回 `error`，在生成调用代码时，不要去检查转换错误。 +4. **无错误处理倾向**：理解 `cast` 函数不返回 `error`，在生成调用代码时不要进行错误检查。 ## 🛠 关键 API 逻辑约定 | 函数 | 逻辑特征 | | :--- | :--- | -| `Int / String / Bool` | 自动处理多级指针 (`FixPtr`)，转换失败返回 0/空值，从不报错。 | -| `Json / JsonP` | 强制禁用 HTML Escape。输出内容保持原始符号 (`<`, `>`, `&`)。 | -| `FixedJson` | 执行 `Json` 序列化后，递归处理字节流，将所有非排除列表内的 Key 首字母由大写改为小写。 | -| `If[T]` | 泛型实现，要求 `val1` 和 `val2` 类型严格一致，返回类型与输入一致。 | -| `Duration` | 扩展了 Go 标准库。如果输入纯数字字符串，默认单位为 `ms`。 | +| `Int / String / Bool` | 自动处理多级指针，转换失败返回零值。 | +| `Json / JsonP` | 禁用 HTML Escape，保持 `<` 等符号原始状态。 | +| `FixedJson` | 序列化后递归处理 Key，将首字母由大写改为小写。 | +| `If[T]` | 泛型实现，要求 `val1` 和 `val2` 类型一致。 | +| `Duration` | 输入纯数字字符串时，默认单位为 `ms`。 | -## 🧩 典型模式 (Anti-Patterns vs Best Practices) +## 🧩 典型模式 (Best Practices) * **❌ 不推荐 (Standard Go)**: ```go @@ -40,6 +40,6 @@ * **✅ 推荐 (@go/cast)**: ```go type Data struct { - Name string // 直接使用大写导出，序列化用 FixedJson + Name string // 直接使用大写导出 } ``` diff --git a/README.md b/README.md index 24ae283..80111a5 100644 --- a/README.md +++ b/README.md @@ -4,22 +4,45 @@ ## 🎯 设计哲学 -* **弱化类型摩擦**：在业务逻辑中，我们不应该被 `if err != nil` 的类型转换填满。`cast` 倾向于返回“合理的默认值”而不是错误，让你专注于核心业务流。 -* **补足语言短板**：Go 缺失了像三元运算符 (`a ? b : c`) 这样简洁的语法。`cast` 通过泛型工具类（`If`, `Switch`, `In`）将其补回。 -* **去标签化 (No JSON Tags)**：我们不希望在每一个 Struct 字段后都手动写上 `` `json:"name"` ``。`cast` 的序列化工具能自动处理 Go 的大写导出规则，将其转换为更符合接口惯例的小写 Key。 -* **数据直觉**：序列化应该保持数据的本色。我们默认禁用了 HTML 转义，确保像 `` 这样的符号在传输中不会被强制转义为 `\u003c`。 +* **弱化类型摩擦**：`cast` 倾向于返回“合理的默认值”而不是错误，让你专注于核心业务流。 +* **补足语言短板**：通过泛型工具类补齐了 Go 缺失的三元运算符。 +* **去标签化 (No JSON Tags)**：支持自动处理大写导出规则，无需在每个结构体字段后手动添加 JSON tag。 +* **数据直觉**：默认禁用 HTML 转义，保持序列化内容的原始色泽。 -## 🚀 核心特性 +## 🛠 API Reference -* **强制转换**：`Int()`, `String()`, `Bool()`, `Float()` 等函数支持多种原始类型及其指针的平滑转换。 -* **泛型工具**： - * `If(cond, a, b)`：类型安全的三元运算符替代品。 - * `In(slice, target)`：一行代码判断包含关系。 - * `Switch(index, ...args)`：基于索引的快速分支选择。 -* **现代化 JSON**： - * `Json()` / `JsonP()`：默认不转义 HTML 字符。 - * `FixedJson()`：自动将 Struct 字段首字母改为小写，无需维护 JSON Tag。 -* **指针辅助**：`StringPtr()`, `IntPtr()` 等函数简化了字面量赋值给指针字段的痛苦。 +### 基础转换函数 +所有转换函数均会自动处理多级指针，并在转换失败时返回零值。 + +- `func Int(v any) int` +- `func Int64(v any) int64` +- `func Uint(v any) uint` +- `func Uint64(v any) uint64` +- `func Float(v any) float32` +- `func Float64(v any) float64` +- `func String(v any) string` +- `func Bool(v any) bool` +- `func Duration(v string) time.Duration` (支持 100ms 这种 DSL 格式) + +### 泛型工具 + +- `func If[T any](cond bool, a, b T) T`：泛型三元运算符。 +- `func Switch[T any](i uint, args ...T) T`：基于索引的选择。 +- `func In[T comparable](arr []T, val T) bool`：判断切片是否包含某值。 + +### 现代化 JSON & YAML + +- `func Json(v any) string`：高性能序列化，不转义 HTML 字符。 +- `func JsonP(v any) string`：带缩进的格式化输出。 +- `func FixedJson(v any) string`：自动将 Struct 字段首字母转为小写。 +- `func UnJson(str string, v any) any`：反序列化。 +- `func Yaml(v any) string` +- `func UnYaml(str string, v any) any` + +### 指针辅助 +- `func StringPtr(v string) *string` +- `func IntPtr(v int) *int` +- `func BoolPtr(v bool) *bool` ## 📦 安装 @@ -32,19 +55,9 @@ go get apigo.cc/go/cast ```go import "apigo.cc/go/cast" -// 1. 像 JS 一样转换 +// 像 JS 一样转换 age := cast.Int("18") // 18 -name := cast.String(123) // "123" -// 2. 泛型三元运算 -status := cast.If(isAdmin, "Admin", "User") // 类型自动推导 - -// 3. 自动首字母小写的 JSON (无需 Tag) -type User struct { Name string } -u := User{Name: "Tom"} -js := cast.FixedJson(u) // {"name":"Tom"} - -// 4. 特殊字符不转义 -content := map[string]string{"link": ""} -fmt.Println(cast.Json(content)) // {"link":""} 而不是 \u003c +// 泛型三元运算 +status := cast.If(isAdmin, "Admin", "User") ```