kitex

README

kitex

Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel

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

安装

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

这个仓库做什么

为 CloudWeGo Kitex 提供生产级运行时集成：klog→logx 日志桥接（caller 归属已修正）、 NewGovernanceConfig 治理配置热更（retry/rpc_timeout/circuit_breaker/limiter，全量同步语义）、 ClientSuite/ServerSuite 一键装配、RunServer 接 bootstrap 优雅退出、WithBizErrorBridge 对端业务异常→ekit BizError 桥接、NewPanicLogMiddleware/SetDefaultPanicHandler panic 收编； 子包 nns/kitex 与 registry/kitex（注册发现）、observability（kitexprom 方法级指标）、 kitexmeta（trace_id/业务元信息跨 RPC 透传）；嵌套模块（独立发版、依赖隔离）： observability/tracing/instrumentation/kitexotel（OTel 链路接入）、istio（xDS 动态熔断， Proxyless 对接 Istio，原独立微库已收编）。

⚠️ v0.7.0 起 kitexotel 与 istio 拆为嵌套模块：obs-opentelemetry / xds 会把 apache/thrift 抬到 v0.16.0，留在根模块会打断下游按 thrift 0.13 生成的 Thrift 代码 （#37）。需要它们时单独 go get（import 路径不变）：

go get github.com/oekit/kitex/observability/tracing/instrumentation/kitexotel@latest  # OTel 链路
go get github.com/oekit/kitex/istio@latest                                           # xDS 动态熔断

⚠️ 嵌套模块版本与根模块锁步（v0.7.0 起，#44）：kitexotel 与 istio 的版本号 与根模块同号（根 v0.7.0 ⇒ 嵌套 v0.7.0）。原因：嵌套模块的版本号若撞上根模块 改名前（旧模块路径，原文见 #44）的历史版本号（v0.1.0–v0.4.0）， Go 解析嵌套模块路径时会按同一版本号探测父模块前缀候选，命中代理上仍缓存旧 模块路径的 .mod 条目即硬失败（module declares its path as ... but was required as ...）⇒ 消费方首次 go get 间歇性失败。 ⇒ 请用 v0.7.0（或更新的同号版本），不要用早期的 v0.1.0。

快速使用

import (
    ekitkitex "github.com/oekit/kitex"
    kitexotel "github.com/oekit/kitex/observability/tracing/instrumentation/kitexotel"
    "github.com/cloudwego/kitex/server"
)

svr := echo.NewServer(handler,
    server.WithSuite(kitexotel.NewServerTracingSuite()),
)
ekitkitex.RunServer(app, "kitex-echo", svr) // 接 bootstrap 生命周期，优雅退出

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

模块	内容	矩阵内依赖
pkg	微工具集 24 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/shellx/timex/cache/bufiox/strmap/singleflighttest/urlguard/cli/pack；v0.10.0 起 uidgen/validator 拆至 kitx）；errors（v0.12.0 起）New/As/Is/Unwrap 与 stdlib 同型透传——下游哨兵/As 判定单 import 即可，类型同一性红线可完整执行；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约（Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界）+ Checker；LocalCache 时钟可注入（LocalConfig.Now——TTL/NullTTL 全路径确定性测试，v0.13.0 起）；v0.16.0 起 LocalCache 可选形状——NoBackgroundSweep 关闭后台清扫 goroutine（嵌入式/短命进程，公开 Sweep 手动清扫口）、CloneOnRead 读命中返回副本（调用方可改写不污染缓存）、EvictPolicy 可选 LRU（默认 FIFO 不变）、GetEx 区分未命中与值为 nil（新增能力以可选接口 Sweeper/HitGetter 外置，不破坏其它后端）；v0.23.0 起补 Peek 非删除式读（可选接口 PeekGetter 外置——读到过期条目只算不命中、不删除它，stale-if-error 兜底需要那份过期真值留在表内；SingleFlightCache 包装 LocalCache 时曾因前置检查走 Get 惰性删除而静默废掉 StaleIfError，#72）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient / 抽对象与抽数组对称原语 ExtractObject·ExtractArray（v0.18.0 起——多段数组与散文含 '{' 的数组文本不再整段作废，取首个口径与对象面一致）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；stringx Masker（v0.16.0 起）正则脱敏——按形态分类打码（形态标签进掩码供审计读）+ 保留首尾各 ≤4 字符定位线索且不可复原（保留位封顶不随长度变化），规则表由调用方完全提供；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）；urlguard（v0.15.0 起）出站 SSRF 防护原语——CheckURL 字面量校验（私网/loopback/链路本地含云元数据 169.254.169.254/CGNAT/ULA/组播保留、.internal·.local·localhost 域名、scheme 白名单、IPv4-mapped IPv6 归一）+ DialFunc 拨号层预解析校验与实际 RemoteAddr 端点核对闭合 TOCTOU（Happy-Eyeballs 覆盖），构造态豁免 WithAllowPrivate/WithAllowCIDRs/WithAllowDomains，与 httpx WithDialFunc 一行组合（httpx#11）；cli（v0.16.0 起）框架无关可单测的子命令分发原语——App/Command + 退出码 0/1/2 写死在包里、usage 按 Summary 自动生成、不读 os.Args 不调 os.Exit（输出流全由调用方给）；pack（v0.16.0 起）迁移包容器原语——zip + manifest（格式版本/条数/每文件 SHA-256）+ JSONL 流式读写 + Inspect 体检一次列全问题并区分包损坏与版本不认识	—
concurrency	并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 / batch 攒批执行器（满条数/满字节/窗口去重）/ timewheel 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试；v0.8.0 起 singleflight DoShared 折叠可观测（Result.Waiters）、async panic 统一收编 typed *PanicError（errors.As 可辨、携带栈）+ 实例级 Runner panic 路由、retry DelayHint（服务端 Retry-After 建议优先）+ JitterRatio 比例抖动 + retry/httpx Retryable 可重试性判定；v0.9.0 起 breaker 显式三态状态机 closed/open/half-open——冷却（WithProbeTimeout 缺省 1m）期满首个放行即半开探测、探测成功关闸清窗/失败重开、失联超时自动回收 + AbandonGen 显式放弃，GenBreaker 代绑定（AllowGen/SuccessGen/FailureGen/AbandonGen：代仅在探测放行自增、陈旧代回报整体作废、开放期失败不后移冷却）；v0.10.0 起 WithCooldown 独立业务冷却期（缺省回落 probeTimeout）+ WithConsecutiveFailures 连续失败计数触发（与速率型并联，补低 QPS 信号，对齐 Envoy consecutive_5xx）；v0.11.0 起 ratelimit Lockout 防爆破锁（fail2ban 形态：滑窗失败计数→阈值锁定拒绝 LockDuration→成功 Reset 清零/到期自解，CheckLocked 返回剩余时长）；v0.12.0 起 retry/httpx RetryableWithHeaders（403 + Retry-After/X-RateLimit-Remaining 头感知可重试判定，HeaderSource 零依赖抽象）、syncx FanInLimit 受限并发扇出（固定 worker 防下游过载）+ FanInLimitCtx（v0.14.0，ctx 感知：ctx 已取消未启动项 fn 一次不调、剩余槽快速排空 Canceled、在飞项照常落槽）、ratelimit WithTokenClock 时钟注入；v0.13.0 起 breaker 熔断期收敛到探测级（forcePass 强制探活 + 冷却期满半开探测，其余拒绝——SRE 公式退役为 closed→open 触发器，WithConsecutiveFailures 触发后流量真停）+ State()/State 枚举可观测出口；v0.16.0 起 ratelimit NewKeyedLimiterByFunc[K]——factory func(K) Limiter 按 key 定配额（一个管理器按接口维度分档位，NewKeyedLimiterOf 零破坏随迁；未登记 key 拿 factory 兜底档的坑已在 doc 点名，#31）；v0.17.0 起 KeyedLimiter.Create 护栏内原子登记（表满先回收空闲与 Allow 同路、仍满拒绝计 OverCapHits、已存在不覆盖——热更走 Replace；解决 ByFunc factory 库锁内调用致消费方锁序倒置，#33）；v0.18.0 起 retry.DoValue 泛型伴生——带返回值的重试（DoValue[T](ctx, cfg, fn func(attempt int) (T, error))；Do 改为委托给 DoValue——退避序列/抖动/MaxDelay 封顶/DelayHint 优先/Retryable 门控/ctx 取消只有一份实现，杜绝「同一个仓里两份实现」；失败返回零值与最后一次错误）	pkg
logx	统一日志门面（多后端可替换 + caller 归属；Sink 已迁嵌套模块 logx/sink，根包纯 stdlib）；WithFilter 脱敏/丢弃包装（FilterKey 命中键替换 ***/FilterFunc 丢整条，子 logger 保持规则）、Slogger/SlogHandler 正向桥（三方 slog 直接消费 logx 生态）、TraceHandler 任意 slog.Handler 自动注入 trace_id、NewAuditLogger 审计留痕（级别锁 Info，不受 LOG_LEVEL 降级）、LevelEnabler 热路径提前判级、ParseLogLevel 返回 (Level, error) + ParseLogLevelOr 配错退默认（v0.7.0）；优雅关停正身在 core/lifecycle.Manager（logx/shutdown 仅余 Deprecated 别名）；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入	core
core	应用基建件——governance 治理 schema、config 配置加载（LoadBootstrap/LoadDotEnv/Get* 系、default/env/range/options tag 校验、OverlaySource 多源叠加热更、ApplyEnvOverlay env 优先 12-factor 形态）、transport 协议无关传输上下文（Transporter/Header/Server·Client ctx 存取，仅标准库）、chain 中间件链（Handler/Middleware/Chain/Recovery/Timeout，与 nns-endpoint.Endpoint 同形）、lifecycle 契约 + Manager 优雅关停（自 logx/shutdown 迁入，日志 *slog.Logger——core 不再依赖 logx）、network IP 工具、version；v0.9.0 起 config FieldSet 显式提供集合（yaml 显式 port:0 不再被 default/env 覆盖——LoadBootstrap 默认接线，免全量指针化）+ require tag（必须 yaml/env 提供，缺失列全并附 env 提示）+ v0.9.1 修 yaml:,inline 字段在 FieldSet 下漏标记（inline 叶子显式零值曾被 default 覆盖）；v0.9.2 env 卫生改纯静态（仅格式/重名，移除依赖进程环境的拼写冒烟检查——误报 PATH/HOME、漏无人设置的真拼错，core#8），命名一致性走 LintEnvNaming 诊断 / WithEnvNamingLint 可选 fail-closed / ignorederived="true" 豁免；v0.10.0 起 config 严格模式——LoadBootstrap[T](envFlag string, opts ...LoadOption) 传 config.WithStrict() 开启：未知键拒载（不再静默忽略），错误带嵌套路径 + 该层合法键清单 + 近似拼写建议（UnknownKeyError）；默认行为不变，严格模式显式开启；v0.11.0 起 config 加载入口按来源拆开——LoadFile（任意路径：CLI -config 路径、容器内固定挂载位）+ Unmarshal（字节源：API 下发 / 模板渲染 / 测试夹具），与 LoadBootstrap（etc/ 约定）共享同一条解码线，因此严格模式诊断面（嵌套路径 / 合法键清单 / 拼写建议）与来源无关；LoadBootstrap 行为与错误文案逐字不变	—
kitx	标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail）+ hash（v0.2.0 起非密码学哈希助手 Md5Hex/Md5Bytes——缓存键/幂等键/短唯一 code，格式稳定承诺，pkg 2026-09-15 治理移除弱哈希后 kitx 侧收编 pkg#10），自 pkg v0.10.0 拆出	pkg
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源（v0.3.0 起 OTLP 双协议导出：gRPC 缺省 / HTTP，Config.Protocol + Headers，切换协议不丢传播器/指标/旧 provider 关闭）	logx
registry	注册发现核心（provider 无关 SPI：Registrar/Discoverer/Subscriber/ConfigStore + 实例模型 + netutil）+ sdbridge + registrymocks——根仓零第三方依赖；Nacos 实现与 Nacos 配置源已拆成嵌套模块（v0.5.0 起：registry/nacosimpl、registry/nacos——nacos-sdk-go 重依赖隔离在此，实测单独引入即拖 63 个第三方模块，不隔离时只要 SPI 接口的消费方也会被连带拖入）	core
data	数据访问门面——复刻 ekit data/ 能力面：cache/rediscache/crud/distlock/gormx/redisx/timertask/cachetest 八子包 re-export（类型同一，实现住 pkg 与各子仓）+ cached 缓存读写编排（写后失效/事务提交后失效/查询缓存版本号失效/GetByIDs 批量点读 MGet 快路径/bloom 防穿透）+ twolevel 两级缓存与跨实例失效广播（v0.7.0 起本仓唯二非 re-export 实现）；v0.15.0 起壳跟随源仓演进——cache 壳补 LocalCache 可选形状（EvictPolicy/Sweeper/HitGetter）、cachetest 壳补 5 个契约套件入口（套件 8 → 13 场景）、v0.18.0 起 cache 壳补 PeekGetter 别名 + cachetest 壳补 2 个 stale-if-error 契约入口（套件 13 → 15 场景）、timertask 壳的 Redis 形态随源仓 v0.2.0 迁至嵌套模块 timertask/redis（壳不再转发 RedisBackend/ShardManager，Redis 形态直接依赖该嵌套模块）；all/ 聚合模块已废弃 retract	concurrency、gormx、logx、pkg、redisx、timertask
gormx	SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储（原 oekit/gorm，v0.3.0 更名）	logx、pkg
redisx	Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock（Locker 同形可互换；Renew 手动续期（false=锁丢失，不进 Locker 接口保 etcdx 互换）+ WithAutoRenew 覆盖 TryLock 自动续期（v0.8.0 feat!：此前组合不续期）；Semaphore ZSET 槽位信号量（v0.8.0：Acquire 同 identifier 幂等刷新 + Lua 内原子清过期槽崩溃自愈、Renew 仅未过期槽可续、Cleanup 返条数、无 Redis 降级 fail-fast））、分布式限流 ratelimit（Lua 三态 + 故障本地兜底）；v0.9.0 起 distlock Lockout 分布式防爆破锁（Redis 侧 fail2ban：滑窗失败计数→阈值锁定 Penalty→Reset 清零，与 concurrency/ratelimit.Lockout 进程内孪生——多实例共享计数是存在理由；惩罚只按首次触发计算、nil client fail-fast 不降级，#6）	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、logx、registry
httpx	HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传；loadbalance Selector 形态（RoundRobin/Random/Weighted/一致性哈希权重感知虚拟副本/p2c 自适应——EWMA 经 DoneFunc 回写建立、Err 计 1s 惩罚；WithFilter 按元数据过滤；v0.4.0 起 Balancer 全家族删除无兼容路径）；codec 注册制编解码器（json 内置 + form 表单，DoCodec 请求按 codec 序列化、响应按 Content-Type 反查回退请求 codec）；v0.6.0 起 net/http 桥接层 NewRoundTripper/StdClient——存量标准库外呼一行 Transport 接入熔断/重试/指标/链路（重试缺省关显式开、非 2xx 非错误、hop-by-hop 隔离，#8）；v0.8.0 起 SafeDialFunc/WithSafeDial 出站 SSRF 防护胶水（判定单源 pkg/urlguard v0.15.0：解析 IP 全量预检 + 实际 RemoteAddr 端点核对闭合重解析 TOCTOU、Happy-Eyeballs 覆盖，构造态豁免；v0.7.0 内置的独立 httpx/urlguard 实现收敛删除，#11）	concurrency、logx、metrics、pkg、registry、tracing
network	轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具	concurrency、logx、tracing
timertask	分片定时任务（FNV-1a、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效）；v0.2.0 起 Redis 后端迁至嵌套模块 timertask/redis（根包不再引 go-redis/logx/concurrency，require 仅 pkg——import timertask 与 import timertask/local 的模块依赖面均无 redis，纯 stdlib 嵌入式场景可用）+ 新增 local 子包 cron 调度器 Scheduler（表达式复用 pkg/timex/cron 不另写一份；并发度/CatchUp 补跑/退出语义明确，FakeClock 假时钟驱动、触发点序列可确定性断言）	pkg
middleware	Hertz 标准中间件栈（模块根 mw，双层目录已收平）+ contrib 桥接 + hmw + SheddingMiddleware 自适应降载 + chainmw 子包（transport 感知框架无关中间件，基于 core/chain+transport：Recovery 带 panic 隔离上报钩子 WithRecoveryReporter、AccessLog skip+redact+自定义字段、MetadataPropagate——kitex 经 kitex/chainmw.ToKitex 复用同一实现，根包 Recovery/AccessLog 已薄壳化复用 chainmw 内核、下游 handler 可经 transport.FromServerContext 读协议无关传输信息）；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶）；v0.11.0 起 WithAccessLogSink 落库 sink（AccessRecord{Method,Path,Status,Latency,ClientIP,UserAgent,TraceID} 与日志同源、c 同传可读业务键、error/panic 只记 Warn 不影响主链路、SkipPaths 命中不触发）+ chainmw.WithSink 内核同构（kitex 随 ToKitex 获得）+ StackConfig.DisableResponseWrap 响应自管一键形态（TraceID→Recovery→AccessLog）与 AccessLogOptions 透传 + doc/README「适用边界」段（响应契约统一 vs handler 自管的推荐组合，#18）；v0.12.0 起 AccessLog panic 恢复点产出记录（AccessRecord.Panic 标记 + Err 摘要，Hertz status 按 Recovery 缺省 500）后按原值重抛——panic 请求不再零访问记录，sink/kitex 桥接同步留痕，#20；v0.13.0 起 accesslog 内建日志可关闭/改道（WithAccessLogSilent 只采不写、WithAccessLogLogger 注入宿主 logger 避免双写；静默下 skip/redact/sink/panic 记录照常），内核 chainmw.WithSilent 同构（kitex 随 ToKitex 获得），#38	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 池	httpx、logx、metrics、nns、registry
bootstrap	应用生命周期引导——New(WithServiceName/WithShutdownTimeout/WithBeforeServe) + Run(fn) + healthz；App.Ready/ReadyChan/IsReady 就绪门（幂等并发安全）——嵌套 bootstrap/nacos 自 v0.3.0 起 NNS 注册延迟到 Ready 之后（server 就绪 → userFn 触发 Ready → 才进注册中心）、关停序 nns 反注册先于 server 关闭；就绪门漏接时可观测——nacos 看门狗超时打 ERROR 点明「服务不会注册到注册中心」（WithReadyTimeout 可调）+ NNSComponent.RegistrationState() 暴露注册阶段（pending/registered/failed/skipped/shutdown）；Metrics/Tracing 在嵌套模块 bootstrap/obs	concurrency、core、logx
hertz	Hertz 运行时集成（模块根扁平化）——日志桥接、生命周期、SSE/health/metrics、适配器、OTel、crudh/validatorh（基于 kitx/validator）/versionh（原 handler 微库收编）；RunServer 变参就绪门 WithOnReady（全部 HostPort TCP 探活可建连后回调，探活超时按启动失败优雅关机；缺省超时 5s 经 WithReadyProbeTimeout 调整——探活目标是 server 自动取到的全部 HostPort，无探活地址覆盖选项（kitex 侧才有 WithReadyAddr）），配合 bootstrap Ready 实现 NNS 延迟注册；transportx（hertz→core/transport 同构适配器）+ chainmw 桥接	bootstrap、concurrency、core、gormx、kitx、logx、metrics、middleware、nns、pkg、registry、tracing
kitex	Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel、istio（xDS 动态熔断，原 istio 微库收编）；RunServer 变参就绪门（WithOnReady/WithReadyAddr/WithReadyProbeTimeout）+ chainmw.ToKitex（core/chain.Middleware → kitex 中间件，与 hertz 共享 middleware/chainmw 实现）+ transportx	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	组合式流程编排——串行/并行/异步/条件分支 + Hook AOP	concurrency、logx
kitex-examples	Kitex echo 示例——client/server + IDL + 治理配置	bootstrap、core、kitex、logx、tracing

Documentation

Overview

Package kitex 为 CloudWeGo Kitex RPC 框架提供 ekit 生态集成。

本包覆盖以下能力：

• 日志桥接：将 Kitex klog 接管到 ekit logx——已迁 github.com/oekit/logx/kitexlog （kitexlog.NewLogger）；本包保留 NewLogger Deprecated 别名委托，行为一致。
• 可观测性：Kitex OpenTelemetry tracing/metrics 一键接入——**已迁嵌套模块** github.com/oekit/kitex/observability/tracing/instrumentation/kitexotel （kitexotel.NewServerTracingSuite / kitexotel.NewClientTracingSuite）。 v0.7.0 起本包不再持有该能力：obs-opentelemetry 会把 apache/thrift 抬到 v0.16.0，留在根模块会打断下游按 thrift 0.13 生成的 Thrift 代码（#37）。
• 治理配置：从 Nacos 配置中心加载 retry/rpc_timeout/circuit_breaker/limiter 策略并热更新（见 NewGovernanceConfig）。
• Suite 聚合：以 Kitex client.Suite/server.Suite 形式聚合治理选项（见 NewClientSuite、NewServerSuite）。
• 启动辅助：与 ekit [bootstrap.App] 集成的生命周期管理（见 RunServer）。

快速开始

// 1. 日志桥接（推荐 logx/kitexlog；必须传 slog 实例避免无限递归）
klog.SetLogger(kitexlog.NewLogger(logx.NewSlogLogger("my-rpc")))
//    或 Deprecated 别名：klog.SetLogger(kitex.NewLogger(logx.NewSlogLogger("my-rpc")))

// 2. 可观测性（需先调用 tracing.Init；v0.7.0 起随嵌套模块 kitexotel 提供）
svr := echo.NewServer(new(Impl),
    server.WithSuite(kitexotel.NewServerTracingSuite()),
)

// 3. 治理配置（需 Nacos config client）
gov, _ := kitex.NewGovernanceConfig(configCli)
svr := echo.NewServer(new(Impl),
    server.WithSuite(kitex.NewServerSuite("echo", gov)),
)

优雅退出最佳实践（对照官方 best practice 文档）

Kitex 的 server.Stop() 按以下流程排空连接：

1. 停止接受新连接（关闭监听端口）
2. 非多路复用：每秒检查直到所有连接处理完毕；多路复用：先发控制帧通知客户端再等待
3. 超时退出：达到 ExitWaitTime（默认 5s）后直接退出

关键旋钮：

server.WithExitWaitTime(10*time.Second) // 排空等待上限（默认 5s）

时间关系（K8s 环境下必须满足）：

client.DiscoverLatency < k8s.PreStopTime < server.MaxLatency < kitex.ExitWaitTime < k8s.TerminationGracePeriodSeconds

其中：

• client.DiscoverLatency：客户端服务发现延迟（Nacos 推送 + 缓存刷新）
• k8s.PreStopTime：preStop 命令等待时间（建议 sleep 5s，确保 iptables/endpoint 更新传播）
• server.MaxLatency：单请求最大处理耗时
• kitex.ExitWaitTime：框架排空等待上限
• k8s.TerminationGracePeriodSeconds：K8s 强杀超时（须大于以上所有值之和）

推荐 K8s 配置：

lifecycle:
  preStop:
    exec:
      command: ["sleep", "5"]
terminationGracePeriodSeconds: 30

与 ekit bootstrap 集成时，bootstrap 的 ShutdownTimeout 是单资源关闭预算； Kitex server.Stop() 使用自身 ExitWaitTime（忽略传入 ctx），两者独立。 保持 ShutdownTimeout > ExitWaitTime 以确保排空不被 bootstrap 兜底截断。

Index

• func FromKitexError(err error) (*ekiterr.BizError, bool)
• func IsKitexTimeoutError(err error) bool
• func NewLogger(logger logx.Logger) klog.FullLogger
• func NewPanicLogMiddleware() endpoint.Middleware
• func RunServer(app lifecycle.App, name string, svr server.Server, opts ...RunServerOption)
• func SetDefaultPanicHandler()
• func WithBizErrorBridge() client.Option
• type ClientSuite
  • func NewClientSuite(clientService, serverService string, gov *GovernanceConfig, ...) *ClientSuite
  • func (s *ClientSuite) Close() error
  • func (s *ClientSuite) Options() []client.Option
• type ClientSuiteOption
  • func WithCircuitBreaker() ClientSuiteOption
  • func WithMetrics(reg prom.Registerer, namespace string) ClientSuiteOption
  • func WithRPCTimeout() ClientSuiteOption
  • func WithRetry() ClientSuiteOption
• type DNSResolver
  • func NewDNSResolver() DNSResolver
• type GovernanceConfig
  • func NewGovernanceConfig(cli config_client.IConfigClient, opts ...GovernanceOption) (*GovernanceConfig, error)
  • func (g *GovernanceConfig) Close() error
  • func (g *GovernanceConfig) TemplateTimeoutOptions() []client.Option
• type GovernanceOption
  • func WithDataIDTemplate(tmpl string) GovernanceOption
  • func WithGovernanceGroup(group string) GovernanceOption
  • func WithGovernanceTemplate(dataID string) GovernanceOption
• type RunServerOption
  • func WithOnReady(fn func(ctx context.Context)) RunServerOption
  • func WithReadyAddr(addr string) RunServerOption
  • func WithReadyProbeTimeout(d time.Duration) RunServerOption
• type ServerSuite
  • func NewServerSuite(serverService string, gov *GovernanceConfig, opts ...ServerSuiteOption) *ServerSuite
  • func (s *ServerSuite) Options() []server.Option
• type ServerSuiteOption
  • func WithLimitReporter(r klimiter.LimitReporter) ServerSuiteOption
  • func WithLimiter() ServerSuiteOption

Functions

func FromKitexError

func FromKitexError(err error) (*ekiterr.BizError, bool)

FromKitexError 把 kitex kerrors 错误转为 ekit BizError,供客户端统一 错误处理路径(middleware.Fail、StatusMapper)使用。覆盖以下类型:

• *kerrors.BizStatusError / *kerrors.GRPCBizStatusError(对端业务异常): 透传 BizStatusCode 作为 BizCode,BizMessage 作为 Message; HTTPCode 留 0,由 ekit StatusMapper 推导。
• kerrors.IsTimeoutError(链路超时):BizCode=50400, HTTPCode=504。
• kerrors.ErrNoMoreInstance / ErrACL(无可用实例 / ACL 拒绝): BizCode=50300 / 40301, HTTPCode=503 / 403。
• *kerrors.DetailedError 兜底:BizCode=50000, HTTPCode=500。
• nil / 非 kitex 错误:返回 (nil, false),调用方走 fallback。

原始错误始终保留为 BizError.Cause(经 Unwrap 链可达):errors.Is / errors.As / kerrors.FromBizStatusError 等链式判定对转换结果依然有效, DetailedError 携带的底层 cause 不会丢失(2026-09-05 复审修复:原实现 丢弃原始错误,转换后排障信息断链)。

官方依据:https://www.cloudwego.io/zh/docs/kitex/best-practice/error_handle/ ("kerrors 的错误定义支持 errors.Is 和 errors.Unwrap"、"basic error types 可以用 WithCause 来添加详细原因" — 错误链可追溯是 kitex 官方语义)

用法(典型场景:kitex client middleware,把对端错误转 ekit BizError 上抛):

if biz, ok := kitex.FromKitexError(err); ok {
    return biz
}
return err

归属说明(2026-09-19 重构):本函数原在 pkg/errors(kerrors_bridge.go), 属"pkg/errors import kitex kerrors"明示例外;为恢复 L1 基础层零框架 依赖,迁至 kitex 包——kitex 错误桥接本就是 kitex 专属能力。

func IsKitexTimeoutError

func IsKitexTimeoutError(err error) bool

IsKitexTimeoutError 包装 kerrors.IsTimeoutError,提供不直接 import kitex kerrors 的判定入口。

官方依据:best-practice/error_handle (Kitex 内部错误章节"判断具体错误类型")

func NewLogger

func NewLogger(logger logx.Logger) klog.FullLogger

NewLogger 将 ekit logx.Logger 适配为 Kitex klog.FullLogger。

映射关系（与迁移前完全一致）：

• Trace → Debug（logx 无 Trace 级别）
• Notice → Info（logx 无 Notice 级别）
• Fatal → Error（ekit 不做 os.Exit）

必须传 slog 实例，不可传 hlog 后端的 Logger（如 logx.WithService(...)）， 否则会形成 adapter → logx → hlog → adapter 的无限递归；实现会在检测到 hlog 后端时 panic 以防止生产环境不可控故障。

Deprecated: 已迁至 github.com/oekit/logx/kitexlog（kitexlog.NewLogger）， 本别名委托实现，行为完全一致；将在未来 major 版本移除。

func NewPanicLogMiddleware

func NewPanicLogMiddleware() endpoint.Middleware

NewPanicLogMiddleware 返回记录业务 handler panic 的 server middleware。

kitex 框架在 handler panic 时自动 recover 并把详情写入 rpcinfo stats (返回 kerrors.ErrPanic/*kerrors.DetailedError 给调用方),业务无法在 recover 之前插桩;官方推荐的获取详情方式就是在 middleware 里检查 rpcinfo.GetRPCInfo(ctx).Stats().Panicked()。本 middleware 做的事:

• next 返回 error 且 stats 记录了 panic → 写 logx 结构化错误日志 (method / remote_addr / panic 值 / err / stack),err 原样透传, 不改变 kitex 默认错误返回语义;
• 无 panic 的普通错误、无 rpcinfo 的 ctx:直接透传,零开销。

用法(与 SetDefaultPanicHandler 互补,建议一起挂):

svr := echo.NewServer(handler,
    server.WithMiddleware(ekitkitex.NewPanicLogMiddleware()),
)

官方依据:https://www.cloudwego.io/zh/docs/kitex/tutorials/basic-feature/panic/ ("你可以在自己的中间件里检查是否发生过 panic" → ri := rpcinfo.GetRPCInfo(ctx); ri.Stats(); stats.Panicked())

func RunServer

func RunServer(app lifecycle.App, name string, svr server.Server, opts ...RunServerOption)

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

该函数会：

1. 通过 app.AddResource 注册 svr.Stop 作为关闭回调（优雅关闭时自动调用）。
2. 通过 app.GoBackground 在后台启动 svr.Run()（阻塞直到 server 退出）。 设置 WithOnReady 时回调以触发延迟注册（app.Ready()）；WithReadyAddr 指定时**探活与 svr.Run() 并发**（#38），端口就绪后回调；探活超时按 启动失败处理（RequestShutdown）。
3. svr.Run() 返回 error（kitex 监听失败如端口被占用即走此路径）或 panic 时调用 app.RequestShutdown() 触发优雅关机，避免进程无服务地"假活" （对称 hertz.RunServer）。

就绪门与启动顺序（#38）

监听端口是在 svr.Run() **内部**才绑定的（kitex server 侧 listener 创建）， 故探活必须与 svr.Run() **并发**：串行先探活后启动必然 connection refused ⇒ 探活必超时 ⇒ svr.Run() 根本不会被调用 ⇒ server 从不监听， 「kitex.RunServer + WithOnReady 配合 bootstrap 的 Ready 实现 NNS 延迟 注册」这条推荐路径在生产中不可用（与 hertz #43 完全同型，hertz 侧已修）。

两条守则：

• 端口归属预检：启动前先自行绑定一次探活地址；已被他人占用（EADDRINUSE） 说明本进程 server 必然绑定失败，此时若继续探活会连上**对方**的监听器 并误判就绪 ⇒ 直接按启动失败处理，绝不回调 onReady。
• 探活期间 app 关闭或 svr.Run() 返回即中止探活（不触发 onReady）。

⚠️ TCP 可建连只近似「端口已监听」，不等于业务健康；业务级健康门请配合 业务自身的健康检查后再 Ready。

关闭语义（对照官方 best-practice/graceful_shutdown 文档）

信号路径：SIGTERM/SIGINT（SIGHUP 未被忽略时含之）由 svr.Run() 内置 waitSignal 处理，直接触发 svr.Stop(context.Background())，排空上限为 server.WithExitWaitTime（**默认 5s** — kitex 官方默认;如未显式设置,框架 内部用 5s,非多路复用每秒 ticker 检 active conn / 多路复用先发控制帧）。 同一信号也会让 bootstrap 走本函数注册的关闭回调,第二次 Stop 因 server 已关可能返回 ErrServerDone（kitex 0.16+ 行为）— 跟 hertz 双路关闭的良性 竞争同理,本函数按成功处理。

⚠️ **必须满足 K8s 时间关系**(官方文档强制约束,违反则优雅停机不保证):

client.DiscoverLatency < k8s.PreStopTime < server.MaxLatency
    < kitex.ExitWaitTime < k8s.TerminationGracePeriodSeconds

**推荐显式设置 server.WithExitWaitTime**(尤其长耗时 RPC):保持其小于 bootstrap 单资源关闭预算(shutdown.New 的 defaultTimeout),避免排空被 bootstrap 兜底截断。kitex server.Stop() 忽略传入 ctx,使用自身 ExitWaitTime。

使用方式（在 bootstrap.Run 的 userFn 内）：

b, _ := bootstrap.New(bootstrap.WithServiceName("svc")) // + nacos/obs WithXxx 按需注入
b.Run(func(app *bootstrap.App) error {
    svr := echo.NewServer(new(Impl),
        server.WithRegistry(kitex.NewRegistry(reg)),
        server.WithServiceAddr(addr.NewNetAddr("tcp", ":9090")),
    )
    kitex.RunServer(app, "kitex-echo", svr,
        kitex.WithOnReady(func(ctx context.Context) { app.Ready() }),
        kitex.WithReadyAddr(":9090"))

    h := server.New(server.WithHostPorts(":8080"))
    app.AddResource("hertz", func(ctx context.Context) error { return h.Shutdown(ctx) })
    return h.Run()
})

func SetDefaultPanicHandler

func SetDefaultPanicHandler()

SetDefaultPanicHandler 注册 ekit 风格的 kitex **内部 goroutine** panic handler (gofunc.RecoverGoFuncWithInfo 恢复的 goroutine:ttstream/nphttp2 流式传输、 框架后台任务等),日志走 logx 结构化输出。

⚠️ 覆盖范围(2026-09-05 复审修正,以 kitex v0.16.3 源码为准):

• 业务 handler panic:kitex 在 server/server.go invokeHandleEndpoint 的 defer 里直接 recover 并转 kerrors.ErrPanic,**不经过** gofunc 的 panicHandler。要在统一日志里记录 handler panic,请使用 NewPanicLogMiddleware(官方推荐路径)。
• kitex 内部 goroutine panic(流式传输等):走 gofunc.SetPanicHandler, 本函数生效。注意这是对 kitex 默认行为的叠加——gofunc 内部仍会打 klog,本 handler 额外写 logx。

官方依据:https://www.cloudwego.io/zh/docs/kitex/tutorials/basic-feature/panic/ ("业务代码使用 go 关键字创建的 goroutine 里发生的 panic,需要业务自行 recover"——handler panic 由框架 recover,详情走 Stats().Panicked(),官方 文档未将 gofunc.SetPanicHandler 列为 handler panic 钩子)

用法(在 bootstrap.Run userFn 内,kitex.RunServer 之前):

b, _ := bootstrap.New(bootstrap.WithServiceName("svc")) // + nacos/obs WithXxx 按需注入
b.Run(func(app *bootstrap.App) error {
    ekitkitex.SetDefaultPanicHandler()
    svr := echo.NewServer(new(Impl), ...)
    ekitkitex.RunServer(app, "kitex-echo", svr)
    ...
})

func WithBizErrorBridge

func WithBizErrorBridge() client.Option

WithBizErrorBridge 返回 kitex client middleware,把对端抛的 kitex kerrors (BizStatusError / GRPCBizStatusError / DetailedError / timeout / no-instance / ACL) 转为 ekit BizError 沿原 error 通道上抛,让 ekit handler 层 middleware.Fail + StatusMapper 走统一处理路径,不再 fallback 500。

⚠️ 行为变化:开启后,client 调用的 error 返回类型可能从 kitex kerrors 变成 ekit *BizError,使用 errors.Is/As 判定的代码需注意。pkg/errors.AsBizError 仍可识别(*BizError Unwrap 自身 cause,kerrors.BizStatusError 通过 kerrors.FromBizStatusError 提取)。

官方依据:

https://www.cloudwego.io/zh/docs/kitex/best-practice/error_handle/
https://www.cloudwego.io/zh/docs/kitex/tutorials/basic-feature/bizstatuserr/

用法(对称其他 client.Option):

cli, err := myservice.NewClient("myservice",
    kitex.WithBizErrorBridge(),
    client.WithHostPorts(":8888"),
)

⚠️ kitex v0.16.3 实测(e2e 2026-09-06):普通 thrift/TTHeader ping-pong 下, server 端 BizStatusError 不做类型化解码(仅 ttstream/gRPC 流式支持), 到达 client 的是 DetailedError 文本 → 走 50000 兜底分支;类型化 code/msg 映射需要流式协议。详见 kitex/e2e_meta_test.go。

Types

type ClientSuite

type ClientSuite struct {
	// contains filtered or unexported fields
}

ClientSuite 聚合 Kitex 客户端治理选项（retry + rpc_timeout + circuit_breaker）。

实现 client.Suite 接口，可通过 client.WithSuite 一行接入。

func NewClientSuite

func NewClientSuite(clientService, serverService string, gov *GovernanceConfig, opts ...ClientSuiteOption) *ClientSuite

NewClientSuite 创建客户端治理 Suite。

clientService 为当前服务名，serverService 为被调服务名。 governance 为 NewGovernanceConfig 返回的治理配置客户端。

使用方式：

suite := kitex.NewClientSuite("my-service", "echo-service", gov,
    kitex.WithRetry(),
    kitex.WithRPCTimeout(),
)
cli, _ := echo.NewClient("echo-service", client.WithSuite(suite))

func (*ClientSuite) Close

func (s *ClientSuite) Close() error

Close 释放本 Suite 创建、且不受 kitex client 生命周期管理的治理资源 （retry 容器内部的熔断面板；CBSuite 由 client.Close() 自动关闭，无需在此处理）。

必须在所有由本 Suite 构建的 client 关闭之后再调用——提前调用会使 retry 容器的重试熔断面板失效。幂等，可安全重复调用。

func (*ClientSuite) Options

func (s *ClientSuite) Options() []client.Option

Options 返回聚合的 client.Option 列表。

type ClientSuiteOption

type ClientSuiteOption func(*clientSuiteConfig)

ClientSuiteOption 是 NewClientSuite 的配置选项函数类型。

func WithCircuitBreaker

func WithCircuitBreaker() ClientSuiteOption

WithCircuitBreaker 启用 circuit_breaker 策略热更新。

func WithMetrics

func WithMetrics(reg prom.Registerer, namespace string) ClientSuiteOption

WithMetrics 启用弹性指标（熔断状态/迁移/拒绝/重试，kind="kitex"）， 形态对齐 httpx.WithMetrics 与 nns endpoint.WithMetrics。 reg 为 nil 时无指标；namespace 为空时用 "kitex"。 重试计数经 metainfo 的 retry.TransitKey（kitex retry 容器每次重试 重新走 middleware 链并注入序号）；方法级 RPC 视角（吞吐/时延按 caller/callee/method/status/retry 分维）另见 kitexprom 桥接包。

func WithRPCTimeout

func WithRPCTimeout() ClientSuiteOption

WithRPCTimeout 启用 rpc_timeout 策略热更新。

func WithRetry

func WithRetry() ClientSuiteOption

WithRetry 启用 retry 策略热更新。

type DNSResolver

type DNSResolver = discovery.Resolver

DNSResolver 是 kitex-contrib/resolver-dns 的别名 type,kitex 客户端 把它当 discovery.Resolver 用(供 client.WithResolver(option) 接入)。

官方依据:https://github.com/kitex-contrib/resolver-dns (v0.1.0)

业务场景: K8s/容器编排下,服务注册用 Headless Service / ClusterIP 暴露,业务用 DNS 名做服务发现,ekit 把 DNSResolver 喂给 kitex client 替代静态 IP 列表。

业务用法:

cli, _ := myservice.NewClient("myservice",
    client.WithResolver(mw.NewDNSResolver()),
    ...
)

注意: DNS lookup 在 K8s 内网/Headless Service 下,每个 pod 有 独立 IP(轮询 round-robin),适合 stateless 微服务;stateful 服务(有状态)用 Headless Service 配 hostname 替代。

func NewDNSResolver

func NewDNSResolver() DNSResolver

NewDNSResolver 桥接 kitex-contrib/resolver-dns.NewDNSResolver。 业务用 client.WithResolver(ekit.NewDNSResolver()) 即可。

局限: kitex-contrib/resolver-dns 只解析 A/AAAA 记录(SRV/Service 头解析需要业务自己实现),如需 SRV 记录可换 kitex-contrib/registry-zookeeper 或 ekit 内部 NNS。

type GovernanceConfig

type GovernanceConfig struct {
	// contains filtered or unexported fields
}

GovernanceConfig 从 Nacos 配置中心加载 Kitex 治理策略（retry/rpc_timeout/circuit_breaker/limiter） 并在配置变更时热更新到 Kitex 运行时。

每类策略对应一个独立的 Nacos 配置项（dataId），格式为：

客户端策略: {clientService}.{serverService}.{category}
服务端策略: {serverService}.{category}

category 可选值: retry, rpc_timeout, circuit_break, limit, degradation

func NewGovernanceConfig

func NewGovernanceConfig(cli config_client.IConfigClient, opts ...GovernanceOption) (*GovernanceConfig, error)

NewGovernanceConfig 创建治理配置客户端。

cli 为 ekit [nacos.NewConfigClient] 返回的配置客户端，与业务配置共享同一连接。

func (*GovernanceConfig) Close

func (g *GovernanceConfig) Close() error

Close 取消本 GovernanceConfig 注册的全部 Nacos 监听并清空订阅状态。

动态创建依赖 client 的场景（如网关按需建 client）会随时间累积监听器， 在 client 全部关闭后调用 Close 释放治理订阅。Close 后对象仍可复用： 下一次 subscribe 会重新注册监听，但未重新订阅前不再收到任何回调。

注意：nacos 的 CancelListenConfig 以 dataId 为粒度，会一并移除该 dataId 上其他监听者——请勿对同一 dataId 混用不同 GovernanceConfig 实例。

func (*GovernanceConfig) TemplateTimeoutOptions

func (g *GovernanceConfig) TemplateTimeoutOptions() []client.Option

TemplateTimeoutOptions 返回统一模板 timeout_ms 的 client.Option; 未启用 WithGovernanceTemplate 时返回 nil。

type GovernanceOption

type GovernanceOption func(*GovernanceConfig)

GovernanceOption 是 NewGovernanceConfig 的配置选项函数类型。

func WithDataIDTemplate

func WithDataIDTemplate(tmpl string) GovernanceOption

func WithGovernanceGroup

func WithGovernanceGroup(group string) GovernanceOption

WithGovernanceGroup 设置 Nacos 配置分组，默认 "DEFAULT_GROUP"。

func WithGovernanceTemplate

func WithGovernanceTemplate(dataID string) GovernanceOption

WithDataIDTemplate 设置 dataId 模板，支持占位符 {client}、{server}、{category}。 默认 "{client}.{server}.{category}"（客户端）和 "{server}.{category}"（服务端）。 传入的模板同时用于客户端；服务端模板会自动去掉 "{client}." 前缀。 WithGovernanceTemplate 订阅**统一治理模板**(governance 包 schema, audit 5.2 阶段 2):单 dataID 承载全部类别,template 中 timeout_ms 应用到 rpctimeout 容器(经 TemplateTimeoutOptions 取 client.Option);retry/ circuit_breaker/limiter 为 kitex 原生富结构,仍走 per-category dataID。

type RunServerOption

type RunServerOption func(*runServerConfig)

RunServerOption 配置 RunServer 的就绪回调行为。

func WithOnReady

func WithOnReady(fn func(ctx context.Context)) RunServerOption

WithOnReady 注册就绪回调：TCP 探活通过（WithReadyAddr 指定地址，默认 未指定时立即回调）后执行，典型用途是触发延迟注册（app.Ready()，配合 bootstrap/nacos v0.3.0）。kitex server 无监听就绪 introspection， 探活目标必须显式给出。

func WithReadyAddr

func WithReadyAddr(addr string) RunServerOption

WithReadyAddr 指定探活目标地址（host:port，即 server.WithServiceAddr 所配）。 设置 WithOnReady 且未指定本项时：无探活目标，onReady 在 svr.Run 启动前 同步执行（注册窗口毫秒级，见 doc 说明）。

⚠️ 探活目标必须是**本 server 自己绑定**的监听地址（契约）：端口被他人 占用时本进程 server 必然绑定失败（kitex 监听失败 → svr.Run() 返回 error）， 此时探活会连上对方的监听器并误判就绪 ⇒ onReady 把不属于自己的实例注册到 注册中心。故启动前先做端口归属预检，被占用即按启动失败处理（见 RunServer）。

func WithReadyProbeTimeout

func WithReadyProbeTimeout(d time.Duration) RunServerOption

WithReadyProbeTimeout 配置探活超时（默认 5s；仅 WithReadyAddr 生效）。

type ServerSuite

type ServerSuite struct {
	// contains filtered or unexported fields
}

ServerSuite 聚合 Kitex 服务端治理选项（limiter）。

实现 server.Suite 接口，可通过 server.WithSuite 一行接入。

func NewServerSuite

func NewServerSuite(serverService string, gov *GovernanceConfig, opts ...ServerSuiteOption) *ServerSuite

NewServerSuite 创建服务端治理 Suite。

serverService 为当前服务名。 governance 为 NewGovernanceConfig 返回的治理配置客户端。

使用方式：

suite := kitex.NewServerSuite("echo-service", gov, kitex.WithLimiter())
svr := echo.NewServer(new(Impl), server.WithSuite(suite))

func (*ServerSuite) Options

func (s *ServerSuite) Options() []server.Option

Options 返回聚合的 server.Option 列表。

type ServerSuiteOption

type ServerSuiteOption func(*serverSuiteConfig)

ServerSuiteOption 是 NewServerSuite 的配置选项函数类型。

func WithLimitReporter

func WithLimitReporter(r klimiter.LimitReporter) ServerSuiteOption

WithLimitReporter 注入限流过载上报器（kitex 在连接/QPS 超限拒绝请求时回调）。 未注入时默认使用内置的节流日志上报（每类事件至多每秒一条 Warn）。

func WithLimiter

func WithLimiter() ServerSuiteOption

WithLimiter 启用 limiter 策略热更新。