hertz

README

hertz

Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel

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

安装

go get github.com/oekit/hertz@v0.5.3

这个仓库做什么

为 CloudWeGo Hertz 提供生产级运行时集成：hlog→logx 日志桥接、RunServer 接 bootstrap 优雅退出（AddShutdownHook 支持关停前刷数据）、server.WithExitWaitTime 排空调优。 本仓自 v0.5.1 起算：历史与旧版本号已全部清空，包布局收成「模块根 + 一级子包」。

组成

包	import 路径	做什么
hertz（模块根包）	github.com/oekit/hertz	RunServer 生命周期、hlog→logx 桥接、Shutdown Hook
health	github.com/oekit/hertz/health	K8s 探针（/ping、/health、/buildVersion）；Degraded 软依赖降级；空路径跳过注册；Redis checker 在 health/redischeck（核心包零 go-redis）
sse	github.com/oekit/hertz/sse	Server-Sent Events 封装（官方 protocol/sse + LastEventID 续传）
metrics	github.com/oekit/hertz/metrics	Prometheus /metrics 暴露（gzip/OpenMetrics 协商）
render / adaptor	github.com/oekit/hertz/render 等	业务 Render 实现、net/http 互转
crudh / validatorh / versionh	github.com/oekit/hertz/crudh 等	泛型 CRUD Handler、参数绑定校验、版本端点
governance	github.com/oekit/hertz/governance	动态限流/超时中间件（包名 govhertz）
registry / nns	github.com/oekit/hertz/registry 等	ekit registry / NNS → Hertz 注册发现适配
hertzotel / hertztracer	github.com/oekit/hertz/hertzotel 等	OpenTelemetry / OpenTracing 链路

快速使用

import (
    ekithertz "github.com/oekit/hertz"
    "github.com/cloudwego/hertz/pkg/app/server"
)

h := server.New(server.WithHostPorts(":8080"))
h.GET("/ping", func(ctx context.Context, c *app.RequestContext) { c.String(200, "pong") })
ekithertz.RunServer(app, "my-http", h) // 接 bootstrap 生命周期，优雅退出

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

模块	内容	矩阵内依赖
pkg	微工具集 21 合 1（errors/bloomx/contextx/container/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；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）	—
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、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

Documentation

Overview

Package hertz 为 Hertz HTTP 框架提供 ekit 生态集成。

覆盖以下能力（对称 kitex 包，治理配置热更新不适用 Hertz）：

• 日志桥接：将 Hertz 框架内部日志通过 hlog → logx 归一，自动携带 trace_id 和结构化字段
• 生命周期管理：RunServer 将 Hertz server 注册到 bootstrap，一行完成 shutdown + 后台 Run； server 启动失败（如端口占用）时自动触发 RequestShutdown 优雅关机，避免进程"假活"

子包（推荐新代码直接使用子包）：

• health: 健康检查端点（/ping、/health、/buildVersion）+ DB checker （Redis checker 在子包 health/redischeck）
• metrics: Prometheus /metrics 端点（gzip/OpenMetrics 协商透传）
• sse: Server-Sent Events 流式推送（官方 protocol/sse 的并发安全封装）
• OTel tracing 见 hertzotel / hertztracer（server/client 全量能力）
• trace_id 中间件见 middleware/hmw（FromRequestContext + Middleware）

完整生命周期示例

hlog.SetSilentMode(true) // 静默客户端不规范行为导致的读头错误日志（推荐生产开启）
hlog.SetLogger(hertz.NewLogger(logx.NewSlogLogger("my-http")))

b, _ := bootstrap.New(bootstrap.WithServiceName("svc")) // + nacos/obs WithXxx 按需注入
b.Run(func(app *bootstrap.App) error {
    tracing := hertzotel.NewServerTracing()
    h := server.New(
        server.WithHostPorts(":8080"),
        server.WithExitWaitTime(10*time.Second), // 排空等待上限，默认 5s
        tracing.Option,
    )
    h.Use(tracing.Middleware)
    h.Use(mw.DefaultMiddleware(mw.StackConfig{SkipPaths: []string{"/healthz"}})...)

    // 健康检查 + 指标（在 RunServer 之前注册，确保端点随 server 一起就绪）
    // Redis 检查器在子包 redischeck；软依赖用 health.Degraded(err) 降级
    health.RegisterHealthRoutes(h, health.WithCheckers(
        redischeck.NamedRedisChecker("redis", rdb),
        health.NamedDBChecker("mysql", sqlDB),
    ))
    hmetrics.InitAndRegister("my-http", h)

    hertz.RunServer(app, "hertz", h)
    <-app.Context().Done()
    return nil
})

信号行为（对照官方 graceful-shutdown 文档）

Hertz 内置信号处理（h.Run() 内的 waitSignal）：

• v0.9.6+：SIGTERM/SIGINT/SIGHUP 均触发优雅退出（h.Shutdown）
• < v0.9.6：SIGTERM 立即退出；SIGINT/SIGHUP 触发优雅退出

ekit bootstrap 同时监听 SIGINT/SIGTERM，与 Hertz 内置处理并发触发。 RunServer 内部已容忍双路 Shutdown 竞态（hertz 返回 "engine is not running" 视为成功）， 用户无需额外处理。

优雅退出流程（Hertz 内部，对照官方文档）：

1. engine 状态设为 closed
2. 并发触发 OnShutdown 钩子（h.Engine.OnShutdown = append(h.Engine.OnShutdown, fn)）
3. 从注册中心注销
4. 关闭网络库信号监听
5. 进行中请求响应附带 Connection:Close 头
6. netpoll：每秒检查直到 active conn = 0；go net：关闭监听
7. 等待 ExitWaitTime（默认 5s）到期后退出

退出时间控制

server.WithExitWaitTime(d) — 排空等待上限（默认 5s），是官方文档的核心旋钮。 有长耗时请求时调大；与 bootstrap 的 ShutdownTimeout（单资源关闭预算）配合： bootstrap 关闭回调传入的 ctx 有 ShutdownTimeout 截断，Hertz 内部再以 ExitWaitTime 截断， 实际排空上限 = min(ShutdownTimeout, ExitWaitTime)。 保持 ExitWaitTime <= ShutdownTimeout 以确保排空不被 bootstrap 兜底截断。

与 kitex 包的差异

Hertz 使用中间件链（h.Use）而非 Suite 模式，因此不提供 ClientSuite/ServerSuite。 治理配置热更新（retry/rpc_timeout/circuit_breaker/limiter）是 Kitex RPC 框架级概念， Hertz 的对应能力由 mw.RateLimitMiddleware 等静态中间件覆盖，无需动态治理。

Index

• func AddShutdownHook(h *server.Hertz, fn func(ctx context.Context) error)
• func NewLogger(logger logx.Logger) hlog.FullLogger
• func RunServer(app lifecycle.App, name string, h *server.Hertz)

Functions

func AddShutdownHook

func AddShutdownHook(h *server.Hertz, fn func(ctx context.Context) error)

AddShutdownHook 注册 Hertz 优雅退出钩子函数,等价于官方教程推荐的 h.Engine.OnShutdown = append(...) 写法,但放在 ekit hertz 包内提供 helper,避免用户在 bootstrap.Run userFn 中手拿 engine。

hertz 官方 OnShutdown 签名 func(ctx context.Context) 不接受 error, 本 helper 接受 func(ctx) error 并把 fn 返回的 error 通过 bootstrapLog 记录为 Warn 日志(hertz 调用栈会忽略 error,日志是唯一能见的位置)。

fn 在 RunServer 调用前后都可以注册(只是 append 切片,无副作用), 多个 hook 按 append 顺序执行(官方文档明确)。

⚠️ 与 RunServer 的关系:

ekit hertz.RunServer 内部用 lifecycle.App.AddResource 注册 h.Shutdown,
OnShutdown hook 在 Shutdown 流程早期被调用(在 deregister 之前),
适合做"关停前刷数据/通知外部"类工作。
如果 hook 是"释放外部资源"(如关 DB),推荐直接用 lifecycle.App.AddResource
+ 显式 closer,语义更清晰、错误能上报 shutdown.Manager。

官方依据:https://www.cloudwego.io/zh/docs/hertz/tutorials/basic-feature/hooks/

"h.Engine.OnShutdown = append(h.Engine.OnShutdown, shutDownFunc)"

用法:

h := server.New(...)
hertz.AddShutdownHook(h, func(ctx context.Context) error {
    // 关闭前的最后操作
    return flushLastBatchToRemote(ctx)
})
hertz.RunServer(app, "my-svc", h)

func NewLogger

func NewLogger(logger logx.Logger) hlog.FullLogger

NewLogger 将 ekit logx.Logger 适配为 Hertz hlog.FullLogger。

调用后 Hertz 框架内部日志（网络层、连接异常、路由警告等）将通过 logx 输出， 自动携带 trace_id、service name 和结构化字段。 本函数会把自身所在文件注册为 logx 内部帧（logx.SkipCallerFiles）， 使经由适配器的框架日志 caller 归属真实调用方；副作用仅此一项。

使用方式（必须传 slog 实例，不可传 hlog 后端的 Logger）：

hlog.SetLogger(hertz.NewLogger(logx.NewSlogLogger("my-http")))

⚠️ 禁止传入 hlog 后端的 Logger（如 logx.WithService(...)），否则会形成 adapter → logx → hlog → adapter 的无限递归，导致栈溢出和进程挂死。 此函数会在检测到 hlog 后端时 panic 以防止生产环境不可控故障。

func RunServer

func RunServer(app lifecycle.App, name string, h *server.Hertz)

RunServer 将 Hertz Server 注册到 ekit 生命周期管理（bootstrap.App 满足 lifecycle.App 接口；transport 适配层只依赖 lifecycle 契约，不依赖 bootstrap）。

该函数会：

1. 通过 app.AddResource 注册 h.Shutdown 作为关闭回调（优雅关闭时自动调用）。
2. 通过 app.GoBackground 在后台启动 h.Run()（阻塞直到 server 退出）。
3. h.Run() 返回 error 或 panic（netpoll 传输层在监听失败如端口占用时 直接 panic 而非返回 error）时调用 app.RequestShutdown() 触发优雅关机， 避免进程无服务地"假活"。

关闭语义（对照官方 graceful-shutdown 文档）

信号路径：SIGTERM/SIGINT（SIGHUP 未被忽略时含之）由 h.Run() 内置 waitSignal 处理，直接触发 h.Shutdown(context.Background())，排空上限为 server.WithExitWaitTime（**默认 5s** — hertz 官方默认;未配时 netpoll 1s ticker 检 active conn / go net 立即关 listen）。同一信号也会让 bootstrap 走本函数注册的 关闭回调，第二次 Shutdown 因 engine 状态已非 running 返回 "engine is not running"——这是双路关闭的良性竞争而非故障，此处按成功处理， 避免每次信号关机都产生假错误日志。

程序化路径（userFn 返回 / RequestShutdown）：走本函数注册的关闭回调， ctx 为 bootstrap 单资源预算（shutdown.New 的 defaultTimeout）；hertz 内部 再以 ExitWaitTime 截断，实际排空上限 = min(两者)。需要更长排空时间时调大 server.WithExitWaitTime，并保持其小于 bootstrap 单资源预算。

⚠️ **推荐显式设置 server.WithExitWaitTime**(尤其长耗时 RPC):保持其小于 bootstrap 单资源关闭预算(shutdown.New 的 defaultTimeout),避免排空被 bootstrap 兜底截断。hertz Shutdown 接受传入 ctx 但内部还会以 ExitWaitTime 截断,二者取 min。

使用方式（在 bootstrap.Run 的 userFn 内，对称 kitex.RunServer）：

b, _ := bootstrap.New(bootstrap.WithServiceName("svc")) // + nacos/obs WithXxx 按需注入
b.Run(func(app *bootstrap.App) error {
    h := server.New(server.WithHostPorts(":8080"))
    h.Use(mw.DefaultMiddleware(mw.StackConfig{})...)
    hertz.RunServer(app, "hertz", h)
    <-app.Context().Done() // 阻塞直到收到 SIGINT/SIGTERM
    return nil
})

⚠️ userFn 返回 = 主动关机。若 RunServer 后直接 return nil， bootstrap.Run 会立即执行 shutdown 序列，服务器启动即退出。