kitex

README

kitex

Kitex RPC 生态——治理热更/BizError 桥接/指标与追踪

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

安装

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

这个仓库做什么

kitex 是 Kitex RPC 生态：日志桥接、治理配置热更新、生命周期接入、业务异常 桥接、方法级指标与追踪——Kitex 生产化的全部拼图。

组成

包	做什么
kitex	GovernanceConfig（Nacos 热更 retry/timeout/CB/limiter）、RunServer、WithBizErrorBridge（对端异常→本地 BizError）、PanicLogMiddleware、NewServerTracingSuite；klog→logx 桥已迁 logx/kitexlog（kitex.NewLogger 保留 Deprecated 别名）
kitex/kitexmeta	trace_id + 业务 metainfo 跨 RPC 透传（TTHeader）
registry/kitex	Kitex 注册发现适配器
nns/kitex	NNS 适配器（服务发现 + 注册）
…/kitexprom	方法级 RPC Prometheus 指标
…/kitexotel	OTel server/client suite
examples 指引	可运行示例在 kitex-examples

快速使用

import (
    ekitkitex "github.com/oekit/kitex/kitex"
    logxkitexlog "github.com/oekit/logx/kitexlog"
)

// 日志桥接推荐直接用 logx/kitexlog（ekitkitex.NewLogger 已 Deprecated，别名委托实现）
klog.SetLogger(logxkitexlog.NewLogger(logx.NewSlogLogger("my-rpc")))

gov, _ := ekitkitex.NewGovernanceConfig(configCli,
    ekitkitex.WithGovernanceTemplate("my-service.governance"))
suite := ekitkitex.NewClientSuite("client-svc", "server-svc", gov,
    ekitkitex.WithRetry(), ekitkitex.WithRPCTimeout(), ekitkitex.WithCircuitBreaker())
cli, _ := echo.NewClient("server-svc",
    client.WithSuite(suite),
    ekitkitex.WithBizErrorBridge(), // 对端业务异常 → 本地 BizError
)
svr := echo.NewServer(handler, server.WithSuite(ekitkitex.NewServerTracingSuite()))
ekitkitex.RunServer(app, "echo-service", svr)

三条纪律

1. 治理策略是全量同步：配置删除的 method 回退 Kitex 默认值
2. 不要混用代码级 client.WithFailureRetry——混用会使容器忽略全部远端配置
3. timeout_ms 必须 >0（0 走无超时 fast path，清超时用删除配置段表达）

边界

• 出站 HTTP 的熔断重试在 nns-endpoint
• Istio Proxyless 在 istio

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

模块	内容	矩阵内依赖
pkg	微工具集 18 合 1（errors/validator/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/uidgen/cache/bufiox/strmap）	—
concurrency	并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）	—
logx	统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停	—
core	应用基建件（governance 治理 schema / config 配置加载 / lifecycle 契约 / network IP 工具 / version）	logx
istio	Istio Proxyless——Kitex xDS 动态熔断	—
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源	logx
registry	注册发现核心 + Nacos 实现 + 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
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