Documentation
¶
Overview ¶
Package governance 定义 kitex/hertz 共用的治理配置模板(audit 5.2)。
目标:业务只维护**一份** Nacos 治理配置模板,kitex 与 hertz 两侧各自 适配消费,不再各管一套格式。
收敛路线(分两阶段):
- 阶段 1(本包):统一 schema + 原子 Store。hertz 侧直接消费 (限流/超时中间件、httpx 重试策略);kitex 侧继续用既有 per-category dataID(NewGovernanceConfig),通过 Parse 对齐字段语义。
- 阶段 2:kitex NewGovernanceConfig 迁移到同一份模板,per-category dataID 转为模板内 category 字段。
配置格式(JSON,Nacos dataId 建议 "{service}.governance"):
{
"retry": { "svc:Method": {"max_attempts": 3, "backoff_ms": 50, "max_backoff_ms": 1000, "jitter_ms": 20} },
"timeout_ms": { "svc:Method": 200, "svc": 500 },
"circuit_breaker": { "svc": {"error_rate_threshold": 0.5, "min_requests": 100, "open_ms": 10000} },
"limiter": { "POST:/order": {"rate": 100, "burst": 200} }
}
key 匹配约定:精确优先("svc:Method" / "METHOD:path"),其后前缀最长匹配 ("svc"),最后全局 ""(可选)。
Index ¶
- Variables
- type CBPolicy
- type Config
- func (c *Config) LookupLimiter(method, path string) (LimiterPolicy, bool)
- func (c *Config) LookupLimiterKey(method, path string) (LimiterPolicy, string, bool)
- func (c *Config) LookupRetry(svc, method string) (RetryPolicy, bool)
- func (c *Config) LookupTimeout(svc, method string) (int, bool)
- func (c *Config) Validate() error
- type LimiterPolicy
- type RetryPolicy
- type Store
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidConfig = errors.New("governance: invalid config")
ErrInvalidConfig 是治理模板校验失败的 sentinel(用 errors.Is 判定)。
Functions ¶
This section is empty.
Types ¶
type CBPolicy ¶
type CBPolicy struct {
// ErrorRateThreshold 错误率阈值(0-1)。
ErrorRateThreshold float64 `json:"error_rate_threshold"`
// MinRequests 触发统计的最小请求数。
MinRequests int64 `json:"min_requests"`
// OpenMs 熔断开启时长(毫秒)。
OpenMs int64 `json:"open_ms"`
}
CBPolicy 是单个 key 的熔断策略。
type Config ¶
type Config struct {
Retry map[string]RetryPolicy `json:"retry,omitempty"`
TimeoutMs map[string]int `json:"timeout_ms,omitempty"`
CircuitBreaker map[string]CBPolicy `json:"circuit_breaker,omitempty"`
Limiter map[string]LimiterPolicy `json:"limiter,omitempty"`
}
Config 是统一治理模板。所有 map 的 key 为 "service:Method"(kitex)或 "METHOD:path"(hertz),省略冒号后缀表示 service/path 级默认。
func (*Config) LookupLimiter ¶
func (c *Config) LookupLimiter(method, path string) (LimiterPolicy, bool)
LookupLimiter 按 "METHOD:path" → "path" → "" 顺序取限流策略。
func (*Config) LookupLimiterKey ¶
func (c *Config) LookupLimiterKey(method, path string) (LimiterPolicy, string, bool)
LookupLimiterKey 行为同 LookupLimiter,额外返回实际命中的配置键 ("METHOD:path" / "path" / "")。消费方应优先用配置键(而非原始请求路径) 做限流桶分片——高基数 path(如 /order/123)在粗粒度(前缀/全局)策略下 若按原始 path 建桶,桶表会无界增长。
func (*Config) LookupRetry ¶
func (c *Config) LookupRetry(svc, method string) (RetryPolicy, bool)
LookupRetry 按 "svc:Method" → "svc" → "" 顺序取重试策略。
func (*Config) LookupTimeout ¶
LookupTimeout 按 "svc:Method" → "svc" → "" 顺序取超时(毫秒);无命中返回 (0,false)。
type LimiterPolicy ¶
type LimiterPolicy struct {
// Rate 每秒允许的请求数。
Rate int `json:"rate"`
// Burst 桶容量(突发上限);0 表示取 Rate。
Burst int `json:"burst,omitempty"`
}
LimiterPolicy 是单个 key 的限流策略(令牌桶)。
type RetryPolicy ¶
type RetryPolicy struct {
// MaxAttempts 总尝试次数(含首次);<=1 表示不重试。
MaxAttempts int `json:"max_attempts"`
// BackOffMs 重试退避基数(毫秒,指数退避)。
BackOffMs int `json:"backoff_ms,omitempty"`
// MaxBackoffMs 退避上限(毫秒)。
MaxBackoffMs int `json:"max_backoff_ms,omitempty"`
// JitterMs 随机抖动上限(毫秒)。
JitterMs int `json:"jitter_ms,omitempty"`
}
RetryPolicy 是单个 key 的重试策略。
Source Files