diff --git a/AI.md b/AI.md index 07c7141..987d9ad 100644 --- a/AI.md +++ b/AI.md @@ -1,6 +1,6 @@ # AI Coding Context: @go/convert -本索引供 AI 模型理解 `@go/convert` 的设计逻辑,以生成符合本项目“意图优先、零摩擦”哲学的代码。 +本索引供 AI 模型理解 `@go/convert` 的逻辑,以生成符合本项目“意图优先、零摩擦”哲学的代码。 ## 🤖 AI 行为准则 @@ -9,35 +9,25 @@ 3. **利用键名容忍度**:在处理不可控的外部数据时,无需担心键名格式(驼峰、蛇形等),`convert.To` 会自动匹配。 4. **无视指针层级**:在编写调用代码时,无需手动解引用或取地址以匹配类型,`convert` 内部会自动穿透处理。 -## 🛠 关键 API 逻辑约定 +## 🛠 API Reference -| 函数 | 逻辑特征 | -| :--- | :--- | -| `To(from, to)` | **主入口**。要求 `to` 必须为指针。核心逻辑是根据 `to` 的类型强力揉捏 `from`。 | -| `Convert(from, to)` | `To` 的别名。 | -| `FlatStruct(data)` | 获取结构体的扁平化元信息(导出字段/方法)。 | +### 核心转换函数 +- `func To(from, to any)`:支持任意可能的类型深度转换,`to` 必须为指针。 + +### 结构体分析 +- `func FlatStruct(data any) *StructInfo`:平展结构体(仅导出字段/方法)。 +- `func FlatStructWithUnexported(data any) *StructInfo`:平展结构体(包含未导出字段/方法)。 ## 🧩 典型模式 (Best Practices) -* **❌ 不推荐 (Standard Go)**: - ```go - // 手动映射字段,且对格式敏感 - u.UserID = m["user_id"].(int) - ``` * **✅ 推荐 (@go/convert)**: ```go // 自动匹配任何格式的键名 - convert.To(m, &u) + convert.To(from, &u) ``` -* **❌ 不推荐 (Standard Go)**: - ```go - // 手动处理单值转切片 - var dest []int - dest = append(dest, src) - ``` * **✅ 推荐 (@go/convert)**: ```go - // 自动包装 + // 自动包装单值至切片 convert.To(src, &dest) ``` diff --git a/go.mod b/go.mod index 75aa24c..7f31e88 100644 --- a/go.mod +++ b/go.mod @@ -3,6 +3,6 @@ module apigo.cc/go/convert go 1.25.0 require ( - apigo.cc/go/cast v1.0.2 + apigo.cc/go/cast v1.0.3 gopkg.in/yaml.v3 v3.0.1 )