# config

**Repository Path**: gousing/config

## Basic Information

- **Project Name**: config
- **Description**: Golang Config 基于Viper神器包装的单实例配置管理器, 支持多文件监听(热更新)，配置项获取基于[Gousing Values](https://gitee.com/gousing/values) 进行了包装(支持Bool/String/IntX/UintX/FloatX/SliceX/MapX)
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-03-14
- **Last Updated**: 2025-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gousing Config

#### 介绍
Golang Config 基于[viper](https://github.com/spf13/viper)包装的单实例配置管理器, 支持多文件监听(热更新)
>  1. 注意：加载多个配置文件，请使用 config.LoadFromXXX() 代理方法，相同Key后加载的配置文件将会覆盖前面的配置
>  2. 注意：INI格式配置文件一级配置项Viper默认添加一个命名为default父级节点，INI格式配置文件一级配置项只能通过default.XXX进行读取
>  3. 注意: 如需监听配置，请使用 config.OnChange() 代理方法：
>  - 原因 1：如加载了多个配置文件, 使用Viper.OnConfigChange => WatchConfig, 仅能监听最后加载的那个配置文件
>  - 原因 2：如加载了多个配置文件, 使用Viper.OnConfigChange => WatchConfig, 将导致多个配置文件项丢失(Viper内部使用ReadInConfig，而非MergeInConfig)

配置项获取基于[Gousing Values](https://gitee.com/gousing/values) 进行了包装(支持Bool/String/IntX/UintX/FloatX/SliceX/MapX),  每个数据类型提供三种接口: 
>  1. func GetXXXFunc() (T) 读取并转换配置项，忽略错误(异常时默认值为零值)
>  2. func GetXXXFuncD() (T) 读取并转换配置项，指定默认值(异常时默认值为指定值)
>  3. func GetXXXFuncE() (T,Error) 读取并转换配置项，获取错误信息

#### 使用
```golang
go get gitee.com/gousing/config
import  "gitee.com/gousing/config"
```
#### 加载配置文件
```golang
//  gitee.com/gousing/config/config.go
//  LoadFromFiles 加载配置文件到单前实例
//  - 合并方式加载多个配置文件或多次加载文件，相同Key, 后读取的配置项将会覆盖前面的配置
func LoadFromFiles(files ...string) error
// LoadFromReader 读取配置文件到单前实例
//   - 合并方式读取多个配置文件或多次读取文件，相同Key, 后读取的配置项将会覆盖前面的配置
//   - 为nil的 io.Reader 将忽略
//   - configType: "json", "toml", "yaml", "yml", "properties", "props", "prop", "hcl", "tfvars", "dotenv", "env", "ini"
func LoadFromReader(configType string, files ...io.Reader) (errs error) 
// LoadFromMaps 加载多个 map[string]any配置项, 合并到单前实例
//   - 为空或nil的 map 将忽略
func LoadFromMaps(maps ...map[string]any) (errs error)
// Reset 重置配置实例，将清空已加载(含设置)的全部配置信息及OnChange监听
func Reset() error
// ResetAndLoadFromFiles 重置配置实例并重新加载配置文件到单前实例
//   - 重置配置实例，将清空已加载(含设置)的全部配置信息及OnChange监听
//   - 合并方式加载多个配置文件或多次加载文件，相同Key, 后读取的配置项将会覆盖前面的配置
func ResetAndLoadFromFiles(files ...string) error
// ResetAndLoadFromReader 重置配置实例并重新读取配置文件到单前实例
//   - 重置配置实例，将清空已加载(含设置)的全部配置信息及OnChange监听
//   - 合并方式读取多个配置文件或多次读取文件，相同Key, 后读取的配置项将会覆盖前面的配置
//   - configType: "json", "toml", "yaml", "yml", "properties", "props", "prop", "hcl", "tfvars", "dotenv", "env", "ini"
func ResetAndLoadFromReader(configType string, files ...io.Reader) error

// 自定义Viper
// SetViperDecodeHook 自定义 Viper 初始化DecodeHook
//   - 会触发 initDeafultViper 初始化单前实例
func SetViperDecodeHook(hook mapstructure.DecodeHookFunc)
// SetViperOptions 自定义 Viper 初始化选项
//   - 会触发 initDeafultViper 初始化单前实例
func SetViperOptions(opts ...viper.Option) 
```
#### 读取配置项
```golang
//  gitee.com/gousing/config/get_xxx.go
//  读取配置项基于[Gousing Values](https://gitee.com/gousing/values) 进行了包装(支持Bool/String/IntX/UintX/FloatX/SliceX/MapX/TimeX/ScanX),  每个数据类型提供三种接口: 
//  1.func GetXXXFunc() (T) 读取并转换配置项为目标格式，忽略错误(异常时默认值为零值)
//  2.func GetXXXFuncD() (T) 读取并转换配置项为目标格式，指定默认值(异常时默认值为指定值)
//  3.func GetXXXFuncE() (T,Error) 读取并转换配置项为目标格式，获取错误信息
// String
func GetString(key string) string
func GetStringD(key string, defaultVal string) string 
func GetStringE(key string) (string, error)  

// Bool
func GetBool(key string) bool
func GetBoolD(key string, defaultVal bool) bool 
func GetBoolE(key string) (bool, error) 

// Int
func GetInt(key string) int
func GetIntD(key string, defaultVal int) int 
func GetIntE(key string) (int, error) 
func GetInt8(key string) int8
func GetInt8D(key string, defaultVal int8) int8 
func GetInt8E(key string) (int8, error) 
// int16 int32 int64 ....

// Uint
func GetUint(key string) uint
func GetUintD(key string, defaultVal int) uint 
func GetUintE(key string) (uint, error) 
func GetUint8(key string) uint8
func GetUint8D(key string, defaultVal uint8) uint8 
func GetUint8E(key string) (uint8, error) 
// uint16 uint32 uint64 ....

// Float
func GetFloat32(key string) float32
func GetFloat32D(key string, defaultVal float32) float32
func GetFloat32E(key string) (float32, error)
func GetFloat64(key string) float64
func GetFloat64D(key string, defaultVal float64) float64
func GetFloat64E(key string) (float64, error)

// GetTime 读取并转换目标为time.Time, 转换失败则返回零值的time.Time
func GetTime(key string) time.Time 
func GetTimeD(key string, defaultVal time.Time) time.Time 
func GetTimeE(key string) (time.Time, error)
func GetTimeWith(key string, location *time.Location) (time.Time, error) 

// GetTimeDuration  读取并转换目标为time.Duration, 转换失败则返回零值的Duration
func GetTimeDuration(key string) time.Duration
func GetTimeDurationD(key string, defaultVal time.Duration) time.Duration
func GetTimeDurationE(key string) (time.Duration, error)

// GetTimeMonth 读取并转换目标为time.Month, 转换失败则返回零值的Month
func GetTimeMonth(key string) time.Month
func GetTimeMonthD(key string, defaultVal time.Month) time.Month
func GetTimeMonthE(key string) (time.Month, error)
 
// GetTimeWeekday 读取并转换目标为time.Weekday, 转换失败则返回零值的Weekday
func GetTimeWeekday(key string) time.Weekday
func GetTimeWeekdayD(key string, defaultVal time.Weekday) time.Weekday
func GetTimeWeekdayE(key string) (toVal time.Weekday, err error)

// GetSliceAny 读取配置项并转换为 []any 切片, 如配置项不存在或转换失败, 则返回空的切片
func GetSliceAny(key string) []any
func GetSliceAnyD(key string, defaultVal []any) []any 
func GetSliceAnyE(key string) ([]any, error) 

// GetSliceAs 读取配置项并转换为 []TypeBase 或 [][]TypeBase 切片, 如配置项不存在或转换失败, 则返回空的切片
//   - TypeBase: string | bool |	int | int8 | int16 | int32 | int64 |	uint | uint8 | uint16 | uint32 | uint64 |	float32 | float64 |	time.Time | time.Duration| time.Month | time.Weekday
func GetSliceAs[T values.TypeBase | values.TypeBaseSlice](key string) []T
func GetSliceAsD[T values.TypeBase | values.TypeBaseSlice](key string, defaultVal []T) []T
func GetSliceAsE[T values.TypeBase | values.TypeBaseSlice](key string) ([]T, error)

// GetSliceMap 读取配置项并转换为 []map[K]V 切片, 如配置项不存在或转换失败, 则返回空的切片
//   - TypeBase: string | bool |	int | int8 | int16 | int32 | int64 |	uint | uint8 | uint16 | uint32 | uint64 |	float32 | float64 |	time.Time | time.Duration| time.Month | time.Weekday
func GetSliceMap[K, V values.TypeBase](key string) []map[K]V
func GetSliceMapD[K, V values.TypeBase](key string, defaultVal []map[K]V) []map[K]V 
func GetSliceMapE[K, V values.TypeBase](key string) ([]map[K]V, error)

// GetMapAny 读取配置项并转换为 map[K]any , 如配置项不存在或转换失败, 则返回空的map
//   - TypeBase: string | bool |	int | int8 | int16 | int32 | int64 |	uint | uint8 | uint16 | uint32 | uint64 |	float32 | float64 |	time.Time | time.Duration| time.Month | time.Weekday
func GetMapAny[K values.TypeBase](key string) map[K]any 
func GetMapAnyD[K values.TypeBase](key string, defaultVal map[K]any) map[K]any
func GetMapAnyE[K values.TypeBase](key string) (map[K]any, error)

// GetMapAs 读取配置项并转换为 map[K]V , 如配置项不存在或转换失败, 则返回空的map
//   - K: map key 的类型 TypeBase
//   - V: map val 的类型 TypeBase
//   - TypeBase: string | bool |	int | int8 | int16 | int32 | int64 |	uint | uint8 | uint16 | uint32 | uint64 |	float32 | float64 |	time.Time | time.Duration| time.Month | time.Weekday
func GetMapAs[K, V values.TypeBase](key string) map[K]V
func GetMapAsD[K, V values.TypeBase](key string, defaultVal map[K]V) map[K]V 
func GetMapAsE[K, V values.TypeBase](key string) (map[K]V, error)

// GetMapSlice 读取配置项并转换为 map[K][]V , 如配置项不存在或转换失败, 则返回空的map
//   - K: map key 的类型 TypeBase
//   - V: map val 的类型 []TypeBase
//   - TypeBase: string | bool |	int | int8 | int16 | int32 | int64 |	uint | uint8 | uint16 | uint32 | uint64 |	float32 | float64 |	time.Time | time.Duration| time.Month | time.Weekday
func GetMapSlice[K, V values.TypeBase](key string) map[K][]V
func GetMapSliceD[K, V values.TypeBase](key string, defaultVal map[K][]V) map[K][]V
func GetMapSliceE[K, V values.TypeBase](key string) (map[K][]V, error)

// ScanTo 从全局配置顶层开始扫描配置内容到 refVal
//   - refVal: 接收对象指针
//   - 不同于Unmarshal方法，Scan方法会忽略refVal未定义的字段, Unmarshal方法如两端字段不一致，会报错或返回空
func ScanTo(refVal any, opts ...viper.DecoderConfigOption) error
// ScanKey 从指定 Key 读取配置项后扫描到 refVal 中， Key不区分大小写
//   - refVal: 接收对象指针
//   - 不同于 UnmarshalKey 方法，Scan方法会忽略refVal未定义的字段, UnmarshalKey 方法如两端字段不一致，会报错或返回空
func ScanKey(key string, refVal any, opts ...viper.DecoderConfigOption) error 
```

#### 监听配置文件变更
```golang
// gitee.com/gousing/config/proxy.go
// OnChange 监听配置文件修改, 触发回调函数
//   - 注意: Windows平台 fsnotify 有触发两次Bug
func OnChange(fn func(e fsnotify.Event))
```
#### 其他 Viper 常用方法代理 
```golang
  // gitee.com/gousing/config/proxy.go
  // IsSet 判断指定配置Key是否存在, Key不区分大小写
 func IsSet(key string) bool
 // InConfig 判断指定配置Key是否存在(包含别名), Key不区分大小写
 func InConfig(key string) bool
 // Get 获取指定配置Key的配置项, Key不区分大小写
//   - 返回值: 配置项(不存在返回nil)
 func Get(key string) (val any)
 // GetExist 获取指定配置Key的配置项, Key不区分大小写
//   - 返回值: 配置项(不存在返回nil), 配置项是否存在(Bool)
 func GetExist(key string) (val any, exists bool) 
// Set 覆盖指定配置Key的配置项, Key不区分大小写
 func Set(key string, value any) 
 // SetDefault 设置指定配置Key的默认值, Key不区分大小写
 func SetDefault(key string, value any) 
 // RegisterAlias 创建指定配置key的别名，用于同一个配置项基于别名的另一个访问键
 func RegisterAlias(alias, key string)
 // WriteConfigAs 将当前配置写入到文件(如文件不存在则创建，如存在则覆盖)
 func WriteConfigAs(filename string) error
 // Env 方法代理
 func SetEnvPrefix(in string)
 func GetEnvPrefix() string
 func SetEnvKeyReplacer(r *strings.Replacer) 
 func AutomaticEnv()
 func AllowEmptyEnv(allowEmptyEnv bool)
 // Bind 方法代理
 func BindEnv(input ...string) error
 func BindPFlag(key string, flag *pflag.Flag) error
 func BindPFlags(flags *pflag.FlagSet) error
 // AllKeys 获取所有配置Key
 func AllKeys() []string
 // AllSettings 获取所有配置项
 func AllSettings() map[string]any
 // GetViper 获取全局默认的Viper实例
 func GetViper() *viper.Viper
```