通用 Go 工具包集合 —— 一组实用、模块化的基础库，用于加速后端服务和工具类开发。模块以 github.com/helays/utils/v2 作为 module 前缀导入，包含文件/IO 工具、模板助手、HTTP 层辅助、文件存储驱动、数据库辅助、规则验证引擎、锁定策略、安全工具与日志封装等。
- 安装（模块导入）：
go get github.com/helays/utils/v2- 典型导入示例：
import (
"github.com/helays/utils/v2/tools"
"github.com/helays/utils/v2/template/template_engine"
"github.com/helays/utils/v2/rule-engine/validator"
)- 常见使用示例：
// 文件读写
err := tools.FilePutContents("/tmp/hello.txt", "hello world")
b, _ := tools.FileGetContents("/tmp/hello.txt")
// 模板函数注册
t := template.New("page").Funcs(template_engine.BuiltinFuncMap())
// 规则验证示例
rule := &validator.Rule{
Field: "age",
FieldDataType: "int",
Category: types.CategoryContent,
Operator: types.GreaterEqual,
Value: []any{18},
}
msg, ok := rule.Validate(map[string]any{"age": 20})下面按模块列出主要职责、关键文件与典型用法，便于快速定位与引用。
-
tools — 通用辅助工具
-
包路径：
github.com/helays/utils/v2/tools -
功能：字符串与命名转换、文件读写、IO 辅助、map/切片工具、环形缓冲索引、深拷贝等。
-
关键文件：
tools/file.go、tools/io.go、tools/map.go、tools/func.go、tools/ringbuffer/...。 -
典型用法：
tools.FileGetContents(path)、tools.FilePutContents(path, content)、tools.FileAppendContents(path, content)
-
-
net/http — HTTP 层工具与中间件
-
包路径：
github.com/helays/utils/v2/net/http（及其子包） -
功能：统一响应（response）、路由处理、http server 支持、session、mime、route 中间件（日志/metrics）等。
-
关键文件：
net/http/response/*、net/http/httpServer/router/*、net/http/route/middleware/*。 -
典型用法：在 handler 中使用统一响应
response.SetReturnData(w, code, data)。
-
-
template/template_engine — 模板内置函数
-
包路径：
github.com/helays/utils/v2/template/template_engine -
功能：为
html/template提供内置函数（时间、格式化、链接生成、dict、循环等）。 -
关键文件：
enginetools.go、utils.go。 -
典型用法：
t := template.New("tpl").Funcs(template_engine.BuiltinFuncMap())
-
-
file/filesaver & db/fileSaver — 文件存储抽象与驱动
-
包路径：
- 抽象：
github.com/helays/utils/v2/file/filesaver - 本地驱动：
github.com/helays/utils/v2/file/filesaver/localfile - MinIO 驱动：
github.com/helays/utils/v2/db/fileSaver/minio
- 抽象：
-
功能：统一文件写入/读取/列举/删除接口，支持本地、FTP、SFTP、HDFS、MinIO 等后端。
-
关键方法（MinIO）：
Write,Read,ListFiles,Delete。
-
-
db — 数据库辅助与查询构造器
-
包路径：
github.com/helays/utils/v2/db，查询构造器在db/query -
功能：DSN 构建（MySQL/Postgres/SQLite）、查询构造器到 GORM clause 的转换、字段解析工具。
-
关键文件：
db/dsn.go、db/query/gorm.go、db/query/helper.go。
-
-
db/localredis — 本地 Redis 适配（测试替代）
-
包路径：
github.com/helays/utils/v2/db/localredis -
说明：提供本地实现以便在无 Redis 环境或测试中替代真实 redis 客户端。注意：部分方法为占位实现，生产使用前请确认完整性。
-
-
rule-engine/validator — 规则验证引擎
-
包路径：
github.com/helays/utils/v2/rule-engine/validator -
功能：支持数据类型、长度、格式、内容与高级表达式验证；支持 AND/OR 逻辑组合、通配符字段、CEL/Go/JSONLogic 等表达式类型；内置中文错误提示。
-
文档：
rule-engine/validator/readme.md（含操作符表与示例）。
-
-
security — 安全相关工具
-
子模块：
- lockpolicy（锁定策略管理，session/ip/user，多层锁定与升级链）
- cors（CORS 策略与预检处理）
-
包路径：
github.com/helays/utils/v2/security/...
-
-
logger — 日志实现
-
包路径：
github.com/helays/utils/v2/logger（含ulogs、zaploger） -
功能：日志记录、文件滚动（结合 lumberjack）、HTTP 请求日志中间件等。
-
-
crypto — 加密工具
-
包路径：
github.com/helays/utils/v2/crypto/aes -
功能：AES CBC 简单加解密（包含 padding/unpadding，适用于简单场景）。
-
-
config — 配置与正则常量
-
包路径：
github.com/helays/utils/v2/config -
功能：常用正则（手机号、邮箱、页面解析）、YAML 加载器（支持 include 机制）。
-
关键文件：
config/regexp.go、config/loadYaml/load.go。
-
-
其它项目级文件
-
var.go：全局常量（Salt、Version、BuildTime） -
init.go：运行目录初始化（设置config.Appath） -
message/：消息模块（当前 README 仅有标题，建议补充实现/使用说明）
-
-
许可证与依赖
-
仓库采用 MIT 许可证（见仓库根 LICENSE）。
-
在打包/发布时，请保留第三方依赖的 LICENSE/NOTICE 文件（特别是 Apache-2.0 的 NOTICE）。
-
-
性能与并发
-
规则引擎：通配符匹配（如
items.*.price）在数据量大或规则复杂时会带来性能开销，建议缓存规则解析或避免在热路径频繁使用。 -
文件写入：并发写入到网络文件系统（NFS、MinIO、HDFS 等）时请考虑临时文件 + 重命名方案以保证原子性与一致性。
-
-
安全与加密
- 仓内提供的加密辅助（如 AES）为通用工具示例。选择真实生产加密方案时，请注意 IV、认证加密（AEAD）与密钥管理等安全需求。
-
Go 版本
- 项目声明
go 1.24.0（见 go.mod），请在升级 Go 版本或依赖版本时做兼容性测试。
- 项目声明
欢迎贡献，简要流程：
-
提交 Issue
- 先创建 issue 讨论需求或 bug，并给出复现步骤与期望行为。
-
Fork 并创建分支
- Fork 仓库，基于
master创建 feature 分支（例如feature/xxx或fix/xxx）。
- Fork 仓库，基于
-
编码与测试
- 编写实现并添加测试，保持模块边界清晰。运行
go test并确保通过。
- 编写实现并添加测试，保持模块边界清晰。运行
-
提交 PR
- 提交 PR，描述变更内容、影响范围、测试步骤与兼容性说明。维护者会审阅并给出反馈。
-
代码规范
- 请使用
gofmt、go vet，保持清晰的注释与示例代码。新增的公共 API 请在对应子模块 README 中补充用法示例。
- 请使用
© helays, 2024~time.Now
本项目采用 MIT 许可证，详见 MIT License。