Documentation
¶
Overview ¶
Application scenarios: - Provide a shared outbound RPC governance chain model used by HTTP and gRPC clients. - Keep timeout, retry, and future client-side governance logic provider-neutral. - Let transport-specific RPC providers reuse one middleware assembly pattern.
适用场景： - 为 HTTP 和 gRPC 客户端提供共享的出站 RPC 治理链模型。 - 让 timeout、retry 以及后续 client 侧治理逻辑保持 provider-neutral。 - 让不同 transport 的 RPC provider 复用同一套中间件装配模式。
Package governance provides outbound RPC governance middleware functions. This file implements a gRPC metadata carrier for TextMapCarrier compatibility.
Package governance 提供出站 RPC 治理中间件函数。 本文件实现 gRPC metadata carrier，用于 TextMapCarrier 兼容性。
Index ¶
- func Apply(invoker transportcontract.RPCInvoker, ...) transportcontract.RPCInvoker
- func Chain(middleware ...transportcontract.RPCClientMiddleware) transportcontract.RPCClientMiddleware
- func CircuitBreakerMiddleware(cb resiliencecontract.CircuitBreaker, ...) transportcontract.RPCClientMiddleware
- func DefaultClientPresetOrder() []string
- func DefaultClientPresetSet(opts DefaultClientPresetOptions, deps DefaultClientPresetDependencies) []transportcontract.RPCClientMiddleware
- func GRPCMetadataFromCarrier(carrier transportcontract.MetadataCarrier) metadata.MD
- func LoadSheddingMiddleware(ls resiliencecontract.LoadShedder, ...) transportcontract.RPCClientMiddleware
- func MetadataMiddleware(propagator transportcontract.MetadataPropagator) transportcontract.RPCClientMiddleware
- func NewGRPCMetadataCarrier(md metadata.MD) transportcontract.MetadataCarrier
- func RetryMiddleware(retry resiliencecontract.Retry) transportcontract.RPCClientMiddleware
- func RetryMiddlewareWithResource(retry resiliencecontract.Retry, resource func(service, method string) string) transportcontract.RPCClientMiddleware
- func SelectorMiddleware(selector discoverycontract.Selector, ...) transportcontract.RPCClientMiddleware
- func ServiceAuthMiddleware(issuer securitycontract.ServiceTokenIssuer) transportcontract.RPCClientMiddleware
- func TimeoutMiddleware(timeout time.Duration) transportcontract.RPCClientMiddleware
- func TraceIDMiddleware() transportcontract.RPCClientMiddleware
- func TracingMiddleware(tracer observabilitycontract.Tracer, serviceName string) transportcontract.RPCClientMiddleware
- type DefaultClientPresetDependencies
- type DefaultClientPresetOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Apply ¶
func Apply(invoker transportcontract.RPCInvoker, middleware ...transportcontract.RPCClientMiddleware) transportcontract.RPCInvoker
Apply wraps one invoker with zero or more outbound RPC middleware.
Apply 使用零个或多个出站 RPC 中间件包装一次调用。
func Chain ¶
func Chain(middleware ...transportcontract.RPCClientMiddleware) transportcontract.RPCClientMiddleware
Chain composes outbound RPC middleware in declaration order.
Chain 按声明顺序组合出站 RPC 中间件。
func CircuitBreakerMiddleware ¶
func CircuitBreakerMiddleware(cb resiliencecontract.CircuitBreaker, resource func(service, method string) string) transportcontract.RPCClientMiddleware
CircuitBreakerMiddleware wraps the outbound invocation with circuit breaker protection. Uses the provided resource function to generate the resource key for breaker state tracking.
CircuitBreakerMiddleware 使用熔断器保护包装出站调用。 使用提供的 resource 函数生成熔断器状态跟踪的资源键。
func DefaultClientPresetOrder ¶
func DefaultClientPresetOrder() []string
DefaultClientPresetOrder returns the stable logical order of the outbound governance chain.
DefaultClientPresetOrder 返回出站治理链的稳定逻辑顺序。
func DefaultClientPresetSet ¶
func DefaultClientPresetSet(opts DefaultClientPresetOptions, deps DefaultClientPresetDependencies) []transportcontract.RPCClientMiddleware
DefaultClientPresetSet builds the complete 8-stage RPC governance middleware chain from options and dependencies. Returns middleware in execution order: selector → timeout → tracing → metadata → serviceauth → loadshedding → breaker → retry. Nil dependencies cause corresponding middleware to be skipped.
DefaultClientPresetSet 从 options 和 dependencies 构建完整 8 阶段 RPC 治理中间件链。 返回的中间件按执行顺序排列：selector → timeout → tracing → metadata → serviceauth → loadshedding → breaker → retry。 nil 依赖会导致对应中间件被跳过。
func GRPCMetadataFromCarrier ¶
func GRPCMetadataFromCarrier(carrier transportcontract.MetadataCarrier) metadata.MD
GRPCMetadataFromCarrier extracts the underlying gRPC metadata from a MetadataCarrier. Returns nil if the carrier is not a grpcMetadataCarrier.
GRPCMetadataFromCarrier 从 MetadataCarrier 提取底层 gRPC metadata。 如果 carrier 不是 grpcMetadataCarrier，返回 nil。
func LoadSheddingMiddleware ¶
func LoadSheddingMiddleware(ls resiliencecontract.LoadShedder, resource func(service, method string) string) transportcontract.RPCClientMiddleware
LoadSheddingMiddleware wraps the outbound invocation with load-shedding protection. Uses the LoadShedder to check if the request should be rejected due to system overload. This middleware protects the client from making requests when the system is under heavy load.
LoadSheddingMiddleware 使用过载保护包装出站调用。 使用 LoadShedder 检查请求是否应因系统过载而被拒绝。 此中间件保护客户端在系统负载过高时不发送请求。
func MetadataMiddleware ¶
func MetadataMiddleware(propagator transportcontract.MetadataPropagator) transportcontract.RPCClientMiddleware
MetadataMiddleware propagates metadata from context to the outgoing RPC call. Uses the MetadataPropagator to inject context metadata into the gRPC outgoing context.
MetadataMiddleware 将 metadata 从 context 传播到出站 RPC 调用。 使用 MetadataPropagator 将 context metadata 注入到 gRPC outgoing context。
func NewGRPCMetadataCarrier ¶
func NewGRPCMetadataCarrier(md metadata.MD) transportcontract.MetadataCarrier
NewGRPCMetadataCarrier creates a new carrier wrapping the given gRPC metadata. Creates empty metadata if nil is provided.
NewGRPCMetadataCarrier 创建包装给定 gRPC metadata 的 carrier。 如果传入 nil，创建空 metadata。
func RetryMiddleware ¶
func RetryMiddleware(retry resiliencecontract.Retry) transportcontract.RPCClientMiddleware
RetryMiddleware retries the outbound invocation through the shared retry capability when available.
RetryMiddleware 在可用时通过统一 Retry 能力重试出站调用。
func RetryMiddlewareWithResource ¶
func RetryMiddlewareWithResource(retry resiliencecontract.Retry, resource func(service, method string) string) transportcontract.RPCClientMiddleware
RetryMiddlewareWithResource retries the outbound invocation with a normalized resource name.
RetryMiddlewareWithResource 使用归一化资源名对出站调用执行重试。
func SelectorMiddleware ¶
func SelectorMiddleware(selector discoverycontract.Selector, registry transportcontract.ServiceRegistry) transportcontract.RPCClientMiddleware
SelectorMiddleware selects a service instance before making the outbound RPC call. Uses the Selector to choose an instance from the registry and updates the service parameter. Calls the DoneFunc after invocation to report feedback to the selector.
SelectorMiddleware 在出站 RPC 调用前选择服务实例。 使用 Selector 从 registry 选择实例并更新 service 参数。 在调用后调用 DoneFunc 向选择器报告反馈。
func ServiceAuthMiddleware ¶
func ServiceAuthMiddleware(issuer securitycontract.ServiceTokenIssuer) transportcontract.RPCClientMiddleware
ServiceAuthMiddleware injects service authentication token into outgoing RPC metadata. Uses the ServiceTokenIssuer to generate a token for the target service.
ServiceAuthMiddleware 将服务认证令牌注入到出站 RPC metadata。 使用 ServiceTokenIssuer 为目标服务生成令牌。
func TimeoutMiddleware ¶
func TimeoutMiddleware(timeout time.Duration) transportcontract.RPCClientMiddleware
TimeoutMiddleware enforces one timeout around the outbound invocation.
TimeoutMiddleware 为出站调用包一层超时控制。
func TraceIDMiddleware ¶
func TraceIDMiddleware() transportcontract.RPCClientMiddleware
TraceIDMiddleware injects trace ID into outgoing RPC metadata for distributed tracing correlation. Uses supportcontract.FromTraceIDContext to extract trace ID from context.
TraceIDMiddleware 将 trace ID 注入到出站 RPC metadata，用于分布式追踪关联。 使用 supportcontract.FromTraceIDContext 从 context 提取 trace ID。
func TracingMiddleware ¶
func TracingMiddleware(tracer observabilitycontract.Tracer, serviceName string) transportcontract.RPCClientMiddleware
TracingMiddleware creates a span for the outbound RPC invocation. Records service and method as span attributes, and captures errors on span end.
TracingMiddleware 为出站 RPC 调用创建 span。 将 service 和 method 记录为 span attributes，并在结束时捕获错误。
Types ¶
type DefaultClientPresetDependencies ¶
type DefaultClientPresetDependencies struct {
Selector discoverycontract.Selector
Registry transportcontract.ServiceRegistry
Tracer observabilitycontract.Tracer
ServiceName string
MetadataPropagator transportcontract.MetadataPropagator
ServiceAuthIssuer securitycontract.ServiceTokenIssuer
CircuitBreaker resiliencecontract.CircuitBreaker
Retry resiliencecontract.Retry
LoadShedder resiliencecontract.LoadShedder
ResourceNamer func(service, method string) string
}
DefaultClientPresetDependencies contains all dependencies needed to build the full 7-stage RPC governance chain. Each field is optional; nil dependencies result in the corresponding middleware being skipped.
DefaultClientPresetDependencies 包含构建完整 7 阶段 RPC 治理链所需的所有依赖。 每个字段都是可选的；nil 依赖会导致对应中间件被跳过。
type DefaultClientPresetOptions ¶
DefaultClientPresetOptions controls the default outbound RPC governance preset.
DefaultClientPresetOptions 用于控制默认出站 RPC 治理预设。
Source Files