kitex

README

kitex

Kitex RPC 生态——日志桥接、治理热更、生命周期、BizError 桥接、方法级指标与 OTel。

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

本仓库是 ekit（git.enjoye.top/enjoydream/ekit v0.34.0） 拆分出的独立 Go module，属于 oekit（Open Easy Kit）模块矩阵。

安装

go get github.com/oekit/kitex@v0.3.8

能做什么

• klog 桥接：框架日志 → logx，caller 归属已修正
• 治理热更：GovernanceConfig 监听 Nacos，retry/timeout/CB/limiter 全量同步
• BizError 桥接：对端业务异常自动转本地 BizError（504/503/403 码表）
• 可观测：NewServerTracingSuite（OTel）+ kitexprom 方法级指标
• panic 防线：handler panic 结构化日志 + 内部 goroutine 兜底
• kitexmeta：trace_id + 业务 metainfo 跨 RPC 透传（TTHeader）

使用示例

Server + Client 全家

svr := echo.NewServer(handler,
    server.WithSuite(ekitkitex.NewServerTracingSuite()),
    server.WithMiddleware(ekitkitex.NewPanicLogMiddleware()))
ekitkitex.RunServer(app, "echo-service", svr)

gov, _ := ekitkitex.NewGovernanceConfig(configCli, ekitkitex.WithGovernanceGroup("my-svc"))
cli := echo.NewClient("server-svc",
    client.WithSuite(ekitkitex.NewClientSuite("client-svc", "server-svc", gov,
        ekitkitex.WithRetry(), ekitkitex.WithRPCTimeout(), ekitkitex.WithCircuitBreaker())),
    ekitkitex.WithBizErrorBridge(),
    kitexmeta.PropagateClientOption(),
)

⚠️ 治理三条纪律：① 全量同步语义（删除配置段=回退默认）；② 勿混用代码级 WithFailureRetry；③ timeout_ms 必须 >0。

包清单

• `kitex/` — klog→logx 桥接、GovernanceConfig（Nacos 热更）、RunServer、WithBizErrorBridge、PanicLogMiddleware、NewServerTracingSuite
• `kitex/kitexmeta/` — trace_id + metainfo 跨 RPC 透传
• `registry/kitex/`、`nns/kitex/` — Kitex 注册发现适配器
• `observability/metrics/instrumentation/kitexprom/` — 方法级 RPC 指标
• `observability/tracing/instrumentation/kitexotel/` — OTel server/client suite
• `examples/` — kitex echo 示例；`internal/e2e/` — e2e 生成代码

Istio Proxyless 已迁 ekit-istio；echo 示例已迁 ekit-kitex-examples——本仓库生产代码不再依赖 bootstrap 链（go.mod 中 bootstrap require 仅供本仓测试用例引用，消费者构建图不含它）。

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

模块	内容	矩阵内依赖
pkg	微工具集 16 合 1（errors/validator/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/uidgen/cache）	—
concurrency	并发与流控原语（async/group/singleflight/progress/syncx/ratelimit/retry）	—
logx	统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停	—
core	应用基建件（governance 治理 schema / lifecycle 契约 / network IP 工具 / version）	—
istio	Istio Proxyless——Kitex xDS 动态熔断	—
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源	logx
registry	注册发现核心 + Nacos 实现 + 配置加载 + sdbridge	core、logx
data	缓存检查器（TTL/failTTL/inflight 合并）+ LocalCache	concurrency、logx
gorm	SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储	logx、pkg
redis	Redis 全家——客户端封装、缓存后端、分布式锁	concurrency、data、logx
httpx	HTTP 客户端 + 负载均衡——服务发现/熔断/重试/指标/OTel 透传	concurrency、core、logx、metrics、registry、tracing
network	轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具、Octopus 推送	concurrency、logx、tracing
timertask	分片定时任务（FNV-1a、心跳续约）	concurrency、logx
middleware	Hertz 自研标准中间件栈 + contrib 桥接 + hmw	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
handler	HTTP handler 层——通用 CRUD Handler、参数绑定、版本端点	concurrency、core、gorm、logx、metrics、middleware、pkg、registry、tracing
hertz	Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel	bootstrap、concurrency、core、logx、metrics、nns、registry、tracing
kitex	Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry、tracing
workflow	组合式流程编排——串行/并行/异步/条件分支 + Hook AOP	concurrency、logx
kitex-examples	Kitex echo 示例——client/server + IDL + 治理配置	bootstrap、concurrency、core、kitex、logx、metrics、nns、registry、tracing

当前仓库依赖

详见上方矩阵表中本仓库行。

与 ekit 单体仓库的关系

• 代码与 ekit v0.34.0 等价，module 路径 git.enjoye.top/enjoydream/ekit/... → github.com/oekit/kitex/...
• 各子仓库独立发版（SemVer）；开发规范沿用 ekit AGENTS.md 约定

License

见 LICENSE