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.4.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.4.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")
要点
- kv 结构化风格是默认规范；
LOG_LEVEL环境变量统一控制所有后端 logx/sink的MultiSink/FileSink/RotatingSink支持同时写 stdout + 轮转文件、自定义 Loki/OTLP 后端- 根门面纯 stdlib；
sink/hlog/hertzlog/kitexlog各自为嵌套模块（见「模块布局」），lumberjack/框架依赖按需引入
矩阵总览（21 活跃模块，自动生成）
| 模块 | 内容 | 矩阵内依赖 |
|---|---|---|
| pkg | 微工具集 21 合 1（errors/bloomx/contextx/collectionx/validator/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/uidgen/cache/bufiox/strmap）；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约 + Checker；collectionx（v0.5.0 起）泛型容器 Set/Ring/Queue/SafeMap；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩 | — |
| concurrency | 并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮 | — |
| logx | 统一日志门面（多后端可替换 + caller 归属）+ 优雅关停；sink/hlog/hertzlog/kitexlog 为嵌套模块按需引入 | — |
| core | 应用基建件（governance 治理 schema / config 配置加载 + default/env/range/options tag 校验 / lifecycle 契约 / network IP 工具 / version） | logx |
| 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 |
| 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 |
| 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、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
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 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 UseSlog(service string, opts ...SlogOption)
- func Warn(msg string, keysAndValues ...any)
- func Warnf(format string, args ...any)
- type Attr
- type BaseLogger
- type ContextLogger
- type CoreLogger
- type FormattedLogger
- type HlogBacked
- type Level
- type Logger
- type LoggerBuilder
- type SlogOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 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) 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 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 解析 LOG_LEVEL 环境变量值为 Level 指针。 未识别的值返回 nil。
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 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。 默认级别为 LevelDebug。
func WithCtx ¶
WithCtx 返回绑定了 context 的子 logger，等价于 Default().WithCtx(ctx)。 绑定后非 Ctx 方法自动携带 trace_id，参见 Logger.WithCtx。
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 运行期调级。
Source Files
Directories