utils

package module
v1.22.19 Latest Latest
Warning

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

 Go to latest Published: May 13, 2026 License: Apache-2.0 Imports: 51 Imported by: 0

README

go-utils

介绍

golang 帮助函数

安装教程

  1. github安装 go get -u github.com/Is999/go-utils

  2. gitee安装 go get -u gitee.com/Is999/go-utils

使用说明
  1. utils 包已按“生产默认安全、历史兼容显式开启”的原则整理；落地生产前仍需结合业务协议、密钥管理、日志合规和调用方并发模型做最终评审。
  2. 版本要求golang 1.22
最终交付说明

本次交付保留原 README 既有标准库与工具函数说明，并在代码实现侧完成安全性、并发性、性能边界和文档一致性整改。核心结论如下：

模块 生产级结论
AES / DES AES 推荐 GCM；CBC 必须显式 WithIV(...) 或 WithRandIV(true)；CTR/CFB/OFB、ECB、默认 key 派生 IV 默认禁用。DES/3DES 仅保留历史兼容，不建议新系统使用。
RSA 生成和导入密钥均要求至少 2048 位；推荐 EncryptOAEP/DecryptOAEP 与 SignPSS/VerifyPSS；PKCS#1 v1.5 仅用于旧协议兼容；签名拒绝 MD5/SHA1。
PKCS7 / Zero Pkcs7UnPadding 严格校验填充字节；ZeroPadding 仅适合能接受尾部 0 歧义的旧协议。
Pool / Once Pool[T] 基于 sync.Pool，支持归还前 reset；Once 并发安全，失败按有限指数退避重试，结果会缓存，需重新执行时调用 Reset。
Retry Retry 使用 capped exponential backoff + jitter：第一次失败后约 100ms~200ms，最多 3s；maxRetries=0 时只执行 1 次。
IP / Logger ClientIP 仅在远端为可信代理时读取转发头；生产建议使用 ClientIPWithTrustedProxies。默认 logger 基于 log/slog 并发安全，自定义 logger 也应保证并发安全。
slices / string / map 常用函数无共享可变全局状态；传入的 slice/map 若被外部并发修改，调用方需自行加锁。
tar / zip 解压防 Zip Slip/Tar Slip，拒绝绝对路径、目录穿越、空字符、符号链接和特殊文件；限制条目数、单文件大小和总展开大小。
errors 支持栈追踪、错误码、上下文键值、errors.Join、文本/JSON/slog 输出；全局配置使用原子变量并发安全。
curl 继承标准库默认 Transport 连接池/TLS 行为；Header 按请求克隆；可回放 body 才会重试；默认日志 body 为预览上限；支持 Clone/NewRequest 派生独立请求实例并复用连接池。
response 状态码只写一次；Content-Type 自动规范化；下载文件名清洗 CR/LF 和路径；文件输出拒绝目录。

本次验证命令：

go test ./...
go vet ./...
go test -race ./...
全局配置 Configure

Configure 是全局配置入口，只需在程序入口处（如 main 函数）调用一次。支持自定义 JSON 编解码器和自定义 Logger。

import utils "github.com/Is999/go-utils"

func main() {
utils.Configure(
utils.WithJSON(json.Marshal, json.Unmarshal), // 可选：自定义 JSON 编解码器
utils.WithLogger(yourLogger), // 可选：自定义 Logger
)
}
JSON 编解码配置

通过 WithJSON 设置自定义的 JSON 编解码方法（如 sonic、go-json 等高性能库），若未设置则默认使用标准库 encoding/json。

import "github.com/bytedance/sonic"

utils.Configure(utils.WithJSON(sonic.Marshal, sonic.Unmarshal))

设置后，使用 utils.Marshal() 和 utils.Unmarshal() 即会调用自定义的编解码器。

Logger 配置

通过 WithLogger 设置自定义 Logger，若未设置则默认使用标准库 log/slog。

Logger 接口定义如下，实现 6 个方法即可集成任何第三方日志库（如 zap、logrus 等）：

type Logger interface {
Debug(msg string, args ...any)
Info(msg string, args ...any)
Warn(msg string, args ...any)
Error(msg string, args ...any)
With(args ...any) Logger
Enabled(ctx context.Context, level LogLevel) bool
}

日志级别定义（与 slog.Level 值一致）：

const (
LevelDebug LogLevel = -4
LevelInfo  LogLevel = 0
LevelWarn  LogLevel = 4
LevelError LogLevel = 8
)
集成 Zap 示例
import (
"context"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
utils "github.com/Is999/go-utils"
)

type zapLoggerAdapter struct {
logger *zap.SugaredLogger
}

func (z *zapLoggerAdapter) Debug(msg string, args ...any) { z.logger.Debugw(msg, args...) }
func (z *zapLoggerAdapter) Info(msg string, args ...any)  { z.logger.Infow(msg, args...) }
func (z *zapLoggerAdapter) Warn(msg string, args ...any)  { z.logger.Warnw(msg, args...) }
func (z *zapLoggerAdapter) Error(msg string, args ...any) { z.logger.Errorw(msg, args...) }

func (z *zapLoggerAdapter) With(args ...any) utils.Logger {
return &zapLoggerAdapter{logger: z.logger.With(args...)}
}

func (z *zapLoggerAdapter) Enabled(ctx context.Context, level utils.LogLevel) bool {
var zapLevel zapcore.Level
switch level {
case utils.LevelDebug:
zapLevel = zapcore.DebugLevel
case utils.LevelInfo:
zapLevel = zapcore.InfoLevel
case utils.LevelWarn:
zapLevel = zapcore.WarnLevel
case utils.LevelError:
zapLevel = zapcore.ErrorLevel
default:
zapLevel = zapcore.InfoLevel
}
return z.logger.Desugar().Core().Enabled(zapLevel)
}

func main() {
zapLogger, _ := zap.NewProduction()
utils.Configure(utils.WithLogger(&zapLoggerAdapter{logger: zapLogger.Sugar()}))
}
集成 Logrus 示例
import (
"context"
"github.com/sirupsen/logrus"
utils "github.com/Is999/go-utils"
)

type logrusLoggerAdapter struct {
logger *logrus.Logger
fields logrus.Fields
}

func (l *logrusLoggerAdapter) entry() *logrus.Entry {
if len(l.fields) > 0 {
return l.logger.WithFields(l.fields)
}
return logrus.NewEntry(l.logger)
}

func (l *logrusLoggerAdapter) Debug(msg string, args ...any) {
l.entry().WithFields(argsToFields(args)).Debug(msg)
}
func (l *logrusLoggerAdapter) Info(msg string, args ...any) {
l.entry().WithFields(argsToFields(args)).Info(msg)
}
func (l *logrusLoggerAdapter) Warn(msg string, args ...any) {
l.entry().WithFields(argsToFields(args)).Warn(msg)
}
func (l *logrusLoggerAdapter) Error(msg string, args ...any) {
l.entry().WithFields(argsToFields(args)).Error(msg)
}

func (l *logrusLoggerAdapter) With(args ...any) utils.Logger {
newFields := argsToFields(args)
merged := make(logrus.Fields, len(l.fields)+len(newFields))
for k, v := range l.fields {
merged[k] = v
}
for k, v := range newFields {
merged[k] = v
}
return &logrusLoggerAdapter{logger: l.logger, fields: merged}
}

func (l *logrusLoggerAdapter) Enabled(_ context.Context, level utils.LogLevel) bool {
var logrusLevel logrus.Level
switch level {
case utils.LevelDebug:
logrusLevel = logrus.DebugLevel
case utils.LevelInfo:
logrusLevel = logrus.InfoLevel
case utils.LevelWarn:
logrusLevel = logrus.WarnLevel
case utils.LevelError:
logrusLevel = logrus.ErrorLevel
default:
logrusLevel = logrus.InfoLevel
}
return l.logger.IsLevelEnabled(logrusLevel)
}

func argsToFields(args []any) logrus.Fields {
fields := make(logrus.Fields)
for i := 0; i < len(args)-1; i += 2 {
if key, ok := args[i].(string); ok {
fields[key] = args[i+1]
}
}
return fields
}

func main() {
logrusLogger := logrus.New()
utils.Configure(utils.WithLogger(&logrusLoggerAdapter{logger: logrusLogger}))
}
Error 追踪与第三方日志库配合

errors 包提供了多种方式获取错误追踪信息，兼容不同日志库：

import "github.com/Is999/go-utils/errors"

err := errors.Wrap(originalErr, "操作失败")

// 方式1: 使用 slog（默认日志库），Trace 返回 slog.LogValuer 接口
slog.Error(err.Error(), "trace", errors.Trace(err))

// 方式2: 使用第三方日志库（zap/logrus 等），TraceString 返回简洁字符串
logger.Error("操作失败", "error", err.Error(), "trace", errors.TraceString(err))

// 方式3: 获取完整 JSON 格式追踪（含嵌套 wrap 信息）
logger.Error("操作失败", "error", err.Error(), "trace", errors.TraceJSON(err))

// 方式4: 使用 fmt 格式化
fmt.Sprintf("%+v", err) // 等同于 TraceJSON
fmt.Sprintf("%#v", err) // 等同于 TraceJSON
历史变更
  1. 版本要求golang 1.18变更为1.22
  2. 移除了1.21 版本前的Max、Min 两个函数，推荐使用golang 内置函数 max、min
  3. 移除了1.21 版本前的Logger 文件，使用标准库中 log/slog
  4. Curl 和 Response 记录日志方式使用了标准库 log/slog记录日志
  5. 根据1.21版本 log/slog 增加了errors文件，实现了LogValuer 接口，对error的日志追踪
  6. utils中返回的error 统一使用了WrapError, 支持error记录追踪
  7. RSA加密解密增加了对长文本的支持，增加了对PEM key 去除头尾标记和还原头尾标记方法
  8. math/rand 改1.22版本 math/rand/v2, 部分函数形参 rand.Source 改为*rand.Rand
  9. Strtotime函数增强，支持更多时间格式自动解析（毫秒、微秒、纳秒格式）
  10. Response模块使用 Header 方法（修复 Herder 拼写错误，当前仅保留 Header 方法）
  11. 修复types.go中"有符合"拼写错误，更正为"有符号"
  12. 新增 Retry 函数，支持带指数退避的重试机制
  13. 新增 Once 结构体，线程安全的带重试机制的一次性执行
  14. 新增泛型对象池 Pool[T]，基于 sync.Pool 封装，支持自定义重置函数
  15. 新增 SumSlice 切片求和、SumMap Map值求和函数
  16. 新增 Configure 全局配置入口，支持自定义 JSON 编解码器和 Logger
  17. 新增 GetFunctionName 获取函数名函数
  18. 修复 IsFile 对不存在路径错误返回 true 的bug
  19. 修复 tar.go/zip.go 中 strings.TrimRight 误用为 strings.TrimSuffix
  20. 修复 cipher.go 中 Decrypt 注释错误（"加密"更正为"解密"）
  21. 修复 response.go 中 Content-Disposition filename 未加引号导致含空格文件名异常
  22. 修复 file.go 中路径分隔符硬编码问题，改用 filepath.Separator
  23. 优化 rsa.go 中 strings.Index 为更符合语义的 strings.Contains，strings.Replace 为 strings.ReplaceAll

Go常用标准库方法及utils包帮助函数

开发中使用频率较高的Go标准库中的方法及utils包中的帮助方法。utils包中的方法都可以在单元测试中找到使用方法示例。版本要求 >= 1.22版本。

注意：utils包中代码仅供参考，不建议用于商业生产，造成损失概不负责。

1. 字符串

​ strings 和 bytes 两个包对字符串的操作基本相同拥有相同的方法名称和参数，只是参数类型的不同。

1.1 截取字符串

推荐：包含中文（宽字符）时，使用 string转rune切片截取字符串。

type string
string[start: end]
参数 描述
string 原字符串。
start 表示要截取的第一个字符所在的索引（截取时包含该字符）。如果不指定，默认为 0，也就是从字符串的开头截取。
end 表示要截取的最后一个字符所在的索引（截取时不包含该字符）。如果不指定，默认为字符串的长度。
func utils.Substr
func Substr(str string, start, length int) string
参数 描述
str 原字符串。
start 截取的起始位置，即截取的第一个字符所在的索引：
start小于0时，start = len(str) + start
length 截取的截止位置，即截取的最后一个字符所在的索引：
length大于0时，length表示为截取子字符串的长度，截取的最后一个字符所在的索引，值为：start + length 。
length小于0时，length表示为截取的最后一个字符所在的索引，值为：len(str) + length + 1 。例如：等于 -1 时，表示截取到最后一个字符；等于 -2 时，表示截取到倒数第二个字符。

备注：Substr 内部实现string转rune切片。

// string转rune切片
runes := []rune(str)
string(runes[start: end])
1.2 拼接字符串

推荐：strings.Builder+预设大小的方式拼接字符串。

struct strings.Builder
var b strings.Builder
b.Grow(length)    // 预设大小
b.WriteString(s1) // 写入字符串s1
b.WriteString(s2) // 写入字符串s2
s3 := b.String() // 拼接后的字符串
func fmt.Sprintf
var str = fmt.Sprintf("%s%d%s", s1, i, s2)
func strings.Join
var str []string = []string{s1, s2}
s := strings.Join(str, "")
struct bytes.Buffer
var bt bytes.Buffer
bt.WriteString(s1)
bt.WriteString(s2)
s3 := bt.String()
1.3 获取字符串长度

推荐：包含宽字符（宽字符算一个长度）时，使用utf8.RuneCount、 utf8.RuneCountInString获取长度。

func len
len(str)
func utf8.RuneCount
func RuneCount(p []byte) int
func utf8.RuneCountInString
func RuneCountInString(s string) (n int)
func bytes.Count
func Count(s, sep []byte) int
参数 描述
str 要获取长度的字符串。
sep 分隔符，一般传 nil。

备注：利用 sep 长度等于0的逻辑获取字符串长度；sep长度等于0内部调用 utf8.RuneCount(s) + 1，所以返回的长度需要减 1。

length := bytes.Count([]byte(str), nil) - 1
func strings.Count
func Count(s, substr string) int
参数 描述
str 要获取长度的字符串。
substr 子串，传入空即可。

备注：利用 substr 长度等于0的逻辑获取字符串长度；substr长度等于0内部调用 utf8.RuneCountInString(s) + 1，所以返回的长度需要减 1。

length := strings.Count(str, "") - 1
1.4 分割字符串

分割字符串我们可以分为几种情况，分别为：按空格分割、按子字符串分割和按字符分割。

func strings.Fields
func Fields(s string) []string

备注：按空格分割字符串

func strings.FieldsFunc
func FieldsFunc(s string, f func (rune) bool) []string

备注：按字符分割字符串

func strings.Split
func Split(s, sep string) []string
参数 描述
s 要分割的字符串。
sep 字符串的分割符。

备注：按子字符串分割字符串

// 按空格(空字符串)分割
strings.Split(s, " ")
// 按xxx字符串分割
strings.Split(s, "xxx")
1.5 统计子串在字符串中出现的次数
func strings.Count
func Count(s, substr string) int
参数 描述
s 原字符串。
substr 要检索的字符串。
1.6 查找子串在字符串中出现位置
func strings.Index
func Index(s, substr string) int
参数 描述
s 原字符串。
substr 要检索的字符串。

备注：返回的是字符串第一次出现的位置。查找不存在的字符串返回 -1。

func stringsLastIndex
func LastIndex(s, substr string) int
参数 描述
s 原字符串。
substr 要检索的字符串。

备注：返回的是字符串最后一次出现的位置。查找不存在的字符串返回 -1。

func strings.IndexAny
func IndexAny(s, chars string) int
参数 描述
s 原字符串。
chars 要检索的字符序列。

备注：返回第一次出现字符序列的索引；反之，则返回 -1。

func strings.LastIndexAny
func LastIndexAny(s, chars string) int
参数 描述
s 原字符串。
chars 要检索的字符序列。

备注：返回最后一次出现字符序列的索引；反之，则返回 -1。

func strings.IndexByte
func IndexByte(s string, c byte) int
参数 描述
s 原字符串。
c 表示要检索的字符。

备注：返回第一次出现字符的索引；反之，则返回 -1。

func strings.LastIndexByte
func LastIndexByte(s string, c byte) int
参数 描述
s 原字符串。
r 表示要检索的字符。

备注：返回最后一次出现字符的索引；反之，则返回 -1。

func strings.IndexRune
func IndexRune(s string, r rune) int
参数 描述
s 原字符串。
r 表示要检索的字符。

备注：返回第一次出现字符的索引；反之，则返回 -1。

func strings.LastIndexRune
func LastIndexRune(s string, r rune) int
参数 描述
s 原字符串。
c 表示要检索的字符。

备注：返回最后一次出现字符的索引；反之，则返回 -1。

func strings.IndexFunc
func IndexFunc(s string, f func (rune) bool) int
参数 描述
s 原字符串。
f 表示要检索的字符的条件判断函数。

备注：返回第一次出现字符的索引；反之，则返回 -1。

func strings.LastIndexFunc
func LastIndexFunc(s string, f func (rune) bool) int
参数 描述
s 原字符串。
f 表示要检索的字符的条件判断函数。

备注：返回最后一次出现字符的索引；反之，则返回 -1。

1.7 判断字符串是否包含子串
func strings.HasPrefix
func HasPrefix(s, prefix string) bool
参数 描述
s 原字符串。
prefix 要检索的子串。

备注：检索字符串s是否以指定字符串prefix开头，如果是返回 True；反之返回 False。

func strings.HasSuffix
func HasSuffix(s, suffix string) bool
参数 描述
s 原字符串。
suffix 要检索的子串。

备注：检索字符串s是否以指定字符串suffix结尾，如果是返回 True；反之返回 False。

func strings.Contains
func Contains(s, substr string) bool
参数 描述
s 原字符串。
substr 要检索的子串。

备注：检索字符串s是否包含字符串substr。函数内部实现 strings.Index >= 0 。

func strings.ContainsRune
func ContainsRune(s string, r rune) bool
参数 描述
s 原字符串。
r 表示要检索的字符。

备注：检索字符串s是否包含字符r。函数内部实现 strings.IndexRune >= 0 。

func strings.ContainsAny
func ContainsAny(s, chars string) bool
参数 描述
s 原字符串。
chars 表示要检索的字符串。

备注：检索字符串s是否包含字符串chars。函数内部实现 strings.IndexAny >= 0 。

func strings.Cut
func Cut(s, sep string) (before, after string, found bool)
参数 描述
s 原字符串。
sep 查找的字符串。

备注：在字符串s中找到字符串sep, 并返回字符串sep前后部分以及是否找到字符串sep。

1.8 字符串大小写转换
func strings.ToTitle
func ToTitle(s string) string

备注：将字符串首字母转成大写。

func strings.ToLower
func ToLower(s string) string

备注：将字符串转成小写。

func strings.ToUpper
func ToUpper(s string) string

备注：将字符串转成大写。

1.9 去除字符串指定字符
func strings.TrimSpace
func TrimSpace(s string) string

备注：将字符串左右两边的空格去除。

func strings.Trim
func Trim(s string, cutset string) string
参数 描述
s 原字符串。
cutset 需要去除的字符串。

备注：将字符串左右两边的指定字符串 cutset 去除。

func strings.TrimLeft
func TrimLeft(s, cutset string) string
参数 描述
s 原字符串。
cutset 需要去除的字符串。

备注：将字符串左边的指定字符串 cutset 去除。

func strings.TrimRight
func TrimRight(s, cutset string) string
参数 描述
s 原字符串。
cutset 需要去除的字符串。

备注：将字符串右边的指定字符串 cutset 去除。

func strings.TrimPrefix
TrimPrefix(s, prefix string) string
参数 描述
s 原字符串。
prefix 需要去除的前缀字符串。

备注：去除字符串的前缀prefix。

func strings.TrimSuffix
func TrimSuffix(s, suffix string) string
参数 描述
s 原字符串。
suffix 需要去除的后缀字符串。

备注：去除字符串的后缀suffix。

func strings.TrimFunc
func TrimFunc(s string, f func (rune) bool) string
参数 描述
s 原字符串。
f 需要去除的字符串的规则函数。

备注：将字符串左右两边符合函数 f 规则字符串去除。函数 f，接受一个 rune 类型的参数，返回一个 bool 类型的变量，如果函数 f 返回 true，那说明符合规则，字符将被移除。

func strings.TrimLeftFunc
func TrimLeftFunc(s string, f func (rune) bool) string
参数 描述
s 原字符串。
f 需要去除的字符串的规则函数。

备注：将字符串左边符合函数 f 规则字符串去除。函数 f，接受一个 rune 类型的参数，返回一个 bool 类型的变量，如果函数 f 返回 true，那说明符合规则，字符将被移除。

func strings.TrimRightFunc
func TrimRightFunc(s string, f func (rune) bool) string
参数 描述
s 原字符串。
f 需要去除的字符串的规则函数。

备注：将字符串右边符合函数 f 规则字符串去除。函数 f，接受一个 rune 类型的参数，返回一个 bool 类型的变量，如果函数 f 返回 true，那说明符合规则，字符将被移除。

1.10 字符串遍历处理
func strings.Map
func Map(mapping func (rune) rune, s string) string
参数 描述
mapping 对字符串中每一个字符的处理函数。
s 原字符串。

备注：对字符串 s 中的每一个字符都做 mapping 处理。

1.11 字符串比较
func strings.Compare
func Compare(a, b string) int

备注：比较字符串 a 和字符串 b 是否相等，如果 a > b，返回一个大于 0 的数，如果 a == b，返回 0，否则，返回负数。

func strings.EqualFold
func EqualFold(s, t string) bool

备注：比较字符串 s 和字符串 t 是否相等，如果相等，返回 true，否则，返回 false。该函数比较字符串大小是忽略大小写的。

1.12 字符串重复指定次数
func strings.Repeat
func Repeat(s string, count int) string
参数 描述
s 原字符串。
count 要重复的次数。

备注：将字符串s重复count次。

1.13 字符串替换
func strings.Replace
func Replace(s, old, new string, n int) string
参数 描述
s 原字符串。
old 要替换的字符串。
new 替换成什么字符串。
n 要替换的次数，-1，那么就会将字符串 s 中的所有的 old 替换成 new。

备注：将字符串 s 中的 old 字符串替换成 new 字符串，替换 n 次，返回替换后的字符串。如果 n 是 -1，那么就会将字符串 s 中的所有的 old 替换成 new。

func strings.ReplaceAll
func ReplaceAll(s, old, new string) string
参数 描述
s 原字符串。
old 要替换的字符串。
new 替换成什么字符串。

备注：将字符串 s 中的 old 字符串全部替换成 new 字符串，返回替换后的字符串。

struct strings.Replacer
strings.NewReplacer(oldnew...).Replace(s)

备注：字符串替换

func utils.Replace
func Replace(s string, oldnew map[string]string) string
参数 描述
s 原字符串。
oldnew 替换规则，map类型， map的键为要替换的字符串，map的值为替换成什么字符串。

备注：内部会先按 key 排序再调用 strings.NewReplacer，保证 map 遍历无序时替换规则仍稳定；使用 map 类型传参更加直观。

1.14 字符串克隆
func strings.Clone
func Clone(s string) string

备注：返回 s 的新副本。

1.15 字符串反转
func utils.StrRev
func StrRev(str string) string

备注：将字符串 str 反转。

1.16 生成随机字符串
func utils.UniqID / utils.UniqId
func UniqID(l uint8, r ...*rand.Rand) string
func UniqId(l uint8, r ...*rand.Rand) string
参数 描述
l 生成字符串的长度。
r 随机种子 utils.RandSource：批量生成时传入r参数可提升生成随机数效率。

备注：生成一个长度范围16-32位的唯一ID字符串(可排序的字符串)，UniqID函数生成字符串并不保证全局强唯一性；UniqId 为历史兼容名称，新代码建议使用 UniqID。该函数基于 math/rand，仅适用于非安全场景；token、验证码、重置链接等安全用途请使用 SecureUniqID。

func utils.RandStr
func RandStr(n int, r ...*rand.Rand) string
参数 描述
n 生成字符串的长度。
r 随机种子 utils.RandSource：批量生成时传入r参数可提升生成随机数效率。

备注：随机生成字符串 ALPHA。ALPHA 值为：A-Za-z。该函数基于 math/rand，仅适用于测试数据、临时标识等非安全场景；安全用途请使用 SecureRandStr。

func utils.RandStr2
func RandStr2(n int, r ...*rand.Rand) string
参数 描述
n 生成字符串的长度。
r 随机种子 utils.RandSource：批量生成时传入r参数可提升生成随机数效率。

备注：随机生成字符串 ALNUM。ALNUM 值为：A-Za-z0-9；为兼容旧行为，首字符固定为字母，不会以数字开头。该函数基于 math/rand， 仅适用于非安全场景；安全用途请使用 SecureRandStr2。

func utils.RandStr3
func RandStr3(n int, alpha string, r ...*rand.Rand) string
参数 描述
n 生成字符串的长度。
alpha 生成随机字符串的种子。
r 随机种子 utils.RandSource：批量生成时传入r参数可提升生成随机数效率。

备注：随机生成字符串。alpha 指定生成随机字符串的种子。该函数基于 math/rand，仅适用于非安全场景；安全用途请使用 SecureRandStr3。

1.17 字符串 Read
struct Reader
NewReader(s string).Read((b []byte)

备注：实现了read接口。

1.18 字符转义
func html.EscapeString
func EscapeString(s string) string

备注：将html文本中的字符转换为实体字符。

func html.UnescapeString
func UnescapeString(s string) string

备注：将实体字符转换为可编译的html字符。

func url.QueryEscape
func QueryEscape(s string) string

备注：将URL中的字符进行转义。

func url.QueryUnescape
func QueryUnescape(s string) (string, error)

备注：将URL中的转义字符转换为对应的字符。

func utils.URLPath / utils.UrlPath
func URLPath(urlPath string, params url.Values) (string, error)
func UrlPath(urlPath string, params url.Values) (string, error)
参数 描述
urlPath 基础 URL 路径。
params 查询参数键值对。

备注：将 params 合并到 urlPath 的查询字符串中，并保留原有查询参数；UrlPath 为历史兼容名称，新代码建议使用 URLPath。

2. 编码与解码

2.1 JSON编码解码
func json.Marshal
func Marshal(v any) ([]byte, error)

备注：对数据进行 JSON 编码

func json.Unmarshal
func Unmarshal(data []byte, v any) error

备注：对数据进行 JSON 解码

2.2 BASE64编码解码
文本数据进行 base64 编码
base64.StdEncoding.EncodeToString(src)
文本数据进行 base64 解码
base64.StdEncoding.DecodeString(s)
URL或文件名进行 base64 编码
base64.URLEncoding.EncodeToString(src)
URL或文件名进行 base64 解码
base64.URLEncoding.DecodeString(s)

3. MATH 函数

3.1 math函数
func math.Pow
func Pow(x, y float64) float64

备注：返回x的y次方。

func math.Abs
func Abs(x float64) float64

备注：返回x的绝对值。

func math.Round
func Round(x float64) float64

备注：返回最接近的整数，从零四舍五入。

func math.Ceil
func Ceil(x float64) float64

备注：返回x的上舍入值。

func math.Floor
func Floor(x float64) float64

备注：返回x的下舍入值。

func math.Mod
func Mod(x, y float64) float64

备注：返回x/y的余数。

func math.Max
func Max(x, y float64) float64

备注：返回x和y中最大值。

func math.Min
func Min(x, y float64) float64

备注：返回x和y中最小值。

3.2 utils函数
func utils.Rand
func Rand(minInt, maxInt int64, r ...*rand.Rand) int64
参数 描述
minInt 最小值。
maxInt 最大值。
r 随机种子 utils.RandSource：批量生成时传入r参数可提升生成随机数效率。

备注：返回 minInt~maxInt 之间的随机数，值可能包含 minInt 和 maxInt；当 minInt 大于 maxInt 时会自动交换。

func utils.Round
func Round(num float64, precision int) float64
参数 描述
num 原数值。
precision 保留小数位。

备注：对num进行四舍五入，并保留指定小数位。

4. 文件

4.1 获取文件信息
func os.Stat
func Stat(name string) (FileInfo, error)

备注：获取名为name的文件或目录信息。

4.2 创建与移除
func os.Mkdir
func Mkdir(name string, perm FileMode) error

备注：创建目录。

func os.Remove
func Remove(name string) error

备注：删除名为name的文件。

4.3 打开与创建
func os.OpenFile
func OpenFile(name string, flag int, perm FileMode) (*File, error)

备注：打开名为name的文件。

func os.Create
func Create(name string) (*File, error)

备注：创建名为name的文件。

4.4 读取与写入
func os.ReadFile
func ReadFile(name string) ([]byte, error)

备注：读取名为name的文件内容。

func os.WriteFile
func WriteFile(name string, data []byte, perm FileMode) error

备注：将data数据写入name文件。

4.5 重命名与移动
func os.Rename
func Rename(oldpath, newpath string) error

备注：重命名文件(夹)oldpath为newpath，或移动文件。

4.6 获取目录路径
func os.Getwd
func Getwd() (dir string, err error)

备注：取得当前工作目录的根路径。

func filepath.Abs
func Abs(path string) (string, error)

备注：获取path的绝对路径。

func filepath.IsAbs
func IsAbs(path string) bool

备注：判断path路径是否是绝对路径。

func filepath.Rel
func Rel(basepath, targpath string) (string, error)

备注：返回一个相对路径。

func filepath.Clean
func Clean(path string) string

备注：返回相path的最短路径名。

4.7 权限
func os.Chmod
 func Chmod(name string, mode FileMode) error

备注：改变文件(夹)name的权限。

func os.Chown
  func Chown(name string, uid, gid int) error

备注： 改变文件的所有者。

4.8 解析路径名
func filepath.Ext
  func Ext(path string) string

备注：返回path文件扩展名。

func filepath.Base
  func Base(path string) string

备注： (path为一个文件路径)可获取path中的文件名。

func filepath.Dir
  func Dir(path string) string

备注：获取path路径的目录。

4.9 路径的切分和拼接
func filepath.Split
  func Split(path string) (dir, file string)

备注：将path路径分成dir目录和file文件。

func filepath.Join
  func Join(elem ...string) string

备注：Join函数可以将任意数量的路径元素放入一个单一路径里。

4.10 路径判断
func utils.IsDir
func IsDir(path string) bool

备注：判断给定路径是否是一个目录。

func utils.IsFile
func IsFile(filepath string) bool

备注：判断给定的文件路径名是否是一个文件。

func utils.IsExist
func IsExist(path string) bool

备注：判断一个文件（夹）是否存在。

4.11 获取文件大小
func utils.Size
func Size(filepath string) (int64, error)

备注：取得文件大小。

func utils.SizeFormat
func SizeFormat(size int64, decimals uint) string
参数 描述
size 文件实际大小(Byte)。
decimals 保留几位小数。

备注：文件大小格式化已可读式显示文件大小。

4.12 复制文件
func utils.Copy
func Copy(src, dst string) error
参数 描述
src 拷贝的原文件。
dst 拷贝后的文件。

备注：拷贝文件。

4.13 获取目录文件
func utils.FindFiles
func FindFiles(path string, depth bool, match ...string) (files []FileInfo, err error)
参数 描述
path 目录路径。
depth 深度查找: true 采用filepath.WalkDir遍历; false 只在当前目录查找。
match 匹配规则:
- 无参 : 匹配所有文件名 FindFiles(path, depth)
- * : 匹配所有文件名 FindFiles(path, depth, *)
- 文件完整名 : 精准匹配文件名 FindFiles(path, depth, fullFileName)
- e, 文件完整名 : 精准匹配文件名 FindFiles(path, depth, e, fullFileName)
- p, 文件前缀名 : 匹配前缀文件名 FindFiles(path, depth, p, fileNamePrefix)
- s, 文件后缀名 : 匹配后缀文件名 FindFiles(path, depth, s, fileNameSuffix)
- r, 正则表达式 : 正则匹配文件名 FindFiles(path, depth, r, fileNameReg)

备注：获取目录下所有匹配文件。

4.14 内容读取
func utils.Scan
func Scan(r io.Reader, handle ReadScan, size ...int) error
参数 描述
r 实现io.Reader接口。
handle func(num int, line []byte, err error) error 函数。
num 行号: 当前扫描到第几行
line 行数据: 当前扫描的行数据
err 扫描错误信息
error 处理错误信息: 返回的 error == DONE 代表正确处理完数据并终止扫描
size 设置Scanner.maxTokenSize 的大小(默认值: 64*1024): 单行内容大于该值则无法读取

备注：使用scan扫描文件每一行数据。

func utils.Line
func Line(r io.Reader, handle ReadLine) error
参数 描述
r 实现io.Reader接口。
handle func(num int, line []byte, lineDone bool) error 函数。
num 行号: 当前扫描到第几行
line 行数据: 当前扫描的行数据
lineDone 当前行(num)数据是否读取完毕: true 当前行(num)数据读取完毕; false 当前行(num)数据未读完
error 处理错误信息: 返回的 error == DONE 代表正确处理完数据并终止扫描

备注：读取一行数据，读取大文件大行数据性能略优于Scan。

func utils.Read
func Read(r io.Reader, handle ReadBlock) error
参数 描述
r 实现io.Reader接口。
handle func(size int, block []byte) error 函数。
size 读取的数据块大小
block 读取的数据块
error 处理错误信息: 返回的 error == DONE 代表正确处理完数据并终止扫描

备注：使用分块读取文件数据，适用于读取大文件或无换行的文件。

4.15 写入内容到文件
func utils.WriteFile
func NewWrite(fileName string, opts ...WriteOption) (*WriteFile, error)
参数 描述
fileName 文件路径名。
opts 写入配置项: WithWriteAppend(true) 追加写入; WithWritePerm(0644) 设置文件权限

备注：返回一个WriteFile实例。

补充说明：

  • NewWrite 适合日志、顺序输出等持续写入场景。
  • 若是配置文件、密钥文件、状态文件等“整文件覆盖”场景，生产环境更建议使用 WriteFileAtomic / WriteStringAtomic，避免直接 O_TRUNC 导致半写文件。
  • NewWrite 会拒绝目标文件为符号链接，降低通过通用写入口写穿到其它路径的风险。
// 实例化一个WriteFile（追加写入）
w, err := NewWrite(fileName, WithWriteAppend(true))
if err != nil {
fmt.Errorf("Write() error = %v", err)
return
}

// 关闭文件
defer func () {
if err := w.Close(); err != nil {
fmt.Errorf("Close() err %v", err)
}
}()


------

#### func    [utils.WriteFileAtomic / utils.WriteStringAtomic](https://github.com/Is999/go-utils/blob/master/file.go)

```go
func WriteFileAtomic(fileName string, data []byte, perm os.FileMode) error
func WriteStringAtomic(fileName, data string, perm os.FileMode) error

备注：使用同目录临时文件 + Sync + Close + Rename 原子覆盖目标文件，适用于配置、密钥、状态等要求“覆盖即完整替换”的场景。

err := utils.WriteFileAtomic(fileName, []byte("hello world"), 0644)
if err != nil {
	fmt.Errorf("WriteFileAtomic() err %v", err)
	return
}

err = utils.WriteStringAtomic(fileName, "hello world", 0644)
if err != nil {
	fmt.Errorf("WriteStringAtomic() err %v", err)
	return
}

备注：适合一次性覆盖完整文件内容；若需要持续写入、追加写入或 `bufio.Writer` 批量写入，继续使用 `NewWrite`。

------

### 4.16 获取文件类型

------

#### func    [utils.FileType](https://github.com/Is999/go-utils/blob/master/file.go#L462)

```go
func FileType(f *os.File) (string, error)

备注：获取文件类型

5. 加密、解密与摘要

5.1 MD5 摘要
func utils.Md5
func Md5(str string) string

备注：返回 MD5 十六进制摘要。MD5 已不适合密码存储、签名、完整性安全校验等安全场景，仅用于历史协议兼容或非安全哈希标识。

5.2 SHA 摘要
func utils.Sha1
func Sha1(str string) string

备注：返回 SHA-1 十六进制摘要。SHA-1 已不适合签名、证书、密码存储等安全场景，仅用于历史协议兼容或非安全哈希标识。

func utils.Sha256
func Sha256(str string) string

备注：返回 SHA-256 十六进制摘要。普通摘要场景可使用；密码存储仍应使用 bcrypt/argon2/scrypt 等专用算法。

func utils.Sha512
func Sha512(str string) string

备注：返回 SHA-512 十六进制摘要。普通摘要场景可使用；密码存储仍应使用 bcrypt/argon2/scrypt 等专用算法。

5.3 RSA 非对称加密与解密
func utils.GenerateKeyRSA
func GenerateKeyRSA(path string, bits int, pkcs ...bool) ([]string, error)
参数 描述
path 文件名路径。
bits 生成秘钥位大小，生产环境要求至少 2048。
pkcs 秘钥格式, 默认格式(公钥PKCS8格式 私钥PKCS1格式):
- pkcs[0] isPubPKCS8 公钥是否是PKCS8格式: 默认 true
- pkcs[1] isPriPKCS1 私钥是否是PKCS1格式: 默认 true

备注：生成秘钥，默认格式(公钥PKCS8格式 私钥PKCS1格式)。返回两个文件名, 第一个公钥文件名, 第二个私钥文件名；为保证生产安全，密钥位数不能低于 2048。

RSA 加密与解密
// 实例化RSA，并设置key
r, err := NewRSA(publicKey, privateKey, WithRSAFilePath(true))
if err != nil {
fmt.Errorf("NewRSA() err = %v", err)
return
}

// 源数据
marshal, err := json.Marshal(map[string]interface{}{
"Title":   tt.name,
"Content": strings.Repeat("测试内容8282@334&-", 1024) + tt.name,
})

// 公钥加密 PKCS1v15
encodeString, err := r.Encrypt(string(marshal), base64.StdEncoding.EncodeToString)
if err != nil {
fmt.Errorf("Encrypt() err = %v", err)
return
}

// 私钥解密 PKCS1v15
decryptString, err := r.Decrypt(encodeString, base64.StdEncoding.DecodeString)
if err != nil {
fmt.Errorf("Decrypt() err = %v", err)
return
}

// 公钥加密 OAEP
encodeString, err = r.EncryptOAEP(string(marshal), base64.StdEncoding.EncodeToString, sha256.New())
if err != nil {
fmt.Errorf("Encrypt() err = %v", err)
return
}

// 私钥解密 OAEP
decryptString, err = r.DecryptOAEP(encodeString, base64.StdEncoding.DecodeString, sha256.New())
if err != nil {
fmt.Errorf("Decrypt() err = %v", err)
return
}

备注：先实例化RSA 设置公钥私钥，使用公钥加密数据， 私钥解密数据。

RSA 签名与验签
// 实例化RSA，并设置key
r, err := NewRSA(publicKey, privateKey, WithRSAFilePath(true))
if err != nil {
fmt.Errorf("NewRSA() err = %v", err)
return
}

// 源数据
marshal, err := json.Marshal(map[string]interface{}{
"Title":   tt.name,
"Content": strings.Repeat("测试内容8282@334&-", 1024) + tt.name,
})

// 私钥签名 PKCS1v15
sign, err := r.Sign(string(marshal), crypto.SHA256, base64.StdEncoding.EncodeToString)
if err != nil {
fmt.Errorf("Sign() err = %v", err)
return
}

// 公钥验签 PKCS1v15
if err := r.Verify(string(marshal), sign, crypto.SHA256, base64.StdEncoding.DecodeString); err != nil {
fmt.Errorf("Verify() err = %v", err)
return
} else {
fmt.Log("Verify() = 验证成功")
}

// 私钥签名 PSS
sign, err = privRsa.SignPSS(string(marshal), crypto.SHA256, base64.StdEncoding.EncodeToString, nil)
if err != nil {
fmt.Errorf("Sign() err = %v", err)
return
}

// 公钥验签 PSS
if err := pubRsa.VerifyPSS(string(marshal), sign, crypto.SHA256, base64.StdEncoding.DecodeString, nil); err != nil {
fmt.Errorf("Verify() err = %v", err)
return
} else {
fmt.Log("Verify() = 验证成功")
}

备注：先实例化RSA 设置公钥私钥，使用私钥签名，公钥验签。

加密模式选型建议
场景 推荐方案 说明
新系统对称加密 AES + GCM 默认优先方案，带机密性和完整性校验，支持 additionalData。
兼容分组协议 AES/DES + CBC + WithIV/WithRandIV 需要补位，适合和旧系统的固定协议对接。
旧系统流模式兼容 CTR/CFB/OFB + WithAllowUnsafeStreamMode(true) 默认禁用；无需块补位，但不提供完整性校验，仅用于兼容历史协议。
旧系统 ECB 兼容 ECB + WithAllowUnsafeECB(true) 默认禁用，不建议新系统使用。
RSA 加密 EncryptOAEP/DecryptOAEP 新协议优先，适合加密小数据或对称密钥。
RSA 签名 SignPSS/VerifyPSS 新协议优先，推荐配合 SHA256 或更强摘要。

备注：

  • RSA 适合加密小块数据或密钥封装，不建议直接承载大体积正文。
  • PKCS#1 v1.5 加解密与签名接口主要保留给旧系统兼容；新系统优先使用 OAEP/PSS。
  • 生产环境推荐 2048 位及以上 RSA 密钥，摘要算法推荐 SHA256 / SHA384 / SHA512。
RSA 秘钥格式转换
// 读取公钥文件内容
pub, err := os.ReadFile(pubFile)
if err != nil {
t.Errorf("ReadFile() WrapError = %v", err)
}

//fmt.Println("公钥 %s", string(pub))
rPub := utils.RemovePEMHeaders(string(pub))
//fmt.Println("remove 公钥 %s", rPub)
aPub := utils.AddPEMHeaders(rPub, "public")
//fmt.Println("add 公钥 %s %v", aPub, strings.EqualFold(aPub, strings.TrimSpace(string(pub))))
if !strings.EqualFold(aPub, strings.TrimSpace(string(pub))) {
fmt.Errorf("转换后的公钥与原始公钥不相等")
}

// 读取私钥文件内容
pri, err := os.ReadFile(priFile)
if err != nil {
t.Errorf("ReadFile() WrapError = %v", err)
}
//fmt.Println("私钥 %s", string(pri))
rPri := utils.RemovePEMHeaders(string(pri))
//fmt.Println("remove 私钥 %s", rPri)
aPri := utils.AddPEMHeaders(rPri, "private")
//fmt.Println("add 私钥 %s %v", aPri, strings.EqualFold(aPri, strings.TrimSpace(string(pri))))
if !strings.EqualFold(aPri, strings.TrimSpace(string(pri))) {
fmt.Errorf("转换后的私钥与原始私钥不相等")
}
5.4 AES 加密与解密
AES 加密与解密
// 实例化AES，并设置key和iv
a, err := AES(key, WithIV(iv))
if err != nil {
fmt.Errorf("AES() error = %v", err)
return
}

// 加密数据
encryptStr, err := a.Encrypt(data, CBC, base64.StdEncoding.EncodeToString, Pkcs7Padding)
if err != nil {
fmt.Errorf("Encrypt() mode = %v error = %v", CBC, err)
return
}

// 解密数据
got, err := a.Decrypt(encryptStr, CBC, base64.StdEncoding.DecodeString, Pkcs7UnPadding)
if err != nil {
fmt.Errorf("Decrypt() mode = %v error = %v", CBC, err)
return
}

备注：先实例化 AES 并设置 key；CBC/CTR/CFB/OFB 等需要显式通过 WithIV 设置固定 IV，或通过 WithRandIV(true) 使用随机 IV。 CTR/CFB/OFB 属于非认证流模式，默认禁用，仅在兼容旧系统时通过 WithAllowUnsafeStreamMode(true) 显式开启。ECB 默认禁用，仅在兼容旧系统时通过 WithAllowUnsafeECB(true) 显式开启；历史上“未设置 IV 时使用 key 派生 IV”的兼容行为也默认禁用，如需兼容旧密文可显式开启 WithAllowUnsafeKeyIV(true)。

补充：CTR/CFB/OFB 若用于旧协议兼容且无需补位，建议配合 NoPadding / NoUnPadding 使用，避免多余填充和块长度约束。

5.5 DES 加密与解密
DES 加密与解密
// 实例化DES，并设置key和iv
a, err := DES(key, WithIV(iv))
if err != nil {
fmt.Errorf("DES() error = %v", err)
return
}

// 加密数据
encryptStr, err := a.Encrypt(data, CBC, base64.StdEncoding.EncodeToString, Pkcs7Padding)
if err != nil {
fmt.Errorf("Encrypt() mode = %v error = %v", CBC, err)
return
}

// 解密数据
got, err := a.Decrypt(encryptStr, CBC, base64.StdEncoding.DecodeString, Pkcs7UnPadding)
if err != nil {
fmt.Errorf("Decrypt() mode = %v error = %v", CBC, err)
return
}

备注：DES/3DES 仅建议用于旧系统兼容，新系统应优先使用 AES-GCM。先实例化 DES 并设置 key；CBC/CTR/CFB/OFB 等需要显式通过 WithIV 设置固定 IV，或通过 WithRandIV(true) 使用随机 IV。CTR/CFB/OFB 属于非认证流模式，默认禁用，仅在兼容旧系统时通过 WithAllowUnsafeStreamMode(true) 显式开启。 ECB 默认禁用，仅在兼容旧系统时通过 WithAllowUnsafeECB(true) 显式开启；历史上“未设置 IV 时使用 key 派生 IV”的兼容行为也默认禁用，如需兼容旧密文可显式开启 WithAllowUnsafeKeyIV(true)。

补充：CTR/CFB/OFB 若用于旧协议兼容且无需补位，建议配合 NoPadding / NoUnPadding 使用，避免多余填充和块长度约束。

5.6 pkcs7 填充与反填充
AES GCM（推荐）
// 实例化 AES
a, err := AES(key)
if err != nil {
fmt.Errorf("AES() error = %v", err)
return
}

// GCM 加密，additionalData 可为空
encryptStr, err := a.EncryptGCMString(data, base64.StdEncoding.EncodeToString, []byte("request-id=r-1"))
if err != nil {
fmt.Errorf("EncryptGCMString() error = %v", err)
return
}

// GCM 解密，additionalData 必须与加密时一致
got, err := a.DecryptGCMString(encryptStr, base64.StdEncoding.DecodeString, []byte("request-id=r-1"))
if err != nil {
fmt.Errorf("DecryptGCMString() error = %v", err)
return
}

备注：GCM 属于 AEAD 认证加密模式，优先级高于 CBC/CTR/CFB/OFB；每次加密都会自动生成随机 nonce 并写入密文头部。

NoPadding / NoUnPadding
// CTR 模式下直接关闭补位。CTR 不提供完整性校验，仅用于旧协议兼容。
a, err := AES(key, WithRandIV(true), WithAllowUnsafeStreamMode(true))
if err != nil {
return
}

encryptStr, err := a.Encrypt(data, CTR, base64.StdEncoding.EncodeToString, NoPadding)
if err != nil {
return
}

got, err := a.Decrypt(encryptStr, CTR, base64.StdEncoding.DecodeString, NoUnPadding)
if err != nil {
return
}

备注：NoPadding / NoUnPadding 适合 CTR/CFB/OFB/GCM 这类不依赖块补位的模式；其中 CTR/CFB/OFB 不提供完整性校验，默认禁用，不建议用于新协议。

加密模块性能验证命令
# 对称加密基准
go test -run '^$' -bench 'BenchmarkCipherAES(CBCEncrypt|CBCDecrypt|CTRNoPaddingEncrypt|CTRNoPaddingDecrypt|GCMEncrypt|GCMDecrypt)$' -benchmem ./...

# RSA 基准
go test -run '^$' -bench 'BenchmarkRSA(EncryptOAEP|DecryptOAEP|SignPSS|VerifyPSS)$' -benchmem ./...

# 全量竞态验证
go test -race ./...

备注：

  • 基准数据受 CPU、系统负载、Go 版本影响较大，建议关注相对变化而不是绝对数值。
  • RSA 私钥解密/签名天然比公钥加密/验签更重，属于算法特性，不是实现异常。
  • 对称加密建议把 CBC、CTR-NoPadding、GCM 分开观察，分别对应兼容分组模式、旧协议流模式和认证加密模式。
func utils.Pkcs7Padding
func Pkcs7Padding(data []byte, blockSize int) []byte

备注：数据填充。

func utils.Pkcs7UnPadding
func Pkcs7UnPadding(data []byte) ([]byte, error)

备注：数据反填充。

5.7 0 填充与反填充
func utils.ZeroPadding
func ZeroPadding(data []byte, blockSize int) []byte

备注：数据填充。

func utils.ZeroUnPadding
func ZeroUnPadding(data []byte) ([]byte, error)

备注：数据反填充。

6. 整形、字符串转换

6.1 字符串转整形
func strconv.ParseInt
func ParseInt(s string, base int, bitSize int) (i int64, err error)

备注：string 转 int64。

func strconv.Atoi
func Atoi(s string) (int, error)

备注：string 转 int。

func utils.Str2Int64
func Str2Int64(s string) (i int64)

备注：string 转 int64，转换失败返回零值。

func utils.Str2Int
func Str2Int(s string) (i int)

备注：string 转 int，转换失败返回零值。

6.2 整形转字符串
func strconv.FormatInt
func FormatInt(i int64, base int) string

备注：int64 转 string。

func strconv.Itoa
func Itoa(i int) string

备注：int 转 string。

6.3 字符串转浮点数
func strconv.ParseFloat
func ParseFloat(s string, bitSize int) (float64, error)

备注：string 转 float64。

func utils.Str2Float
func Str2Float(s string) (i float64)

备注：string 转 float64，失败返回零值。

6.4 浮点数转字符串
func strconv.FormatFloat
func FormatFloat(f float64, fmt byte, prec, bitSize int) string

备注：float64 转 string。

6.5 以千位分隔符方式格式化一个数字
func utils.NumberFormat
func NumberFormat(number float64, decimals uint, decPoint, thousandsSep string) string
参数 描述
number 需要格式化的数字。
decimals 保留几位小数。
decPoint 小数点[.]
thousandsSep 千位分隔符[,]

备注：以千位分隔符方式格式化一个数字。

6.6 进制转换
func utils.BinOct
func BinOct(str string) (string, error)

备注：二进制转换为八进制。

func utils.BinDec
func BinDec(str string) (int64, error)

备注：二进制转换为十进制。

func utils.BinHex
func BinHex(str string) (string, error)

备注：二进制转换为十六进制。

func utils.OctBin
func OctBin(data string) (string, error)

备注：八进制转换为二进制。

func utils.OctDec
func OctDec(str string) (int64, error)

备注：八进制转换为十进制。

func utils.OctHex
func OctHex(data string) (string, error)

备注：八进制转换为十六进制。

func utils.DecBin
func DecBin(number int64) string

备注：十进制转换为二进制。

func utils.DecOct
func DecOct(number int64) string

备注：十进制转换为八进制。

func utils.DecHex
func DecHex(number int64) string

备注：十进制转换为十六进制。

func utils.HexBin
func HexBin(data string) (string, error)

备注：十六进制转换为二进制。

func utils.HexOct
func HexOct(str string) (string, error)

备注：十六进制转换为八进制。

func utils.HexDec
func HexDec(str string) (int64, error)

备注：十六进制转换为十进制。

7. 数组/切片/链表

7.1 检查数组中是否存在某个值
func utils.IsHas
func IsHas[T comparable](v T, s []T) bool

备注：检查s中是否存在v。1.21版本以上推荐使用标准库 slices.Contains(s,v)

7.2 统计某个值在数组中出现次数
func utils.HasCount
func HasCount[T comparable](v T, s []T) (count int)

备注：统计v在s中出现次数。

7.3 反转数组
func utils.Reverse
func Reverse[T any](s []T) []T

备注：反转s。1.21版本以上推荐使用标准库 slices.Reverse(s)

7.4 去除数组中重复的值
func utils.Unique
func Unique[T comparable](s []T) []T

备注：去除s中重复的值。

7.5 计算两个数组的差集
func utils.Diff
func Diff[T comparable](s1, s2 []T) []T

备注：计算s1与s2的差集，返回结果保持 s1 原有顺序，并保留 s1 中原本存在的重复值。

7.6 计算两个数组的交集
func utils.Intersect
func Intersect[T comparable](s1, s2 []T) []T

备注：计算s1与s2的交集，返回结果保持 s1 原有顺序，并保留 s1 中原本存在的重复值。

7.7 切片求和
func utils.SumSlice
func SumSlice[T Number](nums []T) T

备注：计算切片中所有元素的和。

7.8 列表 status container/list.List
创建列表
// 通过 list.New 创建列表
l := list.New()

// 添加元素
l.PushBack("5")
l.PushBack("6")

// 列表遍历
for i := l.Front(); i != nil; i = i.Next() {
fmt.Println("Element =", i.Value)
}

输出：

Element = 5
Element = 6
在列表头部插入元素
// 在列表头部插入
ele4 := l.PushFront("4")

输出：

Element = 4
Element = 5
Element = 6
在列表尾部插元素
// 在列表尾部插
ele8 := l.PushBack("8")

输出：

Element = 4
Element = 5
Element = 6
Element = 8
在列表指定元素前插入
// 在指定元素ele4前插入元素"3"
ele3 := l.InsertBefore("3", ele4)

输出：

Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
在列表指定元素后插入
// 在指定元素ele8后插入元素"9"
ele9 := l.InsertAfter("9", ele8)

输出：

Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
Element = 9
获取列表头结点
// 获取列表头结点
front := l.Front()
fmt.Println("front =", front.Value)

输出：

front = 3
获取列表尾结点
// 获取列表尾结点
back := l.Back()
fmt.Println("back =", back.Value)

输出：

back = 9
获取上一个结点
// 获取ele4上一个结点
prev := ele4.Prev()
fmt.Println("ele4 prev =", prev.Value)

输出：

ele4 prev = 3
获取下一个结点
// 获取ele4下一个结点
next := ele4.Next()
fmt.Println("ele4 next =", next.Value)

输出：

ele4 next = 5
移动到某元素的前面
// 将ele4元素移动到back元素的前面
l.MoveBefore(ele4, back)

输出：

移动前：
Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
Element = 9
--------------
移动后：
Element = 3
Element = 5
Element = 6
Element = 8
Element = 4
Element = 9
移动到某元素的后面
// 将ele4元素移动到back元素的后面
l.MoveAfter(ele4, back)

输出：

移动前：
Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
Element = 9
--------------
移动后：
Element = 3
Element = 5
Element = 6
Element = 8
Element = 9
Element = 4
移动到列表的最前面
// 将ele9元素移动到列表的最前面
l.MoveToFront(ele9)

输出：

移动前：
Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
Element = 9
--------------
移动后：
Element = 9
Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
移动到列表的最面
// 将ele3元素移动到列表的最后面
l.MoveToFront(ele3)

输出：

移动前：
Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
Element = 9
--------------
移动后：
Element = 4
Element = 5
Element = 6
Element = 8
Element = 9
列表正序遍历
// 列表正序遍历
for i := l.Front(); i != nil; i = i.Next() {
fmt.Println("Element =", i.Value)
}

输出：

Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
Element = 9
列表倒叙遍历
// 列表倒叙遍历
for i := l.Back(); i != nil; i = i.Prev() {
fmt.Println("Element =", i.Value)
}

输出：

Element = 9
Element = 8
Element = 6
Element = 5
Element = 4
Element = 3
在列表中删除元素
// 在列表中删除ele4元素
l.Remove(ele4)
// 在列表中删除ele8元素
l.Remove(ele8)

输出：

删除前：
Element = 3
Element = 4
Element = 5
Element = 6
Element = 8
Element = 9
--------------
删除后：
Element = 3
Element = 5
Element = 6
Element = 9
在列表头部插入一个列表
// 创建一个列表（头部列表）
frontList := list.New()
frontList.PushBack("f1")
frontList.PushBack("f2")

// 在列表头部插入一个列表
l.PushFrontList(frontList)

输出：

添加前：
Element = 3
Element = 4
--------------
添加后：
Element = f1
Element = f2
Element = 3
Element = 4
在列表尾部插入一个列表
// 创建一个列表（尾部列表）
backList := list.New()
backList.PushBack("b1")
backList.PushBack("b2")

// 在列表尾部插入一个列表
l.PushBackList(backList)

输出：

添加前：
Element = 3
Element = 4
--------------
添加后：
Element = 3
Element = 4
Element = b1
Element = b2
获取列表长度
l.Len()
初始化或清除列表
l.Init()

8. map/syncMap

8.1 获取map的所有key
func utils.MapKeys
func MapKeys[K Ordered, V any](m map[K]V) []K

备注：获取map所有的key

8.2 获取map的所有value
func utils.MapValues
func MapValues[K Ordered, V any](m map[K]V, isReverse ...bool) []V
参数 描述
m map。
isReverse 是否降序排列：true 降序，false 升序。

备注：当传入 isReverse 参数时，会先按 key 排序后返回对应 value；未传入时直接返回 map 当前遍历到的所有 value，顺序不保证稳定。

8.3 有序遍历map元素
func utils.MapRange
func MapRange[K Ordered, V any](m map[K]V, f func(key K, value V) bool, isReverse ...bool)
参数 描述
m map。
f f 函数接收key与value，返回一个bool值，如果f函数返回false则终止遍历
isReverse 是否降序排列：true 降序，false 升序。

备注：对map的key排序并按排序后的key遍历map的元素，如果f 函数返回 false则终止遍历。

8.4 过滤map的元素
func utils.MapFilter
func MapFilter[K Ordered, V any](m map[K]V, f func(key K, value V) bool) map[K]V
参数 描述
m map。
f f 函数接收key与value，返回一个bool值，如果f函数返回false则过滤掉该元素（删除该元素）

备注：使用回调函数过滤map的元素，如果f 函数返回 false则过滤掉该元素（删除该元素）。

8.5 计算两个map的差集
func utils.MapDiff
func MapDiff[K comparable, V comparable](m1, m2 map[K]V) []V

备注：计算 m1 与 m2 的值差集，返回结果保留 m1 当前遍历结果中的重复值。

func utils.MapDiffKey
func MapDiffKey[K Ordered, V any](m1, m2 map[K]V) []K

备注：计算m1与m2的键差集。

8.6 计算两个map的交集
func utils.MapIntersect
func MapIntersect[K comparable, V comparable](m1, m2 map[K]V) []V

备注：计算 m1 与 m2 的值交集，返回结果保留 m1 当前遍历结果中的重复值。

func utils.MapIntersectKey
func MapIntersectKey[K Ordered, V any](m1, m2 map[K]V) []K

备注：计算m1与m2的键交集。

8.7 计算map的值和
func utils.SumMap
func SumMap[K comparable, V Number](m map[K]V) V

备注：计算map中所有value的和。

8.8 sync.Map
创建sync.Map
//sync.Map 声明完之后，可以立即使用
var m sync.Map
m.Store("Server", "Golang")
m.Store("JavaScript", "Vue")

备注：创建map。

添加元素 Store
func (m *Map) Store(key, value interface{})

备注：向 map 中存入键为 key，值为 value 的键值对，这里的 key 和 value 都是 * interface* 类型的，因此 key 和 value 可以存入任意的类型。

获取元素 Load
func (m *Map) Load(key interface{}) (value interface{}, ok bool)

备注：返回的 value 是 interface 类型的，因此 value 我们不可以直接使用，而必须要转换之后才可以使用，返回的ok是 bool 值，表明获取是否成功。

获取或添加 LoadOrStore
func (m *Map) LoadOrStore(key, value interface{}) (actual interface{}, loaded bool)

备注：获取的 key 存在，返回 key 对应的元素，如果获取的 key 不存在，就返回设置的值，并且将设置的值，存入 map。

删除元素 Delete
func (m *Map) Delete(key interface{})

备注：删除元素，使用 sync.Map Delete 删除不存在的元素，不会报错。

获取并删除 LoadAndDelete
func (m *Map) LoadAndDelete(key any) (value any, loaded bool)

备注：如果key存在返回key的值并删除该key。

遍历元素 Range
func (m *Map) Range(f func (key, value interface{}) bool)

备注：遍历元素，如果f 函数返回 false则终止遍历。

9. 时间

9.1 时区
func utils.Local
func Local() *time.Location

备注：系统运行时区。

func utils.CST
func CST() *time.Location

备注：东八时区。

func utils.UTC
func UTC() *time.Location

备注：UTC时区。

9.2 验证日期：年、月、日
func utils.CheckDate
func CheckDate(year, month, day int) bool
参数 描述
year 年份。
month 月份。
day 日期。

备注：验证日期：年、月、日。

9.3 获取指定月份有多少天
func utils.MonthDay
func MonthDay(year int, month int) (days int)
参数 描述
year 年份。
month 月份。

备注：获取指定月份有多少天。

9.4 增加时间
func utils.AddTime
func AddTime(t time.Time, addTimes ...string) (time.Time, error)
参数 描述
addTimes 增加时间（Y年，M月，D日，H时，I分，S秒，L毫秒，C微妙，N纳秒)。

备注：增加时间。

9.5 获取日期信息
func utils.DateInfo
func DateInfo(t time.Time) map[string]interface{}

备注：获取日期信息。

//	返回：year int - 年，
//		month int - 月，monthEn string - 英文月，
//		day int - 日，yearDay int - 一年中第几日， weekDay int - 一周中第几日，
//		hour int - 时，hour int - 分，second int - 秒，
//		millisecond int - 毫秒，microsecond int - 微妙，nanosecond int - 纳秒，
//		unix int64 - 时间戳-秒，unixNano int64 - 时间戳-纳秒，
//		weekDay int - 星期几，weekDayEn string - 星期几英文， yearWeek int - 一年中第几周，
//		date string - 格式化日期，dateNs string - 格式化日期（纳秒)
9.6 时间格式化为时间字符串
func utils.TimeFormat
func TimeFormat(timeZone *time.Location, layout string, timestamp ...int64) string
参数 描述
timeZone 时区。
layout 格式化。
timestamp Unix 时间sec秒和nsec纳秒。

备注：时间格式化为时间字符串。

9.7 解析时间字符串为time.Time
func utils.TimeParse
func TimeParse(timeZone *time.Location, layout, timeStr string) (time.Time, error)
参数 描述
timeZone 时区。
layout 格式化。
timeStr 时间字符串。

备注：解析时间字符串为time.Time。

9.8 两个时间字符串判断
func utils.Before
func Before(layout string, t1, t2 string) (bool, error)
参数 描述
layout 格式化。
t1 时间字符串。
t2 时间字符串。

备注：返回true: t1在t2之前（t1小于t2），返回false: t1大于等于t2。

func utils.After
func After(layout string, t1, t2 string) (bool, error)
参数 描述
layout 格式化。
t1 时间字符串。
t2 时间字符串。

备注：返回true: t1在t2之后（t1大于t2），返回false: t1小于等于t2。

func utils.Equal
func Equal(layout string, t1, t2 string) (bool, error)
参数 描述
layout 格式化。
t1 时间字符串。
t2 时间字符串。

备注：判断t1是否与t2相等。

9.9 求两个时间字符串的时间差
func utils.Sub
func Sub(layout string, t1, t2 string) (time.Duration, error)
参数 描述
layout 格式化。
t1 时间字符串。
t2 时间字符串。

备注：t1与t2的时间差，t1>t2 结果大于0，否则结果小于等于0。

func time.Since
func Since(t Time) Duration

示例，程序运行时间：

// 开始时间
start := time.Now()

// 业务逻辑
time.Sleep(time.Second)

// 求时间差
diff := time.Since(start)
fmt.Printf("运行时间：%v", diff) // 运行时间：1.001284412s

备注：求某个时间与现在的时间差。

10. 函数验证、正则验证

func utils.Empty
func Empty(value string) bool

备注：空字符串验证。

func utils.QQ
func QQ(value string) bool

备注：QQ号验证。

func utils.Email
func Email(value string) bool

备注：电子邮件验证。

func utils.Mobile
func Mobile(value string) bool

备注：中国大陆手机号码验证。

func utils.Phone
func Phone(value string) bool

备注：中国大陆电话号码验证。

func utils.Numeric
func Numeric(value string) bool

备注：有符号数字验证。

func utils.UnNumeric
func UnNumeric(value string) bool

备注：无符号数字验证。

func utils.UnInteger
func UnInteger(value string) bool

备注：无符号整数(正整数)验证。

func utils.UnIntZero
func UnIntZero(value string) bool

备注：无符号整数(正整数+0)验证。

func utils.Amount
func Amount(amount string, decimal uint8, signed ...bool) bool
参数 描述
amount 金额字符串。
decimal 保留小数位长度。
signed 带符号的金额: 默认无符号。

备注：金额验证。

func utils.Alpha
func Alpha(value string) bool

备注：英文字母验证。

func utils.Zh
func Zh(value string) bool

备注：中文字符验证。

func utils.MixStr
func MixStr(value string) bool

备注：英文、数字、特殊字符(不包含换行符)。

func utils.Alnum
func Alnum(value string) bool

备注：英文字母+数字验证。

func utils.Domain
func Domain(value string) bool

备注：域名(64位内正确的域名，可包含中文、字母、数字和.-)。

func utils.TimeMonth
func TimeMonth(value string) bool

备注：时间格式验证 yyyy-MM yyyy/MM。

func utils.TimeDay
func TimeDay(value string) bool

备注：时间格式验证 yyyy-MM-dd。

func utils.Timestamp
func Timestamp(value string) bool

备注：Timestamp 时间格式验证 yyyy-MM-dd hh:mm:ss。

func utils.Account
func Account(value string, min, max uint8) error

备注：帐号验证(字母开头，允许字母数字下划线，长度在min-max之间)。

func utils.PassWord
func PassWord(value string, min, max uint8) error

备注：密码(字母开头，允许字母数字下划线，长度在 min - max之间)。

func utils.PassWord2
func PassWord2(value string, min, max uint8) error

备注：强密码(必须包含大小写字母和数字的组合，不能使用特殊字符，长度在min-max之间)。

func utils.PassWord3
func PassWord3(value string, min, max uint8) error

备注：强密码(必须包含大小写字母和数字的组合，可以使用特殊字符，长度在min-max之间)。

func utils.HasSymbols
func HasSymbols(value string) bool

备注：是否包含符号。

两个时间字符串判断

备注：参考9.7 两个时间字符串判断。

11. http/curl

11.1 模拟curl请求

请求方式：GET、POST（form，file）、HEAD、PUT、PATCH、DELETE、OPTIONS

备注：

  • Curl 适合作为“基础模板配置 + 按请求派生实例”使用。
  • 共享基础配置时，生产环境建议使用 Clone() 或 NewRequest() 获取独立请求实例，再设置本次请求的 Header / Param / Body。
  • NewRequest() 会复用底层 Transport 连接池，同时为新实例生成新的 X-Request-Id，更适合并发场景。

示例：

baseCurl := utils.NewCurl().
  SetTimeout(10).
  SetHeader("Authorization", "Bearer xxx").
  SetUserAgent("go-utils-client/1.0")

reqCurl, err := baseCurl.NewRequest()
if err != nil {
  return err
}

err = reqCurl.
  SetParam("page", "1").
  SetBodyBytes([]byte(`{"name":"Lisa"}`)).
  AfterBody(func(body []byte) error {
    return json.Unmarshal(body, &result)
  }).
  Post("https://api.example.com/user")
GET 请求方式
func (c *Curl) Get(url string) (err error)

备注：参考测试用例：TestGet

POST 请求方式
func (c *Curl) Post(url string) (err error)

备注：参考测试用例：TestPost

POST FORM 请求方式
func (c *Curl) PostForm(url string) error

备注：参考测试用例：TestPostForm

POST FILE 请求方式
func (c *Curl) Post(url string) (err error)

备注：参考测试用例：TestPostFile

Clone / NewRequest
func (c *Curl) Clone() (*Curl, error)
func (c *Curl) NewRequest() (*Curl, error)

备注：

  • Clone() 会深拷贝 Header、Params、Cookie、StatusCode、Body 等请求级配置，并复用底层连接池。
  • NewRequest() 基于 Clone() 派生新的请求实例，并自动生成新的请求 ID。
  • 若当前 Body 是不可回放的流式 Reader，Clone() / NewRequest() 会返回错误，避免多个请求共享同一读取游标。

参考测试用例：

12. http/response

12.1 重定向
func utils.Redirect
func Redirect(w http.ResponseWriter, url string, opts ...ResponseOption)
参数 描述
url 重定向地址
opts 响应配置项：如 WithStatusCode(301) 
http.HandleFunc("/response/redirect", func(w http.ResponseWriter, r *http.Request) {
		// 重定向
		utils.Redirect(w, "/response/json")
	})

备注：重定向，默认响应302。

12.2 响应JSON
func utils.Json
// Json 响应Json数据
func Json(w http.ResponseWriter, opts ...ResponseOption) *Response

// Success 成功响应返回Json数据
func (r *Response) Success(code int, data any, message ...string)

// Fail 失败响应返回Json数据
func (r *Response) Fail(code int, message string, data ...any)

示例：

// 响应json数据
http.HandleFunc("/json", func(w http.ResponseWriter, r *http.Request) {

  // 获取URL查询字符串参数
  queryParam := r.URL.Query().Get("v")

  // 响应的数据
  user := User{
    Name:      "张三",
    Age:       22,
    Sex:       "男",
    IsMarried: false,
    Address:   "北京市",
    phone:     "131188889999",
  }

  if queryParam == "fail" {
    // 错误响应
	utils.Json(w, utils.WithStatusCode(http.StatusNotAcceptable)).Fail(2000, "fail", user)
    return
  }
  // 成功响应
  utils.Json(w).Success(1000, user)
})

备注：响应JSON数据，响应成功：Json().Success()，响应失败：Json().Fail()。

12.3 响应HTML
// 响应html
http.HandleFunc("/response/html", func(w http.ResponseWriter, r *http.Request) {

  // 响应html数据
  utils.View(w).Html("<p>这是一个<b style=\"color: red\">段落!</b></p>")
})

备注：响应HTML文本 View().Html()。

12.4 响应XML
// 响应xml
http.HandleFunc("/response/xml", func(w http.ResponseWriter, r *http.Request) {

  // 响应的数据
  user := User{
    Name:      "张三",
    Age:       22,
    Sex:       "男",
    IsMarried: false,
    Address:   "北京市",
    phone:     "131188889999",
  }

  // 响应xml数据
  utils.View(w).Xml(user)
})

备注：响应XML文本 View().Xml()。

12.5 响应TEXT
// 响应text
http.HandleFunc("/response/text", func(w http.ResponseWriter, r *http.Request) {
  // 响应text数据
  utils.View(w).Text("<p>这是一个<b style=\"color: red\">段落!</b></p>")
})

备注：响应TEXT文本 View().Text()。

12.6 显示图片
// 响应image
http.HandleFunc("/response/show", func(w http.ResponseWriter, r *http.Request) {
  // 获取URL查询字符串参数
  file := r.URL.Query().Get("file")
  if utils.IsExist(file) {
    // 显示文件内容

    utils.View(w).Show(file)
    return
  }
  // 处理错误
  utils.View(w, utils.WithStatusCode(http.StatusNotFound)).Text("不存在的文件：" + file)
})

备注：显示文件内容 View().Show()。

12.7 下载文件
// 下载文件
http.HandleFunc("/response/download", func(w http.ResponseWriter, r *http.Request) {
		// 获取URL查询字符串参数
		file := r.URL.Query().Get("file")
		if utils.IsExist(file) {
			// 下载文件数据
			utils.View(w).Download(file)
			return
		}
		// 处理错误
		utils.View(w, utils.WithStatusCode(http.StatusNotFound)).Text("不存在的文件：" + file)
})

备注：下载文件 View().Download()。

13. 打包压缩

13.1 zip
func utils.Zip
func Zip(zipFile string, files []string) error
参数 描述
zipFile 打包压缩后文件
files 待打包压缩文件【夹】

备注：使用 zip 打包并压缩；为保证安全，默认不支持符号链接打包。

func utils.UnZip
func UnZip(zipFile, destDir string) error
参数 描述
zipFile 代解压的文件
destDir 解压文件目录

备注：解压 zip 文件；默认仅允许解压到目标目录内，拒绝绝对路径、目录穿越和不支持的条目类型，并尽量恢复归档中的文件权限。

13.2 tar
func utils.Tar
func Tar(tarFile string, files []string) error
参数 描述
tarFile 打包后文件
files 待打包文件【夹】

备注：使用 tar 打包；为保证安全，默认不支持符号链接打包。

func utils.TarGz
func TarGz(tarGzFile string, files []string) error
参数 描述
tarGzFile 打包压缩后文件
files 待打包压缩文件【夹】

备注：使用 tar 打包并 gzip 压缩；为保证安全，默认不支持符号链接打包。

func utils.UnTar
func UnTar(tarFile, destDir string) error
参数 描述
tarFile 代解压的文件
destDir 解压文件目录

备注：解压 tar 或 tar.gz 文件；默认仅允许解压到目标目录内，拒绝绝对路径、目录穿越和不支持的条目类型，并尽量恢复归档中的文件权限。

14. 日志

14.1 默认日志（使用标准库的 log 包来记录日志）
设置日志等级和输出格式
// 日志等级
levelVar := &slog.LevelVar{}
levelVar.Set(slog.LevelDebug)

opts := &slog.HandlerOptions{
  AddSource: true,     // 输出日志的文件和行号
  Level:     levelVar, // 日志等级
}

//日志输出文件
file, err := os.OpenFile("sys.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
if err != nil {
  fmt.Printf("Failed to open error logger file: %v\n", err)
  return
}

// 日志输出格式
//handler := slog.NewTextHandler(os.Stdout, opts)
handler := slog.NewJSONHandler(io.MultiWriter(file, os.Stderr), opts)

// 修改默认的日志输出方式
slog.SetDefault(slog.New(handler))

备注：设置日志级别，小于该级别的日志不会输出；若需禁用默认输出，可将 handler 输出到 io.Discard 或设置更高日志级别。

15. 杂项

15.1 环境变量
func os.Getenv
func Getenv(key string) string

备注：获取环境变量。

func utils.GetEnv
func GetEnv(key string, defaultVal ...string) string
参数 描述
key 变量名。
defaultVal 未获取到时默认返回的值。

备注：获取环境变量。

func os.Setenv
func Setenv(key, value string) error

备注：设置环境变量。

func os.Unsetenv
func Unsetenv(key string) error

备注：删除环境变量。

15.2 IP
func utils.ServerIP
func ServerIP() string

备注：服务器对外IP。默认优先返回缓存值或本地网卡 IP，仅在本地 IP 不可用时才回退到 UDP 探测；如需控制超时可使用 ServerIPContext。

func utils.LocalIP
func LocalIP() string

备注：服务器本地IP。

func utils.ClientIP
func ClientIP(r *http.Request) string

备注：获取客户端 IP。默认仅在请求来自回环地址时信任 X-Forwarded-For / X-Real-IP，否则回退到 RemoteAddr，避免把所有私网来源都视为 可信代理。生产环境建议优先使用 ClientIPWithTrustedProxies 显式配置白名单。

func utils.NewTrustedProxies
func NewTrustedProxies(values ...string) (*TrustedProxies, error)

备注：构造可信代理白名单，支持单个 IP 或 CIDR，例如 10.0.0.10、10.0.0.0/8、fd00::/8。

func utils.ClientIPWithTrustedProxies
func ClientIPWithTrustedProxies(r *http.Request, trustedProxies *TrustedProxies) string

备注：使用显式可信代理白名单解析客户端 IP。生产环境建议按网关、负载均衡或 Ingress 固定地址配置可信代理；只有 RemoteAddr 命中白名单时才读取转发头。

15.3 三目运算
func utils.Ternary
func Ternary[T any](expr bool, trueVal, falseVal T) T
参数 描述
expr bool表达式。
trueVal expr为true时返回值。
falseVal expr为false时返回值。

备注：类似于三目运算的函数。

15.4 获取当前行号、方法名、文件地址
func utils.RuntimeInfo
func RuntimeInfo(skip int) *Frame

备注：获取当前行号、方法名、文件地址。

func utils.GetFunctionName
func GetFunctionName(i interface{}) string

备注：获取函数名（普通函数、结构体方法或匿名函数）。

15.5 重试机制
func utils.Retry
func Retry(maxRetries uint8, fn func(tries int) error) error
参数 描述
maxRetries 最大重试次数。
fn 要执行的函数，参数tries为当前第几次尝试，返回nil则停止重试。

备注：尝试执行 fn，如果 fn 返回错误则进行重试；当前退避从第一次失败后的 100ms~200ms 区间起步，按 2 倍指数退避并加入随机抖动，最大不超过 3s。 maxRetries 表示最大尝试次数，包含首次执行；当 maxRetries == 0 时会按 1 次处理。

15.6 带重试的一次性执行
struct utils.Once
var o utils.Once

// 执行带重试机制的函数调用（线程安全）
err := o.Do(func () error {
// 业务逻辑
return nil
}, 3) // 最大重试3次

// 重置状态，使其可再次执行
o.Reset()

备注：线程安全的带重试机制的一次性执行器；同一轮只会有一个 goroutine 真正执行目标函数，其余调用方等待最终结果。成功或最终失败后会缓存结果，需重新执行时调用 Reset()。

15.7 泛型对象池
struct utils.Pool
// 创建对象池
pool := utils.NewPool(func () *bytes.Buffer {
return new(bytes.Buffer)
}, utils.WithPoolReset(func (b *bytes.Buffer) {
b.Reset()
}))

// 获取对象
buf := pool.Get()

// 归还对象（自动执行重置逻辑）
pool.Put(buf)

备注：基于 sync.Pool 封装的泛型对象池，支持通过 WithPoolReset 设置对象归还时的重置函数；未传工厂函数时会回退为 new(T)， Put(nil) 会被安全忽略。

15.8 全局配置
func utils.Configure
func Configure(opts ...Option)

备注：设置全局参数入口，只需在程序入口处设置一次。目前支持通过 WithJSON 设置自定义 JSON 编解码器，通过 WithLogger 设置自定义日志实现。

// 使用自定义 JSON 编解码器
utils.Configure(utils.WithJSON(customMarshal, customUnmarshal))

// 使用自定义 Logger
utils.Configure(utils.WithLogger(customLogger))

Documentation

Overview

Example (LogrusLoggerAdapter)

Example_logrusLoggerAdapter 演示如何使用 logrus 日志库适配器 Example_logrusLoggerAdapter demonstrates how to use logrus logger adapter 

package main

import (
	"context"
	"fmt"

	utils "github.com/Is999/go-utils"
)

// logrusLoggerAdapter 将 logrus Logger 适配到 utils.Logger 接口
// logrusLoggerAdapter adapts logrus Logger to utils.Logger interface
//
// 使用示例 / Usage example:
// import "github.com/sirupsen/logrus"
//
// logrusLogger := logrus.New()
// adapter := &logrusLoggerAdapter{logger: logrusLogger}
// utils.Configure(utils.WithLogger(adapter))
type logrusLoggerAdapter struct {
	logger interface{}
}

func (l *logrusLoggerAdapter) Debug(msg string, args ...any) {

	fmt.Printf("[LOGRUS DEBUG] %s %v\n", msg, args)
}

func (l *logrusLoggerAdapter) Info(msg string, args ...any) {

	fmt.Printf("[LOGRUS INFO] %s %v\n", msg, args)
}

func (l *logrusLoggerAdapter) Warn(msg string, args ...any) {

	fmt.Printf("[LOGRUS WARN] %s %v\n", msg, args)
}

func (l *logrusLoggerAdapter) Error(msg string, args ...any) {

	fmt.Printf("[LOGRUS ERROR] %s %v\n", msg, args)
}

func (l *logrusLoggerAdapter) With(args ...any) utils.Logger {

	return &logrusLoggerAdapter{logger: l.logger}
}

func (l *logrusLoggerAdapter) Enabled(ctx context.Context, level utils.LogLevel) bool {

	return true
}

func main() {
	// 创建适配器实例
	logrusAdapter := &logrusLoggerAdapter{}

	// 直接使用适配器（因为 Configure 只能调用一次）
	// Use adapter directly (since Configure can only be called once)
	logrusAdapter.Info("Application started", "version", "2.0.0")
	logrusAdapter.Warn("Warning message")

}

Output:
[LOGRUS INFO] Application started [version 2.0.0]
[LOGRUS WARN] Warning message []
Example (ZapLoggerAdapter)

Example_zapLoggerAdapter 演示如何使用 zap 日志库适配器 Example_zapLoggerAdapter demonstrates how to use zap logger adapter 

package main

import (
	"context"
	"fmt"

	utils "github.com/Is999/go-utils"
)

// zapLoggerAdapter 将 zap Logger 适配到 utils.Logger 接口
// zapLoggerAdapter adapts zap Logger to utils.Logger interface
//
// 使用示例 / Usage example:
// import "go.uber.org/zap"
//
// zapLogger, _ := zap.NewProduction()
// adapter := &zapLoggerAdapter{logger: zapLogger.Sugar()}
// utils.Configure(utils.WithLogger(adapter))
type zapLoggerAdapter struct {
	logger interface{}
}

func (z *zapLoggerAdapter) Debug(msg string, args ...any) {

	fmt.Printf("[ZAP DEBUG] %s %v\n", msg, args)
}

func (z *zapLoggerAdapter) Info(msg string, args ...any) {

	fmt.Printf("[ZAP INFO] %s %v\n", msg, args)
}

func (z *zapLoggerAdapter) Warn(msg string, args ...any) {

	fmt.Printf("[ZAP WARN] %s %v\n", msg, args)
}

func (z *zapLoggerAdapter) Error(msg string, args ...any) {

	fmt.Printf("[ZAP ERROR] %s %v\n", msg, args)
}

func (z *zapLoggerAdapter) With(args ...any) utils.Logger {

	return &zapLoggerAdapter{logger: z.logger}
}

func (z *zapLoggerAdapter) Enabled(ctx context.Context, level utils.LogLevel) bool {

	return true
}

func main() {
	// 创建适配器实例
	zapAdapter := &zapLoggerAdapter{}

	// 直接使用适配器进行日志输出（演示目的）
	// Use adapter directly for logging output (demonstration purpose)
	zapAdapter.Info("Application started", "version", "1.0.0")
	zapAdapter.Debug("Debug information", "key", "value")

	// 使用 With 添加上下文字段（注意：此演示实现不保留上下文）
	// Use With to add context fields (note: this demo implementation doesn't retain context)
	childLogger := zapAdapter.With("request_id", "12345")
	childLogger.Info("Processing request")

}

Output:
[ZAP INFO] Application started [version 1.0.0]
[ZAP DEBUG] Debug information [key value]
[ZAP INFO] Processing request []

Index

Examples

Constants

View Source 
const (
	Byte int64 = 1 << (10 * iota) // 1Byte（字节）
	KB                            // 1024Byte = 1KB（千字节）
	MB                            // 1048576Byte = 1024KB = 1MB（兆字节）
	GB                            // 1073741824Byte = 1048576KB = 1024MB = 1GB（吉字节）
	TB                            // 1099511627776Byte = ...（太字节）
	PB                            // 1125899906842624Byte（拍字节）
	EB                            // 1152921504606846976Byte（艾字节）
)

计算机存储单位：Byte、KB、MB、GB、TB、PB、EB。 int64 最大支持到 EB 级别。

View Source 
const (
	YearTime   = "2006"            // 年份格式：4 位数字
	MonthTime  = YearTime + "01"   // 年月格式：YYYYMM
	DayTime    = MonthTime + "02"  // 年月日格式：YYYYMMDD
	HourTime   = DayTime + " 15"   // 年月日时格式：YYYYMMDDHH
	MinuteTime = HourTime + "04"   // 年月日时分格式：YYYYMMDDHHMM
	SecondTime = MinuteTime + "05" // 年月日时分秒格式：YYYYMMDDHHMMSS
)

时间格式化模板常量。 用于 time.Time.Format 方法，格式遵循 Go 的参考时间 "2006-01-02 15:04:05"。

View Source 
const (
	// ALPHA 英文字母：A-Za-z
	ALPHA = `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`

	// DIGIT 数字：0-9
	DIGIT = `0123456789`

	// ALNUM 英文字母+数字：A-Za-z0-9
	ALNUM = ALPHA + DIGIT
)

字符集常量用于随机字符串与校验码生成。

Variables

View Source 
var DONE = errors.New("DONE")

DONE 完成终止

View Source 
var RandSource = rand.New(rand.NewPCG(uint64(time.Now().UnixNano()), uint64(time.Now().UnixNano())))

RandSource rand

Functions

func Account 

func Account(value string, min, max uint8) error

Account 帐号验证(字母开头，允许字母数字下划线，长度在min-max之间)

func AddFileToTar 

func AddFileToTar(tarWriter *tar.Writer, fileToCompress string, baseDir string) error

AddFileToTar 添加文件【夹】到tar 

fileToCompress 需要压缩的文件
baseDir 打包文件根目录

func AddFileToZip 

func AddFileToZip(zipWriter *zip.Writer, fileToCompress string, baseDir string) error

AddFileToZip 添加文件【夹】到zip 

fileToCompress 需要压缩的文件
baseDir 打包文件根目录

func AddPEMHeaders added in v1.21.5 

func AddPEMHeaders(key, keyType string) (string, error)

AddPEMHeaders 为 RSA 密钥串添加 PEM 头尾标记。

keyType 支持 public/private。

func AddTime added in v1.21.4 

func AddTime(t time.Time, addTimes ...string) (time.Time, error)

AddTime 对时间进行增减计算。 支持的时间单位：Y(年)、M(月)、D(日)、H(时)、I(分)、S(秒)、L(毫秒)、C(微秒)、N(纳秒)。 使用 + 或 - 前缀表示增加或减少。

参数说明：

  • t：原始时间
  • addTimes：增减时间列表，如 "-1D"、"+2H"、"1M"

返回值：计算后的时间，错误信息

示例： 

AddTime(t, "-1D", "+2H", "30S") // 减1天，加2小时，加30秒

func After 

func After(layout string, t1, t2 string) (bool, error)

After 比较 t1 是否在 t2 之后。

参数说明：

  • layout：时间格式化模板
  • t1：第一个时间字符串
  • t2：第二个时间字符串

返回值：true 表示 t1 在 t2 之后，错误信息

func Alnum added in v1.22.10 

func Alnum(value string) bool

Alnum 英文字母+数字验证

func Alpha 

func Alpha(value string) bool

Alpha 英文字母验证

func Amount 

func Amount(amount string, decimal uint8, signed ...bool) bool

Amount 金额验证 

amount 金额字符串
decimal 保留小数位长度
signed 带符号的金额: 默认无符号

func Before 

func Before(layout string, t1, t2 string) (bool, error)

Before 比较 t1 是否在 t2 之前。

参数说明：

  • layout：时间格式化模板
  • t1：第一个时间字符串
  • t2：第二个时间字符串

返回值：true 表示 t1 在 t2 之前，错误信息

func BinDec 

func BinDec(str string) (int64, error)

BinDec 二进制转换为十进制

func BinHex 

func BinHex(str string) (string, error)

BinHex 二进制转换为十六进制

func BinOct 

func BinOct(str string) (string, error)

BinOct 二进制转换为八进制

func CST 

func CST() *time.Location

CST 获取中国标准时区（东八区）。

返回值：*time.Location UTC+8 时区

func Certificate 

func Certificate(config *tls.Config, certFile, keyFile string) error

Certificate 设置客户端证书。

参数说明：

  • config：TLS 配置
  • certFile：证书文件路径
  • keyFile：私钥文件路径

返回值：错误信息

func CheckDate 

func CheckDate(year, month, day int) bool

CheckDate 验证日期是否合法。

参数说明：

  • year：年份（1-32767）
  • month：月份（1-12）
  • day：日期（1-31）

返回值：true 表示日期合法

func ClientIP 

func ClientIP(r *http.Request) string

ClientIP 获取客户端 IP 地址。 默认仅在请求来自回环地址时信任转发头，生产环境建议使用 ClientIPWithTrustedProxies 显式配置白名单。

参数说明：

  • r：HTTP 请求对象

返回值：客户端 IP 地址字符串

func ClientIPWithTrustedProxies added in v1.22.15 

func ClientIPWithTrustedProxies(r *http.Request, trustedProxies *TrustedProxies) string

ClientIPWithTrustedProxies 使用显式可信代理白名单解析客户端 IP。 仅当 RemoteAddr 命中 trustedProxies 时才信任 `X-Forwarded-For` / `X-Real-Ip`。

参数说明：

  • r：HTTP 请求对象
  • trustedProxies：可信代理白名单

返回值：客户端 IP 地址字符串

func Configure added in v1.22.13 

func Configure(opts ...Option)

Configure 设置全局参数入口。只需在程序入口处设置一次。

func Copy 

func Copy(src, dst string) error

Copy 拷贝文件 

src 拷贝的源文件
dst 拷贝后的文件

func Date 

func Date(timeZone *time.Location, layout string, timestamp ...int64) string

Date 使用 patterns 规则格式化时间。 patterns 支持 PHP 风格的格式化符（如 Y-m-d H:i:s）。

参数说明：

  • timeZone：目标时区
  • layout：格式化模板
  • timestamp：可变参数，Unix 时间戳

返回值：格式化后的时间字符串

示例： 

Date(CST(), "Y-m-d H:i:s", 1700000000) // "2023-11-15 01:46:40"

func DateInfo 

func DateInfo(t time.Time) map[string]interface{}

DateInfo 获取时间的详细信息映射表。

参数说明：

  • t：待解析的时间

返回值：包含年月日时分秒、周信息、时间戳等的 map

返回值字段说明：

  • year: 年份
  • month: 月份（1-12）
  • monthEn: 英文月份
  • day: 日期
  • hour: 小时（0-23）
  • minute: 分钟（0-59）
  • second: 秒数（0-59）
  • millisecond: 毫秒
  • microsecond: 微秒
  • nanosecond: 纳秒
  • unix: 时间戳（秒）
  • unixNano: 时间戳（纳秒）
  • weekDay: 星期几（0-6，0 为周日）
  • weekDayEn: 英文星期
  • yearWeek: 一年中第几周
  • yearDay: 一年中第几天
  • date: 格式化日期 "2006-01-02 15:04:05"
  • dateNs: 格式化日期（纳秒精度）"2006-01-02T15:04:05.999999999Z07:00"

func DecBin 

func DecBin(number int64) string

DecBin 十进制转换为二进制

func DecHex 

func DecHex(number int64) string

DecHex 十进制转换为十六进制

func DecOct 

func DecOct(number int64) string

DecOct 十进制转换为八进制

func Diff added in v1.22.0 

func Diff[T comparable](s1, s2 []T) []T

Diff 计算 s1 与 s2 的差集，即 s1 中有而 s2 中没有的元素。 返回结果保持 s1 原有顺序，并保留 s1 中原本存在的重复值。

func DiffInto added in v1.22.19 

func DiffInto[T comparable](dst, s1, s2 []T) []T

DiffInto 将 s1 与 s2 的差集追加到 dst，并返回复用后的结果切片。 s2 被视为排除集合；返回结果保持 s1 顺序与重复值，适合权限、标签、状态列表等保序过滤场景。

func Domain 

func Domain(value string) bool

Domain 域名(64位内正确的域名，可包含中文、字母、数字和.-)

func DrainBody 

func DrainBody(b io.ReadCloser) ([]byte, io.ReadCloser, error)

DrainBody 读取 body 内容并恢复原始流。

参数说明：

  • b：io.ReadCloser

返回值：body 内容、恢复的 ReadCloser、错误信息

func Email 

func Email(value string) bool

Email 电子邮件验证

func Empty 

func Empty(value string) bool

Empty 空字符串验证

func Equal 

func Equal(layout string, t1, t2 string) (bool, error)

Equal 比较两个时间是否相等。

参数说明：

  • layout：时间格式化模板
  • t1：第一个时间字符串
  • t2：第二个时间字符串

返回值：true 表示相等，错误信息

func FileType added in v1.21.0 

func FileType(f *os.File) (string, error)

FileType 文件类型

func GenerateKeyRSA 

func GenerateKeyRSA(path string, bits int, pkcs ...bool) ([]string, error)

GenerateKeyRSA 生成 RSA 密钥文件。

path 为密钥存放目录；bits 为密钥位数；生产环境要求至少 2048。 pkcs[0] 控制公钥格式是否为 PKCS8，默认 true；pkcs[1] 控制私钥格式是否为 PKCS1，默认 true。

func GetEnv 

func GetEnv(key string, defaultVal ...string) string

GetEnv 获取环境变量值。 如果环境变量未设置或值为空，且提供了默认值参数，则返回默认值。

参数说明：

  • key：环境变量名
  • defaultVal：可选的默认值，当环境变量未设置时返回

返回值：环境变量值或默认值

func GetFunctionName added in v1.22.12 

func GetFunctionName(i interface{}) string

GetFunctionName 获取函数名（普通函数、结构体方法或匿名函数）

func HasCount 

func HasCount[T comparable](v T, s []T) (count int)

HasCount 统计v在s中出现次数

func HasSymbols 

func HasSymbols(value string) bool

HasSymbols 是否包含符号

func HexBin 

func HexBin(data string) (string, error)

HexBin 十六进制转换为二进制

func HexDec 

func HexDec(str string) (int64, error)

HexDec 十六进制转换为十进制

func HexOct 

func HexOct(str string) (string, error)

HexOct 十六进制转换为八进制

func Intersect added in v1.22.0 

func Intersect[T comparable](s1, s2 []T) []T

Intersect 计算 s1 与 s2 的交集，即 s1 中有而 s2 中也有的元素。 返回结果保持 s1 原有顺序，并保留 s1 中原本存在的重复值。

func IntersectInto added in v1.22.19 

func IntersectInto[T comparable](dst, s1, s2 []T) []T

IntersectInto 将 s1 与 s2 的交集追加到 dst，并返回复用后的结果切片。 s2 被视为命中集合；返回结果保持 s1 顺序与重复值，适合按白名单过滤但不打乱业务排序的场景。

func IsDir 

func IsDir(path string) bool

IsDir 判断给定路径是否是一个目录

func IsExist 

func IsExist(path string) bool

IsExist 判断一个文件（夹）是否存在

func IsFile 

func IsFile(filepath string) bool

IsFile 判断给定的文件路径名是否是一个文件

func IsHas 

func IsHas[T comparable](v T, s []T) bool

IsHas 检查 s 中是否存在 v。1.21 版本以上推荐使用标准库 slices.Contains(s, v)。

func Line 

func Line(r io.Reader, handle ReadLine) error

Line 读取一行数据: 读取大文件大行数据性能略优于Scan

func Local 

func Local() *time.Location

Local 获取系统运行时区。

返回值：*time.Location 系统当前时区

func LocalIP 

func LocalIP() string

LocalIP 获取本机 IP 地址。 优先返回主机名对应的 IPv4 地址，如果获取失败则遍历网络接口。

返回值：本地 IP 地址字符串，获取失败返回空字符串

func MapDiff 

func MapDiff[K comparable, V comparable](m1, m2 map[K]V) []V

MapDiff 计算 m1 与 m2 的值差集，即 m1 中有但 m2 中没有的值。 返回结果保留 m1 原有遍历结果中的重复值。

func MapDiffKey 

func MapDiffKey[K Ordered, V any](m1, m2 map[K]V) []K

MapDiffKey 计算m1与m2的键差集即m1中有但m2中没有的键

func MapFilter 

func MapFilter[K Ordered, V any](m map[K]V, f func(key K, value V) bool) map[K]V

MapFilter 使用回调函数过滤map的元素 

f 函数接收key与value，返回一个bool值，如果f函数返回false则过滤掉该元素（删除该元素）

func MapIntersect 

func MapIntersect[K comparable, V comparable](m1, m2 map[K]V) []V

MapIntersect 计算 m1 与 m2 的值交集，即 m1 与 m2 都有的值。 返回结果保留 m1 原有遍历结果中的重复值。

func MapIntersectKey 

func MapIntersectKey[K Ordered, V any](m1, m2 map[K]V) []K

MapIntersectKey 计算m1与m2的键交集即m1与m2都有的键

func MapKeys 

func MapKeys[K Ordered, V any](m map[K]V) []K

MapKeys 获取map的所有key

func MapRange 

func MapRange[K Ordered, V any](m map[K]V, f func(key K, value V) bool, isReverse ...bool)

MapRange 有序遍历map元素，对map的key排序并按排序后的key遍历m 

f 函数接收key与value，返回一个bool值，如果f函数返回false则终止遍历
isReverse 是否降序排列：true 降序，false 升序

func MapValues 

func MapValues[K Ordered, V any](m map[K]V, isReverse ...bool) []V

MapValues 获取 map 的所有 value。 

isReverse 是否降序排列：true 降序，false 升序，未指定则不排序直接返回所有 value

func Marshal 

func Marshal(v any) ([]byte, error)

Marshal 对数据进行 JSON 编码

func Md5 

func Md5(str string) string

Md5 返回字符串的 MD5 十六进制摘要。

安全说明：MD5 已不适合密码存储、签名、完整性安全校验等安全场景； 该函数仅用于历史协议兼容或非安全哈希标识。

func MixStr 

func MixStr(value string) bool

MixStr 英文、数字、特殊字符(不包含换行符)

func Mobile 

func Mobile(value string) bool

Mobile 中国大陆手机号码验证

func MonthDay 

func MonthDay(year int, month int) (days int)

MonthDay 获取指定年份月份的天数。

参数说明：

  • year：年份
  • month：月份（1-12）

返回值：该月的天数

func NoPadding added in v1.22.15 

func NoPadding(data []byte, _ int) []byte

NoPadding 表示不做任何填充，适合 CTR/CFB/OFB/GCM 等流式或 AEAD 模式。 返回值会复制原始数据，避免调用方后续修改原切片影响加密流程。

func NoUnPadding added in v1.22.15 

func NoUnPadding(data []byte) ([]byte, error)

NoUnPadding 表示不做任何去填充，适合 CTR/CFB/OFB/GCM 等流式或 AEAD 模式。 返回值会复制原始数据，避免调用方后续修改结果影响后续处理。

func NumberFormat 

func NumberFormat(number float64, decimals uint, decPoint, thousandsSep string) string

NumberFormat 以千位分隔符方式格式化一个数字 

number 要格式化的数字
decimals 保留几位小数
decPoint 小数点[.]
thousandsSep 千位分隔符[,]

func Numeric 

func Numeric(value string) bool

Numeric 有符号数字验证

func OctBin 

func OctBin(data string) (string, error)

OctBin 八进制转换为二进制

func OctDec 

func OctDec(str string) (int64, error)

OctDec 八进制转换为十进制

func OctHex 

func OctHex(data string) (string, error)

OctHex 八进制转换为十六进制

func PassWord 

func PassWord(value string, min, max uint8) error

PassWord 密码(字母开头，允许字母数字下划线，长度在 min - max之间)

func PassWord2 

func PassWord2(value string, min, max uint8) error

PassWord2 强密码(必须包含大小写字母和数字的组合，不能使用特殊字符，长度在min-max之间)

func PassWord3 

func PassWord3(value string, min, max uint8) error

PassWord3 强密码(必须包含大小写字母和数字的组合，可以使用特殊字符，长度在min-max之间)

func Phone 

func Phone(value string) bool

Phone 中国大陆电话号码验证

func Pkcs7Padding 

func Pkcs7Padding(data []byte, blockSize int) []byte

Pkcs7Padding 按 PKCS#7 规则填充数据。

返回值总是新切片，避免 append 复用调用方底层数组导致原始数据被意外修改。

func Pkcs7UnPadding 

func Pkcs7UnPadding(data []byte) ([]byte, error)

Pkcs7UnPadding 去除 PKCS#7 填充。

会严格校验填充长度和每个填充字节，避免损坏密文被误当作合法明文。

func ProxyURL 

func ProxyURL(transport *http.Transport, proxyURL string) error

ProxyURL 设置 HTTP 代理。

参数说明：

  • transport：HTTP Transport
  • proxyURL：代理地址

返回值：错误信息

func QQ 

func QQ(value string) bool

QQ QQ号验证

func Rand 

func Rand(minInt, maxInt int64, r ...*rand.Rand) int64

Rand 返回 min ~ max 之间的随机数，返回值可能包含 min 和 max。

参数说明：

  • minInt：最小值
  • maxInt：最大值
  • r：可选的随机数生成器，批量生成时传入 r 参数可提升生成随机数效率

返回值：min ~ max 之间的随机整数

func RandStr 

func RandStr(n int, r ...*rand.Rand) string

RandStr 随机生成字符串，使用 ALPHA 规则。 注意：该函数基于 math/rand，仅适用于测试数据、临时标识等非安全场景。 禁止用于 token、验证码、重置链接、签名密钥等安全敏感用途；安全场景请使用 SecureRandStr。 

n 生成字符串长度
r 随机种子 rand.NewSource(time.Now().UnixNano()) : 批量生成时传入r参数可提升生成随机数效率

func RandStr2 

func RandStr2(n int, r ...*rand.Rand) string

RandStr2 随机生成字符串，使用 ALNUM 规则。 为兼容旧行为，首字符固定从 ALPHA 中选择，避免数字开头。 注意：该函数基于 math/rand，仅适用于测试数据、临时标识等非安全场景。 禁止用于 token、验证码、重置链接、签名密钥等安全敏感用途；安全场景请使用 SecureRandStr2。 

n 生成字符串长度
r 随机种子 rand.NewSource(time.Now().UnixNano()) : 批量生成时传入r参数可提升生成随机数效率

func RandStr3 

func RandStr3(n int, alpha string, r ...*rand.Rand) string

RandStr3 随机生成字符串。 注意：该函数基于 math/rand，仅适用于测试数据、临时标识等非安全场景。 禁止用于 token、验证码、重置链接、签名密钥等安全敏感用途；安全场景请使用 SecureRandStr3。 

n 生成字符串长度
alpha 生成随机字符串的种子
r 随机种子 rand.NewSource(time.Now().UnixNano()) : 批量生成时传入r参数可提升生成随机数效率

func Read 

func Read(r io.Reader, handle ReadBlock) error

Read 使用分块读取文件数据, 读取大文件或无换行的文件

func Redirect 

func Redirect(w http.ResponseWriter, url string, opts ...ResponseOption)

Redirect 重定向。

url 为重定向地址。状态码仅接受 3xx，非 3xx 会回退为 302。

Example 
serveMux.HandleFunc("/response/redirect", func(w http.ResponseWriter, r *http.Request) {
	// 重定向
	utils.Redirect(w, "/response/json")
})

func RemovePEMHeaders added in v1.21.5 

func RemovePEMHeaders(pemText string) string

RemovePEMHeaders 去掉 PEM 头尾标记和空白字符。

func Replace 

func Replace(s string, oldnew map[string]string) string

Replace 字符串替换 

s 源字符串
oldnew 替换规则，map类型，map 的键为要替换的字符串，map 的值为替换后的字符串。

func Retry added in v1.22.12 

func Retry(maxRetries uint8, fn func(tries int) error) error

Retry 尝试执行 fn，如果 fn 返回错误则按指数退避策略重试。 maxRetries 表示最大尝试次数，包含首次执行。 重试间隔从 100ms~200ms 区间起步，按 2 倍递增，并在每次退避上附加随机抖动，最大不超过 3s。

func RetryContext added in v1.22.17 

func RetryContext(ctx context.Context, maxRetries uint8, fn func(ctx context.Context, tries int) error) error

RetryContext 尝试执行 fn，如果 fn 返回错误则按指数退避策略重试。 当 ctx 被取消时，会立即中断后续重试与等待。

func Reverse 

func Reverse[T any](s []T) []T

Reverse 反转 s。1.21 版本以上推荐使用标准库 slices.Reverse(s)。

func RootCAs 

func RootCAs(config *tls.Config, rootCAs string) error

RootCAs 设置根证书池。 默认会在系统根证书池基础上追加自定义根证书，避免误把系统根证书整体替换掉。

参数说明：

  • config：TLS 配置
  • rootCAs：根证书文件路径

返回值：错误信息

func Round 

func Round(num float64, precision int) float64

Round 对 num 进行四舍五入，并保留指定小数位。

参数说明：

  • num：待处理的浮点数
  • precision：保留的小数位数（可以为负数）

返回值：四舍五入后的浮点数

func Scan 

func Scan(r io.Reader, handle ReadScan, size ...int) error

Scan 使用scan扫描文件每一行数据 

size 设置Scanner.maxTokenSize 的大小(默认值: 64*1024): 单行内容大于该值则无法读取

func SecureRandStr added in v1.22.17 

func SecureRandStr(n int) (string, error)

SecureRandStr 使用密码学安全随机源生成字符串，使用 ALPHA 规则。

参数说明：

  • n：生成字符串长度

返回值：随机字符串、错误信息

func SecureRandStr2 added in v1.22.17 

func SecureRandStr2(n int) (string, error)

SecureRandStr2 使用密码学安全随机源生成字符串，使用 ALNUM 规则。 为兼容历史命名习惯，首字符固定从 ALPHA 中选择，避免数字开头。

参数说明：

  • n：生成字符串长度

返回值：随机字符串、错误信息

func SecureRandStr3 added in v1.22.17 

func SecureRandStr3(n int, alpha string) (string, error)

SecureRandStr3 使用密码学安全随机源按自定义字符集生成字符串。

参数说明：

  • n：生成字符串长度
  • alpha：候选字符集

返回值：随机字符串、错误信息

func SecureUniqID added in v1.22.17 

func SecureUniqID(l uint8) (string, error)

SecureUniqID 使用密码学安全随机源生成长度范围 16-32 位的字符串标识。 与 UniqID 不同，SecureUniqID 不依赖时间戳，不保证可排序。

参数说明：

  • l：生成长度，取值范围 [16-32]

返回值：随机字符串、错误信息

func ServerIP 

func ServerIP() string

ServerIP 获取服务器对外 IP 地址。 默认优先返回缓存值或本地网卡 IP，避免在热路径上频繁拨号外网地址。 如需自定义超时控制，可使用 ServerIPContext。

返回值：服务器对外 IP 地址字符串，获取失败返回空字符串

func ServerIPContext added in v1.22.17 

func ServerIPContext(ctx context.Context) string

ServerIPContext 获取服务器出站 IP 地址，并允许调用方控制超时。 默认优先返回缓存值或本地网卡 IP，仅在本地 IP 不可用时才回退到 UDP 探测。

参数说明：

  • ctx：上下文，可用于控制超时或取消

返回值：服务器出站 IP 地址字符串，获取失败返回空字符串

func Sha1 

func Sha1(str string) string

Sha1 返回字符串的 SHA-1 十六进制摘要。

安全说明：SHA-1 已不适合签名、证书、密码存储等安全场景； 该函数仅用于历史协议兼容或非安全哈希标识。

func Sha256 

func Sha256(str string) string

Sha256 返回字符串的 SHA-256 十六进制摘要。 适合普通摘要场景；密码存储仍应使用 bcrypt/argon2/scrypt 等专用算法。

func Sha512 

func Sha512(str string) string

Sha512 返回字符串的 SHA-512 十六进制摘要。 适合普通摘要场景；密码存储仍应使用 bcrypt/argon2/scrypt 等专用算法。

func Size 

func Size(filepath string) (int64, error)

Size 取得文件大小

func SizeFormat 

func SizeFormat(size int64, decimals uint) string

SizeFormat 文件大小格式化已可读式显示文件大小 

size 文件实际大小(Byte)
decimals 保留几位小数

func Str2Float 

func Str2Float(s string) (i float64)

Str2Float string 转 float64，失败返回零值。

func Str2Int 

func Str2Int(s string) (i int)

Str2Int string 转 int，失败返回零值。

func Str2Int64 

func Str2Int64(s string) (i int64)

Str2Int64 string 转 int64，失败返回零值。

func StrRev 

func StrRev(str string) string

StrRev 反转字符串

func Strtotime 

func Strtotime(timeZone *time.Location, parse ...string) (t time.Time, err error)

Strtotime 解析时间字符串（智能解析）。 支持多种常见格式自动识别，也支持指定格式解析。

参数说明：

  • timeZone：目标时区
  • parse：可变参数，第一个为格式化模板，第二个为时间字符串

返回值：解析后的时间，错误信息

示例： 

Strtotime(CST(), "2006-01-02 15:04:05") // 当前时间（如果解析失败）
Strtotime(CST(), "2006-01-02 15:04:05", "2024-01-01 12:00:00") // 指定时间
Strtotime(CST(), "Y-m-d H:i:s") // 当前时间

func Sub 

func Sub(layout string, t1, t2 string) (time.Duration, error)

Sub 计算两个时间的差值。

参数说明：

  • layout：时间格式化模板
  • t1：第一个时间字符串
  • t2：第二个时间字符串

返回值：t1 - t2 的时间差，错误信息

func Substr 

func Substr(str string, start, length int) string

Substr 字符串截取 

str 被截取的字符串
start  截取的起始位置，即截取的第一个字符所在的索引：
	- start小于0时，start = len(str) + start
length  截取的截止位置，即截取的最后一个字符所在的索引：
	- length大于0时，length表示为截取子字符串的长度，截取的最后一个字符所在的索引值为：start + length
	- length小于0时，length表示为截取的最后一个字符所在的索引，值为：len(str) + length + 1
	- 例如：等于-1时，表示截取到最后一个字符；等于-2时，表示截取到倒数第二个字符

func SumMap added in v1.22.12 

func SumMap[K comparable, V Number](m map[K]V) V

SumMap 计算 map 的值和。

func SumSlice added in v1.22.12 

func SumSlice[T Number](nums []T) T

SumSlice 求和

func Tar 

func Tar(tarFile string, files []string) error

Tar 使用tar打包 

tarFile 打包后文件
files 待打包文件【夹】

func TarGz 

func TarGz(tarGzFile string, files []string) error

TarGz 使用tar打包gzip压缩 

tarGzFile 打包压缩后文件
files 待打包压缩文件【夹】

func Ternary 

func Ternary[T any](expr bool, trueVal, falseVal T) T

Ternary 类似于三目运算 

expr bool表达式
trueVal expr为true时返回值
falseVal expr为false时返回值

func TimeDay 

func TimeDay(value string) bool

TimeDay 时间格式验证 yyyy-MM-dd

func TimeFormat 

func TimeFormat(timeZone *time.Location, layout string, timestamp ...int64) string

TimeFormat 将时间戳格式化为字符串。

参数说明：

  • timeZone：目标时区
  • layout：格式化模板，如 "2006-01-02 15:04:05"
  • timestamp：可变参数，Unix 时间戳（秒），支持传入纳秒

返回值：格式化后的时间字符串

示例： 

TimeFormat(CST(), "2006-01-02 15:04:05", 1700000000)
TimeFormat(CST(), "2006-01-02 15:04:05", 1700000000000000000) // 纳秒时间戳

func TimeMonth 

func TimeMonth(value string) bool

TimeMonth 时间格式验证 yyyy-MM yyyy/MM

func TimeParse 

func TimeParse(timeZone *time.Location, layout, timeStr string) (time.Time, error)

TimeParse 解析时间字符串为 time.Time。

参数说明：

  • timeZone：目标时区
  • layout：格式化模板
  • timeStr：时间字符串

返回值：解析后的时间，错误信息

func Timestamp 

func Timestamp(value string) bool

Timestamp 时间格式验证 yyyy-MM-dd hh:mm:ss

func URLPath added in v1.22.15 

func URLPath(urlPath string, params url.Values) (string, error)

URLPath 组装带参数的完整 URL。 将 params 中的查询参数合并到 urlPath 中，保留原有查询参数。

参数说明：

  • urlPath：基础 URL 路径
  • params：查询参数键值对

返回值：完整 URL 字符串，错误信息

func UTC 

func UTC() *time.Location

UTC 获取 UTC 时区。

返回值：*time.Location UTC 时区

func UnIntZero added in v1.22.10 

func UnIntZero(value string) bool

UnIntZero 无符号整数(正整数+0)验证

func UnInteger 

func UnInteger(value string) bool

UnInteger 无符号整数(正整数)验证

func UnNumeric 

func UnNumeric(value string) bool

UnNumeric 无符号数字验证

func UnTar 

func UnTar(tarFile, destDir string) error

UnTar 解压.tar或.tar.gz文件 

tarFile 代解压的文件
destDir 解压文件目录

func UnZip 

func UnZip(zipFile, destDir string) error

UnZip 解压zip文件 

zipFile 代解压的文件
destDir 解压文件目录

func UniqID added in v1.22.15 

func UniqID(l uint8, r ...*rand.Rand) string

UniqID 生成一个长度范围 16-32 位的唯一 ID 字符串（可排序字符串）。 UniqID 只生成字符串标识，不承诺全局强唯一；强唯一场景建议使用业务唯一键或 UUID/ULID。 注意：该函数基于时间戳与 math/rand，仅适用于非安全场景。 禁止用于 token、验证码、重置链接等安全敏感用途；安全场景请使用 SecureUniqID。 

l 生成 UniqID 长度: 取值范围[16-32], 小于16按16位处理, 大于32按32位处理
r 随机种子 rand.NewSource(time.Now().UnixNano()) : 批量生成时传入r参数可提升生成随机数效率

func UniqId deprecated 

func UniqId(l uint8, r ...*rand.Rand) string

UniqId 生成一个长度范围 16-32 位的唯一 ID 字符串。

Deprecated: 请使用 UniqID。

func Unique added in v1.22.0 

func Unique[T comparable](s []T) []T

Unique 去除 s 中重复的值。 返回结果保持首个元素出现顺序；返回切片使用新的底层数组，避免调用方误改原始数据。

func UniqueInPlace added in v1.22.19 

func UniqueInPlace[T comparable](s []T) []T

UniqueInPlace 在 s 的原始底层数组上完成去重并返回结果切片。 业务意图：调用方明确不再需要原始顺序完整数据时，可用该入口省掉结果切片分配；边界是返回后 s 尾部旧数据不可再视为有效结果。

func UniqueInto added in v1.22.19 

func UniqueInto[T comparable](dst, s []T) []T

UniqueInto 将 s 去重后追加到 dst，并返回复用后的结果切片。 dst 的历史内容会被清空但容量会被复用；适合循环内批量处理时降低临时切片分配。

func Unmarshal 

func Unmarshal(data []byte, v any) error

Unmarshal 对数据进行 JSON 解码

func UrlPath deprecated 

func UrlPath(urlPath string, params url.Values) (string, error)

UrlPath 组装带参数的完整 URL。

Deprecated: 请使用 URLPath。

func WriteFileAtomic added in v1.22.17 

func WriteFileAtomic(fileName string, data []byte, perm os.FileMode) error

WriteFileAtomic 原子写入完整文件内容。 适用于配置文件、密钥文件、状态文件等需要“覆盖即完整替换”的场景。 内部使用同目录临时文件 + Sync + Close + Rename，避免直接 O_TRUNC 截断目标文件。

参数说明：

  • fileName：目标文件路径
  • data：完整文件内容
  • perm：文件权限

func WriteStringAtomic added in v1.22.17 

func WriteStringAtomic(fileName, data string, perm os.FileMode) error

WriteStringAtomic 原子写入完整字符串内容。 适用于希望以字符串形式原子覆盖目标文件的场景。

参数说明：

  • fileName：目标文件路径
  • data：完整字符串内容
  • perm：文件权限

func ZeroPadding 

func ZeroPadding(data []byte, blockSize int) []byte

ZeroPadding 使用 0 字节填充到分组大小的整数倍。

注意：ZeroPadding 无法区分明文末尾真实的 0 字节和填充字节，协议允许时优先使用 PKCS#7。

func ZeroUnPadding 

func ZeroUnPadding(data []byte) ([]byte, error)

ZeroUnPadding 去除尾部 0 字节填充。

func Zh 

func Zh(value string) bool

Zh 中文字符验证

func Zip 

func Zip(zipFile string, files []string) error

Zip 使用zip打包并压缩 

zipFile 打包压缩后文件
files 待打包压缩文件【夹】

Types

type Body 

type Body struct {
	Success bool   `json:"success"` // 响应状态：true 成功，false 失败
	Code    int    `json:"code"`    // 业务识别码
	Message string `json:"message"` // 响应信息
	Data    any    `json:"data"`    // 响应数据
}

Body JSON 响应体。

type Cipher 

type Cipher struct {
	// contains filtered or unexported fields
}

Cipher 是 AES/DES/3DES 的通用分组加密器。

架构说明：

  • key 和固定 IV 在构造后只读，Encrypt/Decrypt 过程中不再修改对象状态，便于并发复用。
  • WithRandIV(true) 时，加密会把随机 IV 写入密文头部，解密会从密文头部读取 IV。
  • ECB、非认证流模式与“未显式设置 IV 时使用 key 派生 IV”都属于兼容旧系统的保留能力，默认禁用。
  • 公开 API 同时支持传统 padding 语义和 `NoPadding/NoUnPadding` 零额外拷贝路径。

func AES 

func AES(key string, opts ...CipherOption) (*Cipher, error)

AES AES加密解密 

key 秘钥

func DES 

func DES(key string, opts ...CipherOption) (*Cipher, error)

DES 创建 DES/3DES 分组密码封装。

安全说明：DES 密钥空间过小，3DES 也属于历史兼容算法；新系统应优先使用 AES-GCM。 当 key 长度为 24 字节时自动使用 3DES，长度为 8 字节时使用 DES。 

key 秘钥

func DES3 

func DES3(key string, opts ...CipherOption) (*Cipher, error)

DES3 创建 3DES 分组密码封装。

安全说明：3DES 仅用于旧协议兼容，新系统应优先使用 AES-GCM。 

key 秘钥

func NewCipher 

func NewCipher(key string, block CipherBlock, opts ...CipherOption) (*Cipher, error)

NewCipher 创建通用分组加密器。

key 为原始密钥字符串；block 通常传 aes.NewCipher、des.NewCipher 或 des.NewTripleDESCipher。

func (*Cipher) Decrypt 

func (c *Cipher) Decrypt(encrypt string, mode McryptMode, decode DecodeString, unPadding UnPadding) (string, error)

Decrypt 解密编码后的密文字符串。

encrypt 为待解密数据；decode 为解码方法；unPadding 为去填充方法。

func (*Cipher) DecryptBytes added in v1.22.15 

func (c *Cipher) DecryptBytes(data []byte, mode McryptMode, unPadding UnPadding) ([]byte, error)

DecryptBytes 解密原始密文字节。

参数说明：

  • data：待解密密文。
  • mode：解密模式。
  • unPadding：去填充函数。

返回值：明文字节，错误信息。

func (*Cipher) DecryptCBC 

func (c *Cipher) DecryptCBC(data []byte, unPadding UnPadding) ([]byte, error)

DecryptCBC 使用 CBC 模式解密。

参数说明：

  • data：待解密密文。
  • unPadding：去填充函数。

返回值：明文字节，错误信息。

func (*Cipher) DecryptCFB 

func (c *Cipher) DecryptCFB(data []byte, unPadding UnPadding) ([]byte, error)

DecryptCFB 使用 CFB 模式解密。

参数说明：

  • data：待解密密文。
  • unPadding：去填充函数。

返回值：明文字节，错误信息。

func (*Cipher) DecryptCTR 

func (c *Cipher) DecryptCTR(data []byte, unPadding UnPadding) ([]byte, error)

DecryptCTR 使用 CTR 模式解密。

参数说明：

  • data：待解密密文。
  • unPadding：去填充函数。

返回值：明文字节，错误信息。

func (*Cipher) DecryptECB 

func (c *Cipher) DecryptECB(data []byte, unPadding UnPadding) ([]byte, error)

DecryptECB 使用 ECB 模式解密。

参数说明：

  • data：待解密密文。
  • unPadding：去填充函数。

返回值：明文字节，错误信息。

func (*Cipher) DecryptGCM added in v1.22.15 

func (c *Cipher) DecryptGCM(data, additionalData []byte) ([]byte, error)

DecryptGCM 使用 GCM(AEAD) 模式解密。

参数说明：

  • data：nonce + 密文字节。
  • additionalData：附加认证数据，可为空；加解密两端必须完全一致。

返回值：明文字节，错误信息。

func (*Cipher) DecryptGCMString added in v1.22.15 

func (c *Cipher) DecryptGCMString(encrypt string, decode DecodeString, additionalData []byte) (string, error)

DecryptGCMString 使用 GCM 模式解密编码后的密文字符串。

func (*Cipher) DecryptOFB 

func (c *Cipher) DecryptOFB(data []byte, unPadding UnPadding) ([]byte, error)

DecryptOFB 使用 OFB 模式解密。

参数说明：

  • data：待解密密文。
  • unPadding：去填充函数。

返回值：明文字节，错误信息。

func (*Cipher) DecryptTo added in v1.22.19 

func (c *Cipher) DecryptTo(dst, data []byte, mode McryptMode, unPadding UnPadding) ([]byte, error)

DecryptTo 将解密结果追加到 dst 并返回结果切片。 业务意图：高频解密场景可复用调用方缓冲区，减少明文字节切片分配；CTR/CFB/OFB 且 NoUnPadding 时走直接写入快路径。

参数说明：

  • dst：调用方提供的输出缓冲区，历史内容会保留，新明文追加在末尾。
  • data：待解密密文，不能与 dst 的可写容量部分重叠，避免流解密覆盖尚未读取的密文。
  • mode：解密模式。
  • unPadding：去填充函数。

返回值：追加明文后的 dst，错误信息。

func (*Cipher) Encrypt 

func (c *Cipher) Encrypt(data string, mode McryptMode, encode EncodeToString, padding Padding) (string, error)

Encrypt 加密字符串并编码输出。

data 为待加密数据；mode 为加密模式；encode 为编码方法；padding 为填充方法。

func (*Cipher) EncryptBytes added in v1.22.15 

func (c *Cipher) EncryptBytes(data []byte, mode McryptMode, padding Padding) ([]byte, error)

EncryptBytes 加密字节数据并返回原始密文字节。

该方法适合业务层自行选择编码方式，可避免 string 与 []byte 的额外转换。

参数说明：

  • data：待加密原始数据。
  • mode：加密模式。
  • padding：填充函数。

返回值：密文字节，错误信息。

func (*Cipher) EncryptCBC 

func (c *Cipher) EncryptCBC(data []byte, padding Padding) ([]byte, error)

EncryptCBC 使用 CBC 模式加密。

参数说明：

  • data：待加密原始数据。
  • padding：填充函数。

返回值：密文字节，错误信息。

func (*Cipher) EncryptCFB 

func (c *Cipher) EncryptCFB(data []byte, padding Padding) ([]byte, error)

EncryptCFB 使用 CFB 模式加密。

参数说明：

  • data：待加密原始数据。
  • padding：填充函数。

返回值：密文字节，错误信息。

func (*Cipher) EncryptCTR 

func (c *Cipher) EncryptCTR(data []byte, padding Padding) ([]byte, error)

EncryptCTR 使用 CTR 模式加密。

参数说明：

  • data：待加密原始数据。
  • padding：填充函数。

返回值：密文字节，错误信息。

func (*Cipher) EncryptECB 

func (c *Cipher) EncryptECB(data []byte, padding Padding) ([]byte, error)

EncryptECB 使用 ECB 模式加密。

参数说明：

  • data：待加密的原始数据。
  • padding：填充函数。

返回值：密文字节，错误信息。

func (*Cipher) EncryptGCM added in v1.22.15 

func (c *Cipher) EncryptGCM(data, additionalData []byte) ([]byte, error)

EncryptGCM 使用 GCM(AEAD) 模式加密。

安全说明：

  • 该模式自带完整性校验，优先级高于 CBC/CTR/CFB/OFB 等非认证模式。
  • 每次加密都会随机生成 nonce，并写入密文头部，解密时自动解析。

参数说明：

  • data：待加密原始数据。
  • additionalData：附加认证数据，可为空；加解密两端必须完全一致。

返回值：nonce + 密文字节，错误信息。

func (*Cipher) EncryptGCMString added in v1.22.15 

func (c *Cipher) EncryptGCMString(data string, encode EncodeToString, additionalData []byte) (string, error)

EncryptGCMString 使用 GCM 模式加密字符串并编码输出。

func (*Cipher) EncryptOFB 

func (c *Cipher) EncryptOFB(data []byte, padding Padding) ([]byte, error)

EncryptOFB 使用 OFB 模式加密。

参数说明：

  • data：待加密原始数据。
  • padding：填充函数。

返回值：密文字节，错误信息。

func (*Cipher) EncryptTo added in v1.22.19 

func (c *Cipher) EncryptTo(dst, data []byte, mode McryptMode, padding Padding) ([]byte, error)

EncryptTo 将加密结果追加到 dst 并返回结果切片。 业务意图：高频加密场景可复用调用方缓冲区，减少密文字节切片分配；CTR/CFB/OFB 且 NoPadding 时走零填充复制快路径。

参数说明：

  • dst：调用方提供的输出缓冲区，历史内容会保留，新密文追加在末尾。
  • data：待加密原始数据，不能与 dst 的可写容量部分重叠，避免流加密覆盖尚未读取的明文。
  • mode：加密模式。
  • padding：填充函数。

返回值：追加密文后的 dst，错误信息。

type CipherBlock 

type CipherBlock func([]byte) (cipher.Block, error)

CipherBlock 密码(AES | DES)

  • aes.NewCipher
  • des.NewCipher
  • des.NewTripleDESCipher

type CipherOption added in v1.22.13 

type CipherOption func(*cipherOptions)

CipherOption 加密器配置项。

func WithAllowUnsafeECB added in v1.22.15 

func WithAllowUnsafeECB(allow bool) CipherOption

WithAllowUnsafeECB 设置是否允许使用 ECB 模式。

安全说明：

  • 默认不允许，避免在生产环境中误用会泄露明文模式特征的 ECB。
  • 仅在兼容旧系统密文协议时才建议显式开启。

func WithAllowUnsafeKeyIV added in v1.22.15 

func WithAllowUnsafeKeyIV(allow bool) CipherOption

WithAllowUnsafeKeyIV 设置是否允许在未显式配置 IV 时退回到 key 派生 IV。

安全说明：

  • 默认不允许，避免把固定且与密钥相关的 IV 当作生产默认值。
  • 仅在兼容历史密文或旧系统协议时才建议显式开启。

func WithAllowUnsafeStreamMode added in v1.22.15 

func WithAllowUnsafeStreamMode(allow bool) CipherOption

WithAllowUnsafeStreamMode 设置是否允许使用 CTR/CFB/OFB 等非认证流模式。

安全说明：

  • 默认不允许，避免在生产环境中误用已不推荐的非认证模式。
  • 仅在兼容旧系统密文协议时才建议显式开启。

func WithIV added in v1.22.13 

func WithIV(iv string) CipherOption

WithIV 设置固定 IV。

IV 长度必须等于算法分组长度：AES 为 16 字节，DES/3DES 为 8 字节。

func WithRandIV added in v1.22.13 

func WithRandIV(isRand bool) CipherOption

WithRandIV 设置是否随机生成 IV。

如果同时设置 WithIV，则固定 IV 优先，随机 IV 自动关闭。

type Curl 

type Curl struct {
	Logger Logger // 日志实例
	// contains filtered or unexported fields
}

Curl HTTP 请求客户端。 支持链式调用，配置丰富，功能完善：

  • GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS 七种 HTTP 方法
  • Header/Params/Cookie/Body 配置
  • BasicAuth/Proxy/TLS 认证配置
  • 请求重试/超时控制
  • 请求响应日志追踪

注意：Curl 实例的请求配置阶段不是并发安全的；多个 goroutine 并发请求时，应为每个请求分别创建 Curl 实例。

使用示例： 

utils.NewCurl().
    SetTimeout(10).
    SetHeader("Authorization", "Bearer xxx").
    SetParam("page", "1").
    SetBodyBytes(userData).
    AfterBody(func(body []byte) error {
        return json.Unmarshal(body, &result)
    }).
    Post("https://api.example.com/user")

func NewCurl 

func NewCurl(opts ...CurlOption) *Curl

New 创建一个新的 Curl 客户端实例。 默认配置：

  • 超时时间：30 秒
  • 最大重试：2 次
  • Content-Type：application/json
  • 显式传入 X-Request-Id 时立即绑定；未传入时首次发送或读取请求 ID 时自动生成

参数说明：

  • opts：可选的配置项列表

返回值：配置好的 Curl 客户端指针

func (*Curl) AddCookies 

func (c *Curl) AddCookies(cookies ...*http.Cookie) *Curl

AddCookies 添加 Cookie 列表。 不会清空现有 Cookie，而是增量添加。

参数说明：

  • cookies：可变数量的 Cookie

返回值：Curl 指针，支持链式调用

func (*Curl) AddHeader 

func (c *Curl) AddHeader(key string, values ...string) *Curl

AddHeader 对请求头键添加多个值。

参数说明：

  • key：请求头键名
  • values：多个值

返回值：Curl 指针，支持链式调用

func (*Curl) AddHeaders 

func (c *Curl) AddHeaders(headers map[string][]string) *Curl

AddHeaders 批量添加请求头值。

参数说明：

  • headers：请求头映射，值为切片

返回值：Curl 指针，支持链式调用

func (*Curl) AddParam 

func (c *Curl) AddParam(key string, values ...string) *Curl

AddParam 对查询参数键添加多个值。

参数说明：

  • key：参数键名
  • values：多个值

返回值：Curl 指针，支持链式调用

func (*Curl) AddParams 

func (c *Curl) AddParams(params map[string][]string) *Curl

AddParams 批量添加查询参数值。

参数说明：

  • params：查询参数映射，值为切片

返回值：Curl 指针，支持链式调用

func (*Curl) AfterBody added in v1.22.13 

func (c *Curl) AfterBody(f func(body []byte) error) *Curl

AfterBody 请求发送后对 Response.Body 的处理回调。

参数说明：

  • f：回调函数，接收 body 字节数组

返回值：Curl 指针，支持链式调用

func (*Curl) AfterBodyContext added in v1.22.17 

func (c *Curl) AfterBodyContext(f func(ctx context.Context, body []byte) error) *Curl

AfterBodyContext 请求发送后对 Response.Body 的上下文处理回调。

func (*Curl) AfterDone added in v1.22.13 

func (c *Curl) AfterDone(f func(client *http.Client, request *http.Request, response *http.Response)) *Curl

AfterDone 请求完成后的回调。 用于资源清理，如关闭连接等。 注意：client、request、response 有可能为 nil。

参数说明：

  • f：回调函数

返回值：Curl 指针，支持链式调用

func (*Curl) AfterDoneContext added in v1.22.17 

func (c *Curl) AfterDoneContext(f func(ctx context.Context, client *http.Client, request *http.Request, response *http.Response)) *Curl

AfterDoneContext 请求完成后的上下文回调。

func (*Curl) AfterResponse added in v1.22.13 

func (c *Curl) AfterResponse(f func(response *http.Response) (isDone bool, err error)) *Curl

AfterResponse 请求发送后的回调。

参数说明：

  • f：回调函数，isDone=true 时终止后续代码执行

返回值：Curl 指针，支持链式调用

func (*Curl) AfterResponseContext added in v1.22.17 

func (c *Curl) AfterResponseContext(f func(ctx context.Context, response *http.Response) (isDone bool, err error)) *Curl

AfterResponseContext 请求发送后的上下文回调。

func (*Curl) BeforeClient added in v1.22.13 

func (c *Curl) BeforeClient(f func(client *http.Client) error) *Curl

BeforeClient 请求发送前的 Client 回调。

参数说明：

  • f：回调函数，返回 error 时中断请求

返回值：Curl 指针，支持链式调用

func (*Curl) BeforeClientContext added in v1.22.17 

func (c *Curl) BeforeClientContext(f func(ctx context.Context, client *http.Client) error) *Curl

BeforeClientContext 请求发送前的 Client 上下文回调。

func (*Curl) BeforeRequest added in v1.22.13 

func (c *Curl) BeforeRequest(f func(request *http.Request) error) *Curl

BeforeRequest 请求发送前的回调。

参数说明：

  • f：回调函数，返回 error 时中断请求

返回值：Curl 指针，支持链式调用

func (*Curl) BeforeRequestContext added in v1.22.17 

func (c *Curl) BeforeRequestContext(f func(ctx context.Context, request *http.Request) error) *Curl

BeforeRequestContext 请求发送前的上下文回调。

func (*Curl) ClearCookies 

func (c *Curl) ClearCookies() *Curl

ClearCookies 清空所有 Cookie。

返回值：Curl 指针，支持链式调用

func (*Curl) Clone added in v1.22.17 

func (c *Curl) Clone() (*Curl, error)

Clone 深拷贝当前 Curl 配置。 适用于以当前 Curl 为模板派生新的请求实例，避免多个 goroutine 共享可变请求状态。 Clone 会复用底层 Transport 连接池，但会复制 Header/Params/Cookie/Body 等请求级配置。

返回值：新的 Curl 指针、错误信息

func (*Curl) CloseIdleConnections 

func (c *Curl) CloseIdleConnections()

CloseIdleConnections 关闭所有空闲连接并释放 Transport。

func (*Curl) DelCookies 

func (c *Curl) DelCookies(cookieName ...string) *Curl

DelCookies 删除指定的 Cookie。

参数说明：

  • cookieName：可变数量的 Cookie 名称

返回值：Curl 指针，支持链式调用

func (*Curl) DelHeaders 

func (c *Curl) DelHeaders(keys ...string) *Curl

DelHeaders 删除指定的请求头。

参数说明：

  • keys：可变数量的键名

返回值：Curl 指针，支持链式调用

func (*Curl) DelParams 

func (c *Curl) DelParams(keys ...string) *Curl

DelParams 删除指定的查询参数。

参数说明：

  • keys：可变数量的键名

返回值：Curl 指针，支持链式调用

func (*Curl) Delete 

func (c *Curl) Delete(url string) (err error)

Delete 发起 DELETE 请求。

func (*Curl) DeleteContext added in v1.22.17 

func (c *Curl) DeleteContext(ctx context.Context, url string) (err error)

DeleteContext 发起带 context 的 DELETE 请求。

func (*Curl) Get 

func (c *Curl) Get(url string) (err error)

Get 发起 GET 请求。

func (*Curl) GetContext added in v1.22.17 

func (c *Curl) GetContext(ctx context.Context, url string) (err error)

GetContext 发起带 context 的 GET 请求。

func (*Curl) GetCookie 

func (c *Curl) GetCookie(cookieName string) *http.Cookie

GetCookie 获取指定名称的 Cookie。

参数说明：

  • cookieName：Cookie 名称

返回值：*http.Cookie，不存在时返回 nil

func (*Curl) GetHeader 

func (c *Curl) GetHeader() http.Header

GetHeader 获取当前请求头配置。

返回值：http.Header 请求头映射

func (*Curl) GetHeaderValues 

func (c *Curl) GetHeaderValues(key string) []string

GetHeaderValues 获取请求头中指定键的所有值。

参数说明：

  • key：请求头键名

返回值：值列表

func (*Curl) GetParamValues 

func (c *Curl) GetParamValues(key string) []string

GetParamValues 获取查询参数中指定键的值。

参数说明：

  • key：参数键名

返回值：值列表

func (*Curl) GetParams 

func (c *Curl) GetParams() url.Values

GetParams 获取当前 URL 查询参数。

返回值：url.Values 查询参数映射

func (*Curl) GetRequestID added in v1.22.15 

func (c *Curl) GetRequestID() string

GetRequestID 获取当前请求 ID。 未显式设置时会懒生成默认 ID，确保读取行为与发送请求时的链路 ID 一致。

func (*Curl) GetRequestId deprecated 

func (c *Curl) GetRequestId() string

GetRequestId 获取当前请求 ID。

Deprecated: 请使用 GetRequestID。

func (*Curl) GetStatusCode added in v1.22.15 

func (c *Curl) GetStatusCode() []int

GetStatusCode 获取当前允许通过校验的状态码列表副本。

返回值：状态码切片副本，调用方修改不会影响 Curl 内部状态。

func (*Curl) HasCookie 

func (c *Curl) HasCookie(cookieName string) bool

HasCookie 检查是否设置了给定名称的 Cookie。

参数说明：

  • cookieName：Cookie 名称

返回值：true 表示已设置

func (*Curl) HasHeader 

func (c *Curl) HasHeader(key string) bool

HasHeader 检查请求头中是否设置了指定的键。

参数说明：

  • key：请求头键名

返回值：true 表示已设置

func (*Curl) HasParam 

func (c *Curl) HasParam(key string) bool

HasParam 检查查询参数中是否设置了给定的键。

参数说明：

  • key：参数键名

返回值：true 表示已设置

func (*Curl) Head 

func (c *Curl) Head(url string) error

Head 发起 HEAD 请求。

func (*Curl) HeadContext added in v1.22.17 

func (c *Curl) HeadContext(ctx context.Context, url string) error

HeadContext 发起带 context 的 HEAD 请求。

func (*Curl) InsecureSkipVerify 

func (c *Curl) InsecureSkipVerify(isSkip bool) *Curl

InsecureSkipVerify 设置是否跳过 HTTPS 不安全验证。 注意：生产环境禁止使用，存在安全风险。

参数说明：

  • isSkip：true 跳过验证，false 进行验证

返回值：Curl 指针，支持链式调用

func (*Curl) NewRequest added in v1.22.17 

func (c *Curl) NewRequest() (*Curl, error)

NewRequest 基于当前 Curl 配置派生新的请求实例。 与 Clone 不同，NewRequest 会为新实例生成新的请求 ID，适合把当前 Curl 作为并发安全的模板复用。

返回值：新的 Curl 指针、错误信息

func (*Curl) Options 

func (c *Curl) Options(url string) (err error)

Options 发起 OPTIONS 请求。

func (*Curl) OptionsContext added in v1.22.17 

func (c *Curl) OptionsContext(ctx context.Context, url string) (err error)

OptionsContext 发起带 context 的 OPTIONS 请求。

func (*Curl) Patch 

func (c *Curl) Patch(url string) (err error)

Patch 发起 PATCH 请求。

func (*Curl) PatchContext added in v1.22.17 

func (c *Curl) PatchContext(ctx context.Context, url string) (err error)

PatchContext 发起带 context 的 PATCH 请求。

func (*Curl) Post 

func (c *Curl) Post(url string) (err error)

Post 发起 POST 请求。

func (*Curl) PostContext added in v1.22.17 

func (c *Curl) PostContext(ctx context.Context, url string) (err error)

PostContext 发起带 context 的 POST 请求。

func (*Curl) PostForm 

func (c *Curl) PostForm(url string) error

PostForm 发起 POST Form 请求。

func (*Curl) PostFormContext added in v1.22.17 

func (c *Curl) PostFormContext(ctx context.Context, url string) error

PostFormContext 发起带 context 的 POST Form 请求。

func (*Curl) Put 

func (c *Curl) Put(url string) (err error)

Put 发起 PUT 请求。

func (*Curl) PutContext added in v1.22.17 

func (c *Curl) PutContext(ctx context.Context, url string) (err error)

PutContext 发起带 context 的 PUT 请求。

func (*Curl) ReSetHeader 

func (c *Curl) ReSetHeader(header http.Header) *Curl

ReSetHeader 重置请求头。 如果 header 为 nil，清空所有现有请求头；否则替换为新的请求头。

参数说明：

  • header：新的请求头（可选）

返回值：Curl 指针，支持链式调用

func (*Curl) ReSetParams 

func (c *Curl) ReSetParams(params url.Values) *Curl

ReSetParams 重置查询参数。 如果 params 为 nil，清空所有现有参数；否则替换为新的参数。

参数说明：

  • params：新的查询参数（可选）

返回值：Curl 指针，支持链式调用

func (*Curl) Send 

func (c *Curl) Send(method, url string, body io.Reader) (err error)

Send 发起 HTTP 请求。 封装完整请求生命周期：构建 Request、配置 Client/Transport、执行重试、处理响应。

参数说明：

  • method：HTTP 方法（GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS）
  • url：请求地址
  • body：请求体

返回值：错误信息

func (*Curl) SendContext added in v1.22.17 

func (c *Curl) SendContext(ctx context.Context, method, url string, body io.Reader) (err error)

SendContext 发起带 context 的 HTTP 请求。 当 ctx 被取消时，会立即中断请求以及重试等待。

func (*Curl) SetBasicAuth 

func (c *Curl) SetBasicAuth(username, password string) *Curl

SetBasicAuth 设置 Basic 认证的账号及密码。

参数说明：

  • username：账号
  • password：密码

返回值：Curl 指针，支持链式调用

func (*Curl) SetBody 

func (c *Curl) SetBody(body io.Reader) *Curl

SetBody 设置请求体。

参数说明：

  • body：io.Reader 类型的请求体

返回值：Curl 指针，支持链式调用

func (*Curl) SetBodyBytes 

func (c *Curl) SetBodyBytes(body []byte) *Curl

SetBodyBytes 设置请求体字节。 内部会将字节数组包装为 bytes.Reader。

参数说明：

  • body：字节数组

返回值：Curl 指针，支持链式调用

func (*Curl) SetCertKey 

func (c *Curl) SetCertKey(cert, key string) *Curl

SetCertKey 设置客户端证书和私钥。

参数说明：

  • cert：证书文件路径
  • key：私钥文件路径

返回值：Curl 指针，支持链式调用

func (*Curl) SetContentType 

func (c *Curl) SetContentType(contentType string) *Curl

SetContentType 设置请求头 Content-Type。 常见类型：

  • "application/x-www-form-urlencoded"
  • "application/json"
  • "multipart/form-data"
  • "text/plain"

参数说明：

  • contentType：Content-Type 值

返回值：Curl 指针，支持链式调用

func (*Curl) SetCookies 

func (c *Curl) SetCookies(cookies ...*http.Cookie) *Curl

SetCookies 设置 Cookie 列表。 会先清空现有 Cookie，再添加新的 Cookie。

参数说明：

  • cookies：可变数量的 Cookie

返回值：Curl 指针，支持链式调用

func (*Curl) SetDefLogOutput added in v1.21.0 

func (c *Curl) SetDefLogOutput(enable bool) *Curl

SetDefLogOutput 设置默认日志输出开关。 true：打印 INFO 及以下级别日志；false：禁止打印默认日志。

func (*Curl) SetDump 

func (c *Curl) SetDump(dump bool) *Curl

SetDump 设置是否开启 dump 模式。 dump 模式会详细打印请求和响应的信息。

参数说明：

  • dump：true 开启，false 关闭

返回值：Curl 指针，支持链式调用

func (*Curl) SetHeader 

func (c *Curl) SetHeader(key, value string) *Curl

SetHeader 设置单个请求头键值对。

参数说明：

  • key：请求头键名
  • value：请求头键值

返回值：Curl 指针，支持链式调用

func (*Curl) SetHeaders 

func (c *Curl) SetHeaders(headers map[string]string) *Curl

SetHeaders 批量设置请求头。

参数说明：

  • headers：请求头键值对映射

返回值：Curl 指针，支持链式调用

func (*Curl) SetLogBodyLimit added in v1.22.17 

func (c *Curl) SetLogBodyLimit(limit int64) *Curl

SetLogBodyLimit 设置默认日志 body 预览长度上限。 等于 0 表示不记录 body 预览。

func (*Curl) SetMaxRetry added in v1.21.0 

func (c *Curl) SetMaxRetry(max uint8) *Curl

SetMaxRetry 设置最大请求尝试次数。 max 包含首次请求；max=0 或 max=1 表示不额外重试，最大不超过 5。

参数说明：

  • max：最大请求尝试次数

返回值：Curl 指针，支持链式调用

func (*Curl) SetParam 

func (c *Curl) SetParam(key, value string) *Curl

SetParam 设置单个查询参数。

参数说明：

  • key：参数键名
  • value：参数值

返回值：Curl 指针，支持链式调用

func (*Curl) SetParams 

func (c *Curl) SetParams(params map[string]string) *Curl

SetParams 批量设置查询参数。

参数说明：

  • params：查询参数字典

返回值：Curl 指针，支持链式调用

func (*Curl) SetProxyURL 

func (c *Curl) SetProxyURL(proxyURL string) *Curl

SetProxyURL 设置代理地址。

参数说明：

  • proxyURL：代理服务器 URL

返回值：Curl 指针，支持链式调用

func (*Curl) SetRequestID added in v1.22.15 

func (c *Curl) SetRequestID(requestID ...string) *Curl

SetRequestID 设置请求唯一标识。 如果未指定或为空字符串，自动生成 16 位唯一 ID。 设置后会自动更新 Logger 和 Header 中的 X-Request-Id。

func (*Curl) SetRequestId deprecated 

func (c *Curl) SetRequestId(requestId ...string) *Curl

SetRequestId 设置请求唯一标识。

Deprecated: 请使用 SetRequestID。

func (*Curl) SetRootCAs 

func (c *Curl) SetRootCAs(rootCAs string) *Curl

SetRootCAs 设置根证书。

参数说明：

  • rootCAs：根证书文件路径

返回值：Curl 指针，支持链式调用

func (*Curl) SetStatusCode 

func (c *Curl) SetStatusCode(statusCode ...int) *Curl

SetStatusCode 设置可接受的状态码列表。 当响应状态码不在列表中且不是 200 时，将返回错误。

参数说明：

  • statusCode：可变数量的状态码

返回值：Curl 指针，支持链式调用

func (*Curl) SetTimeout 

func (c *Curl) SetTimeout(timeout uint16) *Curl

SetTimeout 设置超时时间（秒）。

参数说明：

  • timeout：超时秒数

返回值：Curl 指针，支持链式调用

func (*Curl) SetUserAgent 

func (c *Curl) SetUserAgent(userAgent string) *Curl

SetUserAgent 设置请求头 User-Agent。

参数说明：

  • userAgent：User-Agent 字符串

返回值：Curl 指针，支持链式调用

type CurlOption added in v1.22.13 

type CurlOption func(*Curl)

CurlOption Curl 配置项函数类型。 用于通过选项模式配置 Curl 客户端实例。

func WithCurlBasicAuth added in v1.22.13 

func WithCurlBasicAuth(username, password string) CurlOption

WithBasicAuth 设置 BasicAuth 账号密码。

func WithCurlBody added in v1.22.13 

func WithCurlBody(body io.Reader) CurlOption

WithBody 设置请求体。

func WithCurlBodyBytes added in v1.22.13 

func WithCurlBodyBytes(body []byte) CurlOption

WithBodyBytes 设置请求体字节。

func WithCurlCertKey added in v1.22.13 

func WithCurlCertKey(cert, key string) CurlOption

WithCertKey 设置客户端证书和私钥。

func WithCurlContentType added in v1.22.13 

func WithCurlContentType(contentType string) CurlOption

WithContentType 设置请求头 Content-Type。

func WithCurlCookies added in v1.22.13 

func WithCurlCookies(cookies ...*http.Cookie) CurlOption

WithCookies 设置请求 Cookie。

func WithCurlDefLogOutput added in v1.22.13 

func WithCurlDefLogOutput(enable bool) CurlOption

WithDefLogOutput 设置默认日志输出开关。

func WithCurlDump added in v1.22.13 

func WithCurlDump(dump bool) CurlOption

WithDump 设置是否开启 dump 模式。

func WithCurlDumpBodyLimit added in v1.22.13 

func WithCurlDumpBodyLimit(limit int64) CurlOption

WithDumpBodyLimit 设置 dump 预览内容长度上限。

func WithCurlHeader added in v1.22.13 

func WithCurlHeader(key, value string) CurlOption

WithHeader 设置请求头键值。

func WithCurlHeaders added in v1.22.13 

func WithCurlHeaders(headers map[string]string) CurlOption

WithHeaders 批量设置请求头。

func WithCurlInsecureSkipVerify added in v1.22.13 

func WithCurlInsecureSkipVerify(isSkip bool) CurlOption

WithInsecureSkipVerify 设置是否跳过 HTTPS 验证（生产环境禁止使用）。

func WithCurlLogBodyLimit added in v1.22.17 

func WithCurlLogBodyLimit(limit int64) CurlOption

WithCurlLogBodyLimit 设置默认日志 body 预览长度上限。 小于 0 的值会被忽略；等于 0 表示不记录 body 预览。

func WithCurlLogger added in v1.22.13 

func WithCurlLogger(logger Logger) CurlOption

WithLogger 设置日志实例。

func WithCurlMaxRetry added in v1.22.13 

func WithCurlMaxRetry(max uint8) CurlOption

WithMaxRetry 设置最大请求尝试次数。

max 包含首次请求；max=0 或 max=1 表示不额外重试，最大不超过 5。

func WithCurlParams added in v1.22.13 

func WithCurlParams(params map[string]string) CurlOption

WithParams 批量设置请求参数。

func WithCurlProxyURL added in v1.22.13 

func WithCurlProxyURL(proxyURL string) CurlOption

WithProxyURL 设置代理地址。

func WithCurlRequestID added in v1.22.15 

func WithCurlRequestID(requestID string) CurlOption

WithCurlRequestID 设置请求 ID。

func WithCurlRequestId deprecated added in v1.22.13 

func WithCurlRequestId(requestId string) CurlOption

WithCurlRequestId 设置请求 ID。

Deprecated: 请使用 WithCurlRequestID。

func WithCurlRootCAs added in v1.22.13 

func WithCurlRootCAs(rootCAs string) CurlOption

WithRootCAs 设置根证书路径。

func WithCurlStatusCode added in v1.22.13 

func WithCurlStatusCode(statusCode ...int) CurlOption

WithStatusCode 设置可接受的状态码。

func WithCurlTimeout added in v1.22.13 

func WithCurlTimeout(timeout time.Duration) CurlOption

WithTimeout 设置默认超时时间。

type Decode 

type Decode func([]byte, any) error

Decode json反序列化方法

  • json.Unmarshal

type DecodeString added in v1.22.13 

type DecodeString func(string) ([]byte, error)

DecodeString 解密方法

  • hex.DecodeString
  • base64.StdEncoding.DecodeString

type Encode 

type Encode func(any) ([]byte, error)

Encode json序列化方法

  • json.Marshal

type EncodeToString added in v1.22.13 

type EncodeToString func([]byte) string

EncodeToString 加密方法

  • hex.EncodeToString
  • base64.StdEncoding.EncodeToString

type FileInfo 

type FileInfo struct {
	fs.FileInfo
	Path string // 文件绝对路径
}

FileInfo 文件信息

func FindFiles 

func FindFiles(path string, depth bool, match ...string) (files []FileInfo, err error)

FindFiles 获取目录下所有匹配文件 

path 目录
depth 深度查找: true 采用filepath.WalkDir遍历; false 只在当前目录查找
match 匹配规则:
 - `无参` : 匹配所有文件名 FindFiles(path, depth)
 - `*`   : 匹配所有文件名 FindFiles(path, depth, `*`)
 - `文件完整名`      : 精准匹配文件名 FindFiles(path, depth, fullFileName)
 - `e`, `文件完整名` : 精准匹配文件名 FindFiles(path, depth, `e`, fullFileName)
 - `p`, `文件前缀名` : 匹配前缀文件名 FindFiles(path, depth, `p`, fileNamePrefix)
 - `s`, `文件后缀名` : 匹配后缀文件名 FindFiles(path, depth, `s`, fileNameSuffix)
 - `r`, `正则表达式` : 正则匹配文件名 FindFiles(path, depth, `r`, fileNameReg)

type Float 

type Float interface {
	~float32 | ~float64
}

Float 浮点数

type Form 

type Form struct {
	// Params 表单普通字段
	Params url.Values

	// Files 表单文件字段（字段名 -> 文件路径列表）
	Files url.Values

	// MaxSingleFileSize 单个文件大小上限，单位：字节；小于等于 0 表示不限制
	MaxSingleFileSize int64

	// MaxTotalFileSize 所有文件总大小上限，单位：字节；小于等于 0 表示不限制
	MaxTotalFileSize int64
}

Form HTTP 表单。 用于构建 multipart/form-data 类型的请求，支持文件和普通字段。

func NewForm added in v1.22.15 

func NewForm() *Form

NewForm 创建一个新的 Form 实例。

返回值：*Form 表单指针

func (*Form) AddFile 

func (f *Form) AddFile(fieldName string, filePath ...string) *Form

AddFile 对文件字段添加多个文件路径。

参数说明：

  • fieldName：表单字段名
  • filePath：可变数量的文件路径

返回值：Form 指针，支持链式调用

func (*Form) AddFiles 

func (f *Form) AddFiles(files map[string][]string) *Form

AddFiles 批量添加文件字段。

参数说明：

  • files：文件字典，值为切片

返回值：Form 指针，支持链式调用

func (*Form) AddParam 

func (f *Form) AddParam(key string, values ...string) *Form

AddParam 对表单字段添加多个值。

参数说明：

  • key：字段名
  • values：多个值

返回值：Form 指针，支持链式调用

func (*Form) AddParams 

func (f *Form) AddParams(params map[string][]string) *Form

AddParams 批量添加表单字段值。

参数说明：

  • params：字段字典，值为切片

返回值：Form 指针，支持链式调用

func (*Form) DelFiles 

func (f *Form) DelFiles(fieldNames ...string)

DelFiles 删除指定的文件字段。

参数说明：

  • fieldNames：可变数量的字段名

func (*Form) DelParams 

func (f *Form) DelParams(keys ...string)

DelParams 删除指定的表单字段。

参数说明：

  • keys：可变数量的字段名

func (*Form) Reader 

func (f *Form) Reader() (body io.Reader, contentType string, err error)

Reader 读取 Form 内容，转换为可上传的 body 和 content-type。 如果没有文件，返回 application/x-www-form-urlencoded 格式； 如果有文件，返回 multipart/form-data 格式。

返回值：

  • body：io.Reader 请求体
  • contentType：Content-Type
  • err：错误信息

func (*Form) SetFile 

func (f *Form) SetFile(fieldName, filePath string) *Form

SetFile 设置单个文件字段。

参数说明：

  • fieldName：表单字段名
  • filePath：文件路径

返回值：Form 指针，支持链式调用

func (*Form) SetFiles 

func (f *Form) SetFiles(files map[string]string) *Form

SetFiles 批量设置文件字段。

参数说明：

  • files：文件字典（字段名 -> 文件路径）

返回值：Form 指针，支持链式调用

func (*Form) SetMaxSingleFileSize added in v1.22.17 

func (f *Form) SetMaxSingleFileSize(limit int64) *Form

SetMaxSingleFileSize 设置单个文件大小上限。

参数说明：

  • limit：单个文件大小上限，单位：字节；小于等于 0 表示不限制

返回值：Form 指针，支持链式调用

func (*Form) SetMaxTotalFileSize added in v1.22.17 

func (f *Form) SetMaxTotalFileSize(limit int64) *Form

SetMaxTotalFileSize 设置所有文件总大小上限。

参数说明：

  • limit：所有文件总大小上限，单位：字节；小于等于 0 表示不限制

返回值：Form 指针，支持链式调用

func (*Form) SetParam 

func (f *Form) SetParam(key, value string) *Form

SetParam 设置单个表单字段。

参数说明：

  • key：字段名
  • value：字段值

返回值：Form 指针，支持链式调用

func (*Form) SetParams 

func (f *Form) SetParams(params map[string]string) *Form

SetParams 批量设置表单字段。

参数说明：

  • params：字段字典

返回值：Form 指针，支持链式调用

type Frame added in v1.21.1 

type Frame struct {
	Func string // 方法名。
	File string // 文件名。
	Line int    // 行号。
}

Frame 保存调用栈中的函数、文件和行号信息。

func RuntimeInfo 

func RuntimeInfo(skip int) *Frame

RuntimeInfo 获取运行时行号、方法名、文件地址

type Integer 

type Integer interface {
	Signed | Unsigned
}

Integer 整数

type LogLevel added in v1.22.13 

type LogLevel int

LogLevel 日志级别类型，兼容各种第三方日志库 

const (
	// LevelDebug 调试级别 (-4 对应 slog.LevelDebug)
	LevelDebug LogLevel = -4
	// LevelInfo 信息级别 (0 对应 slog.LevelInfo)
	LevelInfo LogLevel = 0
	// LevelWarn 警告级别 (4 对应 slog.LevelWarn)
	LevelWarn LogLevel = 4
	// LevelError 错误级别 (8 对应 slog.LevelError)
	// 这些值与 slog.Level 保持一致，以便内部默认实现的平滑转换
	LevelError LogLevel = 8
)

日志级别常量与 slog 默认级别保持一致。

type Logger added in v1.22.13 

type Logger interface {
	// Debug 调试级别日志
	Debug(msg string, args ...any)
	// Info 信息级别日志
	Info(msg string, args ...any)
	// Warn 警告级别日志
	Warn(msg string, args ...any)
	// Error 错误级别日志
	Error(msg string, args ...any)
	// With 创建携带附加字段的子 Logger
	With(args ...any) Logger
	// Enabled 判断指定级别的日志是否启用
	Enabled(ctx context.Context, level LogLevel) bool
}

Logger 日志接口，可通过 Configure 设置自定义实现，若未设置则默认使用 log/slog 标准库。 该接口设计为与第三方日志库（如 zap、logrus 等）兼容。

func Log added in v1.22.13 

func Log() Logger

Log 获取全局 Logger 实例。 若未通过 Configure 设置自定义 Logger，则返回基于 log/slog 标准库的默认实现。

兼容第三方日志库说明: 本库 Logger 接口设计兼容 log/slog。若需使用 zap、logrus 等第三方库， 需编写适配器实现 Logger 接口，并通过 Configure(WithLogger(adapter)) 注入。 Example (Zap): 

type ZapAdapter struct { l *zap.Logger }
func (z *ZapAdapter) Debug(msg string, args ...any) { ... }
func (z *ZapAdapter) Enabled(ctx context.Context, level LogLevel) bool { ... }

type McryptMode 

type McryptMode int8

McryptMode 密码模式 

const (
	ECB McryptMode = iota // 0 电码本模式（Electronic Codebook Book，ECB），ECB 无须设置初始化向量 IV
	CBC                   // 1 密码分组链接模式（Cipher Block Chaining，CBC），如果明文长度不是分组长度 16 字节（DES 8 字节）的整数倍需要进行填充
	CTR                   // 2 计算器模式（Counter，CTR）
	CFB                   // 3 密码反馈模式（Cipher FeedBack，CFB）
	OFB                   // 4 输出反馈模式（Output FeedBack，OFB）
)

加密模式枚举。 用于指定分组密码的工作模式。

type Number 

type Number interface {
	Integer | Float
}

Number 数字

type Once added in v1.22.13 

type Once struct {
	// contains filtered or unexported fields
}

Once 提供带重试能力的一次性执行控制器。 同一轮生命周期内只会有一个 goroutine 真正执行目标函数，其余调用方等待最终结果。

func (*Once) Do added in v1.22.13 

func (r *Once) Do(f func() error, maxRetries int) error

Do 执行带重试能力的一次性调用。

参数说明：

  • f：待执行函数，无参数并返回 error
  • maxRetries：最大尝试次数，包含首次执行；小于等于 0 时按 1 次处理

返回值：

  • error：执行成功返回 nil，最终失败返回带重试次数的错误

特性：

  • 线程安全：同一时刻仅一个 goroutine 执行目标函数，其余 goroutine 等待结果
  • 使用有上限的指数退避策略，避免重试间隔无限增大
  • 成功或最终失败后都会缓存结果，后续调用直接复用；需重新执行时调用 Reset

func (*Once) DoContext added in v1.22.17 

func (r *Once) DoContext(ctx context.Context, f func(ctx context.Context) error, maxRetries int) error

DoContext 执行带重试能力的一次性调用。 当 ctx 被取消时，等待中的调用方会立即返回；真正执行中的 goroutine 也会在重试等待阶段响应取消。

func (*Once) Reset added in v1.22.13 

func (r *Once) Reset()

Reset 重置 Once 状态，使控制器进入下一轮可执行状态。

type Option added in v1.22.13 

type Option func(*options)

Option 用于配置全局设置入口的选项

func WithJSON added in v1.22.13 

func WithJSON(encode Encode, decode Decode) Option

WithJSON 设置自定义 JSON 编码、解码方法

func WithLogger added in v1.22.13 

func WithLogger(logger Logger) Option

WithLogger 设置自定义 Logger，若未设置则默认使用 log/slog 标准库。

type Ordered 

type Ordered interface {
	Number | ~string
}

Ordered 数字或字符串

type Padding 

type Padding func([]byte, int) []byte

Padding 填充数据方法

  • Pkcs7Padding
  • ZeroPadding

type Pool added in v1.22.11 

type Pool[T any] struct {
	// contains filtered or unexported fields
}

Pool 是带可选重置回调的泛型对象池。

适用场景：

  • 频繁复用临时对象，降低 GC 压力。
  • 需要在对象归还前清理内部状态。

func NewPool added in v1.22.11 

func NewPool[T any](newFn func() *T, opts ...PoolOption[T]) *Pool[T]

NewPool 创建泛型对象池。

参数说明：

  • newFn：对象工厂函数；为空时回退为 `new(T)`
  • opts：对象池配置项

返回值：泛型对象池指针

func (*Pool[T]) Get added in v1.22.11 

func (p *Pool[T]) Get() *T

Get 获取对象。

返回值：池中对象指针

func (*Pool[T]) Put added in v1.22.11 

func (p *Pool[T]) Put(x *T)

Put 放回对象。 若配置了重置函数，会先执行清理逻辑再归还对象。

参数说明：

  • x：待归还对象

type PoolOption added in v1.22.13 

type PoolOption[T any] func(*Pool[T])

PoolOption 对象池配置项。

func WithPoolReset added in v1.22.13 

func WithPoolReset[T any](resetFn func(*T)) PoolOption[T]

WithPoolReset 设置对象重置函数。

参数说明：

  • resetFn：对象归还前的状态清理函数

type RSA 

type RSA struct {
	// contains filtered or unexported fields
}

RSA 封装 RSA 公钥、私钥及常用加解密/签名能力。

说明：

  • RSA 自身适合加密小块数据；本实现会按密钥长度自动分块，便于加密较长字符串。
  • 新系统优先推荐 EncryptOAEP/DecryptOAEP；Encrypt/Decrypt(PKCS#1 v1.5) 主要用于兼容旧系统。
  • RSA 对象初始化后只读，公钥/私钥可被多个 goroutine 并发用于加解密和验签。

func NewPriRSA 

func NewPriRSA(pri string, opts ...RSAOption) (*RSA, error)

NewPriRSA 实例化只含私钥的 RSA，用于解密或签名。

func NewPubRSA 

func NewPubRSA(pub string, opts ...RSAOption) (*RSA, error)

NewPubRSA 实例化只含公钥的 RSA，用于加密或验签。

func NewRSA 

func NewRSA(pub, pri string, opts ...RSAOption) (*RSA, error)

NewRSA 实例化 RSA，并同时设置公钥和私钥。

func (*RSA) Decrypt 

func (r *RSA) Decrypt(encrypt string, decode DecodeString) (string, error)

Decrypt 使用私钥和 PKCS#1 v1.5 填充解密。

func (*RSA) DecryptOAEP added in v1.21.5 

func (r *RSA) DecryptOAEP(encrypt string, decode DecodeString, hash hash.Hash) (string, error)

DecryptOAEP 使用私钥和 OAEP 填充解密。

注意：hash.Hash 实例不是并发安全对象；并发场景推荐使用 DecryptOAEPHash，由方法内部创建摘要实例。

func (*RSA) DecryptOAEPHash added in v1.22.18 

func (r *RSA) DecryptOAEPHash(encrypt string, decode DecodeString, hashID crypto.Hash) (string, error)

DecryptOAEPHash 使用指定 crypto.Hash 创建独立摘要实例并执行 OAEP 解密。

该方法比直接传 hash.Hash 更适合高并发复用 RSA 对象，生产代码建议优先使用 SHA256 及以上摘要算法。

func (*RSA) Encrypt 

func (r *RSA) Encrypt(data string, encode EncodeToString) (string, error)

Encrypt 使用公钥和 PKCS#1 v1.5 填充加密。

生产新协议更建议使用 EncryptOAEP。

func (*RSA) EncryptOAEP added in v1.21.5 

func (r *RSA) EncryptOAEP(data string, encode EncodeToString, hash hash.Hash) (string, error)

EncryptOAEP 使用公钥和 OAEP 填充加密。

注意：hash.Hash 实例不是并发安全对象；并发场景推荐使用 EncryptOAEPHash，由方法内部创建摘要实例。

func (*RSA) EncryptOAEPHash added in v1.22.18 

func (r *RSA) EncryptOAEPHash(data string, encode EncodeToString, hashID crypto.Hash) (string, error)

EncryptOAEPHash 使用指定 crypto.Hash 创建独立摘要实例并执行 OAEP 加密。

该方法比直接传 hash.Hash 更适合高并发复用 RSA 对象，生产代码建议优先使用 SHA256 及以上摘要算法。

func (*RSA) IsSetPrivateKey 

func (r *RSA) IsSetPrivateKey() error

IsSetPrivateKey 校验私钥是否已设置。

func (*RSA) IsSetPublicKey 

func (r *RSA) IsSetPublicKey() error

IsSetPublicKey 校验公钥是否已设置。

func (*RSA) SetPrivateKey 

func (r *RSA) SetPrivateKey(privateKey string, isFilePath bool) error

SetPrivateKey 设置私钥。

privateKey 可以是 PEM 文本、去掉头尾后的 base64 DER 文本，或文件路径。

func (*RSA) SetPublicKey 

func (r *RSA) SetPublicKey(publicKey string, isFilePath bool) error

SetPublicKey 设置公钥。

publicKey 可以是 PEM 文本、去掉头尾后的 base64 DER 文本，或文件路径。

func (*RSA) Sign 

func (r *RSA) Sign(data string, hash crypto.Hash, encode EncodeToString) (string, error)

Sign 使用私钥生成 PKCS#1 v1.5 签名。

func (*RSA) SignPSS added in v1.21.5 

func (r *RSA) SignPSS(data string, hash crypto.Hash, encode EncodeToString, opts *rsa.PSSOptions) (string, error)

SignPSS 使用私钥生成 PSS 签名。

func (*RSA) Verify 

func (r *RSA) Verify(data, sign string, hash crypto.Hash, decode DecodeString) error

Verify 使用公钥验证 PKCS#1 v1.5 签名。

func (*RSA) VerifyPSS added in v1.21.5 

func (r *RSA) VerifyPSS(data, sign string, hash crypto.Hash, decode DecodeString, opts *rsa.PSSOptions) error

VerifyPSS 使用公钥验证 PSS 签名。

type RSAOption added in v1.22.13 

type RSAOption func(*rsaOptions)

RSAOption RSA 配置项。

func WithRSAFilePath added in v1.22.13 

func WithRSAFilePath(isFilePath bool) RSAOption

WithRSAFilePath 指定密钥参数是否为文件路径。

type ReadBlock 

type ReadBlock func(size int, block []byte) error

ReadBlock 处理读取的数据块

  • size 读取的数据块大小
  • block 读取的数据块 返回值 - error 处理错误信息: 返回的 error == DONE 代表正确处理完数据并终止扫描

type ReadLine 

type ReadLine func(num int, line []byte, lineDone bool) error

ReadLine 处理scan扫描的行数据

  • num 行号: 当前扫描到第几行
  • line 行数据: 当前扫描的行数据
  • lineDone 当前行(num)数据是否读取完毕: true 当前行(num)数据读取完毕; false 当前行(num)数据未读完 返回值 - error 处理错误信息: 返回的 error == DONE 代表正确处理完数据并终止扫描

type ReadScan 

type ReadScan func(num int, line []byte, err error) error

ReadScan 处理scan扫描的行数据

  • num 行号: 当前扫描到第几行
  • line 行数据: 当前扫描的行数据
  • WrapError 扫描错误信息 返回值 - error 处理错误信息: 返回的 error == DONE 代表正确处理完数据并终止扫描

type Replacer added in v1.22.19 

type Replacer struct {
	// contains filtered or unexported fields
}

Replacer 是可复用字符串替换器。

业务意图：

  • 当同一批替换规则被反复使用时，调用方可复用已排序和已构建的 strings.Replacer。
  • 替换规则来源于 map，构造时会固定排序，避免 map 遍历无序导致重叠替换规则结果不稳定。

func NewReplacer added in v1.22.19 

func NewReplacer(oldnew map[string]string) *Replacer

NewReplacer 根据 map 规则创建可复用字符串替换器。

oldnew 字段含义：

  • key：需要被替换的原字符串。
  • value：替换后的目标字符串。

func (*Replacer) Replace added in v1.22.19 

func (r *Replacer) Replace(s string) string

Replace 使用已构建规则替换字符串。

空规则或 nil 接收者会原样返回输入，便于调用方在条件化构造替换器时不额外判空。

type Response 

type Response struct {
	Body // JSON 响应体。
	// contains filtered or unexported fields
}

Response HTTP 响应构造器。

设计目标：

  • 易用：保留 Json(w).Success(...)、View(w).Text(...) 等链式调用。
  • 高性能：文本写入使用 io.WriteString，文件响应使用 http.ServeContent。
  • 稳定：统一管理状态码和响应头，避免重复 WriteHeader。
  • 安全：文件响应禁止目录输出，下载文件名会清洗 CR/LF 等危险字符。

func Json added in v1.22.13 

func Json(w http.ResponseWriter, opts ...ResponseOption) *Response

Json 创建 JSON 响应构造器。

Example 
// 响应json数据
serveMux.HandleFunc("/response/json", func(w http.ResponseWriter, r *http.Request) {
	// 获取URL查询字符串参数
	queryParam := r.URL.Query().Get("v")
	// 响应的数据
	user := User{
		Name:      "张三",
		Age:       22,
		Sex:       "男",
		IsMarried: false,
		Address:   "北京市",
		phone:     "131188889999",
	}

	if queryParam == "fail" {
		// 错误响应
		utils.Json(w, utils.WithStatusCode(http.StatusNotAcceptable)).Fail(20000, "fail")
		return
	}

	// 成功响应
	utils.Json(w).Success(10000, user)
})

func View 

func View(w http.ResponseWriter, opts ...ResponseOption) *Response

View 创建文本/文件响应构造器。

Example 
// 响应html
serveMux.HandleFunc("/response/html", func(w http.ResponseWriter, r *http.Request) {

	// 响应html数据
	utils.View(w).Html("<p>这是一个<b style=\"color: red\">段落!</b></p>")
})

// 响应xml
serveMux.HandleFunc("/response/xml", func(w http.ResponseWriter, r *http.Request) {

	// 响应的数据
	user := User{
		Name:      "张三",
		Age:       22,
		Sex:       "男",
		IsMarried: false,
		Address:   "北京市",
		phone:     "131188889999",
	}

	// 响应xml数据
	utils.View(w).Xml(user)
})

// 响应text
serveMux.HandleFunc("/response/text", func(w http.ResponseWriter, r *http.Request) {
	// 响应text数据
	utils.View(w).Text("<p>这是一个<b style=\"color: red\">段落!</b></p>")
})

// 显示image
serveMux.HandleFunc("/response/show", func(w http.ResponseWriter, r *http.Request) {
	// 获取URL查询字符串参数
	file := r.URL.Query().Get("file")
	if utils.IsExist(file) {
		// 显示文件内容

		utils.View(w).Show(file)
		return
	}
	// 处理错误
	utils.View(w, utils.WithStatusCode(http.StatusNotFound)).Text("不存在的文件：" + file)
})

// 下载文件
serveMux.HandleFunc("/response/download", func(w http.ResponseWriter, r *http.Request) {
	// 获取URL查询字符串参数
	file := r.URL.Query().Get("file")
	if utils.IsExist(file) {
		// 下载文件数据
		utils.View(w).Download(file)
		return
	}
	// 处理错误
	utils.View(w, utils.WithStatusCode(http.StatusNotFound)).Text("不存在的文件：" + file)
})

func (*Response) ContentType 

func (r *Response) ContentType(contentType string) *Response

ContentType 设置响应头 Content-Type。

func (*Response) Download 

func (r *Response) Download(filePath string, rename ...string)

Download 响应下载文件。

filePath 为本地文件路径，rename 可指定下载文件名。文件名会被清洗后写入 Content-Disposition，防止 CR/LF 注入和路径穿透式文件名。

func (*Response) DownloadRequest added in v1.22.15 

func (r *Response) DownloadRequest(req *http.Request, filePath string, rename ...string)

DownloadRequest 响应下载文件，并携带原始请求用于 Range/If-Modified-Since 等 HTTP 能力。

新代码建议在 Handler 中优先使用该方法；Download 会使用一个内部 GET 请求兜底。

func (*Response) Encode 

func (r *Response) Encode() ([]byte, error)

Encode 对 JSON 响应体编码。 使用默认标准库 JSON 时走手写响应包壳快路径；配置第三方 JSON 后回退到自定义编码器，避免改变调用方语义。

func (*Response) Fail 

func (r *Response) Fail(code int, message string, data ...any)

Fail 失败响应 JSON 数据。

code 为业务识别码，message 为响应信息，data 可选。

func (*Response) Header added in v1.22.13 

func (r *Response) Header(f func(header http.Header)) *Response

Header 设置响应头。

func (*Response) Html 

func (r *Response) Html(data string)

Html 响应 HTML 文本。

func (*Response) Show 

func (r *Response) Show(filePath string)

Show 响应显示文件内容，如图片、PDF、文本等。

func (*Response) ShowRequest added in v1.22.15 

func (r *Response) ShowRequest(req *http.Request, filePath string)

ShowRequest 响应显示文件内容，并携带原始请求用于 Range/If-Modified-Since 等 HTTP 能力。

新代码建议在 Handler 中优先使用该方法；Show 会使用一个内部 GET 请求兜底。

func (*Response) StatusCode 

func (r *Response) StatusCode(statusCode int) *Response

StatusCode 设置响应状态码，如 http.StatusOK。

func (*Response) Success 

func (r *Response) Success(code int, data any, message ...string)

Success 成功响应 JSON 数据。

code 为业务识别码，data 为响应数据，message 可选；未指定 message 时默认为 SUCCESS。

func (*Response) Text 

func (r *Response) Text(data string)

Text 响应纯文本。

func (*Response) Write 

func (r *Response) Write(body []byte)

Write 写入原始字节响应。

该方法只会写一次状态码；后续多次调用只继续写 body，避免重复 WriteHeader。

func (*Response) Xml 

func (r *Response) Xml(data any)

Xml 响应 XML 数据。

使用 xml.Marshal 而不是 MarshalIndent，减少生产接口中的额外 CPU 和内存开销。

type ResponseOption added in v1.22.13 

type ResponseOption func(*Response)

ResponseOption 响应配置项。

func WithContentType added in v1.22.13 

func WithContentType(contentType string) ResponseOption

WithContentType 设置响应头 Content-Type。

对 text/*、application/json、application/xml 等文本类型自动追加 charset=utf-8； 对 image/*、application/octet-stream 等二进制类型保持原值，避免错误 charset。

func WithHeader added in v1.22.13 

func WithHeader(f func(header http.Header)) ResponseOption

WithHeader 自定义响应头。

回调为 nil 时不做任何操作，便于条件化配置。

func WithStatusCode added in v1.22.13 

func WithStatusCode(statusCode int) ResponseOption

WithStatusCode 设置响应状态码。

仅接受标准 HTTP 状态码范围 [100, 599]，非法值会被忽略，避免 net/http panic。

type Signed 

type Signed interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64
}

Signed 有符号整数

type Slice 

type Slice[T Ordered] []T

Slice 数字或字符串类型slice 

实现了排序接口, 可用sort.Sort(Slice) 排序

func (Slice[T]) Len 

func (s Slice[T]) Len() int

Len 返回 Slice 的元素数量。

func (Slice[T]) Less 

func (s Slice[T]) Less(i, j int) bool

Less 判断索引 i 的元素是否小于索引 j 的元素。

func (Slice[T]) Swap 

func (s Slice[T]) Swap(i, j int)

Swap 交换索引 i 和 j 的元素。

type TrustedProxies added in v1.22.15 

type TrustedProxies struct {
	// contains filtered or unexported fields
}

TrustedProxies 保存可信代理 IP/CIDR 列表。 生产环境建议按网关、负载均衡或 Ingress 的固定地址显式配置，避免过宽地信任所有私网来源。

func NewTrustedProxies added in v1.22.15 

func NewTrustedProxies(values ...string) (*TrustedProxies, error)

NewTrustedProxies 构造可信代理白名单。 支持传入单个 IP 或 CIDR，例如 `10.0.0.10`、`10.0.0.0/8`、`fd00::/8`。

参数说明：

  • values：可信代理 IP 或 CIDR 列表

返回值：可信代理配置、错误信息

func (*TrustedProxies) Contains added in v1.22.15 

func (p *TrustedProxies) Contains(ip net.IP) bool

Contains 判断指定 IP 是否命中可信代理白名单。

参数说明：

  • ip：待判断的 IP 地址

返回值：true 表示命中白名单

type UnPadding 

type UnPadding func([]byte) ([]byte, error)

UnPadding 去除填充数据方法

  • Pkcs7UnPadding
  • ZeroUnPadding

type Unsigned 

type Unsigned interface {
	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr
}

Unsigned 无符号整数

type ValidationError added in v1.22.17 

type ValidationError struct {
	Reason ValidationReason // 校验失败原因
	Min    uint8            // 最小长度约束
	Max    uint8            // 最大长度约束
}

ValidationError 表示结构化校验失败结果。 业务侧应通过 errors.As 提取后，根据 Target/Reason 自行决定提示文案。

func (*ValidationError) DefaultMessage added in v1.22.17 

func (e *ValidationError) DefaultMessage() string

DefaultMessage 返回默认中文提示文案。 该方法适合作为兜底展示文案，也便于业务侧显式区分 Error() 与默认文案语义。

func (*ValidationError) Error added in v1.22.17 

func (e *ValidationError) Error() string

Error 返回默认中文提示文案。 当业务侧未自定义提示时，该文案可以直接返回给终端用户； 如业务侧已有国际化或错误码体系，仍建议优先使用 Target/Reason 自行映射。

func (*ValidationError) MessageKey added in v1.22.17 

func (e *ValidationError) MessageKey() string

MessageKey 返回稳定的文案键。 业务侧可基于该键做国际化映射、错误码映射或统一前端提示管理。

type ValidationReason added in v1.22.17 

type ValidationReason string

ValidationReason 表示校验失败原因。 业务侧可根据该字段决定最终提示文案、错误码或国际化文案键。 

const (
	// ValidationReasonLengthOutOfRange 表示长度不在允许范围内。
	ValidationReasonLengthOutOfRange ValidationReason = "length_out_of_range"
	// ValidationReasonInvalidFormat 表示整体格式不符合要求。
	ValidationReasonInvalidFormat ValidationReason = "invalid_format"
	// ValidationReasonInvalidCharset 表示字符集不符合要求。
	ValidationReasonInvalidCharset ValidationReason = "invalid_charset"
	// ValidationReasonConsecutiveUnderscore 表示存在连续下划线。
	ValidationReasonConsecutiveUnderscore ValidationReason = "consecutive_underscore"
	// ValidationReasonMissingLowercase 表示缺少小写字母。
	ValidationReasonMissingLowercase ValidationReason = "missing_lowercase"
	// ValidationReasonMissingUppercase 表示缺少大写字母。
	ValidationReasonMissingUppercase ValidationReason = "missing_uppercase"
	// ValidationReasonMissingDigit 表示缺少数字。
	ValidationReasonMissingDigit ValidationReason = "missing_digit"
)

type WriteFile 

type WriteFile struct {
	Lock sync.RWMutex
	File *os.File
}

WriteFile 文件读写操作

func NewWrite 

func NewWrite(fileName string, opts ...WriteOption) (*WriteFile, error)

NewWrite 返回一个WriteFile实例 

fileName 文件路径: 不存在则创建
perm 文件权限: 默认权限 文件夹0744, 文件0644

func (*WriteFile) Close 

func (f *WriteFile) Close() error

Close 关闭文件

func (*WriteFile) Write 

func (f *WriteFile) Write(data []byte) (int, error)

Write 写入数据

func (*WriteFile) WriteBuf 

func (f *WriteFile) WriteBuf(handler func(write *bufio.Writer) (int, error)) (int, error)

WriteBuf 使用 bufio.Writer 写入数据

func (*WriteFile) WriteString 

func (f *WriteFile) WriteString(data string) (int, error)

WriteString 写入数据

type WriteOption added in v1.22.13 

type WriteOption func(*writeOptions)

WriteOption 写入文件配置项

func WithWriteAppend added in v1.22.13 

func WithWriteAppend(isAppend bool) WriteOption

WithWriteAppend 设置是否追加写入

func WithWritePerm added in v1.22.13 

func WithWritePerm(perm os.FileMode) WriteOption

WithWritePerm 设置文件权限

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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