Help us shape the future of Go! Take the 2026 Go Developer Survey

nns

package module
v0.4.0 Latest Latest
Warning

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

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

README

nns

NNS 服务治理门面——一行创建/mock 模式/实例缓存与降级

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

安装

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

这个仓库做什么

nns 是 NNS 服务治理门面：provider 无关的服务发现、配置订阅、实例缓存、多级降级。 nns.New 一行创建，mock 模式让本地开发零 Nacos 依赖。

快速使用

import (
    nns "github.com/oekit/nns"
    nacospkg "github.com/oekit/registry/nacos"
)

// 生产：默认对接 Nacos；本地：WithMockMode(true) 零外部依赖
c := nns.New(nacospkg.Bootstrap{ServiceName: "my-service"},
    nns.WithMockMode(true),
    nns.WithStaticInstance("dep-svc", []registry.Instance{{IP: "10.0.0.1", Port: 9000}}))

_ = c.Init(ctx, "my-service", []string{"dep-svc"})
insts, _ := c.GetInstances(ctx, "dep-svc")
defer c.Close() // 终结化：注销订阅 + 关闭 SDK 连接（幂等）

关键语义

  • Close 是终结操作：默认路径下 SDK gRPC 连接已关闭，复用需重新 New
  • ServiceClient() 是逃生口：暴露底层客户端给适配器与端点工厂
  • bootstrap 集成：RunWithLifecycle(app, "svc", port, opts...) 自动注册/注销

边界

矩阵总览（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 nns 提供 Nacos Naming Service 高级封装，是 ekit 服务治理的官方推荐入口。

基于 registry 接口构建，提供 mock、静态实例、缓存、singleflight、多级降级等治理能力。 新服务应通过 NNSClient 接入，而非直接使用 registry/* 薄适配。

核心特性

  • 构造注入：每次 New 返回独立实例，推荐通过构造注入传递，不依赖全局状态
  • 服务初始化：自动加载本地和依赖服务配置
  • HTTP/gRPC Endpoint：自动生成服务端点
  • 服务注册/注销：与 Nacos Naming 集成
  • 实例订阅：实时监听服务实例变更
  • 多级降级：静态实例 > 缓存 > 注册中心
  • 框架适配：通过 ServiceClient() 暴露给 nns/kitex、nns/hertz 适配器

快速接入

创建 NNSClient（推荐通过构造注入传递）： 

ctx := context.Background()
nnsc := nns.New(cfg)
err := nnsc.Init(ctx, "my-service", []string{"user-service", "order-service"})
if err != nil {
    log.Fatal(err)
}
defer nnsc.Close()

注册服务： 

err = nnsc.Register(ctx, port, registry.WithMetadata(version.Metadata()))

获取服务实例： 

instances, err := nnsc.GetInstances(ctx, "user-service")

创建 HTTP Endpoint： 

endpoint, err := nnsc.MakeHTTPEndpoint("user-service")

框架适配： 

// Kitex
cli, _ := echo.NewClient("dep",
    client.WithResolver(nnskitex.NewResolver(nnsc.ServiceClient())))
svr, _ := echo.NewServer(handler,
    server.WithRegistry(nnskitex.NewRegistry(nnsc.ServiceClient())))

// Hertz
cli.Use(sd.Discovery(nnshertz.NewResolver(nnsc.ServiceClient())))
svr := server.New(..., server.WithRegistry(nnshertz.NewRegistry(nnsc.ServiceClient())))

配置选项

  • WithCacheExpiry: 缓存过期时间，默认 30s
  • WithMockMode: 启用模拟模式（本地开发）
  • WithStaticInstances: 静态实例配置
  • WithLocalServiceConfig: 本地服务配置（不从 Nacos 获取）

与 bootstrap 集成

使用 bootstrap.Run 并设置 DepServices 自动初始化 NNS： 

b, _ := bootstrap.New(bootstrap.WithServiceName("my-service"),
    bootstrapnacos.WithNNS(nacosCfg, port, []string{"dep.service"})) // bootstrap/nacos
b.Run(func(app *bootstrap.App) error {
    // ...
})

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type NNSClient 

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

NNSClient NNS 服务客户端，封装了服务发现、负载均衡和端点管理功能。

门面是 provider 选择点：nns.New(cfg) 负责把 Nacos 配置构造为 registry/nacos 实现并注入 provider 无关的 ServiceClient（2026-09-19 重构：默认构造从 nns/client 上提至此，治理核心不再绑定 provider）。

func New 

func New(cfg nacos.Bootstrap, opts ...NNSOption) *NNSClient

New 创建 NNS 客户端。 cfg 是 Nacos 连接配置，opts 可选配置 mock 模式、静态实例、缓存过期等。 返回的 NNSClient 需调用 Init 初始化后使用。

Provider 默认构造（非 mock 时）：创建 naming/config SDK 客户端并注入 registry/nacos 的 Discoverer/Subscriber/Registrar/ConfigStore；构造失败 只 Warn 降级（缓存/静态实例路径），不阻断启动——与既有降级语义一致。 默认路径创建的 SDK 客户端归本实例所有，Close 时释放。

func (*NNSClient) AddStaticInstance 

func (n *NNSClient) AddStaticInstance(serviceName string, instances ...registry.Instance)

AddStaticInstance 向指定服务追加静态实例地址。

func (*NNSClient) Close 

func (n *NNSClient) Close()

Close 关闭 NNSClient 持有的所有资源（ServiceClient 的配置/实例订阅、 回调状态、门面默认路径创建的 Nacos SDK 客户端）。 Close 是终结操作：默认路径下 SDK gRPC 连接已关闭，复用需重新 New。 端点工厂自 Round-4 起移至 ekit-nns-endpoint，其生命周期由构造方管理。

func (*NNSClient) Deregister 

func (n *NNSClient) Deregister(ctx context.Context, port int, opts ...registry.RegisterOptionFunc) error

Deregister 从注册中心注销当前服务实例。

func (*NNSClient) GetAllInstances 

func (n *NNSClient) GetAllInstances(ctx context.Context, serviceName string) ([]registry.Instance, error)

GetAllInstances 获取指定服务的全部实例列表（包括不健康的实例）。

func (*NNSClient) GetInstances 

func (n *NNSClient) GetInstances(ctx context.Context, serviceName string) ([]registry.Instance, error)

GetInstances 获取指定服务的健康实例列表。

func (*NNSClient) GetService 

func (n *NNSClient) GetService(ctx context.Context, serviceName string) (*metadata.ServiceBasic, error)

GetService 获取指定服务的基本配置信息。

func (*NNSClient) Init 

func (n *NNSClient) Init(ctx context.Context, serviceName string, depServices []string) error

Init 初始化本地服务并加载依赖服务配置，同时监听本地服务及所有依赖服务的配置变更（支持热更新）。

func (*NNSClient) Register 

func (n *NNSClient) Register(ctx context.Context, port int, opts ...registry.RegisterOptionFunc) error

Register 向注册中心注册当前服务实例。

func (*NNSClient) ServiceClient 

func (n *NNSClient) ServiceClient() *client.ServiceClient

ServiceClient 返回底层 *client.ServiceClient，供 nns/kitex、nns/hertz 等适配器使用。

推荐用法： 

nnskitex.NewResolver(nnsc.ServiceClient())
nnshertz.NewRegistry(nnsc.ServiceClient())

不应绕过此访问器直接访问内部 ServiceClient 字段。

func (*NNSClient) SetStaticInstances 

func (n *NNSClient) SetStaticInstances(serviceName string, instances []registry.Instance)

SetStaticInstances 设置指定服务的静态实例列表（覆盖原有）。

func (*NNSClient) Subscribe 

func (n *NNSClient) Subscribe(ctx context.Context, serviceName string, callback func([]registry.Instance)) error

Subscribe 订阅指定服务的实例变更，当实例列表变化时回调 callback。

func (*NNSClient) Unsubscribe 

func (n *NNSClient) Unsubscribe(ctx context.Context, serviceName string) error

Unsubscribe 取消订阅指定服务的实例变更。

type NNSOption 

type NNSOption func(*clientOptions)

NNSOption NNSClient 的配置选项函数类型。

func WithCacheExpiry 

func WithCacheExpiry(d time.Duration) NNSOption

WithCacheExpiry 设置实例缓存的过期时间。

func WithLocalServiceConfig 

func WithLocalServiceConfig(serviceName string, basic *metadata.ServiceBasic) NNSOption

WithLocalServiceConfig 配置本地服务配置（不从 Nacos 获取） 用于本地开发或测试环境，直接指定服务的超时、重试等配置

func WithMockMode 

func WithMockMode(enabled bool) NNSOption

WithMockMode 设置是否启用 Mock 模式，Mock 模式下不连接 Nacos。

func WithStaticInstance 

func WithStaticInstance(serviceName string, instances []registry.Instance) NNSOption

WithStaticInstance 配置指定服务的静态实例列表，用于本地开发或特殊场景。

Source Files

View all Source files

Directories

Path Synopsis
Package client 提供 NNS（enjoydream Naming Service）治理核心： 服务发现、配置管理、实例订阅与注册的 provider 无关实现。
 Package client 提供 NNS（enjoydream Naming Service）治理核心： 服务发现、配置管理、实例订阅与注册的 provider 无关实现。
Package metadata 定义了 NNS（enjoydream Naming Service）中使用的核心元数据类型和常量。
 Package metadata 定义了 NNS（enjoydream Naming Service）中使用的核心元数据类型和常量。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.