README
¶
logx
统一日志门面——接口分层/多后端可替换/Sink 多目标/caller 归属
🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。
安装
根门面（纯 stdlib，零外部依赖）：
go get github.com/oekit/logx@v0.8.0
模块布局（1 根模块 + 3 嵌套模块）
本仓自 v0.2.0 起为嵌套多模块仓（同仓不同 go.mod，先例：oekit/bootstrap 的
nacos/、obs/）：根门面与三个框架桥接子包各自持有独立 go.mod，import 路径
不变，依赖图按需解析——Go 的依赖图是模块级的，此前根模块 require 的
hertz/kitex/zap/zerolog/logrus 会进所有消费者的依赖图；拆分后只 import 根门面
的消费者不再被拉入任何框架依赖。
| go.mod 路径 | module | 职责 | 框架依赖 | 安装 |
|---|---|---|---|---|
./ |
github.com/oekit/logx |
统一门面 + std/slog 后端 + shutdown | 无 | go get github.com/oekit/logx@v0.8.0 |
./sink/ |
github.com/oekit/logx/sink |
Sink/FileSink/RotatingSink/MultiSink 多目标输出 | lumberjack | go get github.com/oekit/logx/sink@v0.1.0 |
./hlog/ |
github.com/oekit/logx/hlog |
Hertz hlog 后端适配 | cloudwego/hertz | go get github.com/oekit/logx/hlog@v0.1.0 |
./hertzlog/ |
github.com/oekit/logx/hertzlog |
hertz-contrib logrus/zap/zerolog/slog 桥接 | hertz + hertz-contrib/logger/* + logrus/zap/zerolog | go get github.com/oekit/logx/hertzlog@v0.1.0 |
./kitexlog/ |
github.com/oekit/logx/kitexlog |
Kitex klog→logx 桥接（自 oekit/kitex 迁入） | cloudwego/kitex | go get github.com/oekit/logx/kitexlog@v0.1.0 |
嵌套模块 tag 约定（Go modules 子路径 tag 标准）：根模块 tag vX.Y.Z；
嵌套模块 tag <子目录>/vX.Y.Z，如 hlog/v0.1.0、hertzlog/v0.1.0、kitexlog/v0.1.0。
这个仓库做什么
logx 是统一日志门面：业务代码面向 Logger 接口编程，底层实现（slog/std/hlog/
logrus/zap/zerolog）可整体替换。附带优雅关停管理器 shutdown。
解决的核心问题：
- 换库不改业务代码——接口分四层（CoreLogger → FormattedLogger → ContextLogger → Logger），按需依赖
- SDK 与业务解耦——SDK 包用
Delegating懒解析，消费方 main 里SetDefault后全局生效 - caller 归属准确——自动跳过内部帧，框架日志桥接不串位置
- trace_id 无感注入——
Ctx*方法自动从 context 提取
包结构
| 包 | 做什么 |
|---|---|
| 根包 | 接口 + std/slog 两内置后端 |
sink |
Sink/MultiSink/FileSink/RotatingSink 多目标输出 |
hlog |
Hertz hlog 后端适配 |
hertzlog |
hertz-contrib 的 logrus/zap/zerolog/slog 桥接 |
kitexlog |
Kitex klog→logx 桥接（自 oekit/kitex 迁入；携带 cloudwego/kitex 依赖，按需引入） |
shutdown |
优雅关停管理器：顺序 job、drain 超时、幂等 |
internal/logxcallertest |
caller 归属端到端测试探针 |
快速使用
import "github.com/oekit/logx"
// 业务服务：声明带 service 标识的 logger
var log = logx.WithService("my-service")
log.Info("order created", "order_id", 42, "amount", 99.5)
log.CtxError(ctx, "create failed", "err", err) // 自动带 trace_id；error 值渲染为错误文本
// main() 里可整体替换后端
logx.SetDefault(logx.NewSlogLogger("my-service"))
// 存量 slog 服务：注入自定义 Handler，保留既有日志格式
// logx.SetDefault(logx.NewSlogLogger("my-service", logx.WithHandler(myHandler)))
SDK 包的硬规则
// ✅ SDK 基础包必须用 Delegating 懒解析（消费方 SetDefault 后自动跟随）
var flowLog = logx.Delegating("workflow")
// ❌ 禁止：Default()/WithService 在 init 时求值，消费方后续设置失效
var bad = logx.WithService("hardcoded")
热路径级别守卫（Enabled）
级别过滤发生在后端 emit 内部——热路径打 Debug 时的昂贵参数求值（大对象
截断/序列化/拷贝）无法避免。用 logx.Enabled 提前守卫（std/slog/hlog
后端与 Delegating 包装器均支持；未实现的后端保守返回 true，不误吞日志）：
if !logx.Enabled(l, logx.LevelDebug) {
return // 跳过昂贵求值
}
l.Debug("transport response body", "body", truncateForLog(body, 2048))
要点
- kv 结构化风格是默认规范；
LOG_LEVEL环境变量统一控制所有后端 logx/sink的MultiSink/FileSink/RotatingSink支持同时写 stdout + 轮转文件、自定义 Loki/OTLP 后端- 根门面纯 stdlib；
sink/hlog/hertzlog/kitexlog各自为嵌套模块（见「模块布局」），lumberjack/框架依赖按需引入
矩阵总览（24 活跃模块，自动生成）
| 模块 | 内容 | 矩阵内依赖 |
|---|---|---|
| pkg | 微工具集 23 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap/singleflighttest/urlguard/cli/pack；v0.10.0 起 uidgen/validator 拆至 kitx）；errors（v0.12.0 起）New/As/Is/Unwrap 与 stdlib 同型透传——下游哨兵/As 判定单 import 即可，类型同一性红线可完整执行；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约（Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界）+ Checker；LocalCache 时钟可注入（LocalConfig.Now——TTL/NullTTL 全路径确定性测试，v0.13.0 起）；v0.16.0 起 LocalCache 可选形状——NoBackgroundSweep 关闭后台清扫 goroutine（嵌入式/短命进程，公开 Sweep 手动清扫口）、CloneOnRead 读命中返回副本（调用方可改写不污染缓存）、EvictPolicy 可选 LRU（默认 FIFO 不变）、GetEx 区分未命中与值为 nil（新增能力以可选接口 Sweeper/HitGetter 外置，不破坏其它后端）；v0.23.0 起补 Peek 非删除式读（可选接口 PeekGetter 外置——读到过期条目只算不命中、不删除它，stale-if-error 兜底需要那份过期真值留在表内；SingleFlightCache 包装 LocalCache 时曾因前置检查走 Get 惰性删除而静默废掉 StaleIfError，#72）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient / 抽对象与抽数组对称原语 ExtractObject·ExtractArray（v0.18.0 起——多段数组与散文含 '{' 的数组文本不再整段作废，取首个口径与对象面一致）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；stringx Masker（v0.16.0 起）正则脱敏——按形态分类打码（形态标签进掩码供审计读）+ 保留首尾各 ≤4 字符定位线索且不可复原（保留位封顶不随长度变化），规则表由调用方完全提供；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）；urlguard（v0.15.0 起）出站 SSRF 防护原语——CheckURL 字面量校验（私网/loopback/链路本地含云元数据 169.254.169.254/CGNAT/ULA/组播保留、.internal·.local·localhost 域名、scheme 白名单、IPv4-mapped IPv6 归一）+ DialFunc 拨号层预解析校验与实际 RemoteAddr 端点核对闭合 TOCTOU（Happy-Eyeballs 覆盖），构造态豁免 WithAllowPrivate/WithAllowCIDRs/WithAllowDomains，与 httpx WithDialFunc 一行组合（httpx#11）；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 体检一次列全问题并区分包损坏与版本不认识 | — |
| concurrency | 并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试；v0.8.0 起 singleflight DoShared 折叠可观测（Result.Waiters）、async panic 统一收编 typed *PanicError（errors.As 可辨、携带栈）+ 实例级 Runner panic 路由、retry DelayHint（服务端 Retry-After 建议优先）+ JitterRatio 比例抖动 + retry/httpx Retryable 可重试性判定；v0.9.0 起 breaker 显式三态状态机 closed/open/half-open——冷却（WithProbeTimeout 缺省 1m）期满首个放行即半开探测、探测成功关闸清窗/失败重开、失联超时自动回收 + AbandonGen 显式放弃，GenBreaker 代绑定（AllowGen/SuccessGen/FailureGen/AbandonGen：代仅在探测放行自增、陈旧代回报整体作废、开放期失败不后移冷却）；v0.10.0 起 WithCooldown 独立业务冷却期（缺省回落 probeTimeout）+ WithConsecutiveFailures 连续失败计数触发（与速率型并联，补低 QPS 信号，对齐 Envoy consecutive_5xx）；v0.11.0 起 ratelimit Lockout 防爆破锁（fail2ban 形态：滑窗失败计数→阈值锁定拒绝 LockDuration→成功 Reset 清零/到期自解，CheckLocked 返回剩余时长）；v0.12.0 起 retry/httpx RetryableWithHeaders（403 + Retry-After/X-RateLimit-Remaining 头感知可重试判定，HeaderSource 零依赖抽象）、syncx FanInLimit 受限并发扇出（固定 worker 防下游过载）+ FanInLimitCtx（v0.14.0，ctx 感知：ctx 已取消未启动项 fn 一次不调、剩余槽快速排空 Canceled、在飞项照常落槽）、ratelimit WithTokenClock 时钟注入；v0.13.0 起 breaker 熔断期收敛到探测级（forcePass 强制探活 + 冷却期满半开探测，其余拒绝——SRE 公式退役为 closed→open 触发器，WithConsecutiveFailures 触发后流量真停）+ State()/State 枚举可观测出口；v0.16.0 起 ratelimit NewKeyedLimiterByFunc[K]——factory func(K) Limiter 按 key 定配额（一个管理器按接口维度分档位，NewKeyedLimiterOf 零破坏随迁；未登记 key 拿 factory 兜底档的坑已在 doc 点名，#31）；v0.17.0 起 KeyedLimiter.Create 护栏内原子登记（表满先回收空闲与 Allow 同路、仍满拒绝计 OverCapHits、已存在不覆盖——热更走 Replace；解决 ByFunc factory 库锁内调用致消费方锁序倒置，#33）；v0.18.0 起 retry.DoValue 泛型伴生——带返回值的重试（DoValue[T](ctx, cfg, fn func(attempt int) (T, error))；Do 改为委托给 DoValue——退避序列/抖动/MaxDelay 封顶/DelayHint 优先/Retryable 门控/ctx 取消只有一份实现，杜绝「同一个仓里两份实现」；失败返回零值与最后一次错误） |
pkg |
| logx | 统一日志门面（多后端可替换 + caller 归属；Sink 已迁嵌套模块 logx/sink，根包纯 stdlib）；WithFilter 脱敏/丢弃包装（FilterKey 命中键替换 ***/FilterFunc 丢整条，子 logger 保持规则）、Slogger/SlogHandler 正向桥（三方 slog 直接消费 logx 生态）、TraceHandler 任意 slog.Handler 自动注入 trace_id、NewAuditLogger 审计留痕（级别锁 Info，不受 LOG_LEVEL 降级）、LevelEnabler 热路径提前判级、ParseLogLevel 返回 (Level, error) + ParseLogLevelOr 配错退默认（v0.7.0）；优雅关停正身在 core/lifecycle.Manager（logx/shutdown 仅余 Deprecated 别名）；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入 | core |
| core | 应用基建件——governance 治理 schema、config 配置加载（LoadBootstrap/LoadDotEnv/Get* 系、default/env/range/options tag 校验、OverlaySource 多源叠加热更、ApplyEnvOverlay env 优先 12-factor 形态）、transport 协议无关传输上下文（Transporter/Header/Server·Client ctx 存取，仅标准库）、chain 中间件链（Handler/Middleware/Chain/Recovery/Timeout，与 nns-endpoint.Endpoint 同形）、lifecycle 契约 + Manager 优雅关停（自 logx/shutdown 迁入，日志 *slog.Logger——core 不再依赖 logx）、network IP 工具、version；v0.9.0 起 config FieldSet 显式提供集合（yaml 显式 port:0 不再被 default/env 覆盖——LoadBootstrap 默认接线，免全量指针化）+ require tag（必须 yaml/env 提供，缺失列全并附 env 提示）+ v0.9.1 修 yaml:,inline 字段在 FieldSet 下漏标记（inline 叶子显式零值曾被 default 覆盖）；v0.9.2 env 卫生改纯静态（仅格式/重名，移除依赖进程环境的拼写冒烟检查——误报 PATH/HOME、漏无人设置的真拼错，core#8），命名一致性走 LintEnvNaming 诊断 / WithEnvNamingLint 可选 fail-closed / ignorederived="true" 豁免；v0.10.0 起 config 严格模式——LoadBootstrap[T](envFlag string, opts ...LoadOption) 传 config.WithStrict() 开启：未知键拒载（不再静默忽略），错误带嵌套路径 + 该层合法键清单 + 近似拼写建议（UnknownKeyError）；默认行为不变，严格模式显式开启；v0.11.0 起 config 加载入口按来源拆开——LoadFile（任意路径：CLI -config 路径、容器内固定挂载位）+ Unmarshal（字节源：API 下发 / 模板渲染 / 测试夹具），与 LoadBootstrap（etc/ 约定）共享同一条解码线，因此严格模式诊断面（嵌套路径 / 合法键清单 / 拼写建议）与来源无关；LoadBootstrap 行为与错误文案逐字不变 |
— |
| kitx | 标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail）+ hash（v0.2.0 起非密码学哈希助手 Md5Hex/Md5Bytes——缓存键/幂等键/短唯一 code，格式稳定承诺，pkg 2026-09-15 治理移除弱哈希后 kitx 侧收编 pkg#10），自 pkg v0.10.0 拆出 | pkg |
| metrics | Prometheus 门面 + 弹性指标族 | core |
| tracing | OpenTelemetry 追踪 + trace_id 真相源（v0.3.0 起 OTLP 双协议导出：gRPC 缺省 / HTTP，Config.Protocol + Headers，切换协议不丢传播器/指标/旧 provider 关闭） | logx |
| registry | 注册发现核心（provider 无关 SPI：Registrar/Discoverer/Subscriber/ConfigStore + 实例模型 + netutil）+ sdbridge + registrymocks——根仓零第三方依赖；Nacos 实现与 Nacos 配置源已拆成嵌套模块（v0.5.0 起：registry/nacosimpl、registry/nacos——nacos-sdk-go 重依赖隔离在此，实测单独引入即拖 63 个第三方模块，不隔离时只要 SPI 接口的消费方也会被连带拖入） | core |
| data | 数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；v0.15.0 起壳跟随源仓演进——cache 壳补 LocalCache 可选形状（EvictPolicy/Sweeper/HitGetter）、cachetest 壳补 5 个契约套件入口（套件 8 → 13 场景）、v0.18.0 起 cache 壳补 PeekGetter 别名 + cachetest 壳补 2 个 stale-if-error 契约入口（套件 13 → 15 场景）、timertask 壳的 Redis 形态随源仓 v0.2.0 迁至嵌套模块 timertask/redis（壳不再转发 RedisBackend/ShardManager，Redis 形态直接依赖该嵌套模块）；all/ 聚合模块已废弃 retract | concurrency、gormx、logx、pkg、redisx、timertask |
| gormx | SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名） | logx、pkg |
| redisx | Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock（Locker 同形可互换；Renew 手动续期（false=锁丢失，不进 Locker 接口保 etcdx 互换）+ WithAutoRenew 覆盖 TryLock 自动续期（v0.8.0 feat!：此前组合不续期）；Semaphore ZSET 槽位信号量（v0.8.0：Acquire 同 identifier 幂等刷新 + Lua 内原子清过期槽崩溃自愈、Renew 仅未过期槽可续、Cleanup 返条数、无 Redis 降级 fail-fast））、分布式限流 ratelimit（Lua 三态 + 故障本地兜底）；v0.9.0 起 distlock Lockout 分布式防爆破锁（Redis 侧 fail2ban：滑窗失败计数→阈值锁定 Penalty→Reset 清零，与 concurrency/ratelimit.Lockout 进程内孪生——多实例共享计数是存在理由；惩罚只按首次触发计算、nil client fail-fast 不降级，#6） | 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、logx、registry |
| httpx | HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传；loadbalance Selector 形态（RoundRobin/Random/Weighted/一致性哈希权重感知虚拟副本/p2c 自适应——EWMA 经 DoneFunc 回写建立、Err 计 1s 惩罚；WithFilter 按元数据过滤；v0.4.0 起 Balancer 全家族删除无兼容路径）；codec 注册制编解码器（json 内置 + form 表单，DoCodec 请求按 codec 序列化、响应按 Content-Type 反查回退请求 codec）；v0.6.0 起 net/http 桥接层 NewRoundTripper/StdClient——存量标准库外呼一行 Transport 接入熔断/重试/指标/链路（重试缺省关显式开、非 2xx 非错误、hop-by-hop 隔离，#8）；v0.8.0 起 SafeDialFunc/WithSafeDial 出站 SSRF 防护胶水（判定单源 pkg/urlguard v0.15.0：解析 IP 全量预检 + 实际 RemoteAddr 端点核对闭合重解析 TOCTOU、Happy-Eyeballs 覆盖，构造态豁免；v0.7.0 内置的独立 httpx/urlguard 实现收敛删除，#11） | concurrency、logx、metrics、pkg、registry、tracing |
| network | 轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具 | concurrency、logx、tracing |
| timertask | 分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，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（表达式复用 pkg/timex/cron 不另写一份；并发度/CatchUp 补跑/退出语义明确，FakeClock 假时钟驱动、触发点序列可确定性断言） | pkg |
| middleware | Hertz 标准中间件栈（模块根 mw，双层目录已收平）+ contrib 桥接 + hmw + SheddingMiddleware 自适应降载 + chainmw 子包（transport 感知框架无关中间件，基于 core/chain+transport：Recovery 带 panic 隔离上报钩子 WithRecoveryReporter、AccessLog skip+redact+自定义字段、MetadataPropagate——kitex 经 kitex/chainmw.ToKitex 复用同一实现，根包 Recovery/AccessLog 已薄壳化复用 chainmw 内核、下游 handler 可经 transport.FromServerContext 读协议无关传输信息）；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶）；v0.11.0 起 WithAccessLogSink 落库 sink（AccessRecord{Method,Path,Status,Latency,ClientIP,UserAgent,TraceID} 与日志同源、c 同传可读业务键、error/panic 只记 Warn 不影响主链路、SkipPaths 命中不触发）+ chainmw.WithSink 内核同构（kitex 随 ToKitex 获得）+ StackConfig.DisableResponseWrap 响应自管一键形态（TraceID→Recovery→AccessLog）与 AccessLogOptions 透传 + doc/README「适用边界」段（响应契约统一 vs handler 自管的推荐组合，#18）；v0.12.0 起 AccessLog panic 恢复点产出记录（AccessRecord.Panic 标记 + Err 摘要，Hertz status 按 Recovery 缺省 500）后按原值重抛——panic 请求不再零访问记录，sink/kitex 桥接同步留痕，#20；v0.13.0 起 accesslog 内建日志可关闭/改道（WithAccessLogSilent 只采不写、WithAccessLogLogger 注入宿主 logger 避免双写；静默下 skip/redact/sink/panic 记录照常），内核 chainmw.WithSilent 同构（kitex 随 ToKitex 获得），#38 | 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 池 | httpx、logx、metrics、nns、registry |
| bootstrap | 应用生命周期引导——New(WithServiceName/WithShutdownTimeout/WithBeforeServe) + Run(fn) + healthz；App.Ready/ReadyChan/IsReady 就绪门（幂等并发安全）——嵌套 bootstrap/nacos 自 v0.3.0 起 NNS 注册延迟到 Ready 之后（server 就绪 → userFn 触发 Ready → 才进注册中心）、关停序 nns 反注册先于 server 关闭；就绪门漏接时可观测——nacos 看门狗超时打 ERROR 点明「服务不会注册到注册中心」（WithReadyTimeout 可调）+ NNSComponent.RegistrationState() 暴露注册阶段（pending/registered/failed/skipped/shutdown）；Metrics/Tracing 在嵌套模块 bootstrap/obs | concurrency、core、logx |
| hertz | Hertz 运行时集成（模块根扁平化）——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）；RunServer 变参就绪门 WithOnReady（全部 HostPort TCP 探活可建连后回调，探活超时按启动失败优雅关机；缺省超时 5s 经 WithReadyProbeTimeout 调整——探活目标是 server 自动取到的全部 HostPort，无探活地址覆盖选项（kitex 侧才有 WithReadyAddr）），配合 bootstrap Ready 实现 NNS 延迟注册；transportx（hertz→core/transport 同构适配器）+ chainmw 桥接 | bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing |
| kitex | Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）；RunServer 变参就绪门（WithOnReady/WithReadyAddr/WithReadyProbeTimeout）+ chainmw.ToKitex（core/chain.Middleware → kitex 中间件，与 hertz 共享 middleware/chainmw 实现）+ transportx | bootstrap、concurrency、core、logx、metrics、nns、pkg、registry |
| workflow | 组合式流程编排——串行/并行/异步/条件分支 + Hook AOP | concurrency、logx |
| kitex-examples | Kitex echo 示例——client/server + IDL + 治理配置 | bootstrap、core、kitex、logx、tracing |
依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。
本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。
License
MIT — 见 LICENSE
Documentation
¶
Overview ¶
Package logx 提供统一的日志门面，支持多种底层实现。
所有 enjoydream 后端服务面向 Logger 接口编程，底层实现可灵活替换：
- std: 基于标准库 log（默认）
- hlog: 基于 Hertz hlog（需导入 logx/hlog 子包）
- slog: 基于标准库 log/slog，输出结构化 JSON
快速接入 ¶
// 业务 service 中创建带 service name 的 logger
var releaseLog = logx.WithService("release")
// 使用
releaseLog.Info("creating release", "keyword", keyword)
releaseLog.CtxError(ctx, "create failed", "err", err)
替换底层实现 ¶
// main.go 中调用（可选，默认使用 std）
logx.SetDefault(logx.NewStdLogger("my-service", logx.LevelDebug))
// 使用 hlog 后端（需导入子包）
import logxhlog "github.com/oekit/logx/hlog"
logx.SetDefault(logxhlog.NewHlogLogger("my-service"))
// 使用 slog 后端（推荐生产环境，输出结构化 JSON）
logx.UseSlog("my-service")
日志级别控制 ¶
通过 LOG_LEVEL 环境变量控制（影响所有后端），默认 INFO：
export LOG_LEVEL=DEBUG # DEBUG | INFO | WARN | ERROR
Trace ID 自动注入 ¶
使用 Ctx* 方法时，自动从 context 提取 trace_id（由 ekit/middleware.ResponseMiddleware 注入）。
SDK 包的包级 logger ¶
包级 var 在 init 时求值，先于 main() 中的 SetDefault。ekit 的 SDK 基础包不硬编码 service name（service name 属于消费方），包级 logger 统一用 Delegating 懒解析，组件名经 component 属性标识：
var log = logx.Delegating("mypkg")
上下文绑定（WithCtx） ¶
当不想在每次调用时都显式传入 ctx，可在请求入口绑定一次：
log := releaseLog.WithCtx(ctx) // 绑定后所有非 Ctx 方法自动携带 trace_id
log.Info("step1")
log.Info("step2", "keyword", kw)
绑定的 ctx 会随 WithService/WithAttrs/WithGroup 传递给子 logger。 显式的 Ctx* 方法仍以传入的 ctx 为准（优先于绑定 ctx）。
Index ¶
- func CtxDebug(ctx context.Context, msg string, keysAndValues ...any)
- func CtxDebugf(ctx context.Context, format string, args ...any)
- func CtxError(ctx context.Context, msg string, keysAndValues ...any)
- func CtxErrorf(ctx context.Context, format string, args ...any)
- func CtxInfo(ctx context.Context, msg string, keysAndValues ...any)
- func CtxInfof(ctx context.Context, format string, args ...any)
- func CtxWarn(ctx context.Context, msg string, keysAndValues ...any)
- func CtxWarnf(ctx context.Context, format string, args ...any)
- func Debug(msg string, keysAndValues ...any)
- func Debugf(format string, args ...any)
- func Enabled(logger Logger, level Level) bool
- func Error(msg string, keysAndValues ...any)
- func Errorf(format string, args ...any)
- func ExtractTrace(ctx context.Context) string
- func FormatAttrs(attrs ...Attr) string
- func FormatKeysAndValues(keysAndValues ...any) string
- func FormatWithTraceID(traceID, format string, args ...any) string
- func Info(msg string, keysAndValues ...any)
- func Infof(format string, args ...any)
- func IsHlogBacked(l Logger) bool
- func LevelString(level Level) string
- func SetDefault(l Logger)
- func SetTraceExtractor(fn func(context.Context) string)
- func SkipCallerFiles(files ...string)
- func SlogHandler(l Logger) slog.Handler
- func Slogger(l Logger) *slog.Logger
- func TraceHandler(inner slog.Handler, opts ...TraceHandlerOption) slog.Handler
- func UseSlog(service string, opts ...SlogOption)
- func Warn(msg string, keysAndValues ...any)
- func Warnf(format string, args ...any)
- type Attr
- type BaseLogger
- func (b *BaseLogger) EffectiveCtx() context.Context
- func (b *BaseLogger) Enabled(level Level) bool
- func (b *BaseLogger) MergeAttrs(attrs ...Attr) []Attr
- func (b *BaseLogger) Prefix() string
- func (b *BaseLogger) SetLevel(level Level)
- func (b *BaseLogger) ShouldLog(level Level) bool
- func (b *BaseLogger) Snapshot() BaseLogger
- type ContextLogger
- type CoreLogger
- type FilterOption
- type FormattedLogger
- type HlogBacked
- type Level
- type LevelEnabler
- type Logger
- func Default() Logger
- func Delegating(component string) Logger
- func NewAuditLogger(service string, opts ...SlogOption) Logger
- func NewSlogLogger(service string, opts ...SlogOption) Logger
- func NewStdLogger(service string, level ...Level) Logger
- func Nop() Logger
- func WithCtx(ctx context.Context) Logger
- func WithFilter(l Logger, opts ...FilterOption) Logger
- func WithService(name string) Logger
- type LoggerBuilder
- type SlogOption
- type TraceHandlerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Enabled ¶ added in v0.5.0
Enabled 判定 logger 是否会输出 level 级别日志。 优先走 logger 的 LevelEnabler；未实现时保守返回 true（与历史行为一致，绝不误吞日志）。
热路径守卫：在昂贵参数求值（大对象截断/序列化/拷贝）之前先判定， 被级别过滤掉的事件零成本跳过：
if !logx.Enabled(l, logx.LevelDebug) {
return // 跳过 truncateForLog(body) 等昂贵求值
}
l.Debug("transport response body", "body", truncateForLog(body, 2048))
func ExtractTrace ¶
ExtractTrace 从 context 提取 trace_id。 若未注册提取器或 context 中无 trace_id，返回空字符串。
func FormatKeysAndValues ¶
FormatKeysAndValues 将 key-value 对格式化为可读字符串。 输入: ["key1", val1, "key2", val2] 输出: "key1=val1 key2=val2"
func FormatWithTraceID ¶
FormatWithTraceID 格式化带 trace_id 的日志前缀。
func IsHlogBacked ¶
IsHlogBacked 检查 Logger 是否基于 hlog 实现。
将 hlog 后端的 Logger 传入 hertz.NewLogger 或 kitexlog.NewLogger 会形成 adapter → logx → hlog → adapter 的无限递归，导致栈溢出和进程挂死。 此函数供框架适配层做运行时防御。
func SetDefault ¶
func SetDefault(l Logger)
SetDefault 设置全局默认 logger 实现。 应在 main.go 中调用，且在使用任何 logx.Info 等函数之前。 传入 nil 是编程错误，直接 panic（否则后续所有日志调用都会 nil panic）。 并发安全，使用 atomic.Pointer 保护。
func SetTraceExtractor ¶
SetTraceExtractor 注册从 context 提取 trace_id 的函数。 应由 trace_id 的所有者（如 middleware/traceid）在包 init 时调用。 传入 nil 可清除已注册的提取器。
func SkipCallerFiles ¶
func SkipCallerFiles(files ...string)
SkipCallerFiles 将指定源文件标记为日志内部帧：slog 后端归属 caller 字段时 跳过这些文件中的调用方（重复注册同一文件自动去重，并发安全）。
用途：klog/hlog 桥接适配器位于 logx 之外，若不跳过，框架日志的 caller 会 错误归属到适配器文件（如 kitex/log.go）而非真实调用方——即 Kitex 官方日志 文档警告的"封装 klog 导致文件名行数不准确"问题。适配器应在构造函数中以 runtime.Caller(0) 注册自身文件；其他代码不应调用本函数。
func SlogHandler ¶ added in v0.6.0
SlogHandler 把 logx.Logger 暴露为 slog.Handler——与 slog.go 中 slog 后端（slog.Handler → logx 输出）方向相反的桥：让期望 *slog.Logger 的三方库直接消费 logx 生态（含 Delegating/过滤/子 logger 能力）。
记录经 logx 的 Ctx* 方法下发（保留 ctx 以便 trace_id 注入）；级别映射 slog ↔ logx 按名称对应（logx.Level 是 iota int，slog 是 -4..4，不可数值直转）； WithGroup 实现为键前缀（"group.key"）。
func TraceHandler ¶ added in v0.7.0
func TraceHandler(inner slog.Handler, opts ...TraceHandlerOption) slog.Handler
TraceHandler 给任意 slog.Handler 包一层：Handle 时从 ctx 提取 trace_id （经 ExtractTrace——SetTraceExtractor 注册的提取器，如 tracing/traceid） 注入为结构化字段（#12）。
边界（与消费方实测实现一致）：
- ctx 里没有 trace_id 时不注入（后台任务日志保持原样，不加 trace_id=""）；
- 记录里已有同名字段时不重复注入；
- WithAttrs/WithGroup 转发给 inner 并返回**包装后**的 handler——否则 logger.With(...) 之后 trace 注入会断。
用法（裸 slog 项目接 trace 串联）：
logger := slog.New(logx.TraceHandler(slog.NewJSONHandler(os.Stdout, nil)))
func UseSlog ¶
func UseSlog(service string, opts ...SlogOption)
UseSlog 是便捷函数：创建 slogLogger 并设为全局默认。 service 为服务名（输出为 service 字段）。
Types ¶
type BaseLogger ¶
type BaseLogger struct {
Service string
Level Level
Attrs []Attr
Ctx context.Context
Mu sync.Mutex
}
BaseLogger 包含所有 Logger 实现的公共字段和方法。 通过嵌入消除 hlog/std/slog 三个实现的重复代码。
子包（如 logx/hlog）可嵌入此结构体复用公共逻辑。
func NewBaseLogger ¶
func NewBaseLogger(service string, level Level) BaseLogger
NewBaseLogger 创建 BaseLogger 实例。
func (*BaseLogger) EffectiveCtx ¶
func (b *BaseLogger) EffectiveCtx() context.Context
EffectiveCtx 返回绑定 ctx（无绑定则 context.Background()）。
func (*BaseLogger) Enabled ¶ added in v0.5.0
func (b *BaseLogger) Enabled(level Level) bool
Enabled 判定给定级别当前是否会被输出——LevelEnabler 接口的 BaseLogger 实现。 嵌入 BaseLogger 的后端（std/slog/hlog 等）自动获得该方法。
func (*BaseLogger) MergeAttrs ¶
func (b *BaseLogger) MergeAttrs(attrs ...Attr) []Attr
MergeAttrs 合并已有属性和新属性，返回新的切片。
func (*BaseLogger) Prefix ¶
func (b *BaseLogger) Prefix() string
Prefix 返回 service 前缀（如 "[my-service]"）。
func (*BaseLogger) SetLevel ¶
func (b *BaseLogger) SetLevel(level Level)
SetLevel 设置该 logger 实例的日志级别。
func (*BaseLogger) ShouldLog ¶
func (b *BaseLogger) ShouldLog(level Level) bool
ShouldLog 检查给定级别是否应被记录。
func (*BaseLogger) Snapshot ¶
func (b *BaseLogger) Snapshot() BaseLogger
Snapshot 在锁内拷贝公共字段。clone/With* 派生路径必须经它取值： Level 可经 SetLevel 运行期变更，无锁快照读与写构成 data race （-race 下并发请求路径 + 动态调级可稳定检出）。导出供子包（logx/hlog） 嵌入使用。
type ContextLogger ¶
type ContextLogger interface {
CoreLogger
CtxDebug(ctx context.Context, msg string, keysAndValues ...any)
CtxInfo(ctx context.Context, msg string, keysAndValues ...any)
CtxWarn(ctx context.Context, msg string, keysAndValues ...any)
CtxError(ctx context.Context, msg string, keysAndValues ...any)
CtxDebugf(ctx context.Context, format string, args ...any)
CtxInfof(ctx context.Context, format string, args ...any)
CtxWarnf(ctx context.Context, format string, args ...any)
CtxErrorf(ctx context.Context, format string, args ...any)
}
ContextLogger 扩展 CoreLogger，增加带 Context 的方法（自动提取 trace_id）。
type CoreLogger ¶
type CoreLogger interface {
Debug(msg string, keysAndValues ...any)
Info(msg string, keysAndValues ...any)
Warn(msg string, keysAndValues ...any)
Error(msg string, keysAndValues ...any)
}
CoreLogger 是最小日志接口，仅包含结构化风格的四个级别方法。 大多数库/中间件只需依赖此接口。
type FilterOption ¶ added in v0.6.0
type FilterOption func(*filterConfig)
FilterOption 配置 WithFilter 的过滤行为。
func FilterFunc ¶ added in v0.6.0
func FilterFunc(fn func(msg string, kvs []any) bool) FilterOption
FilterFunc 命中即丢弃整条记录（在脱敏之后评估）。
func FilterKey ¶ added in v0.6.0
func FilterKey(keys ...string) FilterOption
FilterKey 把命中 key 的 kv 值替换为 "***"（精确匹配键名，含点路径字面量， 如 "user.password"）。
type FormattedLogger ¶
type FormattedLogger interface {
CoreLogger
Debugf(format string, args ...any)
Infof(format string, args ...any)
Warnf(format string, args ...any)
Errorf(format string, args ...any)
}
FormattedLogger 扩展 CoreLogger，增加 printf 风格方法。
type HlogBacked ¶
type HlogBacked interface {
IsHlogLogger()
}
HlogBacked 是 hlog 实现的标记接口。 hlog 子包的 hlogLogger 实现此接口，供 IsHlogBacked 运行时检查。
type Level ¶
type Level int
Level 日志级别
func ParseLogLevel ¶
ParseLogLevel 解析级别字符串（DEBUG/INFO/WARN/ERROR/OFF，大小写不敏感）。 未识别的值返回错误（#13：不再返回 *Level 指针——调用方漏判空会在 LOG_LEVEL 配错时得到远端解引用 panic）。空串按错误处理（区分「没配」）， 「配错就退回默认」的场景用 ParseLogLevelOr。
func ParseLogLevelOr ¶ added in v0.7.0
ParseLogLevelOr 解析级别字符串，未识别（含空串）时退回 def—— 「LOG_LEVEL 配错就退回默认」这一绝大多数场景的免判空形态。
type LevelEnabler ¶ added in v0.5.0
LevelEnabler 由支持级别判定的实现提供（LevelEnabler 接口）。 嵌入 BaseLogger 的后端（std/slog/hlog 等）自动实现；Delegating 包装器透传到 当前解析目标。消费方经类型断言可选使用——与生态「可选能力接口 + 类型断言」 哲学一致，不改动 CoreLogger 最小接口。
type Logger ¶
type Logger interface {
FormattedLogger
ContextLogger
LoggerBuilder
}
Logger 是完整的日志接口，组合了 CoreLogger、ContextLogger 和 LoggerBuilder。 所有服务面向此接口编程，底层实现可替换。
扩展点：
- WithAttrs / WithGroup：链式附加结构化字段，用于构建带上下文的子 logger
- SetLevel：动态调整日志级别
这使得 logx 既能配合传统 hlog（字符串拼接降级），也能对接 slog（真正结构化输出）。
func Delegating ¶
Delegating 返回一个懒解析的 Logger：每次调用时才解析当前 Default()， 因此消费方在 main() 中调用 SetDefault 后，本 logger 自动跟随新实现。
SDK 包的包级 logger 应使用本函数，而不是直接捕获 Default()：
// 错误：包级 var 在 init 时求值，永远绑定 init 时刻的默认 logger，
// 消费方随后的 SetDefault 对其无效。
var log = logx.Default()
// 正确：调用时才解析；component 以 component=<name> 属性标识来源子系统。
var log = logx.Delegating("mypkg")
component 为该包/子系统的归属名；传空串表示不打 component 属性。 service name 属于消费方，包归属统一用 component 属性标识。 WithService/WithAttrs/WithGroup/WithCtx 返回的子 logger 同样保持懒解析。
func NewAuditLogger ¶ added in v0.5.1
func NewAuditLogger(service string, opts ...SlogOption) Logger
NewAuditLogger 创建审计/合规/安全留痕类 Logger。
级别锁定在 LevelInfo（及更细），不受 LOG_LEVEL 环境变量降级；SetLevel 试图调到 WARN/ERROR 会被拒绝——审计事件不得被部署配置静默过滤。 需要更细粒度可用 SetLevel(LevelDebug)。
业务日志请用 NewSlogLogger；本构造仅用于「留痕不可丢」的路径 （登录、越权、配置变更、合规操作等）。
func NewSlogLogger ¶
func NewSlogLogger(service string, opts ...SlogOption) Logger
NewSlogLogger 创建基于 log/slog 的结构化 Logger。 service 会作为 "service" 字段输出到每条日志。
级别优先级：WithLevel 显式参数 > LOG_LEVEL 环境变量 > 默认 LevelInfo。 未注入 WithHandler 时输出 JSON 到 stdout；注入后由该 Handler 决定格式。
func NewStdLogger ¶
NewStdLogger 创建标准库实现的 Logger。 无 level 参数时默认 LevelInfo（与文档及 NewSlogLogger 一致； 原先误用 LevelDebug=iota 零值，见 #11）。 传入 level[0] 可显式指定。
func Nop ¶ added in v0.8.0
func Nop() Logger
Nop 返回一个**完全不输出**的 Logger。
用途：组件把 logger 作为**依赖注入**传进来（这是好设计），于是测试成了 唯一难受的地方——组件要一个 logger，测试里只能传真 logger ⇒ 日志直接刷到 stdout，把断言失败信息淹没在噪声里。此前想「不输出任何日志」只有两条路， 都不成立：
- 把级别设到 LevelError —— **仍会打 error**，且构造器 NewStdLogger(service) 要求编一个 service 名；
- 自己实现 logx.Logger —— 接口有 Debug/Info/Warn/Error + 四个 printf 形态 + 四个 Ctx* 形态 + With*/SetLevel 共 17 个方法，成本与收益不成比例。
Nop 同时实现 LevelEnabler（Enabled 恒 false）⇒ 经 logx.Enabled 的热路径 守卫会**跳过昂贵参数求值**（截断/序列化/拷贝），不只是不打印。
var l logx.Logger = logx.Nop()
l.Info("测试里这行不会出现在输出里")
要「保留结构化日志但本进程不落盘」用 LevelOff 档：
logx.NewStdLogger("svc", logx.LevelOff)
func WithCtx ¶
WithCtx 返回绑定了 context 的子 logger，等价于 Default().WithCtx(ctx)。 绑定后非 Ctx 方法自动携带 trace_id，参见 Logger.WithCtx。
func WithFilter ¶ added in v0.6.0
func WithFilter(l Logger, opts ...FilterOption) Logger
WithFilter 返回带脱敏/丢弃能力的子 logger。
过滤在 CoreLogger 四方法与 Ctx*/Fmt* 全路径生效：kv 值按 FilterKey 脱敏、 记录按 FilterFunc 丢弃。WithAttrs/WithGroup/WithCtx 派生的子 logger 保持 相同过滤规则。典型用法（防止敏感信息进日志）：
l := logx.WithFilter(logx.Default(), logx.FilterKey("password", "token"))
func WithService ¶
WithService 创建带 service name 的子 logger。 等价于 Default().WithService(name)。
type LoggerBuilder ¶
type LoggerBuilder interface {
WithCtx(ctx context.Context) Logger
WithService(name string) Logger
WithAttrs(attrs ...Attr) Logger
WithGroup(name string) Logger
SetLevel(level Level)
}
LoggerBuilder 提供子 logger 构建能力。
type SlogOption ¶ added in v0.3.0
type SlogOption func(*slogLogger)
SlogOption 是 NewSlogLogger 的函数选项。
func WithHandler ¶ added in v0.3.0
func WithHandler(h slog.Handler) SlogOption
WithHandler 注入消费方自有的 slog.Handler，日志格式与输出目标完全由该 Handler 决定（TextHandler / 文件轮转 / fan-out 等）。logx 侧仍负责级别过滤（见 BaseLogger.Level）与 service / trace_id / Attr / kv 等结构化字段注入。
未注入时保持默认行为：内置 JSON 序列化输出到 stdout。
func WithLevel ¶ added in v0.3.0
func WithLevel(level Level) SlogOption
WithLevel 显式指定日志级别，优先级高于 LOG_LEVEL 环境变量。 构造后仍可 SetLevel 运行期调级。
type TraceHandlerOption ¶ added in v0.7.0
type TraceHandlerOption func(*traceHandlerConfig)
TraceHandlerOption 配置 TraceHandler。
func WithTraceKey ¶ added in v0.7.0
func WithTraceKey(key string) TraceHandlerOption
WithTraceKey 自定义注入的 trace 字段名（默认 "trace_id"，与 tracing/traceid 的 ctx 键值约定一致）。
Source Files
Directories