pkg

README

pkg

微工具集 19 合 1——errors/bloomx/container/contextx/stringx/convert/timex/cache/bufiox/strmap 等基础工具包

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/pkg@v0.11.0

这个仓库做什么

pkg 是 oekit 的基础工具集：19 个经过生产验证的小工具包合成一个 module， 覆盖错误处理、字符串/切片/类型转换、泛型容器、时间与 cron、JSON 修复、 HTTP JSON 调用、分页、glob 匹配、进程内缓存、零拷贝缓冲 IO、GC 友好只读字典 等日常高频需求。标识与校验（uidgen/validator）已拆分至 kitx。

设计原则：

• 按包编译：import 哪个子包用哪个，go.mod 只多一条 require，二进制零冗余
• 零第三方依赖（v0.10.0 起）：全部子包只依赖标准库，validator/v10 随拆分迁出
• 生产验证：全部代码源自 enjoydream 后端服务多年共用积累，带完整单元测试（19/19 包）

包清单

包	做什么
errors	错误链 Wrap/Cause（nil-safe）、BizError（业务码/HTTP 码双轨）、Chain/In 组合工具、sentinel 错误。整个矩阵的错误处理基座
bloomx	本地布隆过滤器：FNV-1a 双哈希、RWMutex 并发安全，缓存穿透防护/去重预检（非法入参归一默认值）
contextx	ValueOnlyFrom 只传值轻量 ctx：剥离 Done/Err/Deadline，把请求值交给后台任务而不继承取消/超时
stringx	ID 生成、关键词包含匹配、缩进、英文复数化、{key} 模板替换
slicex	Partition 二分组（保序）、GroupBy 等切片操作
container	泛型容器（v0.9.0 起，收编原 collectionx）：Set（集合代数并/交/差）、Ring 定长环形缓冲、Queue 阻塞队列、SafeMap（RWMutex）、Map（sync.Map 背书，读多写少）、Slice 并发安全切片——参考 go-kratos/kit container 设计
enumx	枚举：确定性顺序的 All/Values/解析（map 遍历乱序问题的解法）
convert	字符串/数字/布尔/切片的宽容转换（脏输入友好）
encoding	JSON 序列化助手（UnmarshalUseNumber 系列保留 json.Number，防 >2^53 float 精度丢失）+ FNV-1a/SHA-256 摘要与 Base64
jsonrepair	LLM 输出等脏 JSON 的宽容修复链（围栏/尾逗号/单引号/括号闭合），修复永不失败——异常时回退原文；UnmarshalLenient 宽松模式尽力闭合截断的数组/对象（半截字符串/键位补 null/悬空逗号）并回报 partial
httpjson	带 JSON 解析的 HTTP 调用助手
mathx	安全随机、平均值等统计助手 + Unstable 抖动值（Around 对称打散缓存 TTL 防雪崩 / Upward 单边向上，重试退避「不得早于基准」）
pathx	glob 路径匹配（vendor/**、*.test）
pagination	PageRequest/PageResponse 分页换算
ptrx	指针 To/From 与安全解引用
timex（+cron）	时间格式化/解析/时间戳 + cron 表达式
cache	刷新检查器：TTL 后台刷新、失败按 failTTL 降级、并发请求合并为一次刷新
bufiox	面向协议编解码的零拷贝缓冲 IO：读侧 Next/Peek 返回缓冲视图，写侧 Malloc/WriteBinary 攒批一次 Flush（bytes 与 io.Reader/Writer 双实现）
strmap	GC 友好的只读字符串 map：键打包 + int32 哈希表 + maphash，海量静态映射（header/字典表）零 GC 扫描开销

快速使用

import (
    "github.com/oekit/pkg/errors"
    "github.com/oekit/pkg/jsonrepair"
    "github.com/oekit/pkg/stringx"
)

// 错误链：nil-safe 包装 + kv 关联字段，Is/As 语义保持
err := errors.Wrap(io.ErrUnexpectedEOF, "read config", "path", "/etc/app.yaml")

// 脏 JSON 修复（LLM 场景）
fixed := jsonrepair.Repair(`{"name": "oekit",) `)

fmt.Println(stringx.Pluralize(3, "module")) // 3 modules

import (
    "github.com/oekit/pkg/bufiox"
    "github.com/oekit/pkg/strmap"
)

// 零拷贝解析：Peek 定长头 → Next 出负载视图，全程无字段级拷贝
r := bufiox.NewDefaultReader(conn)
hdr, _ := r.Peek(4)                  // 零拷贝视图
_ = r.Skip(4)
payload, _ := r.Next(int(binary.BigEndian.Uint32(hdr)))
defer r.Release(nil)                 // Release 后视图失效

// GC 友好只读字典：构建后只读，Get 无 map 开销
var canon = strmap.NewStr2StrFromMap(map[string]string{
    "content-type": "Content-Type",
})
name, ok := canon.Get("content-type") // "Content-Type", true

边界

• 需要并发原语（safe-go/重试/限流）→ concurrency
• 需要日志 → logx；需要数据库 → gormx
• 本仓不依赖矩阵内任何其他模块（validator→errors、httpjson→stringx、bloomx→encoding 三条内部边除外）

矩阵总览（24 活跃模块，自动生成）

模块	内容	矩阵内依赖
pkg	微工具集 19 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap；v0.10.0 起 uidgen/validator 拆至 kitx）；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约 + Checker；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）	—
concurrency	并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮	pkg
logx	统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入	—
core	应用基建件（governance 治理 schema / config 配置加载 + default/env/range/options tag 校验 / lifecycle 契约 / network IP 工具 / version）	—
kitx	标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail），自 pkg v0.10.0 拆出	pkg
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源	logx
registry	注册发现核心 + Nacos 实现 + Nacos 配置源 + sdbridge	core、logx
data	数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；all/ 聚合模块已废弃 retract	concurrency、gormx、logx、pkg、redisx、timertask
gormx	SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名）	logx、pkg
redisx	Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock、分布式限流 ratelimit（Lua 三态 + 故障本地兜底）	concurrency、logx、pkg
etcdx	etcd 全家——客户端封装（根包：生产默认值/Health 探活/Close(ctx) 幂等）、registry 注册发现实现（SPI 对接 registry/nacos 链路：Lease KeepAlive 注册 + 丢约指数退避自动重注册、prefix Watch 订阅推送、ConfigStore KV 配置监听）、distlock 分布式锁（Session+concurrency.Mutex 公平排队，接口与 redisx/distlock.Locker 同形可互换，可选无 etcd 降级放行）	concurrency、core、logx、registry
httpx	HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传/一致性哈希（权重感知虚拟副本）	concurrency、core、logx、metrics、registry、tracing
network	轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具	concurrency、logx、tracing
timertask	分片定时任务（FNV-1a、心跳续约）	concurrency、logx
middleware	Hertz 自研标准中间件栈 + contrib 桥接 + hmw + SheddingMiddleware 自适应降载	concurrency、core、logx、metrics、pkg、registry、tracing
k8s	Kubernetes 客户端封装——RESTConfig/Clientset/DynamicClient 构建（显式 kubeconfig → in-cluster 自动 → KUBECONFIG/~/.kube/config 逐级回退，QPS/Burst 限流默认 50/100）+ leaderelection 子包 Lease 选主简化封装（OnStartedLeading/OnStoppedLeading/OnNewLeader 回调，主备单活，仅要求 Lease CRUD 权限）	logx
nns	NNS 服务治理客户端——provider 无关发现/配置/实例缓存	concurrency、core、logx、registry
nns-endpoint	NNS 端点工厂——per-service 熔断、换实例重试、gRPC 池	concurrency、core、httpx、logx、metrics、nns、registry
bootstrap	应用生命周期引导——bootstrap.Run 骨架 + healthz	concurrency、logx
hertz	Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh/versionh（原 handler 微库收编）	bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing
kitex	Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	组合式流程编排——串行/并行/异步/条件分支 + Hook AOP	concurrency、logx
kitex-examples	Kitex echo 示例——client/server + IDL + 治理配置	bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、tracing

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE