# oekit

> Open Easy Kit — 开源 · 易用 · 工具集合。24 个独立发版的 Go 模块（根模块），另有 9 个嵌套模块各自独立发版，合计 34 个发版单元：微工具库、日志/追踪/指标门面、注册发现、HTTP/Kitex 生态、应用引导。

oekit 是一套按"框架耦合分层"组织的 Go 模块矩阵。依赖严格自底向上，每仓独立 SemVer + 独立 CI。每个仓库根目录都有 AGENTS.md（面向 AI Agent 的规范与硬规则）。

## 版本矩阵（机器可读）

- 机器可读版本矩阵：https://oekit.github.io/versions.json
  （每模块 `latest` / `nested` / `matrixDeps` / `breakingIndex`；由 matrix-tools
  `scripts/gen_versions.py` 生成，结构变更当天重跑即可刷新）
- ekit→oekit import 改写：`matrix-tools/scripts/ekit2oekit.py`（AST/import 面 +
  规则表 `--print-rules`；调用点级改动输出需人工清单）
- 一次拉齐经 CI 验证的兼容组合：`go get github.com/oekit/oekit@latest`（BOM 快照
  module `github.com/oekit/oekit`，`matrix.go` 暴露 `Versions`/`VersionOf`；由
  matrix-tools `scripts/gen_matrix_go.py` 从远端 tag 生成）

## 模块

依赖严格自底向上，五个能力层（架构图：https://oekit.github.io/about/architecture.html）

### 应用引导 · 框架生态
- [bootstrap](https://github.com/oekit/bootstrap): 组合根——App/New+Run 应用骨架 + healthz + 优雅关停（v0.4.0 删除 Run(Config{...})，改 `New(WithServiceName, WithShutdownTimeout)` 再 `b.Run(fn)`）；**就绪门** `App.Ready/ReadyChan/IsReady`（幂等并发安全）——嵌套 `bootstrap/nacos` 自 v0.3.0 起 NNS 注册延迟到 Ready 之后（server 就绪 → userFn 触发 Ready → 才进注册中心），关停序 nns 反注册先于 server 关闭；Metrics/Tracing 在嵌套模块 `bootstrap/obs`
- [hertz](https://github.com/oekit/hertz): Hertz 运行时集成（日志桥接/生命周期/SSE/OTel）+ crudh/validatorh/versionh（泛型 CRUD Handler）——模块根扁平化（原 hertz/hertz 双层已收平）；`RunServer` 变参就绪门 `WithOnReady`（全部 HostPort TCP 探活可建连后回调，探活超时按启动失败优雅关机；`WithReadyProbeTimeout` 缺省 5s——探活目标是 server 自动取到的全部 HostPort，**无探活地址覆盖选项**（那是 kitex 侧才有的选项））+ transportx（hertz→core/transport 适配器）+ chainmw 桥接
- [kitex](https://github.com/oekit/kitex): Kitex 生态（治理热更/BizError 桥接/kitexotel）+ istio（xDS 动态熔断）——模块根扁平化（原 kitex/kitex 双层已并入 v0.6.0）；`RunServer` 变参就绪门（WithOnReady/WithReadyAddr/WithReadyProbeTimeout）+ `chainmw.ToKitex`（core/chain.Middleware → kitex 中间件）+ transportx
- [middleware](https://github.com/oekit/middleware): Hertz 标准中间件栈（模块根包 mw，middleware/middleware 双层目录已收平）+ contrib 桥接 + hmw（模块根 `mw/...` 子包）+ chainmw 子包（transport 感知框架无关中间件，基于 core/chain+transport：Recovery 带 panic 隔离上报钩子/AccessLog skip+redact/MetadataPropagate——kitex 经 kitex/chainmw.ToKitex 复用，根包 Recovery/AccessLog 已薄壳化复用 chainmw 内核）；v0.11.0 起 WithAccessLogSink 落库 sink（AccessRecord 与日志同源、error/panic 隔离不影响主链路）+ StackConfig.DisableResponseWrap 响应自管一键形态 + AccessLogOptions 透传 + 适用边界文档（响应自管服务推荐组合）；v0.12.0 起 panic 恢复点产出访问记录（Panic 标记，status 按 Recovery 缺省 500）后按原值重抛
- [workflow](https://github.com/oekit/workflow): 流程编排（Pipe/Parallel/Async/Switch + Hook）
- [kitex-examples](https://github.com/oekit/kitex-examples): Kitex echo 示例（client/server + 治理配置）
- [k8s](https://github.com/oekit/k8s): Kubernetes 客户端封装——RESTConfig/Clientset/DynamicClient 构建（显式 kubeconfig → in-cluster 自动 → KUBECONFIG/~/.kube/config 逐级回退，QPS/Burst 默认 50/100）+ leaderelection Lease 选主（OnStartedLeading/OnStoppedLeading 回调，主备单活）

### 通信 · 服务治理
- [httpx](https://github.com/oekit/httpx): HTTP 客户端（服务发现/熔断 ErrCircuitOpen/重试/指标/OTel 透传）+ loadbalance Selector 负载均衡（RoundRobin/Random/Weighted/一致性哈希权重感知虚拟副本/p2c 自适应——EWMA 经 DoneFunc 回写、WithFilter 元数据过滤；v0.4.0 起 Balancer 全家族删除无兼容路径）+ codec 注册制编解码器（json 内置 + form 表单，DoCodec）+ v0.6.0 起 net/http 桥接 NewRoundTripper/StdClient——存量标准库外呼一行 Transport 接入熔断/重试/指标/链路（重试缺省关 WithRetryConfig 显式开、非 2xx 非错误、hop-by-hop 隔离）
- [nns-endpoint](https://github.com/oekit/nns-endpoint): 端点工厂（per-service 熔断/换实例重试）
- [network](https://github.com/oekit/network): WebSocket/NATS/MQ/流工具（conn/mq/nats/streamx/wsutil）
- [nns](https://github.com/oekit/nns): 服务治理门面（发现/配置/实例缓存）
- [registry](https://github.com/oekit/registry): 注册发现 SPI + Nacos 实现 + sdbridge（v0.3.0 起不再含 config 加载，config 新家见 core）

### 数据访问
- [gormx](https://github.com/oekit/gormx): SQL/GORM 全家（crud Service 事务防丢更新）
- [redisx](https://github.com/oekit/redisx): Redis 客户端/缓存后端/分布式锁（Locker 同形可互换；Renew 手动续期 + WithAutoRenew 覆盖 TryLock 自动续期，v0.8.0 feat!）+ distlock.Semaphore ZSET 槽位信号量（v0.8.0：Acquire 幂等刷新 + 原子清过期槽、Renew 仅未过期槽可续、无 Redis 降级 fail-fast）；distlock Lockout 分布式防爆破锁（v0.9.0，Redis 侧 fail2ban：滑窗失败计数→锁定 Penalty→Reset，与 concurrency/ratelimit.Lockout 进程内孪生，多实例共享计数）/分布式限流 ratelimit（Lua 三态 + 故障本地兜底）
- [etcdx](https://github.com/oekit/etcdx): etcd 全家——客户端封装（根包）+ registry 注册发现实现（Lease KeepAlive 注册/丢约自动重注册/prefix Watch 订阅/ConfigStore 配置监听，SPI 与 registry/nacos 互换）+ distlock 分布式锁（Session+Mutex，接口与 redisx/distlock.Locker 同形可互换）
- [data](https://github.com/oekit/data): 数据访问门面——cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（复刻 ekit data/ 能力面，类型同一）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播
- [timertask](https://github.com/oekit/timertask): 分片定时任务（FNV-1a、心跳续约）+ 可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信，v0.1.7 起接入生命周期真正生效）；**v0.2.0 起 Redis 后端迁至嵌套模块 `timertask/redis`**（根包不再引 go-redis/logx/concurrency，require 仅 pkg——`import timertask` 与 `import timertask/local` 的模块依赖面均无 redis，纯 stdlib 嵌入式场景可用）+ **新增 local 子包 cron 调度器 Scheduler**（New/Schedule/Unschedule/Start/Stop，表达式复用 pkg/timex/cron 不另写一份；并发度/CatchUp 补跑/退出语义明确，FakeClock 假时钟驱动、触发点序列可确定性断言）

### 可观测性
- [logx](https://github.com/oekit/logx): 统一日志门面（接口分层、多后端、caller 归属；根包纯 stdlib）——WithFilter 脱敏/丢弃（FilterKey ***/FilterFunc 丢整条）、Slogger/SlogHandler 正向桥（三方 slog 消费 logx 生态）、TraceHandler 任意 slog.Handler 注入 trace_id、NewAuditLogger 审计留痕（级别锁 Info 不受 LOG_LEVEL 降级）、LevelEnabler 提前判级、ParseLogLevel (Level, error)/ParseLogLevelOr（v0.7.0）；Sink 在嵌套模块 logx/sink；优雅关停正身 core/lifecycle（logx/shutdown 仅余 Deprecated 别名）
- [tracing](https://github.com/oekit/tracing): OTel Init + traceid 真相源 + http/redis 插桩；**v0.3.0 起 OTLP 双协议导出**（Config.Protocol：grpc 缺省 / http，Config.Headers 认证头两协议都生效）——http 走 otlptracehttp/otlpmetrichttp，与 gRPC 分支同样的全局语义（TracerProvider + MeterProvider 含 runtime 指标 + 传播器 + 关闭被替换的旧 provider），换协议退回换一条传输；端点接受完整 signal URL / 基址 / 无 scheme 的 host:port 三种写法；端点不嵌凭据（凭据走 Headers，不进日志与错误信息）
- [metrics](https://github.com/oekit/metrics): Prometheus 门面 + 弹性指标族

### 基础库
- [pkg](https://github.com/oekit/pkg): 23 合 1 微工具集（零第三方依赖，仅标准库）——errors（Wrap/BizError/Chain/In；v0.12.0 起 New/As/Is/Unwrap 与 stdlib 同型透传——哨兵/As 判定单 import 即可）、bloomx（布隆过滤器）、contextx（ValueOnlyFrom）、container（Set/Ring/Queue/SafeMap/Map/Slice 泛型容器，v0.9.0 收编原 collectionx）、stringx（含 trie 多模式替换器 Replacer/NewMask 敏感词遮罩；v0.16.0 起 Masker 正则脱敏——按形态分类打码 + 保留首尾各 ≤4 字符定位线索 + 不可复原，规则表由调用方完全提供）、slicex、enumx、convert、encoding（UseNumber 防精度丢失）、jsonrepair（v0.11.0 起含 UnmarshalLenient 宽松解析；v0.18.0 起抽对象与抽数组对称原语 ExtractObject·ExtractArray——多段数组与散文含 '{' 的数组文本不再整段作废，取首个口径与对象面一致）、httpjson、mathx（Unstable 抖动；v0.11.0 起含单边向上 Upward）、pathx、pagination、ptrx、timex(+cron +时间段边界 BeginningOf/EndOf)、cache（CacheAside + BatchGetter(MGet) + LocalCache/SingleFlightCache + cachetest 契约：Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界，v0.13.0；v0.16.0 起 LocalCache 可选形状 NoBackgroundSweep 无后台 goroutine + CloneOnRead 读命中返回副本 + EvictPolicy LRU + GetEx 命中标志，新能力以可选接口 Sweeper/HitGetter 外置、不破坏既有 Cache 接口）、bufiox（零拷贝缓冲 IO）、strmap（GC 友好只读 map）、singleflighttest（契约测试套件）、cli（v0.16.0 起 框架无关可单测的子命令分发原语：App/Command + 退出码 0/1/2 写死在包里 + usage 按 Summary 自动生成 + 不读 os.Args 不调 os.Exit，输出流全由调用方给）、pack（v0.16.0 起 迁移包容器原语：zip + manifest 清单〔格式版本/条数/每文件 SHA-256〕+ JSONL 流式读写 + Inspect 体检一次列全问题，哨兵错误区分包损坏与版本不认识 + 文件名净化防 zip 路径穿越）；v0.10.0 起 uidgen/validator 拆至 kitx
- [kitx](https://github.com/oekit/kitx): 标识与校验——uidgen（Snowflake 全局单例 + Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样）+ validator（go-playground/validator v10 接口化门面，ValidationError Unwrap 为 BizError 400 对接 middleware.Fail）+ hash（v0.2.0 起非密码学 Md5Hex/Md5Bytes——缓存键/幂等键/短唯一 code，格式稳定承诺，禁用于凭据/签名）
- [concurrency](https://github.com/oekit/concurrency): GoSafe/gopool、单飞（DoShared 折叠可观测/Result.Waiters）、重试（DelayHint Retry-After 优先/JitterRatio 比例抖动 + retry/httpx Retryable；v0.18.0 起 `retry.DoValue[T]`——带返回值的重试，且 `Do` **委托**给 `DoValue`：退避序列/抖动/MaxDelay 封顶/DelayHint 优先/Retryable 门控/ctx 取消只有一份实现，失败返回零值与最后一次错误）、令牌桶、滑动窗口、**三态自适应熔断**（ErrCircuitOpen；closed/open/half-open + GenBreaker 代绑定 AllowGen/SuccessGen/FailureGen/AbandonGen + WithProbeTimeout 缺省 1m + WithCooldown 独立冷却 + WithConsecutiveFailures 连续失败触发；v0.13.0 起熔断期收敛到探测级——open 态不放流量，仅 forcePass 强制探活（缺省 1s）+ 冷却期满半开探测，SRE 公式退役为 closed→open 触发器；State()/State 枚举可观测出口）、ratelimit NewKeyedLimiterByFunc（v0.16.0，factory func(K) Limiter 按 key 定配额单管理器分档位）+ KeyedLimiter.Create 护栏内原子登记（v0.17.0，表满先回收空闲/已存在不覆盖/热更走 Replace）、CPU 自适应降载、ratelimit Lockout 防爆破锁（v0.11.0，fail2ban 形态 keyed 锁定/成功 Reset）、retry/httpx RetryableWithHeaders 403 头感知判定（v0.12.0/v0.13.1，HeaderSource 零依赖抽象 + 头值 OWS 修剪）、syncx FanInLimit 受限并发扇出 + FanInLimitCtx ctx 感知变体（v0.14.0：取消时未启动项 fn 一次不调/剩余槽快速排空 Canceled/在飞项照常落槽）、batch 攒批执行器（满条数/满字节/窗口去重）、timewheel 单级时间轮；async panic 统一收编 typed *PanicError（errors.As 可辨携带栈）+ 实例级 Runner panic 路由
- [core](https://github.com/oekit/core): governance 治理 schema、lifecycle 契约 + Manager 优雅关停（自 logx/shutdown 迁入，日志 *slog.Logger——core 不再依赖 logx）、**transport 协议无关传输上下文**（Transporter/Header/ctx 存取，仅标准库）、**chain 中间件链**（Handler/Middleware/Chain/Recovery/Timeout）、网络 IP 工具、version、**config 配置加载**（LoadDotEnv/Get*/OverlayMerge/ParseDuration + default/env/range/options tag 校验 + OverlaySource 多源叠加 + ApplyEnvOverlay env 优先；v0.9.0 起 FieldSet 显式提供集合（yaml 显式 port:0 不再被 default/env 覆盖，LoadBootstrap 默认接线免指针化）+ require tag，v0.9.1 修 inline 字段标记；v0.9.2 起 env 卫生改纯静态（仅格式/重名，移除依赖进程环境的拼写冒烟检查——既误报 PATH/HOME 又漏掉真拼错；命名一致性走 LintEnvNaming 诊断 / WithEnvNamingLint 可选 fail-closed / ignorederived="true" 豁免）；v0.10.0 起 **严格模式**（`config.WithStrict()`）：未知键**拒载**，错误带**嵌套路径** + **该层合法键清单** + **近似拼写建议**（`UnknownKeyError`），默认行为不变、显式开启；v0.11.0 起加载入口**按来源拆开**——`LoadFile`（任意路径：CLI -config、容器内固定挂载位）/ `Unmarshal`（字节源：API 下发 / 模板渲染 / 测试夹具）/ `LoadBootstrap`（etc/ 约定），三者共享**同一条解码线**，因此严格模式诊断面**与来源无关**；ekit `config` 包的新家；registry v0.3.0 已移除 config）

## 嵌套模块（可选装 · 依赖隔离）

> 嵌套模块是**独立发版**的 Go module（各自有 tag），职责是**依赖隔离**而非目录组织：
> 只 import 根模块的消费者**不会**被拉入这些重依赖；需要时才单独 `go get`。

- [bootstrap/nacos](https://github.com/oekit/bootstrap/tree/main/nacos): bootstrap 的 Nacos/NNS 服务治理接入——以 BootstrapperOption 注入，父仓保持零 Nacos 依赖（v0.3.0 起注册延迟到 App.Ready 之后）
  - 安装：`go get github.com/oekit/bootstrap/nacos@latest`
  - 版本：`v0.3.5` · 对应父仓 `bootstrap v0.6.4`

- [bootstrap/obs](https://github.com/oekit/bootstrap/tree/main/obs): bootstrap 的可观测性接入——以 BootstrapperOption 注入 Prometheus 指标（oekit/metrics）与 OpenTelemetry 追踪（oekit/tracing），父仓保持零 prometheus/otel 依赖
  - 安装：`go get github.com/oekit/bootstrap/obs@latest`
  - 版本：`v0.2.9` · 对应父仓 `bootstrap v0.6.4`

- [logx/sink](https://github.com/oekit/logx/tree/main/sink): logx 的输出目标实现——Sink 抽象 + MultiSink/FileSink/RotatingSink 三个内置实现，重依赖隔离在此，根包纯 stdlib
  - 安装：`go get github.com/oekit/logx/sink@latest`
  - 版本：`v0.1.0` · 对应父仓 `logx v0.4.0`

- [logx/hlog](https://github.com/oekit/logx/tree/main/hlog): 基于 Hertz hlog 的 logx.Logger 实现（结构化 kv 降级为字符串拼接，输出格式与 Hertz hlog 对齐）
  - 安装：`go get github.com/oekit/logx/hlog@latest`
  - 版本：`v0.1.4` · 对应父仓 `logx v0.7.1`

- [logx/hertzlog](https://github.com/oekit/logx/tree/main/hertzlog): Hertz 日志后端桥接——logrus/zap/zerolog/slog 四后端各自实现 hlog.FullLogger（依赖隔离，logx 根包不引三方日志库）
  - 安装：`go get github.com/oekit/logx/hertzlog@latest`
  - 版本：`v0.1.0` · 对应父仓 `logx v0.2.0`

- [logx/kitexlog](https://github.com/oekit/logx/tree/main/kitexlog): Kitex 日志后端桥接——把 logx.Logger 适配为 Kitex klog.FullLogger（依赖隔离，logx 根包不引 kitex）
  - 安装：`go get github.com/oekit/logx/kitexlog@latest`
  - 版本：`v0.1.4` · 对应父仓 `logx v0.7.1`

- [timertask/redis](https://github.com/oekit/timertask/tree/main/redis): timertask 的 Redis 后端——RedisBackend/ShardManager 与可靠投递，go-redis 隔离在此，根包零 redis 依赖（v0.2.0 起）
  - 安装：`go get github.com/oekit/timertask/redis@latest`
  - 版本：`v0.2.1` · 对应父仓 `timertask v0.2.1`

- [registry/nacosimpl](https://github.com/oekit/registry/tree/main/nacosimpl): Nacos SPI 实现——Discoverer/ConfigStore/Registrar 基于 nacos-sdk-go v2（nacos-sdk 重依赖隔离在此，registry 根仓零 nacos-sdk）
  - 安装：`go get github.com/oekit/registry/nacosimpl@latest`
  - 版本：`v0.1.0` · 对应父仓 `registry v0.5.0`

- [registry/nacos](https://github.com/oekit/registry/tree/main/nacos): Nacos 客户端门面——Bootstrap 配置、client 工厂与 config 加载（实现 core/config.ConfigSource，配 ConfigWatcher 热更新）
  - 安装：`go get github.com/oekit/registry/nacos@latest`
  - 版本：`v0.1.0` · 对应父仓 `registry v0.5.0`

## 文档

- [架构总览](https://oekit.github.io/about/architecture.html): 五能力层架构图 + 关键依赖链 + 设计原则
- [快速开始](https://oekit.github.io/guide/getting-started.html): 三种起步姿势 + 模块地图
- [日志指南](https://oekit.github.io/guide/logging.html): logx 全量用法
- [错误处理](https://oekit.github.io/guide/errors.html): Wrap/BizError/Fail 链路与类型同一性红线
- [缓存指南](https://oekit.github.io/guide/caching.html): cache/cached/twolevel 三件套——写后失效/事务安全/查询缓存/两级缓存+失效广播
- [HTTP 服务](https://oekit.github.io/guide/http-service.html): 全栈七步走
- [RPC 服务](https://oekit.github.io/guide/rpc-service.html): 治理热更/BizError 桥接/端点熔断
- [可观测性](https://oekit.github.io/guide/observability.html): metrics/tracing/traceid
- [AI Agent 指南](https://oekit.github.io/guide/ai-agent.html): 人与 Agent 的接入手册
- [迁移指南](https://oekit.github.io/guide/migration.html): ekit 单体 → oekit 路径映射（含完整 perl 改写脚本、矩阵内升级迁移对照、模块布局扁平化说明、bootstrap.Run 删除改写与就绪门契约、混合依赖过渡期 logx 桥）
- [统一 CI](https://github.com/oekit/.github): 共享 reusable workflow——各仓 ci.yml 是薄调用层，改规则只改这一个仓
- [平台契约](https://oekit.github.io/docs/PLATFORM_CONTRACT.html): 分层契约（ekit 时期文档）
- [服务模板](https://oekit.github.io/docs/SERVICE_TEMPLATE.html): 服务脚手架示例

## AI Agent 要点

- 每仓根目录的 AGENTS.md 是该仓的权威规范：错误处理必须用 pkg/errors（类型同一性红线）、
  日志用 logx kv 风格、SDK 包用 Delegating、禁止裸 go func（用 concurrency/async）
- 安装一律 `go get github.com/oekit/<mod>@latest`；不要 pin 旧路径（ekit 单体 / yi-nology 均已迁移）
- 不确定 API 时以源码为准确：每仓均带测试，`go doc github.com/oekit/<mod>[/<pkg>]` 可查
- 改 CI 规则只去 oekit/.github 仓（go-ci.yml@main）；各仓 ci.yml 只带按仓参数，不要在各仓复制规则