feat(os/gcfg): add Loader with automatic struct binding and config watching (like Spring Boot @ConfigurationProperties)

[LanceAdd]

Loader 配置加载器

Loader 是一个通用的配置管理器，提供了类似于 Spring Boot 的@ConfigurationProperties的配置加载、监控、更新和管理功能。

功能特性

• 泛型支持：使用 Go 泛型，类型安全的配置绑定
• 配置加载：从配置源加载数据并绑定到结构体
• 配置监控：自动监控配置变化并更新
• 自定义转换器：支持自定义数据转换函数
• 回调处理：配置变更时的回调函数
• 错误处理：灵活的错误处理机制

安装

go get github.com/gogf/gf/v2

使用示例

1. 基本用法

用法一

package main

import (
	"github.com/gogf/gf/v2/frame/g"
	"github.com/gogf/gf/v2/os/gcfg"
	"github.com/gogf/gf/v2/os/gctx"
)

type AppConfig struct {
	Name     string       `json:"name"`
	Age      int          `json:"age"`
	Enabled  bool         `json:"enabled"`
	Features []string     `json:"features"`
	Server   ServerConfig `json:"server"`
}

type ServerConfig struct {
	Host string `json:"host"`
	Port int    `json:"port"`
}

func main() {
	ctx := gctx.New()
	// 创建配置器实例
	loader := gcfg.NewLoader[AppConfig](g.Cfg("test"), "")

	// 加载和监听配置
	loader.MustLoadAndWatch(ctx, "test-watcher")

	// 获取配置
	config := loader.Get()
	fmt.Println(config.Name)
}

用法二

package main

import (
	"fmt"
	"github.com/gogf/gf/v2/os/gcfg"
	"github.com/gogf/gf/v2/os/gctx"
)

type AppConfig struct {
	Name     string       `json:"name"`
	Age      int          `json:"age"`
	Enabled  bool         `json:"enabled"`
	Features []string     `json:"features"`
	Server   ServerConfig `json:"server"`
}

type ServerConfig struct {
	Host string `json:"host"`
	Port int    `json:"port"`
}

func main() {
	ctx := gctx.New()

	// 使用单独的适配器创建
	// 创建配置管理器
	cfg, _ := gcfg.NewAdapterFile("test.yaml")
	// 创建配置器实例
	loader := gcfg.NewLoaderWithAdapter[AppConfig](cfg, "")

	// 加载和监听配置
	loader.MustLoadAndWatch(ctx, "test-watcher")

	// 获取配置
	config := loader.Get()
	fmt.Println(config.Name)
}

2. 配置监控

// 仅加载App配置
loader := gcfg.NewLoaderWithAdapter[AppConfig](cfg, "app")

// 设置配置变更回调
loader.OnChange(func (updated AppConfig) error {
// 配置变更时的处理逻辑
println("配置已更新:", updated.Name)
return nil
})

// 加载数据
err := loader.Load(ctx)
if err != nil {
panic(err)
}

// 开始监控配置变化
err := loader.Watch(context.Background(), "my-watcher")
if err != nil {
panic(err)
}

3. 自定义转换器

// 设置自定义转换器
loader.SetConverter(func (data any, target *AppConfig) error {
// 自定义数据转换逻辑
return nil
})

4. 便捷方法

// 一步完成加载和监控
loader.MustLoadAndWatch(context.Background(), "my-app")

API 参考

NewLoader

创建一个新的 Loader 实例。

func NewLoader[T any](config *Config, propertyKey string, targetStruct ...*T) *Loader[T]

参数:

• config: 配置实例，用于监控变化
• propertyKey: 监控的属性键模式（使用 "" 或 "." 监控所有配置）
• targetStruct: 接收配置值的结构体指针（可选）

NewLoaderWithAdapter

使用适配器创建一个新的 Loader 实例。

func NewLoaderWithAdapter[T any](adapter Adapter, propertyKey string, targetStruct ...*T) *Loader[T]

Load

从配置实例加载数据并绑定到目标结构体。

func (l *Loader[T]) Load(ctx context.Context) error

MustLoad

与 Load 类似，但出错时会 panic。

func (l *Loader[T]) MustLoad(ctx context.Context)

Watch

开始监控配置变化并自动更新目标结构体。

func (l *Loader[T]) Watch(ctx context.Context, name string) error

MustWatch

与 Watch 类似，但出错时会 panic。

func (l *Loader[T]) MustWatch(ctx context.Context, name string)

MustLoadAndWatch

便捷方法，调用 MustLoad 和 MustWatch。

func (l *Loader[T]) MustLoadAndWatch(ctx context.Context, name string)

Get

返回当前配置结构体。

func (l *Loader[T]) Get() T

GetPointer() *T

返回指向当前配置结构体的指针。

func (l *Loader[T]) GetPointer() *T

OnChange

设置配置变化时调用的回调函数。

func (l *Loader[T]) OnChange(fn func (updated T) error)

SetConverter

设置在 Load 操作期间使用的自定义转换函数。

func (l *Loader[T]) SetConverter(converter func (data any, target *T) error)

SetWatchErrorHandler

设置在 Watch 过程中 Load 操作失败时调用的错误处理函数。

func (l *Loader[T]) SetWatchErrorHandler(errorFunc func(ctx context.Context, err error))

SetReuseTargetStruct

设置是否在更新时重用相同的目标结构体或创建新结构体。

func (l *Loader[T]) SetReuseTargetStruct(reuse bool)

StopWatch

停止监控配置变化并移除关联的监控器。

func (l *Loader[T]) StopWatch(ctx context.Context) (bool, error)

IsWatching

返回 Loader 是否正在监控配置变化。

func (l *Loader[T]) IsWatching() bool

高级用法

监控特定配置键

// 只监控特定配置键
loader := gcfg.NewLoaderWithAdapter[ServerConfig](cfg, "server")

使用默认值

// 创建带默认值的目标结构体
var targetConfig AppConfig
targetConfig.Name = "default-app" // 设置默认值

loader := gcfg.NewLoaderWithAdapter(cfg, "", &targetConfig)

错误处理

Loader 提供了灵活的错误处理机制：

loader.SetWatchErrorHandler(func(ctx context.Context, err error) {
    // 处理加载错误
    log.Printf("配置加载失败: %v", err)
})

[houseme]

建议在example中补充一下示例操作代码，谢谢 @LanceAdd

[LanceAdd]

建议在example中补充一下示例操作代码，谢谢 @LanceAdd

是这个example吗？https://github.com/gogf/examples

[houseme]

建议在example中补充一下示例操作代码，谢谢 @LanceAdd

是这个example吗？https://github.com/gogf/examples是这个例子吗？ https://github.com/gogf/examples

是的

[LanceAdd]

建议在example中补充一下示例操作代码，谢谢 @LanceAdd

是这个example吗？https://github.com/gogf/examples是这个例子吗？ https://github.com/gogf/examples

是的

等大家review完，如果能合并我直接维护到官网文档吧，有版本号了再去补到example里，没发版那个example里面go.mod写版本号写的也不对

[gqcn]

@LanceAdd 除了命名外，我暂无其他疑问了。