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.0
这个仓库做什么
为 CloudWeGo Hertz 提供生产级运行时集成：hlog→logx 日志桥接（caller 归属已修正）、
RunServer 接 bootstrap 优雅退出（AddShutdownHook 支持关停前刷数据）、server.WithExitWaitTime
排空调优；子包 health（K8s 探针）、sse（官方 protocol/sse 封装 + LastEventID 续传）、
metrics（Prometheus 暴露）、render/adaptor（net/http 互转）、governance/hertz
（动态限流/超时中间件）、registry/hertz 与 nns/hertz（注册发现）、observability
（hertzotel/hertztracer 链路）、crudh/validatorh/versionh（泛型 CRUD Handler、
Hertz 参数绑定校验、版本端点——原独立 handler 微库已收编，「一个模型暴露 REST API」
三行直达）。
快速使用
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 生命周期，优雅退出
矩阵总览（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 + LocalCache/SingleFlightCache + cachetest 契约 + Checker；collectionx（v0.5.0 起）泛型容器 Set/Ring/Queue/SafeMap | — |
| concurrency | 并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮 | — |
| logx | 统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停；桥接子包 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 与各子仓；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 抽象、连接与流工具、Octopus 推送 | 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 |
Directories
¶
| Path | Synopsis |
|---|---|
|
Package crudh 提供基于 Hertz 的通用 CRUD HTTP Handler。
|
Package crudh 提供基于 Hertz 的通用 CRUD HTTP Handler。 |
|
governance
|
|
|
hertz
Package govhertz 把 governance.Store 消费成 hertz server 治理中间件 (audit 5.2 阶段 1:hertz 侧治理)。
|
Package govhertz 把 governance.Store 消费成 hertz server 治理中间件 (audit 5.2 阶段 1:hertz 侧治理)。 |
|
Package hertz 为 Hertz HTTP 框架提供 ekit 生态集成。
|
Package hertz 为 Hertz HTTP 框架提供 ekit 生态集成。 |
|
adaptor
Package adaptor 提供 hertz-contrib/adaptor 常用 helper,让 ekit 业务 用 1 行代码把 net/http 生态(http.FileServer / embed.FS / gorilla/websocket)接入 hertz。
|
Package adaptor 提供 hertz-contrib/adaptor 常用 helper,让 ekit 业务 用 1 行代码把 net/http 生态(http.FileServer / embed.FS / gorilla/websocket)接入 hertz。 |
|
health
Package health 提供 Hertz 健康检查端点。
|
Package health 提供 Hertz 健康检查端点。 |
|
metrics
Package metrics 提供 Hertz Prometheus 指标端点。
|
Package metrics 提供 Hertz Prometheus 指标端点。 |
|
render
Package render 提供业务特定的 hertz Render interface 实现,与 hertz 官方 render 子包(https://www.cloudwego.io/zh/docs/hertz/tutorials/basic-feature/render/) 风格一致。
|
Package render 提供业务特定的 hertz Render interface 实现,与 hertz 官方 render 子包(https://www.cloudwego.io/zh/docs/hertz/tutorials/basic-feature/render/) 风格一致。 |
|
sse
Package sse 提供 Hertz SSE（Server-Sent Events）封装。
|
Package sse 提供 Hertz SSE（Server-Sent Events）封装。 |
|
nns
|
|
|
hertz
Package hertz 提供 nns 与 CloudWeGo Hertz 集成的适配器。
|
Package hertz 提供 nns 与 CloudWeGo Hertz 集成的适配器。 |
|
observability
|
|
|
tracing/instrumentation/hertzotel
Package hertzotel 提供 Hertz HTTP client/server 的 OpenTelemetry tracing 集成 helper,桥接 hertz-contrib/obs-opentelemetry/tracing。
|
Package hertzotel 提供 Hertz HTTP client/server 的 OpenTelemetry tracing 集成 helper,桥接 hertz-contrib/obs-opentelemetry/tracing。 |
|
tracing/instrumentation/hertztracer
Package hertztracer 提供 Hertz HTTP client/server 的 OpenTracing tracing 集成 helper,桥接 hertz-contrib/tracer。
|
Package hertztracer 提供 Hertz HTTP client/server 的 OpenTracing tracing 集成 helper,桥接 hertz-contrib/tracer。 |
|
registry
|
|
|
hertz
Package hertz 提供 ekit registry 抽象到 CloudWeGo Hertz 框架的适配器。
|
Package hertz 提供 ekit registry 抽象到 CloudWeGo Hertz 框架的适配器。 |
|
Package validatorh 提供基于 Hertz 的请求参数绑定与验证。
|
Package validatorh 提供基于 Hertz 的请求参数绑定与验证。 |
|
Package versionh 提供版本信息的 HTTP Handler。
|
Package versionh 提供版本信息的 HTTP Handler。 |
Click to show internal directories.
Click to hide internal directories.