helper

package
v0.17.2 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 32 Imported by: 1

README

Helper 组件

Helper 组件提供丰富的工具函数,包括数据类型转换、字符串处理、文件操作、JSON处理、货币计算、SSH密钥管理等常用功能。

概述

Helper 组件是一个功能丰富的工具库,为 Go 开发提供各种常用功能的封装。组件采用模块化设计,包含多个专门的功能模块,每个模块都提供简单易用的 API 接口。

功能特性

  • 数据类型转换:支持各种数据类型之间的安全转换
  • 字符串处理:提供丰富的字符串操作功能,支持多字节字符
  • JSON处理:强大的 JSON 序列化和反序列化功能
  • 文件操作:文件路径处理、文件状态检查等实用功能
  • 货币计算:精确的货币计算,支持加减乘除等操作
  • SSH密钥管理:SSH 密钥的生成和获取
  • 数组和Map操作:提供数组和 Map 的常用操作方法
  • 工具函数:各种实用工具函数

快速开始

安装
go get github.com/jcbowen/jcbaseGo/component/helper
基本使用示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 数据类型转换示例
    convert := helper.Convert{Value: "123"}
    number := convert.ToInt()
    fmt.Printf("字符串转数字: %d\n", number)

    // 字符串处理示例
    str := helper.NewStr("hello world")
    upper := str.ToUpper()
    fmt.Printf("字符串转大写: %s\n", upper)

    // JSON处理示例
    jsonStr := `{"name":"张三","age":25}`
    jsonHelper := helper.Json(jsonStr)
    var data map[string]interface{}
    jsonHelper.ToStruct(&data)
    fmt.Printf("JSON解析结果: %+v\n", data)

    // 货币计算示例
    money := helper.Money("100.50")
    fmt.Printf("货币金额: %s\n", money.FloatString("¥", "元"))
}
数据类型转换示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 字符串转数字
    convert := helper.Convert{Value: "123.45"}
    fmt.Printf("字符串转int: %d\n", convert.ToInt())
    fmt.Printf("字符串转float64: %.2f\n", convert.ToFloat64())

    // 数字转字符串
    convert = helper.Convert{Value: 123.45}
    fmt.Printf("数字转字符串: %s\n", convert.ToString())

    // 布尔值转换
    convert = helper.Convert{Value: "true"}
    fmt.Printf("字符串转bool: %t\n", convert.ToBool())

    // 文件权限转换
    convert = helper.Convert{Value: "0644"}
    fmt.Printf("字符串转FileMode: %o\n", convert.ToFileMode())
}
字符串处理示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 创建字符串对象
    str := helper.NewStr("Hello World 你好世界")

    // 基本操作
    fmt.Printf("原始字符串: %s\n", str.String)
    fmt.Printf("转大写: %s\n", str.ToUpper())
    fmt.Printf("转小写: %s\n", str.ToLower())
    fmt.Printf("字节长度: %d\n", str.ByteLength())

    // 子字符串操作
    fmt.Printf("截取前5个字符: %s\n", str.ByteSubstr(0, 5))
    fmt.Printf("截断为10个字符: %s\n", str.Truncate(10, "..."))

    // 字符串检查
    fmt.Printf("是否以Hello开头: %t\n", str.StartsWith("Hello", true))
    fmt.Printf("是否以世界结尾: %t\n", str.EndsWith("世界", true))

    // 分割字符串
    parts := str.Explode(" ", true, false)
    fmt.Printf("按空格分割: %v\n", parts)

    // 单词统计
    fmt.Printf("单词数量: %d\n", str.CountWords())

    // Base64编码
    encoded := str.Base64UrlEncode()
    fmt.Printf("Base64编码: %s\n", encoded)
    
    decoded, _ := helper.NewStr(encoded).Base64UrlDecode()
    fmt.Printf("Base64解码: %s\n", decoded)

    // HTML转义
    htmlStr := helper.NewStr(`<script>alert("xss")</script>`)
    fmt.Printf("HTML转义: %s\n", htmlStr.EscapeHTML())

    // 驼峰转下划线
    camelStr := helper.NewStr("helloWorldTest")
    fmt.Printf("驼峰转下划线: %s\n", camelStr.ConvertCamelToSnake())
}
JSON处理示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    // 从字符串解析JSON
    jsonStr := `{"name":"张三","age":25}`
    jsonHelper := helper.Json(jsonStr)
    
    var user User
    jsonHelper.ToStruct(&user)
    fmt.Printf("解析结果: %+v\n", user)

    // 从结构体生成JSON
    newUser := User{Name: "李四", Age: 30}
    jsonHelper = helper.Json(newUser)
    var jsonString string
    jsonHelper.ToString(&jsonString)
    fmt.Printf("生成的JSON: %s\n", jsonString)

    // 从Map生成JSON
    data := map[string]interface{}{
        "name": "王五",
        "age":  35,
        "tags": []string{"go", "programming"},
    }
    jsonHelper = helper.Json(data)
    jsonHelper.ToString(&jsonString)
    fmt.Printf("Map生成的JSON: %s\n", jsonString)

    // 从文件读取JSON
    // jsonHelper = helper.JsonFile("config.json")
    // var config map[string]interface{}
    // jsonHelper.ToStruct(&config)
    // fmt.Printf("配置文件: %+v\n", config)

    // 生成JSON文件
    // jsonHelper.MakeFile("output.json").ToString(&jsonString)
}
文件操作示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 创建文件对象
    file := helper.NewFile(&helper.File{Path: "/path/to/file.txt"})

    // 文件状态检查
    fmt.Printf("文件是否存在: %t\n", file.Exists())
    fmt.Printf("是否是目录: %t\n", file.IsDir())
    fmt.Printf("是否是文件: %t\n", file.IsFile())
    fmt.Printf("是否为空: %t\n", file.IsEmpty())
    fmt.Printf("是否可读: %t\n", file.IsReadable())
    fmt.Printf("是否可写: %t\n", file.IsWritable())

    // 路径操作
    absPath, _ := file.GetAbsPath()
    fmt.Printf("绝对路径: %s\n", absPath)
    fmt.Printf("文件名: %s\n", file.Basename(".txt"))
    fmt.Printf("目录名: %s\n", file.DirName())

    // 目录操作
    dir := helper.NewFile(&helper.File{Path: "/path/to/directory"})
    exists, err := dir.DirExists(true)
    if err != nil {
        fmt.Printf("目录操作错误: %v\n", err)
    } else {
        fmt.Printf("目录存在或已创建: %t\n", exists)
    }
}
货币计算示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 创建货币对象
    money1 := helper.Money("100.50")  // 100.50元
    money2 := helper.Money(50.25)     // 50.25元

    // 基本操作
    fmt.Printf("金额1: %s\n", money1.FloatString("¥", ""))
    fmt.Printf("金额2: %s\n", money2.FloatString("¥", ""))

    // 加法
    result := money1.Add(money2)
    fmt.Printf("加法结果: %s\n", result.FloatString("¥", ""))

    // 减法
    result = money1.Subtract(helper.Money("20.00"))
    fmt.Printf("减法结果: %s\n", result.FloatString("¥", ""))

    // 乘法
    result = money1.Multiply(1.1) // 增加10%
    fmt.Printf("乘法结果: %s\n", result.FloatString("¥", ""))

    // 除法
    result = money1.Divide(2) // 除以2
    fmt.Printf("除法结果: %s\n", result.FloatString("¥", ""))

    // 比较操作
    fmt.Printf("金额1 > 金额2: %t\n", money1.GreaterThan(money2))
    fmt.Printf("金额1 < 金额2: %t\n", money1.LessThan(money2))
    fmt.Printf("金额1 == 金额2: %t\n", money1.Equals(money2))

    // 错误处理
    money3 := helper.Money("invalid")
    if err := money3.GetError(); err != nil {
        fmt.Printf("错误信息: %v\n", err)
    }
}
SSH密钥管理示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 获取SSH公钥
    pubKey, err := helper.GetSSHKey()
    if err != nil {
        fmt.Printf("获取SSH密钥错误: %v\n", err)
        
        // 生成新的SSH密钥
        if err := helper.GenerateSSHKey(); err != nil {
            fmt.Printf("生成SSH密钥错误: %v\n", err)
        } else {
            fmt.Println("SSH密钥生成成功")
            
            // 重新获取公钥
            pubKey, err = helper.GetSSHKey()
            if err != nil {
                fmt.Printf("重新获取SSH密钥错误: %v\n", err)
            }
        }
    }

    if pubKey != "" {
        fmt.Printf("SSH公钥: %s\n", pubKey)
    }
}
数组和Map操作示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 数组操作
    arr := []string{"apple", "banana", "orange", "grape"}
    arrHelper := helper.SetArrStr(arr).DoSort()
    
    fmt.Printf("原始数组: %v\n", arr)
    fmt.Printf("排序后数组: %v\n", arrHelper.ArrayValue())
    
    // 数组差异
    otherArr := []string{"banana", "grape", "pear"}
    diff := arrHelper.ArrayDiff(otherArr)
    fmt.Printf("数组差异: %v\n", diff)
    
    // 数组交集
    intersect := arrHelper.ArrayIntersect(otherArr)
    fmt.Printf("数组交集: %v\n", intersect)

    // Map操作
    data := map[string]interface{}{
        "name": "张三",
        "age":  25,
        "city": "北京",
    }
    mapHelper := helper.NewMap(data).DoSort()
    
    fmt.Printf("原始Map: %+v\n", data)
    fmt.Printf("排序后Map: %+v\n", mapHelper.GetData())
    fmt.Printf("Map键: %v\n", mapHelper.ArrayKeys())
    fmt.Printf("Map值: %v\n", mapHelper.ArrayValues())
}
HTTP处理功能

提供HTTP请求和响应处理的实用功能:

  • 头信息提取: 从HTTP请求中提取和解析头信息
  • 主机信息获取: 获取请求的主机名、端口和协议信息
  • URL编码: 对URL参数进行编码和解码
  • 头信息格式化: 将头信息格式化为标准格式
核心函数说明

ExtractHeaders(headers map[string][]string) map[string]string

  • 从HTTP头信息中提取单个值,处理多值情况
  • 返回简化的键值对映射

GetHostInfo(host string) (string, string, string)

  • 解析主机字符串,返回主机名、端口和协议
  • 支持带端口和协议的主机格式

FormatHeaders(headers map[string]string) string

  • 将头信息格式化为标准HTTP头格式
  • 每个头信息单独一行,格式为"Key: Value"

URLEncodeParams(params map[string]string) string

  • 对URL参数进行编码,生成查询字符串
  • 自动处理特殊字符编码

URLDecodeParams(query string) (map[string]string, error)

  • 解码URL查询字符串,返回参数映射
  • 处理URL编码的特殊字符
IP地址处理功能

提供IP地址验证和处理的实用功能:

  • IP地址验证: 验证IP地址格式的有效性
  • 地址类型判断: 判断IP地址是否为回环地址、私有地址等
  • CIDR范围检查: 检查IP地址是否在指定CIDR范围内
核心函数说明

IsValid(ip string) bool

  • 验证IP地址格式是否有效
  • 支持IPv4和IPv6地址格式

IsLoopback(ip string) bool

  • 判断IP地址是否为回环地址
  • IPv4: 127.0.0.0/8, IPv6: ::1

IsPrivate(ip string) bool

  • 判断IP地址是否为私有地址
  • 包括局域网、私有网络等地址范围

IsInCIDR(ip, cidr string) bool

  • 检查IP地址是否在指定CIDR范围内
  • 支持IPv4和IPv6的CIDR表示法
工具函数示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 字符串替换
    result, err := helper.StrReplace("world", "Go", "hello world", -1)
    if err != nil {
        fmt.Printf("字符串替换错误: %v\n", err)
    } else {
        fmt.Printf("字符串替换结果: %s\n", result)
    }

    // 检查字符串开头和结尾
    str := "hello world"
    fmt.Printf("是否以hello开头: %t\n", helper.StringStartWith(str, "hello"))
    fmt.Printf("是否以world结尾: %t\n", helper.StringEndWith(str, "world"))

    // 检查元素是否在数组中
    arr := []string{"apple", "banana", "orange"}
    fmt.Printf("apple是否在数组中: %t\n", helper.InArray("apple", arr))
    fmt.Printf("grape是否在数组中: %t\n", helper.InArray("grape", arr))

    // 通配符匹配
    pattern := "*.go"
    filename := "main.go"
    fmt.Printf("文件名 %s 是否匹配模式 %s: %t\n", 
        filename, pattern, helper.MatchWildcard(pattern, filename, false))
}

详细功能说明

Convert 类型转换模块

提供安全的数据类型转换功能:

  • ToString(): 将任意类型转换为字符串
  • ToInt(): 转换为 int 类型
  • ToInt8(): 转换为 int8 类型
  • ToInt64(): 转换为 int64 类型
  • ToUint(): 转换为 uint 类型
  • ToUint64(): 转换为 uint64 类型
  • ToFloat64(): 转换为 float64 类型
  • ToBool(): 转换为 bool 类型
  • ToFileMode(): 转换为文件权限类型
  • ToArrByte(): 转换为字节数组
  • ToNumber(): 转换为数值类型(自动判断 int 或 float64)
  • ToTime(): 转换为 time.Time 类型
  • ToMap(): 转换为 map[string]interface{}
  • ToMapString(): 转换为 map[string]string
  • ToSlice(): 转换为 []interface{}
  • ToDuration(): 转换为 time.Duration 类型
  • ToInterface(): 返回原始接口值
Str 字符串处理模块

提供丰富的字符串操作功能:

  • 字节操作: ByteLength(), ByteSubstr()
  • 字符串截断: Truncate(), TruncateWords()
  • 字符串检查: StartsWith(), EndsWith(), Contains(), IsNumeric()
  • 字符串分割: Explode(), CountWords()
  • 编码解码: Base64UrlEncode(), Base64UrlDecode()
  • 格式转换: ToUpper(), ToLower(), ConvertCamelToSnake(), ConvertSnakeToCamel(), MbUcFirst(), MbUcWords()
  • 安全处理: EscapeHTML(), TrimSpace(), Trim()
  • 数值处理: SetFloat64(), FloatToString(), ParseUnit(), ToUnitValue(), IsUnitString(), GetUnitTypeFromString(), FormatAsUnit(), ConvertBetweenUnits()
核心函数说明

*NewStr(s string) Str

  • 创建新的字符串对象
  • 初始化字符串内容和状态

ByteLength() int

  • 获取字符串的字节长度
  • 与字符长度不同,考虑多字节字符

ByteSubstr(start, length int) string

  • 按字节位置截取子字符串
  • 支持负数的起始位置和长度

Truncate(maxLength int, suffix string) string

  • 截断字符串到指定长度
  • 可选添加后缀表示截断

TruncateWords(maxWords int, suffix string) string

  • 按单词数量截断字符串
  • 保留完整的单词边界

StartsWith(prefix string, caseSensitive bool) bool

  • 检查字符串是否以指定前缀开头
  • caseSensitive: 是否区分大小写

EndsWith(suffix string, caseSensitive bool) bool

  • 检查字符串是否以指定后缀结尾
  • caseSensitive: 是否区分大小写

Explode(delimiter string, trimSpace, removeEmpty bool) []string

  • 按分隔符分割字符串
  • trimSpace: 是否去除空白字符
  • removeEmpty: 是否移除空元素

CountWords() int

  • 统计字符串中的单词数量
  • 基于空白字符分割单词

Base64UrlEncode() string

  • 对字符串进行Base64 URL安全编码
  • 替换特殊字符,适合URL传输

Base64UrlDecode() (string, error)

  • 对Base64 URL编码的字符串进行解码
  • 处理URL安全的Base64编码

EscapeHTML() string

  • 对HTML特殊字符进行转义
  • 防止XSS攻击

TrimSpace() string

  • 去除字符串两端的空白字符
  • 包括空格、制表符、换行符等

ConvertCamelToSnake() string

  • 将驼峰命名转换为下划线命名
  • 处理大小写转换和分隔符添加
JsonHelper JSON处理模块

强大的 JSON 序列化和反序列化功能:

  • 多数据源支持: 字符串、结构体、Map、文件
  • 链式操作: 支持方法链式调用
  • 文件操作: 支持 JSON 文件的读取和生成
  • 错误处理: 完善的错误处理机制
核心函数说明

*Json(data interface{}) JsonHelper

  • 创建JSON处理对象,支持多种数据源
  • data: 可以是字符串、结构体、Map等

*JsonFile(filename string) JsonHelper

  • 从JSON文件创建处理对象
  • 自动读取文件内容并解析

ToStruct(target interface{}) error

  • 将JSON数据解析到目标结构体
  • 支持结构体标签映射

*ToString(target string) error

  • 将JSON数据转换为字符串
  • 支持格式化输出

*MakeFile(filename string) JsonHelper

  • 设置输出文件名,用于生成JSON文件
  • 配合ToString方法使用

GetError() error

  • 获取处理过程中的错误信息
  • 返回最后一次操作的错误
File 文件操作模块

文件路径和状态操作:

  • 文件状态: Exists(), IsDir(), IsFile(), IsEmpty(), IsEmptyDir(), IsEmptyFile()
  • 权限检查: IsReadable(), IsWritable(), IsExecutable()
  • 路径操作: GetAbsPath(), Basename(), DirName()
  • 目录管理: DirExists()
核心函数说明

**NewFile(file File) File

  • 创建新的文件对象实例
  • 初始化文件路径和状态信息

Exists() bool

  • 检查文件或目录是否存在
  • 返回布尔值表示存在状态

IsDir() bool

  • 判断路径是否为目录
  • 如果路径不存在或不是目录返回false

IsFile() bool

  • 判断路径是否为普通文件
  • 排除目录、符号链接等特殊文件类型

IsEmpty() bool

  • 检查文件是否为空
  • 对于目录,检查是否包含文件或子目录

IsEmptyDir() bool

  • 检查目录是否为空
  • 路径不存在、不是目录或无权限读取时返回 false

IsReadable() bool

  • 检查文件是否可读
  • 验证当前用户对文件的读取权限

IsWritable() bool

  • 检查文件是否可写
  • 验证当前用户对文件的写入权限

IsExecutable() bool

  • 检查文件是否可执行,目录与不存在的路径返回 false
  • Unix/macOS 检查权限位的可执行位(0111)
  • Windows 文件系统不表达 Unix 权限位,改为按扩展名判定(.exe/.bat/.cmd/.com)

GetAbsPath() (string, error)

  • 获取文件的绝对路径
  • 解析相对路径和符号链接

Basename(suffix string) string

  • 获取文件的基本名称
  • 可选去除指定后缀

DirName() string

  • 获取文件所在目录的路径
  • 返回父目录的路径字符串

DirExists(createIfNotExist bool) (bool, error)

  • 检查目录是否存在,可选自动创建
  • createIfNotExist: 如果目录不存在是否自动创建
MoneyHelper 货币计算模块

精确的货币计算功能:

  • 多种输入格式: 字符串、数字
  • 数学运算: Add(), Subtract(), Multiply(), Divide()
  • 比较操作: GreaterThan(), LessThan(), Equals()
  • 格式化输出: FloatString()
  • 错误处理: GetError()
SSH 密钥管理

SSH 密钥的生成和获取:

  • 密钥获取: GetSSHKey()
  • 密钥生成: GenerateSSHKey()
  • 自动创建: 密钥不存在时自动生成
数组和Map操作

提供数组和 Map 的常用操作方法:

  • 数组操作: ArrayValue(), ArrayDiff(), ArrayIntersect()
  • Map操作: ArrayKeys(), ArrayValues(), GetData()
  • 排序支持: DoSort()
  • 字段提取: Extract(), ExtractString(), ExtractWithDefault(), ExtractInt(), ExtractInt64(), ExtractFloat64(), ExtractBool(), ExtractTime(), ExtractStringSlice()
Map字段提取功能

提供多级Map字段提取功能,支持点号分隔的路径访问:

  • ExtractString(): 从多级map中提取字符串字段值
  • Extract(): 从多级map中提取任意类型的字段值
  • ExtractWithDefault(): 从多级map中提取字段值,支持默认值
核心函数说明

*NewMap(data map[string]interface{}) MapHelper

  • 创建MapHelper对象
  • 初始化Map数据

*DoSort() MapHelper

  • 对Map数据进行排序
  • 返回排序后的MapHelper对象

GetData() map[string]interface{}

  • 获取原始的Map数据
  • 返回当前存储的数据

ArrayKeys() []string

  • 获取Map的所有键
  • 返回键的字符串切片

ArrayValues() []interface{}

  • 获取Map的所有值
  • 返回值的接口切片

ExtractString(path string) string

  • 从多级Map中提取字符串值
  • 支持点号分隔的路径访问
  • 如果路径不存在返回空字符串

Extract(path string) interface{}

  • 从多级Map中提取任意类型的值
  • 支持点号分隔的路径访问
  • 返回原始值或nil

ExtractWithDefault(path string, defaultValue interface{}) interface{}

  • 从多级Map中提取值,支持默认值
  • 如果路径不存在返回指定的默认值
使用示例
package main

import (
	"fmt"
	"github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
	// 创建多层嵌套的Map数据
	data := map[string]interface{}{
		"api": map[string]interface{}{
			"response": map[string]interface{}{
				"status": "success",
				"code":   200,
				"data": map[string]interface{}{
					"user": map[string]interface{}{
						"id":       123,
						"username": "john_doe",
						"profile": map[string]interface{}{
							"name":  "John Doe",
							"email": "john@example.com",
						},
					},
				},
			},
		},
	}

	mapHelper := helper.NewMap(data)

	// 使用 ExtractString 提取字符串值
	username := mapHelper.ExtractString("api.response.data.user.username")
	fmt.Printf("用户名: %s\n", username) // 输出: john_doe

	// 使用 Extract 提取原始值
	userID := mapHelper.Extract("api.response.data.user.id")
	fmt.Printf("用户ID: %v\n", userID) // 输出: 123

	// 使用 ExtractWithDefault 处理可能不存在的字段
	avatar := mapHelper.ExtractWithDefault("api.response.data.user.avatar", "default.png")
	fmt.Printf("头像: %v\n", avatar) // 输出: default.png

	// 处理多层嵌套
	email := mapHelper.ExtractString("api.response.data.user.profile.email")
	fmt.Printf("邮箱: %s\n", email) // 输出: john@example.com

	// 处理不存在的路径
	nonexistent := mapHelper.ExtractString("api.response.data.user.nonexistent")
	fmt.Printf("不存在的字段: '%s'\n", nonexistent) // 输出: ''
}
功能特点
  • 路径支持: 使用点号分隔的多级路径访问
  • 类型安全: 自动处理类型转换和边界情况
  • 默认值: 支持自定义默认值处理
  • 链式调用: 与现有 MapHelper 方法兼容
单位转换功能

提供强大的单位转换功能,支持存储单位、时间单位和数据单位之间的转换:

  • 存储单位转换: 字节(Byte)、千字节(KB)、兆字节(MB)、吉字节(GB)、太字节(TB)、拍字节(PB)
  • 时间单位转换: 纳秒(ns)、微秒(μs)、毫秒(ms)、秒(s)、分钟(min)、小时(h)、天(d)
  • 数据单位转换: 比特(b)、字节(byte)、千比特(Kb)、千字节(Kbyte)、兆比特(Mb)、兆字节(Mbyte)、吉比特(Gb)、吉字节(Gbyte)
  • 智能解析: 支持多种单位符号格式,自动识别单位类型
  • 精确计算: 基于单位换算因子进行精确转换
核心函数说明

ParseUnitString(value string, unitType int) (float64, Unit, error)

  • 解析包含数值和单位的字符串,返回数值和单位信息
  • unitType: 指定解析的单位类型(UnitTypeStorage/UnitTypeTime/UnitTypeData)

ConvertUnit(value float64, fromUnit, toUnit string, unitType int) (float64, error)

  • 在不同单位之间进行数值转换
  • 支持存储、时间、数据三种单位类型的转换

FormatUnit(value interface{}, unitType UnitType, precision int, toUnit ...string) (string, error)

  • 将数值格式化为人类可读的单位字符串
  • value: 支持数值或带单位的字符串
  • unitType: 指定单位类型(UnitTypeStorage/UnitTypeTime/UnitTypeData)
  • precision: 指定小数位数精度
  • toUnit: 输出格式("auto"自动选择单位或具体单位符号)

GetAvailableUnits(unitType int) []string

  • 获取指定单位类型下所有可用的单位符号列表

IsValidUnit(unit string, unitType int) bool

  • 检查指定单位符号在给定单位类型下是否有效
使用示例
package main

import (
	"fmt"
	"github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
	// 存储单位转换示例
	fmt.Println("=== 存储单位转换 ===")
	result, err := helper.ConvertUnit(1024, "B", "KB", helper.UnitTypeStorage)
	if err != nil {
		fmt.Printf("转换错误: %v\n", err)
	} else {
		fmt.Printf("1024 B = %.2f KB\n", result) // 输出: 1024 B = 1.00 KB
	}

	// 时间单位转换示例
	fmt.Println("\n=== 时间单位转换 ===")
	result, err = helper.ConvertUnit(3600, "s", "h", helper.UnitTypeTime)
	if err != nil {
		fmt.Printf("转换错误: %v\n", err)
	} else {
		fmt.Printf("3600 s = %.2f h\n", result) // 输出: 3600 s = 1.00 h
	}

	// 数据单位转换示例
	fmt.Println("\n=== 数据单位转换 ===")
	result, err = helper.ConvertUnit(8, "b", "byte", helper.UnitTypeData)
	if err != nil {
		fmt.Printf("转换错误: %v\n", err)
	} else {
		fmt.Printf("8 b = %.2f byte\n", result) // 输出: 8 b = 1.00 byte
	}

	// 单位字符串解析示例
	fmt.Println("\n=== 单位字符串解析 ===")
	value, unit, err := helper.ParseUnitString("1MB", helper.UnitTypeStorage)
	if err != nil {
		fmt.Printf("解析错误: %v\n", err)
	} else {
		fmt.Printf("解析结果: 值=%.0f, 单位=%s (类型: %d)\n", value, unit.Name, unit.Type)
	}

	// 格式化单位值示例
	fmt.Println("\n=== 格式化单位值 ===")
	formatted := helper.FormatUnit(1500000, helper.UnitTypeStorage, 2)
	fmt.Printf("格式化结果: %s\n", formatted) // 输出: 1.43 MB

	// 获取可用单位列表
	fmt.Println("\n=== 可用单位列表 ===")
	storageUnits := helper.GetAvailableUnits(helper.UnitTypeStorage)
	timeUnits := helper.GetAvailableUnits(helper.UnitTypeTime)
	dataUnits := helper.GetAvailableUnits(helper.UnitTypeData)
	
	fmt.Printf("存储单位: %v\n", storageUnits)
	fmt.Printf("时间单位: %v\n", timeUnits)
	fmt.Printf("数据单位: %v\n", dataUnits)

	// 人类可读格式示例
	fmt.Println("\n=== 人类可读格式 ===")
	
	

}
功能特点
  • 多类型支持: 支持存储、时间、数据三种单位类型
  • 符号兼容: 支持多种单位符号格式(如B、byte、bytes等)
  • 精确转换: 基于精确的换算因子进行计算
  • 错误处理: 完善的错误处理机制
  • 格式化输出: 支持自定义精度和格式化
  • 智能解析: 自动识别和解析单位字符串
  • 单位类型参数: 支持指定解析的单位类型,解决符号冲突问题
单位类型参数使用示例

当单位符号存在冲突时(如"byte"同时存在于存储单位和数据单位),可以使用单位类型参数明确指定解析类型:

package main

import (
	"fmt"
	"github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
	// 默认情况下,"byte"被解析为存储单位
	fmt.Println("=== 默认解析 ===")
	_, unitInfo, err := helper.ParseUnitString("8byte", helper.UnitTypeStorage)
	if err != nil {
		fmt.Printf("解析错误: %v\n", err)
	} else {
		fmt.Printf("默认解析: 8byte -> 类型: %v\n", unitInfo.UnitType)
	}

	// 使用单位类型参数指定解析为数据单位
	fmt.Println("\n=== 指定单位类型 ===")
	_, unitInfo, err = helper.ParseUnitString("8byte", helper.UnitTypeData)
	if err != nil {
		fmt.Printf("解析错误: %v\n", err)
	} else {
		fmt.Printf("指定类型解析: 8byte -> 类型: %v\n", unitInfo.UnitType)
	}

	// 单位转换时使用单位类型参数
	fmt.Println("\n=== 单位转换类型参数 ===")
	
	// 默认情况下,b和byte类型不同,转换会失败
	result, err := helper.ConvertUnit(8, "b", "byte", helper.UnitTypeStorage)
	if err != nil {
		fmt.Printf("默认转换失败: %v\n", err)
	} else {
		fmt.Printf("默认转换成功: 8b = %.2f byte\n", result)
	}

	// 指定单位类型为数据单位,转换成功
	result, err = helper.ConvertUnit(8, "b", "byte", helper.UnitTypeData)
	if err != nil {
		fmt.Printf("指定类型转换失败: %v\n", err)
	} else {
		fmt.Printf("指定类型转换成功: 8b = %.2f byte\n", result)
	}

	// 其他函数也支持单位类型参数
	fmt.Println("\n=== 其他函数类型参数 ===")
	
	// 单位有效性检查
	isValid := helper.IsValidUnit("byte", helper.UnitTypeData)
	fmt.Printf("byte作为数据单位是否有效: %t\n", isValid)

	// 获取单位类型
	unitType, err := helper.GetUnitType("byte", helper.UnitTypeData)
	if err != nil {
		fmt.Printf("获取类型错误: %v\n", err)
	} else {
		fmt.Printf("byte作为数据单位的类型: %v\n", unitType)
	}
}
单位类型参数说明
  • UnitTypeStorage: 存储单位类型(默认)
  • UnitTypeTime: 时间单位类型
  • UnitTypeData: 数据单位类型

当单位符号存在歧义时,系统会匹配指定类型的单位。如果没有指定单位类型,则按照存储单位→时间单位→数据单位的顺序进行匹配。

支持的单位符号

存储单位:

  • Byte: B, bytes
  • Kilobyte: KB, K, kilobyte, kilobytes
  • Megabyte: MB, M, megabyte, megabytes
  • Gigabyte: GB, G, gigabyte, gigabytes
  • Terabyte: TB, T, terabyte, terabytes
  • Petabyte: PB, P, petabyte, petabytes

时间单位:

  • Nanosecond: ns, nanosecond, nanoseconds
  • Microsecond: μs, us, microsecond, microseconds
  • Millisecond: ms, millisecond, milliseconds
  • Second: s, sec, second, seconds
  • Minute: m, min, minute, minutes
  • Hour: h, hr, hour, hours
  • Day: d, day, days

数据单位:

  • Bit: b, bit, bits
  • Byte: byte, bytes
  • Kilobit: Kb, Kbit, kilobit, kilobits
  • Kilobyte: Kbyte, kilobyte, kilobytes
  • Megabit: Mb, Mbit, megabit, megabits
  • Megabyte: Mbyte, megabyte, megabytes
  • Gigabit: Gb, Gbit, gigabit, gigabits
  • Gigabyte: Gbyte, gigabyte, gigabytes

结构体默认值填充(CheckAndSetDefault)

CheckAndSetDefault 依据结构体字段上的 default 标签为零值字段填充默认值,适用于配置初始化的场景。

type SubConfig struct {
    Host    string        `json:"host" default:"127.0.0.1"`
    Port    int           `json:"port" default:"3306"`
    Timeout time.Duration `json:"timeout" default:"500ms"`
}

type AppConfig struct {
    Name     string                   `json:"name" default:"myapp"`
    Enabled  bool                     `json:"enabled" default:"true"`
    Port     int                      `json:"port" default:"8080"`
    Timeout  time.Duration            `json:"timeout" default:"300ms"`
    StartAt  time.Time                `json:"start_at" default:"2024-01-01 00:00:00"`
    // map 值为结构体时,每个元素都会被递归补充默认值
    Clusters map[string]SubConfig     `json:"clusters"`
    Shards   map[string]*SubConfig    `json:"shards"`
    Inner    *SubConfig               `json:"inner"`
    // 切片元素为结构体时,每个元素都会被递归补充默认值
    Nodes    []SubConfig              `json:"nodes"`
    NodePtrs []*SubConfig             `json:"node_ptrs"`
    Any      interface{}              `json:"any"`
}

cfg := &AppConfig{Clusters: map[string]SubConfig{"main": {}}, Inner: &SubConfig{}, Nodes: []SubConfig{{}}}
_ = helper.CheckAndSetDefault(cfg)
// cfg.Clusters["main"] => SubConfig{Host: "127.0.0.1", Port: 3306, Timeout: 500ms}
// cfg.Inner           => &SubConfig{Host: "127.0.0.1", Port: 3306, Timeout: 500ms}
// cfg.Nodes[0]        => SubConfig{Host: "127.0.0.1", Port: 3306, Timeout: 500ms}
// cfg.StartAt         => 2024-01-01 00:00:00

支持的递归场景:

字段类型 处理方式
结构体字段 命中「配置结构体」判定(含 default 标签)时递归调用,字段内的默认值一并补充;未命中判定的类型(http.Request、sync.Mutex、atomic.Value、url.URL 等)整体跳过
结构体指针字段 *SubConfig 非 nil 时递归补充;nil 指针保持原样,不自动实例化
interface{} 字段 解引用装载的实际值后分派:结构体、结构体指针、map、切片均递归补充;nil interface 不处理
time.Time 字段 按 default 标签填充(支持多种时间字符串与时间戳);仅零值时填充,解析失败静默跳过
map[string]SubConfig 元素拷贝到新实例后递归补充,再写回 map
map[string]*SubConfig 非 nil 指针就地递归补充;nil 指针保持原样
map[string]interface{} 运行期为结构体或结构体指针时同样递归补充
map[string]map[string]SubConfig 逐层向内递归补充
map[string][]SubConfig 逐层向内递归补充(map → 切片 → 元素)
[]SubConfig 元素拷贝到新实例后递归补充,再 Set 写回该下标
[]*SubConfig 非 nil 指针就地递归补充;nil 指针保持原样,不自动实例化
[]interface{} 逐元素解引用后按实际类型分派(结构体 / 结构体指针 / 映射 / 切片)
[][]SubConfig 嵌套切片逐层向内递归补充
map[string]string / map[string]int 等基础值 保持原逻辑,仅按 default 标签整体填充
[]string / []int 等基础元素切片 保持原逻辑,不逐元素改写(仅空切片按 default 标签整体填充)
map[string]time.Time / []time.Time / map[string]sync.Mutex / []sync.Mutex 等 跳过,不递归、不做拷贝写回
*int 等基础类型指针 跳过,不处理
*time.Time 跳过,不处理(需在 time.Time 字段上使用标签)
配置结构体判定

递归只发生在「配置结构体」上,判定标准是 在递归深度内存在至少一个带 default 标签的可导出字段。

判定条件只看 default 标签,不把「有无切片 / 映射 / interface 字段」作为依据:

  • 切片 / 映射字段无标签时的「初始化为空容器」只作用于字段自身,递归不会带来额外收益
  • interface 字段虽然运行期可能装载配置结构体,但真实配置结构体的宿主必然带有 default 标签,判定自会通过;若宿主毫无标签,递归也无任何字段可填充,属行为中性

切片的例外:切片元素自身携带 default 标签时(如 []SubConfig),宿主结构体即使不带任何标签也会被判为配置结构体 —— 否则整段切片递归能力会在进入递归前就被类型判定挡掉。判定沿切片 / 映射 / 指针逐层剥壳后,再在结构体层面按 default 标签判定。

内层结构体、切片元素、「指向结构体的指针」字段会继续向内判定。判定结果按类型缓存,且带有环保护(类型互相引用不会栈溢出)。

这条判定让以下类型整体跳过:

  • sync.Mutex、atomic.Value、url.URL、配合 net.IP 的包装结构体等无标签类型。对它们递归不可能改到任何内容,跳过可避免 map 值元素被无意义地「拷贝 → 递归 → 写回」(例如 map[string]sync.Mutex 不会再被静默复制 —— 反射路径绕过了 go vet 的 copylocks 检查)
  • http.Request、http.Response 这类含切片 / 映射 / interface 字段但无 default 标签的第三方类型。这是收紧判定的主要收益:避免递归进入第三方对象,把其 nil map / nil slice 静默改写为空容器

注意:判定不影响「顶层直接调用」。CheckAndSetDefault(&cfg{}) 对传入的结构体本体直接逐字段处理,不经过本判定;cfg 内部的 interface / map / 指针字段递归能力也不受影响 —— 只要能进入递归,这些字段都会照常分派处理。

time.Time 字段的默认值

time.Time 字段支持 default 标签,仅在字段为零值(IsZero())时填充:

type Cfg struct {
    StartAt time.Time `json:"start_at" default:"2024-01-01 00:00:00"`
    DateOnly time.Time `json:"date_only" default:"2024-06-15"`
    ByStamp  time.Time `json:"by_stamp" default:"1704067200"`
}

支持的格式由 Convert.ToTime 提供,包括 RFC3339 / RFC1123 等标准格式、2006-01-02 15:04:05、2006-01-02、斜杠与中文分隔格式,以及秒 / 毫秒 / 纳秒时间戳字符串。

解析失败时静默跳过,不报错、不修改字段(与整型 / 浮点 / time.Duration 的容错风格一致)。

行为变更提示(升级需回归)

相比旧实现,以下字段从「完全不处理」变为「会被填充并在必要时就地改写」,升级时需要回归确认:

  1. 非 nil 的结构体指针字段:旧实现不处理任何 *Struct 字段,现在会递归补充其内部默认值
  2. interface{} 字段:旧实现对该字段实际是空操作,现在会解引用后按实际类型递归补充
  3. 非空 map 的元素:旧实现只处理 len == 0 的 map,现在会对非空 map 的元素递归补充并就地写回
  4. time.Time 字段:旧实现会静默忽略其 default 标签,现在会按标签填充
  5. 切片的元素:旧的约定是「切片不在递归范围内」,[]SubConfig、[]*SubConfig、interface{} 承载的切片都需要调用方自行遍历;现在这些切片的元素会被递归补充默认值,无需再手动遍历

第 3、5 条尤其注意:写回是就地的。map 的元素写回、切片元素的 Set 写回都会作用在原容器上,若同一个 map / 切片在别处被共享,其他持有者也会看到变化。

同时,判定条件收紧带来以下行为收窄(仅影响无 default 标签的场景):

场景 变更前 变更后
无标签的中间结构体内的 nil map / nil slice 被初始化为空容器 保持 nil
无标签的中间结构体内的 map / 切片元素 被递归补充默认值 不递归
http.Request 等第三方类型字段 被判为配置结构体并递归,nil map 被改写 整体跳过

如需上述能力,请给中间结构体加上 default 标签(例如 default:"" 可让空 map / 空切片被初始化)。

注意事项:

  1. 已有非零值的元素字段不会被覆盖,仅补充其中的零值字段
  2. map 值类型在反射中不可寻址,结构体元素通过「拷贝 → 补充 → 写回」完成,因此传递的 map 本身会被修改;切片元素可寻址,但为与 map 保持单一实现,值结构体元素同样走「拷贝 → 补充 → Set 写回」
  3. nil 指针不会被自动实例化。nil 表达「字段不存在 / 未启用 / 未配置」,自动创建会把「不存在」变成「存在且带默认值」,改变调用方语义(影响配置合并与 JSON 输出中的 null / {} 区别)。若需要指针也带上默认值,请先显式初始化:cfg.Inner = &SubConfig{}、cfg.Ptrs = []*SubConfig{{}}。该约定对结构体指针字段、map 值为 nil 指针、切片元素为 nil 指针三者一致
  4. 递归环路通过三重保护收敛,不会栈溢出:
    • struct / interface / ptr / slice 元素递归时传递统一的 depth 与 visited,避免每经过一层值类型结构体就把计数器重置
    • 含指针的环(如 map[string]*Node、[]*Node 指回自身)由指针地址路径集合 visited 收敛(进入登记、返回注销,不会把 DAG 的重复引用误判成环)
    • 不含指针的环(如 map[string]interface{} 或 []interface{} 通过 interface 装下自身)由递归深度上限 maxStructDefaultDepth 兜底
  5. maxStructDefaultDepth 的深度语义为「容器嵌套层数」:每深入一层 struct / map 元素 / 切片元素 / 指针指向的 struct 都会 +1;interface 仅作拆包不消耗深度,字段自身的 map / 切片容器也不消耗(其元素才计入)。上限取 32,超出后静默停止深入(不报错、不 panic)。不要依赖「恰好多少层可用」这种由实现倒推得出的具体数字,正常配置的嵌套深度远小于该值
  6. 切片元素在递归范围内,[]SubConfig、[]*SubConfig、[][]SubConfig、map[string][]SubConfig 以及 interface{} 承载的切片都会被自动补充默认值,无需再手动遍历。仍需注意:
    • 元素为基础类型的切片([]string、[]int、[]time.Time 等)不会被逐元素改写,仅空切片按 default 标签整体填充(注:需该字段所在的宿主结构体已进入递归)
    • 元素为无 default 标签的第三方类型(如 []sync.Mutex)会被整段跳过,不做「拷贝 → 写回」

高级用法

组合使用示例
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 组合使用多个模块
    data := map[string]interface{}{
        "amount": "100.50",
        "currency": "CNY",
        "description": "商品购买",
    }

    // 使用Json模块处理数据
    jsonHelper := helper.Json(data)
    var jsonString string
    jsonHelper.ToString(&jsonString)
    
    // 使用字符串模块处理描述
    desc := helper.NewStr(data["description"].(string))
    truncatedDesc := desc.Truncate(10, "...")
    
    // 使用货币模块处理金额
    amount := helper.Money(data["amount"])
    formattedAmount := amount.FloatString("¥", "")
    
    fmt.Printf("JSON数据: %s\n", jsonString)
    fmt.Printf("描述: %s\n", truncatedDesc)
    fmt.Printf("金额: %s\n", formattedAmount)
}
错误处理最佳实践
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func ProcessPayment(amountStr string) error {
    // 货币转换和验证
    money := helper.Money(amountStr)
    if err := money.GetError(); err != nil {
        return fmt.Errorf("金额格式错误: %v", err)
    }
    
    // 金额验证
    if money.LessThan(helper.Money("0.01")) {
        return fmt.Errorf("金额不能小于0.01元")
    }
    
    // 处理支付逻辑...
    fmt.Printf("支付金额: %s\n", money.FloatString("¥", ""))
    
    return nil
}

func main() {
    amounts := []string{"100.50", "invalid", "0.00"}
    
    for _, amount := range amounts {
        fmt.Printf("处理金额: %s\n", amount)
        if err := ProcessPayment(amount); err != nil {
            fmt.Printf("处理失败: %v\n", err)
        } else {
            fmt.Println("处理成功")
        }
        fmt.Println()
    }
}

性能优化建议

  1. 避免不必要的转换: 在可能的情况下直接使用原始类型
  2. 重用对象: 对于频繁使用的对象,考虑重用而不是重复创建
  3. 批量操作: 对于数组和Map操作,使用批量方法减少循环次数
  4. 错误检查: 在使用结果前检查错误,避免无效操作
  5. 内存管理: 对于大文件操作,注意及时关闭文件句柄

安全考虑

  • 输入验证: 所有外部输入都应该进行验证
  • 文件权限: 文件操作时注意权限设置
  • 内存安全: 避免内存泄漏和缓冲区溢出
  • 错误处理: 完善的错误处理防止程序崩溃

API 参考

Convert 类型
type Convert struct {
    Value interface{}
}

func (c Convert) ToString() string
func (c Convert) ToInt() int
func (c Convert) ToInt64() int64
func (c Convert) ToFloat64() float64
func (c Convert) ToBool() bool
func (c Convert) ToFileMode() os.FileMode
func (c Convert) ToArrByte() []byte
func (c Convert) ToNumber() (interface{}, bool)
func (c Convert) ToTime() time.Time
func (c Convert) ToMap() map[string]interface{}
func (c Convert) ToSlice() []interface{}
func (c Convert) ToDuration() time.Duration
func (c Convert) ToInterface() interface{}
Str 类型
type Str struct {
    String  string
    // ... 其他字段
}

func NewStr(str string) *Str
func (s *Str) ByteLength() int
func (s *Str) ByteSubstr(start int, length int) string
func (s *Str) Truncate(length int, suffix string) string
func (s *Str) StartsWith(prefix string, caseSensitive bool) bool
func (s *Str) EndsWith(suffix string, caseSensitive bool) bool
func (s *Str) Explode(delimiter string, trim bool, skipEmpty bool) []string
func (s *Str) Base64UrlEncode() string
func (s *Str) Base64UrlDecode() (string, error)
func (s *Str) EscapeHTML() string
func (s *Str) ConvertCamelToSnake() string
JsonHelper 类型
type JsonHelper struct {
    // ... 字段
}

func Json(input interface{}) *JsonHelper
func JsonFile(path string) *JsonHelper
func (jh *JsonHelper) ToStruct(newStruct interface{}) *JsonHelper
func (jh *JsonHelper) ToString(newStr *string) *JsonHelper
func (jh *JsonHelper) MakeFile(filepath string) *JsonHelper
File 类型
type File struct {
    Path string
    Perm os.FileMode
}

func NewFile(args ...any) *File
func (fh *File) Exists() bool
func (fh *File) IsDir() bool
func (fh *File) GetAbsPath() (string, error)
func (fh *File) Basename(suffix string) string
func (fh *File) DirName() string
func (fh *File) DirExists(createIfNotExists bool) (bool, error)
MoneyHelper 类型
type MoneyHelper struct {
    Amount int64
}

func Money(input interface{}) *MoneyHelper
func (m *MoneyHelper) SetAmount(value interface{}) *MoneyHelper
func (m *MoneyHelper) Add(other *MoneyHelper) *MoneyHelper
func (m *MoneyHelper) Subtract(other *MoneyHelper) *MoneyHelper
func (m *MoneyHelper) Multiply(factor float64) *MoneyHelper
func (m *MoneyHelper) Divide(divisor float64) *MoneyHelper
func (m *MoneyHelper) FloatString(parts ...string) string
func (m *MoneyHelper) GreaterThan(other *MoneyHelper) bool
func (m *MoneyHelper) GetError() error
MapHelper 类型
type MapHelper struct {
    Data map[string]interface{}
    Keys []string
    Sort bool
}

func NewMap(mapData map[string]interface{}) *MapHelper
func (m *MapHelper) DoSort() *MapHelper
func (m *MapHelper) ArrayKeys() []string
func (m *MapHelper) ArrayValues() []interface{}
func (m *MapHelper) GetData() map[string]interface{}
func (m *MapHelper) ExtractString(path string) string
func (m *MapHelper) Extract(path string) interface{}
func (m *MapHelper) ExtractWithDefault(path string, defaultValue interface{}) interface{}
### 单位转换函数

```go
// 单位类型定义
type UnitType int
const (
    UnitTypeStorage UnitType = iota
    UnitTypeTime
    UnitTypeData
)

// 单位结构
type Unit struct {
    Name     string
    Symbols  []string
    Factor   float64
    UnitType UnitType
}

// 单位转换函数
func ParseUnitString(str string, unitType UnitType) (float64, *Unit, error)
func FormatUnit(value float64, unitType UnitType, precision int) string
func ConvertUnit(value float64, fromUnit, toUnit string, unitType UnitType) (float64, error)
func IsValidUnit(unitStr string, unitType UnitType) bool
func GetUnitType(unitStr string, unitType UnitType) (UnitType, error)
func GetAvailableUnits(unitType UnitType) []string

func RoundUnitValue(value float64, unit string, precision int, unitType UnitType) (float64, error)

// Str类型的单位相关方法
func (s *Str) ParseUnit(unitType UnitType) (float64, *Unit, error)
func (s *Str) ToUnitValue(unitType UnitType) (float64, error)
工具函数
func GetSSHKey() (string, error)
func GenerateSSHKey() error
func SetArrStr(str []string) *ArrStr
func NewMap(mapData map[string]interface{}) *MapHelper
func StrReplace(search interface{}, replace interface{}, subject interface{}, count int) (interface{}, error)
func StringStartWith(str, prefix string) bool
func StringEndWith(str, suffix string) bool
func InArray(needle interface{}, haystack []string) bool
func MatchWildcard(pattern, s string, caseSensitive bool) bool
func Random(length int) string
func MD5(text string) string
func SHA256(text string) string
func Base64Encode(data []byte) string
func Base64Decode(s string) ([]byte, error)
func IsError(err error) bool
func IsEmptyValue(v interface{}) bool
func CheckAndSetDefault(config interface{}) error
func CheckAndSetDefaultWithPreserveTag(config interface{}) error
func StructToMap(obj interface{}) map[string]interface{}
func MapToStruct(m map[string]interface{}, target interface{}) error
func CopyStruct(src, dst interface{}) error
func StructMerge(dst, src interface{}) error
func GetFieldNameByJSONTag(t reflect.Type, jsonTag string) string
func CalculateAge(birthDate string) int
func ParseIP(ip string) *IP
func ParseChineseIDCard(idCard string) (map[string]interface{}, error)
func CompareNumber(a, b interface{}) int
func Max(a, b interface{}) interface{}
func Min(a, b interface{}) interface{}
func TraceCaller(skip int) (file string, line int, function string)
func FindAvailablePort(startPort int) int
func BuildYii2RedisCacheKey(key string) string
func CompareVersion(v1, v2 string) int

性能优化建议

字符串处理优化
  1. 避免不必要的字符串转换

    // 不推荐:频繁创建字符串对象
    for i := 0; i < 1000; i++ {
        str := helper.NewStr("test" + strconv.Itoa(i))
        // 处理字符串
    }
    
    // 推荐:复用字符串对象
    str := helper.NewStr("")
    for i := 0; i < 1000; i++ {
        str.String = "test" + strconv.Itoa(i)
        // 处理字符串
    }
    
  2. 使用字节操作替代字符串操作

    // 对于大量数据处理,优先使用字节操作
    str := helper.NewStr(largeText)
    byteLen := str.ByteLength()  // 比 len(str.String) 更高效
    
JSON处理优化
  1. 批量处理JSON数据

    // 不推荐:逐个处理JSON对象
    for _, item := range items {
        jsonHelper := helper.Json(item)
        // 处理单个JSON
    }
    
    // 推荐:批量处理JSON数组
    jsonHelper := helper.Json(items)
    // 批量处理所有JSON对象
    
  2. 使用结构体标签优化序列化

    type User struct {
        Name string `json:"name,omitempty"`  // 空值不序列化
        Age  int    `json:"age"`
    }
    
文件操作优化
  1. 减少文件系统调用

    // 不推荐:多次检查文件状态
    if file.Exists() {
        if file.IsReadable() {
            // 读取文件
        }
    }
    
    // 推荐:缓存文件状态信息
    file := helper.NewFile(&helper.File{Path: "test.txt"})
    if exists := file.Exists(); exists {
        // 一次性获取所有状态信息
        isReadable := file.IsReadable()
        isWritable := file.IsWritable()
    }
    
  2. 使用绝对路径避免路径解析开销

    // 推荐:使用绝对路径
    absPath, _ := filepath.Abs("relative/path.txt")
    file := helper.NewFile(&helper.File{Path: absPath})
    
内存使用优化
  1. 及时释放大对象

    // 处理大文件后及时释放
    func processLargeFile() {
        file := helper.NewFile(&helper.File{Path: "large.txt"})
        // 处理文件
        // 处理完成后,让GC回收内存
        file = nil
    }
    
  2. 避免内存泄漏

    // 在循环中避免创建不必要的对象引用
    var results []string
    for i := 0; i < 10000; i++ {
        str := helper.NewStr(fmt.Sprintf("item%d", i))
        // 只保留需要的数据,而不是整个对象
        results = append(results, str.String)
    }
    

使用最佳实践

错误处理最佳实践
  1. 始终检查错误返回值

    // 不推荐:忽略错误
    jsonHelper.ToStruct(&data)
    
    // 推荐:正确处理错误
    if err := jsonHelper.ToStruct(&data); err != nil {
        log.Printf("JSON解析失败: %v", err)
        return
    }
    
  2. 使用错误包装提供上下文信息

    func processUserData(jsonStr string) error {
        jsonHelper := helper.Json(jsonStr)
        var user User
        if err := jsonHelper.ToStruct(&user); err != nil {
            return fmt.Errorf("处理用户数据失败: %w", err)
        }
        return nil
    }
    
并发安全最佳实践
  1. 避免共享可变状态

    // 不推荐:在goroutine中共享可变对象
    var sharedStr = helper.NewStr("shared")
    
    go func() {
        sharedStr.String = "modified"  // 竞态条件
    }()
    
    // 推荐:每个goroutine使用独立对象
    go func(str *helper.Str) {
        str.String = "modified"  // 安全
    }(helper.NewStr("local"))
    
  2. 使用同步机制保护共享资源

    type SafeStringProcessor struct {
        mu sync.RWMutex
        str *helper.Str
    }
    
    func (s *SafeStringProcessor) Process() {
        s.mu.Lock()
        defer s.mu.Unlock()
        // 安全地处理字符串
    }
    
代码组织最佳实践
  1. 模块化使用helper组件

    // 推荐:按功能模块组织代码
    type UserService struct {
        jsonHelper *helper.JsonHelper
        strHelper  *helper.Str
    }
    
    func (s *UserService) ProcessUser(jsonStr string) error {
        // 使用helper组件处理业务逻辑
        return nil
    }
    
  2. 合理使用接口抽象

    // 定义接口,便于测试和替换
    type StringProcessor interface {
        Process(input string) string
    }
    
    type HelperStringProcessor struct {
        str *helper.Str
    }
    
    func (p *HelperStringProcessor) Process(input string) string {
        p.str.String = input
        return p.str.ToUpper()
    }
    
测试最佳实践
  1. 编写单元测试覆盖helper功能

    func TestStr_ToUpper(t *testing.T) {
        str := helper.NewStr("hello")
        result := str.ToUpper()
        if result != "HELLO" {
            t.Errorf("期望 HELLO, 得到 %s", result)
        }
    }
    
  2. 使用表格驱动测试

    func TestConvert_ToInt(t *testing.T) {
        tests := []struct {
            name     string
            input    interface{}
            expected int
        }{
            {"整数", 123, 123},
            {"字符串", "456", 456},
            {"浮点数", 78.9, 78},
        }
    
        for _, tt := range tests {
            t.Run(tt.name, func(t *testing.T) {
                convert := helper.Convert{Value: tt.input}
                result := convert.ToInt()
                if result != tt.expected {
                    t.Errorf("期望 %d, 得到 %d", tt.expected, result)
                }
            })
        }
    }
    

通过遵循这些性能优化建议和使用最佳实践,您可以确保helper组件在各种场景下都能提供最佳的性能和可靠性。

错误处理和异常情况说明

Helper 组件提供了完善的错误处理机制,帮助开发者优雅地处理各种异常情况。

错误处理原则
  1. 显式错误返回: 所有可能失败的操作都返回错误信息
  2. 错误信息清晰: 错误信息包含足够的上下文信息
  3. 错误类型区分: 区分不同类型的错误以便针对性处理
  4. 错误传播: 支持错误链式传播,便于调试
常见错误类型
1. 输入验证错误
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 无效的JSON字符串
    jsonStr := `{"name": "张三", "age": "invalid"}`
    jsonHelper := helper.Json(jsonStr)
    var data map[string]interface{}
    
    if err := jsonHelper.ToStruct(&data); err != nil {
        fmt.Printf("JSON解析错误: %v\n", err)
        // 输出: JSON解析错误: json: cannot unmarshal string into Go struct field .age of type int
    }
    
    // 无效的货币格式
    money := helper.Money("invalid")
    if err := money.GetError(); err != nil {
        fmt.Printf("货币格式错误: %v\n", err)
        // 输出: 货币格式错误: strconv.ParseFloat: parsing "invalid": invalid syntax
    }
}
2. 文件操作错误
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 文件不存在
    file := helper.NewFile("/path/to/nonexistent/file.txt")
    if !file.Exists() {
        fmt.Println("文件不存在")
    }
    
    // 权限不足
    file = helper.NewFile("/root/protected/file.txt")
    if !file.IsReadable() {
        fmt.Println("文件不可读,权限不足")
    }
    
    // 获取绝对路径错误
    absPath, err := file.GetAbsPath()
    if err != nil {
        fmt.Printf("获取绝对路径失败: %v\n", err)
    }
}
3. 单位转换错误
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // 无效的单位符号
    result, err := helper.ConvertUnit(100, "invalid", "KB", helper.UnitTypeStorage)
    if err != nil {
        fmt.Printf("单位转换错误: %v\n", err)
        // 输出: 单位转换错误: 无效的单位符号: invalid
    }
    
    // 不兼容的单位类型
    result, err = helper.ConvertUnit(100, "B", "s", helper.UnitTypeStorage)
    if err != nil {
        fmt.Printf("单位类型不兼容: %v\n", err)
        // 输出: 单位类型不兼容: 单位类型不匹配
    }
    
    // 单位字符串解析错误
    _, _, err = helper.ParseUnitString("invalid", helper.UnitTypeStorage)
    if err != nil {
        fmt.Printf("单位字符串解析错误: %v\n", err)
        // 输出: 单位字符串解析错误: 无法解析单位字符串
    }
}
4. 字符串处理错误
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func main() {
    // Base64解码错误
    str := helper.NewStr("invalid base64")
    decoded, err := str.Base64UrlDecode()
    if err != nil {
        fmt.Printf("Base64解码错误: %v\n", err)
        // 输出: Base64解码错误: illegal base64 data at input byte 7
    }
    
    // 字符串截取越界
    str = helper.NewStr("hello")
    substr := str.ByteSubstr(0, 10) // 越界访问
    fmt.Printf("截取结果: %s\n", substr) // 输出: hello (自动处理越界)
}
错误处理最佳实践
1. 防御性编程
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func SafeProcessData(input string) error {
    // 输入验证
    if input == "" {
        return fmt.Errorf("输入不能为空")
    }
    
    // 使用helper组件处理
    str := helper.NewStr(input)
    if str.ByteLength() > 1000 {
        return fmt.Errorf("输入长度超过限制")
    }
    
    // 处理逻辑
    processed := str.ToUpper()
    fmt.Printf("处理结果: %s\n", processed)
    
    return nil
}

func main() {
    inputs := []string{"", "hello", "very long string..."}
    
    for _, input := range inputs {
        if err := SafeProcessData(input); err != nil {
            fmt.Printf("处理失败: %v\n", err)
        } else {
            fmt.Println("处理成功")
        }
    }
}
2. 错误链式传播
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func ProcessUserData(jsonStr string) error {
    // 解析JSON
    jsonHelper := helper.Json(jsonStr)
    var userData map[string]interface{}
    if err := jsonHelper.ToStruct(&userData); err != nil {
        return fmt.Errorf("解析用户数据失败: %w", err)
    }
    
    // 提取用户名
    mapHelper := helper.NewMap(userData)
    name := mapHelper.ExtractString("name")
    if name == "" {
        return fmt.Errorf("用户名不能为空")
    }
    
    // 处理用户名
    str := helper.NewStr(name)
    if str.ByteLength() < 2 {
        return fmt.Errorf("用户名长度太短")
    }
    
    fmt.Printf("处理用户: %s\n", str.ToUpper())
    return nil
}

func main() {
    jsonStr := `{"name": "张"}` // 用户名太短
    
    if err := ProcessUserData(jsonStr); err != nil {
        fmt.Printf("用户数据处理失败: %v\n", err)
        // 输出: 用户数据处理失败: 用户名长度太短
    }
}
3. 错误恢复机制
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func SafeUnitConversion(value float64, fromUnit, toUnit string) (result float64, err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("单位转换发生panic: %v", r)
        }
    }()
    
    // 尝试单位转换
    result, err = helper.ConvertUnit(value, fromUnit, toUnit, helper.UnitTypeStorage)
    if err != nil {
        return 0, fmt.Errorf("单位转换失败: %w", err)
    }
    
    return result, nil
}

func main() {
    // 正常情况
    result, err := SafeUnitConversion(1024, "B", "KB")
    if err != nil {
        fmt.Printf("转换失败: %v\n", err)
    } else {
        fmt.Printf("转换结果: %.2f KB\n", result)
    }
    
    // 异常情况
    result, err = SafeUnitConversion(1024, "invalid", "KB")
    if err != nil {
        fmt.Printf("转换失败: %v\n", err)
        // 输出: 转换失败: 单位转换失败: 无效的单位符号: invalid
    }
}
异常情况处理
1. 边界条件处理
package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

func HandleEdgeCases() {
    // 空字符串处理
    emptyStr := helper.NewStr("")
    fmt.Printf("空字符串长度: %d\n", emptyStr.ByteLength()) // 输出: 0
    
    // 超大数字处理
    bigMoney := helper.Money("999999999999999.99")
    if err := bigMoney.GetError(); err != nil {
        fmt.Printf("超大金额错误: %v\n", err)
    }
    
    // 特殊字符处理
    specialStr := helper.NewStr("hello\x00world") // 包含空字符
    fmt.Printf("特殊字符处理: %s\n", specialStr.String)
}

func main() {
    HandleEdgeCases()
}
2. 并发安全处理
package main

import (
    "fmt"
    "sync"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

type SafeProcessor struct {
    mu sync.RWMutex
    data map[string]interface{}
}

func (p *SafeProcessor) SafeExtract(path string) (interface{}, error) {
    p.mu.RLock()
    defer p.mu.RUnlock()
    
    if p.data == nil {
        return nil, fmt.Errorf("数据为空")
    }
    
    mapHelper := helper.NewMap(p.data)
    result := mapHelper.Extract(path)
    if result == nil {
        return nil, fmt.Errorf("路径不存在: %s", path)
    }
    
    return result, nil
}

func main() {
    processor := &SafeProcessor{
        data: map[string]interface{}{
            "user": map[string]interface{}{
                "name": "张三",
                "age": 25,
            },
        },
    }
    
    // 并发安全访问
    var wg sync.WaitGroup
    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            
            result, err := processor.SafeExtract("user.name")
            if err != nil {
                fmt.Printf("协程%d错误: %v\n", id, err)
            } else {
                fmt.Printf("协程%d结果: %v\n", id, result)
            }
        }(i)
    }
    wg.Wait()
}
错误信息国际化

Helper 组件支持错误信息的国际化处理:

package main

import (
    "fmt"
    "github.com/jcbowen/jcbaseGo/component/helper"
)

// 错误信息映射表
var errorMessages = map[string]map[string]string{
    "en": {
        "invalid_json": "Invalid JSON format",
        "file_not_found": "File not found",
        "unit_conversion_error": "Unit conversion error",
    },
    "zh": {
        "invalid_json": "JSON格式无效",
        "file_not_found": "文件不存在",
        "unit_conversion_error": "单位转换错误",
    },
}

func GetErrorMessage(key, lang string) string {
    if messages, ok := errorMessages[lang]; ok {
        if msg, ok := messages[key]; ok {
            return msg
        }
    }
    return key // 默认返回key
}

func main() {
    // 中文错误信息
    fmt.Printf("中文错误: %s\n", GetErrorMessage("file_not_found", "zh"))
    
    // 英文错误信息
    fmt.Printf("英文错误: %s\n", GetErrorMessage("unit_conversion_error", "en"))
}

通过遵循这些错误处理和异常情况说明,您可以确保在使用 Helper 组件时能够优雅地处理各种异常情况,提高代码的健壮性和可靠性。

贡献指南

欢迎提交 Issue 和 Pull Request 来改进 Helper 组件。

许可证

Helper 组件遵循 MIT 许可证。

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// StorageUnits 存储单位映射
	// StorageUnits storage unit mapping
	StorageUnits = []Unit{
		{"Byte", []string{"B", "byte", "bytes"}, 1, UnitTypeStorage},
		{"Kilobyte", []string{"KB", "K", "kilobyte", "kilobytes"}, 1024, UnitTypeStorage},
		{"Megabyte", []string{"MB", "M", "megabyte", "megabytes"}, 1024 * 1024, UnitTypeStorage},
		{"Gigabyte", []string{"GB", "G", "gigabyte", "gigabytes"}, 1024 * 1024 * 1024, UnitTypeStorage},
		{"Terabyte", []string{"TB", "T", "terabyte", "terabytes"}, 1024 * 1024 * 1024 * 1024, UnitTypeStorage},
		{"Petabyte", []string{"PB", "P", "petabyte", "petabytes"}, 1024 * 1024 * 1024 * 1024 * 1024, UnitTypeStorage},
	}

	// TimeUnits 时间单位映射
	// TimeUnits time unit mapping
	TimeUnits = []Unit{
		{"Nanosecond", []string{"ns", "nanosecond", "nanoseconds"}, 1, UnitTypeTime},
		{"Microsecond", []string{"μs", "us", "microsecond", "microseconds"}, 1000, UnitTypeTime},
		{"Millisecond", []string{"ms", "millisecond", "milliseconds"}, 1000 * 1000, UnitTypeTime},
		{"Second", []string{"s", "sec", "second", "seconds"}, 1000 * 1000 * 1000, UnitTypeTime},
		{"Minute", []string{"m", "min", "minute", "minutes"}, 60 * 1000 * 1000 * 1000, UnitTypeTime},
		{"Hour", []string{"h", "hr", "hour", "hours"}, 60 * 60 * 1000 * 1000 * 1000, UnitTypeTime},
		{"Day", []string{"d", "day", "days"}, 24 * 60 * 60 * 1000 * 1000 * 1000, UnitTypeTime},
	}

	// DataUnits 数据单位映射
	// DataUnits data unit mapping
	DataUnits = []Unit{
		{"Bit", []string{"b", "bit", "bits"}, 1, UnitTypeData},
		{"Byte", []string{"byte", "bytes"}, 8, UnitTypeData},
		{"Kilobit", []string{"Kb", "Kbit", "kilobit", "kilobits"}, 1024, UnitTypeData},
		{"Kilobyte", []string{"Kbyte", "kilobyte", "kilobytes"}, 1024 * 8, UnitTypeData},
		{"Megabit", []string{"Mb", "Mbit", "megabit", "megabits"}, 1024 * 1024, UnitTypeData},
		{"Megabyte", []string{"Mbyte", "megabyte", "megabytes"}, 1024 * 1024 * 8, UnitTypeData},
		{"Gigabit", []string{"Gb", "Gbit", "gigabit", "gigabits"}, 1024 * 1024 * 1024, UnitTypeData},
		{"Gigabyte", []string{"Gbyte", "gigabyte", "gigabytes"}, 1024 * 1024 * 1024 * 8, UnitTypeData},
	}

	// AllUnits 所有单位的合并映射
	// AllUnits combined mapping of all units
	AllUnits = append(append(append([]Unit{}, StorageUnits...), TimeUnits...), DataUnits...)
)

预定义的单位映射 Predefined unit mappings

Functions

func AddHeader added in v0.13.5

func AddHeader(w http.ResponseWriter, key, value string)

AddHeader 添加HTTP响应头 参数:

  • w: HTTP响应写入器
  • key: 头信息键名
  • value: 头信息值

func Base64Decode

func Base64Decode(str string) (string, error)

Base64Decode base64解密

func Base64Encode

func Base64Encode(str string) string

Base64Encode base64加密

func BuildQueryString added in v0.13.5

func BuildQueryString(params map[string]string) string

BuildQueryString 构建查询字符串 参数:

  • params: 参数映射

返回值:

  • string: 查询字符串

func BuildURL added in v0.13.5

func BuildURL(scheme, host, path string, query map[string]string) string

BuildURL 构建URL 参数:

  • scheme: 协议
  • host: 主机
  • path: 路径
  • query: 查询参数

返回值:

  • string: 构建的URL

func BuildYii2RedisCacheKey added in v0.10.2

func BuildYii2RedisCacheKey(key string, args ...string) string

BuildYii2RedisCacheKey 生成一个规范化的缓存键,支持可选的前缀参数。 逻辑同yii2的yii\caching\Cache::buildKey

参数说明: - key: 需要规范化的缓存键字符串。 - args: 可选参数,args[0] 为缓存键的前缀字符串。

处理逻辑:

  1. 如果 key 只包含字母和数字,且长度不超过 32 个字符, 则直接返回前缀加 key。
  2. 否则对 key 进行 MD5 哈希处理, 返回前缀加哈希字符串,保证缓存键长度和格式统一。

该方法适用于缓存键的标准化处理,避免因 key 格式差异导致缓存失效。

func CalculateAge added in v0.8.0

func CalculateAge(args ...interface{}) (int, error)

CalculateAge 计算年龄的多功能方法 支持以下两种调用方式: 1. CalculateAge(year, month, day int) (int, error) 2. CalculateAge(dateString string) (int, error)

func CheckAndSetDefault

func CheckAndSetDefault(i interface{}) error

CheckAndSetDefault 检查结构体中的字段是否为空,如果为空则设置为默认值 函数名:CheckAndSetDefault 参数:i interface{} — 结构体或其指针,支持一层指针传入 返回值:error — 始终返回nil;本函数不抛出解析错误,保持兼容的静默行为 异常:不触发panic(除非外部传入不可寻址的值并强制Addr) 使用说明:

  • 仅对以下类型在“空值”时设置默认:string、bool、int系、float32/float64、time.Duration
  • struct、interface、ptr 三类字段会向下递归处理,递归过程中贯通传递深度与已访问指针集合
  • map字段的值类型为自定义配置结构体时,会对每个元素递归补充默认值(支持结构体、结构体指针、interface承载的结构体)
  • 切片字段的元素为自定义配置结构体时同样递归补充默认值(支持 []Struct、[]*Struct、[]interface{}、嵌套切片与 map[string][]Struct)
  • 只有「配置结构体」才会被递归,判定标准为「在递归深度内,存在至少一个会被本工具作用的可导出字段」: 带 default 标签的字段、切片/映射字段(无标签时会被初始化为空容器)、可能装载配置结构体的 interface 字段; 因此 sync.Mutex、atomic.Value、url.URL、time.Time 这类无相关字段的第三方类型会被整体跳过, 既避免对不该复制的类型做「拷贝 → 写回」(例如 map[string]sync.Mutex),也省掉无收益的遍历
  • nil 指针字段保持原样、不会被自动实例化(与 map 值为 nil 指针的处理一致); 若需要指针字段也带上默认值,请先显式初始化:cfg.Inner = &InnerCfg{}
  • 切片在递归范围内:[]SubConfig 的值元素会「拷贝 → 补充 → 写回」,[]*SubConfig 的非 nil 指针就地补充、 nil 指针保持原样,[]interface{} 按实际类型分派,[]T 的嵌套切片与 map[string][]SubConfig 逐层向内; 元素为基础类型的切片([]string、[]int 等)不会被逐元素改写,仅空切片按 default 标签整体填充
  • 递归受环路保护:含指针的环由 visited 路径集合收敛,不含指针的环(如 map 通过 interface 装下自身)由 maxStructDefaultDepth 兜底
  • default标签为空时不会报错,数值/布尔解析失败会被忽略(保持原有逻辑)

行为变更提示(相比旧实现):

  • 旧实现对指针字段完全不处理,现在非 nil 的 *Struct 字段会被递归补充默认值;
  • 旧实现对 interface 字段实际是空操作,现在会解引用后按实际类型(结构体 / 结构体指针 / 映射)递归补充;
  • 旧实现对非空 map 的元素完全不处理,现在会对命中判定条件的 map 元素递归补充,并就地写回原 map (调用方在别处共享的同一个 map 也会看到变化)。

使用示例:

type SubConfig struct {
    Host string `json:"host" default:"127.0.0.1"`
    Port int    `json:"port" default:"3306"`
}
type AppConfig struct {
    Name    string               `json:"name" default:"myapp"`
    Enabled bool                 `json:"enabled" default:"true"`
    Port    int                  `json:"port" default:"8080"`
    Timeout  time.Duration       `json:"timeout" default:"300ms"`
    Clusters map[string]SubConfig `json:"clusters"`
    Inner    *SubConfig          `json:"inner"`
}
cfg := &AppConfig{Clusters: map[string]SubConfig{"main": {}}, Inner: &SubConfig{}}
_ = helper.CheckAndSetDefault(cfg)
// cfg.Clusters["main"] == SubConfig{Host: "127.0.0.1", Port: 3306}
// cfg.Inner           == &SubConfig{Host: "127.0.0.1", Port: 3306}

常见问题:如果发现默认值赋值失败,但是又没有出现报错,可以看看是不是传递的指针的指针

func CheckAndSetDefaultWithPreserveTag added in v0.13.8

func CheckAndSetDefaultWithPreserveTag(i interface{}) error

CheckAndSetDefaultWithPreserveTag 按 `default` 标签设置默认值,同时保留带有 `preserve:"true"` 标签字段的原始值 函数名:CheckAndSetDefaultWithPreserveTag 参数:i interface{} — 结构体或其指针,支持多层指针;顶层为nil指针时直接返回 返回值:error — 当默认值解析失败、类型溢出或不支持的类型时返回错误 异常:不触发panic,本函数所有失败均以error返回 使用说明: - 为需要保留用户显式设置零值(如 bool=false)的字段添加 `preserve:"true"` 标签 - 本函数先快照这些字段的原始值,再调用 CheckAndSetDefault 设置默认值,最后恢复快照值 使用示例:

type Config struct {
    EnableFeature bool `json:"enable_feature" default:"true" preserve:"true"`
}
cfg := &Config{}
_ = helper.CheckAndSetDefaultWithPreserveTag(cfg)

func CheckETag added in v0.13.5

func CheckETag(req *http.Request, etag string) bool

CheckETag 检查ETag是否匹配 参数:

  • req: HTTP请求对象
  • etag: 当前ETag

返回值:

  • bool: 如果ETag匹配返回true,否则返回false

func CompareNumber

func CompareNumber(a, b interface{}) int

CompareNumber 比较两个值,如果 a < b 返回 -1,如果 a == b 返回 0,如果 a > b 返回 1,如果错误则 panic

func CompareVersion added in v0.10.7

func CompareVersion(a string, b string) (result int, level int)

CompareVersion 版本号比较(支持x.y.z,降级为数值分段比较,不足段补0;非法段按0处理) 参数:

  • a: 版本号A
  • b: 版本号B

返回:

  • result: 比较结果(1 表示a>b;0表示相等;-1表示a<b)
  • level: 差异级别(从1开始,表示第几级版本号差异;0表示无差异)

func ConvertUnit added in v0.13.5

func ConvertUnit(value float64, fromUnit, toUnit string, unitType UnitType) (float64, error)

ConvertUnit 在不同单位之间转换数值 ConvertUnit converts values between different units

参数:

  • value: 原始数值
  • fromUnit: 原始单位符号
  • toUnit: 目标单位符号
  • unitType: 单位类型

返回值:

  • float64: 转换后的数值
  • error: 转换过程中的错误

示例:

  • ConvertUnit(10, "MB", "KB", UnitTypeStorage) -> 10240, nil
  • ConvertUnit(1, "h", "m", UnitTypeTime) -> 60, nil
  • ConvertUnit(8, "b", "byte", UnitTypeData) -> 1, nil

func CopyStruct

func CopyStruct(src, dst interface{}) error

CopyStruct 复制源结构体(src)的字段到目标结构体(dst)。 该函数执行的是深层复制,基于字段名和字段类型进行匹配。 src 和 dst 都必须是指向结构体的指针。

注意事项: CopyStruct 函数用于将源结构体 (src) 的字段值深度复制到目标结构体 (dst) 中。 它通过反射机制实现,支持嵌套结构体、切片和映射的深层复制,并尝试进行灵活的类型转换。

注意事项: 1. 错误处理:如果 src 或 dst 不是指向结构体的指针,函数会返回错误。 2. 性能开销:反射操作通常比直接字段访问慢,频繁调用可能影响性能。 3. 深层复制:对于包含指针、切片、映射等复杂类型的字段,现在会进行深层复制。 4. 类型严格匹配:源字段和目标字段的类型现在支持可转换类型之间的灵活转换。 5. 未导出字段:无法设置来自不同包的未导出(小写字母开头)字段。 6. 字段名匹配:依赖于字段名完全匹配。

参数:

src: 源结构体(必须是指向结构体的指针)。
dst: 目标结构体(必须是指向结构体的指针)。

返回值:

error: 如果 src 或 dst 不是指向结构体的指针,或在复制过程中发生类型不匹配等错误,则返回错误;否则返回 nil。

示例:

type Source struct {
  Name string
  Age  int
}
type Destination struct {
  Name string
  Age  int
  City string
}
s := &Source{Name: "Alice", Age: 30}
d := &Destination{}
if err := CopyStruct(s, d); err != nil {
  log.Fatal(err)
}
// 此时 d 将为 {Name: "Alice", Age: 30, City: ""}

func DownloadFile added in v0.13.5

func DownloadFile(url, filepath string) error

DownloadFile 下载文件 参数:

  • url: 文件URL
  • filepath: 保存路径

返回值:

  • error: 下载错误

func ExtractDomain added in v0.13.5

func ExtractDomain(urlStr string) (string, error)

ExtractDomain 提取域名 参数:

  • urlStr: URL字符串

返回值:

  • string: 域名
  • error: 提取错误

func ExtractHeaders added in v0.13.5

func ExtractHeaders(header http.Header) map[string]string

ExtractHeaders 提取HTTP头信息并转换为map[string]string格式 该方法将http.Header中的每个键值对转换为字符串,多个值用逗号分隔

参数:

header - HTTP请求头

返回值:

map[string]string - 转换后的头信息

func ExtractPath added in v0.13.5

func ExtractPath(urlStr string) (string, error)

ExtractPath 提取路径 参数:

  • urlStr: URL字符串

返回值:

  • string: 路径
  • error: 提取错误

func ExtractQueryParams added in v0.13.5

func ExtractQueryParams(urlStr string) (map[string]string, error)

ExtractQueryParams 提取查询参数 参数:

  • urlStr: URL字符串

返回值:

  • map[string]string: 查询参数映射
  • error: 提取错误

func FindAvailablePort added in v0.9.1

func FindAvailablePort(startPort string) string

FindAvailablePort 查找可用端口 从指定端口开始,如果端口被占用则递增端口号,直到找到可用端口 未指定端口的情况下默认使用8080

func FormatHeaders added in v0.13.5

func FormatHeaders(headers map[string]string) string

FormatHeaders 格式化HTTP头信息为可读的字符串格式 该方法将map[string]string格式的头信息转换为键值对字符串,每行一个头信息

参数:

headers - HTTP头信息

返回值:

string - 格式化后的头信息字符串

func FormatUnit added in v0.13.5

func FormatUnit(value interface{}, unitType UnitType, precision int, toUnit ...string) (string, error)

FormatUnit 格式化单位值,支持多种输入格式和输出格式

参数:

  • unitType: 单位类型
  • precision: 小数位数精度
  • toUnit: 输出格式,可以是: -- "auto": 自动选择最合适的单位,默认值 -- 具体的单位符号(如 "MB", "s", "h" 等) -- value: 输入值,可以是: -- 数值(基础单位) -- 带单位的字符串(如 "10MB", "5.5s")

返回值:

  • string: 格式化后的字符串
  • error: 转换过程中的错误

示例:

  • FormatUnit(10485760, UnitTypeStorage, 2, "auto") -> "10.00MB", nil
  • FormatUnit(10485760, UnitTypeStorage, 2, "MB") -> "10.00MB", nil
  • FormatUnit("10MB", UnitTypeStorage, 2, "auto") -> "10.00MB", nil
  • FormatUnit("10MB", UnitTypeStorage, 2, "KB") -> "10240.00KB", nil
  • FormatUnit(5500000000, UnitTypeTime, 1, "auto") -> "5.5s", nil

func GenerateETag added in v0.13.5

func GenerateETag(content []byte) string

GenerateETag 生成ETag 参数:

  • content: 内容字节数组

返回值:

  • string: ETag字符串

func GenerateSSHKey

func GenerateSSHKey() error

GenerateSSHKey 生成 SSH 密钥

func GetAvailableUnits added in v0.13.5

func GetAvailableUnits(unitType UnitType) []string

GetAvailableUnits 获取指定类型的所有可用单位 GetAvailableUnits gets all available units of the specified type

参数:

  • unitType: 单位类型

返回值:

  • []string: 可用的单位符号列表

func GetCookie added in v0.13.5

func GetCookie(req *http.Request, name string) string

GetCookie 获取HTTP Cookie值 参数:

  • req: HTTP请求对象
  • name: Cookie名称

返回值:

  • string: Cookie值,如果不存在则返回空字符串

func GetFieldNameByJSONTag

func GetFieldNameByJSONTag(objType reflect.Type, jsonKey string) string

GetFieldNameByJSONTag 根据 JSON 标记获取结构体字段名

func GetFileExtension added in v0.13.5

func GetFileExtension(filename string) string

GetFileExtension 获取文件扩展名 参数:

  • filename: 文件名

返回值:

  • string: 文件扩展名

func GetFormFile added in v0.13.5

func GetFormFile(req *http.Request, key string) (multipart.File, *multipart.FileHeader, error)

GetFormFile 获取上传的文件 参数:

  • req: HTTP请求对象
  • key: 文件字段名

返回值:

  • multipart.File: 文件对象
  • *multipart.FileHeader: 文件头信息
  • error: 获取错误

func GetFormValue added in v0.13.5

func GetFormValue(req *http.Request, key string) string

GetFormValue 获取表单值 参数:

  • req: HTTP请求对象
  • key: 表单键名

返回值:

  • string: 表单值

func GetFullURL added in v0.13.5

func GetFullURL(req *http.Request) string

GetFullURL 获取完整的URL(包括协议、主机、路径和查询参数) 参数:

  • req: HTTP请求对象

返回值:

  • string: 完整的URL字符串

func GetHTTP added in v0.13.5

func GetHTTP(url string, headers map[string]string) (*http.Response, error)

GetHTTP 发送GET请求 参数:

  • url: 请求URL
  • headers: 请求头

返回值:

  • *http.Response: HTTP响应
  • error: 请求错误

func GetHTTPStatusText added in v0.13.5

func GetHTTPStatusText(code int) string

GetHTTPStatusText 获取HTTP状态码文本描述 参数:

  • code: HTTP状态码

返回值:

  • string: 状态码文本描述

func GetHeader added in v0.13.5

func GetHeader(req *http.Request, key string) string

GetHeader 获取HTTP请求头信息 参数:

  • req: HTTP请求对象
  • key: 头信息键名

返回值:

  • string: 头信息值,如果不存在则返回空字符串

func GetHostInfo

func GetHostInfo(req *http.Request) string

GetHostInfo 从HTTP请求中获取主机信息 该方法会检查TLS状态和X-Scheme头来确定协议,并优先使用代理头获取主机名

参数:

req - HTTP请求

返回值:

string - 完整的主机信息(协议://主机:端口)

func GetHostname added in v0.13.5

func GetHostname(req *http.Request) string

GetHostname 获取主机名(不含端口) 参数:

  • req: HTTP请求对象

返回值:

  • string: 主机名

func GetMimeType added in v0.13.5

func GetMimeType(extension string) string

GetMimeType 根据文件扩展名获取MIME类型 参数:

  • extension: 文件扩展名

返回值:

  • string: MIME类型

func GetPort added in v0.13.5

func GetPort(req *http.Request) string

GetPort 获取端口号 参数:

  • req: HTTP请求对象

返回值:

  • string: 端口号

func GetQueryParam added in v0.13.5

func GetQueryParam(req *http.Request, key string) string

GetQueryParam 获取URL查询参数 参数:

  • req: HTTP请求对象
  • key: 参数键名

返回值:

  • string: 参数值,如果不存在则返回空字符串

func GetQueryParams added in v0.13.5

func GetQueryParams(req *http.Request) map[string][]string

GetQueryParams 获取所有URL查询参数 参数:

  • req: HTTP请求对象

返回值:

  • map[string][]string: 所有查询参数

func GetRealIPFromHeaders added in v0.13.5

func GetRealIPFromHeaders(headers map[string]string) string

GetRealIPFromHeaders 从HTTP头信息中获取真实客户端IP 函数名:GetRealIPFromHeaders 参数: - headers map[string]string — 经过提取与归一化的请求头映射 返回值: - string — 解析出的真实客户端IP;当不可判定时返回空字符串 异常:不触发 panic 使用示例:

ip := GetRealIPFromHeaders(map[string]string{
    "Ali-Cdn-Real-Ip":  "203.0.113.1",
    "X-Forwarded-For":  "203.0.113.1, 198.51.100.2",
    "X-Real-IP":        "198.51.100.2",
})
// ip == "203.0.113.1"

func GetSSHKey

func GetSSHKey() (string, error)

GetSSHKey 获取 SSH 密钥,如果不存在则生成

func GetValidClientIP added in v0.13.5

func GetValidClientIP(ips []string) string

GetValidClientIP 从IP列表中获取有效的客户端IP 该方法会优先选择公网IP,如果没有公网IP则选择私有IP,最后选择第一个有效IP

参数:

  • ips: IP地址列表

返回值:

  • string: 有效的客户端IP地址,如果找不到则返回空字符串

func InArray

func InArray(val interface{}, array interface{}) (exists bool)

InArray 检查某个值是否存在于切片或数组中 val 是要检查的值 array 是要检查的切片或数组 exists 是返回的布尔值,表示 val 是否存在于 array 中;如果 array 不是切片或数组,返回 false

func IsAjaxRequest added in v0.13.5

func IsAjaxRequest(req *http.Request) bool

IsAjaxRequest 检查是否为Ajax请求 参数:

  • req: HTTP请求对象

返回值:

  • bool: 如果是Ajax请求返回true,否则返回false

func IsBotUserAgent added in v0.13.5

func IsBotUserAgent(userAgent string) bool

IsBotUserAgent 检查是否为爬虫/机器人User-Agent 参数:

  • userAgent: User-Agent字符串

返回值:

  • bool: 如果是爬虫返回true,否则返回false

func IsEmptyValue

func IsEmptyValue(val interface{}) bool

IsEmptyValue 检查值是否为空

func IsError

func IsError(errs []error) bool

IsError 判断[]error是否存在错误

func IsFormRequest added in v0.13.5

func IsFormRequest(req *http.Request) bool

IsFormRequest 检查是否为表单请求 参数:

  • req: HTTP请求对象

返回值:

  • bool: 如果是表单请求返回true,否则返回false

func IsHTTPS added in v0.13.5

func IsHTTPS(req *http.Request) bool

IsHTTPS 检查是否为HTTPS请求 参数:

  • req: HTTP请求对象

返回值:

  • bool: 如果是HTTPS请求返回true,否则返回false

func IsJSONRequest added in v0.13.5

func IsJSONRequest(req *http.Request) bool

IsJSONRequest 检查是否为JSON请求 参数:

  • req: HTTP请求对象

返回值:

  • bool: 如果是JSON请求返回true,否则返回false

func IsMobileUserAgent added in v0.13.5

func IsMobileUserAgent(userAgent string) bool

IsMobileUserAgent 检查是否为移动设备User-Agent 参数:

  • userAgent: User-Agent字符串

返回值:

  • bool: 如果是移动设备返回true,否则返回false

func IsURLSecure added in v0.13.5

func IsURLSecure(urlStr string) bool

IsURLSecure 检查URL是否安全(HTTPS) 参数:

  • urlStr: URL字符串

返回值:

  • bool: 如果是HTTPS返回true,否则返回false

func IsValidUnit added in v0.13.5

func IsValidUnit(unitStr string, unitType UnitType) bool

IsValidUnit 检查单位字符串是否有效 IsValidUnit checks if a unit string is valid

参数:

  • unitStr: 单位字符串
  • unitType: 单位类型

返回值:

  • bool: 单位是否有效

示例:

  • IsValidUnit("MB", UnitTypeStorage) -> true
  • IsValidUnit("h", UnitTypeTime) -> true
  • IsValidUnit("b", UnitTypeData) -> true

func MapToStruct

func MapToStruct(mapData interface{}, obj interface{}) error

MapToStruct 通过reflect将map转换为结构体 mapData 是要转换的 map,必须是 map[string]interface{} 类型或其兼容类型 obj 是目标结构体指针 返回转换过程中发生的错误,成功时返回 nil

func MaskIdCard added in v0.13.24

func MaskIdCard(idCard string) string

MaskIdCard 对身份证号进行脱敏处理。 规则:保留前 3 位和后 4 位,中间用 * 替代,例如 110***********1234。 若身份证号长度不足 7 位,则保留首尾各一位,中间替换。

参数:

  • idCard: 原始身份证号

返回值:

  • string: 脱敏后的身份证号

func MaskPhone added in v0.13.24

func MaskPhone(phone string) string

MaskPhone 对手机号进行脱敏处理。 规则:保留前 3 位和后 4 位,中间 4 位用 * 替代,例如 138****1234。 若手机号长度不足 7 位,则保留首尾各一位,中间替换。

参数:

  • phone: 原始手机号

返回值:

  • string: 脱敏后的手机号

func MaskString added in v0.13.24

func MaskString(s string, head, tail int, maskChar rune) string

MaskString 通用字符串脱敏。 保留头部和尾部指定 Unicode 字符数,中间用 maskChar 替换。 若字符串长度不足,则保留首尾各一位,中间替换;若长度小于等于 2,则直接返回原字符串。

参数:

  • s: 原始字符串
  • head: 头部保留字符数
  • tail: 尾部保留字符数
  • maskChar: 替换字符

返回值:

  • string: 脱敏后的字符串

func MatchWildcard

func MatchWildcard(pattern, s string, caseSensitive bool) bool

MatchWildcard 检查字符串是否匹配给定的通配符模式

func Max

func Max(numbers ...interface{}) interface{}

Max 返回可变参数中最大的值

func Min

func Min(numbers ...interface{}) interface{}

Min 返回可变参数中最小的值

func NewHTTPClient added in v0.13.5

func NewHTTPClient(config *HTTPClientConfig) *http.Client

NewHTTPClient 创建新的HTTP客户端 参数:

  • config: 客户端配置

返回值:

  • *http.Client: HTTP客户端

func NormalizeURL added in v0.13.5

func NormalizeURL(urlStr string) (string, error)

NormalizeURL 规范化URL 参数:

  • urlStr: URL字符串

返回值:

  • string: 规范化后的URL
  • error: 规范化错误

func ParseChineseIDCard added in v0.8.0

func ParseChineseIDCard(idCard string) (gender string, age int, birthDay string, regionCode string, sequenceCode string, err error)

ParseChineseIDCard 解析中国大陆身份证号码,提取性别、年龄、生日、出生地等信息

func ParseIP

func ParseIP(s string) (net.IP, int)

ParseIP 解析IP地址,输出是ipv4或ipv6 0: invalid ip 4: ipv4 6: ipv6

func ParseMultipartForm added in v0.13.5

func ParseMultipartForm(req *http.Request, maxMemory int64) error

ParseMultipartForm 解析多部分表单数据 参数:

  • req: HTTP请求对象
  • maxMemory: 最大内存大小(字节)

返回值:

  • error: 解析错误

func ParseQueryString added in v0.13.5

func ParseQueryString(query string) map[string]string

ParseQueryString 解析查询字符串 参数:

  • query: 查询字符串

返回值:

  • map[string]string: 解析后的参数映射

func PostFormHTTP added in v0.13.5

func PostFormHTTP(urlStr string, data map[string]string, headers map[string]string) (*http.Response, error)

PostFormHTTP 发送表单POST请求 参数:

  • urlStr: 请求URL
  • data: 表单数据
  • headers: 请求头

返回值:

  • *http.Response: HTTP响应
  • error: 请求错误

func PostHTTP added in v0.13.5

func PostHTTP(url string, body []byte, headers map[string]string) (*http.Response, error)

PostHTTP 发送POST请求 参数:

  • url: 请求URL
  • body: 请求体
  • headers: 请求头

返回值:

  • *http.Response: HTTP响应
  • error: 请求错误

func Random

func Random(length int, args ...bool) string

Random 生成随机字符

参数:

  • length (必需): 随机字符长度。
  • numericOnly (可选): 如果为 true,则只包含数字字符。

返回值:

  • string: 生成的随机字符串。

示例:

randomString := Random(16)
randomString := Random(16, true)

func ReadResponseBody added in v0.13.5

func ReadResponseBody(resp *http.Response) ([]byte, error)

ReadResponseBody 读取HTTP响应体 参数:

  • resp: HTTP响应

返回值:

  • []byte: 响应体内容
  • error: 读取错误

func ReadResponseBodyString added in v0.13.5

func ReadResponseBodyString(resp *http.Response) (string, error)

ReadResponseBodyString 读取HTTP响应体为字符串 参数:

  • resp: HTTP响应

返回值:

  • string: 响应体字符串
  • error: 读取错误

func Redirect added in v0.13.5

func Redirect(w http.ResponseWriter, req *http.Request, url string, code int)

Redirect 重定向到指定URL 参数:

  • w: HTTP响应写入器
  • req: HTTP请求对象
  • url: 重定向URL
  • code: 重定向状态码(默认302)

func RoundUnitValue added in v0.13.5

func RoundUnitValue(value float64, unit string, precision int, unitType UnitType) (float64, error)

RoundUnitValue 对单位值进行四舍五入 RoundUnitValue rounds a unit value

参数:

  • value: 原始值
  • unit: 单位符号
  • precision: 小数位数精度
  • unitType: 单位类型

返回值:

  • float64: 四舍五入后的值
  • error: 转换错误

func SaveUploadedFile added in v0.13.5

func SaveUploadedFile(fileHeader *multipart.FileHeader, dst string) error

SaveUploadedFile 保存上传的文件 参数:

  • fileHeader: 文件头信息
  • dst: 目标文件路径

返回值:

  • error: 保存错误

func SendHTTPRequest added in v0.13.5

func SendHTTPRequest(config *HTTPRequestConfig) (*http.Response, error)

SendHTTPRequest 发送HTTP请求 参数:

  • config: 请求配置

返回值:

  • *http.Response: HTTP响应
  • error: 请求错误

func SetCacheHeaders added in v0.13.5

func SetCacheHeaders(w http.ResponseWriter, maxAge int, public bool)

SetCacheHeaders 设置缓存头 参数:

  • w: HTTP响应写入器
  • maxAge: 最大缓存时间(秒)
  • public: 是否公开缓存

func SetContentDisposition added in v0.13.5

func SetContentDisposition(w http.ResponseWriter, filename, dispositionType string)

SetContentDisposition 设置内容处置头(用于文件下载) 参数:

  • w: HTTP响应写入器
  • filename: 文件名
  • dispositionType: 处置类型("attachment" 或 "inline")

func SetContentType added in v0.13.5

func SetContentType(w http.ResponseWriter, contentType string)

SetContentType 设置内容类型 参数:

  • w: HTTP响应写入器
  • contentType: 内容类型

func SetHTMLContentType added in v0.13.5

func SetHTMLContentType(w http.ResponseWriter)

SetHTMLContentType 设置HTML内容类型 参数:

  • w: HTTP响应写入器

func SetHeader added in v0.13.5

func SetHeader(w http.ResponseWriter, key, value string)

SetHeader 设置HTTP响应头 参数:

  • w: HTTP响应写入器
  • key: 头信息键名
  • value: 头信息值

func SetJSONContentType added in v0.13.5

func SetJSONContentType(w http.ResponseWriter)

SetJSONContentType 设置JSON内容类型 参数:

  • w: HTTP响应写入器

func SetNoCacheHeaders added in v0.13.5

func SetNoCacheHeaders(w http.ResponseWriter)

SetNoCacheHeaders 设置无缓存头 参数:

  • w: HTTP响应写入器

func SetStatusCode added in v0.13.5

func SetStatusCode(w http.ResponseWriter, code int)

SetStatusCode 设置HTTP状态码 参数:

  • w: HTTP响应写入器
  • code: 状态码

func SetTextContentType added in v0.13.5

func SetTextContentType(w http.ResponseWriter)

SetTextContentType 设置文本内容类型 参数:

  • w: HTTP响应写入器

func SplitAndValidateIPs added in v0.13.5

func SplitAndValidateIPs(s string) []string

SplitAndValidateIPs 分割并验证多个IP地址 该方法会将逗号分隔的IP字符串分割成数组,并验证每个IP的有效性

参数:

  • s: 包含多个IP地址的字符串,用逗号分隔

返回值:

  • []string: 经过验证的有效IP地址列表

func SplitIPs added in v0.13.5

func SplitIPs(s string) []string

SplitIPs 分割多个IP地址字符串 该方法会将逗号分隔的IP字符串分割成数组

参数:

  • s: 包含多个IP地址的字符串,用逗号分隔

返回值:

  • []string: 分割后的IP地址列表

func StrReplace

func StrReplace(search interface{}, replace interface{}, subject interface{}, count int) (interface{}, error)

StrReplace 类似于php中的str_replace

func StringEndWith

func StringEndWith(str, suffix string) bool

StringEndWith 判断字符串是否以某个字符串结尾

func StringStartWith

func StringStartWith(str, prefix string) bool

StringStartWith 判断字符串是否以某个字符串开头

func StructMerge

func StructMerge(dst interface{}, src ...interface{}) error

StructMerge 函数将多个源结构体中的非零值合并到目标结构体中。 源结构体按照传入顺序反向合并,后面的源结构体会覆盖前面的。 目标结构体 (dst) 必须是指向结构体的指针,所有源结构体 (src) 必须是与目标结构体类型相同的指针。

参数:

  • dst: 一个指向目标结构体的指针,非零值将合并到该结构体中。
  • src: 一个变参,包含多个指向源结构体的指针,非零值将从这些源结构体中提取。

返回值:

  • error: 如果 dst 不是指向结构体的指针,或任何 src 元素不是与 dst 类型相同的结构体指针,则返回错误。

func StructToMap

func StructToMap(obj interface{}, useJsonTag bool) map[string]interface{}

StructToMap 通过reflect将结构体转换为map

func TraceCaller added in v0.8.0

func TraceCaller()

TraceCaller 打印当前函数及其调用者的信息。

该函数会获取当前执行的函数名称和调用该函数的位置(文件和行号)。 如果无法获取当前函数或调用者的信息,将会打印错误信息并返回。

注意: - `runtime.Caller(1)` 获取的是TraceCaller的调用者信息。 - `runtime.Caller(2)` 获取的是TraceCaller的调用者的调用者信息,即调用链的上一层。

输出格式为: Function: <当前函数名称> was called from <调用者函数名称>, file: <调用者文件路径>, line: <调用者行号>

func URLDecode added in v0.13.5

func URLDecode(s string) (string, error)

URLDecode 对URL编码的字符串进行解码 参数:

  • s: URL编码的字符串

返回值:

  • string: 解码后的字符串
  • error: 解码错误

func URLEncode added in v0.13.5

func URLEncode(s string) string

URLEncode 对字符串进行URL编码 参数:

  • s: 需要编码的字符串

返回值:

  • string: URL编码后的字符串

func ValidateURL added in v0.13.5

func ValidateURL(urlStr string) bool

ValidateURL 验证URL格式 参数:

  • urlStr: URL字符串

返回值:

  • bool: 如果是有效URL返回true,否则返回false

func WriteHTML added in v0.13.5

func WriteHTML(w http.ResponseWriter, html string) (int, error)

WriteHTML 写入HTML响应 参数:

  • w: HTTP响应写入器
  • html: 要写入的HTML内容

返回值:

  • int: 写入的字节数
  • error: 写入错误

func WriteHTMLWithStatus added in v0.13.5

func WriteHTMLWithStatus(w http.ResponseWriter, code int, html string) (int, error)

WriteHTMLWithStatus 写入HTML响应并设置状态码 参数:

  • w: HTTP响应写入器
  • code: 状态码
  • html: 要写入的HTML内容

返回值:

  • int: 写入的字节数
  • error: 写入错误

func WriteJSON added in v0.13.5

func WriteJSON(w http.ResponseWriter, data interface{}) error

WriteJSON 写入JSON响应 参数:

  • w: HTTP响应写入器
  • data: 要写入的数据

返回值:

  • error: 写入错误

func WriteJSONWithStatus added in v0.13.5

func WriteJSONWithStatus(w http.ResponseWriter, code int, data interface{}) error

WriteJSONWithStatus 写入JSON响应并设置状态码 参数:

  • w: HTTP响应写入器
  • code: 状态码
  • data: 要写入的数据

返回值:

  • error: 写入错误

func WriteString added in v0.13.5

func WriteString(w http.ResponseWriter, s string) (int, error)

WriteString 写入字符串响应 参数:

  • w: HTTP响应写入器
  • s: 要写入的字符串

返回值:

  • int: 写入的字节数
  • error: 写入错误

func WriteStringWithStatus added in v0.13.5

func WriteStringWithStatus(w http.ResponseWriter, code int, s string) (int, error)

WriteStringWithStatus 写入字符串响应并设置状态码 参数:

  • w: HTTP响应写入器
  • code: 状态码
  • s: 要写入的字符串

返回值:

  • int: 写入的字节数
  • error: 写入错误

Types

type ArrStr

type ArrStr struct {
	Arr  []string // 数组
	Sort bool     // 执行ArrayValue方法时是否排序
}

func SetArrStr

func SetArrStr(str []string) *ArrStr

func (*ArrStr) ArrayDiff

func (a *ArrStr) ArrayDiff(oArr ...[]string) (diff []string)

func (*ArrStr) ArrayIntersect

func (a *ArrStr) ArrayIntersect(oArr ...[]string) (intersects []string)

func (*ArrStr) ArrayValue

func (a *ArrStr) ArrayValue() (value []string)

func (*ArrStr) DoSort

func (a *ArrStr) DoSort() *ArrStr

DoSort 设置ArrayValue方法¬是否排序

type Convert

type Convert struct {
	Value interface{}
}

func (Convert) ToArrByte

func (c Convert) ToArrByte() []byte

ToArrByte 将变量转为[]byte类型

func (Convert) ToBool

func (c Convert) ToBool() bool

ToBool 将变量转为bool类型

func (Convert) ToDuration added in v0.13.5

func (c Convert) ToDuration() time.Duration

ToDuration 将变量转为time.Duration类型 支持从字符串、整数、浮点数等类型转换

func (Convert) ToFileMode

func (c Convert) ToFileMode() os.FileMode

ToFileMode 将变量转为os.FileMode类型

func (Convert) ToFloat64

func (c Convert) ToFloat64() float64

ToFloat64 将变量转为float64

func (Convert) ToInt

func (c Convert) ToInt() int

ToInt 将变量转为int类型

func (Convert) ToInt8 added in v0.11.1

func (c Convert) ToInt8() int8

ToInt8 将变量转为int8类型

func (Convert) ToInt64 added in v0.8.0

func (c Convert) ToInt64() int64

ToInt64 将变量转为int64类型

func (Convert) ToInterface added in v0.13.5

func (c Convert) ToInterface() interface{}

ToInterface 将变量转为interface{}类型,主要用于类型断言前的准备 此方法主要用于保持类型一致性,实际返回原始值

func (Convert) ToMap added in v0.13.5

func (c Convert) ToMap() map[string]interface{}

ToMap 将变量转为map[string]interface{}类型 支持从JSON字符串、结构体、map等类型转换

func (Convert) ToMapString added in v0.13.7

func (c Convert) ToMapString() map[string]string

ToMapString 将变量转为map[string]string类型 支持从JSON字符串、结构体、map等类型转换,所有值都会被转换为字符串

func (Convert) ToNumber

func (c Convert) ToNumber() (interface{}, bool)

ToNumber 将字符串变量转为数字类型

func (Convert) ToReflectValue added in v0.13.8

func (c Convert) ToReflectValue(t reflect.Type) (reflect.Value, bool)

ToReflectValue 将任意值按目标反射类型转换为可赋值的 reflect.Value 函数名:ToReflectValue 参数: - t reflect.Type — 目标类型(切片元素类型、映射值类型等) - 使用接收者 c.Value 作为原始输入值,可能是字符串、数字、布尔或时间 返回值: - reflect.Value — 转换后可赋值的值(与 t 匹配) - bool — 当发生类型不支持或位宽溢出时返回 false 异常:不触发panic 说明: - 支持 string/bool/int*/uint*/float*/time.Duration/time.Time 的转换 - 对整型/无符号/浮点类型做溢出检查,保证赋值安全

func (Convert) ToSlice added in v0.13.5

func (c Convert) ToSlice() []interface{}

ToSlice 将变量转为[]interface{}类型 支持从数组、切片、JSON字符串等类型转换

func (Convert) ToString

func (c Convert) ToString() string

ToString 将变量转为字符串 浮点型 3.0将会转换成字符串3, "3" 非数值或字符类型的变量将会被转换成JSON格式字符串

func (Convert) ToTime added in v0.13.5

func (c Convert) ToTime() time.Time

ToTime 将变量转为time.Time类型

func (Convert) ToUint

func (c Convert) ToUint() uint

ToUint 将变量转为uint类型

func (Convert) ToUint64 added in v0.8.0

func (c Convert) ToUint64() uint64

ToUint64 将变量转为uint64类型

type File

type File struct {
	Path string      `json:"path"`
	Perm os.FileMode `json:"perm" default:"0755"`
}

func NewFile

func NewFile(args ...any) *File

func (*File) Basename

func (fh *File) Basename(suffix string) string

Basename 返回路径的最后一个名字组件

func (*File) CopyFile

func (fh *File) CopyFile(targetPath string, overwrite bool, copyAttr bool) error

CopyFile 复制文件到指定位置,可设置是否覆盖,可设置是否复制文件属性

func (*File) CopyFileAttr

func (fh *File) CopyFileAttr(targetFile string) error

CopyFileAttr 复制文件属性到目标文件

func (*File) CreateFile

func (fh *File) CreateFile(content []byte, overwrite bool) error

CreateFile 创建文件,可设置文件权限,可设置是否覆盖

func (*File) DirExists

func (fh *File) DirExists(createIfNotExists bool) (exists bool, err error)

DirExists 判断目录是否存在,可选在不存在时是否创建目录

func (*File) DirName

func (fh *File) DirName() string

DirName 获取目录部分

func (*File) Exists

func (fh *File) Exists() bool

Exists 检查文件是否存在

func (*File) GetAbsPath

func (fh *File) GetAbsPath() (string, error)

GetAbsPath 获取绝对路径

func (*File) IsDir

func (fh *File) IsDir() bool

IsDir 判断是否是目录

func (*File) IsEmpty

func (fh *File) IsEmpty() bool

IsEmpty 判断文件或目录是否为空

func (*File) IsEmptyDir

func (fh *File) IsEmptyDir() bool

IsEmptyDir 判断目录是否为空

返回值: 目录存在且不含任何条目时为 true;路径不存在、不是目录或无权限读取时为 false。 说明: f.Readdirnames(1) 读到目录末尾(即空目录)返回的是 io.EOF,不是 os.ErrNotExist。 行为变更(自 v0.17.0 起): 旧版本误用 os.ErrNotExist 判定,空目录会错误地返回 false;现版本空目录正确返回 true。

func (*File) IsEmptyFile

func (fh *File) IsEmptyFile() bool

IsEmptyFile 判断文件是否为空

func (*File) IsExecutable

func (fh *File) IsExecutable() bool

IsExecutable 判断文件是否可执行

返回值: 路径指向一个可执行文件时为 true;路径不存在或指向目录时为 false。 说明: Unix/macOS 检查权限位的可执行位(0111,任一主体); Windows 权限位不表达可执行性,改为按扩展名(.exe/.bat/.cmd/.com)判定。 行为变更(自 v0.17.0 起): 旧版本仅尝试以只读方式打开文件,目录也总是返回 true;现版本目录返回 false, 且 Unix 改按权限位、Windows 改按扩展名判定,普通数据文件不再被误判为可执行。

func (*File) IsFile

func (fh *File) IsFile() bool

IsFile 判断是否是文件

func (*File) IsHidden

func (fh *File) IsHidden() bool

IsHidden 判断文件是否隐藏

func (*File) IsReadable

func (fh *File) IsReadable() bool

IsReadable 判断文件是否可读

func (fh *File) IsSymlink() bool

IsSymlink 判断是否是软链接

func (*File) IsWritable

func (fh *File) IsWritable() bool

IsWritable 判断文件是否可写

func (*File) JsonToData

func (fh *File) JsonToData(data *interface{}) error

JsonToData 将文件中的json数据解析到data中

func (*File) Remove

func (fh *File) Remove() error

Remove 删除文件或目录

type HTTPClientConfig added in v0.13.5

type HTTPClientConfig struct {
	Timeout    time.Duration
	ProxyURL   string
	UserAgent  string
	SkipVerify bool
}

HTTPClientConfig HTTP客户端配置

type HTTPRequestConfig added in v0.13.5

type HTTPRequestConfig struct {
	Method  string
	URL     string
	Headers map[string]string
	Body    []byte
	Timeout time.Duration
}

HTTPRequestConfig HTTP请求配置

type IP added in v0.13.5

type IP struct {
	IP string
}

IP 提供IP地址处理相关的工具函数

func NewIP added in v0.13.5

func NewIP(ip string) *IP

NewIP 创建一个新的IP实例 参数:

  • ip: IP地址字符串

返回值:

  • *IP: IP实例指针

func (*IP) IsAllowed added in v0.13.5

func (ip *IP) IsAllowed(whitelist, blacklist []string) bool

IsAllowed 检查IP是否被允许(基于白名单和黑名单) 参数:

  • whitelist: IP白名单列表,如果提供则只允许白名单内的IP
  • blacklist: IP黑名单列表,如果提供则拒绝黑名单内的IP

返回值:

  • bool: 如果IP被允许返回true,否则返回false

func (*IP) IsInCIDR added in v0.13.5

func (ip *IP) IsInCIDR(cidr string) bool

IsInCIDR 检查IP是否在CIDR范围内 参数:

  • cidr: CIDR表示法(如 "192.168.1.0/24" 或 "2001:db8::/32")

返回值:

  • bool: 如果IP在CIDR范围内返回true,否则返回false

func (*IP) IsLoopback added in v0.13.5

func (ip *IP) IsLoopback() bool

IsLoopback 检查是否为本地回环地址 参数:

  • 无

返回值:

  • bool: 如果是回环地址返回true,否则返回false

func (*IP) IsPrivate added in v0.13.5

func (ip *IP) IsPrivate() bool

IsPrivate 检查是否为私有IP地址 参数:

  • 无

返回值:

  • bool: 如果是私有地址返回true,否则返回false

func (*IP) IsValid added in v0.13.5

func (ip *IP) IsValid() bool

IsValid 验证IP地址是否有效 参数:

  • 无

返回值:

  • bool: 如果IP有效返回true,否则返回false

type JsonHelper

type JsonHelper struct {
	Struct interface{}            // 结构体
	String string                 // JSON字符串
	Map    map[string]interface{} // Map
	// contains filtered or unexported fields
}

func Json

func Json(input interface{}) *JsonHelper

Json 根据传入的未知类型实例化JsonHelper

func JsonFile

func JsonFile(path string) *JsonHelper

JsonFile 根据传入的文件路径读取JSON文件并实例化JsonHelper

func JsonMap deprecated

func JsonMap(jsonMap map[string]interface{}) *JsonHelper

Deprecated: 使用 Json 代替

func JsonString deprecated

func JsonString(jsonString string) *JsonHelper

Deprecated: 使用 Json 代替

func JsonStruct deprecated

func JsonStruct(jsonStruct interface{}) *JsonHelper

Deprecated: 使用 Json 代替

func (*JsonHelper) Errors

func (jh *JsonHelper) Errors() []error

Errors 获取错误信息列表

func (*JsonHelper) HasError

func (jh *JsonHelper) HasError() bool

HasError 判断是否有错误

func (*JsonHelper) MakeFile

func (jh *JsonHelper) MakeFile(filepath string) *JsonHelper

MakeFile 设置是否生成JSON文件及其路径

func (*JsonHelper) ToFile

func (jh *JsonHelper) ToFile() *JsonHelper

ToFile 将JSON字符串输出为文件

func (*JsonHelper) ToMap

func (jh *JsonHelper) ToMap(newMap *map[string]interface{}) *JsonHelper

ToMap 将JSON字符串或结构体转换为Map

func (*JsonHelper) ToString

func (jh *JsonHelper) ToString(newStr *string) *JsonHelper

ToString 将结构体或Map转换为JSON字符串

func (*JsonHelper) ToStruct

func (jh *JsonHelper) ToStruct(newStruct interface{}) *JsonHelper

ToStruct 将JSON数据转换为结构体

type MapHelper

type MapHelper struct {
	Data map[string]interface{}
	Keys []string
	Sort bool
}

func NewMap

func NewMap(mapData map[string]interface{}) *MapHelper

func (*MapHelper) ArrayKeys

func (d *MapHelper) ArrayKeys() []string

func (*MapHelper) ArrayValues

func (d *MapHelper) ArrayValues() []interface{}

func (*MapHelper) DoSort

func (d *MapHelper) DoSort() *MapHelper

func (*MapHelper) Extract added in v0.13.5

func (d *MapHelper) Extract(path string, defaultVal ...interface{}) interface{}

Extract 从多级map中提取任意类型的字段值 - path: 字段路径,使用点号分隔,如 "data.member_data.age" - defaultVal: 默认值,当路径不存在或类型不匹配时返回该默认值 返回:提取到的原始值,如果路径不存在返回nil

func (*MapHelper) ExtractBool added in v0.13.5

func (d *MapHelper) ExtractBool(path string, defaultVal ...bool) bool

ExtractBool 从多级map中提取布尔字段值 - path: 字段路径,使用点号分隔,如 "data.member_data.is_active" - defaultVal: 默认值,当路径不存在或类型不匹配时返回该默认值 返回:提取到的布尔值,如果路径不存在或类型不匹配返回false

func (*MapHelper) ExtractFloat64 added in v0.13.5

func (d *MapHelper) ExtractFloat64(path string, defaultVal ...float64) float64

ExtractFloat64 从多级map中提取浮点数字段值 - path: 字段路径,使用点号分隔,如 "data.member_data.salary" - defaultVal: 默认值,当路径不存在或类型不匹配时返回该默认值 返回:提取到的浮点数值,如果路径不存在或类型不匹配返回0.0

func (*MapHelper) ExtractInt added in v0.13.5

func (d *MapHelper) ExtractInt(path string, defaultVal ...int) int

ExtractInt 从多级map中提取整数字段值 - path: 字段路径,使用点号分隔,如 "data.member_data.age" - defaultVal: 默认值,当路径不存在或类型不匹配时返回该默认值 返回:提取到的整数值,如果路径不存在或类型不匹配返回0

func (*MapHelper) ExtractInt64 added in v0.13.5

func (d *MapHelper) ExtractInt64(path string, defaultVal ...int64) int64

ExtractInt64 从多级map中提取64位整数字段值 - path: 字段路径,使用点号分隔,如 "data.member_data.big_id" - defaultVal: 默认值,当路径不存在或类型不匹配时返回该默认值 返回:提取到的64位整数值,如果路径不存在或类型不匹配返回0

func (*MapHelper) ExtractString added in v0.13.5

func (d *MapHelper) ExtractString(path string, defaultVal ...string) string

ExtractString 从多级map中提取字符串字段值 - path: 字段路径,使用点号分隔,如 "data.member_data.gender_text" - defaultVal: 默认值,当路径不存在或类型不匹配时返回该默认值 返回:提取到的字符串值,如果路径不存在或类型不匹配返回空字符串

func (*MapHelper) ExtractStringSlice added in v0.13.5

func (d *MapHelper) ExtractStringSlice(path string, defaultVal ...[]string) []string

ExtractStringSlice 从多级map中提取字符串切片字段值 - path: 字段路径,使用点号分隔,如 "data.member_data.tags" - defaultVal: 默认值,当路径不存在或类型不匹配时返回该默认值 返回:提取到的字符串切片,如果路径不存在或类型不匹配返回空切片

func (*MapHelper) ExtractTime added in v0.13.5

func (d *MapHelper) ExtractTime(path string, defaultVal ...time.Time) time.Time

ExtractTime 从多级map中提取时间字段值 - path: 字段路径,使用点号分隔,如 "data.member_data.created_at" - defaultVal: 默认值,当路径不存在或类型不匹配时返回该默认值 返回:提取到的时间值,如果路径不存在或类型不匹配返回零值时间

func (*MapHelper) GetData

func (d *MapHelper) GetData() map[string]interface{}

type MoneyHelper

type MoneyHelper struct {
	Amount int64 `json:"amount" default:"0"` // 单位为厘,1000为1元
	// contains filtered or unexported fields
}

func Money

func Money(input interface{}) *MoneyHelper

func (*MoneyHelper) Add

func (m *MoneyHelper) Add(other *MoneyHelper) *MoneyHelper

Add 加法操作

func (*MoneyHelper) Divide

func (m *MoneyHelper) Divide(divisor float64) *MoneyHelper

Divide 除法操作

func (*MoneyHelper) Equals

func (m *MoneyHelper) Equals(other *MoneyHelper) bool

Equals 比较相等

func (*MoneyHelper) FloatString

func (m *MoneyHelper) FloatString(parts ...string) string

FloatString 输出字符串金额,接受前缀和后缀 参数:

parts - 可变参数列表,第一个参数表示前缀,第二个参数表示后缀,如果省略则不添加

func (*MoneyHelper) GetError

func (m *MoneyHelper) GetError() error

GetError 返回当前的错误

func (*MoneyHelper) GreaterThan

func (m *MoneyHelper) GreaterThan(other *MoneyHelper) bool

GreaterThan 比较大小

func (*MoneyHelper) LessThan

func (m *MoneyHelper) LessThan(other *MoneyHelper) bool

LessThan 比较大小

func (*MoneyHelper) Multiply

func (m *MoneyHelper) Multiply(factor float64) *MoneyHelper

Multiply 乘法操作

func (*MoneyHelper) SetAmount

func (m *MoneyHelper) SetAmount(value interface{}) *MoneyHelper

SetAmount 设置金额,接受不同格式的输入

func (*MoneyHelper) Subtract

func (m *MoneyHelper) Subtract(other *MoneyHelper) *MoneyHelper

Subtract 减法操作

type Str

type Str struct {
	String  string
	Float64 float64
	Float32 float32
	Int64   int64
	Int32   int32
	Int16   int16
	Int8    int8
	Int     int
	Uint64  uint64
	Uint32  uint32
	Uint16  uint16
	Uint8   uint8
	Uint    uint
}

func NewStr

func NewStr(str string) *Str

func (*Str) Base64UrlDecode

func (s *Str) Base64UrlDecode() (string, error)

Base64UrlDecode 解码 URL 和文件名安全的 Base64 编码字符串

func (*Str) Base64UrlEncode

func (s *Str) Base64UrlEncode() string

Base64UrlEncode 对字符串进行 URL 和文件名安全的 Base64 编码

func (*Str) ByteLength

func (s *Str) ByteLength() int

ByteLength 返回给定字符串的字节数

func (*Str) ByteSubstr

func (s *Str) ByteSubstr(start int, length int) string

ByteSubstr 返回从 start 开始、长度为 length 的子字符串

func (*Str) ConvertBetweenUnits added in v0.13.5

func (s *Str) ConvertBetweenUnits(value float64, fromUnit, toUnit string, unitType UnitType) (*Str, error)

ConvertBetweenUnits 在不同单位之间转换数值并返回新的Str对象

参数:

  • value: 原始数值
  • fromUnit: 原始单位符号
  • toUnit: 目标单位符号
  • unitType: 单位类型

返回值:

  • *Str: 包含转换后数值的Str对象
  • error: 转换过程中的错误

示例:

  • s := NewStr(""); s.ConvertBetweenUnits(10, "MB", "KB", UnitTypeStorage) -> NewStr("10240"), nil

func (*Str) ConvertCamelToSnake

func (s *Str) ConvertCamelToSnake() string

ConvertCamelToSnake 转换驼峰字符串为下划线字符串

func (*Str) CountWords

func (s *Str) CountWords() int

CountWords 计算字符串中的单词数

func (*Str) EndsWith

func (s *Str) EndsWith(suffix string, caseSensitive bool) bool

EndsWith 检查字符串是否以指定的子字符串结尾

func (*Str) EscapeHTML

func (s *Str) EscapeHTML() string

EscapeHTML escapes HTML characters in the value to prevent XSS

func (*Str) Explode

func (s *Str) Explode(delimiter string, trim bool, skipEmpty bool) []string

Explode 按分隔符分割字符串,选项修剪值并跳过空值

func (*Str) FloatToString

func (s *Str) FloatToString() *Str

FloatToString 安全地将浮点数转换为字符串

func (*Str) FormatAsUnit added in v0.13.5

func (s *Str) FormatAsUnit(value float64, unitType UnitType, precision int, toUnit ...string) *Str

FormatAsUnit 将数值格式化为带单位的字符串

参数:

  • value: 数值(以基础单位表示)
  • unitType: 单位类型
  • precision: 小数位数精度
  • toUnit: 输出格式("auto"自动选择单位或具体单位符号)

返回值:

  • *Str: 新的Str实例,包含格式化后的字符串

示例:

  • s := NewStr(""); s.FormatAsUnit(10485760, UnitTypeStorage, 2, "auto") -> "10.00MB"
  • s := NewStr(""); s.FormatAsUnit(10485760, UnitTypeStorage, 0, "KB") -> "10240KB"

func (*Str) GetUnitTypeFromString added in v0.13.5

func (s *Str) GetUnitTypeFromString(unitType UnitType) (UnitType, error)

GetUnitTypeFromString 获取字符串中单位的类型

参数:

  • unitType: 单位类型

返回值:

  • UnitType: 单位类型
  • error: 解析错误

示例:

  • s := NewStr("10MB"); s.GetUnitTypeFromString(UnitTypeStorage) -> UnitTypeStorage, nil

func (*Str) IsNumeric added in v0.13.12

func (s *Str) IsNumeric(strict ...bool) bool

IsNumeric 检查字符串是否为有效的数字

参数:

  • strict: 是否启用严格模式。严格模式下只接受整数,宽松模式下接受整数和浮点数(可选,默认为false)

返回值:

  • bool: 如果是有效的数字返回true,否则返回false

示例:

  • s := NewStr("123"); s.IsNumeric() -> true
  • s := NewStr("123.45"); s.IsNumeric() -> true
  • s := NewStr("123.45"); s.IsNumeric(true) -> false(严格模式不接受浮点数)
  • s := NewStr("abc"); s.IsNumeric() -> false

func (*Str) IsUnitString added in v0.13.5

func (s *Str) IsUnitString(unitType UnitType) bool

IsUnitString 检查字符串是否为有效的单位字符串

参数:

  • unitType: 单位类型

返回值:

  • bool: 是否为有效的单位字符串

示例:

  • s := NewStr("MB"); s.IsUnitString(UnitTypeStorage) -> true
  • s := NewStr("invalid"); s.IsUnitString(UnitTypeStorage) -> false

func (*Str) MbUcFirst

func (s *Str) MbUcFirst() string

MbUcFirst 将字符串的第一个字符大写(支持多字节)

func (*Str) MbUcWords

func (s *Str) MbUcWords() string

MbUcWords 将字符串中的每个单词的第一个字符大写(支持多字节)

func (*Str) ParseUnit added in v0.13.5

func (s *Str) ParseUnit(unitType UnitType) (float64, *Unit, error)

ParseUnit 解析字符串中的单位信息 ParseUnit parses unit information from string

参数:

  • unitType: 单位类型

返回值:

  • float64: 解析出的数值(以基础单位表示)
  • *Unit: 单位信息
  • error: 解析过程中的错误

示例:

  • s := NewStr("10MB"); s.ParseUnit(UnitTypeStorage) -> 10485760, &Unit{...}, nil
  • s := NewStr("1h"); s.ParseUnit(UnitTypeTime) -> 3600000000000, &Unit{...}, nil
  • s := NewStr("8b"); s.ParseUnit(UnitTypeData) -> 1, &Unit{...}, nil

func (*Str) SetFloat64

func (s *Str) SetFloat64(number float64) *Str

SetFloat64 设置float64值

func (*Str) StartsWith

func (s *Str) StartsWith(prefix string, caseSensitive bool) bool

StartsWith 检查字符串是否以指定的子字符串开头

func (*Str) ToLower

func (s *Str) ToLower() string

ToLower converts the value to a lower case string

func (*Str) ToUnitValue added in v0.13.5

func (s *Str) ToUnitValue(unitType UnitType) (float64, error)

ToUnitValue 将字符串转换为基础单位的数值

参数:

  • unitType: 单位类型

返回值:

  • float64: 转换后的数值(以基础单位表示)
  • error: 转换过程中的错误

示例:

  • s := NewStr("10MB"); s.ToUnitValue(UnitTypeStorage) -> 10485760, nil

func (*Str) ToUpper

func (s *Str) ToUpper() string

ToUpper converts the value to an upper case string

func (*Str) Trim

func (s *Str) Trim(cutSet string) string

Trim returns a slice of the string s with all leading and trailing Unicode code points contained in cutSet removed.

func (*Str) TrimSpace

func (s *Str) TrimSpace() string

TrimSpace removes leading and trailing white spaces from the value

func (*Str) Truncate

func (s *Str) Truncate(length int, suffix string) string

Truncate 将字符串截断为指定的字符数

func (*Str) TruncateWords

func (s *Str) TruncateWords(count int, suffix string) string

TruncateWords 将字符串截断为指定的单词数

type Unit added in v0.13.5

type Unit struct {
	Name     string   // 单位名称
	Symbols  []string // 单位符号(支持多种表示方式)
	Factor   float64  // 转换因子(相对于基础单位)
	UnitType UnitType // 单位类型
}

Unit 定义单位结构 Unit defines the unit structure

func ParseUnitString added in v0.13.5

func ParseUnitString(str string, unitType UnitType) (float64, *Unit, error)

ParseUnitString 解析包含单位的字符串,返回数值和单位信息 ParseUnitString parses a string containing units and returns the numeric value and unit information

参数:

  • str: 包含单位的字符串,如 "10MB", "5.5s", "1.2KB"
  • unitType: 单位类型

返回值:

  • float64: 转换后的数值(以基础单位表示)
  • *Unit: 解析出的单位信息
  • error: 解析过程中的错误

示例:

  • ParseUnitString("10MB", UnitTypeStorage) -> 10485760, Unit{Name: "Megabyte", ...}, nil
  • ParseUnitString("5.5s", UnitTypeTime) -> 5500000000, Unit{Name: "Second", ...}, nil
  • ParseUnitString("8byte", UnitTypeData) -> 64, Unit{Name: "Byte", ...}, nil

type UnitType added in v0.13.5

type UnitType int

UnitType 定义单位类型 UnitType defines the type of unit

const (
	// UnitTypeStorage 存储单位类型
	// UnitTypeStorage storage unit type
	UnitTypeStorage UnitType = iota
	// UnitTypeTime 时间单位类型
	// UnitTypeTime time unit type
	UnitTypeTime
	// UnitTypeData 数据单位类型(位/字节)
	// UnitTypeData data unit type (bit/byte)
	UnitTypeData
)

func GetUnitType added in v0.13.5

func GetUnitType(unitStr string, unitType UnitType) (UnitType, error)

GetUnitType 获取单位的类型 GetUnitType gets the type of a unit

参数:

  • unitStr: 单位字符串
  • unitType: 单位类型

返回值:

  • UnitType: 单位类型
  • error: 解析错误

示例:

  • GetUnitType("MB", UnitTypeStorage) -> UnitTypeStorage, nil
  • GetUnitType("h", UnitTypeTime) -> UnitTypeTime, nil
  • GetUnitType("b", UnitTypeData) -> UnitTypeData, nil

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL