registry

package
v0.3.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package registry 是 github.com/oekit/registry SPI 的 etcd 实现: Registrar(Lease + KeepAlive 注册,租约丢失自动重注册)、Discoverer (prefix 拉取)、Subscriber(prefix Watch 推送)、ConfigStore(KV Watch 配置监听)。上层 nns 等依赖 SPI 接口而非本包,可与 registry/nacos 互换。

键布局

<prefix>/services/<group>/<service>/<ip:port>  → 实例 JSON(含 weight/metadata/cluster)
<prefix>/configs/<group>/<dataID>              → 配置内容字符串

prefix 默认 "/oekit/registry",group 默认 "DEFAULT_GROUP"。

键路径段(group/service/dataID/ip)不得含 "/":键空间按 "/" 分层,段内 出现 "/" 会与分隔符不可区分,前缀扫描/键构造越界到其他服务的键空间 (#110)。注册/发现/订阅/配置入口对含 "/" 的名称 fail-fast,键布局本身 不变,既有干净键完全兼容。

健康语义

etcd 没有独立的健康状态:实例键绑定 Lease(默认 30s TTL + 自动续约), 进程崩溃后租约到期键自动消失,因此 Discover 与 DiscoverAll 返回同一集合。

用法

import (
    regcore "github.com/oekit/registry"
    "github.com/oekit/etcdx/registry"
)

reg, err := registry.NewRegistrar(cli, registry.WithPrefix("/myapp"), registry.WithTTL(15*time.Second))
if err != nil {
    return err
}
_ = reg.Register(ctx, regcore.Instance{Service: "user", IP: "10.0.0.1", Port: 8080})
defer reg.Close(ctx)

disc, err := registry.NewDiscoverer(cli, registry.WithPrefix("/myapp"))
if err != nil {
    return err
}
insts, _ := disc.Discover(ctx, "user")

与 SPI 同名包 co-import 时请为本包起别名(如 etcdreg)。

Index

Constants

This section is empty.

Variables

View Source
var ErrNilClient = errors.New("etcdx/registry: client must be non-nil")

ErrNilClient 表示构造时传入了 nil 的 etcd client。

构造期 fail-fast:client 为 nil 时,任何一次实际访问(Register / Discover / Subscribe / PutConfig……)都会在 `cli.Get`/`cli.Put` 上空指针崩溃——错误发生在 **离构造点很远**的地方(往往是生产环境第一次注册服务时),堆栈里只有 etcd 内部帧,看不出「是构造时没传 client」。构造期报错把这道接线错误挡在启动 阶段。

与 registry/nacosimpl 的 ErrNilClient 同口径。

View Source
var ErrRegistrarClosed = errors.New("etcdx registry: registrar closed")

ErrRegistrarClosed 表示注册器已 Close(终态):此后 Register 永远失败。

关闭竞态(Register 进行中 Close 完成落闸)与优雅停机后的调用方需要区分 「停止重试」与「瞬时失败」——此前这个明确的终态类别只返回裸 fmt.Errorf,调用方只能 strings.Contains 文案匹配(#131),两处重复文案 今后还可能漂移。与 ErrNilClient 同为哨兵,errors.Is 判定。

Functions

This section is empty.

Types

type ConfigStore

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

ConfigStore 是 regcore.ConfigStore 的 etcd 实现:配置即一个 KV, 监听即 Watch 该键。

func NewConfigStore

func NewConfigStore(cli *clientv3.Client, opts ...OptionFunc) (*ConfigStore, error)

NewConfigStore 创建 etcd 配置源。

client 为 nil 时返回 ErrNilClient(构造期 fail-fast,避免首次读写时在 cli.Get/cli.Put 上空指针崩溃)。

func (*ConfigStore) Close

func (c *ConfigStore) Close(_ context.Context) error

Close 停止全部监听。

被取消的句柄同样转入 retired 待退出槽位(#149,与 StopListenConfig 同 口径;单源见 watchRegistry.closeAll):Close 之后立即重建监听仍须等旧 goroutine 退出,回调不并发。

func (*ConfigStore) GetConfig

func (c *ConfigStore) GetConfig(ctx context.Context, dataID, group string) (string, error)

GetConfig 拉取配置内容;键不存在返回空字符串(非错误)。

func (*ConfigStore) ListenConfig

func (c *ConfigStore) ListenConfig(ctx context.Context, dataID, group string, onChange func(data string)) error

ListenConfig 监听配置变更:Put 事件回调新内容,Delete 事件回调空字符串。 不回放当前值(需要初值请先 GetConfig)。回调在监听专属 goroutine 中串行 执行(不会并发调用 onChange)。onChange panic 不会终结监听循环:panic 被 就地 recover 转 Error 日志(含调用栈),本次投递跳过,后续变更照常推送 (#87)。同一键重复监听会替换旧监听:旧观察 goroutine 被标记取代并取消,其未投递的过期内容被丢弃,新监听等旧 goroutine 退出后才开始投递,新旧回调从不错峰并发(#84)。替换不阻塞 ListenConfig 调用方,但旧回调永久阻塞会拖住新监听的首次投递。监听生命 周期与传入 ctx 无关,由 StopListenConfig 终止。停听(StopListenConfig) 或 Close 之后立即重建监听同样遵守 #84 交接:被摘除的旧句柄保留在 retired 待退出槽位,新监听仍能等到其退出后才投递(#149)。

func (*ConfigStore) PutConfig

func (c *ConfigStore) PutConfig(ctx context.Context, dataID, group, content string) error

PutConfig 写入配置(SPI 之外的便捷方法:供运维脚本/测试灌配置)。

func (*ConfigStore) StopListenConfig

func (c *ConfigStore) StopListenConfig(_ context.Context, dataID, group string) error

StopListenConfig 停止监听(未监听为 no-op)。

摘除的句柄先进入 retired 待退出槽位而非直接丢弃(#149,与 Subscriber.Unsubscribe 同口径;摘除/槽位逻辑单源见 watchRegistry.remove, #185):其观察 goroutine 可能仍在执行消费方回调,后续同键 ListenConfig 靠该槽位拿到 old.done 完成 #84 交接——先删表再 supersede 会让交接整段 失效(停听后重建监听与旧回调并发)。本方法不等待旧回调返回;槽位由观察 goroutine 退出时自清。

type Discoverer

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

Discoverer 是 regcore.Discoverer 的 etcd 实现:按服务前缀一次 Get 拉取全部实例。

func NewDiscoverer

func NewDiscoverer(cli *clientv3.Client, opts ...OptionFunc) (*Discoverer, error)

NewDiscoverer 创建 etcd 发现器。

client 为 nil 时返回 ErrNilClient(构造期 fail-fast,避免首次发现时在 cli.Get 上空指针崩溃)。

func (*Discoverer) Discover

func (d *Discoverer) Discover(ctx context.Context, serviceName string) ([]regcore.Instance, error)

Discover 返回服务当前存活实例(按地址排序,结果确定);无实例返回 regcore.ErrNoInstances。

func (*Discoverer) DiscoverAll

func (d *Discoverer) DiscoverAll(ctx context.Context, serviceName string) ([]regcore.Instance, error)

DiscoverAll 与 Discover 返回同一集合:etcd 无独立健康状态,死实例已随 租约到期自动消失;区别仅在无实例时返回空切片而非 ErrNoInstances。

type Option

type Option struct {
	// Prefix 是全部键的根前缀(默认 "/oekit/registry"),自动去尾部 "/"。
	Prefix string
	// Group 是 Instance.Group 为空时使用的默认分组(默认 "DEFAULT_GROUP")。
	Group string
	// TTL 是注册租约时长(默认 30s;etcd 服务端可能上调至其最小租约 TTL)。
	TTL time.Duration
}

Option 是本包各组件的共享配置。

type OptionFunc

type OptionFunc func(*Option)

OptionFunc 配置函数类型。

func WithGroup

func WithGroup(group string) OptionFunc

WithGroup 设置默认分组。

func WithPrefix

func WithPrefix(prefix string) OptionFunc

WithPrefix 设置键根前缀。

func WithTTL

func WithTTL(ttl time.Duration) OptionFunc

WithTTL 设置注册租约时长(秒级精度,不足 1s 按 1s 计)。

type Registrar

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

Registrar 是 regcore.Registrar 的 etcd 实现:实例键绑定 Lease 并由后台 监护 goroutine 持续 KeepAlive;租约丢失(网络分区、etcd 重启)后自动 指数退避重注册,直到 Deregister/Close 显式停止。

func NewRegistrar

func NewRegistrar(cli *clientv3.Client, opts ...OptionFunc) (*Registrar, error)

NewRegistrar 创建 etcd 注册器。

client 为 nil 时返回 ErrNilClient(构造期 fail-fast,避免首次注册时在 cli.Put 上空指针崩溃)。

func (*Registrar) Close

func (r *Registrar) Close(ctx context.Context) error

Close 注销全部实例并拒绝后续 Register(幂等)。

func (*Registrar) Deregister

func (r *Registrar) Deregister(ctx context.Context, inst regcore.Instance) error

Deregister 注销实例:停止监护 → Revoke 租约(键随租约原子删除)。 未注册或已注销的实例为 no-op。

func (*Registrar) Register

func (r *Registrar) Register(ctx context.Context, inst regcore.Instance) error

Register 注册实例:Grant 租约 → Put 带租约的实例键 → 启动监护 goroutine。 同一实例重复 Register 视为刷新(旧监护停止、旧租约撤销后重新注册); 同 key 并发 Register 被串行化(#67,见 registerMu)——后到者整体替换 先到者的注册,先到者的监护 goroutine 与租约必被回收,不会孤儿化。 注册成功返回后,续约与重注册与调用方 ctx 无关,由 Deregister/Close 终止。

type Subscriber

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

Subscriber 是 regcore.Subscriber 的 etcd 实现:Watch 服务前缀,任一实例 键增删改后重新拉取全量快照回调。订阅建立时立即回调一次当前快照。

func NewSubscriber

func NewSubscriber(cli *clientv3.Client, opts ...OptionFunc) (*Subscriber, error)

NewSubscriber 创建 etcd 订阅器。

client 为 nil 时返回 ErrNilClient(构造期 fail-fast,避免首次订阅时在 cli.Get 上空指针崩溃)。

func (*Subscriber) Close

func (s *Subscriber) Close(_ context.Context) error

Close 取消全部订阅。

被取消的句柄同样转入 retired 待退出槽位(#149,与 Unsubscribe 同口径; 单源见 watchRegistry.closeAll):Close 之后立即重建订阅仍须等旧 goroutine 退出,回调不并发。

func (*Subscriber) Subscribe

func (s *Subscriber) Subscribe(ctx context.Context, serviceName string, cb func([]regcore.Instance)) error

Subscribe 订阅服务实例变更:订阅建立后先回调一次当前快照,随后后台 Watch 推送增量——首次快照与后续事件走同一条订阅 goroutine 串行投递路径(#84)。 回调在订阅专属 goroutine 中串行执行(**不会并发调用 cb**),回调内阻塞会 延迟后续事件处理。cb panic 不会终结观察循环:panic 被就地 recover 转 Error 日志(含调用栈),本次投递跳过,后续变更照常推送(#87)。同一服务 重复订阅会替换旧订阅:旧观察 goroutine 被标记 取代并取消,其未投递的过期快照被丢弃;新订阅等旧 goroutine 退出后才开始 投递,新旧回调从不错峰并发(#84)。替换不阻塞 Subscribe 调用方,但旧回调 永久阻塞会拖住新订阅的首次投递——不要在回调内阻塞,也不要在回调内对同一 服务再次 Subscribe。订阅生命周期与传入 ctx 无关,由 Unsubscribe 终止。 退订(Unsubscribe)或 Close 之后立即重建订阅同样遵守 #84 交接:被摘除的 旧句柄保留在 retired 待退出槽位,新订阅仍能等到其退出后才投递(#149—— 此前先删 map 再 supersede,重建订阅读到 old==nil,交接被绕过)。

func (*Subscriber) Unsubscribe

func (s *Subscriber) Unsubscribe(_ context.Context, serviceName string) error

Unsubscribe 取消订阅(未订阅为 no-op)。

摘除的句柄先进入 retired 待退出槽位而非直接丢弃(#149;摘除/槽位逻辑 单源见 watchRegistry.remove,#185):其观察 goroutine 可能仍在执行消费方 回调,后续同服务 Subscribe 靠该槽位拿到 old.done 完成 #84 交接——先删表 再 supersede 会让交接整段失效(退订后重建订阅与旧回调并发)。本方法不 等待旧回调返回(不阻塞退订方);槽位由观察 goroutine 退出时自清,不会随 退订次数累积。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL