config

package
v2.7.0 Latest Latest
Warning

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

 Go to latest Published: Apr 16, 2022 License: Apache-2.0 Imports: 20 Imported by: 0

README

Config

功能完善的Golang应用程序配置管理工具库。

EN README

功能简介

  • 支持多种格式: JSON(默认), INI, YAML, TOML, HCL, ENV, Flags
    • JSON 内容支持注释，解析时将自动清除注释
    • 其他驱动都是按需使用，不使用的不会加载编译到应用中
  • 支持多个文件、多数据加载
  • 支持从 OS ENV 变量数据加载配置
  • 支持从远程 URL 加载配置数据
  • 支持从命令行参数(flags)设置配置数据
  • 支持数据覆盖合并，加载多份数据时将按key自动合并
  • 支持通过 . 分隔符来按路径获取子级值。 e.g map.key arr.2
  • 支持解析ENV变量名称。 like shell: ${SHELL} -> shell: /bin/zsh
  • 简洁的使用API Get Int Uint Int64 String Bool Ints IntMap Strings StringMap ...
  • 完善的单元测试(code coverage > 95%)

提供一个子包 dotenv，支持从文件（eg .env）中导入数据到ENV

快速使用

这里使用yaml格式作为示例(testdata/yml_other.yml):

name: app2
debug: false
baseKey: value2
shell: ${SHELL}
envKey1: ${NotExist|defValue}

map1:
    key: val2
    key2: val20

arr1:
    - val1
    - val21
载入数据

示例代码请看 _examples/yaml.go:

package main

import (
    "github.com/abulo/ratel/v2/config"
    "github.com/abulo/ratel/v2/config/yaml"
)

// go run ./examples/yaml.go
func main() {
	// 设置选项支持 ENV 解析
	config.WithOptions(config.ParseEnv)

	// 添加驱动程序以支持yaml内容解析（除了JSON是默认支持，其他的则是按需使用）
	config.AddDriver(yaml.Driver)

	// 加载配置，可以同时传入多个文件
	err := config.LoadFiles("testdata/yml_base.yml")
	if err != nil {
		panic(err)
	}

	// fmt.Printf("config data: \n %#v\n", config.Data())

	// 加载更多文件
	err = config.LoadFiles("testdata/yml_other.yml")
	// can also load multi at once
	// err := config.LoadFiles("testdata/yml_base.yml", "testdata/yml_other.yml")
	if err != nil {
		panic(err)
	}
}
获取数据
// 获取整型
age := config.Int("age")
fmt.Print(age) // 100

// 获取布尔值
val := config.Bool("debug")
fmt.Print(val) // true

// 获取字符串
name := config.String("name")
fmt.Print(name) // inhere

// 获取字符串数组
arr1 := config.Strings("arr1")
fmt.Printf("%v %#v", arr1) // []string{"val1", "val21"}

// 获取字符串KV映射
val := config.StringMap("map1")
fmt.Printf("%v %#v",val) // map[string]string{"key":"val2", "key2":"val20"}

// 值包含ENV变量
value := config.String("shell")
fmt.Print(value) // /bin/zsh

// 通过key路径获取值
// from array
value := config.String("arr1.0")
fmt.Print(value) // "val1"

// from map
value := config.String("map1.key")
fmt.Print(value) // "val2"
设置新的值
// set value
config.Set("name", "new name")
// get
name = config.String("name")
fmt.Print(name) // new name

API方法参考

载入配置
  • LoadOSEnv(keys []string) Load from os ENV
  • LoadData(dataSource ...interface{}) (err error) Load from struts or maps
  • LoadFlags(keys []string) (err error) Load from CLI flags
  • LoadExists(sourceFiles ...string) (err error)
  • LoadFiles(sourceFiles ...string) (err error)
  • LoadRemote(format, url string) (err error)
  • LoadSources(format string, src []byte, more ...[]byte) (err error)
  • LoadStrings(format string, str string, more ...string) (err error)
获取值
  • Bool(key string, defVal ...bool) bool
  • Int(key string, defVal ...int) int
  • Uint(key string, defVal ...uint) uint
  • Int64(key string, defVal ...int64) int64
  • Ints(key string) (arr []int)
  • IntMap(key string) (mp map[string]int)
  • Float(key string, defVal ...float64) float64
  • String(key string, defVal ...string) string
  • Strings(key string) (arr []string)
  • StringMap(key string) (mp map[string]string)
  • Get(key string, findByPath ...bool) (value interface{})
设置值
  • Set(key string, val interface{}, setByPath ...bool) (err error)
有用的方法
  • Getenv(name string, defVal ...string) (val string)
  • AddDriver(driver Driver)
  • Data() map[string]interface{}
  • Exists(key string, findByPath ...bool) bool
  • DumpTo(out io.Writer, format string) (n int64, err error)

Documentation

Index

Constants

View Source 
const (
	Ini  = "ini"
	Hcl  = "hcl"
	Yml  = "yml"
	JSON = "json"
	Yaml = "yaml"
	Toml = "toml"
)

There are supported config format

Variables

View Source 
var EnvValueGetter = func(name string) string {
	return os.Getenv(name)
}

EnvValueGetter Env value provider. TIPS: you can custom provide data.

View Source 
var JSONAllowComments = true

JSONAllowComments support write comments on json file.

View Source 
var JSONDriver = &jsonDriver{name: JSON}

JSONDriver instance fot json

Functions

func AddDriver 

func AddDriver(driver Driver)

AddDriver set a decoder and encoder driver for a format.

func BindStruct 

func BindStruct(key string, dst interface{}) error

BindStruct alias method of the 'Structure'

func Bool 

func Bool(key string, defVal ...bool) bool

Bool get a bool value, if not found return default value

func ClearAll 

func ClearAll()

ClearAll data and caches

func Data 

func Data() map[string]interface{}

Data return all config data

func Delimiter 

func Delimiter(sep byte) func(*Options)

Delimiter set delimiter char

func DumpTo 

func DumpTo(out io.Writer, format string) (int64, error)

DumpTo a writer and use format

func EnableCache 

func EnableCache(opts *Options)

EnableCache set readonly

func Exists 

func Exists(key string, findByPath ...bool) bool

Exists key exists check

func Float 

func Float(key string, defVal ...float64) float64

Float get a float64 value, if not found return default value

func Get 

func Get(key string, findByPath ...bool) interface{}

Get config value by key string, support get sub-value by key path(eg. 'map.key'), ok is true, find value from config ok is false, not found or error

func GetEnv 

func GetEnv(name string, defVal ...string) (val string)

GetEnv get os ENV value by name Deprecated 

please use Getenv() instead

func GetValue 

func GetValue(key string, findByPath ...bool) (interface{}, bool)

GetValue get value by given key string.

func Getenv 

func Getenv(name string, defVal ...string) (val string)

Getenv get os ENV value by name. like os.Getenv, but support default value Notice: - Key is not case sensitive when getting

func Int 

func Int(key string, defVal ...int) int

Int get a int by key

func Int64 

func Int64(key string, defVal ...int64) int64

Int64 get a int value, if not found return default value

func IntMap 

func IntMap(key string) map[string]int

IntMap get config data as a map[string]int

func Ints 

func Ints(key string) []int

Ints get config data as a int slice/array

func LoadData 

func LoadData(dataSource ...interface{}) error

LoadData load one or multi data

func LoadDir 

func LoadDir(dir, suffix string) error

func LoadExists 

func LoadExists(sourceFiles ...string) error

LoadExists load one or multi files, will ignore not exist

func LoadExistsByFormat 

func LoadExistsByFormat(format string, sourceFiles ...string) error

LoadExistsByFormat load one or multi files by give format

func LoadFiles 

func LoadFiles(sourceFiles ...string) error

LoadFiles load one or multi files

func LoadFilesByFormat 

func LoadFilesByFormat(format string, sourceFiles ...string) error

LoadFilesByFormat load one or multi files by give format

func LoadFlags 

func LoadFlags(keys []string) error

LoadFlags load data from cli flags

func LoadOSEnv 

func LoadOSEnv(keys []string, keyToLower bool)

LoadOSEnv load data from OS ENV

func LoadRemote 

func LoadRemote(format, url string) error

LoadRemote load config data from remote URL.

func LoadSources 

func LoadSources(format string, src []byte, more ...[]byte) error

LoadSources load one or multi byte data

func LoadStrings 

func LoadStrings(format string, str string, more ...string) error

LoadStrings load one or multi string

func MapStruct 

func MapStruct(key string, dst interface{}) error

MapStruct alias method of the 'Structure' Usage: 

dbInfo := &Db{}
config.MapStruct("db", dbInfo)

func OnConfigChange added in v2.5.2 

func OnConfigChange(run func(in fsnotify.Event))

func ParseEnv 

func ParseEnv(opts *Options)

ParseEnv set parse env

func ParseEnvValue 

func ParseEnvValue(val string) (newVal string)

ParseEnvValue parse ENV var value from input string

func ParseEnvVarStringHookFunc 

func ParseEnvVarStringHookFunc() mapstructure.DecodeHookFunc

ParseEnvVarStringHookFunc returns a DecodeHookFunc that parse ENV var

func Readonly 

func Readonly(opts *Options)

Readonly set readonly

func Set 

func Set(key string, val interface{}, setByPath ...bool) error

Set val by key

func SetData 

func SetData(data map[string]interface{})

SetData for override the Config.Data

func SetDecoder 

func SetDecoder(format string, decoder Decoder)

SetDecoder add/set a format decoder Deprecated please use driver instead

func SetEncoder 

func SetEncoder(format string, encoder Encoder)

SetEncoder set a encoder for the format Deprecated please use driver instead

func String 

func String(key string, defVal ...string) string

String get a string by key

func StringMap 

func StringMap(key string) map[string]string

StringMap get config data as a map[string]string

func Strings 

func Strings(key string) []string

Strings get strings by key

func StripComments 

func StripComments(src string) string

StripComments strip comments for a JSON string

func Uint 

func Uint(key string, defVal ...uint) uint

Uint get a uint value, if not found return default value

func WatchConfig added in v2.5.2 

func WatchConfig(suffix string)

func WithOptions 

func WithOptions(opts ...func(*Options))

WithOptions with options

func WriteTo 

func WriteTo(out io.Writer) (int64, error)

WriteTo a writer

Types

type Config 

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

Config structure definition

func Default 

func Default() *Config

Default get the default instance

func New 

func New(name string) *Config

New config instance

func NewEmpty 

func NewEmpty(name string) *Config

NewEmpty config instance

func NewWith 

func NewWith(name string, fn func(c *Config)) *Config

NewWith create config instance, and you can call some init func

func NewWithOptions 

func NewWithOptions(name string, opts ...func(*Options)) *Config

NewWithOptions config instance

func (*Config) AddDriver 

func (c *Config) AddDriver(driver Driver)

AddDriver set a decoder and encoder driver for a format.

func (*Config) BindStruct 

func (c *Config) BindStruct(key string, dst interface{}) error

BindStruct alias method of the 'Structure'

func (*Config) Bool 

func (c *Config) Bool(key string, defVal ...bool) (value bool)

Bool looks up a value for a key in this section and attempts to parse that value as a boolean, along with a boolean result similar to a map lookup. of following(case insensitive):

  • true
  • yes
  • false
  • no
  • 1
  • 0

The `ok` boolean will be false in the event that the value could not be parsed as a bool

func (*Config) ClearAll 

func (c *Config) ClearAll()

ClearAll data and caches

func (*Config) ClearCaches 

func (c *Config) ClearCaches()

ClearCaches clear caches

func (*Config) ClearData 

func (c *Config) ClearData()

ClearData clear data

func (*Config) ConfigDir added in v2.6.1 

func (c *Config) ConfigDir() []string

func (*Config) Data 

func (c *Config) Data() map[string]interface{}

Data get all config data

func (*Config) DelDriver 

func (c *Config) DelDriver(format string)

DelDriver delete driver of the format

func (*Config) DumpTo 

func (c *Config) DumpTo(out io.Writer, format string) (n int64, err error)

DumpTo use the format(json,yaml,toml) dump config data to a writer

func (*Config) Error 

func (c *Config) Error() error

Error get last error

func (*Config) Exists 

func (c *Config) Exists(key string, findByPath ...bool) (ok bool)

Exists key exists check

func (*Config) Float 

func (c *Config) Float(key string, defVal ...float64) (value float64)

Float get a float64 by key

func (*Config) Get 

func (c *Config) Get(key string, findByPath ...bool) interface{}

Get config value by key

func (*Config) GetValue 

func (c *Config) GetValue(key string, findByPath ...bool) (value interface{}, ok bool)

GetValue get value by given key string.

func (*Config) HasDecoder 

func (c *Config) HasDecoder(format string) bool

HasDecoder has decoder

func (*Config) HasEncoder 

func (c *Config) HasEncoder(format string) bool

HasEncoder has encoder

func (*Config) Int 

func (c *Config) Int(key string, defVal ...int) (value int)

Int get a int value, if not found return default value

func (*Config) Int64 

func (c *Config) Int64(key string, defVal ...int64) (value int64)

Int64 get a int value, if not found return default value

func (*Config) IntMap 

func (c *Config) IntMap(key string) (mp map[string]int)

IntMap get config data as a map[string]int

func (*Config) Ints 

func (c *Config) Ints(key string) (arr []int)

Ints get config data as a int slice/array

func (*Config) IsEmpty 

func (c *Config) IsEmpty() bool

IsEmpty of the config

func (*Config) LoadData 

func (c *Config) LoadData(dataSources ...interface{}) (err error)

LoadData load data from map OR struct The dataSources can be:

  • map[string]interface{}

func (*Config) LoadDir 

func (c *Config) LoadDir(dir, suffix string) (err error)

loadDir

func (*Config) LoadExists 

func (c *Config) LoadExists(sourceFiles ...string) (err error)

LoadExists load and parse config files, but will ignore not exists file.

func (*Config) LoadExistsByFormat 

func (c *Config) LoadExistsByFormat(format string, sourceFiles ...string) (err error)

LoadExistsByFormat load one or multi files by give format

func (*Config) LoadFiles 

func (c *Config) LoadFiles(sourceFiles ...string) (err error)

LoadFiles load and parse config files

func (*Config) LoadFilesByFormat 

func (c *Config) LoadFilesByFormat(format string, sourceFiles ...string) (err error)

LoadFilesByFormat load one or multi files by give format

func (*Config) LoadFlags 

func (c *Config) LoadFlags(keys []string) (err error)

LoadFlags parse command line arguments, based on provide keys. Usage: 

// debug flag is bool type
c.LoadFlags([]string{"env", "debug:bool"})

func (*Config) LoadOSEnv 

func (c *Config) LoadOSEnv(keys []string, keyToLower bool)

LoadOSEnv load data from os ENV

func (*Config) LoadRemote 

func (c *Config) LoadRemote(format, url string) (err error)

LoadRemote load config data from remote URL. Usage: 

c.LoadRemote(config.JSON, "http://abc.com/api-config.json")

func (*Config) LoadSources 

func (c *Config) LoadSources(format string, src []byte, more ...[]byte) (err error)

LoadSources load data from byte content. Usage: 

config.LoadSources(config.Yml, []byte(`
name: blog
arr:
	key: val

`))

func (*Config) LoadStrings 

func (c *Config) LoadStrings(format string, str string, more ...string) (err error)

LoadStrings load data from source string content.

func (*Config) LoadedFiles 

func (c *Config) LoadedFiles() []string

LoadedFiles get loaded files name

func (*Config) MapStruct 

func (c *Config) MapStruct(key string, dst interface{}) error

MapStruct alias method of the 'Structure'

func (*Config) Name 

func (c *Config) Name() string

Name get config name

func (*Config) OnConfigChange added in v2.6.1 

func (v *Config) OnConfigChange(run func(in fsnotify.Event))

func (*Config) Options 

func (c *Config) Options() *Options

Options get

func (*Config) Readonly 

func (c *Config) Readonly()

Readonly disable set data to config. Usage: 

config.LoadFiles(a, b, c)
config.Readonly()

func (*Config) Set 

func (c *Config) Set(key string, val interface{}, setByPath ...bool) (err error)

Set a value by key string.

func (*Config) SetData 

func (c *Config) SetData(data map[string]interface{})

SetData for override the Config.Data

func (*Config) SetDecoder 

func (c *Config) SetDecoder(format string, decoder Decoder)

SetDecoder set decoder Deprecated please use driver instead

func (*Config) SetDecoders 

func (c *Config) SetDecoders(decoders map[string]Decoder)

SetDecoders set decoders Deprecated please use driver instead

func (*Config) SetEncoder 

func (c *Config) SetEncoder(format string, encoder Encoder)

SetEncoder set a encoder for the format Deprecated please use driver instead

func (*Config) SetEncoders 

func (c *Config) SetEncoders(encoders map[string]Encoder)

SetEncoders set encoders Deprecated please use driver instead

func (*Config) String 

func (c *Config) String(key string, defVal ...string) string

String get a string by key, if not found return default value

func (*Config) StringMap 

func (c *Config) StringMap(key string) (mp map[string]string)

StringMap get config data as a map[string]string

func (*Config) Strings 

func (c *Config) Strings(key string) (arr []string)

Strings get config data as a string slice/array

func (*Config) Structure 

func (c *Config) Structure(key string, dst interface{}) error

Structure get config data and binding to the dst structure. Usage: 

dbInfo := Db{}
config.Structure("db", &dbInfo)

func (*Config) ToJSON 

func (c *Config) ToJSON() string

ToJSON string

func (*Config) Uint 

func (c *Config) Uint(key string, defVal ...uint) (value uint)

Uint get a int value, if not found return default value

func (*Config) WatchConfig added in v2.6.1 

func (c *Config) WatchConfig(suffix string)

loadDir

func (*Config) With 

func (c *Config) With(fn func(c *Config)) *Config

With apply some options

func (*Config) WithOptions 

func (c *Config) WithOptions(opts ...func(*Options)) *Config

WithOptions apply some options

func (*Config) WriteTo 

func (c *Config) WriteTo(out io.Writer) (n int64, err error)

WriteTo Write out config data representing the current state to a writer.

type Decoder 

type Decoder func(blob []byte, v interface{}) (err error)

Decoder for decode yml,json,toml format content 

var JSONDecoder Decoder = func(data []byte, v interface{}) (err error) {
	if JSONAllowComments {
		str := StripComments(string(data))
		return json.Unmarshal([]byte(str), v)
	}

	return json.Unmarshal(data, v)
}

JSONDecoder for json decode

type Driver 

type Driver interface {
	Name() string
	GetDecoder() Decoder
	GetEncoder() Encoder
}

Driver interface

type Encoder 

type Encoder func(v interface{}) (out []byte, err error)

Encoder for decode yml,json,toml format content 

var JSONEncoder Encoder = json.Marshal

JSONEncoder for json encode

type Options 

type Options struct {
	// parse env value. like: "${EnvName}" "${EnvName|default}"
	ParseEnv bool
	// config is readonly
	Readonly bool
	// enable config data cache
	EnableCache bool
	// parse key, allow find value by key path. eg: 'key.sub' will find `map[key]sub`
	ParseKey bool
	// tag name for binding data to struct
	// Deprecated
	// please set tag name by DecoderConfig
	TagName string
	// the delimiter char for split key path, if `FindByPath=true`. default is '.'
	Delimiter byte
	// default write format
	DumpFormat string
	// default input format
	ReadFormat string
	// DecoderConfig setting for binding data to struct
	DecoderConfig *mapstructure.DecoderConfig
}

Options config options

func GetOptions 

func GetOptions() *Options

GetOptions get options

Source Files

View all Source files

Directories

Path Synopsis
Package dotnev provide load .env data to os ENV
 Package dotnev provide load .env data to os ENV
Package json5 use the https://github.com/yosuke-furukawa/json5 for parse json5
 Package json5 use the https://github.com/yosuke-furukawa/json5 for parse json5
parser
ini
ini/dotnev
ini/parser
Package toml is driver use TOML format content as config source Usage please see example:
 Package toml is driver use TOML format content as config source Usage please see example:
Package yaml is a driver use YAML format content as config source Usage please see example:
 Package yaml is a driver use YAML format content as config source Usage please see example:

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.