# utils4go

**Repository Path**: last911/utils4go

## Basic Information

- **Project Name**: utils4go
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-22
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# utils4go

[![Go Version](https://img.shields.io/badge/Go-1.23+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)]()
[![Coverage](https://img.shields.io/badge/Coverage-88.8%25-green.svg)]()

> 一个功能强大、类型安全的 Go 工具库，提供常用的工具函数和实用程序

## 📖 简介

`utils4go` 是一个现代化的 Go 工具库，旨在为 Go 开发者提供一套完整、高效、类型安全的工具函数集合。该库采用 Go 1.23+ 的泛型特性，确保了类型安全的同时提供了极佳的开发体验。

## ✨ 特性

- 🚀 **现代 Go 特性**: 使用 Go 1.23+ 泛型，提供类型安全的 API
- 📦 **模块化设计**: 按功能分类的包结构，按需引入
- 🧪 **完整测试**: 高测试覆盖率，确保代码质量
- 📚 **详细文档**: 完善的 API 文档和使用示例
- 🔒 **安全可靠**: 经过充分测试，适用于生产环境
- ⚡ **高性能**: 优化的算法实现，追求极致性能

## 🏗️ 项目结构

```
utils4go/
├── collection/     # 集合和数组操作
├── config/         # 配置管理
├── crypto/         # 加密和安全
├── io/             # 文件和IO操作
├── net/            # 网络工具
├── random/         # 随机数生成
└── web/            # Web响应处理
```

## 📦 安装

```bash
go get ekuy.com/utils4go
```

## 🚀 快速开始

### Collection 包 - 集合操作

```go
import "ekuy.com/utils4go/collection"

// 随机选择数组元素
names := []string{"Alice", "Bob", "Charlie"}
randomName := collection.RandArray(names)

// 生成数值序列
numbers := collection.RangeNumeric[int](1, 10) // [1,2,3,4,5,6,7,8,9]

// 使用转换函数生成序列
squares := collection.RangeArray(1, 5, func(i int) int { return i * i }) // [1,4,9,16]
```

### Config 包 - 配置管理

```go
import "ekuy.com/utils4go/config"

type AppConfig struct {
    Port    int    `mapstructure:"port"`
    Debug   bool   `mapstructure:"debug"`
    LogPath string `mapstructure:"log_path"`
}

var cfg AppConfig
config.InitConfig(&cfg, "config.yaml")
```

### Crypto 包 - 加密工具

```go
import "ekuy.com/utils4go/crypto"

// MD5 哈希
hash := crypto.Md5Sum("hello world")

// Base64 编码解码
encoded := crypto.Base64Encode([]byte("hello"))
decoded, _ := crypto.Base64Decode(encoded)

// SHA256 哈希
sha256Hash := crypto.SHA256("secret data")

// HMAC-SHA256
hmac := crypto.HMacSHA256("message", "secret-key")
```

### IO 包 - 文件操作

```go
import "ekuy.com/utils4go/io"

// 解析文件路径
info := io.ParseFilePath("/path/to/file.txt")
// info.Dir = "/path/to"
// info.Name = "file.txt"
// info.Ext = ".txt"

// 检查文件是否存在
exists := io.FileExists("/path/to/file.txt")
```

### Net 包 - 网络工具

```go
import "ekuy.com/utils4go/net"

// 验证 IP 地址
isValid := net.IsValidIP("192.168.1.1")

// 子网掩码转换
mask, _ := net.BitsToMask(24)     // "255.255.255.0"
bits, _ := net.MaskToBits("255.255.255.0") // 24

// IP 地址与整数互转
ipInt, _ := net.IPToInt("192.168.1.1")
ipStr := net.IntToIP(ipInt) // "192.168.1.1"
```

### Random 包 - 随机数生成

```go
import "ekuy.com/utils4go/random"

// 生成随机数生成器
r := random.NewRand()
randomNum := r.Intn(100)
```

### Web 包 - Web 响应

```go
import "ekuy.com/utils4go/web"

// 成功响应
result := web.OK("name", "Alice", "age", 25)
// Result{Code: 0, Msg: "", Data: map[string]interface{}{"name": "Alice", "age": 25}}

// 错误响应
errorResult := web.Error(404, "Not Found")
// Result{Code: 404, Msg: "Not Found", Data: nil}

// 使用预定义错误码
forbiddenResult := web.ErrorResult(web.ERROR_FORBID)
```

## 📚 API 文档

### Collection 包

| 函数 | 描述 | 泛型约束 |
|------|------|----------|
| `RandArray[T any](arr []T) T` | 随机选择数组元素 | `any` |
| `RangeArray[T any](m, n int, fn func(int) T) []T` | 生成序列数组 | `any` |
| `RangeNumeric[T Numeric](m, n int) []T` | 生成数值序列 | `Numeric` |
| `RandNumeric[T Numeric](arr []T) T` | 随机选择数值 | `Numeric` |
| `RangeInteger[T Integer](m, n int) []T` | 生成整数序列 | `Integer` |
| `RandInteger[T Integer](arr []T) T` | 随机选择整数 | `Integer` |

### Config 包

| 函数 | 描述 |
|------|------|
| `InitConfig[T any](config *T, path ...string)` | 初始化配置 |
| `NewViper(fileInfo f.Info) (*viper.Viper, error)` | 创建 Viper 实例 |
| `NewViperFromPath(path string) (*viper.Viper, error)` | 从路径创建 Viper |

### Crypto 包

| 函数 | 描述 |
|------|------|
| `Md5Sum(text string) string` | MD5 哈希 |
| `SHA256(s string) string` | SHA256 哈希 |
| `HMacSHA256(s, key string) string` | HMAC-SHA256 |
| `Base64Encode(b []byte) string` | Base64 编码 |
| `Base64Decode(str string) ([]byte, error)` | Base64 解码 |
| `RsaEncode(b, rsaKey []byte, t ...CertType) ([]byte, error)` | RSA 加密 |
| `RsaDecode(b, rsaKey []byte, t ...CertType) ([]byte, error)` | RSA 解密 |
| `Authcode(text string, params ...interface{}) (string, error)` | 授权码 |
| `URLEncode(params interface{}) string` | URL 编码 |
| `URLDecode(str string) (string, error)` | URL 解码 |

### IO 包

| 函数 | 描述 |
|------|------|
| `ParseFilePath(path string) Info` | 解析文件路径 |
| `FileExists(filePath string) bool` | 检查文件是否存在 |

### Net 包

| 函数 | 描述 |
|------|------|
| `IsValidIP(ipStr string) bool` | 验证 IP 地址 |
| `IsValidNetmask(maskStr string) bool` | 验证子网掩码 |
| `BitsToMask(prefixLength int) (string, error)` | 位数转掩码 |
| `MaskToBits(maskStr string) (int, error)` | 掩码转位数 |
| `IPToInt(ipStr string) (uint32, error)` | IP 转整数 |
| `IntToIP(ipInt uint32) string` | 整数转 IP |

### Random 包

| 函数 | 描述 |
|------|------|
| `NewRand() *rand.Rand` | 创建随机数生成器 |

### Web 包

| 函数 | 描述 |
|------|------|
| `OK(params ...interface{}) *Result` | 成功响应 |
| `Error(params ...interface{}) *Result` | 错误响应 |
| `ErrorResult(message *MessageCode) *Result` | 消息码错误响应 |

## 🧪 测试

运行所有测试：

```bash
go test ./...
```

运行测试并查看覆盖率：

```bash
go test -cover ./...
```

测试覆盖率报告：
- collection: 100.0%
- config: 57.1%
- crypto: 68.1%
- io: 100.0%
- net: 96.3%
- random: 100.0%
- web: 100.0%

## 🔧 开发

### 环境要求

- Go 1.23+
- Git

### 构建项目

```bash
git clone https://github.com/kbrownehs18/utils4go.git
cd utils4go
go mod tidy
go test ./...
```

### 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 Apache License 2.0 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 🤝 致谢

感谢所有为这个项目做出贡献的开发者！

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 Issue: [GitHub Issues](https://github.com/kbrownehs18/utils4go/issues)
- 邮箱: your-email@example.com

---

⭐ 如果这个项目对你有帮助，请给我们一个 Star！