XStr Guide - zhoudm1743/go-util GitHub Wiki

XStr 是 Go-Util 的核心字符串处理工具，提供了丰富的字符串操作方法，支持链式调用，让字符串处理变得简单而优雅。

🚀 特性亮点

🔗 链式调用: 流畅的方法链，提高代码可读性
🛡️ 类型安全: 编译时类型检查，避免运行时错误
⚡ 高性能: 优化的算法实现，最小化内存分配
🌍 国际化: 完整的 Unicode 和中文支持
📝 丰富功能: 涵盖常见字符串操作场景
🔧 易扩展: 支持自定义验证和转换函数

📦 基础用法

创建 XStr 对象

import util "github.com/zhoudm1743/go-util"

// 从字符串创建
str := util.Str("hello world")

// 从其他类型创建
num := util.Str(123)        // "123"
flag := util.Str(true)      // "true"
price := util.Str(3.14)     // "3.14"

// 空字符串
empty := util.Str("")

基础信息获取

str := util.Str("Hello, 世界!")

// 长度信息
fmt.Println(str.Len())           // 9 (字节长度)
fmt.Println(str.RuneCount())     // 8 (字符数，支持中文)

// 状态检查
fmt.Println(str.IsEmpty())       // false
fmt.Println(str.IsBlank())       // false (非空且非空白)

// 获取原始字符串
original := str.String()         // "Hello, 世界!"

🔤 大小写转换

基础转换

str := util.Str("Hello World")

// 大小写转换
upper := str.Upper().String()           // "HELLO WORLD"
lower := str.Lower().String()           // "hello world"

// 首字母处理
firstUpper := str.FirstUpper().String() // "Hello world"
firstLower := str.FirstLower().String() // "hello World"

// 标题格式 (每个单词首字母大写)
title := str.Title().String()           // "Hello World"

命名风格转换

// 不同命名风格的转换
snake := util.Str("userName").String()

// Snake Case (蛇形命名)
snakeCase := util.Str("userName").Camel2Snake().String()        // "user_name"
snakeCase2 := util.Str("UserNameExample").BigCamel2Snake().String() // "user_name_example"

// Camel Case (驼峰命名)
camelCase := util.Str("user_name").Snake2Camel().String()       // "userName"
bigCamelCase := util.Str("user_name").Snake2BigCamel().String() // "UserName"

// Kebab Case (短横线命名)
kebabCase := util.Str("userName").Camel2Kebab().String()        // "user-name"
camelFromKebab := util.Str("user-name").Kebab2Camel().String()  // "userName"

// 复杂示例
complexStr := util.Str("user_profile_settings").
    Snake2BigCamel().      // "UserProfileSettings"
    BigCamel2Kebab().      // "user-profile-settings"  
    Kebab2Camel().         // "userProfileSettings"
    String()

✂️ 字符串修剪和处理

空白字符处理

str := util.Str("  hello world  \n\t")

// 基础修剪
trimmed := str.Trim().String()              // "hello world"
leftTrim := str.TrimLeft().String()         // "hello world  \n\t"
rightTrim := str.TrimRight().String()       // "  hello world"

// 自定义字符修剪
custom := util.Str("...hello...").
    TrimPrefix("...").        // "hello..."
    TrimSuffix("...").        // "hello"
    String()

字符串截取

str := util.Str("Hello, World!")

// 基础截取
sub := str.Substring(0, 5).String()         // "Hello"
sub2 := str.Substring(7, -1).String()       // "World!"

// 长度限制
truncated := str.Truncate(10).String()      // "Hello, Wor"
truncatedWithSuffix := str.TruncateWithSuffix(10, "...").String() // "Hello, W..."

// 左右截取
left := str.Left(5).String()                // "Hello"
right := str.Right(6).String()              // "World!"

🔍 查找和检查

内容检查

str := util.Str("Hello, World! 123")

// 包含检查
hasHello := str.Contains("Hello")           // true
hasPrefix := str.HasPrefix("Hello")         // true
hasSuffix := str.HasSuffix("123")          // true

// 位置查找
index := str.Index("World")                 // 7
lastIndex := str.LastIndex("l")             // 10
count := str.Count("l")                     // 3

类型检查

// 数字检查
num := util.Str("123")
fmt.Println(num.IsNumeric())               // true
fmt.Println(num.IsInt())                   // true
fmt.Println(num.IsFloat())                 // true

decimal := util.Str("123.45")
fmt.Println(decimal.IsNumeric())           // true
fmt.Println(decimal.IsInt())               // false
fmt.Println(decimal.IsFloat())             // true

// 字母检查
alpha := util.Str("Hello")
fmt.Println(alpha.IsAlpha())               // true
fmt.Println(alpha.IsAlphaNumeric())        // true

mixed := util.Str("Hello123")
fmt.Println(mixed.IsAlpha())               // false
fmt.Println(mixed.IsAlphaNumeric())        // true

格式验证

// 邮箱验证
email := util.Str("[email protected]")
fmt.Println(email.IsEmail())               // true

// URL 验证
url := util.Str("https://www.example.com")
fmt.Println(url.IsURL())                   // true

// IP 地址验证
ip := util.Str("192.168.1.1")
fmt.Println(ip.IsIP())                     // true
fmt.Println(ip.IsIPv4())                   // true

ipv6 := util.Str("2001:0db8:85a3:0000:0000:8a2e:0370:7334")
fmt.Println(ipv6.IsIPv6())                 // true

// 手机号验证 (中国)
phone := util.Str("13812345678")
fmt.Println(phone.IsMobile())              // true

// JSON 格式验证
json := util.Str(`{"name": "test", "age": 25}`)
fmt.Println(json.IsJSON())                 // true

🔄 替换和正则表达式

基础替换

str := util.Str("Hello, World! Hello, Go!")

// 简单替换
replaced := str.Replace("Hello", "Hi").String()           // "Hi, World! Hi, Go!"
replaceFirst := str.ReplaceFirst("Hello", "Hi").String()  // "Hi, World! Hello, Go!"
replaceLast := str.ReplaceLast("Hello", "Hi").String()    // "Hello, World! Hi, Go!"

// 大小写忽略替换
ignoreCaseReplace := str.ReplaceIgnoreCase("hello", "Hi").String() // "Hi, World! Hi, Go!"

正则表达式

str := util.Str("Phone: 123-456-7890, Mobile: 987-654-3210")

// 正则匹配
phonePattern := `\d{3}-\d{3}-\d{4}`
matches := str.FindAllRegex(phonePattern)   // ["123-456-7890", "987-654-3210"]
hasMatch := str.MatchRegex(phonePattern)    // true

// 正则替换
masked := str.ReplaceRegex(`\d{3}-\d{3}-\d{4}`, "XXX-XXX-XXXX").String()
// "Phone: XXX-XXX-XXXX, Mobile: XXX-XXX-XXXX"

// 提取数字
numbers := util.Str("Price: $123.45, Tax: $12.34")
extractedNumbers := numbers.ExtractNumbers()  // ["123.45", "12.34"]

✂️ 分割和连接

字符串分割

str := util.Str("apple,banana,orange")

// 基础分割
parts := str.Split(",")                     // ["apple", "banana", "orange"]
partsWithLimit := str.SplitN(",", 2)        // ["apple", "banana,orange"]

// 按行分割
multiLine := util.Str("line1\nline2\rline3\r\nline4")
lines := multiLine.SplitLines()             // ["line1", "line2", "line3", "line4"]

// 按空白分割
words := util.Str("  hello   world  go  ").SplitWhitespace()
// ["hello", "world", "go"]

字符串连接

// 连接字符串
result := util.Str("Hello").
    Concat(", ").
    Concat("World").
    Concat("!").
    String()                                // "Hello, World!"

// 使用分隔符连接数组
parts := []string{"apple", "banana", "orange"}
joined := util.StrJoin(parts, ", ")         // "apple, banana, orange"

🔢 类型转换

数值转换

// 转换为数字
num := util.Str("123")
intVal := num.Int()                         // 123
int64Val := num.Int64()                     // int64(123)
floatVal := num.Float64()                   // 123.0

// 安全转换 (带错误检查)
safeInt, err := num.ToInt()
if err == nil {
    fmt.Printf("转换成功: %d\n", safeInt)
}

// 带默认值的转换
defaultInt := util.Str("invalid").IntOr(0)     // 0 (默认值)
defaultFloat := util.Str("invalid").Float64Or(0.0) // 0.0

布尔转换

// 布尔值转换
trueStr := util.Str("true")
fmt.Println(trueStr.Bool())                 // true

// 支持多种格式
formats := []string{"true", "TRUE", "True", "1", "yes", "YES", "on", "ON"}
for _, format := range formats {
    fmt.Printf("%s -> %t\n", format, util.Str(format).Bool())
}

// 带默认值
invalidBool := util.Str("invalid").BoolOr(false) // false

🌍 编码和解码

Base64 编码

str := util.Str("Hello, World!")

// Base64 编码
encoded := str.Base64Encode().String()      // "SGVsbG8sIFdvcmxkIQ=="

// Base64 解码
decoded := util.Str(encoded).Base64Decode().String() // "Hello, World!"

// URL 安全的 Base64
urlEncoded := str.Base64URLEncode().String()
urlDecoded := util.Str(urlEncoded).Base64URLDecode().String()

URL 编码

str := util.Str("Hello World & Go")

// URL 编码
urlEncoded := str.URLEncode().String()      // "Hello%20World%20%26%20Go"
urlDecoded := util.Str(urlEncoded).URLDecode().String() // "Hello World & Go"

// 查询参数编码
queryEncoded := str.QueryEscape().String()
queryDecoded := util.Str(queryEncoded).QueryUnescape().String()

HTML 编码

str := util.Str("<div>Hello & \"World\"</div>")

// HTML 编码
htmlEncoded := str.HTMLEscape().String()    // "&lt;div&gt;Hello &amp; &quot;World&quot;&lt;/div&gt;"
htmlDecoded := util.Str(htmlEncoded).HTMLUnescape().String() // 原始字符串

🔐 哈希和加密

哈希函数

str := util.Str("Hello, World!")

// 常用哈希
md5Hash := str.MD5().String()               // "65a8e27d8879283831b664bd8b7f0ad4"
sha1Hash := str.SHA1().String()             // "943a702d06f34599aee1f8da8ef9f7296031d699"
sha256Hash := str.SHA256().String()         // "dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f"

// 多重哈希
multiHash := str.MD5().SHA256().String()    // 先MD5，再SHA256

字符串生成

// 随机字符串生成
randomStr := util.RandomString(10)          // 生成10位随机字符串
randomAlpha := util.RandomAlphaString(8)    // 生成8位字母字符串
randomNum := util.RandomNumericString(6)    // 生成6位数字字符串

// UUID 生成
uuid := util.GenerateUUID()                 // 生成 UUID

📏 字符串度量

相似度计算

str1 := util.Str("hello")
str2 := util.Str("hallo")

// 编辑距离
distance := str1.LevenshteinDistance(str2.String()) // 1

// 相似度百分比
similarity := str1.Similarity(str2.String())        // 0.8 (80%)

// 模糊匹配
fuzzyMatch := str1.FuzzyMatch(str2.String(), 0.7)   // true (相似度超过70%)

字符统计

str := util.Str("Hello, World! 123")

// 字符统计
charCount := str.CharCount()                // map[rune]int
letterCount := str.LetterCount()            // 字母数量
digitCount := str.DigitCount()              // 数字数量
spaceCount := str.SpaceCount()              // 空格数量

// 单词统计
wordCount := str.WordCount()                // 单词数量

🎨 格式化和美化

字符串格式化

str := util.Str("hello world")

// 填充
padded := str.PadLeft(15, ' ').String()     // "     hello world"
paddedRight := str.PadRight(15, '*').String() // "hello world****"
paddedBoth := str.PadBoth(15, '-').String() // "--hello world--"

// 居中对齐
centered := str.Center(20, ' ').String()    // "   hello world    "

文本处理

longText := util.Str("This is a very long line that needs to be wrapped")

// 文本换行
wrapped := longText.WordWrap(20).String()
/* 输出:
This is a very long
line that needs to be
wrapped
*/

// 缩进
indented := util.Str("line1\nline2\nline3").Indent("  ").String()
/* 输出:
  line1
  line2
  line3
*/

🔧 高级功能

自定义验证

// 自定义验证函数
isValidUsername := func(s string) bool {
    return len(s) >= 3 && len(s) <= 20 && util.Str(s).MatchRegex(`^[a-zA-Z0-9_]+$`)
}

username := util.Str("user123")
valid := username.Validate(isValidUsername)  // true

// 多个验证规则
validators := []func(string) bool{
    func(s string) bool { return len(s) >= 6 },  // 最小长度
    func(s string) bool { return util.Str(s).MatchRegex(`[A-Z]`) }, // 包含大写字母
    func(s string) bool { return util.Str(s).MatchRegex(`[0-9]`) }, // 包含数字
}

password := util.Str("Password123")
allValid := password.ValidateAll(validators) // true

字符串构建器

// 高效的字符串构建
builder := util.NewStringBuilder()
builder.Append("Hello")
builder.Append(", ")
builder.Append("World")
builder.Append("!")

result := builder.String()                   // "Hello, World!"

// 带容量预分配的构建器
builder2 := util.NewStringBuilderWithCapacity(100)
for i := 0; i < 10; i++ {
    builder2.Append(fmt.Sprintf("Item %d, ", i))
}

模板处理

// 简单模板替换
template := util.Str("Hello, {{name}}! You have {{count}} messages.")
result := template.ReplaceTemplate(map[string]string{
    "name":  "Alice",
    "count": "5",
}).String()                                  // "Hello, Alice! You have 5 messages."

// 条件模板
conditionalTemplate := util.Str("{{if premium}}Premium{{else}}Regular{{endif}} User")
premiumResult := conditionalTemplate.ReplaceConditional("premium", true).String()
// "Premium User"

🚀 性能优化

链式调用优化

// ✅ 推荐：合理的链式调用
result := util.Str("  Hello_World_Example  ").
    Trim().                    // 去除空白
    Snake2BigCamel().          // 转换为大驼峰
    Truncate(10).              // 截取前10个字符
    String()

// ❌ 避免：过长的链式调用（影响可读性）

批量操作

// 批量字符串处理
strings := []string{"hello_world", "user_name", "data_base"}
results := util.BatchStringProcess(strings, func(s string) string {
    return util.Str(s).Snake2Camel().String()
})
// ["helloWorld", "userName", "dataBase"]

内存优化

// 使用StringBuilder处理大量字符串拼接
builder := util.NewStringBuilderWithCapacity(1000)
for i := 0; i < 100; i++ {
    builder.Append(fmt.Sprintf("Item %d\n", i))
}
result := builder.String()

// 复用XStr对象
str := util.Str("")
for _, item := range items {
    str = str.Reset(item).Process().String()  // 复用对象
}

🔍 实际应用场景

数据清洗

// 用户输入数据清洗
func CleanUserInput(input string) string {
    return util.Str(input).
        Trim().                     // 去除首尾空白
        ReplaceRegex(`\s+`, " ").   // 多个空格替换为单个
        HTMLEscape().               // HTML转义防XSS
        Truncate(200).              // 限制长度
        String()
}

// CSV 数据处理
func ProcessCSVField(field string) string {
    return util.Str(field).
        Trim().
        Replace(`"`, `""`).         // 转义双引号
        String()
}

API 响应处理

// 统一的错误消息格式化
func FormatErrorMessage(code string, message string) string {
    return util.Str("ERROR_{{code}}: {{message}}").
        ReplaceTemplate(map[string]string{
            "code":    code,
            "message": message,
        }).
        Upper().
        String()
}

// URL 路径标准化
func NormalizePath(path string) string {
    return util.Str(path).
        TrimPrefix("/").
        TrimSuffix("/").
        ReplaceRegex(`/+`, "/").    // 多个斜杠替换为单个
        Lower().
        String()
}

配置文件处理

// 环境变量处理
func ProcessEnvVar(key, defaultValue string) string {
    value := os.Getenv(key)
    if util.Str(value).IsBlank() {
        return defaultValue
    }
    
    return util.Str(value).
        Trim().
        String()
}

// 配置键名标准化
func NormalizeConfigKey(key string) string {
    return util.Str(key).
        Lower().
        ReplaceRegex(`[^a-z0-9]`, "_").  // 非字母数字替换为下划线
        ReplaceRegex(`_+`, "_").         // 多个下划线替换为单个
        Trim("_").                       // 去除首尾下划线
        String()
}

📊 性能基准

基准测试结果

操作类型                    性能指标
基础字符串操作              微秒级响应
正则表达式匹配              毫秒级处理
大小写转换                  零内存分配
链式调用(5个方法)          < 1微秒
哈希计算(MD5/SHA256)       毫秒级完成
Base64编码/解码            微秒级响应

内存使用优化

// 基准测试示例
func BenchmarkStringOperations(b *testing.B) {
    testStr := "hello_world_example_test_string"
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        result := util.Str(testStr).
            Snake2Camel().
            FirstUpper().
            String()
        _ = result
    }
}

// 结果示例：
// BenchmarkStringOperations-8    1000000    1.2 μs/op    32 B/op    2 allocs/op

🎯 最佳实践

1. 错误处理

// ✅ 安全的类型转换
str := util.Str("123abc")
if str.IsNumeric() {
    value := str.Int()  // 安全转换
} else {
    // 处理无效输入
    log.Printf("Invalid numeric input: %s", str.String())
}

// ✅ 带默认值的转换
value := str.IntOr(0)  // 转换失败返回0

2. 性能优化

// ✅ 预编译正则表达式
var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)

func IsValidEmail(email string) bool {
    return emailRegex.MatchString(email)
}

// ✅ 复用字符串构建器
var builderPool = sync.Pool{
    New: func() interface{} {
        return &strings.Builder{}
    },
}

3. 可读性优化

// ✅ 清晰的链式调用
cleanedInput := util.Str(userInput).
    Trim().                    // 步骤1：去除空白
    HTMLEscape().             // 步骤2：HTML转义
    Truncate(maxLength).      // 步骤3：限制长度
    String()

// ✅ 语义化的变量名
username := util.Str(rawUsername).
    Lower().
    ReplaceRegex(`[^a-z0-9_]`, "").
    String()

🔗 相关资源

🚀 快速开始 - 基础使用方法
🧠 基础概念 - 设计理念
⚡ 性能优化指南 - 性能调优
❓ 常见问题 - 问题解答

💬 获取帮助

如果您在使用 XStr 时遇到问题：

🔍 查看FAQ - 常见字符串处理问题
🐛 报告问题 - Bug反馈
💡 功能建议 - 新功能讨论
📧 邮件支持 - [email protected]

🎉 现在您已经掌握了 XStr 的强大功能，开始在项目中使用这些优雅的字符串操作吧！

XStr Guide - zhoudm1743/go-util GitHub Wiki

🚀 特性亮点

📦 基础用法

创建 XStr 对象

基础信息获取

🔤 大小写转换

基础转换

命名风格转换

✂️ 字符串修剪和处理

空白字符处理

字符串截取

🔍 查找和检查

内容检查

类型检查

格式验证

🔄 替换和正则表达式

基础替换

正则表达式

✂️ 分割和连接

字符串分割

字符串连接

🔢 类型转换

数值转换

布尔转换

🌍 编码和解码

Base64 编码

URL 编码

HTML 编码

🔐 哈希和加密

哈希函数

字符串生成

📏 字符串度量

相似度计算

字符统计

🎨 格式化和美化

字符串格式化

文本处理

🔧 高级功能

自定义验证

字符串构建器

模板处理

🚀 性能优化

链式调用优化

批量操作

内存优化

🔍 实际应用场景

数据清洗

API 响应处理

配置文件处理

📊 性能基准

基准测试结果

内存使用优化

🎯 最佳实践

1. 错误处理

2. 性能优化

3. 可读性优化

🔗 相关资源

💬 获取帮助

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️