# go-tools **Repository Path**: hexug/go-tools ## Basic Information - **Project Name**: go-tools - **Description**: go-tools 是一套为 Go 开发者打造的通用工具函数集合，涵盖日志封装、IOC 服务注册、Kubernetes 操作辅助、HTTP 中间件、配置解析、字符串处理等功能。 - **Primary Language**: Go - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: https://pkg.go.dev/gitee.com/hexug/go-tools - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-08-27 - **Last Updated**: 2026-06-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: Go语言, 工具 ## README # go-tools > 一套面向 Go 后端工程的轻量化通用工具库集合：日志、配置、加密、限流、Kubernetes、消息推送、异常等开箱即用的独立小模块。 [![License](https://img.shields.io/badge/License-Apache_2.0-green?logo=apache)](LICENSE) [![Go Version](https://img.shields.io/badge/Go-1.25%2B-blue?logo=go)](https://go.dev/) [![Go Report Card](https://goreportcard.com/badge/gitee.com/hexug/go-tools)](https://goreportcard.com/report/gitee.com/hexug/go-tools) [![Gitee tag (latest SemVer)](https://img.shields.io/badge/dynamic/json?&logo=gitee&logoColor=ee1c25&url=https://gitee.com/api/v5/repos/hexug/go-tools/tags?per_page=1%26direction=desc%26sort=updated&label=Version&query=$[0].name&color=brightgreen)](https://gitee.com/hexug/go-tools/tags) --- ## 项目背景 `go-tools` 整合了在多个内部 Go 服务中沉淀下来的通用工具与基础设施粘合层，目标是： - **按需引入**：每个能力独立成包，import 一个用一个，不连带拉取无关功能； - **直观可控**：对外 API 优先选择短小、贴近标准库习惯的形态，避免重抽象、重封装； - **生产就绪**：每个模块均自带 `*_test.go` 测试用例，行为以源码与测试为准。 库**模块路径**：`gitee.com/hexug/go-tools/v2`（v2 起遵循 Go module SemVer Import Compatibility，路径含 `/v2` 后缀） --- ## v2 升级提示 本仓库自 **v2.0.0** 起对 `ioc` / `logger` 做了一次破坏性升级，主要变化： - **模块路径**：`gitee.com/hexug/go-tools` → `gitee.com/hexug/go-tools/v2`（遵循 Go module v2+ 规范）。下游升级需把 `go.mod` 的 `require` 行改为 `gitee.com/hexug/go-tools/v2 vX.Y.Z`，所有 import 路径加 `/v2` 后缀（如 `gitee.com/hexug/go-tools/v2/ioc`）。 - **`ioc`**：`IocContainter` → `IocContainer`；`AppManager.Init` / `ConfManager.Init` 全部改为 `Init(ctx context.Context) error`；新增 `Bootstrap` 一行启动、`Lifecycle.Start` 阶段、依赖拓扑排序、`Inspector` 快照、泛型 `MustGetConf[T]` 等；web 框架适配（gin / fiber / restful / grpc）剥离到 [`ioc/adapter/*`](./ioc/adapter/) 子包，主包零 web 框架依赖。详见 [ioc/README.md](./ioc/README.md) 的「v2 关键变化」与「Worker 类模块教学」。 - **`logger`**：移除全部包级全局变量，改为惰性默认 + `SetDefault` 装配；`L()` 永不为 nil 兜底；保留 `Default()` 等少量旧 API 作为 `// Deprecated:` 别名以便平滑迁移。详见 [logger/README.md](./logger/README.md)。 - **`cli/cobrazh`**：v2 新增的 cobra 中文化辅助层，把"中文 UsageTemplate / HelpTemplate / VersionTemplate + completion 子命令 + bash V2 兼容补丁 + flag 补全 helper"这一组样板抽到独立包，业务一行调用即可。详见 [cli/cobrazh/README.md](./cli/cobrazh/README.md)。 > v2 改造的完整设计与迁移路径见各模块 README；v1 与 v2 不做源码兼容（仅在必要的 `// Deprecated:` 别名层做平滑过渡）。 --- ## 安装 ```bash go get gitee.com/hexug/go-tools/v2 ``` Go 版本：`go.mod` 声明 `go 1.25.0`，请使用 Go 1.25 及以上版本。 > 推荐设置 `GOPROXY=https://goproxy.cn,direct` 加速依赖拉取。 --- ## 模块目录 | 模块 | 背景 | 用途 | 解决的问题 | |---|---|---|---| | [cli](./cli/cobrazh/README.md) | cobra CLI 工具中文化辅助层 | `cobrazh.ApplyZh` 一键装中文 UsageTemplate；`NewCompletionCmd` 内置 bash V2 sh-mode 守卫与中间空 token 补丁；`Enum / DirOnly / NoFile / FlagList` 等 flag 补全 helper | 收敛每个 cobra 项目里 ~80 行的中文化与补全样板代码 | | [common](./common/README.md) | 跨模块共用的小工具集合 | `map[string]any` 操作、基础类型指针化、字段校验、FNV 哈希 ID | 消除项目里反复出现的“小工具拷贝粘贴” | | [crypto](./crypto/README.md) | 业务侧常用密码学能力 | AES-GCM/CBC、RSA-OAEP、ECIES、PBKDF2/HKDF、bcrypt/Argon2、HMAC/RSA-PSS/ECDSA/Ed25519、安全随机数 | 提供基于标准库的密码学能力封装与统一管理器 | | [exception](./exception/README.md) | 跨服务统一的异常模型 | `ApiException` + 标准业务错误工厂 + HTTP/gRPC/CLI 序列化适配 | 消除每个服务自定义错误结构、错误码风格不一致 | | [format](./format/README.md) | 调试与排版小工具 | JSON/YAML/TOML/INI/XML/HTML 美化输出、字节大小格式化、字符串数组索引 | 减少日志/排查场景对一次性格式化函数的重复实现 | | [grpc](./grpc/README.md) | gRPC 服务端通用拦截器 | 类似 Gin debug 风格的访问日志拦截器 + Prometheus 指标拦截器（Unary / Stream / 流式消息粒度） | 统一 gRPC 服务的访问日志与可观测性 | | [http](./http/README.md) | 三套 HTTP 框架的通用中间件 | Gin / Fiber / go-restful 的访问日志中间件、Gin 拦截放通、Gin JWT 鉴权、跨框架 Prometheus 指标采集 | 不同框架接入相同风格的访问日志、基础鉴权与可观测性 | | [ioc](./ioc/README.md) | 进程级配置 + 组件容器（**v2**） | App / Conf 两类核心对象注册与生命周期；`Init(ctx) error` + `Lifecycle.Start` + `Closer.Close` 三阶段；TOML/YAML/Env 三源加载；依赖 `DependsOn` 拓扑排序；`Bootstrap.Run` 一行启动；`Inspector` 快照与 DOT 依赖图；泛型 `MustGetConf[T]`；web 框架适配在 [`ioc/adapter/{gin,fiber,restful,grpc}`](./ioc/adapter/) 子包按需引入；指标暴露端通过 [`ioc/metrics`](./ioc/metrics/README.md) 双模式（http / standalone）配置驱动 | 统一应用启动顺序、配置来源、资源回收、协议层挂载与指标暴露，主包零 web 依赖 | | [k8s](./k8s/README.md) | Kubernetes 客户端封装 | Pod / Deployment / Service / ConfigMap CRUD、工作负载资源指标、Leader Election | 屏蔽 client-go 直接调用的样板代码 | | [logger](./logger/README.md) | Zap 的薄封装 + 上下文追踪（**v2**） | 惰性默认 logger（零配置即可 `logger.L()`）、`SetDefault` 装配、私有实例、文件切割、JSON/Console 双模式、`Ctx(ctx)` 注入 trace 字段 | 统一项目日志格式与请求级追踪信息，启动早期也能安全打日志 | | [metrics](./metrics/README.md) | Prometheus 指标中心 | 进程级共享 Registry、`promhttp` Handler、`go_app_build_info` Gauge、HTTP / gRPC 默认 Collectors 工厂；与各框架 `middleware/metrics` 共用同一套 `Options` | 统一指标命名、暴露端与桶配置，避免业务在多个框架内重复造采集 / 暴露逻辑 | | [mfa](./mfa/README.md) | 多因子认证 | TOTP / SMS / Email / WebAuthn 流程编排、Memory/Redis/MySQL 存储、记住设备、状态/验证码 TTL | 在已有账号体系上挂载 MFA 而无需自己造流程 | | [msgbot](./msgbot/README.md) | 群机器人推送 | 飞书 / 钉钉 / 企业微信 webhook 文本、Markdown、卡片、图片、文件等消息发送 | 统一封装常用 IM 群机器人 webhook 协议 | | [ping](./ping/README.md) | ICMP 探活 | 通过 ICMP（IPv4/IPv6）连续 ping 主机并返回 RTT 统计 | 在不依赖系统 ping 工具的前提下做主机探活 | | [rate](./rate/README.md) | 单机限流器 | 令牌桶 / 漏桶 / 固定窗口 / 滑动窗口 + 全局/路由限速管理器 + Gin / go-restful 中间件 | 在网关或单机服务上做流量控制 | | [resolver](./resolver/README.md) | DNS 解析 | A / AAAA / NS / CNAME / MX / TXT 记录查询，支持自定义 DNS、ECS、source IP、批量打印 | 取代 shell 调 `dig` 进行可编程的 DNS 排查 | | [scan](./scan/README.md) | TCP 端口扫描 | 单 IP:Port 的 TCP 探活与耗时统计 | 配合 resolver 做基础的连通性检测 | | [tool_files](./tool_files/README.md) | 工程模板片段 | 通用 Dockerfile、Makefile（普通/含 gRPC 生成） | 新项目直接复用既定的构建脚本 | --- ## 测试 ```bash go test ./... ``` 各模块测试文件命名为 `*_test.go`，测试用例本身即为最贴近源码的使用示例。 --- ## 协作规约 本仓库的注释、README 与文档维护由项目级规约 [AI_DOC_SPEC.md](./AI_DOC_SPEC.md) 统一约束。 任何 AI 工具 / 协作者在本仓库内修订文档时，**请先阅读该规约**。 --- ## 开源协议 本项目使用 [Apache License 2.0](./LICENSE)。