refresh

package
v0.0.5 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package refresh 提供配置刷新功能，用于 enhance 框架。

该模块支持运行时配置热更新、RefreshScope 作用域管理、配置变更事件通知等动态配置功能。 参考 Spring Cloud RefreshScope 的设计理念。

架构设计

  • RefreshScope: 刷新作用域接口，管理可刷新的 Bean
  • RefreshEvent: 刷新事件，表示配置变更
  • RefreshEndpoint: 刷新端点，提供 HTTP 刷新接口
  • ConfigWatcher: 配置监听器，监控配置变更

核心功能

  • 配置热更新: 支持运行时动态更新配置
  • RefreshScope: 管理可刷新的 Bean 作用域
  • 事件通知: 配置变更时发布事件通知
  • HTTP 端点: 提供 /actuator/refresh 端点触发刷新
  • 配置监听: 支持监听配置中心变更

使用方式

创建刷新作用域： 

scope := refresh.NewRefreshScope()

注册可刷新的 Bean： 

scope.Register("myBean", func() any {
    return NewMyService(config)
})

触发刷新： 

err := scope.Refresh()

刷新端点

通过 HTTP 端点触发配置刷新： 

POST /actuator/refresh

配置变更事件

配置刷新时会发布事件：

  • EnvironmentChangeEvent: 环境配置变更事件
  • RefreshScopeEvent: 刷新作用域事件
  • RefreshEvent: 通用刷新事件

使用场景

  • 配置中心集成: 监听配置中心变更并自动刷新
  • 动态路由: 运行时更新路由配置
  • 功能开关: 动态启用/禁用功能

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewConfigChangeEvent 

func NewConfigChangeEvent(eventType string, keys []string, oldValues, newValues map[string]any, source string) environment.ConfigChangeEvent

NewConfigChangeEvent 创建配置变更事件

参数：

  • eventType: 事件类型（"modify"、"delete"、"create"）
  • keys: 变更的配置键列表
  • oldValues: 变更前的值
  • newValues: 变更后的值
  • source: 配置源类型

Types

type BeanRefreshEvent 

type BeanRefreshEvent struct {
	BeanID     string         // 需要刷新的 Bean 标识
	ConfigKeys []string       // 触发刷新的配置键
	OldValues  map[string]any // 变更前的值
	NewValues  map[string]any // 变更后的值
}

BeanRefreshEvent Bean 刷新事件

当配置变更导致 Bean 需要刷新时发布此事件。

func (*BeanRefreshEvent) Timestamp 

func (e *BeanRefreshEvent) Timestamp() time.Time

Timestamp 返回事件发生时间

func (*BeanRefreshEvent) Type 

func (e *BeanRefreshEvent) Type() string

Type 返回事件类型标识

type BeanRefreshedEvent 

type BeanRefreshedEvent struct {
	BeanID      string    // Bean 标识
	OldVersion  int64     // 刷新前版本号
	NewVersion  int64     // 刷新后版本号
	RefreshTime time.Time // 刷新完成时间
	Success     bool      // 是否刷新成功
	Error       error     // 刷新失败的错误信息
}

BeanRefreshedEvent Bean 刷新完成事件。

type ConfigChangeEvent 

type ConfigChangeEvent = environment.ConfigChangeEvent

ConfigChangeEvent 配置变更事件，别名来自 config/environment 包，保持向后兼容。

type ConfigChangeEventBuilder 

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

ConfigChangeEventBuilder 配置变更事件构建器

func NewConfigChangeEventBuilder 

func NewConfigChangeEventBuilder() *ConfigChangeEventBuilder

NewConfigChangeEventBuilder 创建配置变更事件构建器

func (*ConfigChangeEventBuilder) Build 

func (b *ConfigChangeEventBuilder) Build() environment.ConfigChangeEvent

Build 构建配置变更事件

func (*ConfigChangeEventBuilder) EventType 

func (b *ConfigChangeEventBuilder) EventType(eventType string) *ConfigChangeEventBuilder

EventType 设置事件类型

func (*ConfigChangeEventBuilder) Keys 

func (b *ConfigChangeEventBuilder) Keys(keys []string) *ConfigChangeEventBuilder

Keys 设置变更的配置键列表

func (*ConfigChangeEventBuilder) Metadata 

func (b *ConfigChangeEventBuilder) Metadata(metadata map[string]string) *ConfigChangeEventBuilder

Metadata 设置元数据

func (*ConfigChangeEventBuilder) NewValues 

func (b *ConfigChangeEventBuilder) NewValues(values map[string]any) *ConfigChangeEventBuilder

NewValues 设置新值

func (*ConfigChangeEventBuilder) OldValues 

func (b *ConfigChangeEventBuilder) OldValues(values map[string]any) *ConfigChangeEventBuilder

OldValues 设置旧值

func (*ConfigChangeEventBuilder) Source 

func (b *ConfigChangeEventBuilder) Source(source string) *ConfigChangeEventBuilder

Source 设置配置来源

type EventRouter 

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

EventRouter 配置变更事件路由器

维护 Bean 与配置键的双向映射关系，当配置变更事件到达时， 查找受影响的 Bean 并发布 BeanRefreshEvent。

func NewEventRouter 

func NewEventRouter(eventBus *event.EventBus) *EventRouter

NewEventRouter 创建事件路由器

创建后自动订阅事件总线的 "ConfigChange" 事件。

func (*EventRouter) RegisterBean 

func (r *EventRouter) RegisterBean(beanID string, configKeys []string)

RegisterBean 注册 Bean 及其依赖的配置键

建立 Bean 与配置键的双向映射，用于后续的事件路由。

type RefreshConfig 

type RefreshConfig struct {
	Enabled            bool          // 是否启用刷新功能
	RefreshDelay       time.Duration // 刷新延迟，避免频繁刷新
	MaxRefreshAttempts int           // 最大刷新尝试次数
	Logger             *slog.Logger  // 日志记录器
}

RefreshConfig 刷新配置

控制刷新功能的行为，包括是否启用、刷新延迟和重试策略。

func DefaultRefreshConfig 

func DefaultRefreshConfig() *RefreshConfig

DefaultRefreshConfig 返回默认刷新配置

默认值：

  • Enabled: true
  • RefreshDelay: 100ms
  • MaxRefreshAttempts: 3
  • Logger: slog.Default()

func (*RefreshConfig) ApplyOptions 

func (c *RefreshConfig) ApplyOptions(opts []RefreshOption)

ApplyOptions 应用配置选项列表

type RefreshEvent added in v0.0.3 

type RefreshEvent struct {
	// Environment 关联的环境配置。
	Environment *environment.Environment

	// ChangedKeys 变更的配置键列表。
	ChangedKeys []string

	// Timestamp 事件发生时间戳（毫秒）。
	Timestamp int64
}

RefreshEvent 刷新事件。

type RefreshFailedEvent 

type RefreshFailedEvent struct {
	BeanID     string    // 失败的 Bean 标识
	ConfigKeys []string  // 触发刷新的配置键
	Error      error     // 失败原因
	Timestamp  time.Time // 失败时间
}

RefreshFailedEvent 刷新失败事件。

type RefreshListener added in v0.0.3 

type RefreshListener interface {
	// OnRefresh 刷新时回调。
	OnRefresh(event RefreshEvent) error
}

RefreshListener 刷新监听器接口。

type RefreshManager added in v0.0.3 

type RefreshManager interface {
	// Start 启动刷新管理器。
	Start() error

	// Stop 停止刷新管理器。
	Stop() error

	// Refresh 刷新配置。
	Refresh() error

	// AddRefreshListener 添加刷新监听器。
	AddRefreshListener(listener RefreshListener)
}

RefreshManager 配置刷新管理器接口。

负责配置的动态刷新，依赖 config/environment 包。 依赖方向：config/refresh → config/environment（正确方向）。

func NewRefreshManager added in v0.0.3 

func NewRefreshManager(env *environment.Environment) RefreshManager

NewRefreshManager 创建刷新管理器。

参数：

  • env: 环境配置，刷新时会关联到 RefreshEvent 中

type RefreshMetrics 

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

RefreshMetrics 刷新指标收集器

使用原子操作记录刷新次数、耗时等指标，支持并发安全访问。

func NewRefreshMetrics 

func NewRefreshMetrics() *RefreshMetrics

NewRefreshMetrics 创建刷新指标收集器

func (*RefreshMetrics) AverageRefreshTime 

func (m *RefreshMetrics) AverageRefreshTime() time.Duration

AverageRefreshTime 返回平均刷新耗时

func (*RefreshMetrics) FailedRefreshes 

func (m *RefreshMetrics) FailedRefreshes() int64

FailedRefreshes 返回失败刷新次数

func (*RefreshMetrics) LastRefreshTime 

func (m *RefreshMetrics) LastRefreshTime() time.Time

LastRefreshTime 返回最后刷新时间

func (*RefreshMetrics) RecordRefresh 

func (m *RefreshMetrics) RecordRefresh(duration time.Duration, success bool)

RecordRefresh 记录一次刷新操作

参数：

  • duration: 刷新耗时
  • success: 是否刷新成功

func (*RefreshMetrics) Reset 

func (m *RefreshMetrics) Reset()

Reset 重置所有指标

func (*RefreshMetrics) SuccessfulRefreshes 

func (m *RefreshMetrics) SuccessfulRefreshes() int64

SuccessfulRefreshes 返回成功刷新次数

func (*RefreshMetrics) TotalRefreshes 

func (m *RefreshMetrics) TotalRefreshes() int64

TotalRefreshes 返回总刷新次数

type RefreshOption 

type RefreshOption func(*RefreshConfig)

RefreshOption 刷新配置选项函数

func WithMaxRefreshAttempts 

func WithMaxRefreshAttempts(attempts int) RefreshOption

WithMaxRefreshAttempts 设置最大刷新尝试次数

func WithRefreshDelay 

func WithRefreshDelay(delay time.Duration) RefreshOption

WithRefreshDelay 设置刷新延迟时间

func WithRefreshEnabled 

func WithRefreshEnabled(enabled bool) RefreshOption

WithRefreshEnabled 设置是否启用刷新功能

func WithRefreshLogger 

func WithRefreshLogger(logger *slog.Logger) RefreshOption

WithRefreshLogger 设置日志记录器

type RefreshProxy 

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

RefreshProxy Bean 刷新代理

使用代理模式实现延迟刷新。消费者持有代理引用， 代理内部在刷新标记被设置后重新创建目标实例。

刷新流程：

  1. MarkForRefresh 设置刷新标记
  2. GetTarget 检测到刷新标记，加锁创建新实例
  3. 使用双重检查锁定避免不必要的加锁

func NewRefreshProxy 

func NewRefreshProxy(beanID string, target any, manager *RefreshScopeManager, logger *slog.Logger) *RefreshProxy

NewRefreshProxy 创建刷新代理

参数：

  • beanID: Bean 标识
  • target: 初始 Bean 实例
  • manager: 刷新作用域管理器
  • logger: 日志记录器

func (*RefreshProxy) GetTarget 

func (p *RefreshProxy) GetTarget() any

GetTarget 获取目标 Bean 实例

如果需要刷新，使用双重检查锁定模式创建新实例：

  1. 快速路径：无需刷新时直接返回当前实例（无锁）
  2. 慢速路径：加锁后再次检查，确认需要刷新后创建新实例
  3. 创建失败时返回旧实例，保证服务可用性

func (*RefreshProxy) MarkForRefresh 

func (p *RefreshProxy) MarkForRefresh()

MarkForRefresh 标记代理需要在下次 GetTarget 时刷新

type RefreshProxyBuilder 

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

RefreshProxyBuilder 刷新代理构建器

func NewRefreshProxyBuilder 

func NewRefreshProxyBuilder() *RefreshProxyBuilder

NewRefreshProxyBuilder 创建刷新代理构建器

func (*RefreshProxyBuilder) BeanID 

func (b *RefreshProxyBuilder) BeanID(beanID string) *RefreshProxyBuilder

BeanID 设置Bean标识

func (*RefreshProxyBuilder) Build 

func (b *RefreshProxyBuilder) Build() (*RefreshProxy, error)

Build 构建刷新代理

func (*RefreshProxyBuilder) Logger 

func (b *RefreshProxyBuilder) Logger(logger *slog.Logger) *RefreshProxyBuilder

Logger 设置日志记录器

func (*RefreshProxyBuilder) Manager 

func (b *RefreshProxyBuilder) Manager(manager *RefreshScopeManager) *RefreshProxyBuilder

Manager 设置刷新作用域管理器

func (*RefreshProxyBuilder) MustBuild 

func (b *RefreshProxyBuilder) MustBuild() *RefreshProxy

MustBuild 构建刷新代理，失败则panic

func (*RefreshProxyBuilder) Target 

func (b *RefreshProxyBuilder) Target(target any) *RefreshProxyBuilder

Target 设置目标Bean实例

type RefreshScopeManager 

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

RefreshScopeManager 刷新作用域管理器

参考 Spring Cloud 的 @RefreshScope，管理可刷新 Bean 的生命周期。 当配置变更时，标记受影响的 Bean 并在下次访问时重建实例。

使用代理模式实现延迟刷新：Bean 的消费者持有代理引用， 代理内部在刷新标记被设置后重新创建目标实例。

func NewRefreshScopeManager 

func NewRefreshScopeManager(beanCreator core.BeanCreator, logger *slog.Logger, opts ...RefreshOption) *RefreshScopeManager

NewRefreshScopeManager 创建刷新作用域管理器

参数：

  • beanCreator: Bean 创建器，用于重建 Bean 实例
  • logger: 日志记录器，nil 时使用配置中的默认值
  • opts: 刷新配置选项

func (*RefreshScopeManager) GetRefreshedBean 

func (m *RefreshScopeManager) GetRefreshedBean(beanID string) (any, error)

GetRefreshedBean 获取刷新后的 Bean 实例

通过代理获取最新的 Bean 实例。如果代理不存在，返回错误。

func (*RefreshScopeManager) MarkBeanForRefresh 

func (m *RefreshScopeManager) MarkBeanForRefresh(beanID string)

MarkBeanForRefresh 标记 Bean 为需要刷新

设置刷新标记并通知代理，代理会在下次 GetTarget 时重建实例。

func (*RefreshScopeManager) Metrics 

func (m *RefreshScopeManager) Metrics() *RefreshMetrics

Metrics 返回刷新指标

func (*RefreshScopeManager) OnConfigChange 

func (m *RefreshScopeManager) OnConfigChange(event environment.ConfigChangeEvent)

OnConfigChange 处理配置变更事件

遍历所有已注册的可刷新 Bean，逐一通知配置变更。 如果某个 Bean 通知失败，记录错误日志但不中断其他 Bean 的通知。

注意：此方法在读锁内复制 Bean 列表后释放锁再回调，避免回调内部 调用 RegisterRefreshableBean 等写方法时产生死锁。

func (*RefreshScopeManager) RegisterRefreshableBean 

func (m *RefreshScopeManager) RegisterRefreshableBean(beanID string, bean RefreshableBean)

RegisterRefreshableBean 注册可刷新 Bean

注册后，该 Bean 会在配置变更时收到 OnConfigChange 通知。

type RefreshScopeManagerBuilder 

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

RefreshScopeManagerBuilder 刷新作用域管理器构建器，支持链式配置

func NewRefreshScopeManagerBuilder 

func NewRefreshScopeManagerBuilder() *RefreshScopeManagerBuilder

NewRefreshScopeManagerBuilder 创建刷新作用域管理器构建器

func (*RefreshScopeManagerBuilder) BeanCreator 

func (b *RefreshScopeManagerBuilder) BeanCreator(creator core.BeanCreator) *RefreshScopeManagerBuilder

BeanCreator 设置Bean创建器

func (*RefreshScopeManagerBuilder) Build 

func (b *RefreshScopeManagerBuilder) Build() (*RefreshScopeManager, error)

Build 构建刷新作用域管理器

func (*RefreshScopeManagerBuilder) Enabled 

func (b *RefreshScopeManagerBuilder) Enabled(enabled bool) *RefreshScopeManagerBuilder

Enabled 设置是否启用刷新功能

func (*RefreshScopeManagerBuilder) Logger 

func (b *RefreshScopeManagerBuilder) Logger(logger *slog.Logger) *RefreshScopeManagerBuilder

Logger 设置日志记录器

func (*RefreshScopeManagerBuilder) MaxRefreshAttempts 

func (b *RefreshScopeManagerBuilder) MaxRefreshAttempts(attempts int) *RefreshScopeManagerBuilder

MaxRefreshAttempts 设置最大刷新尝试次数

func (*RefreshScopeManagerBuilder) MustBuild 

func (b *RefreshScopeManagerBuilder) MustBuild() *RefreshScopeManager

MustBuild 构建刷新作用域管理器，失败则panic

func (*RefreshScopeManagerBuilder) RefreshDelay 

func (b *RefreshScopeManagerBuilder) RefreshDelay(delay time.Duration) *RefreshScopeManagerBuilder

RefreshDelay 设置刷新延迟

func (*RefreshScopeManagerBuilder) RefreshableBean 

func (b *RefreshScopeManagerBuilder) RefreshableBean(beanID string, bean RefreshableBean) *RefreshScopeManagerBuilder

RefreshableBean 注册可刷新Bean

type RefreshableBean 

type RefreshableBean interface {
	OnConfigChange(event ConfigChangeEvent) error
}

RefreshableBean 可刷新 Bean 接口。

实现此接口的 Bean 会在配置变更时收到 OnConfigChange 回调。

Source Files

View all Source files

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.