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 ¶
- Variables
- func CompressDirTarGz(filePath, tarDirPath string) error
- func CompressFileTarGz(dirPath, targetFile string) error
- func ContentReplace(path string, oldStr, newStr string) error
- func Decompose(sourceFile, targetPath string) error
- func DelFileOrDir(dir string) error
- func DelFileOrDirWithParent(path string) error
- func DeleteDirContent(dir string) error
- func DirSize(dirPath string) (int64, error)
- func DirSizeMb(path string) (int64, error)
- func ExternalIP() (string, error)
- func ExtractArchiveAuto(archiveFile, destDir string) error
- func FileMainName(path string) string
- func FileMd5(filePath string) string
- func GetEnv() string
- func GetFileExtensionByType(fileType FileType) string
- func InitializeTimePRC()
- func IsCompressedFile(filePath string) bool
- func IsDevEnv() bool
- func IsIDCAddress() (bool, error)
- func NowInTimeRange(rang string) bool
- func NowTime() time.Time
- func RegisterTasks(tasks []JobTask) error
- func RemoveTask(names ...string)
- func ServerAgentStatus(sType int, version string, api string) error
- func SimpleUID() string
- func StartTask(names ...string)
- func StopTask(names ...string)
- func StopTasks(ctx context.Context) error
- func StrPrefixRemove(str, prefix string) string
- func StrSuffixRemove(str, suffix string) string
- func TrackTime(n time.Time, name string)
- func UUID() string
- func WriteFileAtomic(path string, perm fs.FileMode, write func(w io.Writer) error) (err error)
- func XID() string
- type FileType
- type JobTask
Constants ¶
This section is empty.
Variables ¶
var ( // DecompressMaxFileSize 单个条目解压后的字节数上限,默认 2 GiB DecompressMaxFileSize int64 = 2 << 30 // DecompressMaxTotalSize 单次解压写出的总字节数上限,默认 8 GiB DecompressMaxTotalSize int64 = 8 << 30 )
解压体积上限,用于拦截压缩炸弹(解压后体积远大于归档本身的输入)。 需要处理超大归档时在应用启动阶段调整,置 0 表示关闭该项限制; 运行期不要并发修改。
var ErrDecompressTooLarge = errors.New("解压内容超过体积上限")
ErrDecompressTooLarge 解压内容超过 DecompressMaxFileSize 或 DecompressMaxTotalSize
Functions ¶
func CompressDirTarGz ¶ added in v0.1.19
CompressionTarGz 将指定文件压缩成 tar.gz 格式 filePath: 要压缩的文件路径 tarDirPath: 压缩后的目标文件路径
func CompressFileTarGz ¶ added in v0.1.19
CompressDirectory 压缩整个目录到tar.gz文件
func ContentReplace ¶ added in v0.1.18
文件内容替换
func DelFileOrDir ¶ added in v0.1.24
DelFileOrDir 删除指定文件或目录,遍历目录时跳过隐藏文件(以 . 开头) 如果路径不存在,返回 nil(视为删除成功) 删除目录时,目录内的隐藏文件(如 NFS 的 .nfsXXXX 文件)会被保留; 若目录因保留了隐藏文件而非空,则该目录本身也会被保留 如果路径存在但无法删除,返回错误
func DelFileOrDirWithParent ¶ added in v0.1.34
DelFileOrDirWithParent 删除指定文件或目录,如果父目录变空则同时删除父目录 这个函数会先删除指定的文件或目录,然后检查其父目录是否为空 如果父目录为空,则也会删除父目录
func DeleteDirContent ¶ added in v0.1.18
DeleteDirContent 删除目录中的所有内容,但保留目录本身 如果目录不存在,返回错误
func ExtractArchiveAuto ¶ added in v0.1.26
ExtractArchiveAuto 自动检测文件类型并解压 支持 .tar, .tar.gz, .tgz 格式
func GetFileExtensionByType ¶ added in v0.1.26
GetFileExtensionByType 根据文件类型返回对应的扩展名
func InitializeTimePRC ¶ added in v0.2.62
func InitializeTimePRC()
func IsCompressedFile ¶ added in v0.1.26
IsCompressedFile 检查文件是否为压缩文件
func NowInTimeRange ¶ added in v0.2.62
是否时间范围内,rang 07:00-09:00 true是,false不是
func RegisterTasks ¶ added in v0.2.57
RegisterTasks 注册一组定时任务并统计结果。 任务处理函数会被自动包装:panic 会被恢复并记录堆栈,在途任务数交给 StopTasks 等待。
逐个注册,某个失败不影响其余任务;全部成功返回 nil,否则返回各失败任务的错误(带任务名) 用 errors.Join 合并的结果,调用方据此决定是否让启动失败(v0.3.19 起返回 error)。
func ServerAgentStatus ¶ added in v0.2.51
客户端是否存活及新的检查
func StopTask ¶ added in v0.2.71
func StopTask(names ...string)
StopTask 暂停指定名称的任务,任务保留在调度器中,可用 StartTask 恢复。
func StopTasks ¶ added in v0.2.71
StopTasks 停止调度并等待在途任务结束,供 Fx 生命周期 OnStop 直接调用。 ctx 到期仍有任务未结束时返回错误,不再等待。停机状态是一次性的, 调用后 RegisterTasks 注册的任务不会再被触发。
与 gcron.StopGracefully 的区别:后者无超时,在途任务不结束就一直阻塞; 本函数用 ctx 约束等待上限,超时后让进程继续退出。
func WriteFileAtomic ¶ added in v0.3.32
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:掉电后目标是旧文件或新文件,不会是半个。
- 进程在改名前被杀会留下临时文件,本函数不清理历史残留。
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
GetFileCompressType 获取文件的压缩类型 通过检查文件头部的魔数(特征字节)来确定文件类型。
只有能成功解析出 TAR 头时才判为 tar.gz 等复合格式,普通 gzip 文本不会被误判; 空归档与内容为空的 gzip 在这一层无法区分,统一返回 TypeGzip。 空文件和长度不足以判定的短文件返回 TypeUnknown 且 error 为 nil, 只有真正的读取失败才返回 error。