xxutil

package
v0.3.34 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MulanPSL-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package xxutil 提供定时任务、文件压缩、时间、字符串、ID 和环境辅助能力。

定时任务

RegisterTasks 根据 JobTask 注册定时任务,任务名应全局唯一;有任务注册失败时返回合并后的 error (其余任务照常注册),调用方据此决定是否让启动失败; StopTask、StartTask、RemoveTask 控制指定任务,StopTasks 停止调度并等待在途任务。 StopTasks 的 context 限定等待时间,不会强制终止正在执行的 Handler; 它停止全局 gcron 调度器,应作为应用停机操作使用。

异步执行

SafeGo、SafeGoWithArg、SetDefaultPanicHandler、PanicHandler 与 AsyncTask、AsyncExecute、 AsyncExecuteFunc、AsyncRun 自 v0.3.19 起移至 xxpool,本包不再提供;签名与行为不变,升级时改用 xxpool。

压缩与解压

CompressFileTarGz、CompressDirTarGz 打包为 tar.gz。 GetFileCompressType 按魔数识别格式:只有能成功解析出 TAR 头时才判为复合格式, 普通 gzip 文本不会被误判成 tar.gz;空归档与内容为空的 gzip 在这一层无法区分,统一按 gzip 处理。

Decompose 按格式自动解压,ExtractArchiveAuto 处理 tar、tar.gz、tgz。 三个解压入口共用同一套边界判据:

  • 条目路径规范化后必须落在目标目录内,".." 逃逸会中止解压并返回错误;
  • 允许代表目标目录本身的目录条目,即 tar -C src -cf a.tar . 产生的 "./";
  • 建目录与写文件都经 os.Root 约束在目标目录内:路径中任意一层是指向目录外的 符号链接都会被拒绝,仅校验路径字符串挡不住这种情况。 指向目标目录内部的符号链接不受影响,仍会被正常跟随;
  • 目标位置已存在符号链接时拒绝写入;
  • 归档内的符号链接、硬链接等非普通文件条目一律跳过并计数,不创建链接;
  • 单个条目与单次解压的总字节数受 DecompressMaxFileSize、DecompressMaxTotalSize 限制, 超限时中止并返回 ErrDecompressTooLarge。两者可在启动阶段调整,置 0 表示不限制。

读取归档过程中出错会立即返回,不再跳过继续读:标准库 tar.Reader 的错误是粘滞的, 继续调用 Next 只会拿到同一个错误并陷入死循环。 解压失败时目标目录可能残留已写出的部分文件,调用方需要干净结果时应先解到临时目录再整体移动。 解压路径的边界依赖 os.Root,要求 Go 1.25 及以上工具链。

其他工具

文件工具覆盖摘要、大小、替换和删除; WriteFileAtomic 在目标同目录写临时文件,Sync 后改名覆盖目标,读的一方看不到写了一半的文件, 失败时目标保持原样;它会换掉目标文件本身(属主、SELinux 标签、硬链接不保留), 不建父目录,要保留这些属性的系统配置文件仍应原地写。 时间、ID、IP 和环境函数按需直接调用,无需统一初始化。 删除与解压会写入文件系统,调用方应确认目标路径和输入来源。

Index

Constants

This section is empty.

Variables

View Source
var (
	// DecompressMaxFileSize 单个条目解压后的字节数上限,默认 2 GiB
	DecompressMaxFileSize int64 = 2 << 30
	// DecompressMaxTotalSize 单次解压写出的总字节数上限,默认 8 GiB
	DecompressMaxTotalSize int64 = 8 << 30
)

解压体积上限,用于拦截压缩炸弹(解压后体积远大于归档本身的输入)。 需要处理超大归档时在应用启动阶段调整,置 0 表示关闭该项限制; 运行期不要并发修改。

View Source
var ErrDecompressTooLarge = errors.New("解压内容超过体积上限")

ErrDecompressTooLarge 解压内容超过 DecompressMaxFileSize 或 DecompressMaxTotalSize

Functions

func CompressDirTarGz added in v0.1.19

func CompressDirTarGz(filePath, tarDirPath string) error

CompressionTarGz 将指定文件压缩成 tar.gz 格式 filePath: 要压缩的文件路径 tarDirPath: 压缩后的目标文件路径

func CompressFileTarGz added in v0.1.19

func CompressFileTarGz(dirPath, targetFile string) error

CompressDirectory 压缩整个目录到tar.gz文件

func ContentReplace added in v0.1.18

func ContentReplace(path string, oldStr, newStr string) error

文件内容替换

func Decompose added in v0.1.19

func Decompose(sourceFile, targetPath string) error

Decompose 解压缩文件到指定目录 sourceFile: 要解压的文件路径 targetPath: 解压的目标目录

func DelFileOrDir added in v0.1.24

func DelFileOrDir(dir string) error

DelFileOrDir 删除指定文件或目录,遍历目录时跳过隐藏文件(以 . 开头) 如果路径不存在,返回 nil(视为删除成功) 删除目录时,目录内的隐藏文件(如 NFS 的 .nfsXXXX 文件)会被保留; 若目录因保留了隐藏文件而非空,则该目录本身也会被保留 如果路径存在但无法删除,返回错误

func DelFileOrDirWithParent added in v0.1.34

func DelFileOrDirWithParent(path string) error

DelFileOrDirWithParent 删除指定文件或目录,如果父目录变空则同时删除父目录 这个函数会先删除指定的文件或目录,然后检查其父目录是否为空 如果父目录为空,则也会删除父目录

func DeleteDirContent added in v0.1.18

func DeleteDirContent(dir string) error

DeleteDirContent 删除目录中的所有内容,但保留目录本身 如果目录不存在,返回错误

func DirSize added in v0.1.18

func DirSize(dirPath string) (int64, error)

获取目录的大小

func DirSizeMb added in v0.1.18

func DirSizeMb(path string) (int64, error)

获取目录的大小Mb

func ExternalIP

func ExternalIP() (string, error)

获取内网IP地址

func ExtractArchiveAuto added in v0.1.26

func ExtractArchiveAuto(archiveFile, destDir string) error

ExtractArchiveAuto 自动检测文件类型并解压 支持 .tar, .tar.gz, .tgz 格式

func FileMainName

func FileMainName(path string) string

只获取文件名,不含后辍

func FileMd5

func FileMd5(filePath string) string

获取文件的Md5

func GetEnv added in v0.1.40

func GetEnv() string

获取运行环境配置文件内容

func GetFileExtensionByType added in v0.1.26

func GetFileExtensionByType(fileType FileType) string

GetFileExtensionByType 根据文件类型返回对应的扩展名

func InitializeTimePRC added in v0.2.62

func InitializeTimePRC()

func IsCompressedFile added in v0.1.26

func IsCompressedFile(filePath string) bool

IsCompressedFile 检查文件是否为压缩文件

func IsDevEnv added in v0.1.5

func IsDevEnv() bool

获取运行环境配置文件是否为dev

func IsIDCAddress

func IsIDCAddress() (bool, error)

是否是IDC的地址

func NowInTimeRange added in v0.2.62

func NowInTimeRange(rang string) bool

是否时间范围内,rang 07:00-09:00 true是,false不是

func NowTime added in v0.1.39

func NowTime() time.Time

北京当前时间

func RegisterTasks added in v0.2.57

func RegisterTasks(tasks []JobTask) error

RegisterTasks 注册一组定时任务并统计结果。 任务处理函数会被自动包装:panic 会被恢复并记录堆栈,在途任务数交给 StopTasks 等待。

逐个注册,某个失败不影响其余任务;全部成功返回 nil,否则返回各失败任务的错误(带任务名) 用 errors.Join 合并的结果,调用方据此决定是否让启动失败(v0.3.19 起返回 error)。

func RemoveTask added in v0.2.71

func RemoveTask(names ...string)

RemoveTask 从调度器中移除指定名称的任务。

func ServerAgentStatus added in v0.2.51

func ServerAgentStatus(sType int, version string, api string) error

客户端是否存活及新的检查

func SimpleUID added in v0.1.38

func SimpleUID() string

UID

func StartTask added in v0.2.71

func StartTask(names ...string)

StartTask 恢复被 StopTask 暂停的任务。

func StopTask added in v0.2.71

func StopTask(names ...string)

StopTask 暂停指定名称的任务,任务保留在调度器中,可用 StartTask 恢复。

func StopTasks added in v0.2.71

func StopTasks(ctx context.Context) error

StopTasks 停止调度并等待在途任务结束,供 Fx 生命周期 OnStop 直接调用。 ctx 到期仍有任务未结束时返回错误,不再等待。停机状态是一次性的, 调用后 RegisterTasks 注册的任务不会再被触发。

与 gcron.StopGracefully 的区别:后者无超时,在途任务不结束就一直阻塞; 本函数用 ctx 约束等待上限,超时后让进程继续退出。

func StrPrefixRemove added in v0.1.26

func StrPrefixRemove(str, prefix string) string

移除字符串指定的头

func StrSuffixRemove added in v0.1.26

func StrSuffixRemove(str, suffix string) string

移除字符串指定的尾

func TrackTime added in v0.1.8

func TrackTime(n time.Time, name string)

添加时间跟踪函数

func UUID

func UUID() string

uuid 32位

func WriteFileAtomic added in v0.3.32

func WriteFileAtomic(path string, perm fs.FileMode, write func(w io.Writer) error) (err error)

WriteFileAtomic 先在 path 同目录写临时文件,再改名覆盖 path,读的一方看不到写了一半的文件。

流程:os.CreateTemp 建 ".<文件名>.*.tmp" → 调 write → Chmod(perm) → Sync → Close → Rename。 任一步失败(含 write 返回 error 或 panic)都删除临时文件、目标保持原样;panic 清理后继续向上抛。

  • perm 按原值设置,不受 umask 影响;perm 的权限位为 0 或 write 为 nil 时直接返回 error。
  • 不建父目录,父目录不存在返回 error。
  • 改名会换掉目标文件本身:原有属主、扩展属性(如 SELinux 标签)、硬链接都不保留; 目标是符号链接时替换链接本身,目标是目录时返回 error。要保留这些属性的系统配置文件不要用它。
  • 只对文件做 Sync,不对目录做 fsync:掉电后目标是旧文件或新文件,不会是半个。
  • 进程在改名前被杀会留下临时文件,本函数不清理历史残留。

func XID

func XID() string

20位可解析日期的ID

Types

type FileType added in v0.1.26

type FileType string

FileType 表示文件的压缩类型

const (
	TypeUnknown  FileType = "unknown" // 未知类型
	TypeGzip     FileType = "gzip"    // Gzip 格式
	TypeTarGz    FileType = "tar.gz"  // Tar+Gzip 格式
	TypeZip      FileType = "zip"     // ZIP 格式
	TypeTar      FileType = "tar"     // Tar 格式
	TypeRar      FileType = "rar"     // RAR 格式
	Type7z       FileType = "7z"      // 7z 格式
	TypeBzip2    FileType = "bzip2"   // BZip2 格式
	TypeTarBzip2 FileType = "tar.bz2" // Tar+BZip2 格式
	TypeXz       FileType = "xz"      // XZ 格式
	TypeTarXz    FileType = "tar.xz"  // Tar+XZ 格式
)

func GetFileCompressType added in v0.1.26

func GetFileCompressType(filePath string) (FileType, error)

GetFileCompressType 获取文件的压缩类型 通过检查文件头部的魔数(特征字节)来确定文件类型。

只有能成功解析出 TAR 头时才判为 tar.gz 等复合格式,普通 gzip 文本不会被误判; 空归档与内容为空的 gzip 在这一层无法区分,统一返回 TypeGzip。 空文件和长度不足以判定的短文件返回 TypeUnknown 且 error 为 nil, 只有真正的读取失败才返回 error。

type JobTask added in v0.2.57

type JobTask struct {
	Cron    string                    // cron表达式
	Name    string                    // 任务名称,同时作为 gcron 条目名,需全局唯一
	Handler func(ctx context.Context) // 任务处理函数
}

JobTask 定义任务配置

Directories

Path Synopsis
Package jsonx 是库内统一的 JSON 编解码入口,基于 sonic,配置向 encoding/json 靠拢。
Package jsonx 是库内统一的 JSON 编解码入口,基于 sonic,配置向 encoding/json 靠拢。

Jump to

Keyboard shortcuts

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