# xutils

**Repository Path**: liangzero/xutils

## Basic Information

- **Project Name**: xutils
- **Description**: 工具包
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Go 工具包集合

这是一个实用的 Go 语言工具包集合，包含了多个常用的功能模块，旨在提高开发效率和代码质量。

## 目录结构

```
utils/
├── xcrypto/      # 加密解密工具
├── xfile/        # 文件操作工具
├── xstring/      # 字符串处理工具
├── xslice/       # 切片操作工具
├── xdate/        # 日期时间处理工具
├── xlog/         # 日志工具
├── xcache/       # 缓存工具（包名为di）
├── xvalidator/   # 数据验证工具
├── go.mod        # 依赖管理
├── test_all.go   # 测试文件
└── README.md     # 项目说明
```

## 工具包介绍

### 1. xcrypto - 加密解密工具

提供常用的加密解密功能，包括 MD5、SHA 系列哈希算法、AES 加解密等。

#### 主要功能

- MD5 哈希计算
- SHA 系列（SHA1、SHA224、SHA256、SHA384、SHA512）哈希计算
- AES 加密解密（支持 ECB 和 CBC 模式）
- 随机字符串生成

#### 使用示例

```go
package main

import (
	"fmt"
	"gitee.com/liangzero/xutils/xcrypto"
)

func main() {
	// MD5 哈希
	md5 := xcrypto.MD5("hello world")
	fmt.Println("MD5:", md5)

	// SHA256 哈希
	sha256 := xcrypto.SHA256("hello world")
	fmt.Println("SHA256:", sha256)

	// AES 加密解密
	key := "1234567890123456"
	plaintext := "hello world"
	ciphertext, _ := xcrypto.AESEncrypt(plaintext, key)
	fmt.Println("AES加密结果:", ciphertext)

	decrypted, _ := xcrypto.AESDecrypt(ciphertext, key)
	fmt.Println("AES解密结果:", decrypted)
}
```

### 2. xfile - 文件操作工具

提供便捷的文件和目录操作功能，包括文件读写、目录遍历、文件信息获取等。

#### 主要功能

- 文件存在性检查
- 文件读写操作
- 目录创建和遍历
- 文件复制、移动和删除
- 文件大小获取
- 文件权限管理

#### 使用示例

```go
package main

import (
	"fmt"
	"gitee.com/liangzero/xutils/xfile"
)

func main() {
	// 检查文件是否存在
	exists := xfile.Exists("test.txt")
	fmt.Println("文件是否存在:", exists)

	// 写入文件
	xfile.WriteFile("test.txt", "hello world", false)

	// 读取文件
	content, _ := xfile.ReadFile("test.txt")
	fmt.Println("文件内容:", content)

	// 获取文件大小
	size, _ := xfile.GetFileSize("test.txt")
	fmt.Println("文件大小:", size, "bytes")

	// 创建目录
	xfile.MkdirAll("test_dir", 0755)
}
```

### 3. xstring - 字符串处理工具

提供常用的字符串处理功能，包括字符串检查、转换、格式化等。

#### 主要功能

- 字符串空值检查
- 字符串转换（大小写、格式转换等）
- 字符串格式化
- 字符串截取和填充
- 字符串替换和分割

#### 使用示例

```go
package main

import (
	"fmt"
	"gitee.com/liangzero/xutils/xstring"
)

func main() {
	// 检查字符串是否为空
	isEmpty := xstring.IsEmpty("")
	fmt.Println("字符串是否为空:", isEmpty)

	// 字符串转大写
	upper := xstring.ToUpper("hello world")
	fmt.Println("大写字符串:", upper)

	// 字符串截断
	truncated := xstring.Substring("hello world", 0, 5)
	fmt.Println("截断字符串:", truncated)

	// 字符串填充
	padded := xstring.PadLeft("123", "0", 5)
	fmt.Println("左填充:", padded)
}
```

### 4. xslice - 切片操作工具

提供常用的切片操作功能，包括切片去重、查找、删除、合并等。

#### 主要功能

- 切片去重
- 切片查找
- 切片删除
- 切片合并
- 切片反转
- 切片排序

#### 使用示例

```go
package main

import (
	"fmt"
	"gitee.com/liangzero/xutils/xslice"
)

func main() {
	// 切片去重
	slice := []int{1, 2, 3, 2, 4, 1}
	unique := xslice.Unique(slice)
	fmt.Println("去重后:", unique)

	// 切片查找
	index := xslice.IndexOf(slice, 3)
	fmt.Println("元素3的索引:", index)

	// 切片删除
	removed := xslice.Remove(slice, 2)
	fmt.Println("删除索引2后:", removed)

	// 切片合并
	slice1 := []int{1, 2, 3}
	slice2 := []int{4, 5, 6}
	merged := xslice.Merge(slice1, slice2)
	fmt.Println("合并后:", merged)
}
```

### 5. xdate - 日期时间处理工具

提供常用的日期时间处理功能，包括日期时间格式化、解析、计算等。

#### 主要功能

- 日期时间格式化
- 日期时间解析
- 日期时间比较
- 日期时间计算（加减天数、小时等）
- 时间戳转换

#### 使用示例

```go
package main

import (
	"fmt"
	"time"
	"gitee.com/liangzero/xutils/xdate"
)

func main() {
	// 获取当前时间
	now := xdate.Now()
	fmt.Println("当前时间:", now)

	// 格式化时间
	formatted := xdate.Format(now, xdate.LayoutDateTime)
	fmt.Println("格式化时间:", formatted)

	// 解析时间字符串
	dateStr := "2023-01-01 12:00:00"
	parsed, _ := xdate.Parse(xdate.LayoutDateTime, dateStr)
	fmt.Println("解析时间:", parsed)

	// 计算时间差
	later := xdate.AddDays(now, 1)
	diff := xdate.DiffDays(now, later)
	fmt.Println("时间差:", diff, "天")
}
```

### 6. xlog - 日志工具

提供灵活的日志记录功能，支持多级别日志、文件日志、控制台日志等。

#### 主要功能

- 多级别日志（DEBUG、INFO、WARN、ERROR、FATAL）
- 控制台和文件日志输出
- 日志格式化
- 日志文件滚动
- 日志级别控制

#### 使用示例

```go
package main

import (
	"gitee.com/liangzero/xutils/xlog"
)

func main() {
	// 初始化日志
	xlog.InitLog(xlog.LogConfig{
		ConsoleLevel: xlog.LevelInfo,
		FileLevel:    xlog.LevelDebug,
		FilePath:     "app.log",
		MaxSize:      10,
		MaxBackups:   5,
		MaxAge:       30,
	})

	// 记录日志
	xlog.Debug("调试信息")
	xlog.Info("普通信息")
	xlog.Warn("警告信息")
	xlog.Error("错误信息")
	xlog.Fatal("致命错误")
}
```

### 7. xcache - 缓存工具

提供缓存功能，支持本地缓存和 Redis 缓存，包含自动化缓存管理。

**注意：实际包名为 `di`，不是 `xcache`**

#### 主要功能

- 基本缓存操作（Get、Set、Del）
- 哈希缓存操作
- 列表缓存操作
- 集合缓存操作
- 分布式锁（基于 Redis）
- 自动化缓存管理

#### 使用示例

```go
package main

import (
	"fmt"
	"time"
	"gitee.com/liangzero/xutils/xcache"
)

func main() {
	// 设置缓存
	di.Set("key", "value", time.Hour)

	// 获取缓存
	value := di.Get("key")
	fmt.Println("缓存值:", value)

	// 哈希缓存操作
	di.PutMap("user:1001", "name", "张三", time.Hour)
	di.PutMap("user:1001", "age", "25", time.Hour)
	userMap := di.GetMap("user:1001")
	fmt.Println("用户信息:", userMap)

	// 使用分布式锁
	lock, _ := di.NewLock("lock:key")
	if lock != nil {
		defer di.UnLock(lock)
		// 执行临界区操作
	}
}
```

### 8. xvalidator - 数据验证工具

提供数据验证功能，支持结构体标签验证、自定义验证规则等。

#### 主要功能

- 结构体标签验证
- 常用验证规则（必填、长度、范围、格式等）
- 自定义验证器
- 验证错误处理

#### 使用示例

```go
package main

import (
	"fmt"
	"gitee.com/liangzero/xutils/xvalidator"
)

// 定义验证结构体
type User struct {
	Name    string `validate:"required,min=2,max=20"`
	Email   string `validate:"required,email"`
	Phone   string `validate:"required,phone"`
	Age     int    `validate:"required,min=18,max=100"`
	IDCard  string `validate:"idcard"`
	Website string `validate:"url"`
}

func main() {
	// 创建验证器
	validator := xvalidator.NewValidator()

	// 验证结构体
	user := User{
		Name:    "张三",
		Email:   "zhangsan@example.com",
		Phone:   "13812345678",
		Age:     25,
		IDCard:  "110101199001011234",
		Website: "https://example.com",
	}

	err := validator.Validate(user)
	if err != nil {
		fmt.Println("验证失败:", err)
	} else {
		fmt.Println("验证成功")
	}

	// 也可以使用全局验证函数
	err = xvalidator.Validate(user)
}
```

## 验证规则

xvalidator 支持以下验证规则：

| 规则       | 说明                          | 示例                            |
|----------|-----------------------------|-------------------------------|
| required | 必填字段                        | `validate:"required"`         |
| min      | 最小值或最小长度                    | `validate:"min=6"`            |
| max      | 最大值或最大长度                    | `validate:"max=20"`           |
| len      | 固定长度                        | `validate:"len=11"`           |
| email    | 邮箱格式                        | `validate:"email"`            |
| phone    | 手机号格式（中国大陆）                 | `validate:"phone"`            |
| idcard   | 身份证号格式（18位）                 | `validate:"idcard"`           |
| url      | URL格式                       | `validate:"url"`              |
| ipv4     | IPv4地址格式                    | `validate:"ipv4"`             |
| ipv6     | IPv6地址格式                    | `validate:"ipv6"`             |
| date     | 日期格式（YYYY-MM-DD）            | `validate:"date"`             |
| time     | 时间格式（HH:MM:SS）              | `validate:"time"`             |
| datetime | 日期时间格式（YYYY-MM-DD HH:MM:SS） | `validate:"datetime"`         |
| pattern  | 正则表达式模式                     | `validate:"pattern=^[a-z]+$"` |
| enum/in  | 值在列表中                       | `validate:"enum=男             |女"`  |
| notin    | 值不在列表中                      | `validate:"notin=admin        |root"` |
| gt       | 大于                          | `validate:"gt=18"`            |
| lt       | 小于                          | `validate:"lt=60"`            |
| gte      | 大于等于                        | `validate:"gte=0"`            |
| lte      | 小于等于                        | `validate:"lte=100"`          |

## 安装和使用

1. 克隆项目到本地

2. 在项目中导入所需的工具包

```go
import (
"gitee.com/liangzero/xutils/xcrypto"
"gitee.com/liangzero/xutils/xfile"
"gitee.com/liangzero/xutils/xstring"
"gitee.com/liangzero/xutils/xslice"
"gitee.com/liangzero/xutils/xdate"
"gitee.com/liangzero/xutils/xlog"
"gitee.com/liangzero/xutils/xcache"
"gitee.com/liangzero/xutils/xvalidator"
)
```

## 依赖管理

项目使用 Go Modules 进行依赖管理，主要依赖包括：

- github.com/bsm/redislock - Redis 分布式锁
- github.com/bytedance/sonic - JSON 序列化

## 在新项目中使用工具包

### 方法一：作为本地模块使用

如果你的新项目与 `utils` 工具包在同一台机器上，可以将其作为本地模块使用：

1. 在新项目的根目录创建 `go.mod` 文件（如果尚未创建）：

```bash
go mod init your-project-name
```

2. 添加本地工具包依赖：

```bash
go mod edit -replace utils=E:\RongJiProject\utils
go get utils
```

3. 在代码中导入并使用工具包：

```go
package main

import (
	"fmt"
	"gitee.com/liangzero/xutils/xcrypto"
	"gitee.com/liangzero/xutils/xdate"
	"gitee.com/liangzero/xutils/xfile"
)

func main() {
	// 使用 xcrypto 工具包
	md5 := xcrypto.MD5("hello world")
	fmt.Println("MD5:", md5)

	// 使用 xdate 工具包
	now := xdate.Now()
	fmt.Println("当前时间:", xdate.Format(now, xdate.LayoutDateTime))

	// 使用 xfile 工具包
	xfile.WriteFile("test.txt", "Hello from utils", false)
	fmt.Println("文件已创建")
}
```

### 方法二：通过 Gitee 远程仓库使用

1. 在新项目的根目录创建 `go.mod` 文件（如果尚未创建）：

```bash
go mod init your-project-name
```

2. 添加 Gitee 远程仓库依赖：

```bash
# 替换为你的实际 Gitee 仓库地址
go get gitee.com/your-username/utils
```

3. 在代码中导入并使用工具包：

```go
package main

import (
	"fmt"
	"gitee.com/your-username/utils/xcrypto"
	"gitee.com/your-username/utils/xdate"
	"gitee.com/your-username/utils/xfile"
)

func main() {
	// 使用 xcrypto 工具包
	md5 := xcrypto.MD5("hello world")
	fmt.Println("MD5:", md5)

	// 使用 xdate 工具包
	now := xdate.Now()
	fmt.Println("当前时间:", xdate.Format(now, xdate.LayoutDateTime))

	// 使用 xfile 工具包
	xfile.WriteFile("test.txt", "Hello from utils", false)
	fmt.Println("文件已创建")
}
```

### 方法三：通过 Go Modules 替换使用

如果需要同时管理本地开发和远程仓库，可以使用 Go Modules 的替换功能：

```bash
# 添加远程仓库依赖
go get gitee.com/your-username/utils

# 替换为本地路径以便开发
go mod edit -replace gitee.com/your-username/utils=E:\RongJiProject\utils
go mod tidy
```

### 导入不同的工具包

根据需要导入不同的工具包：

```go
// 加密解密工具
import "gitee.com/liangzero/xutils/xcrypto"

// 文件操作工具
import "gitee.com/liangzero/xutils/xfile"

// 字符串处理工具
import "gitee.com/liangzero/xutils/xstring"

// 切片操作工具
import "gitee.com/liangzero/xutils/xslice"

// 日期时间处理工具
import "gitee.com/liangzero/xutils/xdate"

// 日志工具
import "gitee.com/liangzero/xutils/xlog"

// 缓存工具
import "gitee.com/liangzero/xutils/xcache"

// 数据验证工具
import "gitee.com/liangzero/xutils/xvalidator"

// 类型转换工具
import "gitee.com/liangzero/xutils/xconv"

// 依赖注入工具
import "gitee.com/liangzero/xutils/xdi"

// 环境变量工具
import "gitee.com/liangzero/xutils/xenv"

// HTTP 工具
import "gitee.com/liangzero/xutils/xhttp"

// 线程池工具
import "gitee.com/liangzero/xutils/xpool"
```

### 使用示例

以下是一个综合使用多个工具包的示例：

```go
package main

import (
	"fmt"
	"gitee.com/liangzero/xutils/xcrypto"
	"gitee.com/liangzero/xutils/xdate"
	"gitee.com/liangzero/xutils/xfile"
	"gitee.com/liangzero/xutils/xlog"
	"gitee.com/liangzero/xutils/xvalidator"
)

type User struct {
	Name     string `validate:"required,min=2,max=20"`
	Email    string `validate:"required,email"`
	Password string `validate:"required,min=6"`
}

func main() {
	// 初始化日志
	xlog.InitLog(xlog.LogConfig{
		ConsoleLevel: xlog.LevelInfo,
		FileLevel:    xlog.LevelDebug,
		FilePath:     "app.log",
	})

	xlog.Info("应用程序启动")

	// 创建用户
	user := User{
		Name:     "张三",
		Email:    "zhangsan@example.com",
		Password: "123456",
	}

	// 验证用户信息
	if err := xvalidator.Validate(user); err != nil {
		xlog.Error("用户信息验证失败:", err)
		return
	}

	xlog.Info("用户信息验证成功")

	// 加密密码
	hashedPassword := xcrypto.SHA256(user.Password)
	fmt.Println("加密后的密码:", hashedPassword)

	// 记录当前时间
	now := xdate.Now()
	fmt.Println("当前时间:", xdate.Format(now, xdate.LayoutDateTime))

	// 写入用户信息到文件
	userInfo := fmt.Sprintf("用户: %s, 邮箱: %s, 注册时间: %s",
		user.Name, user.Email, xdate.Format(now, xdate.LayoutDateTime))

	if err := xfile.WriteFile("user_info.txt", userInfo, false); err != nil {
		xlog.Error("写入文件失败:", err)
		return
	}

	xlog.Info("用户信息已写入文件")

	// 读取文件内容
	content, err := xfile.ReadFile("user_info.txt")
	if err != nil {
		xlog.Error("读取文件失败:", err)
		return
	}

	fmt.Println("文件内容:", content)
	xlog.Info("应用程序执行完成")
}
```

git add .

git commit -m "Update to v1.1.7"

git tag v1.1.7

git push origin master

git push origin --tags

git ls-remote --tags origin