From 40c9f62c9fc5dc4334290982e401149fbf5588da Mon Sep 17 00:00:00 2001 From: 4566704 <4566704@qq.com> Date: Sun, 20 Sep 2026 12:42:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=A1=B6=E5=B1=82=20README=20=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=E2=80=94=E2=80=94=E5=8C=85=E6=B8=85=E5=8D=95=E6=8C=89?= =?UTF-8?q?=E7=B1=BB=E5=BD=92=E7=BB=84=20+=20go-hua=20=E8=BF=81=E7=A7=BB?= =?UTF-8?q?=E5=AF=B9=E7=85=A7=E8=A1=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 28 个迁入包的分类清单(基础工具/网络协议/系统与硬件) - go-hua→zogo 包名替换对照表(含不迁入项: log 弃用/qps 空壳/remote 归 remote-core) - examples 例程约定写入开发约定 --- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++------- go.mod | 19 +++++++------ go.sum | 10 ++++--- 3 files changed, 91 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 70a06ca..e50acae 100644 --- a/README.md +++ b/README.md @@ -5,28 +5,92 @@ zeroone Go 通用库（单仓多包，顶层即包）。被各后端服务以 Go ## 包清单 +### 服务开发 + | 包 | 用途 | 文档 | |---|---|---| -| `httpx` | Gin 统一出入参：OkJson/ErrorJson（CodeMsg 错误码透传）、Handle/HandleResult、Parse（uri→query→header→json 顺序绑定 + binding 校验收口） | [httpx/README.md](httpx/README.md) | +| `httpx` | Gin 统一出入参：OkJson/ErrorJson（CodeMsg 错误码透传）、Handle/HandleResult、Parse（uri→query→header→json 顺序绑定 + binding 校验收口）、ParseXML | [httpx/README.md](httpx/README.md) | | `logger` | logrus 日志初始化（控制台彩色 + 按天轮转文件 + 历史压缩） | [logger/README.md](logger/README.md) | | `wsc` | WebSocket 服务端框架（会话/房间/路由）+ 配套客户端（自动重连），同一 Message 信封 | [wsc/README.md](wsc/README.md) | | `jwtx` | 轻量 HMAC-SHA256 令牌签发与校验 | [jwtx/README.md](jwtx/README.md) | +| `snowid` | 雪花 ID 生成器（进程内单例）+ GORM 模型 ID 钩子模板 | [snowid/README.md](snowid/README.md) | + +### 基础工具（自 go-hua 迁入） + +| 包 | 用途 | 文档 | +|---|---|---| +| `stringx` | 字符串/切片工具：随机串、UUID、通配符匹配、校验规则、中文首字母 | [stringx/README.md](stringx/README.md) | +| `timex` | 时间日期：NT/UTC 时间戳互转、时间字符串转毫秒时间戳、月份天数 | [timex/README.md](timex/README.md) | +| `filex` | 文件目录：运行目录定位、路径存在性、进度下载、Zip 压缩解压（GBK 兼容） | [filex/README.md](filex/README.md) | +| `cryptox` | MD5 摘要：字符串/字节集/文件 | [cryptox/README.md](cryptox/README.md) | +| `netx` | 本机网络信息：IPv4 与 MAC 地址枚举 | [netx/README.md](netx/README.md) | +| `numx` | 数值工具：流量格式化、低位取整、多整数取最值 | [numx/README.md](numx/README.md) | +| `verx` | 版本号：点分版本解析/还原/比较 | [verx/README.md](verx/README.md) | +| `counter` | 线程安全 string→int64 键值计数器（原 go-hua/single 更名） | [counter/README.md](counter/README.md) | +| `queue` | 链式先进先出队列（哨兵头结点风格） | [queue/README.md](queue/README.md) | + +### 网络协议（自 go-hua 迁入） + +| 包 | 用途 | 文档 | +|---|---|---| +| `frame` | 应用层帧协议：8 字节头（版本+命令+长度+流 ID）+ 数据，Conn 读写封装 | [frame/README.md](frame/README.md) | +| `proto` | 长度前缀封包协议编解码（含 CRC32 校验版） | [proto/README.md](proto/README.md) | +| `bytepacket` | 二进制封包/解包（小端序，兼容易语言协议、GBK、易语言日期） | [bytepacket/README.md](bytepacket/README.md) | +| `conn` | net.Conn 装饰器：透明叠加带宽限速（rate）与流量统计（flow） | [conn/README.md](conn/README.md) | +| `listen` | net.Listener 简单封装（Close 解除 Accept 阻塞） | [listen/README.md](listen/README.md) | +| `flow` | 并发安全流量统计（收发字节累计/取走清零） | [flow/README.md](flow/README.md) | +| `rate` | 按秒配额的带宽限速器 | [rate/README.md](rate/README.md) | +| `httpprobe` | 按首部字节探测 HTTP/HTTPS 流量（原 go-hua/http 更名） | [httpprobe/README.md](httpprobe/README.md) | +| `httpc` | HTTP 客户端：GET/POST/PUT/DELETE/代理/Digest 认证（原 go-hua/httpurl 更名） | [httpc/README.md](httpc/README.md) | +| `nettest` | 网络连通性探测：TCP 端口 + 原始 ICMP Ping，统计成功率与延迟 | [nettest/README.md](nettest/README.md) | +| `spmux` | 单端口多路复用：按报文特征分发到 HTTP/HTTPS/TCP 三个 Listener | [spmux/README.md](spmux/README.md) | +| `ipratelimiter` | 按 IP 维度的令牌桶限流器 | [ipratelimiter/README.md](ipratelimiter/README.md) | + +### 系统与硬件（自 go-hua 迁入） + +| 包 | 用途 | 文档 | +|---|---|---| +| `arp` | 系统 ARP 表读取与 IP→MAC 查询（定时刷新缓存） | [arp/README.md](arp/README.md) | +| `dll` | Windows API 封装：互斥体防多开、ShellExecute、窗口操作 | [dll/README.md](dll/README.md) | +| `hardware` | 硬件信息采集（WMI）与硬件变更检测 | [hardware/README.md](hardware/README.md) | +| `monitor` | 系统资源监控：CPU/内存/磁盘/网络/进程/连接/主机，后台采集 | [monitor/README.md](monitor/README.md) | +| `dotnet` | .NET Framework 安装信息（Windows 注册表，原 go-hua/netFramework 更名） | [dotnet/README.md](dotnet/README.md) | +| `ipquery` | IP/域名归属地查询（ip2region xdb 全内存加载） | [ipquery/README.md](ipquery/README.md) | +| `mail` | SMTP 邮件发送（收/抄/密送、HTML 正文） | [mail/README.md](mail/README.md) | +| `certx` | x509 证书解析校验与自签生成（原 go-hua/ssl 更名） | [certx/README.md](certx/README.md) | +| `gormtypes` | GORM/JSON 双向转换类型：八种 Slice/Map 类型（原 go-hua/datatypes 更名） | [gormtypes/README.md](gormtypes/README.md) | +| `cafegame` | 网咖游戏识别与运行记录上报（网吧业务专用） | [cafegame/README.md](cafegame/README.md) | > 历史说明：v0.1.0 曾存在独立包 `wscclient`，v0.2.0 起并入 `wsc`（`wsc.Client`）—— > 客户端与服务端共用信封定义，协议单一来源防两端漂移。 +## go-hua 迁移对照 + +2026-09 自 `github.com/4566704/go-hua` 迁入并整理，消费方替换对照： + +| go-hua 包 | zogo 去处 | 说明 | +|---|---|---| +| `common` | 拆分为 `stringx` / `timex` / `filex` / `cryptox` / `netx` / `numx` / `verx`；`frame.go` 独立为 `frame` | 拆大杂烩，按职责归位 | +| `http` | `httpprobe` | 实为协议探测，与 net/http 混淆故更名 | +| `httpurl` | `httpc` | 实为 HTTP 客户端 | +| `single` | `counter` | 实为键值计数器 | +| `netFramework` | `dotnet` | 实为 .NET Framework 信息查询 | +| `ssl` | `certx` | 实为 x509 证书操作 | +| `datatypes` | `gormtypes` | 避免与 gorm.io/datatypes 混淆 | +| `log` | **不迁入**（已弃用） | 消费方用 `logger`（logrus）；spmux 已改为 `spmux.Logger` 接口 | +| `snowid` / `gormhook` | 已被 `snowid` 覆盖（v0.2.0 吸收），不再迁入 | | +| `httpx` | 已存在，仅并入 `ParseXML` 与全套单元测试 | | +| `remote` | 并入 [remote-core](../remote-core) 仓库（被控端远程能力归位） | | +| `qps` | 不迁入 | 空壳包（无代码） | + +迁移中修复的缺陷见各包 README：`frame`（SetData 未返回错误、ReadFrame 短读/吞帧）、 +`ipratelimiter`（包子句大写不规范）、`httpx`（README 笔误）等。 + ## 约定 - 通用性准入：被 ≥2 个服务复制使用过的包才进入本仓库；仅单服务使用的留在服务内。 - 改动流程：在本仓库修复/演进 → 打 tag（如 v0.2.0）→ 各服务 `go get git.zeroonesoft.cn/golib/zogo@v0.2.0`。 - 本地联动开发：在 `D:\zomaintain\backend\go.work` 中 `use D:/golib/zogo`（go.work 不提交）。 -- go.mod 声明 go 1.24（不高于最低版本消费方），不要随意上调。 +- go.mod 声明 go 版本不高于最低版本消费方，不要随意上调。 - 依赖版本声明「最低可用」而非 latest（如 gorm 锁消费方在用的版本），避免把消费方依赖图顶出新版本引发不兼容。 -- 每个包自带 README.md（定位/用法/注意事项），改 API 先改文档。 - -## 私有模块拉取配置（每台开发机/CI 一次） - -``` -go env -w GOPRIVATE=git.zeroonesoft.cn/* -``` -git 凭据需能访问 git.zeroonesoft.cn（Git Credential Manager 存 PAT）。 +- 每个包自带 README.md（定位/用法/注意事项），改 API 先改文档；可运行例程统一放 `examples/<包名>/main.go`。 diff --git a/go.mod b/go.mod index 47b61c4..be64610 100644 --- a/go.mod +++ b/go.mod @@ -9,10 +9,16 @@ require ( github.com/google/uuid v1.6.0 github.com/gorilla/websocket v1.5.3 github.com/lestrrat-go/file-rotatelogs v2.4.0+incompatible + github.com/lionsoul2014/ip2region/binding/golang v0.0.0-20250508043914-ed57fa5c5274 + github.com/lxn/win v0.0.0-20210218163916-a377121e959e github.com/mattn/go-colorable v0.1.15 github.com/mozillazg/go-pinyin v0.21.0 + github.com/shirou/gopsutil/v3 v3.24.3 github.com/sirupsen/logrus v1.10.2 + github.com/yusufpapurcu/wmi v1.2.4 + golang.org/x/sys v0.47.0 golang.org/x/text v0.41.0 + golang.org/x/time v0.5.0 gorm.io/gorm v1.25.12 ) @@ -35,26 +41,23 @@ require ( github.com/klauspost/cpuid/v2 v2.3.0 // indirect github.com/leodido/go-urn v1.5.0 // indirect github.com/lestrrat-go/strftime v1.2.0 // indirect - github.com/lionsoul2014/ip2region/binding/golang v0.0.0-20250508043914-ed57fa5c5274 // indirect - github.com/lxn/win v0.0.0-20210218163916-a377121e959e // indirect + github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect github.com/mattn/go-isatty v0.0.20 // indirect - github.com/mitchellh/go-homedir v1.1.0 // indirect github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect github.com/modern-go/reflect2 v1.0.2 // indirect - github.com/mostlygeek/arp v0.0.0-20170424181311-541a2129847a // indirect github.com/pelletier/go-toml/v2 v2.2.4 // indirect github.com/pkg/errors v0.9.1 // indirect + github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect github.com/quic-go/qpack v0.6.0 // indirect github.com/quic-go/quic-go v0.59.0 // indirect - github.com/shirou/gopsutil/v3 v3.24.3 // indirect + github.com/shoenig/go-m1cpu v0.1.6 // indirect + github.com/tklauser/go-sysconf v0.3.12 // indirect + github.com/tklauser/numcpus v0.6.1 // indirect github.com/twitchyliquid64/golang-asm v0.15.1 // indirect github.com/ugorji/go/codec v1.3.1 // indirect - github.com/yusufpapurcu/wmi v1.2.4 // indirect go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect golang.org/x/arch v0.22.0 // indirect golang.org/x/crypto v0.55.0 // indirect golang.org/x/net v0.57.0 // indirect - golang.org/x/sys v0.47.0 // indirect - golang.org/x/time v0.5.0 // indirect google.golang.org/protobuf v1.36.10 // indirect ) diff --git a/go.sum b/go.sum index a748f4a..cec664f 100644 --- a/go.sum +++ b/go.sum @@ -61,6 +61,7 @@ github.com/lestrrat-go/strftime v1.2.0 h1:8fAUYOeaJKCuLzNvUWBAo8t6I6hkFfodDTndEz github.com/lestrrat-go/strftime v1.2.0/go.mod h1:GtsIA/7ddIGJjEdfadUafEb1sbutvlvpMdPCMglykYo= github.com/lionsoul2014/ip2region/binding/golang v0.0.0-20250508043914-ed57fa5c5274 h1:Vslec/nYvO2TdLdhwex8/1x64OZoQNsUzG79WABQaWg= github.com/lionsoul2014/ip2region/binding/golang v0.0.0-20250508043914-ed57fa5c5274/go.mod h1:C5LA5UO2ZXJrLaPLYtE1wUJMiyd/nwWaCO5cw/2pSHs= +github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4= github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I= github.com/lxn/win v0.0.0-20210218163916-a377121e959e h1:H+t6A/QJMbhCSEH5rAuRxh+CtW96g0Or0Fxa9IKr4uc= github.com/lxn/win v0.0.0-20210218163916-a377121e959e/go.mod h1:KxxjdtRkfNoYDCUP5ryK7XJJNTnpC8atvtmTheChOtk= @@ -68,15 +69,11 @@ github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8= github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY= github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y= -github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y= -github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0= github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M= github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk= -github.com/mostlygeek/arp v0.0.0-20170424181311-541a2129847a h1:AfneHvfmYgUIcgdUrrDFklLdEzQAvG9AKRTe1x1mx/0= -github.com/mostlygeek/arp v0.0.0-20170424181311-541a2129847a/go.mod h1:jZxafo9CAqaKFQE4zitrg5QNlA6CXUsjwXPlIppF3tk= github.com/mozillazg/go-pinyin v0.21.0 h1:Wo8/NT45z7P3er/9YSLHA3/kjZzbLz5hR7i+jGeIGao= github.com/mozillazg/go-pinyin v0.21.0/go.mod h1:iR4EnMMRXkfpFVV5FMi4FNB6wGq9NV6uDWbUuPhP4Yc= github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4= @@ -84,6 +81,7 @@ github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4= github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF4JjgDlrVEn3C11VoGHZN7m8qihwgMEtzYw= github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE= github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8= github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII= @@ -91,7 +89,9 @@ github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SA github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU= github.com/shirou/gopsutil/v3 v3.24.3 h1:eoUGJSmdfLzJ3mxIhmOAhgKEKgQkeOwKpz1NbhVnuPE= github.com/shirou/gopsutil/v3 v3.24.3/go.mod h1:JpND7O217xa72ewWz9zN2eIIkPWsDN/3pl0H8Qt0uwg= +github.com/shoenig/go-m1cpu v0.1.6 h1:nxdKQNcEB6vzgA2E2bvzKIYRuNj7XNJ4S/aRSwKzFtM= github.com/shoenig/go-m1cpu v0.1.6/go.mod h1:1JJMcUBvfNwpq05QDQVAnx3gUHr9IYF7GNg9SUEw2VQ= +github.com/shoenig/test v0.6.4 h1:kVTaSd7WLz5WZ2IaoM0RSzRsUD+m8wRR+5qvntpn4LU= github.com/shoenig/test v0.6.4/go.mod h1:byHiCGXqrVaflBLAMq/srcZIHynQPQgeyvkvXnjqq0k= github.com/sirupsen/logrus v1.10.2 h1:G2SED73/qrAu6YwbdxOD6peLkCBI3z7L+ykJFTXJBBo= github.com/sirupsen/logrus v1.10.2/go.mod h1:SLEg8TqYulVKKfIGHldVp2K2aYz2DKSVBq4g/H5bR7Q= @@ -107,7 +107,9 @@ github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE= github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg= +github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFAEVmqU= github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI= +github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk= github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY= github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI= github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=