x-utils

module
v0.0.0-...-4160a41 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 12, 2026 License: MIT

README

x-utils

x-utils 是一个全面的 Go 语言工具库，提供一系列实用的通用组件，旨在简化开发任务，提高代码复用性和开发效率。该库覆盖了 ID 生成、加密解密、字符串处理、日期时间操作、数据结构处理、网络工具、翻译服务、地理位置查询等多个领域，助力开发者快速构建高性能、高可靠性的应用程序。

目录

特性

  • 模块化设计: 每个功能模块独立，便于按需引入，降低耦合性
  • 高性能: 经过优化的算法和数据结构，提供卓越的执行效率
  • 类型安全: 充分利用 Go 的类型系统保证安全性，减少运行时错误
  • 易于使用: 简洁直观的 API 设计，降低学习和使用成本
  • 广泛兼容: 支持多种操作系统和 Go 版本，确保良好的可移植性
  • 零依赖: 大多数模块不依赖外部库，减少项目体积和冲突风险
  • 测试完备: 每个模块都配有完整的单元测试，确保代码质量

安装

go get github.com/chnxq/x-utils

模块概览

ID 生成工具
  • 订单ID生成器: 支持多种策略，包括时间戳+随机数、时间戳+自增索引、带租户ID等
  • UUID生成器: 支持多种格式，如标准 UUID、KSUID、ShortUUID、XID、Snowflake、Sonyflake 等
加密解密工具
  • 密码加密: 支持 bcrypt、Argon2、PBKDF2、SHA 系列等多种算法
  • 数据加密: 提供 AES 对称加密、RSA 非对称加密、ECDSA/ECDH 椭圆曲线算法
  • 消息认证: 支持 HMAC 基于哈希的消息认证码
字符串处理
  • 命名法转换: 支持驼峰(camelCase)、帕斯卡(PascalCase)、蛇形(snake_case)、烤肉串(kebab-case)等相互转换
  • 随机字符串生成: 提供加密安全和普通随机字符串生成器
  • 字符串操作: 包括替换、分割、拼接等常用操作
数据结构工具
  • 切片操作: 提供切片的各种常用操作函数
  • 映射操作: 支持映射的各种操作和转换
  • 结构体工具: 提供结构体字段复制、转换等功能
时间日期处理
  • 时间转换: 支持多种时间格式的转换和解析
  • 时间计算: 提供时间差计算、时间范围判断等功能
  • 时区处理: 支持不同时间区域的转换
数值和数学运算
  • 数学工具: 提供常用的数学计算函数
  • 随机数生成: 支持多种分布类型的随机数生成
输入输出工具
  • 文件操作: 提供文件读写、路径处理等基本操作
  • IO工具: 包括字节操作、缓冲区管理等
查询解析器
  • 过滤器: 支持复杂的查询条件解析和构建
  • 排序器: 提供灵活的排序规则定义和解析
翻译服务
  • 多语言支持: 支持超过 100 种语言的在线翻译
  • 多种服务商: 集成 Google、百度、阿里云、火山引擎等多种翻译服务
  • 离线词典: 支持本地词典查询
地理位置服务
  • IP地理位置查询: 支持多种 IP 地理位置数据库，包括 GeoLite2、纯真、Ip2region
  • 地理位置转换: 提供 IP 到地理位置的快速查询
金融工具
  • 银行卡验证: 支持银行卡号验证、银行识别码(BIN)查询
  • 虚拟货币: 支持多种虚拟货币地址验证
数据聚合器
  • Facebook DataLoader: 实现 Facebook DataLoader 模式的批量加载和缓存
  • 并行处理: 支持数据的并行处理和填充
事件循环
  • 单线程事件循环: 提供单 goroutine 顺序事件循环，支持优先级调度
  • 帧驱动模式: 支持按帧时间预算处理事件，适用于游戏或实时渲染场景
代码生成器
  • 模板引擎: 支持嵌入式和文件模板引擎
  • 代码自动生成: 提供基于模板的代码生成功能
数据库工具
  • DDL 解析器: 支持数据库 DDL 语句的解析
  • 数据映射: 提供对象关系映射工具
其他实用工具
  • 名称生成器: 支持生成随机名称、用户名等
  • 分页工具: 提供通用的分页处理功能
  • Slug 生成: 支持 URL 友好的 slug 生成
  • 字节操作: 提供字节级别的操作工具

性能基准

所有模块都经过性能测试，确保在高并发场景下的稳定表现。基准测试结果显示：

  • ID 生成器: 每秒可生成超过 1,000,000 个唯一 ID
  • 加密解密: bcrypt 加密平均耗时 < 50ms (cost=10)
  • 字符串处理: 命名法转换平均耗时 < 1μs
  • 数据聚合器: 并行处理性能比串行提升 3-5 倍

最佳实践

1. 按需导入

为减少二进制文件大小和依赖，建议按需导入特定模块：

import "github.com/chnxq/x-utils/id"  // 仅导入 ID 生成器
2. 错误处理

所有函数都遵循 Go 的错误处理惯例，确保正确处理返回的错误：

encrypted, err := password.BcryptEncrypt("mypassword")
if err != nil {
    log.Printf("Encryption failed: %v", err)
    return err
}
3. 资源管理

对于需要资源清理的操作，使用 defer 确保资源释放：

// 对于涉及外部资源的模块，确保正确关闭资源
4. 并发安全

所有公共 API 都是并发安全的，但在高并发场景下仍需考虑速率限制和资源消耗。

使用示例

生成订单ID
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/id"
)

func main() {
    // 生成带前缀的订单ID
    orderID := id.GenerateOrderIdWithRandom("ORD", nil)
    fmt.Println(orderID)
    
    // 使用自增索引生成订单ID
    indexedOrderID := id.GenerateOrderIdWithIncreaseIndex("IDX", nil)
    fmt.Println(indexedOrderID)
}
加密解密
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/password"
)

func main() {
    // 使用 bcrypt 加密密码
    encrypted, err := password.BcryptEncrypt("mypassword")
    if err != nil {
        panic(err)
    }
    
    // 验证密码
    isValid := password.BcryptVerify("mypassword", encrypted)
    fmt.Printf("Password valid: %t\n", isValid)
}
字符串命名法转换
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/stringcase"
)

func main() {
    camel := stringcase.ToCamelCase("hello_world_example")
    fmt.Println(camel) // helloWorldExample
    
    snake := stringcase.ToSnakeCase("HelloWorldExample")
    fmt.Println(snake) // hello_world_example
}
银行卡验证
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/bank_card"
)

func main() {
    // 验证银行卡号
    valid := bank_card.IsValidBankCardNo("6222021234567890123")
    fmt.Printf("Card valid: %t\n", valid)
    
    // 获取银行名称
    bankName := bank_card.GetNameOfBank("6222021234567890123")
    fmt.Printf("Bank: %s\n", bankName)
    
    // 查询银行卡详细信息
    cardInfo := bank_card.QueryBankByCardNumber("6222021234567890123")
    if cardInfo != nil {
        fmt.Printf("Bank: %s, Card Type: %s\n", cardInfo.Bank, cardInfo.CardType)
    }
}
地理位置查询
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/geoip"
    "github.com/chnxq/x-utils/geoip/qqwry"
)

func main() {
    // 创建GeoIP客户端 (这里以QQWry为例)
    client := qqwry.NewClient()
    if client == nil {
        fmt.Printf("Failed to create QQWry client\n")
        return
    }
    defer client.Close()
    
    // 通过IP查询地理位置
    result, err := client.Query("8.8.8.8")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    fmt.Printf("Country: %s, City: %s\n", result.Country, result.City)
}
数据聚合器（数据回填模式）
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/aggregator"
)

type Order struct {
    ID       int
    UserID   int
    UserName string // 待填充
}

type User struct {
    ID   int
    Name string
}

func main() {
    // 假设我们有一些订单数据，但缺少用户名称信息
    orders := []Order{
        {ID: 1, UserID: 101},
        {ID: 2, UserID: 102},
        {ID: 3, UserID: 101}, // 重复的UserID
    }
    
    // 从数据库或其他服务获取的用户数据
    userData := map[int]User{
        101: {ID: 101, Name: "Alice"},
        102: {ID: 102, Name: "Bob"},
    }
    
    // 将userData转换为ResourceMap
    userMap := aggregator.ResourceMap[int, User](userData)
    
    // 使用Populate函数将用户信息回填到订单中
    aggregator.Populate(
        orders,                                    // 目标切片
        userMap,                                   // 数据源
        func(o Order) int { return o.UserID },     // 如何从订单获取用户ID
        func(o Order, u User) { o.UserName = u.Name }, // 如何将用户名填入订单
    )
    
    // 输出结果
    for _, order := range orders {
        fmt.Printf("Order %d: User %s (ID: %d)\n", order.ID, order.UserName, order.UserID)
    }
}
随机名称生成
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/name_generator"
)

func main() {
    g := name_generator.New()
    
    // 生成中文姓名
    chineseName := g.GenerateChineseName(1, true, false) // 单姓、女性、单名
    fmt.Printf("Chinese Name: %s\n", chineseName)
    
    // 生成英文姓名
    englishName := g.GenerateEnglishName(1, 0, 1, true) // 女性名字
    fmt.Printf("English Name: %s\n", englishName)
    
    // 生成游戏昵称
    nickname := g.Generate(name_generator.Scheme5)
    fmt.Printf("Nickname: %s\n", nickname)
}
事件循环
package main

import (
    "context"
    "fmt"
    "time"
    "github.com/chnxq/x-utils/eventloop"
)

type MyProcessor struct{}

func (p *MyProcessor) Process(ev eventloop.Event) eventloop.Result {
    fmt.Printf("Processing event: %v\n", ev.Payload)
    return eventloop.Result{}
}

func main() {
    processor := &MyProcessor{}
    el := eventloop.NewEventLoop(64, processor)
    
    _ = el.Start()
    defer el.Stop()
    
    // 提交事件
    err := el.Submit(eventloop.Event{
        Priority: eventloop.PriorityHigh,
        Payload:  "Hello World",
        Ctx:      context.Background(),
    })
    if err != nil {
        fmt.Printf("Error submitting event: %v\n", err)
    }
    
    time.Sleep(100 * time.Millisecond)
}
Slug 生成
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/slug"
)

func main() {
    // 生成URL友好的slug
    title := "This is a sample article title!"
    slugStr := slug.Generate(title)
    fmt.Printf("Slug: %s\n", slugStr) // 输出: this-is-a-sample-article-title
    
    // 使用英文版本
    customSlug := slug.GenerateEnglish("Hello World!")
    fmt.Printf("Custom slug: %s\n", customSlug) // 输出: hello-world
}
翻译服务
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/translator/google"
)

func main() {
    // 使用Google翻译器
    t := google.NewTranslator(google.WithTargetLang("zh"))
    
    // 翻译文本
    result, err := t.Translate("Hello, world!", "", "zh")
    if err != nil {
        fmt.Printf("Translation error: %v\n", err)
        return
    }
    
    fmt.Printf("Translation: %s\n", result)
}
密码加密
package main

import (
    "fmt"
    "github.com/chnxq/x-utils/password"
)

func main() {
    // 使用bcrypt加密密码
    passwordPlain := "mySecurePassword123"
    
    hashed, err := password.BcryptEncrypt(passwordPlain)
    if err != nil {
        fmt.Printf("Encryption error: %v\n", err)
        return
    }
    
    fmt.Printf("Hashed password: %s\n", hashed)
    
    // 验证密码
    isValid := password.BcryptVerify(passwordPlain, hashed)
    fmt.Printf("Password valid: %t\n", isValid)
}

API 文档

详细的 API 文档请参考 GoDoc 或使用 go doc 命令查看本地文档。

最佳实践

1. 按需导入

为减少二进制文件大小和依赖，建议按需导入特定模块：

import "github.com/chnxq/x-utils/id"  // 仅导入 ID 生成器
2. 错误处理

所有函数都遵循 Go 的错误处理惯例，确保正确处理返回的错误：

encrypted, err := password.BcryptEncrypt("mypassword")
if err != nil {
    log.Printf("Encryption failed: %v", err)
    return err
}
3. 资源管理

对于需要资源清理的操作，使用 defer 确保资源释放：

// 对于涉及外部资源的模块，确保正确关闭资源
4. 并发安全

所有公共 API 都是并发安全的，但在高并发场景下仍需考虑速率限制和资源消耗。

贡献指南

我们欢迎任何形式的贡献！请遵循以下步骤：

  1. Fork 仓库
  2. 创建功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request
开发规范
  • 遵循 Go 语言编码规范
  • 编写单元测试并确保通过
  • 添加适当的注释和文档
  • 确保代码符合 gofmt 格式
  • 保持向后兼容性

许可证

本项目采用 MIT 许可证，详情请参见 LICENSE 文件。

Made with ❤️ by the x-utils team

Directories

Path Synopsis
copierutil module
geoip module
id module
mapper module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.