registry

README

registry

注册发现与配置基础设施——SPI/Nacos 实现/Nacos 配置源/sdbridge

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

安装

go get github.com/oekit/registry@v0.4.0

这个仓库做什么

registry 是注册发现与配置的基础设施层：provider 无关的服务注册/发现/订阅/配置 SPI、Nacos 落地实现、Nacos 客户端门面、Nacos 配置源适配，以及跨框架的服务发现桥接。 本地配置文件加载（YAML/env/.env）已迁至 core/config。

组成

包	做什么
registry（模块根）	SPI：Registrar/Discoverer/Subscriber/ConfigStore + 实例模型 + 注册地址解析（netutil）。hertz/kitex 适配器面向它编程。v0.4.0 起自 registry/registry 子目录提升至模块根
nacosimpl	Nacos SPI 实现（nacos-sdk-go v2；原 registry/registry/nacos）
sdbridge	服务发现适配器共享核心（拉取+校验+错误包装），oekit/hertz 与 oekit/kitex 复用
registrymocks	四接口的统一测试 mock
nacos	Nacos 客户端门面（nns 默认构造用）

快速使用

import nacosimpl "github.com/oekit/registry/nacosimpl"

reg, _ := nacosimpl.NewRegistrar(namingCli)    // 服务注册
disc, _ := nacosimpl.NewDiscoverer(namingCli)  // 服务发现

import (
    "github.com/oekit/core/config"   // 本地配置文件（已迁 core）
    nacosreg "github.com/oekit/registry/nacos"
)

cfg, _ := config.LoadBootstrap[MyConfig]("dev") // etc/config-dev.yaml
// Nacos 配置源（实现 core/config.ConfigSource，配 ConfigWatcher 热更新）：
// src := nacosreg.NewConfigClient(...); nacosreg.NewConfigSource(cli, bootstrapCfg)

边界

• Kitex/Hertz 的注册发现适配器分属 kitex 与 hertz
• 服务治理高级语义（熔断/换实例重试）在 nns

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

模块	内容	矩阵内依赖
pkg	微工具集 19 合 1（errors/bloomx/contextx/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/cache/bufiox/strmap；v0.10.0 起 uidgen/validator 拆至 kitx）；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 单级时间轮；v0.5.0 起 retry 指数退避+抖动（MaxDelay 封顶/溢出饱和）、loop 周期原语（忙时丢 tick/单轮 panic 收编/FirstDelay 可打断）、async labeled RunSafe（panic 按任务标签上报）、syncx.FanInErr 逐槽错误（panic 槽显式标记）、KeyedLimiter 增强（容量护栏/RetryAfter/速率热更）并接入 pkg/singleflighttest 契约测试	pkg
logx	统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入	—
core	应用基建件（governance 治理 schema / config 配置加载 + default/env/range/options tag 校验 / lifecycle 契约 / network IP 工具 / version）	—
kitx	标识与校验——uidgen（Snowflake 全局单例+Extract 元数据、手写 RFC 4122 v4 UUID 零第三方依赖、RandomHex/RandomString 拒绝采样随机串）+ validator（go-playground/validator v10 接口化门面：struct tag 校验/自定义规则注册/ValidationError Unwrap 为 BizError 400 对接 middleware.Fail），自 pkg v0.10.0 拆出	pkg
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、心跳续约）；v0.1.5 起可选可靠投递 DeliveryAtLeastOnce（租约 + Ack + 可见性超时；过期租约回扫重投/死信、停机 best-effort 收租，v0.1.7 接入生命周期真正生效）	concurrency、logx
middleware	Hertz 自研标准中间件栈 + contrib 桥接 + hmw + SheddingMiddleware 自适应降载；v0.6.0 起 accesslog 凭证路径脱敏（WithAccessLogRedactPathPrefixes）、ratelimit 默认 KeyFunc 去端口（连接桶→地址桶）	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（基于 kitx/validator）/versionh（原 handler 微库收编）	bootstrap、concurrency、core、gormx、kitx、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

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE

Documentation

Overview

Package registry 提供与服务注册中心无关的服务注册与发现抽象接口。

本包定义核心接口（Registrar、Discoverer、Subscriber、ConfigStore）， 不依赖任何具体的注册中心 SDK。各注册中心（如 Nacos）的实现放在子包中 （例如 registry/nacos）。

注意：registry 是底层 SPI 和框架薄适配，只供 NNS、测试、极简接入使用。 不包含缓存、降级、singleflight 等治理能力。新服务推荐通过 nns 包接入。

设计目标

• 解耦：上层（如 nns 包）依赖接口而非具体 SDK，便于测试和替换实现。
• 可测试：通过接口可以轻松注入 mock，解决上层核心逻辑难以测试的问题。
• 可扩展：未来新增 etcd/consul/k8s 等实现时，上层无需改动。

三层架构

ekit/nacos              SDK 薄封装（Bootstrap 配置、client 工厂、config 加载）
ekit/registry           provider 无关的抽象接口（本包）
ekit/registry/nacos     Nacos 实现（封装 naming_client/config_client）

上层门面 nns 依赖 registry 接口，默认使用 registry/nacos 实现， 也可通过依赖注入替换为 mock 或其他 provider。

快速接入

使用 Nacos 实现：

reg, err := nacosimpl.NewRegistrar(namingClient, nacosimpl.WithGroup("DEFAULT_GROUP"))
if err != nil {
    log.Fatal(err)
}
err = reg.Register(ctx, registry.Instance{
    Service:  "my-service",
    IP:       "10.0.0.1",
    Port:     8080,
    Metadata: version.Metadata(),
})

发现服务实例：

disc, err := nacosimpl.NewDiscoverer(namingClient)
instances, err := disc.Discover(ctx, "user-service")

Index

• Variables
• func EncodeTargetTags(host string, tags map[string]string) string
• func ParseAddr(addr net.Addr) (string, int, error)
• type ConfigStore
• type Discoverer
• type Instance
  • func InfoFrom(name string, addr net.Addr, weight, defaultWeight int, tags map[string]string) (Instance, error)
  • func (i Instance) Addr() string
• type RegisterOption
  • func Apply(opts ...RegisterOptionFunc) *RegisterOption
• type RegisterOptionFunc
  • func WithCluster(cluster string) RegisterOptionFunc
  • func WithGroup(group string) RegisterOptionFunc
  • func WithMetadata(metadata map[string]string) RegisterOptionFunc
  • func WithWeight(weight float64) RegisterOptionFunc
• type Registrar
• type Subscriber

Variables

var ErrNoInstances = errors.New("registry: no instances found")

ErrNoInstances 表示服务发现未找到任何实例。

Functions

func EncodeTargetTags

func EncodeTargetTags(host string, tags map[string]string) string

EncodeTargetTags 将 host 和 tags 编码为确定性的缓存 key。 tags 的 key 按字典序排序，确保相同 tags 产生相同结果（Go map 迭代顺序不确定）。 当 tags 为空时直接返回 host。

func ParseAddr

func ParseAddr(addr net.Addr) (string, int, error)

ParseAddr 从 net.Addr 解析出 IP 和端口号。 当 host 为未指定地址（空、"::" 或 "0.0.0.0"——kitex/hertz 对 ":9090" 这类 通配监听时，listener.Addr() 与 WithServiceAddr 会产生这些形式）时， 自动使用 network.GetPodIP() 获取本机 IP（支持 K8s POD_IP），保证注册出去 的实例地址对其他节点可拨号。 这是 ekit 中解析注册地址的唯一实现，kitex/registry、hertz/registry、kitex/nns 应委托至此，避免逻辑重复。

Types

type ConfigStore

type ConfigStore interface {
	// GetConfig 拉取指定 dataID 的配置内容。
	//
	// 返回空字符串表示配置不存在（非错误）。
	GetConfig(ctx context.Context, dataID, group string) (string, error)

	// ListenConfig 监听指定 dataID 的配置变更，内容变化时回调 onChange。
	//
	// onChange 接收最新的配置内容字符串。实现应确保回调在独立 goroutine
	// 中执行或不会阻塞监听循环。
	ListenConfig(ctx context.Context, dataID, group string, onChange func(data string)) error

	// StopListenConfig 停止监听指定 dataID 的配置变更。
	StopListenConfig(ctx context.Context, dataID, group string) error
}

ConfigStore 提供服务配置的拉取和动态监听能力。

这与服务发现（Discoverer/Subscriber）是正交关注点： 服务发现返回实例列表（IP/Port），而 ConfigStore 返回服务的运行时配置 （如超时、重试、负载均衡策略等，通常以 JSON 等格式存储）。

nns 包的 ServiceClient 同时使用 ConfigStore 和服务发现接口， 将配置和实例信息组合为完整的 ServiceBasic。

type Discoverer

type Discoverer interface {
	// Discover 根据服务名称返回健康实例列表。
	Discover(ctx context.Context, serviceName string) ([]Instance, error)

	// DiscoverAll 根据服务名称返回全部实例列表（包括不健康的实例）。
	// 用于调试、监控等场景；生产调用应优先使用 Discover。
	DiscoverAll(ctx context.Context, serviceName string) ([]Instance, error)
}

Discoverer 提供服务实例的拉取发现能力。

type Instance

type Instance struct {
	// Service 是服务名称。
	Service string
	// IP 是实例的 IP 地址。
	IP string
	// Port 是实例的端口。
	Port int
	// Weight 是实例的权重，用于加权负载均衡。
	Weight float64
	// Metadata 是实例的元数据，可携带版本、颜色、区域等信息。
	Metadata map[string]string
	// Group 是分组名称。空值时使用 Registrar 的默认 Group。
	Group string
	// Cluster 是集群名称。空值时使用 Registrar 的默认 Cluster。
	Cluster string
}

Instance 表示注册中心中的一个服务实例，与具体 provider 无关。

func InfoFrom

func InfoFrom(name string, addr net.Addr, weight, defaultWeight int, tags map[string]string) (Instance, error)

InfoFrom 从通用字段构造 Instance，内部调用 ParseAddr 解析地址。

name 是服务名称，addr 是注册地址（如 *net.TCPAddr）， weight 是实例权重（<=0 时使用 defaultWeight），tags 是元数据。 defaultWeight 用于 weight<=0 的回退值。

func (Instance) Addr

func (i Instance) Addr() string

Addr 返回实例的地址字符串，格式为 "IP:Port"。

type RegisterOption

type RegisterOption struct {
	// Weight 是实例权重，默认 10。
	Weight float64
	// Metadata 是实例元数据。
	Metadata map[string]string
	// Cluster 是集群名称（部分 provider 支持）。
	Cluster string
	// Group 是分组名称（部分 provider 支持）。
	Group string
}

RegisterOption 是服务注册的可选配置，与具体 provider 无关。

各 provider 实现会将这些字段映射到自身 SDK 的参数。 如果某个字段在目标 provider 中不存在，实现应安全地忽略它。

func Apply

func Apply(opts ...RegisterOptionFunc) *RegisterOption

Apply 将多个选项函数应用到一个新的 RegisterOption 上，返回最终配置。

用法：

opt := Apply(registry.WithWeight(20), registry.WithMetadata(meta))

type RegisterOptionFunc

type RegisterOptionFunc func(*RegisterOption)

RegisterOptionFunc 是配置 RegisterOption 的函数选项类型。

func WithCluster

func WithCluster(cluster string) RegisterOptionFunc

WithCluster 设置服务实例所属的集群名称。

func WithGroup

func WithGroup(group string) RegisterOptionFunc

WithGroup 设置服务实例所属的分组名称。

func WithMetadata

func WithMetadata(metadata map[string]string) RegisterOptionFunc

WithMetadata 设置服务实例的元数据。

多次调用会合并而非覆盖。

func WithWeight

func WithWeight(weight float64) RegisterOptionFunc

WithWeight 设置服务实例的权重。

type Registrar

type Registrar interface {
	// Register 将服务实例注册到注册中心。
	Register(ctx context.Context, inst Instance) error
	// Deregister 从注册中心注销服务实例。
	Deregister(ctx context.Context, inst Instance) error
}

Registrar 提供服务实例的注册和注销能力。

type Subscriber

type Subscriber interface {
	// Subscribe 订阅指定服务的实例变更，当实例列表变化时回调 cb。
	Subscribe(ctx context.Context, serviceName string, cb func([]Instance)) error
	// Unsubscribe 取消订阅指定服务的实例变更。
	Unsubscribe(ctx context.Context, serviceName string) error
}

Subscriber 提供服务实例变更的订阅推送能力。