[FEATURE] Introduce Router Cache to Enhance Routing Performance

[Aetherance]

✅ 验证清单

• 🔍 我已经搜索过 现有 Issues，确信这不是重复请求
• 📋 我已经查看了 发布说明，确信此功能尚未实现

🎯 功能描述

在 Dubbo-Go 的 RouterChain 层引入一种轻量级的路由结果缓存机制。

目前，每一次 RPC 调用都会完整执行所有的 Router 逻辑（如 Tag 匹配、脚本运算等）。本功能旨在优化这一过程，具体行为如下：

1. 结果缓存：将 RouterChain 计算后的最终产物（即过滤后的 Invoker 列表）进行缓存。

2. 读取拦截：在执行路由逻辑前，根据 RPC 方法、Consumer 上下文以及当前的规则版本构建 Cache Key。如果命中缓存，直接返回结果，跳过所有 Router 的计算。

3. 自动失效：依赖“路由规则版本号”和“服务列表版本号”来感知变化。一旦服务上下线或规则变更，生成的 Key 会自动变化，从而自然屏蔽旧的缓存数据，确保路由准确性。

4. 可配置：提供配置开关，允许用户根据业务场景选择开启或关闭此缓存能力。

📋 使用场景

• 高并发场景
  在 QPS 很高，但服务列表和路由规则相对稳定的场景下，能避免重复计算，显著降低 CPU 消耗。

• 复杂路由规则
  当系统中使用了较复杂的路由逻辑（如多重条件路由或脚本路由）时，缓存能直接跳过繁重的计算过程。

• 对延迟敏感的核心链路
  消除框架内部不必要的计算开销，降低 RPC 调用的整体延迟。

⚖️ 复杂性与风险评估

内存占用
风险：如果 Cache Key 设计不当（例如包含随机值）导致 Key 数量爆炸，或者缓存未设置容量上限，可能引发 OOM。
对策：默认实现应基于 LRU（最近最少使用）策略，并设置合理的容量上限。

🔗 外部依赖

No response

📚 附加信息

No response

[Aetherance]

assign to me plz

[AlexStocks]

todo：把 config center 机制看下，整体给出一套解决方案。

[Aetherance]

todo：把 config center 机制看下，整体给出一套解决方案。

ok

[Aetherance]

目前除了 config center 导致的router 规则变化，还有 registry center 变更导致的源 provider 列表变更会导致旧 router cache 不可用。现在将 registry center 和 config center 导致的变化一并讨论。

简单介绍一下这两种变化：

1. Config Center：路由规则发生变化
2. Registry Center：Provider 列表发生变化

最直接的方式是在发生变化的时候直接删除相应 router chain cache

1. config center change:

用户动态修改路由规则（如 YAML 内容）。有些Router支持“原地热更新”，导致Router Chain 中部分 Router 在运行时发生规则变化。而 Router Chain 目前无法获知路由规则变化，Router Chain Cache 继续返回按照旧规则计算的内容。

解决方法:

Router 监听 config center 的能力来自于对 ConfigurationListener 接口的实现

config_center/configuration_listener.go

type ConfigurationListener interface {
	// Process the notification event once there's any change happens on the config
	Process(*ConfigChangeEvent)
}

Process 接口会在 config center 发生规则变化的时候被以回调函数的方式被调用。

以 nacos 为例:

config_center/nacos/listener.go:40

func callback(listenersMap *sync.Map, _, group, dataId, data string) {
	listenersMap.Range(func(key, value any) bool {
		key.(config_center.ConfigurationListener).Process(&config_center.ConfigChangeEvent{Key: dataId, Value: data, ConfigType: remoting.EventTypeUpdate})
		metrics.Publish(metricsConfigCenter.NewIncMetricEvent(dataId, group, remoting.EventTypeUpdate, metricsConfigCenter.Nacos))
		return true
	})
}

config center 会将Process包装成一个callback() 然后在规则发生变化的时候调用这个函数。

config_center/nacos/listener.go:61

OnChange: func(namespace, group, dataId, data string) {
	go callback(listenersMap, namespace, group, dataId, data)
},

OnChange 最终会被 nacos-SDK 执行。

除了 nacos 外 config_center 目录下的其他注册中心也有这样的实现 (这个功能其实是 DynamicConfiguration 接口所要求的)

config_center/dynamic_configuration.go:35

// DynamicConfiguration is the interface which modifys listener and gets properties file.
type DynamicConfiguration interface {
	Parser() parser.ConfigurationParser
	SetParser(parser.ConfigurationParser)
	AddListener(string, ConfigurationListener, ...Option)
	RemoveListener(string, ConfigurationListener, ...Option)
	// GetProperties get properties file
	GetProperties(string, ...Option) (string, error)

	// GetRule get Router rule properties file
	GetRule(string, ...Option) (string, error)

	// GetInternalProperty get value by key in Default properties file(dubbo.properties)
	GetInternalProperty(string, ...Option) (string, error)

	// PublishConfig will publish the config with the (key, group, value) pair
	// for zk: path is /$(group)/config/$(key) -> value
	// for nacos: group, key -> value
	PublishConfig(string, string, string) error

	// RemoveConfig will remove the config white the (key, group) pair
	RemoveConfig(string, string) error

	// GetConfigKeysByGroup will return all keys with the group
	GetConfigKeysByGroup(group string) (*gxset.HashSet, error)
}

Process 方法完美契合 router cache 的错误 cache 销毁，它能够做到：

1. 自动检测配置中心的规则变化
2. 自动执行销毁 wrong cache 的代码
3. 实现的代码不会分散在各个文件中，并且实现代码量不至于过多（实际上应该会很少

我们只要让 Router Chain 也实现 Process 方法，并将其添加到配置中心的 Listener 中，就能在 Process 方法中完成配置中心导致的错误缓存的自动销毁。并且可以涵盖任何由配置中心导致的规则变化产生的变更。

2. registry center

registry center 对于源 provider 列表的推送也由 Process 方法承担（对于这个方法这里不再过多赘述）。

在获取到 registry center 的变化后，direcotry 会通过 Process 自动执行 refreshInvokers 然后调用 setNewInvokers

registry/directory/directory.go:190

// refreshInvokers refreshes service's events.
func (dir *RegistryDirectory) refreshInvokers(event *registry.ServiceEvent) {
	if event != nil {
		logger.Debugf("refresh invokers with %+v", event)
	} else {
		logger.Debug("refresh invokers with nil")
	}

	var oldInvoker []protocolbase.Invoker
	if event != nil {
		oldInvoker, _ = dir.cacheInvokerByEvent(event)
	}
	dir.setNewInvokers()
	for _, v := range oldInvoker {
		if v != nil {
			v.Destroy()
		}
	}
}

这个方法最终调用 router chain 的 SetInvokers，我们可以直接在 SetInvokers 做对旧缓存的处理。

这样可以在 router chain 层面实现对 router chain cache 的旧缓存的处理，并且侵入性低，实现的代码量非常少。(可能只需要几行)

[Aetherance]

router chain cache 设计思路

1. router chain cache 存储结构

router 的路由功能是有条件的，需要通过一定的条件进行 routing

因此不同的条件会产生不同的路由结果，用 key-val 结构可以将不同的条件hash到不同的路由结果，使router chain cache 可以正确获取路由结果。

2. router chain cache key 设计

type RouterCacheKey struct {
	// 服务标识
	ServiceKey string 

	// 方法标识
	MethodName string 

	// 路由元数据哈希
	// 将所有影响路由的动态参数（Identity, Tags, Attachments）压缩成一个 hash值
	RuleAttributeHash uint64 
}

这个key将会通过 buildCacheKey() 构建，然后作为存储路由结果 []Invokers 的键

对于过于复杂的路由结果，可以不进行缓存，以免出现命中错误缓存等危险情况

3. router chain cache interface 设计

type RouterCache interface {
	// Get 根据 Key 获取缓存的 Invoker 列表
	Get(key RouterCacheKey) ([]base.Invoker, bool)

	// Set 将路由计算结果存入缓存
	Set(key RouterCacheKey, invokers []base.Invoker)

	// Clear 清空当前服务下的所有路由缓存
	// 触发时机：
	// 1. SetInvokers
	// 2. Process
    // 3. ...
	Clear()
}

4. router chain cache struct 实现示例

（由ai生成，不代表最终设计）

package chain

import (
	"sync"
)

import (
	"dubbo.apache.org/dubbo-go/v3/protocol/base"
)

// DefaultRouterCache 是 RouterCache 接口的默认实现。
// 它内置了读写锁以支持高并发下的缓存读写。
type DefaultRouterCache struct {
	// 使用读写锁保护 map，因为路由场景下“读多写少”
	mutex sync.RWMutex
	
	// 核心存储结构
	// Key 是我们定义的 RouterCacheKey 结构体
	// Value 是过滤后的 Invoker 指针切片
	data map[RouterCacheKey][]base.Invoker
	
	// 可选：最大容量限制（简单的防内存溢出机制）
	maxCapacity int
}

// NewDefaultRouterCache 创建一个默认的缓存实例
func NewDefaultRouterCache(capacity int) *DefaultRouterCache {
	if capacity <= 0 {
		capacity = 1000 // 默认给个 1000 个缓存位
	}
	return &DefaultRouterCache{
		data:        make(map[RouterCacheKey][]base.Invoker, capacity),
		maxCapacity: capacity,
	}
}