Contributing - zhoudm1743/go-util GitHub Wiki

// ✅ 推荐：使用语义化的函数名
func ProcessUserData(users []User) []ProcessedUser {
    return util.ArraysFromSlice(users).
        Filter(isValidUser).
        Map(transformUser).
        ToSlice()
}

// ✅ 推荐：接口名使用 -er 后缀
type DataProcessor interface {
    Process(data []byte) ([]byte, error)
}

// ✅ 推荐：包名简短且有意义
package stringutils // 而不是 strutils 或 string_utilities

// ✅ 推荐：常量使用大写
const (
    DefaultTimeout = 30 * time.Second
    MaxRetries     = 3
)

// ✅ 推荐：文件组织结构
// types_str.go - 字符串工具
// types_array.go - 数组工具
// types_map.go - 映射工具
// types_time.go - 时间工具

// ✅ 推荐：包内导入顺序
import (
    // 标准库
    "context"
    "fmt"
    "time"
    
    // 第三方库
    "github.com/example/package"
    
    // 本地导入
    "github.com/zhoudm1743/go-util/internal"
)

// ✅ 推荐：结构体字段排序
type User struct {
    // 导出字段在前
    ID    string
    Name  string
    Email string
    
    // 未导出字段在后
    password string
    lastLogin time.Time
}

// Package util 提供了一套强大的 Go 语言工具库，
// 包含字符串、数组、映射、时间等常用操作的链式API。
//
// 使用示例：
//   str := util.Str("hello world").Upper().ReplaceRegex(`\s+`, "_").String()
//   // 结果: "HELLO_WORLD"
package util

// XStr 表示一个字符串包装器，提供链式操作方法。
//
// XStr 支持各种字符串操作，包括大小写转换、格式验证、
// 内容替换、编码解码等功能。
//
// 使用示例：
//   email := util.Str(userInput).Trim().Lower().String()
//   if util.Str(email).IsEmail() {
//       // 处理有效邮箱
//   }
type XStr struct {
    value string
}

// Upper 将字符串转换为大写。
//
// 返回一个新的 XStr 实例，原实例保持不变。
//
// 使用示例：
//   result := util.Str("hello").Upper().String() // "HELLO"
func (s *XStr) Upper() *XStr {
    return &XStr{value: strings.ToUpper(s.value)}
}

// IsEmail 检查字符串是否为有效的邮箱地址。
//
// 使用正则表达式验证邮箱格式的有效性。
//
// 返回值：
//   - true: 字符串是有效的邮箱地址
//   - false: 字符串不是有效的邮箱地址
//
// 使用示例：
//   valid := util.Str("[email protected]").IsEmail() // true
//   invalid := util.Str("not-an-email").IsEmail()   // false
func (s *XStr) IsEmail() bool {
    pattern := `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`
    matched, _ := regexp.MatchString(pattern, s.value)
    return matched
}

// ✅ 推荐：定义自定义错误类型
type ValidationError struct {
    Field   string
    Value   interface{}
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("字段 %s 验证失败: %s (值: %v)", e.Field, e.Message, e.Value)
}

// ✅ 推荐：使用 errors.Is 和 errors.As
func ProcessData(data string) error {
    if err := validateData(data); err != nil {
        var validationErr *ValidationError
        if errors.As(err, &validationErr) {
            // 处理验证错误
            return fmt.Errorf("数据处理失败: %w", err)
        }
        return err
    }
    return nil
}

// ✅ 推荐：链式操作中的错误处理
func (s *XStr) SafeToInt() (int, error) {
    if s.IsBlank() {
        return 0, errors.New("不能将空字符串转换为整数")
    }
    
    value, err := strconv.Atoi(s.value)
    if err != nil {
        return 0, fmt.Errorf("字符串转整数失败: %w", err)
    }
    
    return value, nil
}

// ✅ 推荐：测试文件命名 *_test.go
// types_str_test.go

func TestXStr_Upper(t *testing.T) {
    tests := []struct {
        name     string
        input    string
        expected string
    }{
        {
            name:     "基础大写转换",
            input:    "hello",
            expected: "HELLO",
        },
        {
            name:     "混合字符",
            input:    "Hello World",
            expected: "HELLO WORLD",
        },
        {
            name:     "空字符串",
            input:    "",
            expected: "",
        },
        {
            name:     "已经是大写",
            input:    "HELLO",
            expected: "HELLO",
        },
        {
            name:     "包含数字和特殊字符",
            input:    "hello123!@#",
            expected: "HELLO123!@#",
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result := util.Str(tt.input).Upper().String()
            if result != tt.expected {
                t.Errorf("Upper() = %v, want %v", result, tt.expected)
            }
        })
    }
}

// ✅ 推荐：边界条件测试
func TestXStr_IsEmail_EdgeCases(t *testing.T) {
    testCases := []struct {
        email    string
        expected bool
        reason   string
    }{
        {"", false, "空字符串"},
        {"@", false, "只有@符号"},
        {"user@", false, "缺少域名"},
        {"@domain.com", false, "缺少用户名"},
        {"user@domain", false, "缺少顶级域名"},
        {"[email protected]", true, "用户名包含点"},
        {"[email protected]", true, "用户名包含加号"},
        {"[email protected]", true, "长邮箱地址"},
    }
    
    for _, tc := range testCases {
        t.Run(tc.reason, func(t *testing.T) {
            result := util.Str(tc.email).IsEmail()
            if result != tc.expected {
                t.Errorf("IsEmail(%q) = %v, want %v (%s)", 
                    tc.email, result, tc.expected, tc.reason)
            }
        })
    }
}

// ✅ 推荐：性能基准测试
func BenchmarkXStr_Upper(b *testing.B) {
    testStr := "hello world this is a benchmark test"
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        _ = util.Str(testStr).Upper().String()
    }
}

func BenchmarkXStr_ChainedOperations(b *testing.B) {
    testStr := "  hello WORLD [email protected]  "
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        result := util.Str(testStr).
            Trim().
            Lower().
            ReplaceRegex(`\s+`, "_").
            String()
        _ = result
    }
}

// ✅ 推荐：内存分配测试
func TestXStr_MemoryAllocation(t *testing.T) {
    const iterations = 1000
    
    // 测试链式操作的内存分配
    var allocsBefore runtime.MemStats
    runtime.ReadMemStats(&allocsBefore)
    
    for i := 0; i < iterations; i++ {
        _ = util.Str("test").Upper().Lower().Trim().String()
    }
    
    var allocsAfter runtime.MemStats
    runtime.ReadMemStats(&allocsAfter)
    
    allocsPerOp := (allocsAfter.Mallocs - allocsBefore.Mallocs) / iterations
    
    // 确保每次操作的内存分配在合理范围内
    if allocsPerOp > 10 {
        t.Errorf("过多的内存分配: %d allocs/op", allocsPerOp)
    }
}

// ✅ 推荐：功能集成测试
func TestUserDataProcessingIntegration(t *testing.T) {
    // 模拟真实的用户数据处理场景
    rawUsers := []map[string]interface{}{
        {"name": "  Alice  ", "email": "[email protected]", "age": "25"},
        {"name": "Bob", "email": "[email protected]", "age": "30"},
        {"name": "", "email": "invalid-email", "age": "abc"},
    }
    
    var processedUsers []User
    var errors []error
    
    for i, rawUser := range rawUsers {
        // 使用 Go-Util 处理用户数据
        name := util.Str(fmt.Sprintf("%v", rawUser["name"])).Trim().String()
        email := util.Str(fmt.Sprintf("%v", rawUser["email"])).Lower().Trim().String()
        ageStr := util.Str(fmt.Sprintf("%v", rawUser["age"])).Trim().String()
        
        // 验证数据
        if util.Str(name).IsBlank() {
            errors = append(errors, fmt.Errorf("用户 %d: 姓名不能为空", i))
            continue
        }
        
        if !util.Str(email).IsEmail() {
            errors = append(errors, fmt.Errorf("用户 %d: 邮箱格式无效", i))
            continue
        }
        
        if !util.Str(ageStr).IsNumeric() {
            errors = append(errors, fmt.Errorf("用户 %d: 年龄必须为数字", i))
            continue
        }
        
        age := util.Str(ageStr).Int()
        
        processedUsers = append(processedUsers, User{
            Name:  name,
            Email: email,
            Age:   age,
        })
    }
    
    // 验证结果
    if len(processedUsers) != 2 {
        t.Errorf("期望处理2个用户，实际处理了%d个", len(processedUsers))
    }
    
    if len(errors) != 1 {
        t.Errorf("期望1个错误，实际有%d个错误", len(errors))
    }
    
    // 验证处理后的数据
    alice := processedUsers[0]
    if alice.Name != "Alice" || alice.Email != "[email protected]" || alice.Age != 25 {
        t.Errorf("Alice 数据处理错误: %+v", alice)
    }
}