Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
55e63b1261 | ||
| 8b641f1cff | |||
| eedce7abcb |
64
AI.md
64
AI.md
@ -1,45 +1,45 @@
|
||||
# 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 逻辑约定
|
||||
## 🛠 API Reference
|
||||
|
||||
| 函数 | 逻辑特征 |
|
||||
| :--- | :--- |
|
||||
| `Int / String / Bool` | 自动处理多级指针 (`FixPtr`)，转换失败返回 0/空值，从不报错。 |
|
||||
| `Json / JsonP` | 强制禁用 HTML Escape。输出内容保持原始符号 (`<`, `>`, `&`)。 |
|
||||
| `FixedJson` | 执行 `Json` 序列化后，递归处理字节流，将所有非排除列表内的 Key 首字母由大写改为小写。 |
|
||||
| `If[T]` | 泛型实现，要求 `val1` 和 `val2` 类型严格一致，返回类型与输入一致。 |
|
||||
| `Duration` | 扩展了 Go 标准库。如果输入纯数字字符串，默认单位为 `ms`。 |
|
||||
### 基础转换
|
||||
- `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 StringP(v any) string`
|
||||
- `func Bool(v any) bool`
|
||||
- `func Ints(v any) []int64` / `func Strings(v any) []string`
|
||||
- `func Duration(v string) time.Duration`
|
||||
|
||||
## 🧩 典型模式 (Anti-Patterns vs Best Practices)
|
||||
### 泛型工具
|
||||
- `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`：判断切片是否包含某值。
|
||||
|
||||
* **❌ 不推荐 (Standard Go)**:
|
||||
```go
|
||||
var status string
|
||||
if ok { status = "A" } else { status = "B" }
|
||||
```
|
||||
* **✅ 推荐 (@go/cast)**:
|
||||
### 序列化 (JSON/YAML)
|
||||
- `func Json(v any) string` / `func JsonP(v any) string` / `func JsonBytes(v any) []byte`
|
||||
- `func FixedJson(v any) string`：Struct 首字母转小写。
|
||||
- `func UnJson(str string, v any) any` / `func UnJsonBytes(data []byte, 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 Int64Ptr(v int64) *int64` / `func BoolPtr(v bool) *bool`
|
||||
- `func SplitTrim(s, sep string) []string` / `func SplitArgs(s string) []string`
|
||||
- `func GetLowerName(s string) string` / `func GetUpperName(s string) string`
|
||||
|
||||
## 🧩 典型模式 (Best Practices)
|
||||
|
||||
* **✅ 推荐**:
|
||||
```go
|
||||
status := cast.If(ok, "A", "B")
|
||||
```
|
||||
|
||||
* **❌ 不推荐 (Standard Go)**:
|
||||
```go
|
||||
type Data struct {
|
||||
Name string `json:"name"`
|
||||
}
|
||||
```
|
||||
* **✅ 推荐 (@go/cast)**:
|
||||
```go
|
||||
type Data struct {
|
||||
Name string // 直接使用大写导出，序列化用 FixedJson
|
||||
}
|
||||
age := cast.Int("18")
|
||||
jsonStr := cast.Json(myStruct)
|
||||
```
|
||||
|
||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 ssgo
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
71
README.md
71
README.md
@ -1,25 +1,52 @@
|
||||
# 关于本项目
|
||||
|
||||
本项目完全由 AI 维护。代码源自 github.com/ssgo/u 的重构。
|
||||
|
||||
# @go/cast
|
||||
|
||||
`@go/cast` 是一个为“敏捷开发”设计的 Go 基础工具库。它的设计初衷是打破 Go 语言严苛类型系统带来的繁琐摩擦，让开发者在处理数据转换时能够拥有类似 **JavaScript** 或 **PHP** 的丝滑体验。
|
||||
|
||||
## 🎯 设计哲学
|
||||
|
||||
* **弱化类型摩擦**：在业务逻辑中，我们不应该被 `if err != nil` 的类型转换填满。`cast` 倾向于返回“合理的默认值”而不是错误，让你专注于核心业务流。
|
||||
* **补足语言短板**：Go 缺失了像三元运算符 (`a ? b : c`) 这样简洁的语法。`cast` 通过泛型工具类（`If`, `Switch`, `In`）将其补回。
|
||||
* **去标签化 (No JSON Tags)**：我们不希望在每一个 Struct 字段后都手动写上 `` `json:"name"` ``。`cast` 的序列化工具能自动处理 Go 的大写导出规则，将其转换为更符合接口惯例的小写 Key。
|
||||
* **数据直觉**：序列化应该保持数据的本色。我们默认禁用了 HTML 转义，确保像 `<a>` 这样的符号在传输中不会被强制转义为 `\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 +59,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": "<a>"}
|
||||
fmt.Println(cast.Json(content)) // {"link":"<a>"} 而不是 \u003c
|
||||
// 泛型三元运算
|
||||
status := cast.If(isAdmin, "Admin", "User")
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user