mirror of
https://gitee.com/johng/gf
synced 2026-06-07 02:12:11 +08:00
b4053ed32e
# Loader 配置加载器
Loader 是一个通用的配置管理器，提供了类似于 Spring Boot
的`@ConfigurationProperties`的配置加载、监控、更新和管理功能。
## 功能特性
- **泛型支持**：使用 Go 泛型，类型安全的配置绑定
- **配置加载**：从配置源加载数据并绑定到结构体
- **配置监控**：自动监控配置变化并更新
- **自定义转换器**：支持自定义数据转换函数
- **回调处理**：配置变更时的回调函数
- **错误处理**：灵活的错误处理机制
## 安装
```bash
go get github.com/gogf/gf/v2
```
## 使用示例
### 1. 基本用法
#### 用法一
```go
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)
}
```
#### 用法二
```go
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. 配置监控
```go
// 仅加载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. 自定义转换器
```go
// 设置自定义转换器
loader.SetConverter(func (data any, target *AppConfig) error {
// 自定义数据转换逻辑
return nil
})
```
### 4. 便捷方法
```go
// 一步完成加载和监控
loader.MustLoadAndWatch(context.Background(), "my-app")
```
## API 参考
### `NewLoader`
创建一个新的 Loader 实例。
```go
func NewLoader[T any](config *Config, propertyKey string, targetStruct ...*T) *Loader[T]
```
参数:
- `config`: 配置实例，用于监控变化
- `propertyKey`: 监控的属性键模式（使用 "" 或 "." 监控所有配置）
- `targetStruct`: 接收配置值的结构体指针（可选）
### `NewLoaderWithAdapter`
使用适配器创建一个新的 Loader 实例。
```go
func NewLoaderWithAdapter[T any](adapter Adapter, propertyKey string, targetStruct ...*T) *Loader[T]
```
### `Load`
从配置实例加载数据并绑定到目标结构体。
```go
func (l *Loader[T]) Load(ctx context.Context) error
```
### `MustLoad`
与 Load 类似，但出错时会 panic。
```go
func (l *Loader[T]) MustLoad(ctx context.Context)
```
### `Watch`
开始监控配置变化并自动更新目标结构体。
```go
func (l *Loader[T]) Watch(ctx context.Context, name string) error
```
### `MustWatch`
与 Watch 类似，但出错时会 panic。
```go
func (l *Loader[T]) MustWatch(ctx context.Context, name string)
```
### `MustLoadAndWatch`
便捷方法，调用 MustLoad 和 MustWatch。
```go
func (l *Loader[T]) MustLoadAndWatch(ctx context.Context, name string)
```
### `Get`
返回当前配置结构体。
```go
func (l *Loader[T]) Get() T
```
### `GetPointer() *T`
返回指向当前配置结构体的指针。
```go
func (l *Loader[T]) GetPointer() *T
```
### `OnChange`
设置配置变化时调用的回调函数。
```go
func (l *Loader[T]) OnChange(fn func (updated T) error)
```
### `SetConverter`
设置在 Load 操作期间使用的自定义转换函数。
```go
func (l *Loader[T]) SetConverter(converter func (data any, target *T) error)
```
### `SetWatchErrorHandler`
设置在 Watch 过程中 Load 操作失败时调用的错误处理函数。
```go
func (l *Loader[T]) SetWatchErrorHandler(errorFunc func(ctx context.Context, err error))
```
### `SetReuseTargetStruct`
设置是否在更新时重用相同的目标结构体或创建新结构体。
```go
func (l *Loader[T]) SetReuseTargetStruct(reuse bool)
```
### `StopWatch`
停止监控配置变化并移除关联的监控器。
```go
func (l *Loader[T]) StopWatch(ctx context.Context) (bool, error)
```
### `IsWatching`
返回 Loader 是否正在监控配置变化。
```go
func (l *Loader[T]) IsWatching() bool
```
## 高级用法
### 监控特定配置键
```go
// 只监控特定配置键
loader := gcfg.NewLoaderWithAdapter[ServerConfig](cfg, "server")
```
### 使用默认值
```go
// 创建带默认值的目标结构体
var targetConfig AppConfig
targetConfig.Name = "default-app" // 设置默认值
loader := gcfg.NewLoaderWithAdapter(cfg, "", &targetConfig)
```
## 错误处理
Loader 提供了灵活的错误处理机制：
```go
loader.SetWatchErrorHandler(func(ctx context.Context, err error) {
// 处理加载错误
log.Printf("配置加载失败: %v", err)
})
```
---------
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: houseme <housemecn@gmail.com>