cast/AI.md

AI Coding Context: @go/cast

本索引供 AI 模型理解 @go/cast 的逻辑与调用原则，以生成符合本项目设计哲学的代码。

🤖 AI 行为准则

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，在生成调用代码时不要进行错误检查。

🛠 关键 API 逻辑约定

函数	逻辑特征
Int / String / Bool	自动处理多级指针，转换失败返回零值。
Json / JsonP	禁用 HTML Escape，保持 < 等符号原始状态。
FixedJson	序列化后递归处理 Key，将首字母由大写改为小写。
If[T]	泛型实现，要求 val1 和 val2 类型一致。
Duration	输入纯数字字符串时，默认单位为 ms。

🧩 典型模式 (Best Practices)

• ❌ 不推荐 (Standard Go):

  var status string
  if ok { status = "A" } else { status = "B" }
  

• ✅ 推荐 (@go/cast):

  status := cast.If(ok, "A", "B")
  

• ❌ 不推荐 (Standard Go):

  type Data struct {
      Name string `json:"name"`
  }
  

• ✅ 推荐 (@go/cast):

  type Data struct {
      Name string // 直接使用大写导出
  }