用户指南 :: Zeus

注册中心

Mon, 01 Jan 0001 00:00:00 +0000

注册中心三层模型对齐 K8s Endpoints + Istio ServiceEntry：概念说明 Instance 实例（一个进程的一个端口），含 Id/Name/Cluster/Protocol/Ip/Port/Metadata/Labels Cluster 集群（同名+同 cluster 的实例集合，按 cluster 路由的候选池） ServiceEntry 逻辑服务（同名实例的集合）注册/反注册最小单位是 *types.Instance。多协议应用注册多条 Instance（每条带 Protocol 字段，如 http/grpc）。内置实现 1import "github.com/go-zeus/zeus/registry/memory" 2 3reg := memory.New() registry/memory 是进程内实现，零依赖，主要用于单进程 demo 和单测 mock。 plugins 实现 1import _ "github.com/go-zeus/zeus/plugins/registry/etcd" 通过 import _ 副作用注册 etcd:// scheme。 URL scheme 切换 L2 用户通过 URL 字符串切换实现：

集群路由

Mon, 01 Jan 0001 00:00:00 +0000

并行开发场景下，多个项目共享同一套服务，每个项目对应一组灰度实例（cluster）。流量通过 X-Zeus-Cluster Header 端到端路由：“有标识走标识，无标识走 default”。术语统一为 cluster，与 K8s/Istio/Envoy/gRPC xDS 对齐。传播链路 [Client] X-Zeus-Cluster: canary │ ▼ HTTP Header / gRPC metadata["x-zeus-cluster"] [Gateway (proxy)] NewDiscoverySelector 从 Header 读 cluster → 选 cluster → 转发 │ ▼ Header 透传 [HTTP Server (srv-1)] 入口 clusterInjector 自动注入 ctx │ ├─ tracing: span.Attrs["zeus.cluster"]=cluster │ ├─ metrics: labels["cluster"]=cluster │ └─ log: 自动 Field{cluster} ▼ [业务 handler] ctx 已含 cluster │ ▼ client.Do(): resolveCluster 读 ctx → 选 cluster → 注入 Header [HTTP Server (srv-2)] 同 srv-1 核心 API 1import "github.com/go-zeus/zeus/routing" 2 3// HTTP 入口注入 4ctx := routing.WithCluster(r.Context(), routing.ClusterFromHTTPHeader(r.Header)) 5 6// 业务读取 7c := routing.FromContext(ctx) 8 9// 常量 10routing.HeaderCluster // "X-Zeus-Cluster" 11routing.MetadataCluster // "x-zeus-cluster"（gRPC metadata） 12routing.Default // "default" 默认行为组件行为 server/http 默认自动注入 cluster（WithoutAutoClustering() 关闭） plugins/server/grpc 默认 UnaryServerInterceptor 从 metadata 提取 cluster 注入 ctx plugins/client/grpc UnaryInterceptor() 从 ctx cluster 注入 outgoing metadata log 包自动 prepend Field{cluster}（仅非 default 时） plugins/middleware/tracing 自动写入 span attribute zeus.cluster plugins/middleware/metrics 自动打 label cluster 治理模块按 cluster 维度 1import clusterlimit "github.com/go-zeus/zeus/ratelimit/cluster" 2import clusterbreak "github.com/go-zeus/zeus/circuitbreaker/cluster" 3import clusterretry "github.com/go-zeus/zeus/retry/cluster" 4 5// 每个 cluster key 独立桶/熔断器/重试策略 6limiter := clusterlimit.New(func() ratelimit.Limiter { return token.New(100, 10) }) 7ok := limiter.Allow(ctx) // 从 ctx 提取 cluster 作为 key 8 9cb := clusterbreak.New(func() circuitbreaker.Breaker { return counter.New(100, 0.5) }) 10err := cb.Execute(ctx, func() error { ... }) 11 12cr := clusterretry.New(func() retry.Retrier { return exponential.New(3, 100*time.Millisecond) }) 13r := cr.NewRetriever(ctx) 完整示例参见 examples/12-cluster-routing/：单进程演示 gateway → srv1 → srv2 多 cluster 路由 + cluster 全链路传播。

上下文传播

Mon, 01 Jan 0001 00:00:00 +0000

propagation 包提供 W3C Baggage 兼容的跨进程 K-V 上下文传播，扩展自单一 X-Zeus-Cluster Header，支持用户自定义任意 K-V（如 tenant.id / feature.flag / region）的全链路透传。与 routing 的关系维度 routing propagation 范围仅 zeus.cluster 单字段任意 K-V 协议 X-Zeus-Cluster Header / gRPC metadata Baggage Header（W3C 标准）实现基于 propagation，同步到 Bag W3C baggage 编解码 + Bag/Entry 数据结构 routing.WithCluster 同时写入 ctx 本地值 + propagation Bag，routing.FromContext 优先读 ctx 本地值，缺失时从 Bag 兜底。自动传播矩阵（用户零感知）位置行为 server/http 入口 clusterInjector 自动 ExtractHTTP 注入 ctx plugins/server/grpc 入口 clusterInterceptor 自动 ExtractMetadataMulti client.Do 出口自动 InjectHTTP 写入 Baggage Header plugins/client/grpc 出口 UnaryInterceptor 自动 InjectMetadataMulti proxy 反向代理 HTTP Header 自然透传（httputil.ReverseProxy 默认行为） log 包自动从 ctx 读 baggage entries 写成 Field plugins/middleware/tracing 自动写 span attribute（每个 K-V 一个） plugins/middleware/metrics 默认不加 baggage label（避免基数爆炸），用户通过 WithBaggageLabels 显式声明核心 API 1import "github.com/go-zeus/zeus/propagation" 2 3// 业务代码注入 K-V（一次性） 4ctx = propagation.With(ctx, "tenant.id", "acme") 5ctx = propagation.With(ctx, "feature.flag", "beta") 6 7// 业务代码读取 8v, ok := propagation.Get(ctx, "tenant.id") 9 10// 手动注入/提取（仅在不走 zeus client/server 时需要） 11propagation.InjectHTTP(ctx, req.Header) 12ctx = propagation.ExtractHTTP(ctx, r.Header) 不自动传播的场景绕过 Zeus 抽象时需手动调用：

可观测性

Mon, 01 Jan 0001 00:00:00 +0000

三件套联动模式：构造期注入 → 中间件链自动埋点 → 优雅关闭时 batch flush。 1import ( 2 "github.com/go-zeus/zeus/middleware" 3 "github.com/go-zeus/zeus/middleware/recovery" 4 metricsmw "github.com/go-zeus/zeus/plugins/middleware/metrics" 5 tracingmw "github.com/go-zeus/zeus/plugins/middleware/tracing" 6 "github.com/go-zeus/zeus/plugins/metrics/prometheus" 7 "github.com/go-zeus/zeus/plugins/trace/otel" 8) 9 10meter := prometheus.New(prometheus.WithNamespace("zeus")) 11tracer := otel.New(otel.WithServiceName("my-app")) 12 13// 链顺序：recovery → tracing → metrics（外→内） 14chain := middleware.NewChain(recovery.New(), tracingmw.New(tracer), metricsmw.New(meter)) 15 16// /metrics 端点：mux.Handle("/metrics", prometheus.HTTPHandler()) 17// 优雅关闭时 TraceComponent.OnStop 调用 tracer.Close()，OTel batch flush 完成 Metrics 接口职责 Meter 工厂接口，创建 Counter/Histogram/Gauge Counter 单调递增计数器 Histogram 分布统计（请求耗时等） Gauge 瞬时值（连接数等）内置：metrics/noop（默认装配时使用）插件：plugins/metrics/prometheus

反向代理

Mon, 01 Jan 0001 00:00:00 +0000

proxy 包提供多协议反向代理，统一 http.Handler 入口按协议自动嗅探分流。 1import ( 2 "net/http" 3 "net/url" 4 "github.com/go-zeus/zeus/proxy" 5 "github.com/go-zeus/zeus/balancer/roundrobin" 6) 7 8// 静态模式 9target, _ := url.Parse("http://127.0.0.1:9000") 10p := proxy.New(proxy.WithSelector(proxy.NewStaticSelector(target))) 11http.ListenAndServe(":8081", p) 12 13// 动态模式（服务发现 + 集群路由） 14p := proxy.New(proxy.WithSelector( 15 proxy.NewDiscoverySelector("api-svc", dis, roundrobin.New()), 16)) 支持的协议协议实现 HTTP/HTTPS 基于 httputil.ReverseProxy，自动注入 X-Forwarded-For/X-Real-IP/X-Request-ID WebSocket Hijack + raw io.Copy 透传（nginx 风格，不解析 RFC6455 帧） SSE 禁用缓冲 + Flusher，串行 read-write-flush 保证事件顺序 gRPC 走独立 plugin 模块 plugins/proxy/grpc，独立监听端口（HTTP/2 多路复用） Selector 接口抽象后端选择：

中间件

Mon, 01 Jan 0001 00:00:00 +0000

Zeus 中间件基于 Interceptor 接口和 Chain 类型组合。内置中间件包职责 middleware/recovery panic 恢复（默认装配） middleware/requestid 请求 ID 注入（默认装配） middleware/accesslog 访问日志（默认装配） middleware/timeout 请求超时控制 middleware/clustering cluster 自动注入 plugins 中间件包职责 plugins/middleware/tracing 自动 trace 埋点 + cluster attr plugins/middleware/metrics 自动 metrics 埋点 + cluster label 链式组合 1import ( 2 "github.com/go-zeus/zeus/middleware" 3 "github.com/go-zeus/zeus/middleware/recovery" 4 metricsmw "github.com/go-zeus/zeus/plugins/middleware/metrics" 5 tracingmw "github.com/go-zeus/zeus/plugins/middleware/tracing" 6) 7 8// 链顺序：外 → 内 9chain := middleware.NewChain( 10 recovery.New(), 11 tracingmw.New(tracer), 12 metricsmw.New(meter), 13) L1 vs L3 默认链差异层默认中间件说明 L1/L2 (app.Run) requestid → accesslog → recovery（/health 等端点单独路由，非中间件）自动包装 L3 (app.NewApp) 空（用户显式 WithMiddleware）用户完全控制 L3 不自动包装的原因：用户已直接构造 http.NewHTTP()，对 server 中间件链有完全控制。

客户端

Mon, 01 Jan 0001 00:00:00 +0000

client 包提供带集群路由 + baggage 传播的 HTTP 客户端。第一参数 name 是服务名（用于服务发现查找实例）。 1import "github.com/go-zeus/zeus/client" 2 3c := client.NewClient("my-service", 4 client.Discovery(dis), // 启用服务发现（registry.Discovery） 5 client.LoadBalance(roundrobin.New()),// 负载均衡策略 6 client.WithTimeout(5*time.Second), 7) 8// ctx 经由 req 携带；client.Do 自动透传 cluster + baggage 9req, _ := http.NewRequestWithContext(ctx, http.MethodGet, "http://my-service/api", nil) 10resp, err := c.Do(req) 自动行为集成行为集群路由 resolveCluster 读 ctx 的 cluster → 选 cluster 实例 → 注入 X-Zeus-Cluster Header Baggage 传播自动 InjectHTTP(ctx, req.Header) 写入 Baggage Header Tracing 自动创建 client span（如有 tracer） Metrics 自动记录 client request latency（如有 meter）其他 Option Option 说明 WithHTTPClient(hc *http.Client) 注入底层 *http.Client WithTLS(cfg *tls.Config) 启用 TLS WithTransport(rt *http.Transport) 注入自定义 transport WithTimeout(d) 请求超时 type Client = HTTPClient 别名保留向后兼容。主包仅提供 HTTP 客户端——gRPC 等其他协议走 plugins/client/ 独立 module（HTTP/gRPC 请求模型本质不同，强行抽象会失去类型安全）。

数据库

Mon, 01 Jan 0001 00:00:00 +0000

Zeus 提供 database 包作为薄封装 stdlib 抽象，不做 ORM（用户可自由选 sqlx / gorm / ent / sqlc）。核心概念概念说明 DB / Tx / Rows / Row 薄接口，签名几乎对齐 *sql.DB（学习成本零） DBOptions 连接池配置（Driver/DSN/MaxOpenConns/…） TxOption 事务选项（WithIsolation / WithReadOnly） WithTx/FromTx 同进程事务传播（多个 Repository 共享 Tx） WithTxID/TxIDFromContext/EnsureTxID 跨服务 tx_id 传播（审计/排查用，不做 2PC） database/sql 内置实现：薄封装 stdlib *sql.DB + 自动 trace/metrics/tx_id DatabaseComponent components 适配器：OnStart Ping，OnStop Close 自动集成矩阵每次 Query/Exec 触发：

缓存

Mon, 01 Jan 0001 00:00:00 +0000

概念说明 Cache 接口：Get/Set/Delete/Has/Close（与 Redis API 对齐） Item 载体：Key/Value/TTL Option WithTTL(d)（默认无 TTL = 永久） cache/memory 内置实现：sync.Map + TTL 双路径清理（懒 + 后台周期扫描） CacheComponent components 适配器：OnStop Close（停后台 goroutine）自动集成矩阵集成行为 trace span cache.get/cache.set/cache.delete/cache.has；attrs: cache，可选 cache_key（默认关闭避免敏感数据） metrics counter cache_op_total{cache,op,status}（status: hit/miss/ok） + histogram cache_op_duration{cache,op} 使用方式 1import ( 2 "github.com/go-zeus/zeus/cache" 3 "github.com/go-zeus/zeus/cache/memory" 4) 5 6c := memory.New( 7 memory.WithTracer(tracer), 8 memory.WithMeter(meter), 9 memory.WithName("user-cache"), 10 memory.WithCleanupInterval(time.Minute), // 默认 60s 11) 12defer c.Close() 13 14_ = c.Set(ctx, "user:1", user, cache.WithTTL(5*time.Minute)) 15v, ok := c.Get(ctx, "user:1") // (user, true) 或 (nil, false) 16_ = c.Delete(ctx, "user:1") 设计权衡维度选择理由 cache 后台清理 60s 默认 + 懒清理兼顾内存与 CPU 开销 cache key 记录默认关闭避免敏感数据进入 trace 接入 Redis 1import ( 2 "github.com/redis/go-redis/v9" 3 "github.com/go-zeus/zeus/cache" 4 redis "github.com/go-zeus/zeus/plugins/cache/redis" 5) 6 7cli := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"}) 8c := redis.New(cli, redis.WithTracer(tracer), redis.WithMeter(meter)) 9defer c.Close() // 关闭 client（WithManagedClient(false) 可保留共享 client） 10 11// 复杂类型需自行序列化 12payload, _ := json.Marshal(user) 13_ = c.Set(ctx, "user:1", payload, cache.WithTTL(5*time.Minute)) 完整示例参见 examples/14-cache/：Set/Get/Has/Delete/TTL 过期。

消息队列

Mon, 01 Jan 0001 00:00:00 +0000

mq 包提供发布/订阅（pub/sub）的统一抽象，参考 Dapr Building Block 设计。概念说明 Message 消息体（Topic + Payload + Headers） Handler 消息处理函数（返回 nil=ack，error=nack） Publisher 发布者接口（Publish + Close） Subscriber 订阅者接口（Subscribe + Close） Broker 完整代理（同时实现 Publisher + Subscriber） memory.Broker 内置实现：channel fan-out，无缓冲反压，自动 baggage 注入/提取 MQComponent components 适配器：声明式注册 + 自动启停设计权衡维度选择理由抽象层级只抽象 topic / payload / headers 屏蔽 Kafka partition / RabbitMQ exchange 等厂商专属语义 ack 语义 Handler 返回 error = nack 不同实现可映射到不同动作（memory 走 ErrorHandler，Kafka 不 commit offset）内置实现进程内 channel + 无缓冲零依赖、保证不丢消息，反压慢消费者（牺牲吞吐换可靠）持久化不持久化用作单进程事件总线 / 测试 mock；生产用 plugins Baggage 传播 Publish 自动注入 msg.Headers[“baggage”]，handler 自动 extract 全链路 tenant.id / cluster 等 K-V 透传并发模型每订阅者独立 goroutine fan-out 隔离故障使用方式 1import ( 2 "github.com/go-zeus/zeus/components" 3 "github.com/go-zeus/zeus/mq" 4 "github.com/go-zeus/zeus/mq/memory" 5) 6 7// 1. 直接使用 Broker（无 components） 8broker := memory.New() 9defer broker.Close() 10 11_ = broker.Subscribe(ctx, "orders.created", func(ctx context.Context, msg *mq.Message) error { 12 return nil 13}) 14_ = broker.Publish(ctx, "orders.created", &mq.Message{Payload: []byte("order-1")}) 15 16// 2. 自动装配 17app := components.NewApp( 18 components.NewMQComponent(memory.New()), 19 components.NewMQSubscription("orders.created", handleOrder), 20 components.NewMQSubscription("log.all", handleLog), 21) 22app.Run() Baggage 自动传播位置行为 Publish 出口自动 InjectMetadata(ctx, msg.Headers)：ctx baggage → msg.Headers["baggage"]（W3C 编码） handler 入口自动 ExtractMetadata(ctx, msg.Headers)：msg.Headers["baggage"] → handler ctx Handler 内读取 propagation.Get(ctx, "tenant.id") 直接拿到完整示例参见 examples/15-mq/：3 个订阅者（不同 topic）+ baggage 全链路传播 + 优雅关闭。

任务调度

Mon, 01 Jan 0001 00:00:00 +0000

job 包提供声明式周期性任务调度抽象。概念说明 Spec 任务规格（Name + Schedule/Every + Handler + Timeout） Scheduler 调度器接口（Register/Start/Stop） interval.Scheduler 内置实现：固定间隔，每 Job 独立 goroutine + Ticker JobComponent components 适配器：声明式注册 + 自动启停 JobRegistration 单个 Job 包装为组件设计权衡维度选择理由内置调度器 time.Ticker 固定间隔零依赖、覆盖 80% 用例（心跳/上报/清理） Cron 表达式放 plugins/job/cron cron 解析复杂，且需要 robfig/cron 依赖首次执行立即执行（不延迟一个周期）心跳类任务不应延迟首次上报并发模型每 Job 独立 goroutine 隔离故障，单 Job panic 不影响其他错误处理默认 log.Error，可注入 ErrorHandler 用户可对接告警/重试系统使用方式 1import ( 2 "github.com/go-zeus/zeus/components" 3 "github.com/go-zeus/zeus/job" 4 "github.com/go-zeus/zeus/job/interval" 5) 6 7heartbeat := job.Spec{ 8 Name: "heartbeat", 9 Every: 30 * time.Second, 10 Handler: func(ctx context.Context) error { 11 return reportHeartbeat(ctx) 12 }, 13 Timeout: 5 * time.Second, 14} 15 16app := components.NewApp( 17 components.NewJobComponent(interval.New()), 18 components.NewJobRegistration(heartbeat), 19) 20app.Run() URL scheme 切换调度器实现通过 job.NewSchedulerFromURL 用 URL 字符串切换 interval / cron 实现：