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 ¶
- Variables
- type ConfigStore
- func (c *ConfigStore) Close(_ context.Context) error
- func (c *ConfigStore) GetConfig(ctx context.Context, dataID, group string) (string, error)
- func (c *ConfigStore) ListenConfig(ctx context.Context, dataID, group string, onChange func(data string)) error
- func (c *ConfigStore) PutConfig(ctx context.Context, dataID, group, content string) error
- func (c *ConfigStore) StopListenConfig(_ context.Context, dataID, group string) error
- type Discoverer
- type Option
- type OptionFunc
- type Registrar
- type Subscriber
Constants ¶
This section is empty.
Variables ¶
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 同口径。
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) 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) 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 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) Deregister ¶
Deregister 注销实例:停止监护 → Revoke 租约(键随租约原子删除)。 未注册或已注销的实例为 no-op。
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 退出时自清,不会随 退订次数累积。